Skip to content

RFC: doc: glossary: Consolidate "software component" as a term #100118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+10 −9
Open

RFC: doc: glossary: Consolidate "software component" as a term #100118

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions doc/glossary.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,8 +127,9 @@ Glossary of Terms
executing on the processor.

kernel
The set of Zephyr-supplied files that implement the Zephyr kernel,
including its core services, device drivers, network stack, and so on.
The :term:`software component` in Zephyr that provides the
hardware-agnostic core of the RTOS, including booting, threading,
scheduling, synchronization, user mode, memory management and more.
Comment on lines +130 to +132
Copy link
Contributor

@mathieuchopstm mathieuchopstm Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hardware-agnostic core

would mean that arch is not part of the kernel, which sounds wrong?

Copy link
Member Author

@carlescufi carlescufi Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! That is exactly the kind of discussion I wanted to have here. I am very much OK with arch being part of the kernel component, so I am completely fine with removing the hardware-agnostic part and even specifically mentioning the arch part as part of the kernel.

Copy link
Contributor

@mathieuchopstm mathieuchopstm Nov 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be clear, I have no issues with hardware-agnostic core by itself; however, if we keep it (and if arch is indeed considered part of the kernel!), then arch should be explicitly mentioned as also being part of the "kernel" software component in addition to the HW-agnostic code, e.g. roughly:

Suggested change
The :term:`software component` in Zephyr that provides the
hardware-agnostic core of the RTOS, including booting, threading,
scheduling, synchronization, user mode, memory management and more.
The :term:`software component` in Zephyr that provides the
hardware-agnostic core of the RTOS, including booting, threading,
scheduling, synchronization, user mode, memory management and more,
as well as architecture-specific implementation of certain routines
used by the hardware-agnostic code.

Another wording (without the hardware-agnostic part) is possible too, but IMO your proposal is fine except for this tiny detail.

Copy link
Member Author

@carlescufi carlescufi Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @mathieuchopstm! I will wait for more feedback from others before I make any changes. Your proposed change is fine with me.


power domain
A power domain is a collection of devices for which power is
Expand Down Expand Up @@ -169,9 +170,9 @@ Glossary of Terms
features, and that the vendor typically names and markets together.

software component
A software component is a self-contained, modular, and replaceable part of
the Zephyr source code. A driver, a subsystem or an applications are all
examples of software components present in Zephyr.
A software component is a well-defined and modular part of
the Zephyr source code. The kernel, a driver, a library, a subsystem or a
sample are all examples of software components present in Zephyr.

subsystem
A subsystem refers to a logically distinct part of the operating system
Expand Down
8 changes: 4 additions & 4 deletions doc/introduction/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,11 @@ The Zephyr kernel supports multiple architectures, including:

The full list of supported boards based on these architectures can be found :ref:`here <boards>`.

In the context of the Zephyr OS, a :term:`subsystem` refers to a logically distinct
In the context of the Zephyr OS, a :term:`software component` refers to a logically distinct
Copy link
Member

@nashif nashif Nov 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thank you for taking care of this, I think a review of terminology used and making things less confusing in our docs and codebase is long overdue, however, we should try to have a deep review and fix this once and for all and take any major actions needed (renaming stuff) in one single step. few comments.

  • I guess the main driver for this is the fact that we have drivers being classified as subsystem? Well, I guess it was necessary at some time to call them something and we might have picked the wrong name and if it is a problem, we probably need to address this.
  • if we are going this path, I would remove this section completely and just rely on this being defined in the gloassry, no need to keep it duplicatated here.
  • Also, I would look across the documentation and the code base and address existing usage of subsystem
    • example, take https://docs.zephyrproject.org/latest/kernel/usermode/kernelobjects.html where usage of 'driver subsystems' is common. What changes do we need to make there and in the code to make this compatible with the new definition, or we do not need to touch it at all?
    • also look at other items in the gloassary and define how those relate to SC
    • visualizing all of this would be very helpful, maybe using some of our existing (probably outdated) architecture diagrams
  • Based on this definition, everything is a a component, a device driver class is a component, a driver is a component, a sample using those drivers is a component, so I am not sure how useful this is, looking at our docs, there are 4 mentions, 2 of which go bak to ETSI, see below:
  • Many related standards/project define software component already, need to make sure we do not conflict or overload the definition, or it will be confusing to users:
  • Autosar: AUTOSAR software components are reusable building blocks of AUTOSAR software. An AUTOSAR software component encapsulates one or more algorithms and communicates with its environment through well-defined ports. For example, a throttle application might include AUTOSAR software components that represent sensors for throttle and acceleration pedal sensors, a throttle position monitor, a controller, and an actuator.
  • IETSI:
    a general term used to refer to a software system or an element, such as module, unit, data, or document. IEEE Std 1061-1998 (R2004) IEEE Standard for Software Quality Metrics Methodology.2.2. 2. a functionally or logically distinct part of a software configuration item, distinguished for the purpose of convenience in designing and specifying a complex SCI as an assembly of subordinate elements"

part of the operating system that handles specific functionality or provides
certain services. Subsystems can include components such as networking,
certain services. Zephyr contains software components such as networking,
file systems, device driver classes, power management, and communication protocols,
among others. Each subsystem is designed to be modular and can be configured,
among others. Each software component is designed to be modular and can be configured,
customized, and extended to meet the requirements of different embedded
applications.

Expand Down Expand Up @@ -182,7 +182,7 @@ Zephyr offers a large and ever growing number of features including:

**Native port**
:zephyr:board:`Native sim <native_sim>` allows running Zephyr as a Linux application with support
for various subsystems and networking.
for most components, including networking.


.. include:: ../../README.rst
Expand Down