From 5b783f4e2ec8af181c1b7563e50018c8ca380824 Mon Sep 17 00:00:00 2001 From: Bahadir Balban Date: Fri, 4 Dec 2009 00:30:25 +0200 Subject: [PATCH] Update to manual pages. Introduced an ENOMAP error code for l4_unmap. --- docs/man/man7/capability.7 | 0 docs/man/man7/l4_capability_control.7 | 0 docs/man/man7/l4_exchange_registers.7 | 0 docs/man/man7/l4_getid.7 | 50 +++++++++++++++------------ docs/man/man7/l4_ipc.7 | 0 docs/man/man7/l4_map.7 | 0 docs/man/man7/l4_mutex_control.7 | 0 docs/man/man7/l4_thread_control.7 | 11 +++--- docs/man/man7/l4_thread_switch.7 | 9 ++--- docs/man/man7/l4_time.7 | 41 +++++++++++++++------- docs/man/man7/l4_unmap.7 | 27 ++++++++++++--- docs/man/man7/utcb.7 | 0 include/l4/api/errno.h | 1 + src/arch/arm/v5/mm.c | 2 +- src/generic/time.c | 7 ++-- 15 files changed, 96 insertions(+), 52 deletions(-) mode change 100644 => 100755 docs/man/man7/capability.7 mode change 100644 => 100755 docs/man/man7/l4_capability_control.7 mode change 100644 => 100755 docs/man/man7/l4_exchange_registers.7 mode change 100644 => 100755 docs/man/man7/l4_getid.7 mode change 100644 => 100755 docs/man/man7/l4_ipc.7 mode change 100644 => 100755 docs/man/man7/l4_map.7 mode change 100644 => 100755 docs/man/man7/l4_mutex_control.7 mode change 100644 => 100755 docs/man/man7/l4_thread_control.7 mode change 100644 => 100755 docs/man/man7/l4_thread_switch.7 mode change 100644 => 100755 docs/man/man7/l4_time.7 mode change 100644 => 100755 docs/man/man7/l4_unmap.7 mode change 100644 => 100755 docs/man/man7/utcb.7 diff --git a/docs/man/man7/capability.7 b/docs/man/man7/capability.7 old mode 100644 new mode 100755 diff --git a/docs/man/man7/l4_capability_control.7 b/docs/man/man7/l4_capability_control.7 old mode 100644 new mode 100755 diff --git a/docs/man/man7/l4_exchange_registers.7 b/docs/man/man7/l4_exchange_registers.7 old mode 100644 new mode 100755 diff --git a/docs/man/man7/l4_getid.7 b/docs/man/man7/l4_getid.7 old mode 100644 new mode 100755 index 664938b..7ecfea1 --- a/docs/man/man7/l4_getid.7 +++ b/docs/man/man7/l4_getid.7 @@ -1,7 +1,7 @@ .TH L4_GETID 7 2009-11-02 "Codezero" "Codezero Programmer's Manual" .SH NAME .nf -.BR "l4_getid" "- Returns thread id, thread group id and space id of a thread." +.BR "l4_getid" " - returns thread id, thread group id and space id of a thread." .SH SYNOPSIS .nf @@ -10,35 +10,39 @@ .BI "int l4_getid(struct task_ids " "*ids" ");" .SH DESCRIPTION -.BR l4_getid() " Returns thread id, thread group id and space id of a thread." - -.SH Operational Model -Thread ID, Thread Group ID, and Space ID are received via the -.B ids -structure. -.nf -Every thread in the system has a globally unique Thread ID. -An address space may have one or more threads. Therefore threads may share their Space IDs. -A Thread Group Leader has a Thread ID same as its Thread Group ID. -A newly created thread may join an existing thread group or create a new group. This behaviour is defined by the thread's pager. +.BR "l4_getid() " "returns thread id, thread group id and space id of a thread in a " "struct task_ids " "structure, as shown below." .nf -.in 16 -.B "struct task_ids {" -.BI "int " "tid" "; /* Thread ID */" -.BI "int " "spid" "; /* Space ID */" -.BI "int " "tgid" "; /* Thread Group ID */" -.B "};" +.TP +.BI "struct" " task_ids { " +.in 15 +.BI "int " "tid" "; /* Fully qualified thread id */" +.BI "int " "spid" "; /* Address space id (local to container) */" +.BI "int " "tgid" "; /* Thread group id (local, defined by userspace protocol) */" +.ti 7 +}; + +.fi + +.in 7 +Every thread in the system has a thread id, space id and a thread group id associated with it. Each thread and space id is globally unique across the system. Thread group ids are available for grouping threads in arbitrary groups, via a user-defined protocol. A newly created thread may join an existing thread group or create a new group. This behaviour is defined by the thread's pager. Such a user-defined thread group allocation protocol may be useful for implementing groups of threads by higher level OS services. + +Even though both thread and space ids are globally unique across the system, there is an addressability difference between them. Each thread id is a fully qualified id, carrying its container id information with it. Upon a system call that targets a thread id, the system allows addressing threads in other containers. In contrast, space ids are not fully qualified. They are local to a container, and any system call addressing a space id cannot target a space in another container. + +.SH FUTURE +.BR "l4_getid() " "call is currently not subject to capability checking, as every thread has a natural right to discover their ids. In the future, it is possible that this system call is used for naming discovery for other addressable entities. If such a role is given to this call, it may also become subject to capability checking, as access control would prove beneficial over naming discovery services." + .SH L4 USERSPACE LIBRARY .nf +.B #include + /* * Returns Thread ID of current thread */ +.BI "static inline l4id_t self_tid(" "void" ")" + +.SH RETURN VALUE +.BR "l4_getid()" " always succeeds with a return value of 0." -.BI "static inline l4id_t self_tid(" "void" "){" -.BI "struct task_ids " "ids" ";" -.BI "l4_getid(" "&ids" ");" -.BI "return " "ids.tid" ";" -.B } diff --git a/docs/man/man7/l4_ipc.7 b/docs/man/man7/l4_ipc.7 old mode 100644 new mode 100755 diff --git a/docs/man/man7/l4_map.7 b/docs/man/man7/l4_map.7 old mode 100644 new mode 100755 diff --git a/docs/man/man7/l4_mutex_control.7 b/docs/man/man7/l4_mutex_control.7 old mode 100644 new mode 100755 diff --git a/docs/man/man7/l4_thread_control.7 b/docs/man/man7/l4_thread_control.7 old mode 100644 new mode 100755 index 224d214..ee3bb45 --- a/docs/man/man7/l4_thread_control.7 +++ b/docs/man/man7/l4_thread_control.7 @@ -76,10 +76,8 @@ Waits on a thread to exit, with exit status. On a system setup where a pager is responsible for creating threads in separate address spaces and communicating with them via IPC, the children may send an exit IPC message to their pager. This way, a pager may synchronously receive exit status of a child in the form of IPC, and take action to destroy it as part of handling the IPC. However, on systems where the application is a multi-threaded, single address space application, a thread wait call provides a simple synchronous channel for the parent to wait on its child's exit status, without requiring any extra set up for IPC handling. -.ti 8 - -.I ids -field specifies the thread, address space, and thread group ids of the targeted thread. Below is the declaration for this structure: +.ti 7 +.IR "ids " "field specifies the thread, address space, and thread group ids of the targeted thread. Below is the declaration for this structure:" .nf .TP @@ -115,6 +113,9 @@ flags .I tgid field is provided as an extra id slot for the thread. The pager of the thread may designate a group of threads to be in the same thread group, defining the group by a userspace protocol. This field has no meaning from the kernel's perspective, and may be removed in future releases. +.in 7 +.RB "See " "l4_getid" "(7) for more details on resource ids in Codezero." + .SH THREAD RELATIONSHIPS Codezero aims to provide fine-grain privilege levels to threads in the system in the form of capabilities. Capabilities enable privileges of threads over each other to become highly configurable, resulting in the hierarchical relationship between them to become blurry. However, even though such a relationship is not enforced by the architecture, often it comes natural that threads are created by other threads. As a result, even though a thread hierarchy is not enforced by the capability design, it is implicitly catered for by a .I pagerid @@ -152,4 +153,4 @@ argument would cause a page fault. returned when a given thread id has not been found in the container. .SH SEE ALSO -.BR "capability"(7), " l4_exchange_registers"(7) +.BR "capability"(7), " l4_exchange_registers" "(7), " "l4_getid" "(7)" diff --git a/docs/man/man7/l4_thread_switch.7 b/docs/man/man7/l4_thread_switch.7 old mode 100644 new mode 100755 index c111bd5..9cb28fa --- a/docs/man/man7/l4_thread_switch.7 +++ b/docs/man/man7/l4_thread_switch.7 @@ -10,9 +10,10 @@ .BI "int l4_thread_switch(u32 " "dest" ");" .SH DESCRIPTION -.BR l4_thread_switch() " - Yields the CPU." +.BR l4_thread_switch() " - yields the CPU. Current thread yields the CPU donating its left timeslice to thread with id specified in the +.I dest +field. -Current thread yields the CPU donating its left timeslice to thread with ID specified in the -.B dest -argument. +.SH RETURN VALUE +Always succeeds with a return value of 0. diff --git a/docs/man/man7/l4_time.7 b/docs/man/man7/l4_time.7 old mode 100644 new mode 100755 index e83033d..7785e24 --- a/docs/man/man7/l4_time.7 +++ b/docs/man/man7/l4_time.7 @@ -1,27 +1,44 @@ .TH L4_TIME 7 2009-11-07 "Codezero" "Codezero Programmer's Manual" .SH NAME .nf -.BR "l4_time" "- Sets or returns system time." +.BR "l4_time" " - sets or reads system time." .SH SYNOPSIS .nf .B #include .B #include -.BI "int l4_time(void " "*timeval" ", int " "set" ");" +.BI "int l4_time(struct timeval *" "timeval" ", int " "set" ");" + .SH DESCRIPTION -.BR l4_time() " - Sets or returns system time." +.BR "l4_time() " "sets or reads system time. " -System time is read in the -.B timeval -argument field. +.IR "timeval " "field is the representation of time since the system has started running. See below for details." -If -.B set -argument is a non-zero value, system time is set using the values in -.B timeval +.IR "set " " field instructs whether the time is to be read or set to the values specified in the " "timeval " "field supplied." -Currently setting the time feature is disabled +.nf +.B struct timeval { +.BI " int " "tv_sec;" " /* Time value in seconds */ " +.BI " int " "tv_usec;" " /* Time value in microseconds */ " +.B }; +.fi -Currently the system time is returned since the system has started rather than a set date. +.SH LIMITATIONS +- Currently setting the time feature is disabled. + +- Currently the system time is returned since the system has started rather than a set date. + +- Currently this system call is not subject to capabilities. + +.SH ERRORS +.TP +.B -EFAULT +.IR "timeval " "field would cause an unhandled page fault." +.TP +.B -EBUSY +Timer structures in the system are currently being used. +.TP +.B -ENOSYS +Operation of given type is not supported. diff --git a/docs/man/man7/l4_unmap.7 b/docs/man/man7/l4_unmap.7 old mode 100644 new mode 100755 index 78f9fc0..7f5e1dc --- a/docs/man/man7/l4_unmap.7 +++ b/docs/man/man7/l4_unmap.7 @@ -1,7 +1,7 @@ .TH L4_UNMAP 7 2009-11-02 "Codezero" "Codezero Programmer's Manual" .SH NAME .nf -.BR "l4_unmap" "- Removes virtual to physical address mappings." +.BR "l4_unmap" " - removes virtual to physical address mappings." .SH SYNOPSIS .nf @@ -10,9 +10,9 @@ .BI "int l4_unmap(void " "*virtual" ", unsigned long " "npages" ", l4id_t " "tid" ")" .SH DESCRIPTION -.BR l4_unmap() " Removes virtual to physical address mappings from a thread's address space" +.B l4_unmap() +.RI "removes a virtual to physical mapping from the address space of the thread identified by " "tid " "starting from virtual address " "virtual" ", and spanning " "npages" " number of pages." -.RB "Removes a virtual to physical mapping for the thread identified by " "tid" ", startingfrom virtual address " "virtual" ", spanning " "npages" " number of pages." .SH L4 USERSPACE LIBRARY @@ -23,5 +23,24 @@ * spanning npages number of pages. Returns negative value * if the address was already unmapped. */ - .BI "static inline void *l4_unmap_helper(void " "*virt" ", int " "npages" ");" + +.fi +.SH RETURN VALUE +.BR "l4_unmap"() +returns 0 on success, and negative value on failure. See below for error codes. + +.SH ERRORS + +.B -ESRCH +The thread to remove the mapping could not be found on the system. + +.B -ENOCAP +Capabilities required don't exist or caller do not have sufficient privileges. + +.B -1 +There is already an unmapped area in one of the pages that were unmapped. This may or may not be an error, depending on what state the caller expects the unmapped area to be in. + +.SH SEE ALSO +.BR "l4_map"(7) + diff --git a/docs/man/man7/utcb.7 b/docs/man/man7/utcb.7 old mode 100644 new mode 100755 diff --git a/include/l4/api/errno.h b/include/l4/api/errno.h index 6d50a54..35301eb 100644 --- a/include/l4/api/errno.h +++ b/include/l4/api/errno.h @@ -140,5 +140,6 @@ #define ENOIPC 133 /* General IPC error */ #define ENOCAP 134 /* None or insufficient capability */ #define ENOUTCB 135 /* Task has no utcb set up */ +#define ENOMAP 136 /* The memory area has unmapped regions */ #endif /* __ERRNO_H__ */ diff --git a/src/arch/arm/v5/mm.c b/src/arch/arm/v5/mm.c index d37e41c..ccf243f 100644 --- a/src/arch/arm/v5/mm.c +++ b/src/arch/arm/v5/mm.c @@ -443,7 +443,7 @@ int remove_mapping_pgd(unsigned long vaddr, pgd_table_t *pgd) break; case PGD_TYPE_FAULT: - ret = -1; + ret = -ENOMAP; break; case PGD_TYPE_SECTION: diff --git a/src/generic/time.c b/src/generic/time.c index b33321f..cbce9ab 100644 --- a/src/generic/time.c +++ b/src/generic/time.c @@ -68,10 +68,11 @@ void update_system_time(void) int sys_time(struct timeval *tv, int set) { int retries = 20; + int err; - if (check_access((unsigned long)tv, sizeof(*tv), - MAP_USR_RW_FLAGS, 1) < 0) - return -EINVAL; + if ((err = check_access((unsigned long)tv, sizeof(*tv), + MAP_USR_RW_FLAGS, 1)) < 0) + return err; /* Get time */ if (!set) {