doc: document python build scripts
We have a collection of python scripts that are part of our build system. This PR collects docstring comments added to these scripts into a summary document. Previous references to just the script name in other documentation are updated to point to this build tool documentation. Some of the scripts needed an update to be processed (via include directives) consistently. Signed-off-by: David B. Kinder <david.b.kinder@intel.com> Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
parent
9055cfe57e
commit
17299f0734
10 changed files with 142 additions and 35 deletions
|
@ -51,7 +51,7 @@ call APIs, several conditions must be met on how the kernel object is declared:
|
|||
|
||||
* The object must be declared as a top-level global at build time, such that it
|
||||
appears in the ELF symbol table. It is permitted to declare kernel objects
|
||||
with static scope. The post-build script ``gen_kobject_list.py`` scans the
|
||||
with static scope. The post-build script :ref:`gen_kobject_list.py` scans the
|
||||
generated ELF file to find kernel objects and places their memory addresses
|
||||
in a special table of kernel object metadata. Kernel objects may be members
|
||||
of arrays or embedded within other data structures.
|
||||
|
@ -66,7 +66,7 @@ Kernel objects that are found but do not meet the above conditions will not be
|
|||
included in the generated table that is used to validate kernel object pointers
|
||||
passed in from user mode.
|
||||
|
||||
The debug output of the ``gen_kobject_list.py`` script may be useful when
|
||||
The debug output of the :ref:`gen_kobject_list.py` script may be useful when
|
||||
debugging why some object was unexpectedly not being tracked. This
|
||||
information will be printed if the script is run with the ``--verbose`` flag,
|
||||
or if the build system is invoked with verbose output.
|
||||
|
@ -98,7 +98,7 @@ the access control aspects of the permission system are not enforced.
|
|||
Implementation Details
|
||||
======================
|
||||
|
||||
The ``gen_kobject_list.py`` script is a post-build step which finds all the
|
||||
The :ref:`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
|
||||
the DWARF debug information present in the generated ELF file for the kernel.
|
||||
|
||||
|
|
|
@ -8,7 +8,7 @@ set of stacks. These stacks exist in a 1:1 relationship with each thread stack
|
|||
defined in the system. The privileged stacks are created as a part of the
|
||||
build process.
|
||||
|
||||
A post-build script ``gen_priv_stacks.py`` scans the generated
|
||||
A post-build script :ref:`gen_priv_stacks.py` scans the generated
|
||||
ELF file and finds all of the thread stack objects. A set of privileged
|
||||
stacks, a lookup table, and a set of helper functions are created and added
|
||||
to the image.
|
||||
|
|
|
@ -28,7 +28,7 @@ All system calls have the following components:
|
|||
|
||||
* A **C prototype** for the API, declared in some header under ``include/`` and
|
||||
prefixed with :c:macro:`__syscall`. This prototype is never implemented
|
||||
manually, instead it gets created by the ``scripts/gen_syscalls.py`` script.
|
||||
manually, instead it gets created by the :ref:`gen_syscalls.py` script.
|
||||
What gets generated is an inline function which either calls the
|
||||
implementation function directly (if called from supervisor mode) or goes
|
||||
through privilege elevation and validation steps (if called from user
|
||||
|
@ -57,8 +57,8 @@ supervisor mode. For example, to initialize a semaphore:
|
|||
|
||||
The :c:macro:`__syscall` attribute is very special. To the C compiler, it
|
||||
simply expands to 'static inline'. However to the post-build
|
||||
``parse_syscalls.py`` script, it indicates that this API is a system call.
|
||||
The ``parse_syscalls.py`` script does some parsing of the function prototype,
|
||||
:ref:`parse_syscalls.py` script, it indicates that this API is a system call.
|
||||
The :ref:`parse_syscalls.py` script does some parsing of the function prototype,
|
||||
to determine the data types of its return value and arguments, and has some
|
||||
limitations:
|
||||
|
||||
|
@ -118,7 +118,7 @@ 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
|
||||
C and header files by the :ref:`gen_syscalls.py` script, all of which can be found in
|
||||
the project out directory under ``include/generated/``:
|
||||
|
||||
* The system call is added to the enumerated type of system call IDs,
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue