linux/aarch64: make mcontext_t.__reserved pub

[jstarks]

Description

The mcontext_t.__reserved field is documented to contain extra context, such as FP state and the ESR register.

Sources

• Linux uapi
• Glibc
• Musl
• Android

Checklist

• Relevant tests in libc-test/semver have been updated
• No placeholder or unstable values like *LAST or *MAX are
  included (see #3131)
• Tested locally (cd libc-test && cargo test --target mytarget);
  especially relevant for platforms that may not be checked in CI

@rustbot label +stable-nominated

[rustbot]

Some changes occurred in the Android module

cc @maurer

[tgross35]

Is there official documentation outside of the uapi comment saying what this field contains? The manpage I found says (link):

The mcontext_t type is machine-dependent and opaque.

Given that and the fact that the field is actually named reserved, I am hesitant to expose this. If you actually need these fields and want to opt into whatever sort of instability they have, it would be better to define your own struct and transmute.

[tgross35]

(updating status)

[jstarks]

Is there official documentation outside of the uapi comment saying what this field contains? The manpage I found says (link):

The mcontext_t type is machine-dependent and opaque.

Given that and the fact that the field is actually named reserved, I am hesitant to expose this. If you actually need these fields and want to opt into whatever sort of instability they have, it would be better to define your own struct and transmute.

The uapi header is the only documentation I am aware of. But uapi documents interfaces that are stable. I certainly agree that the __reserved name is a red flag--nonetheless, it's a guaranteed stable part of the Linux ABI and by extension the glibc/musl API. I think they're just stuck with the poor choice of name, which hasn't changed since it was introduced in 2012.

If you search around (https://github.com/search?q=__reserved+uc_mcontext&type=code), you can find lots of C/C++ code accessing this field as documented in the uapi definitions. It should be possible to port such code to Rust without manually defining types.

I suppose to really complete that promise, libc should also define _aarch64_ctx and some of the magic numbers and other types from uapi. I'd be happy to do that as well, if you think it's a good idea. musl and Android define these types in their headers but glibc does not--I would guess glibc users probably include the uapi header directly to get these definitions, but I'm not sure.

[maurer]

tl;dr: __reserved isn't defined in a way where you can do field access on it, nothing is defined on mcontext_t (only sigcontext_t), but we should probably make this pub like you suggest.

Honestly, I think that making mcontext_t fully opaque might be the "right way" be in line with spec unless individual libcs make claims in their documentation about the usability of mcontext_t fields. We'd have a separate sigcontext_t struct which exposes just the usable fields, and the fact that in for most libcs, we'd have a backend type of #[repr(transparent)] pub struct mcontext_t(sigcontext_t) would make the backing of mcontext_t implementation dependent, like it's supposed to be. All that said, I think breaking people to be pedantically right here is not worthwhile.

The uapi header is the only documentation I am aware of. But uapi documents interfaces that are stable.

The UAPI header also says "(Note: records do not necessarily occur in the order shown here.)", which means that you cannot actually read from that __reserved field in a stable way. The interface is stable, sure, but the contents of that field are not - that's why they're marked reserved. As you pointed out at the end of your last comment, you'd need several other structs to actually interpret this correctly.

it's a guaranteed stable part of the Linux ABI and by extension the glibc/musl API

This is also not true - being part of the Linux ABI doesn't automatically make it part of the libc API. A libc would be within its rights to replace all mcontext_ts with the same contents xor'd by 0x42 and just xor it back before it sends it to the kernel, since it's opaque. For a ucontext_t, only the fields uc_link, uc_sigmask, and uc_stack are guaranteed to be something you can meaningfully access.

All that said:

1. We don't currently seem to use sigcontext for Linux, which means there isn't a place to expose this correctly at the moment?
2. The UAPI header does seem to declare an explicit format for __reserved, and the similar portion of sigcontext in other archs (e.g. riscv) is required for correct use of ptrace

I think that means that we should probably make __reserved be pub, because there's a legit interface on it.

I would be a lot happier with it if you added the structs that are supposed to be used to read from it (even happier if we were allowed to put zerocopy derivations on them, but I know we can't have those in libc yet).