rust-embedded / rust-embedded/cortex-m
Documentation: What is the contract to call NVIC::unmask soundly?
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 1k
- Forks
- 202
- Avg merge
- 6d 2h
- Merged PRs (30d)
- 2
Description
NVIC::enable() was deprecated with the following warning.
WARNING This method is a soundness hole in the API; it should actually be an unsafe function. Use NVIC::unmask which has the right unsafety.
https://docs.rs/stm32f3xx-hal/0.3.0/stm32f3xx_hal/stm32/struct.NVIC.html#method.enable
NVIC::unmask() has the following documentation.
This function is unsafe because it can break mask-based critical sections
https://docs.rs/stm32f3xx-hal/0.3.0/stm32f3xx_hal/stm32/struct.NVIC.html#method.unmask
This isn't sufficient information for someone to know how they can soundly call the unmask function to enable interrupts. The documentation should include a # Safety section per the API guidelines describing the invariants the caller is expected to uphold.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the NVIC::unmask documentation and compare its safety explanation with the Rust API Guidelines linked in the issue. Document the caller invariants needed to use unmask soundly, including why it can break mask-based critical sections; done means the API has a clear # Safety section.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- embedded-iot
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 50/100