From 510dfe82ddff2e4b9ef6e94bcbad7d2b7835c6f9 Mon Sep 17 00:00:00 2001 From: Bahadir Balban Date: Wed, 2 Dec 2009 19:42:56 +0200 Subject: [PATCH] l4_exchange_registers man page. --- docs/man/man7/l4_exchange_registers.7 | 109 +++++++++++++++++--------- 1 file changed, 71 insertions(+), 38 deletions(-) diff --git a/docs/man/man7/l4_exchange_registers.7 b/docs/man/man7/l4_exchange_registers.7 index d3f6a16..1d49ff2 100644 --- a/docs/man/man7/l4_exchange_registers.7 +++ b/docs/man/man7/l4_exchange_registers.7 @@ -1,7 +1,7 @@ .TH L4_EXCHANGE_REGISTERS 7 2009-11-02 "Codezero" "Codezero Programmer's Manual" .SH NAME .nf -.BR "l4_exchange_registers" "- Modifies the context of a suspended thread." +.BR "l4_exchange_registers" "Modifies the context of a suspended thread." .SH SYNOPSIS .nf @@ -10,47 +10,15 @@ .BI "int l4_exchange_registers(void " "*exregs_struct" ", l4id_t " "tid" ");" .SH DESCRIPTION -.BR l4_exchange_registers() " Modifies the context of a suspended thread." +.BR "l4_exchange_registers() " " Reads and modifies the context of a suspended thread." -Pagers can modify any register, the pager id or utcb virtual address of a thread using this call. - -An architecture specific +By this call, pagers can read and modify any register or other crucial information about a thread such as the pager id or utcb virtual address. An architecture specific .BI "struct " exregs_data -is passed to the kernel for modifying the context of a thread. - -Each bit in the -.B valid_vect -field determines which register offsets are to be modified. - -.B flags -field determines whether to set the -.BR pagerid " and " utcb_address -fields of the thread. +is passed to the kernel for modifying the targeted thread's context. See below for a detailed description of this structure and the default context structure for the ARM architecture. .nf .in 8 -/* Values for the flags fields */ -#define EXREGS_SET_PAGER 1 -#define EXREGS_SET_UTCB 2 -#define EXREGS_READ 4 -.nf -.in 8 - -/* Generic structure passed by userspace pagers - * for exchanging registers - */ -.B struct exregs_data { -.in 16 -.BI "exregs_context_t " "context" ";" -.BI "u32 " "valid_vect" ";" -.BI "u32 " "flags" ";" -.BI "l4id_t " "pagerid" ";" -.BI "unsigned long " "utcb_address" ";" -.ti 8 -.B }; - -.in 8 -/* Exchange registers context structure for ARM */ +/* Exchange registers context structure for the ARM architecture */ .B typedef struct arm_exregs_context { .in 16 .BI "u32 " "r0" "; /* 0x4 */" @@ -72,6 +40,43 @@ fields of the thread. .ti 8 .B } __attribute__((__packed__)) exregs_context_t; +.nf +.in 8 + +/* + * Generic structure passed by userspace pagers + * for exchanging registers + */ +.B struct exregs_data { +.in 16 +.BI "exregs_context_t " "context" ";" +.BI "u32 " "valid_vect" ";" +.BI "u32 " "flags" ";" +.BI "l4id_t " "pagerid" ";" +.BI "unsigned long " "utcb_address" ";" +.ti 8 +.B }; + +.fi +.in 7 +Each bit in the +.I valid_vect +field determines which register offsets are going to be modified. + +.I flags +field determines whether to set or read the pager values provided, and affects the +.IR pagerid " and " utcb_address +fields of the thread: +.TP +.B EXREGS_SET_PAGER +Sets the pagerid value of the targeted thread. +.TP +.B EXREGS_SET_UTCB +Sets the utcb virtual address of the targeted thread. +.TP +.B EXREGS_READ +Enables read-only operation, all set fields are read back from the targeted thread's context instead of modifying it. + .in 8 .SH L4 Userspace Library Functions @@ -81,9 +86,37 @@ fields of the thread. * Exchange register library calls to modify program counter, * stack, pager id, utcb address and any hardware register. */ - .BI "void exregs_set_stack(struct exregs_data " "*s" ", unsigned long " sp); .BI "void exregs_set_mr(struct exregs_data " "*s" ", int " "offset" ", unsigned long " "val" ");" .BI "void exregs_set_pc(struct exregs_data " "*s" ", unsigned long " "pc" ");" .BI "void exregs_set_pager(struct exregs_data " "*s" ", l4id_t " "pagerid" ");" .BI "void exregs_set_utcb(struct exregs_data "*s" ", unsigned long " "virt" ");" + +.fi +Above functions may be used for convenient manipulation of the +.BI "struct " "exregs_data" +structure. + +.SH RETURN VALUE +.IR "l4_exchange_registers"() +Returns 0 on success, and negative value on failure. See below for error codes. + +.SH ERRORS +.TP +.B -ESRCH +Target thread was not found in the system. + +.TP +.B -ENOCAP +Capabilities required don't exist or do not have sufficient privileges. + +.TP +.B -EACTIVE +Target thread has not suspended yet. + +.TP +.B -EAGAIN +Target thread is busy holding a mutex. + +.SH SEE ALSO +.BR "l4_thread_control"(7)