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!

[PLeVasseur]

@iglesias & @pellico -- I've added the topics from the Unsafe Coding Guidelines Reference Glossary you'd like to review!

[PLeVasseur]

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"

@adfernandes -- from what I'm reading this is more to the mission of filling in broader safety-critical Rust coding guidelines, which I think is great! Since these are a number of different categories, outside of the realm of unsafe, I'd like to keep track of them properly.

What do you think about opening an issue for each so they can be tracked and worked?

[PLeVasseur]

Hey folks -- I'm considering how we want to frame up the contributions we'll make to Learn unsafe Rust.

Much like how the practicum chapter draft could be an introduction and walkthrough to the book, I think it makes sense to gather references and drafts under folders in this repo to prepare for contribution.

For example, if you've taken ABI (of a type), you can reference that it'd go under ABI and FFI. So the structure could look like:

coding-guidelines/initiatives/safe-use-of-unsafe-guidelines/learn_unsafe_rust/core_safety/abi_and_ffi.md

to match the Learn unsafe Rust book structure.

I updated the first comment with a mapping from Unsafe Coding Guidelines Reference Glossary -> Learn unsafe Rust that can be referenced to find where your contribution would go in this folder structure.

[PLeVasseur]

So I got to thinking that it may make a nice focus for our work if we chose topics from the glossary which can feed into becoming a chapter for the Learn unsafe Rust book. Each person could still take a few topics and we could still (maybe should have!) topic overlap. The intent to make those few topics focused towards being able to eventually write a chapter. I made this an agenda item for our meeting tomorrow, so let's chat more about it there.

[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"

@adfernandes -- from what I'm reading this is more to the mission of filling in broader safety-critical Rust coding guidelines, which I think is great! Since these are a number of different categories, outside of the realm of unsafe, I'd like to keep track of them properly.

What do you think about opening an issue for each so they can be tracked and worked?

@PLeVasseur I'm happy to open an issue for each, but I'd like to bring up my comment from the pull request.

I think there really needs to be a distinction (and separation) between "Unsafe Rust" and "Safety-Critical Unsafe Rust"... I'm just not certain exactly what that is right now, without some thought...

See, for example this project / comment about a codebase that's littered with unsafe *char references because the author decided that Path and PathRef didn't meet their needs. With "lots of testing" [sic], why exactly is this "bad"? (I mean, it is 😄 but what would you write in a standards document to help rule it out?)

The upcoming MISRA guidelines will help, I'm supposing... but what additional burden of proof does "unsafe" require that, for example, recursive mutexes (and hence the possibility of deadlock) do or don't?

[squell]

@PLeVasseur

I'd be willing to review the currently open items:

• Niche
• Padding

Also, I'm interested in the rabbit hole that might be:

• Aliasing (and, probably, the more people look at this, the better)

Of course several of these things have overlap (e.g. "representation" and "niche" and "padding").

[PLeVasseur]

Hey @adfernandes -- yeah it makes sense to have some discussion on this in our meeting today. I feel like it dovetails a bit with the discussions we had last time on where to draw the the line on unsafe with @pellico. 🤔

I think there really needs to be a distinction (and separation) between "Unsafe Rust" and "Safety-Critical Unsafe Rust"... I'm just not certain exactly what that is right now, without some thought...

[adfernandes]

@PLeVasseur I knew I was remembering something like a pre-existing "safety critical Rust book" from somewhere, and I finally remembered / found it: there's a group I'm not familiar with writing a book on High Assurance Rust.

I've only skimmed the book, but it seems to start at the beginning and slowing grow to more advanced topics.

Not certain what the authors' affiliations are, if any, or of they're on the committee or not.

Edit: I think I found the repo owner - Tiemoko Ballo - who is at 1Password. I know they use Rust extensively in their back end, so I'm guessing that Tiemoko's personal repo refers to "data security safety".

[pellico]

I am interested in ABI & FFI chapter.

[VinEckSie]

Pointer Aliasing, interested people for me. Thx.

[vapdrs]

Here are my notes from the 2025-01-15 meeting about the Learn unsafe Rust volunteers,

• Markus Hosch volunteers to be responsible for “ABI and FFI”
• Oreste Bernardi is interested in “ABI and FFI”
• Chistof Petig is interested in “ABI and FFI”
• Joe Johnson is interested in “ABI and FFI”
• Pete LeVasseur volunteers to be responsible for “Pointer aliasing”
• Marc Schoolderman is interested in “Pointer aliasing”
• Alexandru Vochescu is interested in “Pointer aliasing”
• Jonas Wolf volunteers to be responsible for “Intrinsics”
• Douglas Deslauriers is interested in “Intrinsics”

[PLeVasseur]

Thanks @vapdrs for pulling together the list from our meeting! I've updated the table in the first comment with folks that were in the meeting.

Folks who expressed interest, but were not in the meeting (IIRC?) @iglesias, @Dillonmcewan --

@iglesias -- I moved your name to the table for Pointer aliasing under Interested. If you'd like to be Responsible that works, or be working on another chapter, that works too.

@Dillonmcewan -- do you still see yourself contributing and if so, under which chapter of the Learn unsafe Rust book I highlight at the bottom of the first post?

Once I've cleared up all the contributions currently, I'll rework the first post, including removing the "Unsafe Coding Guidelines (UCG) Reference Glossary Topics & Folks Interested" to make it a bit easier to parse.

[PLeVasseur]

@darkwisebear, @vjonaswolf -- could you folks create tracking issues for the chapters you're responsible for?

I'll do the same for the Dangling and unaligned pointers chapter. :)

[darkwisebear]

@darkwisebear, @vjonaswolf -- could you folks create tracking issues for the chapters you're responsible for?

I've created #150 for the ABI and FFI topic, with a list of potential topics to cover. Please have a look and feel free to add content ideas; I'll provide an initial draft soon(tm).

[VinEckSie]

People interested about pointer aliasing being already 3, can you put me in Intrinsics interested people ?

Thx.

[PLeVasseur]

I'll do the same for the Dangling and unaligned pointers chapter. :)

Done! Put this as #151

[Dillonmcewan]

Hi @PLeVasseur, I've been traveling so unfortunately wasn't able to respond to your comment until now. I don't know if I'll have much time to contribute in the short term, but would like to stay involved in some way. I'm happy to help with reviewing/proof reading any content. I did some research on the following topics, so would probably be the most helpful with those sections:

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

[PLeVasseur]

Hey @Dillonmcewan -- in that case, I'd rather not sign you up directly for an interested category unless you'd slot yourself into one of the three buckets currently started:

• intrinsics
• dangling and unaligned pointers
• ABI and FFI

If you'd count yourself among the "interested", I'll note you down, but otherwise I'll go ahead and clean up the first comment to remove the previous table.

[Dillonmcewan]

Okay, that sounds good. I'll just try to keep up on this thread and help where I can!