michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: fix ReST heading underlines

Browse source 
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>
This commit is contained in:
David B. Kinder 2018-02-01 16:06:21 -08:00 • committed by Anas Nashif
commit ec1b1df5ed
4 changed files with 29 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

20
doc/kernel/usermode/kernelobjects.rst
View file

@ -27,7 +27,7 @@ that the kernel object address is valid and that the calling thread
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 @@ information will be printed if the script is run with the ``--verbose`` flag,
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 @@ includes:
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 @@ supervisor threads are still tracked for two reasons:
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 @@ not being tracked by the kernel will be no-ops. Doing the same from user mode
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 @@ are embedded within some larger struct and initialized statically.
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 @@ Creating New Core Kernel Objects
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 @@ what API struct they are set to.
Driver instances of the new subsystem should now be tracked.
Configuration Options
=====================
*********************
Related configuration options:
@ -249,7 +249,7 @@ Related configuration options:
* :option:`CONFIG_MAX_THREAD_BYTES`
APIs
====
****
* :c:func:`k_object_access_grant()`
* :c:func:`k_object_access_revoke()`

26
doc/kernel/usermode/syscalls.rst
View file

@ -22,7 +22,7 @@ This section describes how to declare new system calls and discusses a few
implementation details relevant to them.
Components
==========
**********
All system calls have the following components:
@ -42,7 +42,7 @@ All system calls have the following components:
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 @@ bottom of ``include/sensor.h``:
#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 @@ flags in the build system for the related files.
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 @@ see the implementation of :c:func:`_syscall_ret64_invoke0` and
: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 @@ declared in some C file. There is no prototype needed for implementation
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 @@ made simpler by some macros in ``kernel/include/syscall_handlers.h``.
Handler functions should be declared using these macros.
Argument Validation
-------------------
===================
Several macros exist to validate arguments:
@ -297,7 +297,7 @@ calling thread. This is done instead of returning some error condition to
keep the APIs the same when calling from supervisor mode.
Handler Declaration
-------------------
===================
All handler functions have the same prototype:
@ -349,7 +349,7 @@ initialized), and that the limit parameter is nonzero:
}
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 @@ as:
_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 @@ before checking. Using the previous example:
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 @@ be validated as writable by the calling thread:
}
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`:

8
doc/kernel/usermode/usermode.rst
View file

@ -10,7 +10,7 @@ For details on creating threads that run in user mode, please see
: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 @@ Example use-cases of Zephyr's user mode features:
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 @@ We are specifically not protecting against the following attacks:
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 @@ through the following mechanisms:
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

4
samples/drivers/led_ws2812/README.rst
View file

@ -43,7 +43,7 @@ The sample application is located at ``samples/drivers/led_ws2812/``
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 @@ values of the following configuration options:
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.