Create new man page sysctl_machdep(4) to document the machdep namespace

[felix.the.red_gmail.com]

Summary

Most of the sysctl variables under the machdep namespace and machdep.mitigations namespace are not documented.
I created a new man page to bring all of these sysctl variables together.

I'm still not sure what a pvo is for PowerPC.

PR: 259425

[koobs]

Thanks Felix!

Would machdep_sysctl feel odd without a machdep counterpart?

Given the existing pattern of a SYSCTL section in $component(sektion) manual pages, might a machdep (without the prefix) man page name be more suitable, including an introduction about what machdep 'is', or are there are existing examples of sysctl_ prefixed manual pages?

Alternatively, might $component_sysctl(sektion), ie a _sysctl suffix pattern be more suitable, such that any existing manual page can choose to have an 'extended' and dedicated sysctl manual page. I know there are frequent questions like 'what are the sysctl's for this thing' in the community.

I don't know what what precedents / mechanisms there are in manpage culture and implementation for 'namespaced manual pages', but I think the naming/namespace question is an interesting one.

[mhorne]

Hi, this is an interesting patch! Thanks for your effort.

I believe most sysctls under the machdep.mitigation namespace would be best documented in the security(7) man page. This is where many are documented already.

As for the rest... I do not think one large catch-all man page is the right approach. By their nature, sysctls under machdep are usually platform dependent, and cover a wide range of topics/functionality. IMO it is confusing for a single man page to touch on such varying topics as signal delivery, virtual memory translation features, and VGA aspect ratios, for example.
Maybe we can find a more fine-grained approach to this? Ideally these sysctls would be documented alongside the relevant functionality (e.g. machdep.efi_rt_handle_faults might be able to go directly in efidev(4)), but this is not always possible.

[felix.the.red_gmail.com]

My overall goal is to document sysctls, and I wasn't sure where to put these.
I originally wondered if there was an i386 man page or amd64 man page, but couldn't find one.

Reading through these sysctls, several of them mentioned that being in machdep was
an accident of history and they should be moved to hw or kern.
Similarly, several of them had identically named sysctls under hw.

If we could find locations closer to the functionality, I would do away with this page and
patch the other pages.
What would we do with sysctls that don't find a home?

[pauamma_gundo.com]

So I don't mention it everywhere it's present: should "x86" be "i386" to match FreeBSD nomenclature?

Losing focus and it's past my bedtime. Will continue reviewing later.

share/man/man4/sysctl_machdep.4

35

8 or 3? (Leaning toward 3 myself, since they're accessible to userland in general, not just sysctl(8).

40

Or perhaps "some machine-dependent behavior". The intent is to make clearer not all of it is user-controllable.

73

87

104

"tunable" meaning "can be set in the loader only"? If I'm correct, should it be listed in an architecture-specific section of loader.conf(5) as well/instead? (Also, perhaps clarify "tunable". What do sysctl sections other manual pages say for those?

113

121

125

127

128

136

Do all x86 generations FreeBSD still support have it? I vaguely remember it came with Pentium, but don't remember when 486 support was/will be dropped.

142

Same question as above.

158

Should "by" be either "around" or "inside"? Not sure what you mean here.

160

161

Or perhaps "to call them", but previous sysctls repeat the object.

168

Is Elan support (still) controlled by a config(5) option? It seems to be on 12.2, not sure about 13 or -current.

171

174

Same question as above about Elan support.

179

180

Either "enable it" or "enable system panic via keypress", I think.

181

Same as above.

191–192

s/able/able fastcopying/g maybe? Probably taste.

215

While I'm at it: "or" or "and"? Since both values are possible, I'm leaning toward "and", but some may understand "and" to mean "both at the same time". (If going for "and", keep it consistent with other boolean-like options.)

217

Perhaps out of scope for this review, but check there's a reference in the other direction in loader.conf(5).

226

How do boolean/true/false here differ from int/0/1 elsewhere? Specifically, are the values represented as strings, or as (unsigned) ints?

231

234

Why is there no line break after "false" here and one after "true" below (twice)?

234–235

See question under "Boolean" above.

244

Hyphen or no hyphen?

248–249

254–255

272

Where does this markup put the "."? If inside (), also needs one in the line above.

284

Define "short"?

286

297–298

299

322

Maybe. Redundancy is good for clarity sometimes.

328

333

336

347

Hyphen or no hyphen?

374

Either s/for /if /g or use "being" and "not being" instead of "is (not)".

376

382

Or maybe "for (en|dis)abling" for consistency with "for" on ,next line.

394

Or "for disabling"

397

See above.

[pauamma_gundo.com]

And done.

share/man/man4/sysctl_machdep.4

482–483

510–511

523

Or "for autodetection".

529–530

"between saving the system time to the realtime clock" and what? If it's the minimum time between successive saves, it should be made clearer.

564–565

577

582

585

591

Is this read-write or read-only?

594

[gbe]

@felix.the.red_gmail.com did you find the time add the suggestions that were made?

I would like to see this commit since it quite a good addition to the man pages.