NCS: nRF I2C driver API documentation

RE: NCS: nRF I2C driver API documentation

Jørgen Holmefjord — Mon, 16 Oct 2023 15:52:16 GMT

[quote user="ngrunert"]I think it is a bit confusing that the documentation refers to modules which are not (necessarily?) present when having installing the NCS. [/quote]

Not sure I understand this. NRFX is integrated in both nRF Connect SDK (which you were linking to) and in nRF5 SDK (documentation found e.g. here: https://infocenter.nordicsemi.com/topic/sdk_nrf5_v17.1.0/group__nrfx__spim.html). NRFX is released in many versions, as you can see in the GitHub repository: https://github.com/NordicSemiconductor/nrfx/releases

[quote user="ngrunert"]You mean the nrfx driver which is documented on the site is actually integrated with the nRF5 SDK? Certainly not. The last version of the nRF5 SDK I am aware of is the 17.1.0 and AFAIK its API is slightly different.[/quote]

The documentation you linked to was for the "latest" of NCS, not for nRF5 SDK. You can see which version of nrfx is integrated in the latest NCS release in nrfx changelog documentation. For nRF5 SDK, the integrated version of nrfx is mentioned in the release notes:

- nrfx has been updated to version 1.9.0.
  For details, see .\modules\nrfx\changelog.md.

[quote user="ngrunert"]An example for a driver which does not forward error codes but only EIO is the lis2dh driver.[/quote]

This driver is part of Zephyr, which is an open-source RTOS. Nordic does not have control over or influence on all sensor drivers that are implemented as part of the RTOS offerings. I was referring to the HW peripheral drivers for our devices. If the available driver does not work for your needs, you can implement your own sensor driver with more features (this is what you had to do in nRF5 SDK, as the selection of available sensor drivers was very limited).

[quote user="ngrunert"]I am not sure that logging will work while the initialization is still ongoing. This depends probably on the driver initialization sequence. Anyway, even with log probably the application implementer is forced to dig into the driver code to make sense of the error message. That would be a lot easier with some documentation, at least at the level of the non-Zephyr-driver nrfx (or whatever you call these).[/quote]

Yes, if the error occurs in the sensor driver, and this driver does not forward the error codes, you will likely have to look into the driver implementation. I was referring to the HW peripheral drivers, where you can get logs about failed transfers, etc, with actual error codes from the nrfx drivers.

RE: NCS: nRF I2C driver API documentation

Norbert — Mon, 16 Oct 2023 15:36:21 GMT

I think it is a bit confusing that the documentation refers to modules which are not (necessarily?) present when having installing the NCS. You mean the nrfx driver which is documented on the site is actually integrated with the nRF5 SDK? Certainly not. The last version of the nRF5 SDK I am aware of is the 17.1.0 and AFAIK its API is slightly different.

An example for a driver which does not forward error codes but only EIO is the lis2dh driver.

I am not sure that logging will work while the initialization is still ongoing. This depends probably on the driver initialization sequence. Anyway, even with log probably the application implementer is forced to dig into the driver code to make sense of the error message. That would be a lot easier with some documentation, at least at the level of the non-Zephyr-driver nrfx (or whatever you call these).

Best regards,

Norbert

RE: NCS: nRF I2C driver API documentation

Jørgen Holmefjord — Mon, 16 Oct 2023 15:04:24 GMT

Hi,

[quote user="ngrunert"]The page https://docs.nordicsemi.com/bundle/ncs-latest/page/nrfx/drivers/spi/index.html says it is for the nRF Connect SDK but the API seems to be for the old (completely unrelated) nRF5 SDK.[/quote]

This is incorrect. The nrfx driver module is SDK/OS agnostic and is delivered as a separate module through our GitHub. It is also integrated with both the nRF5 SDK and nRF Connect SDK. nrfx can be used directly in nRF Connect SDK, but the nrfx APIs are also used in the Zephyr driver implementations for nRF devices.

There is no driver documentation for the device-specific implementations of the Zephyr drivers APIs, as these are meant as internal implementations that interact with the Zephyr driver APIs depending on the configured target/configuration. Most error codes should be forwarded to the application through the Zephyr API interface, if this is not the case, this is something that can be reported and evaluated to be changed. Note that not all errors makes sense to forward directly to the higher layer API. Many of the driver implementations also have logging messages that can be enabled for each module, in case you need to debug what is failing, see for instance CONFIG_I2C_LOG_LEVEL_CHOICE.

Best regards,
Jørgen

RE: NCS: nRF I2C driver API documentation

Norbert — Fri, 13 Oct 2023 08:26:03 GMT

I am sorry, but I am profoundly confused by your documentation. The page https://docs.nordicsemi.com/bundle/ncs-latest/page/nrfx/drivers/spi/index.html says it is for the nRF Connect SDK but the API seems to be for the old (completely unrelated) nRF5 SDK. At least, neither HAL nor driver API match the NCS implementation.

Could you please comment on this?

Thanks,

Norbert

RE: NCS: nRF I2C driver API documentation

Norbert — Fri, 13 Oct 2023 06:17:38 GMT

Hello Johnny,

I am using them through the Zephyr drivers. Not directly, but through another layer of more generic Zephyr drivers (sensor class). The problem occurs during initialisation of the driver so even before Zephyr enters the app. The outer Zephyr driver replaces all error messages from underlying drivers with -EIO.

Meanwhile I solved this issue but my question for documentation is more general. There are tons of things which can go wrong in the driver configuration via DT and Kconfig without the compiler issuing as much as a warning. The only way to know what is wrong is to go inside the driver. The nrfx drivers return an error number which is removed by the outer layer driver which only checks for !=0. But if there is no reliable documentation that debug is pretty much an uphill battle. SDK5 was much more straightforward, much easier to use and better documented.

Please tell me there is somewhere a driver-specific API documentation of the Zephyr drivers... although I have not much hope left. :-(

Thanks,

Norbert

RE: NCS: nRF I2C driver API documentation

Johnny Nguyen — Thu, 12 Oct 2023 21:20:04 GMT

Hello Norbert,

Have you seen the following?

As you've stated, you can deep dive for that fxn here, but most of the return values you are asking about are in errno.h.

The versions of nrfx driver api documentation exists in the infocenter and documentation center, but these are not 100% relevant to your original inquiry given that you list the zephyr\... file. (and as such may not contain the relevant returns that you would see from the fxn you are calling)

Are you trying to use that function directly or through Zephyr's I2C driver?