Formulate Chapter Material for Learn unsafe Rust

[PLeVasseur]

Hey folks 👋 using this as the general tracking issue for contributions we'll make to Learn unsafe Rust, out of the Coding Guidelines Subcommittee.

Contribution Model

Edit: I've proposed and had accepted by members of the subcommittee to change-up how we're going to tackle fleshing out guidelines around unsafe in Rust. My intent here is to attempt to focus our work a bit to have some tangible outputs, improving the state of guidance around unsafe useful to safety-critical applications and the wider Rust community.

The process I outlined was one in which:

• we pick a handful of chapters from Learn unsafe Rust
• people that are interested raise their hands on whether they are responsible or interested
  • These definitions are not written in stone, but you could think of:
  • responsible folks generally trying to guide the process, reporting out in subcommittee meetings, taking on coordination work with the project and/or broader Rust ecosystem along with what interested folks will be doing, which is:
  • interested folks as contributing to researching on the chapter, writing material, and reviewing material contributed
• the chapter teams run for a while, making PRs into this repo, into the structure they would eventually find themselves in when a PR is opened to the Learn unsafe Rust repo
• when there's general agreement on style and content parity with existing chapters of Learn unsafe Rust we can raise a PR to try to contribute
  • I'm sure there's likely to be some suggestions here, so we'll work this until the material is deemed worthy of contribution
• when a chapter team is finished, folks that contributed can disband or pick up another chapter to work or pick up some additional way to contribute to the coding guidelines subcommittee

Chapter goal and style guidelines

In the goals for each chapter are:

• They should talk about a specific topic
• They should tell you how UB around that topic works
• They should tell you when thinking about that topic is relevant (Sometimes it's not obvious! Dealing with padding can end up with validity/uninit issues, for example)
• They should tell you common techniques for safely working with it
• They should tell you what is yet-to-be-decided on the topic, and ideally have some advice on how to work around these specification holes, or assumptions on the specification's future that can be safely made.

Lifted from guidance provided by @Manishearth here.

Mapping from Unsafe Coding Guidelines Reference Glossary to Learn unsafe Rust

A good resource to reference is the Unsafe Coding Guidelines (UCG) Reference Glossary. Below you can find a mapping between the UCG Glossary topics and Learn unsafe Rust

• Core unsafety

  • UCG: Undefined Behavior
  • ABI and FFI
    • UCG: ABI (of a type)
    • UCG: Layout?
    • UCG: Padding?
  • Dangling and unaligned pointers
  • Data races
  • Inline assembly
  • Intrinsics
  • Platform features

• Advanced unsafety

  • UCG: Soundness (of code / of a library)
  • Atomic ordering
  • Immutable data
    • UCG: Interior mutability?
  • Invalid values
    • UCG: Niche
    • UCG: Representation (relation)
    • UCG: Validity and safety invariant
    • UCG: Value
    • UCG: Zero-sized type / ZST?
  • Pinning
  • Pointer aliasing
    • UCG: Aliasing
    • UCG: Memory Address
    • UCG: Place
  • Uninitialized memory
    • UCG: Abstract Byte
    • UCG: Allocation
  • Variance

• Expert unsafety

  • Pointer provenance
    • UCG: Memory Address
    • UCG: Place
    • UCG: Pointer Provenance
  • Stacked borrows

Initial Chapters for Contribution to Learn unsafe Rust

Some (possibly biased!) ranking of chapters from Learn unsafe Rust I think would be particularly handy for a group working in a safety-critical context:

Learn unsafe Rust Chapter	Rationale	People Responsible	People Interested
ABI and FFI	Practically speaking we often need to interact with libraries written in C and C++	@darkwisebear	@pellico, @ChristofPetig, @joej357
Intrinsics	One of the first questions asked about, when proposing Rust in automotive. Useful	@vjonaswolf	@vapdrs, @VinEckSie
Dangling and unaligned pointers	Understanding aliasing can be important, as these concepts differ a bit from their C and C++ definition	@PLeVasseur	@squell, @valexandru, @iglesias

[vapdrs]

I'd like to review,

• Soundness (of code / of a library)
• Undefined Behavior
• Validity and safety invariant

[Dillonmcewan]

Interested in:

• Interior mutability
• Pointer provenance
• Zero-sized type / ZST

[Manishearth]

Based on the discussion we had yesterday in our Coding Guidelines Subcommittee meeting, I'd like to propose we divvy up entries from the glossary of the Unsafe Coding Guidelines Reference.

This is a great idea, the Learn Unsafe Rust book's chapter organization is currently a mess and we probably could do much better.

[PLeVasseur]

@Manishearth -- as we're looking to contribute to the Learn unsafe Rust book, a couple of questions:

1. Does the effort we're starting off over here to write up a bit of a practicum make sense as a contribution to Learn unsafe Rust?
2. Are there particular areas of the Learn unsafe Rust book that would make sense to flesh out in a particular order? Could help focus on the ordering of sections of the glossary we review. (Speaking just for myself, I'm relatively newbie when it comes to unsafe)

[Manishearth]

(Sorry, been extremely busy these weeks, I'm going to try and respond to this soon)

[iglesias]

Hey, nice to e-meet you, I started going through the info and I'd like to review

• Aliasing
• Allocation
• Memory Address

[PLeVasseur]

Hi @iglesias 👋

Would love to have more contributions!

Have you joined the consortium and the coding guidelines subcommittee?

Here's a link to the issue templates.

If you could do these couple of steps, I'll go ahead and add your items you're interested in into the table ✌️

[iglesias]

Hi @PLeVasseur

I opened this issue to apply for the consortium with motivation, noticed it was closed and then got the invitation through gmail to today's coding guidelines subcommittee meeting. Does it mean the application to the consortium went through?

In any case, I will open the issue for the coding guidelines subcommittee.

Thanks for the swift reply!

[pellico]

Hi @PLeVasseur ,
I would like to review:

• Undefined Behavior
• ABI
• Layout
• Soundness

[adfernandes]

I'd be happy to add sections/definitions on the following:

• Regulatory Approach (objective-based vs Risk-Based)
• Spatial Safety (à la "mutable xor shareable")
• Temporal Safety
  • concurrency, infinite loops, liveness, and deadlocks
• Modified Condition / Decision Coverage (MC/DC) verification and validation
• Integer overflow / underflow
• Functional "purity" and "side effects"

[Manishearth]

• Does the effort we're starting off over here to write up a bit of a practicum make sense as a contribution to Learn unsafe Rust?

It's a nice example, would this be like a tour through the different parts? That would work nicely as an introduction.

2. Are there particular areas of the Learn unsafe Rust book that would make sense to flesh out in a particular order? Could help focus on the ordering of sections of the glossary we review. (Speaking just for myself, I'm relatively newbie when it comes to unsafe)

Yeah even figuring out what sections the book should have, and in which order, is a huge help.

In general my goals for each chapter are:

• They should talk about a specific topic
• They should tell you how UB around that topic works
• They should tell you when thinking about that topic is relevant (Sometimes it's not obvious! Dealing with padding can end up with validity/uninit issues, for example)
• They should tell you common techniques for safely working with it
• They should tell you what is yet-to-be-decided on the topic, and ideally have some advice on how to work around these specification holes, or assumptions on the specification's future that can be safely made.

[Manishearth]

Yeah even figuring out what sections the book should have, and in which order, is a huge help.

Though I do think this should be done by someone who has a really good understanding of how unsafe works in Rust. There's a certain flow to it, many things depend on many other things.

[PLeVasseur]

It's a nice example, would this be like a tour through the different parts? That would work nicely as an introduction.

That's my thought: a tour through. Intro might be a nice idea for where it fits in.

Though I do think this should be done by someone who has a really good understanding of how unsafe works in Rust. There's a certain flow to it, many things depend on many other things.

While I serve as chair, I would not put myself among the crowd that has this level of understanding, frankly. As I've begun to learn more about unsafe, it's true that there's many interlocking pieces. Anyone else in the subcommittee that does I'd welcome to help guide section choice and ordering!