search

zephyrproject-rtos / zephyr

Primary Git Repository for the Zephyr Project. Zephyr is a new generation, scalable, optimized, secure RTOS for multiple hardware architectures.
https://docs.zephyrproject.org
Apache License 2.0
10.52k stars 6.45k forks source link

Zephyr API definition (Auditable Branch) #40259

Open Abramo-Bagnara opened 2 years ago

Abramo-Bagnara commented 2 years ago

Several MISRA guidelines included in the Zephyr Coding Guidelines prescribe the elimination or justification of unused declarations, macros and typedefs. For a project like Zephyr, the first thing to be done is to define the API: all API elements can be easily justified independently from the fact that they are or are not used in any particular build. The most convenient way to define the API elements is by listing the header files that contain the corresponding declarations, under the assumption that such header file have been designed for this purpose.

Does such a list of header files already exist? If not, can someone help defining it? This would be very useful for any (automatic and manual) activity regarding the checking of compliance with the coding guidelines.

Abramo-Bagnara commented 2 years ago

Ping. Acting upon this is needed to efficiently continue the work on compliance with the coding guidelines.

peter-mitsis commented 2 years ago

To my knowledge, such a list does not yet exist.

I know that the C compiler can be used to generate a list of header file dependencies for each file, but that, from what I understand, would be too coarse of resolution for our needs.

Would you be able to provide a concrete example of the resulting information you are looking for? This would help in establishing both what is needed, and scope of effort.

Abramo-Bagnara commented 2 years ago

Restricting attention to the MISRA C:2012 guidelines that are in the Zephyr subset, the following is the list of files that declare one or more functions that are never used in the reference builds:

zephyr/arch/x86/zefi/printf.h zephyr/build/zephyr/include/generated/syscalls/device.h zephyr/build/zephyr/include/generated/syscalls/entropy.h zephyr/build/zephyr/include/generated/syscalls/kernel.h zephyr/build/zephyr/include/generated/syscalls/kobject.h zephyr/build/zephyr/include/generated/syscalls/libc-hooks.h zephyr/build/zephyr/include/generated/syscalls/log_core.h zephyr/build/zephyr/include/generated/syscalls/log_ctrl.h zephyr/build/zephyr/include/generated/syscalls/mem_manage.h zephyr/build/zephyr/include/generated/syscalls/rand32.h zephyr/build/zephyr/include/generated/syscalls/time.h zephyr/build/zephyr/include/generated/syscalls/uart.h zephyr/include/app_memory/mem_domain.h zephyr/include/arch/x86/arch.h zephyr/include/arch/x86/intel64/arch.h zephyr/include/arch/x86/intel64/syscall.h zephyr/include/debug/coredump.h zephyr/include/debug/gcov.h zephyr/include/debug/stack.h zephyr/include/device.h zephyr/include/drivers/entropy.h zephyr/include/drivers/interrupt_controller/sysapic.h zephyr/include/drivers/uart.h zephyr/include/fatal.h zephyr/include/fs/fs.h zephyr/include/irq.h zephyr/include/kernel.h zephyr/include/kernel/sched_priq.h zephyr/include/kernel_structs.h zephyr/include/kernel_version.h zephyr/include/logging/log.h zephyr/include/logging/log_backend.h zephyr/include/logging/log_core.h zephyr/include/logging/log_msg.h zephyr/include/logging/log_msg2.h zephyr/include/pm/device.h zephyr/include/pm/pm.h zephyr/include/posix/time.h zephyr/include/sys/arch_interface.h zephyr/include/sys/atomic.h zephyr/include/sys/atomic_builtin.h zephyr/include/sys/bitarray.h zephyr/include/sys/cbprintf.h zephyr/include/sys/crc.h zephyr/include/sys/dlist.h zephyr/include/sys/fdtable.h zephyr/include/sys/kobject.h zephyr/include/sys/math_extras.h zephyr/include/sys/mem_manage.h zephyr/include/sys/mutex.h zephyr/include/sys/notify.h zephyr/include/sys/onoff.h zephyr/include/sys/rb.h zephyr/include/sys/sem.h zephyr/include/sys/sflist.h zephyr/include/sys/slist.h zephyr/include/sys/sys_heap.h zephyr/include/sys/time_units.h zephyr/include/sys/timeutil.h zephyr/include/sys/util.h zephyr/include/syscall_handler.h zephyr/include/timeout_q.h zephyr/include/tracing/tracing.h zephyr/kernel/include/kernel_internal.h zephyr/kernel/include/kernel_offsets.h zephyr/kernel/include/ksched.h zephyr/kernel/include/mmu.h zephyr/lib/libc/minimal/include/stdio.h zephyr/lib/libc/minimal/include/stdlib.h zephyr/lib/libc/minimal/include/string.h zephyr/lib/libc/minimal/include/time.h zephyr/lib/os/heap.h

For the automatically generated header files, the rationale for deviation is clear. For the others, there is good rationale for deviation is they are header files that define the public APIs of the respective software modules.

The following header files contain type declarations that are never used in the reference builds:

zephyr/include/arch/structs.h zephyr/include/drivers/console/console.h zephyr/include/drivers/uart.h zephyr/include/kernel.h zephyr/include/kernel_structs.h zephyr/include/pm/device.h zephyr/include/posix/posix_types.h zephyr/include/posix/signal.h

I guess all those are part of public APIs, but I would like to have an authoritative confirmation for this fact.

peter-mitsis commented 2 years ago

Unless I am missing something, my interpretation of "Additional rules Rule A.1: Conditional Compiliation" at https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html, is that they are implicitly part of the public API and thus necessary to be included in the documentation.