Document the claim API's use in libraries #881

New issue

Open

opened 2022-06-24 08:39:09 -05:00 by daveythacher · 1 comment

daveythacher commented

2022-06-24 08:39:09 -05:00

(Migrated from github.com)

This is not library friendly:
github.com/raspberrypi/pico-sdk@426e46126b/src/rp2_common/hardware_dma/dma.c (L20)
github.com/raspberrypi/pico-sdk@426e46126b/src/rp2_common/hardware_pio/pio.c (L21)

I am able to work around this, but this requires a factory. As mentioned here: https://forums.raspberrypi.com/viewtopic.php?t=334125

This is not disclosed in documentation leading to undefined behavior. https://raspberrypi.github.io/pico-sdk-doxygen/group__hardware__dma.html#gae1b3c916746b3d2052f21b7dda34aab9

In fact, is this correct?

Method for cooperative claiming of hardware. Will cause a panic if the channel is already claimed. Use of this method by libraries detects accidental configurations that would fail in unpredictable ways.

This would predict reserved memory which cannot be bypassed. Such reservation would need to be used by the linker script, which is pointless. Perhaps the best solution is to just increase the documentation. Recommending the programmer handle this in their context as appropriate, as the SDK is not the right context to handle this.

My guess is the documentation is written from the perspective of a single static compilation. However, a warning should exist for other cases. Most of these practices are not recommended, however should they be undocumented?

This is not library friendly: https://github.com/raspberrypi/pico-sdk/blob/426e46126b5a1efaea4544cdb71ab81b61983034/src/rp2_common/hardware_dma/dma.c#L20 https://github.com/raspberrypi/pico-sdk/blob/426e46126b5a1efaea4544cdb71ab81b61983034/src/rp2_common/hardware_pio/pio.c#L21 I am able to work around this, but this requires a factory. As mentioned here: https://forums.raspberrypi.com/viewtopic.php?t=334125 This is not disclosed in documentation leading to undefined behavior. https://raspberrypi.github.io/pico-sdk-doxygen/group__hardware__dma.html#gae1b3c916746b3d2052f21b7dda34aab9 In fact, is this correct? > Method for cooperative claiming of hardware. Will cause a panic if the channel is already claimed. Use of this method by libraries detects accidental configurations that would fail in unpredictable ways. This would predict reserved memory which cannot be bypassed. Such reservation would need to be used by the linker script, which is pointless. Perhaps the best solution is to just increase the documentation. Recommending the programmer handle this in their context as appropriate, as the SDK is not the right context to handle this. My guess is the documentation is written from the perspective of a single static compilation. However, a warning should exist for other cases. Most of these practices are not recommended, however should they be undocumented?

kilograham commented

2022-06-27 04:31:29 -05:00

(Migrated from github.com)

The intention is currently that you always use INTERFACE libraries. if you statically link the SDK code into a static library, then you will end up with unexpected results.

You should be able to workaround this in the meanwhile by just including the foo_headers rather than foo libraries from the SDK, however it is not currently ideal in so far as the _headers libraries do not have the same dependencies as their non header cohorts. I had been planning to fix this soon, and will add a new issue

The intention is currently that you always use INTERFACE libraries. if you statically link the SDK code into a static library, then you will end up with unexpected results. You should be able to workaround this in the meanwhile by just including the `foo_headers` rather than `foo` libraries from the SDK, however it is not currently ideal in so far as the `_headers` libraries do not have the same dependencies as their non header cohorts. I had been planning to fix this soon, and will add a new issue