Vendor-specific APIs in Zephyr

[carlescufi]

Problem Description

This issue started from discussions in the following two PRs:

• drivers: misc: Add support renesas_elc driver for Renesas devices #88141
• drivers: nrf_ironside dvfs service #90755

Which introduce similar but subtly different API types:

• drivers: misc: Add support renesas_elc driver for Renesas devices #88141 Introduces a completely vendor-specific API for a hardware function that is not yet abstracted as a common driver class in Zephyr
• drivers: nrf_ironside dvfs service #90755 introduces SoC-specific APIs that the application and drivers can use to access functionality over IPC. Those will likely never be generalized at all

Proposed Change (Summary)

The options we have for the different vendor-specific APIs are:

a. Keep the headers in include/zephyr/drivers/soc/<vendor-function>.h and the implementation in drivers/soc/<vendor-function>.c
b. Keep both headers and implementations in soc/<vendor>/<function>
c. Start new driver classes every time a new proposal like this comes. For example, in the case of the Renesas ELC above, a new include/zephyr/drivers/interconnect/ could have been started that tries to generalize the API to a certain extent

Proposed Change (Detailed)

Not available yet.

Dependencies

No response

Concerns and Unresolved Questions

No response

Alternatives Considered

No response

[henrikbrixandersen]

Keep the headers in include/zephyr/drivers/soc/<vendor-function>.h and the implementation in drivers/soc/<vendor-function>.c

We could end up having vendor-specific APIs that are not tied to a SoC, but rather a peripheral IC.

[carlescufi]

Keep the headers in include/zephyr/drivers/soc/<vendor-function>.h and the implementation in drivers/soc/<vendor-function>.c

We could end up having vendor-specific APIs that are not tied to a SoC, but rather a peripheral IC.

Sure, I had not covered that specific case, but is it common? Do you think we will actually find one of those? Have we seen one so far, or are all external ICs documented and generic to all SoCs?

[nashif]

a. Keep the headers in include/zephyr/drivers/soc/<vendor-function>.h and the implementation in drivers/soc/<vendor-function>.c

Hmm, not a fan of this, include/zephyr should not have any vendor specific APIs that are exposed as Zephyr public APIs and would never have a chance of following our API lifecycles, because they will be experimental for the entirty of their existence.

If something, on arrival, can't evolve through the API life cycle, then it should not be exposed as a Zephyr API.

The only reason I would consider drivers/soc/ is to be able to share across a vast number of hardware which might get problematic inside soc/.

But we could consider a parallel to soc/<vendor> and board/<vendor> and have drivers/<vendor>, for anything that is not an existing peripheral/hw class we suppprt and that is 100% vendor specific.

b. Keep both headers and implementations in soc/<vendor>/<function>

IMO this is cleanest solution for things that we know for sure will not evolve into something generic, if something like this happens and there are more vendors introducing somethig similar, that is where we will consider creating a new driver class and moving things out of soc/ into drivers/.

Here is an example, intel adsp IPC, see https://github.com/zephyrproject-rtos/zephyr/blob/main/soc/intel/intel_adsp/common/include/intel_adsp_ipc.h and https://github.com/zephyrproject-rtos/zephyr/blob/main/soc/intel/intel_adsp/common/ipc.c

This was introduced as part of the SoC, whether that was the right thing to do at the time, is a question for another discussion.

it is not available as public API, completely contained and does not touch anyone else and part of the SoC, i.e if I drop the SoC, it goes away with it, completely managed by the vendor, does not have to go through some API lifecycle or review etc. etc, however, all of that said, years later you realize it was the wrtong thing to do, and now there is an effor to move this to use some public IPC Zephyr APIs (that came later I think) and use the same approach in SOF by other vendors, who happen to do things in different ways.

c. Start new driver classes every time a new proposal like this comes. For example, in the case of the Renesas ELC above, a new include/zephyr/drivers/interconnect/ could have been started that tries to generalize the API to a certain extent

I think this is an option we should explore and should be the first choice if something has potential or it is not clear yet, how it evolves and their it is feasible to abstract it and build on top of it.

so, in the right order:

1. Is it something that can be part of an existing class, build on top of an existing? No need for new class, just extend existing class.
2. is this a new driver class that is not vendor specific, i.e. an evolution of some legcy bus or a new bus etc, go into drivers/, no questions asked. We know this will pick up more adopters and it will evolve to a stable API soon enough.
3. See option (c) from above (from @carlescufi )
4. See option (b) from above
5. See option (a) from above (consider driver/<vendor>)

[nashif]

here are the draft slides i was sharing yesterday in the arch WG meeting: https://docs.google.com/presentation/d/1URk28GanuvnKC9FBxkDzOMnDtbD62dCTGOlhTGpqipI/edit?usp=sharing

[carlescufi]

Thanks @nashif for the proposal. I will start a PR based on this and other thoughts I have and we can continue there.

[henrikbrixandersen]

Keep the headers in include/zephyr/drivers/soc/<vendor-function>.h and the implementation in drivers/soc/<vendor-function>.c

We could end up having vendor-specific APIs that are not tied to a SoC, but rather a peripheral IC.

Sure, I had not covered that specific case, but is it common? Do you think we will actually find one of those? Have we seen one so far, or are all external ICs documented and generic to all SoCs?

I meant something like what we saw in #69920 - a driver for an external/peripheral IC, which doesn't really fit into any of the existing driver subsystems. This IC is not a SoC, so placing it's driver under include/zephyr/drivers/soc/<vendor-function>.h would be weird.

[de-nordic]

Keep the headers in include/zephyr/drivers/soc/<vendor-function>.h and the implementation in drivers/soc/<vendor-function>.c

We could end up having vendor-specific APIs that are not tied to a SoC, but rather a peripheral IC.

We already have a few for these. For example there are Nordic specific functions for qspi to enable XIP (

zephyr/include/zephyr/drivers/flash/nrf_qspi_nor.h

Line 32 in 66f5d70

__syscall void nrf_qspi_nor_xip_enable(const struct device *dev, bool enable);

) .
Also Flash API defines ex_op callback that allows to define vendor specific operations, without extending the API dispatch structure. I would gladly see some better way to do that, specifically the userspace support is clunky.
Still, we need a way to allow vendor specific APIs, because user may want, for an app code, functionalities that we can not universally provide across devices, because these functionalities have been a reason for an user to select IC in the first place (like mem protections, etc).