Define the boundaries between driver class, library and subsystem

[carlescufi]

Summary

In Zephyr we have two distinct ways of achieving a similar result:

• Driver classes (drivers/) which offer a common API that encapsulates a hardware feature and then has multiple hardware-specific implementations
• Libraries, which are usually self-contained reusable units of code that do not interact with the hardware
• Subsystems, which typically implement a higher-level API that is hardware agnostic and is not tied to pure hardware feature but rather something higher level, and that then have a concept of "backends" each of which is typically a different "transport"

Describe the solution you'd like

Define and describe in the documentation clear guidelines to determine whether a new feature should be added as a new driver class or a new subsystem.

Alternatives

No response

Additional Context

No response

[butok]

Also, it's good to clarify the difference & boundaries between "subsystem" /subsys and "library" /lib."

[carlescufi]

Architecture WG meeting:

• Proposal for definition of library: Self-contained reusable units of code that do not depend on the driver model or hardware and provide common functionality for subsystems and applications. Library code may use other parts of Zephyr but typically encapsulates a particular function.
• Proposal for definition of subsystem: higher-level software component that provides a set of related functionalities or services, typically independent of specific hardware. It is designed to be hardware-agnostic (although it can interact with the hardware using the Zephyr driver model) and exposes an API for applications, middleware or other OS components, often with support for multiple backends or implementations. Unlike device drivers, which directly interact with hardware, subsystems implement functionality that is not tied to a single hardware feature. Examples: Protocol stacks, file systems, logging, settings, debug and instrumentation facilities.
• Proposal for definition of driver class: Drivers classes are hardware abstractions that define a vendor-agnostic common API to interface with a hardware peripheral or feature. Individual instances of the driver class provide the code necessary to map the vendor-agnostic API to the vendor-specific hardware interface. TBD: mention common code in drivers

Drivers:
TBD

Libraries:

• lib/acpi likely needs to be moved out
• A bunch of components in lib/os need to be moved out, perhaps to a top-level folder with OS-support code (e.g. userspace helpers, poweroff, ...)
• posix should be moved to subsys/portability since it is essentially an adaptation layer to allow POSIX APIs to be used by apps

Subsystems:
TBD

[ngphibang]

Video subsystem should be moved from drivers/ to subsys/ after finishing some on-going reworks, I think.

[nashif]

• lib/acpi likely needs to be moved out

#99398

[dkalowsk]

How does Zephyr see industry standards apply to these distinctions? Using JDEC as an example, should a JDEC standard implementation be considered a driver (for example SPI -> JDEC -> flash |-> fs) or should it be considered a subsystem (for example SPI -> flash |-> JDEC -> fs)?

[carlescufi]

Architecture WG meeting:

Updated during the meting

• library: Self-contained reusable units of code that do not depend on the driver model or hardware and provide common functionality for subsystems and applications. Library code may use other parts of Zephyr but typically encapsulates a particular function.
• subsystem:
  • Higher-level software component that provides a set of related functionalities or services, independent of specific hardware.
  • It is designed to be hardware-agnostic (although it can interact with the hardware using the Zephyr driver model or other means when applicable [[and typically uses either an application-provided reference or Devicetree's chosen node to select a particular hardware device]])
  • It exposes an API for applications, middleware or other OS components, often with support for multiple backends or implementations.
  • Unlike device drivers, which directly interact with specific hardware, subsystems implement functionality that is not tied to a single hardware feature. Examples: Protocol stacks, file systems, logging, settings, debug and instrumentation facilities.
• Driver:
  • Drivers are individual implementations of a driver class for a specific type of peripheral, providing the code necessary to map the vendor-agnostic API to the vendor-specific hardware interface.
  • Drivers classes are hardware abstractions that define a vendor-agnostic common API to interface with a hardware peripheral or feature, alongside common code for all specific individual drivers implementing a driver class

[de-nordic]

How does Zephyr see industry standards apply to these distinctions? Using JDEC as an example, should a JDEC standard implementation be considered a driver (for example SPI -> JDEC -> flash |-> fs) or should it be considered a subsystem (for example SPI -> flash |-> JDEC -> fs)?

You mean JEDEC as specification for BPF/SFDP tables and ID? Problem with JEDEC is that it is mostly a database describing a device. Parsing it could probably be extracted into separate unit, if we manage to create some common driver configuration object, or create parameter query API - but that would be a lot of identifiers, and separate queries over SPI.
JEDEC, that it is not really embedded software friendly, as, if you rely on it for configuration, you have to query and keep a lot of information in RAM to use it, for example specific commands for writes, and so on.

Currently drivers can choose which info read from JEDEC to enable features they implement and these paths are often highly optimized.

JEDEC is great if you are willing to write generic driver that can pick and work with any device it finds at run time, but at a lot of cost in code, as long as you are able to standardize bus object passed to that driver by different SoC.

I do not think we can add a simple JEDEC API that any driver can just use, because you would probably end up with a lot of "does this device support this feature" functions. We already have some basic functions to parse BPF.

On the other hand you have SPI FLASH interface functions, the basic set, that is de-facto standard and could be dropped into separate unit, usable by any driver; functions from the unit would be just given a bus to operate on (but there is also question of properly addressing timeouts). I was actually convinced, for some time, that this is what MSPI will do.