Re: [PATCH 4/6] zsmalloc: add/fix function comment

[Nitin Gupta]

On 04/25/2012 02:23 AM, Minchan Kim wrote:

> Add/fix the comment.
> 
> Signed-off-by: Minchan Kim <minchan@xxxxxxxxxx>
> ---
>  drivers/staging/zsmalloc/zsmalloc-main.c |   15 +++++++++++----
>  1 file changed, 11 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/staging/zsmalloc/zsmalloc-main.c b/drivers/staging/zsmalloc/zsmalloc-main.c
> index 0fe4cbb..b7d31cc 100644
> --- a/drivers/staging/zsmalloc/zsmalloc-main.c
> +++ b/drivers/staging/zsmalloc/zsmalloc-main.c
> @@ -565,12 +565,9 @@ EXPORT_SYMBOL_GPL(zs_destroy_pool);
>   * zs_malloc - Allocate block of given size from pool.
>   * @pool: pool to allocate from
>   * @size: size of block to allocate
> - * @page: page no. that holds the object
> - * @offset: location of object within page
>   *
>   * On success, <page, offset> identifies block allocated
> - * and 0 is returned. On failure, <page, offset> is set to
> - * 0 and -ENOMEM is returned.
> + * and <page, offset> is returned. On failure, NULL is returned.
>   *


The returned value indeed encodes <page, offset> values as a 'void *'
but this should not be part of the function documentation since its an
internal detail.  So, its probably better to say:

On success, handle to the allocated object is returned; NULL otherwise.

On a side note, we should also 'typedef void * zs_handle' to avoid any
confusion. Without this, users may just treat zs_malloc return value as
a pointer and try to deference it.

>   * Allocation requests with size > ZS_MAX_ALLOC_SIZE will fail.
>   */
> @@ -666,6 +663,16 @@ void zs_free(struct zs_pool *pool, void *obj)
>  }
>  EXPORT_SYMBOL_GPL(zs_free);
>  
> +/**
> + * zs_map_object - get address of allocated object from handle.
> + * @pool: object allocated pool


should be: @pool: pool from which the object was allocated

> + * @handle: handle returned from zs_malloc
> + *

> + * Before using object allocated from zs_malloc, object
> + * should be mapped to page table by this function.
> + * After using object,  call zs_unmap_object to unmap page
> + * table.
> + */


We are not really unmapping any page tables, so could be written as:

Before using an object allocated from zs_malloc, it must be mapped using
this function. When done with the object, it must be unmapped using
zs_unmap_object


Sorry for nitpicking.

Thanks,
Nitin
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/