[PATCH 1/4] ACE documentation

[Wink Saville <wink-hKg/bvL8yClBDgjK7y7TUQ@public.gmane.org>]

ACE, is an acronym for Atomic Code Execution and provides
spin_lock_irqsave and spin_lock_irqrestore semantics in
user space.

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

Index: linux-2.6/Documentation/ace.txt
===================================================================
--- /dev/null	1970-01-01 00:00:00.000000000 +0000
+++ linux-2.6/Documentation/ace.txt	2007-04-29 21:52:04.000000000 -0700
@@ -0,0 +1,100 @@
+Title	: Atomic Code Execution (ACE)
+Authors	: Wink Saville <wink-hKg/bvL8yClBDgjK7y7TUQ@public.gmane.org>
+
+CONTENTS
+
+1. Concepts
+2. Architectures Supported
+3. Configuring
+4. API Reference
+5. TODO
+
+
+1. Concepts
+
+Atomic Code Execution (ACE) allows code to execute as if it was
+surrounded by spin_lock_irqsave and spin_unlock_irqrestore without
+requiring actual access to the processor flags register. Thus code
+executing within the ACE area can also be executed from user space or
+kernel space. This is accomplished by using spin locks when executing
+within the ACE area and changes to arch/x86_64/kernel/entry.S such that
+when an interrupt occurs while executing code in the ACE area that code
+will be completed before the interrupt is dispatched.
+
+The modifications to entry.S starts at the label ace_common plus the
+macro HANDLE_ACE immediately following. HANDLE_ACE invokes ace_common
+at the beginning of each interrupt, if it finds that code in the ACE
+area was interrupted it causes the ACE code to resume execution prior
+to handling the interrupt.
+
+The code for the ACE area is in the file arch/x86_64/kernel/ace.S. This
+file contains all of the code that maybe executed by the kernel or
+user-space. To be able to share this code with user space the code is
+also compiled by user space, but this is only to generate the jump
+table. Other techniques are possible, but this is the current
+implementation and can be seen in the directory test/ace.
+
+The implementation of the code in the ACE area must be coordinated with
+how the code in HANDLE_ACE is implemented and will be specific to each
+architecture. The primary requirement is that it must be easy for the
+ISR code to continue execution and it must be easy for both user and
+kernel code to execute it. To make it simple to continue execution the
+ISR code alters the ACE code return address.
+
+This is done by having the ACE code always return to the non-ACE code
+via register r11. This allows the HANDLE_ACE code to swap the contents
+of r11 with the interrupted address and thus compete the ACE code which
+will release the spinlock and the original caller will be returned to
+when the ISR completes. Thus giving us the semantic that ACE area code
+was executed as if it was surrounded by a spin_lock_irqsave and a
+spin_unlock_irqrestore.
+
+To allow the above algorithm to work under all circumstances the ACE
+area code must appear in every user and kernel thread, this is
+accomplished by allocting the ACE area using kshmem_alloc_at.
+
+The ACE area is initialized by calling
+drivers/ace/ace_device.c/ace_init() from init/main.c/start_kernel().
+
+
+2. Architectures Supported
+
+- X86_64
+
+
+3. Configuring
+
+In "Processor type and features" select "Atomic Code Execution (ACE)".
+
+
+4. ACE area API Reference
+
+ACE supports the following API:
+
+uint64_t ace_inc_counter(void)
+
+  Increment the counter
+
+
+uint64_t ace_inc_timer_counter(void)
+
+  Increment the timer counter
+
+
+void ace_get_counters(uint64_t *counter, uint64_t *timer_counter)
+
+  Return the counter and timer counter
+
+
+5. ACE device driver API Reference
+
+The ACE driver must be opened before accessing any of the ACE are API
+routines and close upon exiting. The driver name is /dev/ace.
+Currently there is an ioctl routine but no operations are defined.
+
+
+5. TODO
+
+a. Decide how to handle page faults while executing ACE.
+b. Decide upon the actual code needed in ACE.
+


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