diff --git a/coding/Makefile b/coding/Makefile new file mode 100644 index 00000000..f1611b43 --- /dev/null +++ b/coding/Makefile @@ -0,0 +1,23 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +# To make the version_management module visible while building the documentation +export PYTHONPATH := $(SOURCEDIR):$(PYTHONPATH) diff --git a/coding/conf.py b/coding/conf.py new file mode 100644 index 00000000..b60a9f67 --- /dev/null +++ b/coding/conf.py @@ -0,0 +1,59 @@ +# TemplateConfiguration file for the Sphinx documentation builder. + +from datetime import datetime +from phoenixsystems.docsresources import latex_default + +project = "Phoenix RTOS DO-178C" +copyright = "2025, Phoenix Systems" +author = "Phoenix Systems" + +extensions = ["myst_parser", "sphinx_copybutton"] +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', +} + +exclude_patterns = ["README", "_build", "Thumbs.db", ".DS_Store", "_venv"] + +latexpdf_title = "Software Code Standards" +latexpdf_author = "Bartłomiej Paczek" +latexpdf_reviewer = 'Kamil Ber' +latexpdf_date = datetime.today().strftime('%d-%m-%Y') +latexpdf_version = "Rev. 1.0" +latexpdf_filename = "PHOENIX-RTOS-DO178-STD-0003-Software_Code_Standards" +latexpdf_dochistory = r''' + \begin{table}[h!] + \centering + \color{ps-darkblue} + \begin{tabular}{p{1cm}|p{8cm}|p{3cm}|p{2cm}} + \hline + \textbf{Rev.} & \textbf{Description} & \textbf{Elaborated by} & \textbf{Date} \\ + \hline + 0.1 & Initial draft & B. Paczek & 2025-12-01 \\ + \hline + \end{tabular} + \end{table} + ''' + +latex_documents = [ + ("index", f"{latexpdf_filename}.tex", latexpdf_title, author, "howto", False), +] + +latex_engine = latex_default["engine"] +latex_table_style = latex_default["table_style"] +latex_additional_files = latex_default["additional_files"] + +# overwrite the maketitle element to use the variables from the current file +modified_elements = latex_default["elements"].copy() +modified_elements["maketitle"] = fr''' + \newcommand{{\doctitle}}{{{latexpdf_title}}} + \newcommand{{\docauthor}}{{{latexpdf_author}}} + \newcommand{{\docreviewer}}{{{latexpdf_reviewer}}} + \newcommand{{\docversion}}{{{latexpdf_version}}} + \newcommand{{\docdate}}{{{latexpdf_date}}} + \newcommand{{\dochistory}}{{{latexpdf_dochistory}}} + + ''' + modified_elements["maketitle"] + +modified_elements["preamble"] = modified_elements["preamble"] + r'''\setcounter{secnumdepth}{1}''' +latex_elements = modified_elements diff --git a/coding/index.md b/coding/index.md index 474ed459..51428fbf 100644 --- a/coding/index.md +++ b/coding/index.md @@ -1,14 +1,49 @@ -# Coding convention +# Software Code Standards -The chapter presents coding convention used in the implementation files of Phoenix-RTOS. +## Introduction + +This document defines the Software Code Standards to be followed when writing Phoenix-RTOS source code. +It is organized into sections that group coding rules, recommendations by topic. +Rules identify quality considerations that must always be followed unless an exception is approved by +the Technical Coordinator and Quality Assurance Engineer, this has to be noted in the Source code peer-review. + +Recommendations are practices which should be followed. Known exceptions have to be noted in the software coding +peer review record. + +The identifiers referenced in this standard are: + +- `PS-CODE-RULE-XXX` for rules, which are formulated using `shall` what indicates mandatory action; +- `PS-CODE-REC-XXX` for recommendations, which are formulated using `should`; + +### Note + +Rule numbering does not have to be sequential and should not be changed once assigned. +If a new rule is added in any section, it should be assigned the next available number after the highest existing rule +number. ## C language standard -In general code should be compliant with C99 (without GNU extensions) standard. +### PS-CODE-RULE-001 + +The code shall be compliant with C99 (without GNU extensions) standard. + +## MISRA C 2023 (2012) + +### PS-CODE-RULE-002 + +The code shall be compliant with the set of MISRA C 2023 (2012) defined in +[Phoenix RTOS MISRA C Profile](./misracprofile.rst) with justified local rule exemptions. + +### PS-CODE-RULE-003 + +Any local deviations from the [Phoenix RTOS MISRA C Profile](./misracprofile.rst) rules +shall be justified within the code. ## File label -Each operating system source file is marked with label with the following structure: +### PS-CODE-REC-004 + +Each operating system source file should be marked with label with the following structure: ```c /* @@ -25,9 +60,27 @@ Each operating system source file is marked with label with the following struct */ ``` -Example of a file that is a part of the Phoenix-RTOS kernel: +Main label blocks should be separated by an empty line. + +The consecutive label blocks, in that order, should: + +- inform that file is the part of Phoenix-RTOS operating system +- provide the information about the operating system +- describe the file functionality +- present copyright notices for the file, with the newest copyrights at the top and authors sorted +according to the importance of their contribution +- provide license information with %LICENSE% macro + +#### Example + +In this example, the file belongs to operating system kernel. The file implements `pmap` interface - +the hardware dependent part of memory management subsystem for managing the MMU or MPU (part of HAL). +The file was developed in years 2014-2015 and in the earlier period of 2005-2006. It has three +authors sorted according to the importance of their contribution. All names are presented. +The %LICENSE% macro is used to inject the license conditions. ```c + /* * Phoenix-RTOS * @@ -43,26 +96,27 @@ Example of a file that is a part of the Phoenix-RTOS kernel: */ ``` -Main label blocks are separated with empty line. The first label block informs that file is the part of Phoenix-RTOS -operating system. In next block the information about the operating system module is provided. In this example, the file -belongs to operating system kernel. Third label block describes the file functionality. In presented example label, the -file implements `pmap` interface - the hardware dependent part of memory management subsystem for managing the MMU or -MPU (part of HAL). Fourth label block presents copyright notices and authors of the file. Newest copyrights are located -on the top. Copyrights are associated with dates informing about the development periods separated with commas. In the -example label the file was developed in years 2014-2015 and in the earlier period of 2005-2006. Presented file has three -authors sorted according to the importance of their contribution. All names are presented. Next block contains the -information that file belongs to the operating system project. The %LICENSE% macro is used to inject the license -conditions. +## Allowed characters + +### PS-CODE-REC-007 -Labels in each file should be constructed according to presented rules. Modification of these rules is not allowed. +Only characters from the standard ASCII range (0x20–0x7E) should be used in source files. ## Indentation -Code indentation is based on tabulator. It is not allowed to make an indentation with space character. The source code +### PS-CODE-REC-008 + +The `Tab` character should be used as code indentation. + +#### Note + +It is not allowed to make an indentation with space character. The source code used for development tests (e.g. printf debug) should be entered without indentation. The following code presents correctly formatted code with one line (`lib_printf`) entered for debug purposes. The inserted line should be removed in the final code. +#### Example + ```c int main(void) { @@ -73,7 +127,7 @@ int main(void) _proc_init(&main_common.kmap, &main_common.kernel); _syscalls_init(); - lib_printf("DEBUG: starting first process...\n"); +lib_printf("DEBUG: starting first process...\n"); /* Start init process */ proc_start(main_initthr, NULL, (const char *)"init"); @@ -88,34 +142,79 @@ int main(void) ## Source files -Separate source files should be created for each operating system module. Source files are grouped in directories which -names correspond to the names of subsystems. +### PS-CODE-REC-009 + +Separate source files should be created for each operating system module. + +### PS-CODE-REC-010 + +Source files should be grouped in directories whose names correspond to the names of subsystems. + +## Functions and modules + +### PS-CODE-REC-011 + +Functions should be short and not too complex in terms of logic - +not shorter than 10 and not longer than 200 lines of code. -## Functions +### PS-CODE-REC-012 -Functions should be short and not too complex in terms of logic. The function should do one thing only. Functions should -be separated with two newline characters. +The function should do one thing only. -## Function names +### PS-CODE-REC-013 -Function names should be created according to the following schema `[_]_` where `` -is the name of subsystem or file to which function belongs and `` is the brief sentence explaining the -implemented functionality. The subsystem name should be a one word without the underline characters. The functionality -could be expressed using many words but without the underlines. In such case camelCase should be used. +Functions should be separated with two `newline` characters. -For example function for kernel space memory allocation could be named `vm_kmalloc()`. Function for creating a new -thread could be named `proc_threadCreate()`. +### PS-CODE-REC-014 -The underline character at the start of the function name means that function is not synchronized and its usage by two -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. +Function names should be created according to the following schema `[_]_` where: -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. +- `` is the name of subsystem or file in which function belongs +- `` is a brief sentence explaining the implemented functionality. -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 +#### Note + +Functions used only inside the selected subsystem could be named with the name of the module +instead of the name of subsystem. + +### PS-CODE-REC-016 + +The subsystem name should consist of one word. + +### PS-CODE-REC-017 + +The subsystem name should not contain the `underscore` characters. + +### PS-CODE-REC-018 + +The subsystem name should be written in the camelCase format if more than one word is used. + +#### Example + +The function for kernel space memory allocation could be named `vm_kmalloc()`. +The function for creating a new thread could be named `proc_threadCreate()`. + +#### Note + +An underscore character at the start of the function name indicates that the function is not synchronized, and its usage +by two parallel threads requires external synchronization. A good example of such function is the internal function +for adding a node to a red-black tree or the internal function for adding an item to a list. + +### PS-CODE-REC-019 + +Functions used only internally in the file, where they are defined, should be declared as `static`. + +### PS-CODE-REC-020 + +Functions exported outside the subsystem should be named with the subsystem name only. + +### PS-CODE-REC-021 + +All external (i.e. non-static) symbols (including functions) of a library should be prefixed with the library name. + +#### Example + +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 @@ -126,31 +225,106 @@ int libfoo_init(void); int foo_init(void); ``` +### PS-CODE-REC-022 + 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: +to separate library from submodule and from functionality names. + +#### Note + +Please note that in general such functions shouldn't be a part of API, but need to adhere to namespace rules +as they can not also be `static`. + +#### Example ```c int libfoo_bar_start(); ``` -## Function length +### PS-CODE-REC-023 + +*Rule derived from MISRA C.* + +When function handler is an argument of a function it should be specified with explicit arguments. -Function should be not longer than 200 lines of code and not shorter than 10 lines of code. +#### Example + +Incorrect: + +```c +int hal_cpuCreateContext(cpu_context_t **nctx, void *start, void *kstack, size_t kstacksz, void *ustack, void *arg, hal_tls_t *tls) +``` + +Correct: + +```c +int hal_cpuCreateContext(cpu_context_t **nctx, void (*start)(void *harg), void *kstack, size_t kstacksz, void *ustack, void *arg, hal_tls_t *tls) +``` + +### PS-CODE-REC-025 + +*Recommendation derived from MISRA C.* + +If the function output is not used it should be cast to `void`. + +#### Example + +```c +(void)lib_vprintf(fmt, ap); +``` + +### PS-CODE-REC-026 + +*Recommendation derived from MISRA C.* + +Function types should be `typedef`-ed with `Fn_t` suffix to make them distinguishable from non-function types, +e.g. `startFn_t`, `sighandlerFn_t` + +### PS-CODE-REC-027 + +*Recommendation derived from MISRA C.* + +`extern` keyword should not be used in function prototypes as it’s the default. ## 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. +### PS-CODE-REC-028 + +Variables should be named with one short word without the underscore characters. + +### PS-CODE-REC-029 + +For variable names longer than one word, the camelCase format should be used. +### PS-CODE-REC-030 + +When defining a variable, it should be assigned with a value (do not assume that its value is zero). + +#### Note + +**In the kernel code always initialize global/static variables at runtime.** There's not `.bss` and +`.data` initialization in the kernel. + +### PS-CODE-REC-031 + +**In the kernel code always initialize global/static variables at runtime.** There's no `.bss` and `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. +### PS-CODE-REC-032 + +Local variables should be defined before the function code in the kernel. + +### PS-CODE-REC-033 + +The stack usage and number of local variables should be minimized in the kernel. + +### PS-CODE-REC-034 + +Static local variables should not be used in the kernel. + +#### Example ```c void *_kmalloc_alloc(u8 hdridx, u8 idx) @@ -176,8 +350,20 @@ void *_kmalloc_alloc(u8 hdridx, u8 idx) ## 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. +### PS-CODE-REC-035 + +Scope of local variables should be minimized in libphoenix and userspace (as the stack usage and +number of local variables). + +### PS-CODE-REC-036 + +The variables should not be used for different purposes across the function. + +### PS-CODE-REC-037 + +Static local variables should be used in only libphoenix and userspace. + +#### Example ```c void countSheeps(herd_t *herd) @@ -198,10 +384,27 @@ void countSheeps(herd_t *herd) ## 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. +### PS-CODE-REC-038 + +In the kernel code global variables should be always initialized at runtime. + +### PS-CODE-REC-039 + +Global variables should be used only if they're absolutely necessary. + +### PS-CODE-REC-040 + +The scope of global variables should be limited whenever possible by using `static`. + +### PS-CODE-REC-041 + +Global variables should only be placed in common structures. + +### PS-CODE-REC-042 + +The structure should be named after the system module that implements it, followed by `_common`. + +#### Example ```c static struct { @@ -209,36 +412,66 @@ static struct { } 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. +#### Note + +The module name could be omitted in user space applications (i.e. not in the kernel) and name the structure `common`, +only if static is used. ## Operators +### PS-CODE-REC-044 + One space character should be used after and before the following binary and ternary operators: ```c = + - < > * / % | & ^ <= >= == != ? : ``` +### PS-CODE-REC-045 + 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: +### PS-CODE-REC-046 + +The `sizeof` and `typeof` operators should be treated as functions and are to be used in accordance +to the following notation: ```c 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. +### PS-CODE-REC-047 + +If the increment `++` or decrement `--` operators are postfixed, no space should be used before the operator. + +### PS-CODE-REC-048 + +If the increment `++` or decrement `--` operators are prefixed, no space should be used after the operator. ## Conditional expressions -Notation of conditional expression is presented below. +### PS-CODE-REC-049 + +A space should be used after a keyword of the conditional instruction. + +### PS-CODE-REC-050 + +Opening and closing braces should always be used. + +### PS-CODE-REC-051 + +The opening brace should be put in the same line as the keyword of the conditional instruction. + +### PS-CODE-REC-052 + +The closing brace should be placed after the last line of the conditional instruction in a new line. + +#### Example ```c if (expr) { @@ -259,14 +492,81 @@ else { } ``` -A space should be used after a keyword of the conditional instruction. Opening and closing braces should be always used. -The opening brace should be put in the same line as the keyword of the conditional instruction. The closing brace should -be placed after the last line of the conditional instruction in a new line. +### PS-CODE-REC-053 + +*Recommendation derived from MISRA C.* + +Only values of `bool` type should be used as condition input. + +#### Example + +Incorrect: + +```c +unsigned int len = 0; + +if (!len) + +``` + +Correct: + +```c +unsigned int len = 0; + +if (len == 0U) +``` + +## Comparison output + +### PS-CODE-REC-054 + +*Recommendation derived from MISRA C.* + +An outcome of comparison operation should not be used as an integer value. + +#### Example + +```c +unsigned int a = 1U, b = 0U, c; +``` + +Incorrect: + +```c +c = a == b; +``` + +Correct: + +```c +c = (a == b) ? 1U : 0U; +``` + +## Type specifiers and definitions + +### PS-CODE-REC-55 + +The type specifiers from the list bellow should be used: + +- `char` +- `unsigned char` +- `int` +- `unsigned int` +- `long` +- `unsigned long` +- `long long` +- `unsigned long long` + +### PS-CODE-REC-056 -## Type definition +New types should only be defined if it is absolutely necessary. -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: +### PS-CODE-REC-057 + +If `typedef` is used for a structure/union, structure/union should be left anonymous if possible: + +#### Example ```c typedef struct { @@ -275,10 +575,37 @@ typedef struct { } foobar_t; ``` +### PS-CODE-REC-058 + +*Recommendation derived from MISRA C.* + +Types of defined length should be used over default C types. + +#### Note + +That is especially valid for static variables used to operate on processor registers. + +#### Example + +Not recommended: +`unsigned char` + +Recommended: +`uint8_t, u8, __u8` + ## Comments -When the C programming language is used only C language comments should be used. It means that only `/* */` are allowed -and `//` are not to be used at all. A two line comment is presented below. +### PS-CODE-REC-059 + +When the C programming language is used only C language comments should be used: `/* */`. + +### PS-CODE-REC-060 + +`//` comments should not to be used. + +#### Example + +Multi line comment: ```c /* @@ -287,21 +614,41 @@ and `//` are not to be used at all. A two line comment is presented below. */ ``` -One line comment should look like the following example. +One line comment: ```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. +### PS-CODE-REC-061 + +Comments should be brief and placed only in essential parts of the code. + +### PS-CODE-REC-062 + +Comments should not contain copied parts of specification. + +#### Note + +Comments are not the place to express programmer's novel writing skills. + +### PS-CODE-REC-063 -The use of any kind of documentation generator (e.g. Doxygen) is strictly forbidden. +Documentation generators (e.g. Doxygen) should not be used. ## 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: +### PS-CODE-REC-064 + +Disabled or dead code should not be placed in the code. + +#### Note + +Version control should be relied upon to hold obsolete code. + +### PS-CODE-REC-065 + +If disabled or dead code is present (it was necessary), preprocessor should be used accordingly: ```c releveantCode(); @@ -313,8 +660,11 @@ releveantCode(); ## Preprocessor -The header with the `#include` preprocessing directive should be placed after the label. The example header notation is -shown below. +### PS-CODE-REC-066 + +The header with the `#include` preprocessing directive should be placed after the label. + +#### Example ```c #include "pmap.h" @@ -324,11 +674,22 @@ shown below. #include "stm32.h" ``` -It is advised not to use MACROS in the code. +### PS-CODE-REC-067 -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. +MACROS should not be used in the code. + +### PS-CODE-REC-068 + +The preprocessor conditionals like: `#if`, `#ifdef` or `#ifndef` should not be used in the code. + +#### Note + +The use of preprocessing conditionals makes it harder to follow the code logic and can be used only +if it is absolutely necessary. + +### PS-CODE-REC-069 + +Preprocessing conditionals should be formatted as the following example: ```c #ifndef NOMMU @@ -351,26 +712,100 @@ formatted as the following example. ## Operating system messages -Following notation for operating system messages should be applied. Message should start from a subsystem name, which -should be followed by colon and a message body. An example is shown below. +### PS-CODE-REC-070 + +Operating system messages should consist of, in that order: + +- a subsystem name +- a colon +- a message body +- a newline character + +#### Example ```c lib_printf("main: Starting syspage programs (%d) and init\n", syspage->progssz); ``` -## Coding guidelines +## Literals + +### PS-CODE-REC-071 + +The numeric literals suffixes should be written with capital letters. + +#### Example + +```c +#define SIZE_PAGE 0x200U +``` + +### PS-CODE-REC-072 + +*Recommendation derived from MISRA C.* + +When shifting unsigned constants by more than 7 bits the `UL` suffix should be used. + +#### Explanation + +It’s not sufficient to mark them with `U` as MISRA classifies `U` constants, despite the C standard implications, as +8-bit essential type (see the “To assist in understanding” example in Rule 12.2 rationale, D.3 and D.7.4). + +#### Exception + +Per exception 1 to rule 10.3 it is allowed to assign simple constants to unsigned variables without the `U`/`UL` suffix, +like `size_t i = 0` provided that the constant fits into the variable type. Use of this exception is permitted as long +as it is stylistically consistent. + +### PS-CODE-REC-073 + +The numeric hexadecimal literals should be written with small letters. + +#### Example + +```c +#define SIZE_PAGE 0xffU +``` + +### PS-CODE-REC-074 + +*Recommendation derived from MISRA C.* + +`\0` literal should be used to define a variable of `char` type with a value of 0. + +## Pointers -MISRA C:2012 coding guideline standard should be adhered to in all matters not addressed in this guideline (advisory -rules are optional). +### PS-CODE-REC-075 + +`NULL` should be used as default value for empty pointers. ## Miscellaneous -The `goto` statement shall not be used. The main goal of this prohibition is the minimalization of the spaghetti code +### PS-CODE-REC-076 + +The `goto` statement should not be used. + +#### Note + +The main goal of this prohibition is the minimization of the spaghetti code generation and the prevention of the linear programming usage. To better understand our position please read the famous Dijkstra article. -In our opinion usage of `goto` increases the chaos in the source code and absolutely brings no value like -minimalization of the number of lines of code. It also encourages programmers to poor code structurization. +In our opinion, the usage of goto increases chaos in the source code and +offers no value, such as minimizing the number of lines of code. +It also encourages programmers to poor code structurization. + +### PS-CODE-REC-077 + +All user input should be sanitized - consider this especially in cases such as syscall implementations: + e.g. check if flags are in the required range (example: `(var & FLAG_MASK_ALL) == 0`). + +## Appendixes + +```{toctree} +:maxdepth: 1 +misracprofile.rst + +``` diff --git a/coding/misracprofile.rst b/coding/misracprofile.rst new file mode 100644 index 00000000..12e29140 --- /dev/null +++ b/coding/misracprofile.rst @@ -0,0 +1,243 @@ +Appendix 1 - Phoenix MISRA C Profile +==================================== + +The following table lists the directives and rules of the MISRA C:2023 standard +and their status within the Phoenix MISRA C Profile. + +Column Descriptions +------------------- + +- **ID:** The official directive or rule identifier from the MISRA C:2023 standard. +- **Category:** The rule's category as defined by the standard. By default, the Phoenix MISRA C Profile + applies all ``Required`` and ``Mandatory`` rules. +- **Applicability Change:** Shows any deviation from the standard's default applicability. + ``Advisory`` rules may be ``ENABLED``, while ``Required`` or ``Mandatory`` rules may be ``DISABLED``. + ``NO`` indicates no change. +- **Applied:** A ``YES``/``NO`` indicator of whether the rule is active in the Phoenix MISRA C Profile. +- **Justification:** Provides the justification for enabling or disabling a rule. + +.. csv-table:: Phoenix MISRA C Profile + :header: "ID", "Category", "Applicability Change", "Applied", "Justification" + :widths: 15, 15, 15, 15, 40 + + "Dir 1.1", "Required", "NO", "**YES**", "" + "Dir 2.1", "Required", "NO", "**YES**", "" + "Dir 3.1", "Required", "NO", "**YES**", "" + "Dir 4.1", "Required", "NO", "**YES**", "" + "Dir 4.2", "Advisory", "NO", "NO", "" + "Dir 4.3", "Required", "NO", "**YES**", "" + "Dir 4.4", "Advisory", "NO", "NO", "" + "Dir 4.5", "Advisory", "NO", "NO", "" + "Dir 4.6", "Advisory", "NO", "NO", "" + "Dir 4.7", "Required", "NO", "**YES**", "" + "Dir 4.8", "Advisory", "NO", "NO", "" + "Dir 4.9", "Advisory", "NO", "NO", "" + "Dir 4.10", "Required", "NO", "**YES**", "" + "Dir 4.11", "Required", "NO", "**YES**", "" + "Dir 4.12", "Required", "NO", "**YES**", "" + "Dir 4.13", "Advisory", "NO", "NO", "" + "Dir 4.14", "Required", "NO", "**YES**", "" + "Dir 4.15", "Required", "NO", "**YES**", "" + "Dir 5.1", "Required", "NO", "**YES**", "" + "Dir 5.2", "Required", "NO", "**YES**", "" + "Dir 5.3", "Required", "NO", "**YES**", "" + "Rule 1.1", "Required", "NO", "**YES**", "" + "Rule 1.2", "Advisory", "NO", "NO", "" + "Rule 1.3", "Required", "NO", "**YES**", "" + "Rule 1.4", "Required", "NO", "**YES**", "" + "Rule 1.5", "Required", "NO", "**YES**", "" + "Rule 2.1", "Required", "NO", "**YES**", "" + "Rule 2.2", "Required", "NO", "**YES**", "" + "Rule 2.3", "Advisory", "NO", "NO", "" + "Rule 2.4", "Advisory", "NO", "NO", "" + "Rule 2.5", "Advisory", "NO", "NO", "" + "Rule 2.6", "Advisory", "NO", "NO", "" + "Rule 2.7", "Advisory", "NO", "NO", "" + "Rule 2.8", "Advisory", "NO", "NO", "" + "Rule 3.1", "Required", "NO", "**YES**", "" + "Rule 3.2", "Required", "NO", "**YES**", "" + "Rule 4.1", "Required", "NO", "**YES**", "" + "Rule 4.2", "Advisory", "NO", "NO", "" + "Rule 5.1", "Required", "NO", "**YES**", "" + "Rule 5.2", "Required", "NO", "**YES**", "" + "Rule 5.3", "Required", "NO", "**YES**", "" + "Rule 5.4", "Required", "NO", "**YES**", "" + "Rule 5.5", "Required", "NO", "**YES**", "" + "Rule 5.6", "Required", "NO", "**YES**", "" + "Rule 5.7", "Required", "NO", "**YES**", "" + "Rule 5.8", "Required", "NO", "**YES**", "" + "Rule 5.9", "Advisory", "NO", "NO", "" + "Rule 6.1", "Required", "NO", "**YES**", "" + "Rule 6.2", "Required", "NO", "**YES**", "" + "Rule 6.3", "Required", "NO", "**YES**", "" + "Rule 7.1", "Required", "NO", "**YES**", "" + "Rule 7.2", "Required", "NO", "**YES**", "" + "Rule 7.3", "Required", "NO", "**YES**", "" + "Rule 7.4", "Required", "NO", "**YES**", "" + "Rule 7.5", "Mandatory", "NO", "**YES**", "" + "Rule 7.6", "Required", "NO", "**YES**", "" + "Rule 8.1", "Required", "NO", "**YES**", "" + "Rule 8.2", "Required", "NO", "**YES**", "" + "Rule 8.3", "Required", "NO", "**YES**", "" + "Rule 8.4", "Required", "NO", "**YES**", "" + "Rule 8.5", "Required", "NO", "**YES**", "" + "Rule 8.6", "Required", "NO", "**YES**", "" + "Rule 8.7", "Advisory", "NO", "NO", "" + "Rule 8.8", "Required", "NO", "**YES**", "" + "Rule 8.9", "Advisory", "NO", "NO", "" + "Rule 8.10", "Required", "NO", "**YES**", "" + "Rule 8.11", "Advisory", "NO", "NO", "" + "Rule 8.12", "Required", "NO", "**YES**", "" + "Rule 8.13", "Advisory", "NO", "NO", "" + "Rule 8.14", "Required", "NO", "**YES**", "" + "Rule 8.15", "Required", "NO", "**YES**", "" + "Rule 8.16", "Advisory", "NO", "NO", "" + "Rule 8.17", "Advisory", "NO", "NO", "" + "Rule 9.1", "Mandatory", "NO", "**YES**", "" + "Rule 9.2", "Required", "NO", "**YES**", "" + "Rule 9.3", "Required", "NO", "**YES**", "" + "Rule 9.4", "Required", "NO", "**YES**", "" + "Rule 9.5", "Required", "NO", "**YES**", "" + "Rule 9.6", "Required", "NO", "**YES**", "" + "Rule 9.7", "Mandatory", "NO", "**YES**", "" + "Rule 10.1", "Required", "NO", "**YES**", "" + "Rule 10.2", "Required", "NO", "**YES**", "" + "Rule 10.3", "Required", "NO", "**YES**", "" + "Rule 10.4", "Required", "NO", "**YES**", "" + "Rule 10.5", "Advisory", "NO", "NO", "" + "Rule 10.6", "Required", "NO", "**YES**", "" + "Rule 10.7", "Required", "NO", "**YES**", "" + "Rule 10.8", "Required", "NO", "**YES**", "" + "Rule 11.1", "Required", "NO", "**YES**", "" + "Rule 11.2", "Required", "NO", "**YES**", "" + "Rule 11.3", "Required", "DISABLED", "NO", "This rule is not applicable for the Phoenix-RTOS kernel source code, because casting between different types of pointers can not be avoided in the operating system implementation." + "Rule 11.4", "Advisory", "NO", "NO", "" + "Rule 11.5", "Advisory", "NO", "NO", "" + "Rule 11.6", "Required", "DISABLED", "NO", "This rule is not applicable for the Phoenix-RTOS kernel source code, because casting between pointer to void and an arithmetic type can not be avoided inn the operating system implementation." + "Rule 11.7", "Required", "NO", "**YES**", "" + "Rule 11.8", "Required", "NO", "**YES**", "" + "Rule 11.9", "Required", "NO", "**YES**", "" + "Rule 11.10", "Required", "NO", "**YES**", "" + "Rule 12.1", "Advisory", "NO", "NO", "" + "Rule 12.2", "Required", "NO", "**YES**", "" + "Rule 12.3", "Advisory", "NO", "NO", "" + "Rule 12.4", "Advisory", "NO", "NO", "" + "Rule 12.5", "Mandatory", "NO", "**YES**", "" + "Rule 12.6", "Required", "NO", "**YES**", "" + "Rule 13.1", "Required", "NO", "**YES**", "" + "Rule 13.2", "Required", "NO", "**YES**", "" + "Rule 13.3", "Advisory", "NO", "NO", "" + "Rule 13.4", "Advisory", "NO", "NO", "" + "Rule 13.5", "Required", "NO", "**YES**", "" + "Rule 13.6", "Required", "NO", "**YES**", "" + "Rule 14.1", "Required", "NO", "**YES**", "" + "Rule 14.2", "Required", "NO", "**YES**", "" + "Rule 14.3", "Required", "NO", "**YES**", "" + "Rule 14.4", "Required", "NO", "**YES**", "" + "Rule 15.1", "Advisory", "NO", "NO", "" + "Rule 15.2", "Required", "NO", "**YES**", "" + "Rule 15.3", "Required", "NO", "**YES**", "" + "Rule 15.4", "Advisory", "NO", "NO", "" + "Rule 15.5", "Advisory", "NO", "NO", "" + "Rule 15.6", "Required", "NO", "**YES**", "" + "Rule 15.7", "Required", "NO", "**YES**", "" + "Rule 16.1", "Required", "NO", "**YES**", "" + "Rule 16.2", "Required", "NO", "**YES**", "" + "Rule 16.3", "Required", "NO", "**YES**", "" + "Rule 16.4", "Required", "NO", "**YES**", "" + "Rule 16.5", "Required", "NO", "**YES**", "" + "Rule 16.6", "Required", "NO", "**YES**", "" + "Rule 16.7", "Required", "NO", "**YES**", "" + "Rule 17.1", "Required", "NO", "**YES**", "" + "Rule 17.2", "Required", "NO", "**YES**", "" + "Rule 17.3", "Mandatory", "NO", "**YES**", "" + "Rule 17.4", "Mandatory", "NO", "**YES**", "" + "Rule 17.5", "Required", "NO", "**YES**", "" + "Rule 17.6", "Mandatory", "NO", "**YES**", "" + "Rule 17.7", "Required", "NO", "**YES**", "" + "Rule 17.8", "Advisory", "NO", "NO", "" + "Rule 17.9", "Mandatory", "NO", "**YES**", "" + "Rule 17.10", "Required", "NO", "**YES**", "" + "Rule 17.11", "Advisory", "NO", "NO", "" + "Rule 17.12", "Advisory", "NO", "NO", "" + "Rule 17.13", "Required", "NO", "**YES**", "" + "Rule 18.1", "Required", "NO", "**YES**", "" + "Rule 18.2", "Required", "NO", "**YES**", "" + "Rule 18.3", "Required", "NO", "**YES**", "" + "Rule 18.4", "Advisory", "NO", "NO", "" + "Rule 18.5", "Advisory", "NO", "NO", "" + "Rule 18.6", "Required", "NO", "**YES**", "" + "Rule 18.7", "Required", "NO", "**YES**", "" + "Rule 18.8", "Required", "NO", "**YES**", "" + "Rule 18.9", "Required", "NO", "**YES**", "" + "Rule 18.10", "Mandatory", "NO", "**YES**", "" + "Rule 19.1", "Mandatory", "NO", "**YES**", "" + "Rule 19.2", "Advisory", "NO", "NO", "" + "Rule 20.1", "Advisory", "NO", "NO", "" + "Rule 20.2", "Required", "NO", "**YES**", "" + "Rule 20.3", "Required", "NO", "**YES**", "" + "Rule 20.4", "Required", "NO", "**YES**", "" + "Rule 20.5", "Advisory", "NO", "NO", "" + "Rule 20.6", "Required", "NO", "**YES**", "" + "Rule 20.7", "Required", "NO", "**YES**", "" + "Rule 20.8", "Required", "NO", "**YES**", "" + "Rule 20.9", "Required", "NO", "**YES**", "" + "Rule 20.10", "Advisory", "NO", "NO", "" + "Rule 20.11", "Required", "NO", "**YES**", "" + "Rule 20.12", "Required", "NO", "**YES**", "" + "Rule 20.13", "Required", "NO", "**YES**", "" + "Rule 20.14", "Required", "NO", "**YES**", "" + "Rule 21.1", "Required", "DISABLED", "NO", "This rule is not applicable for Phoenix-RTOS kernel source code, because common identifiers are defined within its codebase." + "Rule 21.2", "Required", "DISABLED", "NO", "This rule is not applicable for Phoenix-RTOS kernel source code, because common identifiers are defined within its codebase." + "Rule 21.3", "Required", "NO", "**YES**", "" + "Rule 21.4", "Required", "NO", "**YES**", "" + "Rule 21.5", "Required", "DISABLED", "NO", "This rule is not applicable for the Phoenix-RTOS kernel source code, because is proprietary to its codebase and has defined behavior." + "Rule 21.6", "Required", "NO", "**YES**", "" + "Rule 21.7", "Required", "NO", "**YES**", "" + "Rule 21.8", "Required", "NO", "**YES**", "" + "Rule 21.9", "Required", "NO", "**YES**", "" + "Rule 21.10", "Required", "DISABLED", "NO", "This rule is not applicable for the Phoenix-RTOS kernel source code, because date and time functions are proprietary to its codebase and has defined behavior. " + "Rule 21.11", "Advisory", "NO", "NO", "" + "Rule 21.12", "Required", "NO", "**YES**", "" + "Rule 21.13", "Mandatory", "NO", "**YES**", "" + "Rule 21.14", "Required", "NO", "**YES**", "" + "Rule 21.15", "Required", "NO", "**YES**", "" + "Rule 21.16", "Required", "NO", "**YES**", "" + "Rule 21.17", "Mandatory", "NO", "**YES**", "" + "Rule 21.18", "Mandatory", "NO", "**YES**", "" + "Rule 21.19", "Mandatory", "NO", "**YES**", "" + "Rule 21.20", "Mandatory", "NO", "**YES**", "" + "Rule 21.21", "Required", "NO", "**YES**", "" + "Rule 21.22", "Mandatory", "NO", "**YES**", "" + "Rule 21.23", "Required", "NO", "**YES**", "" + "Rule 21.24", "Required", "NO", "**YES**", "" + "Rule 21.25", "Required", "NO", "**YES**", "" + "Rule 21.26", "Required", "NO", "**YES**", "" + "Rule 22.1", "Required", "NO", "**YES**", "" + "Rule 22.2", "Mandatory", "NO", "**YES**", "" + "Rule 22.3", "Required", "NO", "**YES**", "" + "Rule 22.4", "Mandatory", "NO", "**YES**", "" + "Rule 22.5", "Mandatory", "NO", "**YES**", "" + "Rule 22.6", "Mandatory", "NO", "**YES**", "" + "Rule 22.7", "Required", "NO", "**YES**", "" + "Rule 22.8", "Required", "NO", "**YES**", "" + "Rule 22.9", "Required", "NO", "**YES**", "" + "Rule 22.10", "Required", "NO", "**YES**", "" + "Rule 22.11", "Required", "NO", "**YES**", "" + "Rule 22.12", "Mandatory", "NO", "**YES**", "" + "Rule 22.13", "Required", "NO", "**YES**", "" + "Rule 22.14", "Mandatory", "NO", "**YES**", "" + "Rule 22.15", "Required", "NO", "**YES**", "" + "Rule 22.16", "Required", "NO", "**YES**", "" + "Rule 22.17", "Required", "NO", "**YES**", "" + "Rule 22.18", "Required", "NO", "**YES**", "" + "Rule 22.19", "Required", "NO", "**YES**", "" + "Rule 22.20", "Mandatory", "NO", "**YES**", "" + "Rule 23.1", "Advisory", "NO", "NO", "" + "Rule 23.2", "Required", "NO", "**YES**", "" + "Rule 23.3", "Advisory", "NO", "NO", "" + "Rule 23.4", "Required", "NO", "**YES**", "" + "Rule 23.5", "Advisory", "NO", "NO", "" + "Rule 23.6", "Required", "NO", "**YES**", "" + "Rule 23.7", "Advisory", "NO", "NO", "" + "Rule 23.8", "Required", "NO", "**YES**", "" diff --git a/docsresources/phoenixsystems/docsresources/maketitle.tex b/docsresources/phoenixsystems/docsresources/maketitle.tex index 958a6061..e2931f2f 100644 --- a/docsresources/phoenixsystems/docsresources/maketitle.tex +++ b/docsresources/phoenixsystems/docsresources/maketitle.tex @@ -25,8 +25,13 @@ {\setmainfont{Liberation Sans} \textcolor{ps-darkblue}{% - {\fontsize{16}{19}\selectfont \textbf{\docauthor}} + {\fontsize{16}{19}\selectfont \textbf{Author: \docauthor}} }} +\ifdefined\docreviewer +\textcolor{ps-darkblue}{% + {\fontsize{16}{19}\selectfont \textbf{Reviewer: \docreviewer}} +} +\fi \vspace{2.25cm} @@ -50,5 +55,9 @@ \textcolor{ps-lightblue}{% \makebox[\textwidth][l]{\hspace{0.2cm}\docversion\hfill \docdate\hspace{0.2cm}} }} +\ifdefined\dochistory + \newpage + \dochistory +\fi \clearpage \pagestyle{plain}