msp432/adc: document safety invariants on &[u8] to &[u16] conversion #2689
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
To support ADC operations on `&'static mut [u16]` slice references, while at the same time using DMA over `&'static mut [u8]` slice references, the MSP432's ADC implementation features conversion helpers. While these are unsafe and check some of the required invariants, these checks and the documentation have been insufficient. In particular, it is not guaranteed that a given `u8` will be well-aligned to the alignment constraints of a `u16`. Thus, simply transmuting a `*mut u8` to a `*mut 16` and converting this back to a slice can cause undefined behavior. This does not add additional checks on these functions given they are already unsafe. Furthermore, this issue likely does not affect the existing codebase, given that only buffers which were `&'static mut [u16]` slice references get converted to `&'static mut [u8]`, and back to `&'static mut [u16]` again. Nonetheless, the presence of checks for some of the required invariants could be interpreted as a function which is safe to use, even though it is marked unsafe. Instead, this PR adds a clear indication of the required invariants and the consequences of a violation of any given requirement. Signed-off-by: Leon Schuermann <[email protected]>
hudson-ayers
approved these changes
Jul 23, 2021
bradjc
approved these changes
Jul 27, 2021
|
bors r+ |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Pull Request Overview
To support ADC operations on
&'static mut [u16]slice references, while at the same time using DMA over&'static mut [u8]slice references, the MSP432's ADC implementation features conversion helpers. While these are unsafe and check some of the required invariants, these checks and the documentation have been insufficient.In particular, it is not guaranteed that a given
u8will be well-aligned to the alignment constraints of au16. Thus, simply transmuting a*mut u8to a*mut 16and converting this back to a slice can cause undefined behavior.This does not add additional checks on these functions given they are already unsafe. Furthermore, this issue likely does not affect the existing codebase, given that only buffers which were
&'static mut [u16]slice references get converted to&'static mut [u8], and back to&'static mut [u16]again. Nonetheless, the presence of checks for some of the required invariants could be interpreted as a function which is safe to use, even though it is marked unsafe.Instead, this PR adds a clear indication of the required invariants and the consequences of a violation of any given requirement.
Testing Strategy
This pull request was tested by proofreading.
TODO or Help Wanted
This code seems weird. Also, is a conversion from
&'static mut [u16]to&'static mut [u8]unsound in any case? If not, we shouldn't mark it unsafe.Documentation Updated
Updated the relevant files inor no updates are required./docs,Formatting
make prepush.@lebakassemmerl