Skip to content
Permalink
Browse files

gen_kobject_list.py: better comments and --help. Zero code change.

- The script can but does not always generate five files, in fact the
  current build invokes it at least three times requesting different
  outputs every time.

- --kobj-types-output produces a code fragment; not a standalone/usable
  header file. It outputs enum constants for a single enum type and not
  several enum types.

- Some outputs include driver instances and others not: clarify which.

- There's an entire and great section in the documentation that took
  me ages to find because it's not referenced anywhere in the --help
  or code. Fixed.

- Highlight the massive duplication in the CMakeLists.txt to save
  déjà vu confusion and minimize future divergence.

- Other minor tweaks.

Signed-off-by: Marc Herbert <marc.herbert@intel.com>
  • Loading branch information...
marc-hb authored and galak committed Apr 16, 2019
1 parent c8208a3 commit 4a10eea0ebe490402b291c7342fc6703222a2a83
Showing with 18 additions and 11 deletions.
  1. +5 −1 CMakeLists.txt
  2. +13 −10 scripts/gen_kobject_list.py
@@ -899,6 +899,8 @@ if(CONFIG_USERSPACE)
endif()


# Warning most of this gperf code is duplicated below for
# gen_kobject_list.py / output_lib
if(CONFIG_ARM AND CONFIG_USERSPACE)
set(GEN_PRIV_STACKS $ENV{ZEPHYR_BASE}/scripts/gen_priv_stacks.py)
set(PROCESS_PRIV_STACKS_GPERF $ENV{ZEPHYR_BASE}/scripts/process_gperf.py)
@@ -1022,6 +1024,8 @@ if(CONFIG_ARM AND CONFIG_USERSPACE)
set_property(GLOBAL APPEND PROPERTY GENERATED_KERNEL_OBJECT_FILES priv_stacks_output_obj_renamed_lib)
endif()

# Warning: most of this gperf code is duplicated above for
# gen_priv_stacks.py / priv_stacks_output_lib
if(CONFIG_USERSPACE)
set(GEN_KOBJ_LIST ${ZEPHYR_BASE}/scripts/gen_kobject_list.py)
set(PROCESS_GPERF ${ZEPHYR_BASE}/scripts/process_gperf.py)
@@ -1036,7 +1040,7 @@ if(CONFIG_USERSPACE)
# out of the nearly finished elf file, generating the source code
# for a hash table based on that information, and then compiling and
# linking the hash table back into a now even more nearly finished
# elf file.
# elf file. More information in gen_kobject_list.py --help.

# Use the script GEN_KOBJ_LIST to scan the kernel binary's
# (${ZEPHYR_PREBUILT_EXECUTABLE}) DWARF information to produce a table of kernel
@@ -19,14 +19,16 @@
- The calling thread has sufficient permissions on the object
For more details see the "Kernel Objects" section in the documentation.
The zephyr build generates an intermediate ELF binary, zephyr_prebuilt.elf,
which this script scans looking for kernel objects by examining the DWARF
debug information to look for instances of data structures that are considered
kernel objects. For device drivers, the API struct pointer populated at build
time is also examined to disambiguate between various device driver instances
since they are all 'struct device'.
The result of this script is five generated files:
This script can generate five different output files:
- A gperf script to generate the hash table mapping kernel object memory
addresses to kernel object metadata, used to track permissions,
@@ -35,17 +37,18 @@
- A header file containing generated macros for validating driver instances
inside the system call handlers for the driver subsystem APIs.
- A header file defining enumerated types for all the different kernel
object types.
- A code fragment included by kernel.h with one enum constant for
each kernel object type and each driver instance.
- A C code fragment, included by kernel/userspace.c, for printing
human-readable representations of kernel object types in the
- The inner cases of a switch/case C statement, included by
kernel/userspace.c, mapping the kernel object types and driver
instances to their human-readable representation in the
otype_to_str() function.
- A C code fragment, included by kernel/userspace.c, for mapping
kernel object types to the sizes of those kernel objects, used for
allocating instances of them at runtime (CONFIG_DYNAMIC_OBJECTS)
in the obj_size_get() function.
- The inner cases of a switch/case C statement, included by
kernel/userspace.c, mapping kernel object types to their sizes.
This is used for allocating instances of them at runtime
(CONFIG_DYNAMIC_OBJECTS) in the obj_size_get() function.
"""

import sys
@@ -317,7 +320,7 @@ def parse_args():
help="Output driver validation macros")
parser.add_argument(
"-K", "--kobj-types-output", required=False,
help="Output k_object enum values")
help="Output k_object enum constants")
parser.add_argument(
"-S", "--kobj-otype-output", required=False,
help="Output case statements for otype_to_str()")

0 comments on commit 4a10eea

Please sign in to comment.
You can’t perform that action at this time.