On 04/10/2013 01:18:54 PM, Seth Jennings wrote:
> This patch adds a documentation file for zsmalloc at
> Documentation/vm/zsmalloc.txt

Docs acked-by: Rob Landley <rob@landley.net>

Literary criticism below:

> Signed-off-by: Seth Jennings <sjenning@linux.vnet.ibm.com>
> ---
>  Documentation/vm/zsmalloc.txt | 68  
> +++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 68 insertions(+)
>  create mode 100644 Documentation/vm/zsmalloc.txt
> 
> diff --git a/Documentation/vm/zsmalloc.txt  
> b/Documentation/vm/zsmalloc.txt
> new file mode 100644
> index 0000000..85aa617
> --- /dev/null
> +++ b/Documentation/vm/zsmalloc.txt
> @@ -0,0 +1,68 @@
> +zsmalloc Memory Allocator
> +
> +Overview
> +
> +zmalloc a new slab-based memory allocator,
> +zsmalloc, for storing compressed pages.

zmalloc a new slab-based memory allocator, zsmalloc? (How does one  
zmalloc zsmalloc?)

Out of curiosity, what does zsmalloc stand for, anyway?

>  It is designed for
> +low fragmentation and high allocation success rate on
> +large object, but <= PAGE_SIZE allocations.

1) objects

2) maybe "large objects for <= PAGE_SIZE"...

> +zsmalloc differs from the kernel slab allocator in two primary
> +ways to achieve these design goals.
> +
> +zsmalloc never requires high order page allocations to back
> +slabs, or "size classes" in zsmalloc terms. Instead it allows
> +multiple single-order pages to be stitched together into a
> +"zspage" which backs the slab.  This allows for higher allocation
> +success rate under memory pressure.
> +
> +Also, zsmalloc allows objects to span page boundaries within the
> +zspage.  This allows for lower fragmentation than could be had
> +with the kernel slab allocator for objects between PAGE_SIZE/2
> +and PAGE_SIZE.  With the kernel slab allocator, if a page compresses
> +to 60% of it original size, the memory savings gained through
> +compression is lost in fragmentation because another object of

I lean towards "are lost", but it's debatable. (Savings are plural, but  
savings could also be treated as a mass noun like water/air/bison that  
doesn't get pluralized because you can't count instances of a liquid.  
No idea which is more common.)

> +the same size can't be stored in the leftover space.
> +
> +This ability to span pages results in zsmalloc allocations not being
> +directly addressable by the user.  The user is given an
> +non-dereferencable handle in response to an allocation request.
> +That handle must be mapped, using zs_map_object(), which returns
> +a pointer to the mapped region that can be used.  The mapping is
> +necessary since the object data may reside in two different
> +noncontigious pages.

Presumably this allows packing of unmapped entities if you detect  
fragmentation and are up for a latency spike?

Rob