update text about the lint

Author: folkertdev

text/0000-cmse-calling-conventions.md

@@ -99,12 +99,12 @@ Currently both ABIs disallow the use of c-variadics. For `cmse-nonsecure-entry`,
 - but accepts c-variadic nonsecure calls: https://godbolt.org/z/5rdK58ar4
 
 For `cmse-nonsecure-call`, we may stabilize c-variadics at some point in the future.
-### Warn on unions crossing the secure boundary
+### Warn on partially uninitialized values crossing the secure boundary
 
-Unions can contain uninitialized memory, and this uninitialized memory can contain stale secure information. Clang warns when union values cross the security boundary (see https://godbolt.org/z/vq9xnrnEs), and rust does the same.
+Unions and types with padding or niches can contain uninitialized memory, and this uninitialized memory can contain stale secure information. Clang warns when union values cross the security boundary (see https://godbolt.org/z/vq9xnrnEs), and rust does the same.
 
 ```
-warning: passing a union across the security boundary may leak information
+warning: passing a (partially) uninitialized value across the secure boundary may leak information
   --> $DIR/params-via-stack.rs:43:41
    |
 LL |     f4: extern "cmse-nonsecure-call" fn(MaybeUninit<u64>),
@@ -113,11 +113,26 @@ LL |     f4: extern "cmse-nonsecure-call" fn(MaybeUninit<u64>),
    = note: the bytes not used by the current variant may contain stale secure data
 ```
 
-Like clang, the lint is emitted at the use site. That means that in the case where passing such a value is deliberate, each use site can be annotated with `#[allow(cmse_uninitialized_leak)]`.
+Like clang, the lint is emitted at the use site. That means that in the case where passing such a value is deliberate, each use site can be annotated with `#[allow(cmse_uninitialized_leak)]`. In most cases this lint should be considered an error, and an alternative way of returning/passing the value should be found that does not run the risk of leaking secure information.
 
-A `cmse-nonsecure-call` function call will emit a warning when any of its arguments is or contains a union, and a `cmse-nonsecure-entry` function warns at any (implicit) return when the return type is or contains a union.
+The lint is implemented in https://github.com/rust-lang/rust/pull/147697, and checks whether transmuting a type `T` to `[u8; size_of::<T>]` is valid. The transmute is only valid when all bytes of `T` are guaranteed to be initialized.
 
-There are other types that may contain uninitialized memory, for instance in padding bytes or in niches. Currently passing such types does not emit a warning because there is no straightforward way in the compiler to check whether a type may be (partially) uninitialized. We are of course free to extend this lint in the future when emitting the lint correctly in more cases becomes feasible.
+```rust
+#[repr(C)]
+struct PaddedStruct {
+    a: u8,
+	// There is a byte of padding here.
+    b: u16,
+}
+
+#[no_mangle]
+extern "cmse-nonsecure-entry" fn padded_struct() -> PaddedStruct {
+    PaddedStruct { a: 0, b: 1 }
+    //~^ WARN passing a (partially) uninitialized value across the security boundary may leak information
+}
+```
+
+A `cmse-nonsecure-call` function call will emit a warning when any of its arguments has a partially uninitialized type, and a `cmse-nonsecure-entry` function warns at any (implicit) return when the return type may be partially uninitialized.
 
 Ultimately guaranteeing the security properties of the system is up to the programmer, but warning on types with potentially uninitialized memory is a helpful signal that the compiler can provide.
 ## Background