First commit, Vystem v0.1

docs/shelter/kernel/config.md

@@ -0,0 +1,3 @@
+# Config parsing
+
+In Shelter, the parsing of the config is made by the `SH_STATUS sh_conf_get_boot_config(sh_conf_BOOT_CONFIG **config)` function. It allow for quick and secure configuration parsing. It create a `sh_conf_BOOT_CONFIG` object. These elements are defined inside `shelter/lib/include/kernel/conf.h` and implemented inside `shelter/lib/src/kernel/conf.c`. For the full configuration documentation, please see [boot configuration documentation](../bootconfig.md).

docs/shelter/kernel/kernel.md

@@ -0,0 +1,11 @@
+# Kernel-specific APIs
+
+## Introduction
+
+The Shelter kernel define his own specific APIs like logging and configuration parsing.
+
+## Summary
+
+1) [Log API](log.md)
+2) [Config parsing](config.md)
+3) [Tests utilities](testutils.md)

docs/shelter/kernel/log.md

@@ -0,0 +1,137 @@
+# Log API
+
+## Introduction
+
+The logging API is one of the most important of the entire kernel: it allow it to output informations with various level of importance and various sources.
+
+## Output methods
+
+The logging API can log informations with two differents methods:
+- serial output: use the serial API to output in real time all the provided informations. Can be disabled by setting it to true using the `sh_log_load_serial_setting(sh_bool is_disabled)` function. The serial API being disabled, this method can also be disabled by that.
+- ring buffer output: use the ring buffer API to store all the provided informations into a ring buffer, mapped by the bootloader. Can be disabled by setting the `logging_ring_size` boot configuration key to 0
+
+The following functions provide way to set and get those settings:
+- `void sh_log_load_serial_setting(sh_bool is_disabled)`: specify if serial log outputting should be disabled
+- `sh_bool sh_log_get_serial_setting()` return the activation status of serial log outputting (`SH_TRUE` mean disabled)
+- `void sh_log_load_logging_ring_size(sh_uint16 pages_count)`: set logging ring size
+- `sh_uint32 sh_log_get_logging_ring_size()`: return logging ring size
+- `sh_uint64 sh_log_get_total_bytes_written()`: return total amount of bytes written inside logging ring
+
+## Output primitives
+
+The following functions doesn't care about log level or log source and are specialized into specific data type:
+- `void sh_log_byte(sh_uint8 byte)`: log a byte, basic entry point of the entire logging system
+- `SH_STATUS sh_log_string(const char* str)`: log a table of characters
+Here are the numbers logging functions under their naming scheme:
+```
+sh_log_(u)int[8/16/32/64](_hex)
+```
+
+Basically, there is 12 functions that can output numbers, in various sizes (8 to 64 bits), signed or unsigned, in decimal or hexadecimal. The hexadecimal variant doesn't exist for signed integers. Examples: `sh_log_uint8`, `sh_log_int16`, `sh_log_uint64_hex`...
+
+There are two mores functions:
+- `SH_STATUS sh_log_uint64_hex_fixed(sh_uint64 n)`: log a `sh_uint64` in hexadecimal without removing useless zeros, useful for logging pointers and address
+- `SH_STATUS sh_log_double(double value)`: log a double encoded in decimal
+
+## Output channels and log level
+
+The Shelter logging API provide higher level functions to output on specific log channels. Here are all the log channels:
+- `SH_LOG_DEBUG`: log level 0
+- `SH_LOG_LOG`: log level 1
+- `SH_LOG_WARNING`: log level 2
+- `SH_LOG_ERROR`: log level 3
+- `SH_LOG_CRITICAL`: log level 4
+- `SH_LOG_FATAL`: log level 5
+- `SH_LOG_TEST`: log level 6
+
+Each log channel has a log level. The log level is set by the `log_level` boot configuration key. The log API will only output log messages with log level equal or higher to current log level. This restriction doesn't apply to log channel `SH_LOG_TEST`.
+
+The `sh_log_OUTPUT_TYPE` type is used to store output type by log level. It's a wrapper of `sh_uint8`. The `sh_log_output_type_valid(sh_log_OUTPUT_TYPE t)` can be used to check if a log level is valid.
+
+Two functions allow to set and get the current log level:
+- `SH_STATUS sh_log_load_log_level(sh_uint8 log_level)`
+- `sh_uint8 sh_log_get_log_level()`
+
+## Output sources
+
+The Shelter logging API also require a source in order to log informations. Here are all the possible sources:
+- `SH_LOG_SOURCE_MAIN`
+- `SH_LOG_SOURCE_CONF`
+- `SH_LOG_SOURCE_PAGE`
+- `SH_LOG_SOURCE_SLAB`
+- `SH_LOG_SOURCE_TEST`
+- `SH_LOG_SOURCE_PEZ`
+- `SH_LOG_SOURCE_PBA`
+- `SH_LOG_SOURCE_HEAP`
+- `SH_LOG_SOURCE_STD`
+
+The `sh_log_OUTPUT_SOURCE` type is used to store log source. It's a wrapper of `sh_uint16`. The `sh_log_output_source_valid(sh_log_OUTPUT_SOURCE s)` can be used to check if a log level is valid.
+
+## Output payloads
+
+In order to compile all of those informations into one payload, the logging API provide this structure :
+``` C
+typedef struct {
+  sh_log_OUTPUT_TYPE output_type;
+  sh_log_OUTPUT_SOURCE output_source;
+  sh_tsc_TSC_VALUE tsc_value;
+  const char* message_pointer;
+} sh_log_OUTPUT_PAYLOAD;
+```
+
+This allow to contain the message content, the output channel, the output source and the TSC value of any log message.
+
+There is two functions that can manipulate output payloads:
+- `SH_STATUS sh_log_payload(sh_log_OUTPUT_PAYLOAD *payload)`: output a payload
+- `SH_STATUS sh_log_payload_format(sh_log_OUTPUT_PAYLOAD *payload,va_list args)`: format then output a payload, not directly callable, see below for more informations
+
+## Higher levels logging functions
+
+The following functions will automatically create the payload depending on the parameters they receive.
+
+### Logging with automatic line break
+
+These functions are named like this:
+```
+sh_log_[test/debug/log/warning/error/critical/fatal]
+```
+
+They all need two arguments in the following order (except `sh_log_test` which only need the first one):
+- `const char* str`: the text to log
+- `sh_log_OUTPUT_SOURCE source`: the source of the log message
+
+These functions will automatically add the `\n` characters at the end of each log message.
+
+### Logging without automatic line break
+
+These functions are named like this:
+```
+sh_log_l[test/debug/log/warning/error/critical/fatal]
+```
+
+They all need two arguments in the following order (except `sh_log_ltest` which only need the first one):
+- `const char* str`: the text to log
+- `sh_log_OUTPUT_SOURCE source`: the source of the log message
+
+### Logging with formating
+
+In order to allow for formatting log messages, the log API provide functions named like this:
+```
+sh_log_f[test/debug/log/warning/error/critical/fatal]
+```
+
+They all need at least two arguments in the following order (except `sh_log_ltest` which only need the second one):
+- `sh_log_OUTPUT_SOURCE source`: the source of the log message
+- `const char* format`: the format text
+- all the others argument after that are used as content for formatting the log message
+
+All of these functions use `sh_log_payload_format()` under the hood which itself use `SH_STATUS sh_log_format(const char* format,va_list args)` to format log messages.
+
+The format syntax is as follow:
+- `%s`: insert a string made of `char`, passed as `char*`
+- `%d`: insert a double
+- `%x`: insert a integer that need to be provided as a `sh_uint64`, format it as hexadecimal without removing useless zeros. Used to log addresses
+- `%c`: insert a `char`
+- `%%`: insert a `%`
+
+There is also a specific syntax for formatting integers. It's start with the `%` symbol, then need a amount of bytes (can be 1, 2, 4 or 8) and a output format: `u` for unsigned decimal, `s` for signed decimal, `U` for unsigned decimal. Example: `%1s` output a `sh_int8` in decimal, `%2u` output a `sh_uint16` in decimal, `%4U` output a unsigned `sh_uint32` in hexadecimal.

docs/shelter/kernel/testutils.md

@@ -0,0 +1,23 @@
+# Tests utilities
+
+## Introduction
+
+To support the test-and-benchmark framework, the Shelter kernel include a common base of utilities that provide to all tests a basic way to store and expose their results. This file only cover the basic utilities usable by all tests, not the detail and typical results of each test. These utilities are defined inside `shelter/lib/include/kernel/tests/test_utils.h` and implemented inside `shelter/lib/src/kernel/tests/test_utils.c`.
+
+## Overview
+
+The test-and-benchmark (TAB) framework is responsible for testing differents subsystems to ensure their stability and performances over differents devices. But it also provides a common base for showing results and others little things.
+
+Firsty, it define internally a buffer of 10000 `sh_tsc_TSC_VALUE` for storing cycles count and compute statistics. The pointer to this buffer is obtainable through the `sh_tsc_TSC_VALUE* sh_test_get_tsc_values_buffer_ptr()` function.
+
+Then, the TAB framework also define the `void sh_test_load_iterations_count(sh_uint64 iterations_num)` function. This function load the iterations count defined by the `bench_iterations` boot configuration key. Some tests doesn't support this feature, so this function will only set iterations count for tests that support custom iterations count.
+
+Finally, each test uses the `SH_STATUS sh_test_compute_print_stats(char* benchname,sh_tsc_TSC_VALUE *tsc_value_array,sh_uint64 array_size)` function. This function will compute various statistics and print them like this:
+```
+Result for benchmark "<benchmark name>" :
+Min: <min time> | Med: <median time> | Avg: <average time> | Max: <max time> | Total : <total time> (TSC)
+[P00-P90] <min time>-P90 : [##################--] 90%
+[P90-P99] P90-P99 : [#-------------------] 9%
+[P99-Max] P99-<max time> : [--------------------] 1%
+```
+Here, `PXX` where `XX` is a percentage mean a percentile.