[Skiboot] [PATCH 1/2] flash: Add documentation for blocklevel_smart_write()

[Cyril Bur]

On Wed, 27 Jul 2016 12:19:13 +1000
Michael Neuling <mikey at neuling.org> wrote:

> A function called "smart" doesn't give the user any clues as to why
> they would want to use it over a another calls.
> 
> This adds some documentation so users can determine when to best use
> this call.
> 

Thanks Mikey

Reviewed-by: Cyril Bur <cyrilbur at gmail.com>

> Signed-off-by: Michael Neuling <mikey at neuling.org>
> ---
>  libflash/blocklevel.h | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)
> 
> diff --git a/libflash/blocklevel.h b/libflash/blocklevel.h
> index 9f4285e..9770e11 100644
> --- a/libflash/blocklevel.h
> +++ b/libflash/blocklevel.h
> @@ -64,7 +64,14 @@ int blocklevel_erase(struct blocklevel_device *bl, uint32_t pos, uint32_t len);
>  int blocklevel_get_info(struct blocklevel_device *bl, const char **name, uint32_t *total_size,
>  		uint32_t *erase_granule);
>  
> -/* Convienience functions */
> +/*
> + * blocklevel_smart_write() performs reads on the data to see if it
> + * can skip erase or write calls. This is likely more conveient for
> + * the caller since they don't need to perform these checks
> + * themselves. Depending on the new and old data, this may be faster
> + * or slower than the just using blocklevel_erase/write calls.
> + * directly.
> + */
>  int blocklevel_smart_write(struct blocklevel_device *bl, uint32_t pos, const void *buf, uint32_t len);
>  
>  /* Implemented in software at this level */