drivers/periph_{i2c,spi}: fix doc on initialization

[maribu]

Contribution description

Both SPI and I2C peripheral drivers MUST NOT be initialized by the application code / (non-peripheral) device driver, as this is done automatically be default. Some peripheral drivers have a non-idempotent initialization and initializing them twice will break things.

Sadly, the doc states the exact opposite.

This updates the documentation to match the implementation. In addition the special case is pointed out of disabling the automatic initialization during boot, in which case the app indeed has to do the initialization.

Testing procedure

The CI will generate a preview of the doc that can be checked.

Issues/PRs references

Might fix #21187

[riot-ci]

Murdock results

✔️ PASSED

a825735 drivers/periph_{i2c,spi}: fix doc on initialization

Success	Failures	Total	Runtime
1	0	1	01m:13s

Artifacts

• Documentation preview

[dylad]

What about removing i2c/spi_init from the header to prevent users from easily adding this function ? We can keep those init functions somehow "private". And of course, explicitly explain why we do this in the doc :)

[maribu]

I just had a similar thought. Maybe rename the functions to i2c_init_internal_use_only() and and spi_init_internal_use_only() and call them from periph_init.

If and only if periph_init_i2c is not used, provide the symbol i2c_init. That way users will notice the issue at link time, even if the provide the forward declaration of i2c_init() by hand.

This will also keep existing users that do correctly add DISABLE_MODULE += periph_init_i2c working without change.

[dylad]

If and only if periph_init_i2c is not used, provide the symbol i2c_init. That way users will notice the issue at link time, even if the provide the forward declaration of i2c_init() by hand.
This will also keep existing users that do correctly add DISABLE_MODULE += periph_init_i2c working without change.

Sounds perfectly reasonable to me.

[dylad]

ACK.
Changes in the doc looks good. Let's rework the I2C/SPI init in a followup PR.