[1/1] doc: dfu: describe more DFU function

Add some of the missing DFU function descriptions.

Signed-off-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
---
 include/dfu.h | 178 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 174 insertions(+), 4 deletions(-)

--
2.26.2

On Sat, 23 May 2020 14:24:40 +0200
Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:

> Add some of the missing DFU function descriptions.
> 
> Signed-off-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
> ---
>  include/dfu.h | 178
> ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed,
> 174 insertions(+), 4 deletions(-)
> 
> diff --git a/include/dfu.h b/include/dfu.h
> index 938a4d1b81..065d8db824 100644
> --- a/include/dfu.h
> +++ b/include/dfu.h
> @@ -159,20 +159,139 @@ struct dfu_entity {
>  };
> 
>  #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);
> -const char *dfu_get_dev_type(enum dfu_device_type t);
> -const char *dfu_get_layout(enum dfu_layout l);
> +
> +/**
> + * 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);
> @@ -183,8 +302,59 @@ 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);
> 
>  /**
> @@ -195,9 +365,9 @@ int dfu_flush(struct dfu_entity *de, void *buf,
> int size, int blk_seq_num);
>   * 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 *
> @@ -205,7 +375,6 @@ void dfu_initiated_callback(struct dfu_entity
> *dfu);
>   * 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);
> 
> @@ -217,6 +386,7 @@ void dfu_transaction_cleanup(struct dfu_entity
> *dfu);
>   *		     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 *
> --
> 2.26.2
> 

Acked-by: Lukasz Majewski <lukma at denx.de>


Best regards,

Lukasz Majewski

--

DENX Software Engineering GmbH,      Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-59 Fax: (+49)-8142-66989-80 Email: lukma at denx.de
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 488 bytes
Desc: OpenPGP digital signature
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20200524/a1d2b29e/attachment.sig>

On Sat, May 23, 2020 at 02:24:40PM +0200, Heinrich Schuchardt wrote:

> Add some of the missing DFU function descriptions.
> 
> Signed-off-by: Heinrich Schuchardt <xypron.glpk at gmx.de>
> Acked-by: Lukasz Majewski <lukma at denx.de>

Applied to u-boot/master, thanks!