diff --git a/coding.md b/coding.md index 70ec7490..c786436e 100644 --- a/coding.md +++ b/coding.md @@ -95,9 +95,13 @@ The underline character at the start of the function name means that function is parallel threads demands the external synchronization. Good example of such function is the internal function for adding the node to the red-black tree or the internal function for adding the item to the list. -Functions used internally in C file should be declared as static. Functions used only inside the selected subsystem could be named with the name of the module instead of the name of subsystem. Functions exported outside the subsystem must be named with subsystem name only. +Functions used internally in C file should be declared as static. Functions used only inside the selected subsystem +could be named with the name of the module instead of the name of subsystem. Functions exported outside the subsystem +must be named with subsystem name only. -All external (i.e. non-static) symbols (including functions) of a library must be prefixed with a library name. For example, lets say we have library `libfoo` and it's function called `init`. This function must be prefixed with either `foo` or `libfoo` - prefix has to be unique and be consistent within the library: +All external (i.e. non-static) symbols (including functions) of a library must be prefixed with a library name. +For example, lets say we have library `libfoo` and it's function called `init`. This function must be prefixed +with either `foo` or `libfoo` - prefix has to be unique and be consistent within the library: ```c int libfoo_init(void); @@ -107,7 +111,10 @@ All external (i.e. non-static) symbols (including functions) of a library must b int foo_init(void); ``` -If a library consists of submodules (i.e. well separated modules within one library) then second underscore can be used to separate library from submodule and from functionality names. Please note that in general such functions shouldn't be a part of API, but need to adhere to namespace rules as can not be `static` also. Example of this naming scheme: +If a library consists of submodules (i.e. well separated modules within one library) then second underscore +can be used to separate library from submodule and from functionality names. Please note that in general such +functions shouldn't be a part of API, but need to adhere to namespace rules as can not be `static` also. +Example of this naming scheme: ```c int libfoo_bar_start(); @@ -119,13 +126,17 @@ Function should be not longer than 200 lines of code and not shorter than 10 lin ## Variables -Variables should be named with one short words without the underline characters. If one word is not enough for variable name then use camelCase. When defining a variable assign it a value, do not assume that its value is zero. **In the kernel code always initialize global/static variables in runtime.** There's not `.bss` and `.data` initialization in the kernel. +Variables should be named with one short words without the underline characters. If one word is not enough for +variable name then use camelCase. When defining a variable, assign it a value, do not assume that its value is zero. +**In the kernel code always initialize global/static variables in runtime.** +There's not `.bss` and `.data` initialization in the kernel. `const` should be used whenever it is not expected or prohibited for value to change. ## Local variables - kernel -Local variables should be defined before the function code. The stack usage and number of local variables should be minimized. Static local variables are not allowed. +Local variables should be defined before the function code. The stack usage and number of local variables +should be minimized. Static local variables are not allowed. ```c void *_kmalloc_alloc(u8 hdridx, u8 idx) @@ -151,7 +162,8 @@ Local variables should be defined before the function code. The stack usage and ## Local variables - libphoenix, userspace -Scope of local variables should be minimalized, as the stack usage and number of local variables. It is advised to avoid reusing variables for different purposes across the function. Static local variables are allowed. +Scope of local variables should be minimalized, as the stack usage and number of local variables. +It is advised to avoid reusing variables for different purposes across the function. Static local variables are allowed. ```c void countSheeps(herd_t *herd) @@ -172,7 +184,10 @@ Scope of local variables should be minimalized, as the stack usage and number of ## Global variables -In the kernel code global variables should be always initialized in runtime. Global variables should be used only if they're absolutely necessary. Scope should be limited whenever possible by using `static`. If they are used, global variables can only be placed in common structures. The structure should be named after the system module that implements it, followed by `_common`. Example notation is shown below. +In the kernel code global variables should be always initialized in runtime. Global variables should be used only if +they're absolutely necessary. Scope should be limited whenever possible by using `static`. If they are used, global +variables can only be placed in common structures. The structure should be named after the system module that +implements it, followed by `_common`. Example notation is shown below. ```c static struct { @@ -180,24 +195,22 @@ In the kernel code global variables should be always initialized in runtime. Glo } pmap_common; ``` -It is acceptable to omit module name in user space applications (i.e. not in the kernel) and name the structure `common`, only if static is used. +It is acceptable to omit module name in user space applications (i.e. not in the kernel) and name +the structure `common`, only if static is used. ## Operators One space character should be used after and before the following binary and ternary operators: -```c ```c = + - < > * / % | & ^ <= >= == != ? : ``` -``` No space should be used after the following unary operators: ```c & * + - ~ ! ``` -``` The `sizeof` and `typeof`are treated as functions and are to be used in accordance to the following notation: @@ -205,7 +218,6 @@ The `sizeof` and `typeof`are treated as functions and are to be used in accordan sizeof(x) typeof(x) ``` -``` In case of increment `++` and decrement `--` operators following rules should be applied. If they are postfixed, no space should be used before the operator. If they are prefixed, no space should be used after the operator. @@ -239,7 +251,8 @@ be placed after the last line of the conditional instruction in a new line. ## Type definition -New types can only be defined if it is absolutely necessary. if `typedef` is used for a structure/union, structure/union should be left anonymous if possible: +New types can only be defined if it is absolutely necessary. If `typedef` is used for a structure/union, +structure/union should be left anonymous if possible: ```c typedef struct { @@ -262,11 +275,9 @@ and `//` are not to be used at all. A two line comment is presented below. One line comment should look like the following example. -```c ```c /* comment */ ``` -``` All comments should be brief and placed only in essential parts of the code. Comments are not the place to copy parts of the specifications. Nor are they the place to express programmer's novel writing skills. @@ -275,7 +286,8 @@ The use of any kind of documentation generator (e.g. doxygen) is strictly forbid ## Code disabling -Leaving disabled, dead code should be avoided, version control should be relied upon to hold obsolete code. However, should it be necessary, preprocessor should be used: +Leaving disabled, dead code should be avoided, version control should be relied upon to hold obsolete code. +However, should it be necessary, preprocessor should be used: ```c releveantCode(); @@ -287,9 +299,9 @@ Leaving disabled, dead code should be avoided, version control should be relied ## Preprocessor -The header with the `#include` preprocessing directive should be placed after the label. The example header notation is shown below. +The header with the `#include` preprocessing directive should be placed after the label. +The example header notation is shown below. -```c ```c #include "pmap.h" #include "spinlock.h" @@ -297,11 +309,10 @@ The header with the `#include` preprocessing directive should be placed after th #include "console.h" #include "stm32.h ``` -``` It is advised not to use MACROS in the code. -It is not advised to use preprocessor conditionals like `#if` or `if def'. The use of preprocessing conditionals makes +It is not advised to use preprocessor conditionals like `#if` or `if def`. The use of preprocessing conditionals makes it harder to follow the code logic. If it is absolutely necessary to use preprocessing conditionals, they ought to be formatted as the following example. @@ -336,7 +347,8 @@ should be followed by colon and a message body. An example is shown below. ## Coding guidelines -MISRA C:2012 coding guideline standard should be adhered to in all matters not addressed in this guideline (advisory rules are optional). +MISRA C:2012 coding guideline standard should be adhered to in all matters not addressed +in this guideline (advisory rules are optional). ## Miscellaneous @@ -353,4 +365,3 @@ minimalization of the number of lines of code. It also encourages programmers to ## See also 1. [Table of Contents](README.md) - diff --git a/corelibs/libcache.md b/corelibs/libcache.md index 89d63728..954eea9a 100644 --- a/corelibs/libcache.md +++ b/corelibs/libcache.md @@ -221,7 +221,7 @@ maximum offset of the line, a read from multiple lines is performed. At first, a ``` (size of cache line - offset of the first byte) ``` -is read into the buffer. Depending on the size of the requested data, a few next whole cache lines might be read +Is read into the buffer. Depending on the size of the requested data, a few next whole cache lines might be read into the buffer. The address of the first whole line is computed as follows: ```(address of the first byte to be read - offset of the first byte) + size of a cache line``` diff --git a/kernel/hal/README.md b/kernel/hal/README.md index 55d2c5fe..8011652c 100644 --- a/kernel/hal/README.md +++ b/kernel/hal/README.md @@ -81,7 +81,7 @@ space is switched. Timer is the fundamental device for the operating system kernel. It is used for preemptive scheduling and time management. HAL is responsible for the implementation of two timers - a scheduler timer and high precision timer. -On some architectures, they can be based on one hardware device but commonly the are based on two separate devices. +On some architectures, they can be based on one hardware device, but commonly they are based on two separate devices. The interface provided for the upper layer unifies these devices and hides implementation details. HAL implements one function for operating on timers and defines two interrupt numbers respectively for timers used for diff --git a/kernel/proc/README.md b/kernel/proc/README.md index 65496e59..7ed7d977 100644 --- a/kernel/proc/README.md +++ b/kernel/proc/README.md @@ -78,7 +78,7 @@ services. Virtual addressing and private address spaces have also big impact on memory sharing. When a new process is created it can define its private map based on already allocated and named physical memory (see [Memory objects](../vm/objects.md)). This map can be derived from the map of parent process or can be established from -scratch. The smart use of copy-on-write technique allow to allocate the physical memory only for local modifications +scratch. The smart use of copy-on-write technique allows allocating physical memory only for local modifications made by process threads during their execution (see [Memory objects](../vm/objects.md)). ## Process model on architectures not equipped with MMU @@ -140,7 +140,7 @@ used when MMU is available. Some address spaces (e.g. kernel address space) can be attributed with the processor execution mode required to access to them. Using extended processor execution modes (e.g. ARM TrustZone or IA32 rings) the intermediate privilege -modes can be introduced. This technique allows to separate the sensitive parts or program executed within a process +modes can be introduced. This technique allows the separation of sensitive parts or program executed within a process from other parts. Privileged and separated address spaces mapped into many processes can consist shared data and code used for example for emulation or to implement managed execution environments. diff --git a/kernel/vm/page.md b/kernel/vm/page.md index 76c0b347..1883c819 100644 --- a/kernel/vm/page.md +++ b/kernel/vm/page.md @@ -141,7 +141,7 @@ Page deallocation is defined as the process opposite to the page allocation proc ### Sample deallocation Let us assume that the page allocated in the previous section must be released. The first step is to analyze the -neighborhood of the page based on the `pages[]` array. The array is sorted and it is assumed that the +neighborhood of the page based on the `pages[]` array. The array is sorted, and it is assumed that the next page for the released `page_t` is the `page_t` structure, describing the physical page located right after the released page or the page located on higher physical addresses. If the next `page_t` structure describes the neighboring page, and if it is marked as free, the merging process is performed. The next page is removed from diff --git a/libc/functions/f/freopen.part-impl.md b/libc/functions/f/freopen.part-impl.md index a0613469..b20b4e0b 100644 --- a/libc/functions/f/freopen.part-impl.md +++ b/libc/functions/f/freopen.part-impl.md @@ -54,7 +54,7 @@ returned, and `errno` shall be set to indicate the error. The `freopen()` function shall fail if: -* `EACCES` - Search permission is denied on a component of the path prefix, or the file exists and the permissions +* `EACCES` - Search permission is denied on a component of the path prefix, or the file exists, and the permissions specified by _mode_ are denied, or the file does not exist and write permission is denied for the parent directory of the file to be created. diff --git a/libc/functions/q/qsort.part-impl.md b/libc/functions/q/qsort.part-impl.md index e90d3b8f..dd83b924 100644 --- a/libc/functions/q/qsort.part-impl.md +++ b/libc/functions/q/qsort.part-impl.md @@ -16,7 +16,7 @@ IEEE Std 1003.1-2017 The `qsort()` function shall sort an array of _nel_ objects, the initial element of which is pointed to by _base_. The size of each object, in bytes, is specified by the _width_ argument. If the _nel_ argument has the value zero, -the comparison function pointed to by _compar_ shall not be called and no rearrangement shall take place. +the comparison function pointed to by _compar_ shall not be called, and no rearrangement shall take place. The application shall ensure that the comparison function pointed to by _compar_ does not alter the contents of the array. diff --git a/libc/functions/r/read.part-impl.md b/libc/functions/r/read.part-impl.md index cf8d9d74..940c66b6 100644 --- a/libc/functions/r/read.part-impl.md +++ b/libc/functions/r/read.part-impl.md @@ -137,7 +137,7 @@ read. Otherwise, the functions shall return `-1` and set errno to indicate the e These functions shall fail if: -* `EAGAIN` - The file is neither a pipe, nor a `FIFO`, nor a socket, the `O_NONBLOCK` flag is set for the file +* `EAGAIN` - The file is neither a pipe nor a `FIFO`, nor a socket, the `O_NONBLOCK` flag is set for the file descriptor, and the thread would be delayed in the read operation. * `EBADF` - The fildes argument is not a valid file descriptor open for reading. diff --git a/libc/functions/s/strlen.part-impl.md b/libc/functions/s/strlen.part-impl.md index 45eb679f..eea737ef 100644 --- a/libc/functions/s/strlen.part-impl.md +++ b/libc/functions/s/strlen.part-impl.md @@ -19,7 +19,7 @@ IEEE Std 1003.1-2017 The `strlen()` function shall compute the number of bytes in the string to which _s_ points, not including the terminating `NUL` character. The -`strnlen()` function shall compute the smaller of the number of bytes in the array to which _s_ points, not including +`strnlen()` function shall compute the smallest of the number of bytes in the array to which _s_ points, not including any terminating `NUL` character, or the value of the _maxlen_ argument. The `strnlen()` function shall never examine more than _maxlen_ bytes of the array pointed to by _s_. diff --git a/libc/functions/u/unlink.part-impl.md b/libc/functions/u/unlink.part-impl.md index 6dbfdfd0..9ca4898c 100644 --- a/libc/functions/u/unlink.part-impl.md +++ b/libc/functions/u/unlink.part-impl.md @@ -52,7 +52,7 @@ Values for _flag_ are constructed by a bitwise-inclusive OR of flags from the fo * `AT_REMOVEDIR` - remove the directory entry specified by _fd_ and _path_ as a directory, not a normal file. If `unlinkat()` is passed the special value `AT_FDCWD` in the _fd_ parameter, the current working directory shall be -used and the behavior shall be identical to a call to `unlink()` or `rmdir()` respectively, depending on +used, and the behavior shall be identical to a call to `unlink()` or `rmdir()` respectively, depending on whether the `AT_REMOVEDIR` bit is set in flag. diff --git a/libc/functions/w/write.part-impl.md b/libc/functions/w/write.part-impl.md index ab472e43..856f4212 100644 --- a/libc/functions/w/write.part-impl.md +++ b/libc/functions/w/write.part-impl.md @@ -157,7 +157,7 @@ indicate the error. The `write()` function shall fail if: -* `EAGAIN` - The file is neither a pipe, nor a `FIFO`, nor a socket, the `O_NONBLOCK` flag is set for the file +* `EAGAIN` - The file is neither a pipe nor a `FIFO`, nor a socket, the `O_NONBLOCK` flag is set for the file descriptor, and the thread would be delayed in the `write()` operation. * `EBADF` - The _fildes_ argument is not a valid file descriptor open for writing. diff --git a/quickstart/README.md b/quickstart/README.md index b959b909..49acd1a8 100644 --- a/quickstart/README.md +++ b/quickstart/README.md @@ -1,6 +1,6 @@ # Running system on targets -This chapter presents how to run Phoenix-RTOS on supported targets. It is assumed that `phoenix-rtos-project` is built +This chapter presents how to run Phoenix-RTOS on supported targets. It is assumed that `phoenix-rtos-project` is built, and building artifacts are available in the `_boot` directory. The building process has been described in [phoenix-rtos-doc/building](../building/README.md). diff --git a/quickstart/riscv64-generic-qemu.md b/quickstart/riscv64-generic-qemu.md index 13e484ab..b9ea5bfa 100644 --- a/quickstart/riscv64-generic-qemu.md +++ b/quickstart/riscv64-generic-qemu.md @@ -42,7 +42,7 @@ Firstly, you need to install QEMU emulator.
- How to get QEMU (Mac OS) + How to get QEMU (macOS) - Install the required packages diff --git a/quickstart/riscv64-generic-spike.md b/quickstart/riscv64-generic-spike.md index 986476a0..8177fc5f 100644 --- a/quickstart/riscv64-generic-spike.md +++ b/quickstart/riscv64-generic-spike.md @@ -86,7 +86,7 @@ Just like before, you first need to install the emulator.
- How to get QEMU (Mac OS) + How to get QEMU (macOS) - Install the required packages diff --git a/tests/README.md b/tests/README.md index c4c57971..de2f30bf 100644 --- a/tests/README.md +++ b/tests/README.md @@ -478,12 +478,12 @@ Now let's go through the tests and try to understand the final configuration: - The `arg_zero` test specifies that the `test-hello-arg` executable should be executed without any arguments (`execute: test-hello-arg`). We provide the `hello_arg_harness.py` as the harness. In the `kwargs` section, we set -`argc` to `0`. This dictionary is passed later to the harness as `kwargs` parameter. Additional, we exclude the +`argc` to `0`. This dictionary is passed later to the harness as `kwargs` parameter. Additionally, we exclude the `armv7a9-zynq7000-qemu` target for this specific test. As a result, it will be run on the `ia32-generic-qemu` and `host-generic-pc` targets. - The `arg_two` test specifies that the `test-hello-arg` should be executed with two arguments: `arg1` and `arg2` (`execute: test-hello-arg arg1 arg2`). We provide the `hello_arg_harness.py` as the harness. In the `kwargs` section, we -set `argc` to `2`. Additional, we specify that this test should only run on the `ia32-generic-qemu` target. +set `argc` to `2`. Additionally, we specify that this test should only run on the `ia32-generic-qemu` target. - The `arg_hello` test specifies that the `test-hello-arg` executable should be executed with the argument `world`. We provide the `hello_arg_harness.py` as the harness. In the `kwargs` section, we set `input` to `Adios!`. This word will be used as the input to the `test-hello-arg`. We also set `nightly` to false for this specific test. Thanks to that, the