[PATCH 1/3] kshmem documentation

[PATCH 1/3] kshmem documentation

[Wink Saville]

This series of patches allows memory to be allocated
by the kernel at addresses that can be used both by
the kernel and user space.

A following series of patches, ACE (Atomic Code Execution),
uses kshmem to implement spin_lock_irqsave and
spin_lock_irqresotre semantics in user space. With these
two features it is possible to implement simple
data structures, such as linked lists of data, that
can be shared between kernel and user code.

I would like to know if the people on the KVM mailing
list might find this useful for implementing para-virtual
devices. For instance, it is possible for an interrupt
service routine to directly send or receive information
using these two features with the need for copying.

Signed-off-by: Wink Saville <wink-hKg/bvL8yClBDgjK7y7TUQ@public.gmane.org>
---
  Documentation/kshmem.txt |   91 ++++++++++++++++++++++++++++++++++++++++++++++
  1 files changed, 91 insertions(+), 0 deletions(-)
  create mode 100644 Documentation/kshmem.txt

Index: linux-2.6/Documentation/kshmem.txt
===================================================================
--- /dev/null    1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6/Documentation/kshmem.txt    2007-04-29 21:52:04.000000000 -0700
@@ -0,0 +1,91 @@
+Title    : Kernel shared memory
+Authors    : Wink Saville <wink-hKg/bvL8yClBDgjK7y7TUQ@public.gmane.org>
+
+CONTENTS
+
+1. Concepts
+2. Architectures Supported
+3. Configuring
+4. API Reference
+5. TODO
+
+
+1. Concepts
+
+Kernel shared memory (kshmem) is memory that is shared by all
+processes/threads both user and kernel. The purpose is to allow
+any code running on the system to efficiently share data in
+memory. In particular ISR's and user space code can share memory.
+
+The current implementation works by sharing one set of page
+descriptors for all instances of mm_struct's that are created.
+Anytime a new mm_struct is created kshmem_prepare is called and
+the level 4 page descriptor from init_mm is copied to the new_mm
+but the user flag is disabled so no access is possible from user
+space.
+
+To access the kshmem from user space some mechanism, such as
+creating a device driver, which calls kshmem_user_enable().
+
+You will notice that there is no kshmem_free, currently it is
+envisioned that kshmem will be allocated by other subsystems
+and that pools will be created which will manage memory. Of
+course this may not be enough and a kshmem_free may be needed.
+
+
+2. Architectures Supported
+
+- X86_64
+
+
+3. Configuring
+
+In "Processor type and features" select "Kernel shared memory".
+
+
+4. API Reference
+
+Kshmem supports the following API:
+
+char *kshmem_alloc_at(unsigned long location, unsigned long size, pgprot_t page_flags)
+
+  Allocate size number of bytes of kshmem at a specific location,
+  page_flags should be PAGE_SHARED or PAGE_SHARED_EXEC.
+
+  The resulting pointer will be page aligned and consume at least
+  on page of memory.
+
+
+void *kshmem_alloc(unsigned long size, pgprot_t page_flags)
+
+  Allocate size number of bytes of kshmem, page_flags
+  should be PAGE_SHARED or PAGE_SHARED_EXEC.
+
+  The resulting pointer will be page aligned and consume at least
+  on page of memory.
+
+
+void kshmem_user_disable()
+
+  Disable the kshmem for the current mm.
+
+
+void kshmem_user_enable()
+
+  Enable the kshmem for the current mm.
+
+
+int kshmem_prepare(struct mm_struct *pNew_mm)
+
+  Prepare a mm_struct, used by the kernel when new mm_structs are created.
+
+
+unsigned long     kshmem_addr_to_kvaddr(unsigned long kshmem_addr);
+
+  Convert a virtual kshmem_addr to a kernel virtual address so DMA may be performed.
+
+
+5. TODO
+
+a. kshmem_free not implemented this may or may not be needed
+



-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/