diff --git a/kernel/syscalls/sync.md b/kernel/syscalls/sync.md index 4bd381e5..bc54fca3 100644 --- a/kernel/syscalls/sync.md +++ b/kernel/syscalls/sync.md @@ -1,12 +1,13 @@ # Thread synchronization -## `syscalls_mutexCreate` +## `syscalls_phMutexCreate` ````C GETFROMSTACK(ustack, unsigned int *, h, 0); +GETFROMSTACK(ustack, const struct lockAttr *, attr, 1); ```` -Creates mutex and returns resource handle `h`. +Creates mutex and returns resource handle `h`. Mutex attributes are specified in `attr` structure. ## `syscalls_mutexLock` (`syscalls_phMutexLock`) @@ -32,13 +33,15 @@ GETFROMSTACK(ustack, unsigned int, h, 0); Unlocks mutex given by `h`. -## `syscalls_condCreate` +## `syscalls_phCondCreate` ````C GETFROMSTACK(ustack, unsigned int *, h, 0); +GETFROMSTACK(ustack, const struct condAttr *, attr, 1); ```` -Creates conditional variable and returns its handle in variable `h`. +Creates conditional variable and returns its handle in variable `h`. Conditional variable attributes are specified in +`attr` structure. ## `syscalls_condWait` (`syscalls_phCondWait`) diff --git a/libc/functions/index.md b/libc/functions/index.md index 9b9ea9a7..bf1c27fd 100644 --- a/libc/functions/index.md +++ b/libc/functions/index.md @@ -252,8 +252,11 @@ ## sys/threads [`condCreate`](sys/threads/condCreate.phrtos.md), +[`condCreateWithAttr`](sys/threads/condCreateWithAttr.phrtos.md), [`condBroadcast`](sys/threads/condSignal.phrtos.md), -[`condWait`](sys/threads/condWait.phrtos.md) +[`condWait`](sys/threads/condWait.phrtos.md), +[`mutexCreate`](sys/threads/mutexCreate.phrtos.md), +[`mutexCreateWithAttr`](sys/threads/mutexCreateWithAttr.phrtos.md) ## sys/times diff --git a/libc/functions/sys/threads/condCreate.phrtos.md b/libc/functions/sys/threads/condCreate.phrtos.md index 6791108a..33bc2a03 100644 --- a/libc/functions/sys/threads/condCreate.phrtos.md +++ b/libc/functions/sys/threads/condCreate.phrtos.md @@ -16,8 +16,8 @@ Phoenix-RTOS specific ## Description -The `condCreate()` function shall initialize the condition variable referenced by _h_. Upon successful initialization, -the state of the condition variable shall become initialized. +The `condCreate()` function shall initialize the condition variable referenced by _h_ using default attributes. Upon +successful initialization, the state of the condition variable shall become initialized. Attempting to initialize an already initialized condition variable results in undefined behavior. @@ -31,12 +31,13 @@ an error number shall be returned to indicate the error. The `condCreate()` function shall fail if: * `-ENOMEM` - Insufficient memory exists to initialize the condition variable. +* `-EFAULT` - The address specified by `h` is invalid. These functions shall not return an error code of `EINTR`. ## Tests -Untested +Tested in [test-sys](https://github.com/phoenix-rtos/phoenix-rtos-tests/tree/master/sys) ## Known bugs diff --git a/libc/functions/sys/threads/condCreateWithAttr.phrtos.md b/libc/functions/sys/threads/condCreateWithAttr.phrtos.md new file mode 100644 index 00000000..c89e6b34 --- /dev/null +++ b/libc/functions/sys/threads/condCreateWithAttr.phrtos.md @@ -0,0 +1,65 @@ +# condCreateWithAttr + +## Synopsis + +`#include ` + +`int condCreateWithAttr(handle_t *h, struct condAttr *attr);` + +## Status + +Implemented + +## Conformance + +Phoenix-RTOS specific + +## Description + +The `condCreateWithAttr()` function shall initialize the condition variable referenced by `h` using attributes +specified in the `attr` structure (non-`NULL`). Upon successful initialization, the state of the condition variable +shall become initialized. + +Attempting to initialize an already initialized condition variable results in undefined behavior. + +Attributes structure `condAttr` is defined as follows: + +```c +struct condAttr { + int clock; +}; +``` + +The `clock` field specifies the clock to be used for the condition variable. The following values are supported: + +* `PH_CLOCK_RELATIVE` - `timeout` passed to `condWait()` is relative to the current time. +* `PH_CLOCK_REALTIME` - `timeout` passed to `condWait()` is absolute time based on the real-time clock. +* `PH_CLOCK_MONOTONIC` - `timeout` passed to `condWait()` is absolute time based on the monotonic clock. + +## Return value + +If successful, the `condCreateWithAttr()` function shall return zero; otherwise, +an error number shall be returned to indicate the error. + +## Errors + +The `condCreateWithAttr()` function shall fail if: + +* `-ENOMEM` - Insufficient memory exists to initialize the condition variable. +* `-EINVAL` - The attributes specified in `attr` are invalid. +* `-EFAULT` - The address specified by `h` or `attr` is invalid. + +These functions shall not return an error code of `EINTR`. + +## Tests + +Tested in [test-sys](https://github.com/phoenix-rtos/phoenix-rtos-tests/tree/master/sys) + +## Known bugs + +None + +## See Also + +1. [Standard library functions](../../index.md) +2. [Table of Contents](../../../../index.md) diff --git a/libc/functions/sys/threads/condSignal.phrtos.md b/libc/functions/sys/threads/condSignal.phrtos.md index d9a37e05..afa420e0 100644 --- a/libc/functions/sys/threads/condSignal.phrtos.md +++ b/libc/functions/sys/threads/condSignal.phrtos.md @@ -61,7 +61,7 @@ These functions shall not return an error code of `-EINTR`. ## Tests -Untested +Tested in [test-sys](https://github.com/phoenix-rtos/phoenix-rtos-tests/tree/master/sys) ## Known bugs diff --git a/libc/functions/sys/threads/condWait.phrtos.md b/libc/functions/sys/threads/condWait.phrtos.md index d35bfa80..8c8b723c 100644 --- a/libc/functions/sys/threads/condWait.phrtos.md +++ b/libc/functions/sys/threads/condWait.phrtos.md @@ -77,7 +77,7 @@ This function shall fall if: ## Tests -Untested +Tested in [test-sys](https://github.com/phoenix-rtos/phoenix-rtos-tests/tree/master/sys) ## Known bugs diff --git a/libc/functions/sys/threads/mutexCreate.phrtos.md b/libc/functions/sys/threads/mutexCreate.phrtos.md new file mode 100644 index 00000000..08580831 --- /dev/null +++ b/libc/functions/sys/threads/mutexCreate.phrtos.md @@ -0,0 +1,49 @@ +# mutexCreate + +## Synopsis + +`#include ` + +`int mutexCreate(handle_t *h);` + +## Status + +Implemented + +## Conformance + +Phoenix-RTOS specific + +## Description + +The `mutexCreate()` function shall initialize the mutex referenced by `h` using default attributes. Upon +successful initialization, the state of the mutex shall become initialized. + +Attempting to initialize an already initialized mutex results in undefined behavior. + +## Return value + +If successful, the `mutexCreate()` function shall return zero; otherwise, +an error number shall be returned to indicate the error. + +## Errors + +The `mutexCreate()` function shall fail if: + +* `-ENOMEM` - Insufficient memory exists to initialize the mutex. +* `-EFAULT` - The address specified by `h` is invalid. + +These functions shall not return an error code of `EINTR`. + +## Tests + +Tested in [test-sys](https://github.com/phoenix-rtos/phoenix-rtos-tests/tree/master/sys) + +## Known bugs + +None + +## See Also + +1. [Standard library functions](../../index.md) +2. [Table of Contents](../../../../index.md) diff --git a/libc/functions/sys/threads/mutexCreateWithAttr.phrtos.md b/libc/functions/sys/threads/mutexCreateWithAttr.phrtos.md new file mode 100644 index 00000000..3a5f1698 --- /dev/null +++ b/libc/functions/sys/threads/mutexCreateWithAttr.phrtos.md @@ -0,0 +1,66 @@ +# mutexCreateWithAttr + +## Synopsis + +`#include ` + +`int mutexCreateWithAttr(handle_t *h, struct lockAttr *attr);` + +## Status + +Implemented + +## Conformance + +Phoenix-RTOS specific + +## Description + +The `mutexCreateWithAttr()` function shall initialize the mutex referenced by `h` using attributes specified by `attr` +(non-`NULL`). Upon successful initialization, the state of the mutex shall become initialized. + +Attempting to initialize an already initialized mutex results in undefined behavior. + +Attributes structure `lockAttr` is defined as follows: + +```c +struct lockAttr { + int type; +}; +``` + +The `type` field specifies the type of the mutex. The following values are supported: + +* `PH_LOCK_NORMAL` - The mutex is a normal mutex. +* `PH_LOCK_RECURSIVE` - The mutex is a recursive mutex. A recursive mutex allows the same thread to lock the mutex +multiple times. +* `PH_LOCK_ERRORCHECK` - The mutex is an error-checking mutex. An error-checking mutex checks for deadlock conditions +and return an error if such condition is detected. + +## Return value + +If successful, the `mutexCreateWithAttr()` function shall return zero; otherwise, an error number shall be returned to +indicate the error. + +## Errors + +The `mutexCreateWithAttr()` function shall fail if: + +* `-ENOMEM` - Insufficient memory exists to initialize the mutex. +* `-EINVAL` - The attributes specified in `attr` are invalid. +* `-EFAULT` - The address specified by `h` or `attr` is invalid. + +These functions shall not return an error code of `EINTR`. + +## Tests + +Tested in [test-sys](https://github.com/phoenix-rtos/phoenix-rtos-tests/tree/master/sys) + +## Known bugs + +None + +## See Also + +1. [Standard library functions](../../index.md) +2. [Table of Contents](../../../../index.md)