lkml.org 
[lkml]   [2018]   [Mar]   [6]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    SubjectRe: [PATCH 7/7] Documentation for Pmalloc
    From
    Date

    Minus the comment-fixes Mike Rapoport mentioned, looks good:

    Reviewed-by: Jay Freyensee <why2jjj.linux@gmail.com>


    On 2/28/18 12:06 PM, Igor Stoppa wrote:
    > Detailed documentation about the protectable memory allocator.
    >
    > Signed-off-by: Igor Stoppa <igor.stoppa@huawei.com>
    > ---
    > Documentation/core-api/index.rst | 1 +
    > Documentation/core-api/pmalloc.rst | 111 +++++++++++++++++++++++++++++++++++++
    > 2 files changed, 112 insertions(+)
    > create mode 100644 Documentation/core-api/pmalloc.rst
    >
    > diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
    > index c670a8031786..8f5de42d6571 100644
    > --- a/Documentation/core-api/index.rst
    > +++ b/Documentation/core-api/index.rst
    > @@ -25,6 +25,7 @@ Core utilities
    > genalloc
    > errseq
    > printk-formats
    > + pmalloc
    >
    > Interfaces for kernel debugging
    > ===============================
    > diff --git a/Documentation/core-api/pmalloc.rst b/Documentation/core-api/pmalloc.rst
    > new file mode 100644
    > index 000000000000..8fb9c9d3171b
    > --- /dev/null
    > +++ b/Documentation/core-api/pmalloc.rst
    > @@ -0,0 +1,111 @@
    > +.. SPDX-License-Identifier: GPL-2.0
    > +
    > +Protectable memory allocator
    > +============================
    > +
    > +Purpose
    > +-------
    > +
    > +The pmalloc library is meant to provide R/O status to data that, for some
    > +reason, could neither be declared as constant, nor could it take advantage
    > +of the qualifier __ro_after_init, but is write-once and read-only in spirit.
    > +It protects data from both accidental and malicious overwrites.
    > +
    > +Example: A policy that is loaded from userspace.
    > +
    > +
    > +Concept
    > +-------
    > +
    > +pmalloc builds on top of genalloc, using the same concept of memory pools.
    > +
    > +The value added by pmalloc is that now the memory contained in a pool can
    > +become R/O, for the rest of the life of the pool.
    > +
    > +Different kernel drivers and threads can use different pools, for finer
    > +control of what becomes R/O and when. And for improved lockless concurrency.
    > +
    > +
    > +Caveats
    > +-------
    > +
    > +- Memory freed while a pool is not yet protected will be reused.
    > +
    > +- Once a pool is protected, it's not possible to allocate any more memory
    > + from it.
    > +
    > +- Memory "freed" from a protected pool indicates that such memory is not
    > + in use anymore by the requester; however, it will not become available
    > + for further use, until the pool is destroyed.
    > +
    > +- pmalloc does not provide locking support with respect to allocating vs
    > + protecting an individual pool, for performance reasons.
    > + It is recommended not to share the same pool between unrelated functions.
    > + Should sharing be a necessity, the user of the shared pool is expected
    > + to implement locking for that pool.
    > +
    > +- pmalloc uses genalloc to optimize the use of the space it allocates
    > + through vmalloc. Some more TLB entries will be used, however less than
    > + in the case of using vmalloc directly. The exact number depends on the
    > + size of each allocation request and possible slack.
    > +
    > +- Considering that not much data is supposed to be dynamically allocated
    > + and then marked as read-only, it shouldn't be an issue that the address
    > + range for pmalloc is limited, on 32-bit systems.
    > +
    > +- Regarding SMP systems, the allocations are expected to happen mostly
    > + during an initial transient, after which there should be no more need to
    > + perform cross-processor synchronizations of page tables.
    > +
    > +- To facilitate the conversion of existing code to pmalloc pools, several
    > + helper functions are provided, mirroring their kmalloc counterparts.
    > +
    > +
    > +Use
    > +---
    > +
    > +The typical sequence, when using pmalloc, is:
    > +
    > +1. create a pool
    > +
    > +.. kernel-doc:: include/linux/pmalloc.h
    > + :functions: pmalloc_create_pool
    > +
    > +2. [optional] pre-allocate some memory in the pool
    > +
    > +.. kernel-doc:: include/linux/pmalloc.h
    > + :functions: pmalloc_prealloc
    > +
    > +3. issue one or more allocation requests to the pool with locking as needed
    > +
    > +.. kernel-doc:: include/linux/pmalloc.h
    > + :functions: pmalloc
    > +
    > +.. kernel-doc:: include/linux/pmalloc.h
    > + :functions: pzalloc
    > +
    > +4. initialize the memory obtained with desired values
    > +
    > +5. [optional] iterate over points 3 & 4 as needed
    > +
    > +6. write-protect the pool
    > +
    > +.. kernel-doc:: include/linux/pmalloc.h
    > + :functions: pmalloc_protect_pool
    > +
    > +7. use in read-only mode the handles obtained through the allocations
    > +
    > +8. [optional] release all the memory allocated
    > +
    > +.. kernel-doc:: include/linux/pmalloc.h
    > + :functions: pfree
    > +
    > +9. [optional, but depends on point 8] destroy the pool
    > +
    > +.. kernel-doc:: include/linux/pmalloc.h
    > + :functions: pmalloc_destroy_pool
    > +
    > +API
    > +---
    > +
    > +.. kernel-doc:: include/linux/pmalloc.h

    \
     
     \ /
      Last update: 2018-03-06 18:34    [W:5.621 / U:0.012 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site