summaryrefslogtreecommitdiff
path: root/include/dfu.h
blob: dcb9cd9d799a2d5d5ebb72016434ce283ff5bf34 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
/* SPDX-License-Identifier: GPL-2.0+ */
/*
 * dfu.h - DFU flashable area description
 *
 * Copyright (C) 2012 Samsung Electronics
 * authors: Andrzej Pietrasiewicz <andrzej.p@samsung.com>
 *	    Lukasz Majewski <l.majewski@samsung.com>
 */

#ifndef __DFU_ENTITY_H_
#define __DFU_ENTITY_H_

#include <common.h>
#include <linux/list.h>
#include <mmc.h>
#include <spi_flash.h>
#include <linux/usb/composite.h>

enum dfu_device_type {
	DFU_DEV_MMC = 1,
	DFU_DEV_ONENAND,
	DFU_DEV_NAND,
	DFU_DEV_RAM,
	DFU_DEV_SF,
	DFU_DEV_MTD,
	DFU_DEV_VIRT,
};

enum dfu_layout {
	DFU_RAW_ADDR = 1,
	DFU_FS_FAT,
	DFU_FS_EXT2,
	DFU_FS_EXT3,
	DFU_FS_EXT4,
	DFU_RAM_ADDR,
	DFU_SKIP,
	DFU_SCRIPT,
};

enum dfu_op {
	DFU_OP_READ = 1,
	DFU_OP_WRITE,
	DFU_OP_SIZE,
};

struct mmc_internal_data {
	int dev_num;

	/* RAW programming */
	unsigned int lba_start;
	unsigned int lba_size;
	unsigned int lba_blk_size;

	/* eMMC HW partition access */
	int hw_partition;

	/* FAT/EXT */
	unsigned int dev;
	unsigned int part;
};

struct mtd_internal_data {
	struct mtd_info *info;

	/* RAW programming */
	u64 start;
	u64 size;
	/* for ubi partition */
	unsigned int ubi;
};

struct nand_internal_data {
	/* RAW programming */
	u64 start;
	u64 size;

	unsigned int dev;
	unsigned int part;
	/* for nand/ubi use */
	unsigned int ubi;
};

struct ram_internal_data {
	unsigned long	start;
	unsigned int	size;
};

struct sf_internal_data {
	struct spi_flash *dev;

	/* RAW programming */
	u64 start;
	u64 size;
	/* for sf/ubi use */
	unsigned int ubi;
};

struct virt_internal_data {
	int dev_num;
};

#define DFU_NAME_SIZE			32
#ifndef DFU_DEFAULT_POLL_TIMEOUT
#define DFU_DEFAULT_POLL_TIMEOUT 0
#endif
#ifndef DFU_MANIFEST_POLL_TIMEOUT
#define DFU_MANIFEST_POLL_TIMEOUT	DFU_DEFAULT_POLL_TIMEOUT
#endif

struct dfu_entity {
	char			name[DFU_NAME_SIZE];
	int                     alt;
	void                    *dev_private;
	enum dfu_device_type    dev_type;
	enum dfu_layout         layout;
	unsigned long           max_buf_size;

	union {
		struct mmc_internal_data mmc;
		struct mtd_internal_data mtd;
		struct nand_internal_data nand;
		struct ram_internal_data ram;
		struct sf_internal_data sf;
		struct virt_internal_data virt;
	} data;

	int (*get_medium_size)(struct dfu_entity *dfu, u64 *size);

	int (*read_medium)(struct dfu_entity *dfu,
			u64 offset, void *buf, long *len);

	int (*write_medium)(struct dfu_entity *dfu,
			u64 offset, void *buf, long *len);

	int (*flush_medium)(struct dfu_entity *dfu);
	unsigned int (*poll_timeout)(struct dfu_entity *dfu);

	void (*free_entity)(struct dfu_entity *dfu);

	struct list_head list;

	/* on the fly state */
	u32 crc;
	u64 offset;
	int i_blk_seq_num;
	u8 *i_buf;
	u8 *i_buf_start;
	u8 *i_buf_end;
	u64 r_left;
	long b_left;

	u32 bad_skip;	/* for nand use */

	unsigned int inited:1;
};

struct list_head;
extern struct list_head dfu_list;

#ifdef CONFIG_SET_DFU_ALT_INFO
/**
 * set_dfu_alt_info() - set dfu_alt_info environment variable
 *
 * If CONFIG_SET_DFU_ALT_INFO=y, this board specific function is called to set
 * environment variable dfu_alt_info.
 *
 * @interface:	dfu interface, e.g. "mmc" or "nand"
 * @devstr:	device number as string
 */
void set_dfu_alt_info(char *interface, char *devstr);
#endif

/**
 * dfu_alt_init() - initialize buffer for dfu entities
 *
 * @num:	number of entities
 * @dfu:	on return allocated buffer
 * Return:	0 on success
 */
int dfu_alt_init(int num, struct dfu_entity **dfu);

/**
 * dfu_alt_add() - add alternate to dfu entity buffer
 *
 * @dfu:	dfu entity
 * @interface:	dfu interface, e.g. "mmc" or "nand"
 * @devstr:	device number as string
 * @s:		string description of alternate
 * Return:	0 on success
 */
int dfu_alt_add(struct dfu_entity *dfu, char *interface, char *devstr, char *s);

/**
 * dfu_config_entities() - initialize dfu entitities from envirionment
 *
 * Initialize the list of dfu entities from environment variable dfu_alt_info.
 * The list must be freed by calling dfu_free_entities(). This function bypasses
 * set_dfu_alt_info(). So typically you should use dfu_init_env_entities()
 * instead.
 *
 * See function :c:func:`dfu_free_entities`
 * See function :c:func:`dfu_init_env_entities`
 *
 * @s:		string with alternates
 * @interface:	interface, e.g. "mmc" or "nand"
 * @devstr:	device number as string
 * Return:	0 on success, a negative error code otherwise
 */
int dfu_config_entities(char *s, char *interface, char *devstr);

/**
 * dfu_free_entities() - free the list of dfu entities
 *
 * Free the internal list of dfu entities.
 *
 * See function :c:func:`dfu_init_env_entities`
 */
void dfu_free_entities(void);

/**
 * dfu_show_entities() - print DFU alt settings list
 */
void dfu_show_entities(void);

/**
 * dfu_get_alt_number() - get number of alternates
 *
 * Return: number of alternates in the dfu entities list
 */
int dfu_get_alt_number(void);

/**
 * dfu_get_dev_type() - get string representation for dfu device type
 *
 * @type:	device type
 * Return:	string representation for device type
 */
const char *dfu_get_dev_type(enum dfu_device_type type);

/**
 * dfu_get_layout() - get string describing layout
 *
 * Internally layouts are represented by enum dfu_device_type values. This
 * function translates an enum value to a human readable string, e.g. DFU_FS_FAT
 * is translated to "FAT".
 *
 * @layout:	layout
 * Result:	string representation for the layout
 */
const char *dfu_get_layout(enum dfu_layout layout);

/**
 * dfu_get_entity() - get dfu entity for an alternate id
 *
 * @alt:	alternate id
 * Return:	dfu entity
 */
struct dfu_entity *dfu_get_entity(int alt);

char *dfu_extract_token(char** e, int *n);

/**
 * dfu_get_alt() - get alternate id for filename
 *
 * Environment variable dfu_alt_info defines the write destinations (alternates)
 * for different filenames. This function get the index of the alternate for
 * a filename. If an absolute filename is provided (starting with '/'), the
 * directory path is ignored.
 *
 * @name:	filename
 * Return:	id of the alternate or negative error number (-ENODEV)
 */
int dfu_get_alt(char *name);

/**
 * dfu_init_env_entities() - initialize dfu entitities from envirionment
 *
 * Initialize the list of dfu entities from environment variable dfu_alt_info.
 * The list must be freed by calling dfu_free_entities().
 * @interface and @devstr are used to select the relevant set of alternates
 * from environment variable dfu_alt_info.
 *
 * If environment variable dfu_alt_info specifies the interface and the device,
 * use NULL for @interface and @devstr.
 *
 * See function :c:func:`dfu_free_entities`
 *
 * @interface:	interface, e.g. "mmc" or "nand"
 * @devstr:	device number as string
 * Return:	0 on success, a negative error code otherwise
 */
int dfu_init_env_entities(char *interface, char *devstr);

unsigned char *dfu_get_buf(struct dfu_entity *dfu);
unsigned char *dfu_free_buf(void);
unsigned long dfu_get_buf_size(void);
bool dfu_usb_get_reset(void);

#ifdef CONFIG_DFU_TIMEOUT
unsigned long dfu_get_timeout(void);
void dfu_set_timeout(unsigned long);
#endif

/**
 * dfu_read() - read from dfu entity
 *
 * The block sequence number @blk_seq_num is a 16 bit counter that must be
 * incremented with each call for the same dfu entity @de.
 *
 * @de:			dfu entity
 * @buf:		buffer
 * @size:		size of buffer
 * @blk_seq_num:	block sequence number
 * Return:		0 for success, -1 for error
 */
int dfu_read(struct dfu_entity *de, void *buf, int size, int blk_seq_num);

/**
 * dfu_write() - write to dfu entity
 *
 * Write the contents of a buffer @buf to the dfu entity @de. After writing
 * the last block call dfu_flush(). If a file is already loaded completely
 * into memory it is preferable to use dfu_write_from_mem_addr() which takes
 * care of blockwise transfer and flushing.
 *
 * The block sequence number @blk_seq_num is a 16 bit counter that must be
 * incremented with each call for the same dfu entity @de.
 *
 * See function :c:func:`dfu_flush`
 * See function :c:func:`dfu_write_from_mem_addr`
 *
 * @de:			dfu entity
 * @buf:		buffer
 * @size:		size of buffer
 * @blk_seq_num:	block sequence number
 * Return:		0 for success, -1 for error
 */
int dfu_write(struct dfu_entity *de, void *buf, int size, int blk_seq_num);

/**
 * dfu_flush() - flush to dfu entity
 *
 * This function has to be called after writing the last block to the dfu
 * entity @de.
 *
 * The block sequence number @blk_seq_num is a 16 bit counter that must be
 * incremented with each call for the same dfu entity @de.
 *
 * See function :c:func:`dfu_write`
 *
 * @de:			dfu entity
 * @buf:		ignored
 * @size:		ignored
 * @blk_seq_num:	block sequence number of last write - ignored
 * Return:		0 for success, -1 for error
 */
int dfu_flush(struct dfu_entity *de, void *buf, int size, int blk_seq_num);

/**
 * dfu_initiated_callback() - weak callback called on DFU transaction start
 *
 * It is a callback function called by DFU stack when a DFU transaction is
 * initiated. This function allows to manage some board specific behavior on
 * DFU targets.
 *
 * @dfu:	pointer to the dfu_entity, which should be initialized
 */
void dfu_initiated_callback(struct dfu_entity *dfu);

/**
 * dfu_flush_callback() - weak callback called at the end of the DFU write
 *
 * It is a callback function called by DFU stack after DFU manifestation.
 * This function allows to manage some board specific behavior on DFU targets
 *
 * @dfu:	pointer to the dfu_entity, which should be flushed
 */
void dfu_flush_callback(struct dfu_entity *dfu);

/**
 * dfu_error_callback() - weak callback called at the DFU write error
 *
 * It is a callback function called by DFU stack after DFU write error.
 * This function allows to manage some board specific behavior on DFU targets
 *
 * @dfu:	pointer to the dfu_entity which cause the error
 * @msg:	the message of the error
 */
void dfu_error_callback(struct dfu_entity *dfu, const char *msg);

int dfu_transaction_initiate(struct dfu_entity *dfu, bool read);
void dfu_transaction_cleanup(struct dfu_entity *dfu);

/*
 * dfu_defer_flush - pointer to store dfu_entity for deferred flashing.
 *		     It should be NULL when not used.
 */
extern struct dfu_entity *dfu_defer_flush;

/**
 * dfu_get_defer_flush() - get current value of dfu_defer_flush pointer
 *
 * Return:	value of the dfu_defer_flush pointer
 */
static inline struct dfu_entity *dfu_get_defer_flush(void)
{
	return dfu_defer_flush;
}

/**
 * dfu_set_defer_flush() - set the dfu_defer_flush pointer
 *
 * @dfu:	pointer to the dfu_entity, which should be written
 */
static inline void dfu_set_defer_flush(struct dfu_entity *dfu)
{
	dfu_defer_flush = dfu;
}

/**
 * dfu_write_from_mem_addr() - write data from memory to DFU managed medium
 *
 * This function adds support for writing data starting from fixed memory
 * address (like $loadaddr) to dfu managed medium (e.g. NAND, MMC, file system)
 *
 * @dfu:	dfu entity to which we want to store data
 * @buf:	fixed memory address from where data starts
 * @size:	number of bytes to write
 *
 * Return:	0 on success, other value on failure
 */
int dfu_write_from_mem_addr(struct dfu_entity *dfu, void *buf, int size);

/* Device specific */
/* Each entity has 5 arguments in maximum. */
#define DFU_MAX_ENTITY_ARGS	5

#if CONFIG_IS_ENABLED(DFU_MMC)
extern int dfu_fill_entity_mmc(struct dfu_entity *dfu, char *devstr,
			       char **argv, int argc);
#else
static inline int dfu_fill_entity_mmc(struct dfu_entity *dfu, char *devstr,
				      char **argv, int argc)
{
	puts("MMC support not available!\n");
	return -1;
}
#endif

#if CONFIG_IS_ENABLED(DFU_NAND)
extern int dfu_fill_entity_nand(struct dfu_entity *dfu, char *devstr,
				char **argv, int argc);
#else
static inline int dfu_fill_entity_nand(struct dfu_entity *dfu, char *devstr,
				       char **argv, int argc)
{
	puts("NAND support not available!\n");
	return -1;
}
#endif

#if CONFIG_IS_ENABLED(DFU_RAM)
extern int dfu_fill_entity_ram(struct dfu_entity *dfu, char *devstr,
			       char **argv, int argc);
#else
static inline int dfu_fill_entity_ram(struct dfu_entity *dfu, char *devstr,
				      char **argv, int argc)
{
	puts("RAM support not available!\n");
	return -1;
}
#endif

#if CONFIG_IS_ENABLED(DFU_SF)
extern int dfu_fill_entity_sf(struct dfu_entity *dfu, char *devstr,
			      char **argv, int argc);
#else
static inline int dfu_fill_entity_sf(struct dfu_entity *dfu, char *devstr,
				     char **argv, int argc)
{
	puts("SF support not available!\n");
	return -1;
}
#endif

#if CONFIG_IS_ENABLED(DFU_MTD)
extern int dfu_fill_entity_mtd(struct dfu_entity *dfu, char *devstr,
			       char **argv, int argc);
#else
static inline int dfu_fill_entity_mtd(struct dfu_entity *dfu, char *devstr,
				      char **argv, int argc)
{
	puts("MTD support not available!\n");
	return -1;
}
#endif

#ifdef CONFIG_DFU_VIRT
int dfu_fill_entity_virt(struct dfu_entity *dfu, char *devstr,
			 char **argv, int argc);
int dfu_write_medium_virt(struct dfu_entity *dfu, u64 offset,
			  void *buf, long *len);
int dfu_get_medium_size_virt(struct dfu_entity *dfu, u64 *size);
int dfu_read_medium_virt(struct dfu_entity *dfu, u64 offset,
			 void *buf, long *len);
#else
static inline int dfu_fill_entity_virt(struct dfu_entity *dfu, char *devstr,
				       char **argv, int argc)
{
	puts("VIRT support not available!\n");
	return -1;
}
#endif

extern bool dfu_reinit_needed;

#if CONFIG_IS_ENABLED(DFU_WRITE_ALT)
/**
 * dfu_write_by_name() - write data to DFU medium
 * @dfu_entity_name:	Name of DFU entity to write
 * @addr:		Address of data buffer to write
 * @len:		Number of bytes
 * @interface:		Destination DFU medium (e.g. "mmc")
 * @devstring:		Instance number of destination DFU medium (e.g. "1")
 *
 * This function is storing data received on DFU supported medium which
 * is specified by @dfu_entity_name.
 *
 * Return:		0 - on success, error code - otherwise
 */
int dfu_write_by_name(char *dfu_entity_name, void *addr,
		      unsigned int len, char *interface, char *devstring);

/**
 * dfu_write_by_alt() - write data to DFU medium
 * @dfu_alt_num:	DFU alt setting number
 * @addr:		Address of data buffer to write
 * @len:		Number of bytes
 * @interface:		Destination DFU medium (e.g. "mmc")
 * @devstring:		Instance number of destination DFU medium (e.g. "1")
 *
 * This function is storing data received on DFU supported medium which
 * is specified by @dfu_alt_name.
 *
 * Return:		0 - on success, error code - otherwise
 */
int dfu_write_by_alt(int dfu_alt_num, void *addr, unsigned int len,
		     char *interface, char *devstring);
#else
static inline int dfu_write_by_name(char *dfu_entity_name, void *addr,
				    unsigned int len, char *interface,
				    char *devstring)
{
	puts("write support for DFU not available!\n");
	return -ENOSYS;
}

static inline int dfu_write_by_alt(int dfu_alt_num, void *addr,
				   unsigned int len, char *interface,
				   char *devstring)
{
	puts("write support for DFU not available!\n");
	return -ENOSYS;
}
#endif

int dfu_add(struct usb_configuration *c);
#endif /* __DFU_ENTITY_H_ */