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.55k stars 6.46k forks source link

Split driver APIs into application-facing and driver-facing headers #44086

Open carlescufi opened 2 years ago

carlescufi commented 2 years ago

The current driver API headers contain effectively 2 separate APIs:

The proposal is to separate these 2 APIs into independent headers.

Eg. include/drivers/can.h would become:

can.h will then #include <drivers/can/dev.h>

de-nordic commented 2 years ago

Maybe device.h instead of dev.h, the device header is called device.h anyway, so why short the other one.

carlescufi commented 2 years ago

Maybe device.h instead of dev.h, the device header is called device.h anyway, so why short the other one.

Sure, why not. But Linux tends to use dev.h, and it's shorter :)

carlescufi commented 2 years ago

cc @tbursztyka @jfischer-no

teburd commented 2 years ago

I think this is a nice idea 👍

jfischer-no commented 2 years ago

The current driver API headers contain effectively 2 separate APIs:

* The application-facing calls (i.e. the ones an application uses to interact with the driver)

* The driver-facing calls (typically in an `_api` struct, exposed by each driver implementation to the "common layer")

The proposal is to separate these 2 APIs into independent headers.

Eg. include/drivers/can.h would become:

* `include/drivers/can.h` (application-facing)

* `include/drivers/can/dev.h` (driver-facing)

can.h will then #include <drivers/can/dev.h>

I do not like, looks like unnecessary changes. If then rather #include <drivers/uapi/can.h>, #include <drivers/uapi/spi.h> or #include <drivers/dapi/can.h>, #include <drivers/dapi/spi.h> ... than a bunch of subdirectories.

carlescufi commented 2 years ago

@jfischer-no sounds like a good alternative too. I will bring it up on the API meeting.

tbursztyka commented 2 years ago

Do we really want that split? I mean, the driver-facing calls tend to be really small and do not bloat the header. While the fact that 2 sort of APIs are present is indeed true, are there any other arguments in favor of such split? Note that the user-facing API does not exist without the driver-facing one... So even if there are 2 APIs, they are not at all disconnected: in fact, user will need to use the so called driver-facing API as well (all the structs used by the driver, enums, dedicated types...)

I am trying to be conservative here. I am not especially against or in favor of such split. But it seems to me this would benefit of more arguments.

Maybe device.h instead of dev.h, the device header is called device.h anyway, so why short the other one.

We already have a device.h file in includes/, as a absolute name we should avoid duplicates as much as possible.

I do not like, looks like unnecessary changes. If then rather #include <drivers/uapi/can.h>, #include <drivers/uapi/spi.h> or #include <drivers/dapi/can.h>, #include <drivers/dapi/spi.h> ... than a bunch of subdirectories.

If we would go that way, I'd rather prefer that solution as well (the uapi directory version of it)

henrikbrixandersen commented 2 years ago

If we are to separate the two, I lean towards the uapi/ version tool