libc: update cond and mutex functions documentation

JIRA: RTOS-870

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

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
 

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
 

libc/functions/sys/threads/condCreateWithAttr.phrtos.md

@@ -0,0 +1,65 @@
+# condCreateWithAttr
+
+## Synopsis
+
+`#include <sys/threads.h>`
+
+`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)

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
 

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
 

libc/functions/sys/threads/mutexCreate.phrtos.md

@@ -0,0 +1,49 @@
+# mutexCreate
+
+## Synopsis
+
+`#include <sys/threads.h>`
+
+`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)

libc/functions/sys/threads/mutexCreateWithAttr.phrtos.md

@@ -0,0 +1,66 @@
+# mutexCreateWithAttr
+
+## Synopsis
+
+`#include <sys/threads.h>`
+
+`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)