Buffer access methods do not document the caller's safety obligations

[jonas-schievink]

All of the buffer access methods, write_buffer, read_buffer, and their static counterparts, are unsafe, but the Safety section in their docs does not explain what invariants the caller needs to uphold for the call to be safe.

The safety docs for write_buffer are:

Once this method has been called, it is unsafe to call any &mut self methods, except for write_buffer, on this object as long as the returned value is in use (by DMA).

The docs for read_buffer are:

Once this method has been called, it is unsafe to call any &mut self methods on this object as long as the returned value is in use (by DMA).

...which makes it sound like even a subsequent call to read_buffer would be unsafe.

[Sympatron]

Proper documentation is on the traits:

From ReadBuffer docs:

The implementing type must be safe to use for DMA reads. This means:

• It must be a pointer that references the actual buffer.
• As long as no &mut self method is called on the implementing object:
  • read_buffer must always return the same value, if called multiple times.
  • The memory specified by the pointer and size returned by read_buffer must not be freed as long as self is not dropped.

To make this easier to find it could probably be added to the methods as well.

[jonas-schievink]

That also does not seem to include any obligations that need to be upheld by the caller of the method. If there are none, the function can be made safe while keeping just the trait unsafe.

[thalesfragoso]

...which makes it sound like even a subsequent call to read_buffer would be unsafe.

Did you mean write_buffer ?

The functions are unsafe to allow for implementations for types like Vec, just like StableDeref, but we decided to be more clear since we deal with raw pointers.