Docs: clarify how PAC usage is "unsafe"

[natevw]

In the Embassy book here

embassy/docs/pages/layer_by_layer.adoc

Line 11 in ef32187

The PAC is the lowest API for accessing peripherals and registers, if you don't count reading/writing directly to memory addresses. It provides distinct types to make accessing peripheral registers easier, but it does not prevent you from writing unsafe code.

the claim is made that a PAC:

does not prevent you from writing unsafe code.

It goes on to give an example blinky app using PAC, which at no point uses any actual unsafe blocks. So I do not understand what this introduction is trying to demonstrate. As a beginner I am wondering/guessing that it may be one of these:

• that perhaps in Rust embedded cultural practice, the entire PAC crate as a whole is simply considered unsafe and just does not mark its functions as such
  • but I don't find any mention of this in the docs for the crate itself https://docs.embassy.dev/stm32-metapac/git/stm32c011d6/index.html
  • and I see examples to the contrary in e.g. https://docs.rust-embedded.org/book/start/registers.html where some of the closures do need to deal with unsafe while most do not
• that perhaps the example is really more pseudo-code and in practice would need to be wrapped in various unsafe caveats
  • I didn't try compile/run it but the code otherwise looks like it's supposed to work as-is so I'd be a little surprised if it were broken?
  • especially since in the context I would expect the example to deliberately emphasize just how unsafe using a PAC is given the intro…
• or perhaps the introductory paragraph is using "unsafe" not in a technical Safe Rust vs. Unsafe Rust way, but more of just a colloquial e.g. "you might configure a register wrong and then your code/board won't work right"?
  • but you could still make those sorts of logic/hardware mistakes with a HAL crate to some extent too
  • and honestly it seems unlikely given the marketing around Rust that such a core term as "unsafe code" would get used generically/casually when talking about low-level API options here

So none of these guesses seems quite right. Could the wording of this section be updated to clarify what it's trying to say?

[lulf]

  * but you could still make those sorts of logic/hardware mistakes with a HAL crate to some extent too
  * and honestly it seems unlikely given the marketing around Rust that such a core term as "unsafe code" would get used generically/casually when talking about low-level API options here

This is probably the most accurate way to describe the word unsafe used in this context, and I agree it's probably the wrong term to use. The point is, with the PAC you can not only cause logic/hardware mistakes, but maybe you write to DMA registers and cause memory corruption that way.

I'll try to find some time to update the docs, otherwise feel free to create a PR with a wording you think is more accurate.

[natevw]

@lulf Thanks — opened #4259 with a take on it but feel free to tweak further.