doc: fix ReST heading underlines
The expected order for heading levels in our ReST documents is # for H1,
* for H2, = for H3, and - for H4. Some documents snuck in without
following this guideline.
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>
diff --git a/doc/kernel/usermode/kernelobjects.rst b/doc/kernel/usermode/kernelobjects.rst
index d5f8fbc..765ecfa 100644
--- a/doc/kernel/usermode/kernelobjects.rst
+++ b/doc/kernel/usermode/kernelobjects.rst
@@ -27,7 +27,7 @@
has sufficient permissions to work with it.
Object Placement
-================
+****************
Kernel objects that are only used by supervisor threads have no restrictions
and can be located anywhere in the binary, or even declared on stacks. However,
@@ -69,7 +69,7 @@
or if the build system is invoked with verbose output.
Implementation Details
-----------------------
+======================
The ``gen_kobject_list.py`` script is a post-build step which finds all the
valid kernel object instances in the binary. It accomplishes this by parsing
@@ -106,7 +106,7 @@
the thread's index in kernel object permission bitfields.
Supervisor Thread Access Permission
-===================================
+***********************************
Supervisor threads can access any kernel object. However, permissions for
supervisor threads are still tracked for two reasons:
@@ -120,7 +120,7 @@
same permissions as the parent thread, except the parent thread object.
User Thread Access Permission
-=============================
+*****************************
By default, when a user thread is created, it will only have access permissions
on its own thread object. Other kernel objects by default are not usable.
@@ -161,7 +161,7 @@
will result in a fatal error for the calling thread.
Initialization State
-====================
+********************
Most operations on kernel objects will fail if the object is considered to be
in an uninitialized state. The appropriate init function for the object must
@@ -200,14 +200,14 @@
Creating New Kernel Object Types
-================================
+********************************
When implementing new kernel features or driver subsystems, it may be necessary
to define some new kernel object types. There are different steps needed
for creating core kernel objects and new driver subsystems.
Creating New Core Kernel Objects
---------------------------------
+================================
* In ``scripts/gen_kobject_list.py``, add the name of the struct to the
:py:data:`kobjects` list.
@@ -222,7 +222,7 @@
Instances of the new struct should now be tracked.
Creating New Driver Subsystem Kernel Objects
---------------------------------------------
+============================================
All driver instances are :c:type:`struct device`. They are differentiated by
what API struct they are set to.
@@ -240,7 +240,7 @@
Driver instances of the new subsystem should now be tracked.
Configuration Options
-=====================
+*********************
Related configuration options:
@@ -249,7 +249,7 @@
* :option:`CONFIG_MAX_THREAD_BYTES`
APIs
-====
+****
* :c:func:`k_object_access_grant()`
* :c:func:`k_object_access_revoke()`
diff --git a/doc/kernel/usermode/syscalls.rst b/doc/kernel/usermode/syscalls.rst
index 5f007d2..b06cc3e 100644
--- a/doc/kernel/usermode/syscalls.rst
+++ b/doc/kernel/usermode/syscalls.rst
@@ -22,7 +22,7 @@
implementation details relevant to them.
Components
-==========
+**********
All system calls have the following components:
@@ -42,7 +42,7 @@
validation of all the arguments passed in.
C Prototype
-===========
+***********
The C prototype represents how the API is invoked from either user or
supervisor mode. For example, to initialize a semaphore:
@@ -86,7 +86,7 @@
#include <syscalls/sensor.h>
Invocation Context
-------------------
+==================
Source code that uses system call APIs can be made more efficient if it is
known that all the code inside a particular C file runs exclusively in
@@ -112,7 +112,7 @@
code runs in user mode and system calls are unconditionally made.
Implementation Details
-----------------------
+======================
Declaring an API with :c:macro:`__syscall` causes some code to be generated in
C and header files by ``scripts/gen_syscalls.py``, all of which can be found in
@@ -210,7 +210,7 @@
:c:func:`_syscall_ret64_invoke1`.
Implementation Function
-=======================
+***********************
The implementation function is what actually does the work for the API.
Zephyr normally does little to no error checking of arguments, or does this
@@ -224,7 +224,7 @@
functions, these are automatically generated.
Handler Function
-================
+****************
The handler function runs on the kernel side when a user thread makes
a system call. When the user thread makes a software interrupt to elevate to
@@ -252,7 +252,7 @@
Handler functions should be declared using these macros.
Argument Validation
--------------------
+===================
Several macros exist to validate arguments:
@@ -297,7 +297,7 @@
keep the APIs the same when calling from supervisor mode.
Handler Declaration
--------------------
+===================
All handler functions have the same prototype:
@@ -349,7 +349,7 @@
}
Simple Handler Declarations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+---------------------------
Many kernel or driver APIs have very simple handler functions, where they
either accept no arguments, or take one object which is a kernel object
@@ -373,7 +373,7 @@
_SYSCALL_HANDLER1_SIMPLE(k_sem_count_get, K_OBJ_SEM, struct k_sem *);
System Calls With 6 Or More Arguments
--------------------------------------
+=====================================
System calls may have more than six arguments, however the number of arguments
passed in via registers when the privilege elevation is invoked is fixed at six
@@ -425,7 +425,7 @@
System Calls With 64-bit Return Value
--------------------------------------
+=====================================
If a system call has a return value larger than 32-bits, the handler will not
return anything. Instead, a pointer to a sufficient memory region for the
@@ -451,14 +451,14 @@
}
Configuration Options
-=====================
+*********************
Related configuration options:
* :option:`CONFIG_USERSPACE`
APIs
-====
+****
Helper macros for creating system call handlers are provided in
:file:`kernel/include/syscall_handler.h`:
diff --git a/doc/kernel/usermode/usermode.rst b/doc/kernel/usermode/usermode.rst
index dfccd24..2b2e4f0 100644
--- a/doc/kernel/usermode/usermode.rst
+++ b/doc/kernel/usermode/usermode.rst
@@ -10,7 +10,7 @@
:ref:`lifecycle_v2`.
Threat Model
-============
+************
User mode threads are considered to be untrusted by Zephyr and are therefore
isolated from other user mode threads and from the kernel. A flawed or
@@ -32,7 +32,7 @@
isolated from each other if one crashes or is otherwise compromised.
Design Goals
-------------
+============
For threads running in a non-privileged CPU state (hereafter referred to as
'user mode') we aim to protect against the following:
@@ -116,7 +116,7 @@
but the integrity of the system cannot be guaranteed.
High-level Policy Details
-=========================
+*************************
Broadly speaking, we accomplish these thread-level memory protection goals
through the following mechanisms:
@@ -160,7 +160,7 @@
varies per architecture.
Constraints
-===========
+***********
All kernel objects, thread stacks, and device driver instances must be defined
at build time if they are to be used from user mode. Dynamic use-cases for
diff --git a/samples/drivers/led_ws2812/README.rst b/samples/drivers/led_ws2812/README.rst
index 02210f3..996990f 100644
--- a/samples/drivers/led_ws2812/README.rst
+++ b/samples/drivers/led_ws2812/README.rst
@@ -43,7 +43,7 @@
in the Zephyr source tree.
Configure For Your LED Strip
-----------------------------
+============================
The first thing you need to do is make sure that the driver is
configured to match the particular LED chips you're using. For
@@ -65,7 +65,7 @@
Refer to their help strings for details.
Configure For Your Board
-------------------------
+========================
Now check if your board is already supported, by looking for a file
named ``boards/YOUR_BOARD_NAME.conf`` in the application directory.
