sambuc/codezero
1
0
Fork 0
mirror of https://github.com/drasko/codezero.git synced 2026-01-12 02:43:15 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

l4_exchange_registers man page.

Browse Source
This commit is contained in:
Bahadir Balban
2009-12-02 19:42:56 +02:00
parent 8b0aab976a
commit 510dfe82dd
1 changed files with 71 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
docs/man/man7/l4_exchange_registers.7
View File

@@ -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)