sys/README.md
11	Maybe add reference to v6/v7 here? @imp?
12	Note that you can have an ARMv8 AArch32 binary. Maybe "64-bit ARMv8+"?
26–27	Maybe add descriptions to these while we're here? E.g. WiFi? Grab the title from the referenced man pages perhaps?
26–27	We might want to mention that this is both 32- and 64-bit

mhorne added inline comments.Oct 26 2022, 6:53 PM

sys/README.md
12	Right, so do we like: 32-bit ARMv6+ architecture support 64-bit ARMv8+ (AArch64) architecture support ?

imp added inline comments.Oct 27 2022, 6:29 AM

sys/README.md

I struggled here. I think 32-bit is a sufficient level of detail for this file, though

arm	arm (32-bit armv6+) architecture support

would also be good. I think that extra bi tis short enough and clarifying enough that it's good, even if it isn't completely correct (it's really v7 with 1 v6 cpu that has some of the v7 extensions), it's sufficient for the context and short enough to not interfere with the clarity. Though technically, mhorne is right that aarch32 (armv8) is a thing we don't separately support,, that's also generally not a thing that exists that doesn't work with our v7 support w/o taking advantage of the new v8 32-bit features.

I'd be tempted here to say kernel debugger stubs, since it's really a remote frontend rather than a debugger. I think that nuance is easy enough to convey accurately w/o getting too verbose and affecting the clarity of things.

23–25

It's really 486 and newer. I think 'i486+ (32-bit x86) architecture support' would express this nicely w/o undue verbosity.

26–27

agreed, but I'd think twice about the longer sub-types beyond that (eg poerpc64le).

26–27

64-bitt RISC-V architecture support maybe? We don't have 32-bit support at all and likely never will, but it is a thing that other system call out.

s/libc/libc-like/ maybe? or libc-subset since it's similar / subsetted libc support for the kernel. But I'd not make it much more verbose than that, and would accept that it's fine as is if you don't think this suggestion adds value. I'm finding myself a little torn, but leaning towards 'short addition to better express the nuance' over omitting.

modules

kernel module infrastructure

might be less verbose?

imp accepted this revision.Oct 27 2022, 6:30 AM

imp added inline comments.

sys/README.md
43	Would adding 'MACH-deriverd' be helpful here? I'm not sure. Even though it's short, maybe it's too confusing and I'm too picky.

This revision is now accepted and ready to land.Oct 27 2022, 6:30 AM

Handle review feedback. Improve several of the descriptions that were just man page links.

For CPU architecture entries:
Simpler is better; note the supported CPU bit-widths in every case, but do not
get into the minutia of exactly which subset of CPUs are supported.

A guiding principle for these descriptions is that it is okay if they do not
capture the entire story of the folders' contents, but they should not contain
misinformation. "32-bit ARM architecture support" makes no promises about ARMv5
support, but forgetting to bump "32-bit ARMv6+ architecture support" after a
hypothetical removal of armv6 does result in a false claim.

This revision now requires review to proceed.Oct 27 2022, 5:26 PM

Harbormaster completed remote builds in B48052: Diff 112292.Oct 27 2022, 5:26 PM

mhorne marked 9 inline comments as done.Oct 27 2022, 5:29 PM

mhorne added inline comments.

sys/README.md
23–25	I would like to note it, but i386 is the colloquial name used throughout the source tree, so it needs to be in there (also in the 'x86' entry below).
43	Thinking back to when I first started with the source tree, I think I would have found it confusing. Certainly the history is captured properly elsewhere.