API and component naming conventions

[carlescufi]

The following two items are to be covered by this issue:

• API naming conventions
• Component definitions:
  • kernel
  • OS
  • subsystem
  • middleware
  • ...

[pabigot]

This seems to be a pretty broad issue.

Is this things like:

• under what conditions should a function be prefixed with k_ vs sys_ vs z_?
• do prefixes form a namespace, e.g. everything related to work queues should start with k_work_?
• do names follow an order based on grammatical function, e.g. verb-object so k_cancel_work rather than k_work_cancel?
• how do we ensure that selected prefixes clearly identify their role and don't conflict with other systems or user code (e.g. rb_)?
• how do we mediate clarity, uniqueness, and identifier length (e.g. is k_work_delayable_cancel_sync acceptable)?

Does it answer questions like:

• What "the Zephyr kernel" in terms of scope? Everything in the Zephyr tree? Only code in /kernel?
• What is "the safety certification scope"?

Or is this a list of things for which documentation needs to be provided and the details will be handled at a lower level.

A clear written description of the problem and the criteria for an acceptable solution could make discussion more effective.

[carlescufi]

API meeting 27th October 2020:

Terms:

• arch: Code living in the arch/ folder
• kernel: Code living in the kernel/ folder
• system: TBD
• OS: TBD

Standard prefixes:

• arch_: TBD
• k_: Public kernel APIs
• z_: Internal APIs. Not to be used by code outside the module, not exposed in include/
• sys_: TBD

To be continued next week.

[nashif]

the old naming conventions that might shed some light on the background:

https://github.com/zephyrproject-rtos/zephyr/wiki/Naming-Conventions

[carlescufi]

API meeting 19th January 2021:

Terms:

arch: Architecture-specific code. All arch code lives in the arch/ and include/arch folders
kernel: RTOS kernel (list functionality here) . All code that lives in kernel/, kernel/include/ and lib/kernel/ (will be populated with files from lib/os/)
Note: the following files need to be moved from lib/os to lib/kernel:
rb.c
sem.c
thread_entry.c
work_q.c
heap.c
heap-validate.c
mutex.c
p4wq.c

Core OS: Kernel and basic functionality included in Zephyr:

• C library
• The contents of lib/os except for the ones that belong in lib/kernel

Subsystems: Hardware independent software components

• POSIX
• CMSIS
• All subsystems in subsys/, some of those need to be moved out to drivers (disk, Bluetooth controller)

Drivers: All driver implementations in drivers/ and driver APIs in include/drivers/

Standard prefixes:

arch: arch_
kernel: k_: Public kernel APIs,
sys_: TBD

z_: Internal APIs. Not to be used by code outside the module, not exposed in include/
To be continued next week.

[pearson]

It would be a good idea to have a link to the naming conventions in the Zephyr documentation, and possibly somewhere before any examples are discussed. For me, after taking a look at the "synchronization" example, it took some googling to find this issue and the link to the naming conventions document.

[de-nordic]

Might be worth setting some general naming convention, or how to short names. It is quite annoying, when you switch between APIs, to remind yourself whether offset in function call is now spelled "offset", "off" or "offs".