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

[Minchan Kim <minchan@kernel.org>]

On 04/25/2012 10:27 PM, Nitin Gupta wrote:

> On 04/25/2012 02:23 AM, Minchan Kim wrote:
> 
>> Add/fix the comment.
>>
>> Signed-off-by: Minchan Kim <minchan@kernel.org>
>> ---
>>  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.


Fair enough.

> 
> 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.


Yes. We should do it. I will make it as another patch in next spin.

> 
>>   * 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.


Never nitpicking.
Confusing documentation makes people very hang so documentation is very important.

Nitin, Thanks!

> 
> Thanks,
> Nitin
> 
> --
> To unsubscribe, send a message with 'unsubscribe linux-mm' in
> the body to majordomo@kvack.org.  For more info on Linux MM,
> see: http://www.linux-mm.org/ .
> Fight unfair telecom internet charges in Canada: sign http://stopthemeter.ca/
> Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>
> 



-- 
Kind regards,
Minchan Kim

--
To unsubscribe, send a message with 'unsubscribe linux-mm' in
the body to majordomo@kvack.org.  For more info on Linux MM,
see: http://www.linux-mm.org/ .
Fight unfair telecom internet charges in Canada: sign http://stopthemeter.ca/
Don't email: <a href=mailto:"dont@kvack.org"> email@kvack.org </a>