[Coding Guideline]: Ensure reads of union fields produce valid values #300

manhatsu · 2025-12-16T02:41:09Z

Added new guideline on unions by @rcseacord.

This is the same content as #270 but moved to the feature branch.

netlify · 2025-12-16T02:41:15Z

✅ Deploy Preview for scrc-coding-guidelines ready!

Name	Link
🔨 Latest commit	`99551c2`
🔍 Latest deploy log	https://app.netlify.com/projects/scrc-coding-guidelines/deploys/694b19254346670008b3828a
😎 Deploy Preview	https://deploy-preview-300--scrc-coding-guidelines.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

rcseacord · 2025-12-16T12:09:58Z

@PLeVasseur @felix91gr I did a final cleanup and this rule LGTM. Please review & approve

iglesias

I left a couple of comments. Otherwise it was all clear. One is a question about a line I wasn't sure about and the other just a typo fix suggestion.

src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc

felix91gr · 2025-12-17T02:11:24Z

@PLeVasseur @felix91gr I did a final cleanup and this rule LGTM. Please review & approve

Alright, it goes into the queue.

src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc

PLeVasseur · 2025-12-17T02:35:01Z

@PLeVasseur @felix91gr I did a final cleanup and this rule LGTM. Please review & approve

Alright, it goes into the queue.

Hey @felix91gr -- did you take a look at this one yet? I'd like it to be reviewed before we queue it up

(I'll try to make time to review some of @rcseacord's latest ones tomorrow, this included, if it's not been reviewed by you yet)

felix91gr · 2025-12-17T15:19:17Z

I'd like it to be reviewed before we queue it up

@PLeVasseur ah, sorry! I forgot we have a Merge Queue as well. I meant it as my own task queue, my bad. I haven't reviewed it yet

PLeVasseur

Hey thanks for pulling this together @manhatsu and @rcseacord

Given that adding the bibliography bit touches quite a few other things, I'd suggest backing that out of this PR if you'd like the guideline to be reviewed on its merits and merged sooner than later.

I've opened issue #306 to track the work towards the work for a bibliography.

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc

src/conf.py

manhatsu · 2025-12-19T02:39:20Z

There is a duplication of URL in these two documents:
expressions/gui_Bib7x9KmPq2nL.rst.inc and types-and-traits/gui_0cuTYG8RVYjg.rst.inc.
bibliography.md says I should consider this, but how can I actually solve this?
I think it's fine if both have the source entry...

PLeVasseur · 2025-12-19T12:47:14Z

There is a duplication of URL in these two documents: expressions/gui_Bib7x9KmPq2nL.rst.inc and types-and-traits/gui_0cuTYG8RVYjg.rst.inc. bibliography.md says I should consider this, but how can I actually solve this? I think it's fine if both have the source entry...

Yeah, you're right. I didn't have this implemented correctly. Duplicate URLs should be fine, what I wanted to have was for the same URL to force consistent referencing to be used.

I've pushed #335 which should fix this.

Please take a look at the following and rebase:
https://github.com/rustfoundation/safety-critical-rust-coding-guidelines/blob/main/docs/bibliography.md

added new guideline on unions

repaired bibliography

delete unused citations

fixing up bibliography

interim save

cleaned up

…rst.inc Co-authored-by: Fernando José <fernando.iglesiasg@gmail.com>

…rst.inc

PLeVasseur · 2025-12-23T22:38:36Z

I rebased this on main. It's building and working now.

PLeVasseur

This is somewhat a procedural review to get this in-line with current best practices as outlined in CONTRIBUTING.md.

I haven't reviewed the contents of the guideline yet.

Please update and I can then take a look through content.

PLeVasseur · 2025-12-23T22:39:28Z

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

+   If the active field is uncertain, use explicit validity checks.
+
+   .. rationale::
+      :id: rat_UnionFieldValidityReason


Please use IDs generated from ./generate_guideline_templates.py.

PLeVasseur · 2025-12-23T22:39:37Z

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

+      Reading an invalid value is undefined behavior.
+
+   .. non_compliant_example::
+      :id: non_compl_ex_UnionBool


Please use IDs generated from ./generate_guideline_templates.py.

PLeVasseur · 2025-12-23T22:39:42Z

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

+         }
+
+   .. non_compliant_example::
+      :id: non_compl_ex_UnionChar


Please use IDs generated from ./generate_guideline_templates.py.

PLeVasseur · 2025-12-23T22:41:19Z

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

+         }
+
+   .. non_compliant_example::
+      :id: non_compl_ex_UnionEnum


Please use IDs generated from ./generate_guideline_templates.py.

PLeVasseur · 2025-12-23T22:41:27Z

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

+         }
+
+   .. non_compliant_example::
+      :id: non_compl_ex_UnionRef


Please use IDs generated from ./generate_guideline_templates.py.

PLeVasseur · 2025-12-23T22:46:00Z

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

+      This noncompliant example reads a reference from a union containing a null pointer.
+      A similar problem occurs when reading a misaligned pointer.
+
+      .. code-block:: rust


Please use the .. rust-example:: directive to ensure that these are extracted and tested correctly.
I think we have this a bit loose right now. Perhaps we should fail if there's an example without a .. rust-example:: directive to ensure that this is enforced.

PLeVasseur · 2025-12-23T22:46:06Z

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

+
+      This compliant example tracks the active field explicitly to ensure valid reads.
+
+      .. code-block:: rust


Please use the .. rust-example:: directive to ensure that these are extracted and tested correctly.
I think we have this a bit loose right now. Perhaps we should fail if there's an example without a .. rust-example:: directive to ensure that this is enforced.

PLeVasseur · 2025-12-23T22:46:17Z

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

+
+      This compliant solution reads from the same field that was written.
+
+      .. code-block:: rust


Please use the .. rust-example:: directive to ensure that these are extracted and tested correctly.
I think we have this a bit loose right now. Perhaps we should fail if there's an example without a .. rust-example:: directive to ensure that this is enforced.

PLeVasseur · 2025-12-23T22:46:24Z

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

+
+      This compliant example reinterprets the value as a different types where all bit patterns are valid.
+
+      .. code-block:: rust


Please use the .. rust-example:: directive to ensure that these are extracted and tested correctly.
I think we have this a bit loose right now. Perhaps we should fail if there's an example without a .. rust-example:: directive to ensure that this is enforced.

PLeVasseur · 2025-12-23T22:46:30Z

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc

+
+      This compliant example validates bytes before reading as a constrained type.
+
+      .. code-block:: rust


Please use the .. rust-example:: directive to ensure that these are extracted and tested correctly.
I think we have this a bit loose right now. Perhaps we should fail if there's an example without a .. rust-example:: directive to ensure that this is enforced.

manhatsu mentioned this pull request Dec 16, 2025

[Coding Guideline]: Ensure reads of union fields produce valid values #270

Merged

manhatsu force-pushed the doc/union-field-validation branch from 9dc2bcd to ea2dcf2 Compare December 16, 2025 03:02

rcseacord self-assigned this Dec 16, 2025

iglesias reviewed Dec 16, 2025

View reviewed changes

src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc Outdated Show resolved Hide resolved

src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc Outdated Show resolved Hide resolved

PLeVasseur reviewed Dec 17, 2025

View reviewed changes

src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc Outdated Show resolved Hide resolved

rcseacord requested review from PLeVasseur and felix91gr December 17, 2025 13:47

felix91gr mentioned this pull request Dec 17, 2025

[Coding Rule]: Do not read from uninitialized union fields #302

Draft

PLeVasseur mentioned this pull request Dec 17, 2025

Add bibliography directive to guideline #306

Closed

PLeVasseur requested changes Dec 17, 2025

View reviewed changes

src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc Show resolved Hide resolved

src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc Outdated Show resolved Hide resolved

src/conf.py Show resolved Hide resolved

manhatsu force-pushed the doc/union-field-validation branch from 0431525 to 696e633 Compare December 19, 2025 02:27

manhatsu requested a review from PLeVasseur December 19, 2025 02:41

rcseacord and others added 11 commits December 24, 2025 07:29

Update types-and-traits.rst

47db6d9

added new guideline on unions

Apply suggestion from @rcseacord

95e8f54

Update types-and-traits.rst

be9cb93

Update types-and-traits.rst

edc14a2

repaired bibliography

fix: add bibliography entry;

8d5c834

delete unused citations

chore: put citations in table

205fc0f

fix: implement "Copy" to use enum in union

c6bd716

fix: add main function

f4a49c9

Update types-and-traits.rst

0872f3c

fixing up bibliography

Update types-and-traits.rst

a935fe0

Update types-and-traits.rst

7e2875f

rcseacord and others added 10 commits December 24, 2025 07:29

Update types-and-traits.rst

8b7306a

interim save

Update types-and-traits.rst

a7e8ff0

Update types-and-traits.rst

fc9d450

chore: enable line breaks

6d67edd

Update gui_UnionFieldValidity.rst.inc

4da5850

cleaned up

Update src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.…

03d3c63

…rst.inc Co-authored-by: Fernando José <fernando.iglesiasg@gmail.com>

Remove git cruft

a07d1aa

Update src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.…

507bd94

…rst.inc

chore: rename with unique ID

428f952

fix: bibliography style

99551c2

PLeVasseur force-pushed the doc/union-field-validation branch from 696e633 to 99551c2 Compare December 23, 2025 22:35

PLeVasseur requested changes Dec 23, 2025

View reviewed changes


		This compliant example tracks the active field explicitly to ensure valid reads.

		.. code-block:: rust


		This compliant solution reads from the same field that was written.

		.. code-block:: rust


		This compliant example reinterprets the value as a different types where all bit patterns are valid.

		.. code-block:: rust


		This compliant example validates bytes before reading as a constrained type.

		.. code-block:: rust

[Coding Guideline]: Ensure reads of union fields produce valid values #300

Are you sure you want to change the base?

[Coding Guideline]: Ensure reads of union fields produce valid values #300

Conversation

manhatsu commented Dec 16, 2025

Uh oh!

netlify bot commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for scrc-coding-guidelines ready!

Uh oh!

rcseacord commented Dec 16, 2025

Uh oh!

iglesias left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

felix91gr commented Dec 17, 2025

Uh oh!

Uh oh!

PLeVasseur commented Dec 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felix91gr commented Dec 17, 2025

Uh oh!

PLeVasseur left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

manhatsu commented Dec 19, 2025

Uh oh!

PLeVasseur commented Dec 19, 2025

Uh oh!

PLeVasseur commented Dec 23, 2025

Uh oh!

PLeVasseur left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

netlify bot commented Dec 16, 2025 •

edited

Loading

PLeVasseur commented Dec 17, 2025 •

edited

Loading