Subversion Repositories c0or1k

.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."

.SH SYNOPSIS

.nf

.B #include 

.B #include 

.BI "int l4_exchange_registers(void " "*exregs_struct" ", l4id_t " "tid" ");"

.SH DESCRIPTION

.BR "l4_exchange_registers() " " Reads and modifies the context of a suspended thread."

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 targeted thread's context. See below for a detailed description of this structure and the default context structure for the ARM architecture.

.nf

/* Exchange registers context structure for the ARM architecture */

.B typedef struct arm_exregs_context {

.BI "      u32 " "r0" ";                /* 0x4 */"

.BI "      u32 " "r1" ";                /* 0x8 */"

.BI "      u32 " "r2" ";                /* 0xC */"

.BI "      u32 " "r3" ";                /* 0x10 */"

.BI "      u32 " "r4" ";                /* 0x14 */"

.BI "      u32 " "r5" ";                /* 0x18 */"

.BI "      u32 " "r6" ";                /* 0x1C */"

.BI "      u32 " "r7" ";                /* 0x20 */"

.BI "      u32 " "r8" ";                /* 0x24 */"

.BI "      u32 " "r9" ";                /* 0x28 */"

.BI "      u32 " "r10" ";               /* 0x2C */"

.BI "      u32 " "r11" ";               /* 0x30 */"

.BI "      u32 " "r12" ";               /* 0x34 */"

.BI "      u32 " "sp" ";                /* 0x38 */"

.BI "      u32 " "lr" ";                /* 0x3C */"

.BI "      u32 " "pc" ";                /* 0x40 */"

.B } __attribute__((__packed__)) exregs_context_t;

.nf

/*

 * Generic structure passed by userspace pagers

 * for exchanging registers

 */

.B struct exregs_data {

.BI "      exregs_context_t " "context" ";"

.BI "      u32 " "valid_vect" ";"

.BI "      u32 " "flags" ";"

.BI "      l4id_t " "pagerid" ";"

.BI "      unsigned long " "utcb_address" ";"

.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

.nf

/*

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