lkml.org 
[lkml]   [2007]   [Feb]   [21]   [last100]   RSS Feed
Views: [more markup]  [less markup]  [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    DateWed, 21 Feb 2007 22:15:21 +0100
    FromIngo Molnar <>
    Subject[patch 05/13] syslets: core, documentation
    From: Ingo Molnar <mingo@elte.hu>
    
    Add Documentation/syslet-design.txt with a high-level description
    of the syslet concepts.
    
    Signed-off-by: Ingo Molnar <mingo@elte.hu>
    Signed-off-by: Arjan van de Ven <arjan@linux.intel.com>
    ---
     Documentation/syslet-design.txt |  137 ++++++++++++++++++++++++++++++++++++++++
     1 file changed, 137 insertions(+)
    Index: linux/Documentation/syslet-design.txt
    ===================================================================
    --- /dev/null
    +++ linux/Documentation/syslet-design.txt
    @@ -0,0 +1,137 @@
    +Syslets / asynchronous system calls
    +===================================
    +
    +started by Ingo Molnar <mingo@redhat.com>
    +
    +Goal:
    +-----
    +
    +The goal of the syslet subsystem is to allow user-space to execute
    +arbitrary system calls asynchronously. It does so by allowing user-space
    +to execute "syslets" which are small scriptlets that the kernel can execute
    +both securely and asynchronously without having to exit to user-space.
    +
    +the core syslet concepts are:
    +
    +The Syslet Atom:
    +----------------
    +
    +The syslet atom is a small, fixed-size (44 bytes on 32-bit) piece of
    +user-space memory, which is the basic unit of execution within the syslet
    +framework. A syslet represents a single system-call and its arguments.
    +In addition it also has condition flags attached to it that allows the
    +construction of larger programs (syslets) from these atoms.
    +
    +Arguments to the system call are implemented via pointers to arguments.
    +This not only increases the flexibility of syslet atoms (multiple syslets
    +can share the same variable for example), but is also an optimization:
    +copy_uatom() will only fetch syscall parameters up until the point it
    +meets the first NULL pointer. 50% of all syscalls have 2 or less
    +parameters (and 90% of all syscalls have 4 or less parameters).
    +
    + [ Note: since the argument array is at the end of the atom, and the
    +   kernel will not touch any argument beyond the final NULL one, atoms
    +   might be packed more tightly. (the only special case exception to
    +   this rule would be SKIP_TO_NEXT_ON_STOP atoms, where the kernel will
    +   jump a full syslet_uatom number of bytes.) ]
    +
    +The Syslet:
    +-----------
    +
    +A syslet is a program, represented by a graph of syslet atoms. The
    +syslet atoms are chained to each other either via the atom->next pointer,
    +or via the SYSLET_SKIP_TO_NEXT_ON_STOP flag.
    +
    +Running Syslets:
    +----------------
    +
    +Syslets can be run via the sys_async_exec() system call, which takes
    +the first atom of the syslet as an argument. The kernel does not need
    +to be told about the other atoms - it will fetch them on the fly as
    +execution goes forward.
    +
    +A syslet might either be executed 'cached', or it might generate a
    +'cachemiss'.
    +
    +'Cached' syslet execution means that the whole syslet was executed
    +without blocking. The system-call returns the submitted atom's address
    +in this case.
    +
    +If a syslet blocks while the kernel executes a system-call embedded in
    +one of its atoms, the kernel will keep working on that syscall in
    +parallel, but it immediately returns to user-space with a NULL pointer,
    +so the submitting task can submit other syslets.
    +
    +Completion of asynchronous syslets:
    +-----------------------------------
    +
    +Completion of asynchronous syslets is done via the 'completion ring',
    +which is a ringbuffer of syslet atom pointers user user-space memory,
    +provided by user-space as an argument to the sys_async_exec() syscall.
    +The kernel fills in the ringbuffer starting at index 0, and user-space
    +must clear out these pointers. Once the kernel reaches the end of
    +the ring it wraps back to index 0. The kernel will not overwrite
    +non-NULL pointers (but will return an error), user-space has to
    +make sure it completes all events it asked for.
    +
    +Waiting for completions:
    +------------------------
    +
    +Syslet completions can be waited for via the sys_async_wait()
    +system call - which takes the number of events it should wait for as
    +a parameter. This system call will also return if the number of
    +pending events goes down to zero.
    +
    +Sample Hello World syslet code:
    +
    +--------------------------->
    +/*
    + * Set up a syslet atom:
    + */
    +static void
    +init_atom(struct syslet_uatom *atom, int nr,
    +	  void *arg_ptr0, void *arg_ptr1, void *arg_ptr2,
    +	  void *arg_ptr3, void *arg_ptr4, void *arg_ptr5,
    +	  void *ret_ptr, unsigned long flags, struct syslet_uatom *next)
    +{
    +	atom->nr = nr;
    +	atom->arg_ptr[0] = arg_ptr0;
    +	atom->arg_ptr[1] = arg_ptr1;
    +	atom->arg_ptr[2] = arg_ptr2;
    +	atom->arg_ptr[3] = arg_ptr3;
    +	atom->arg_ptr[4] = arg_ptr4;
    +	atom->arg_ptr[5] = arg_ptr5;
    +	atom->ret_ptr = ret_ptr;
    +	atom->flags = flags;
    +	atom->next = next;
    +}
    +
    +int main(int argc, char *argv[])
    +{
    +	unsigned long int fd_out = 1; /* standard output */
    +	char *buf = "Hello Syslet World!\n";
    +	unsigned long size = strlen(buf);
    +	struct syslet_uatom atom, *done;
    +
    +	async_head_init();
    +
    +	/*
    +	 * Simple syslet consisting of a single atom:
    +	 */
    +	init_atom(&atom, __NR_sys_write, &fd_out, &buf, &size,
    +		  NULL, NULL, NULL, NULL, SYSLET_ASYNC, NULL);
    +	done = sys_async_exec(&atom);
    +	if (!done) {
    +		sys_async_wait(1);
    +		if (completion_ring[curr_ring_idx] == &atom) {
    +			completion_ring[curr_ring_idx] = NULL;
    +			printf("completed an async syslet atom!\n");
    +		}
    +	} else {
    +		printf("completed an cached syslet atom!\n");
    +	}
    +
    +	async_head_exit();
    +
    +	return 0;
    +}
    -
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at  http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at  http://www.tux.org/lkml/
    
    \
     
     \ /
      Last update: 2007-02-21 22:27    [from the cache]
    ©2003-2008