x86: Create manpage for mca subsystem

[jtl]

Summary

Create a manpage for the mca subsystem.

Sponsored by: Netflix

[ziaee]

share/man/man4/mca.4

6

We no longer need to write this, see

https://docs.freebsd.org/en/articles/license-guide/

28

We dropped i386. You're not going to back port this, right? Thus this is only for amd64?

[jtl]

Updated license and clarified this is only applicable to amd64 in main.

[jtl]

share/man/man4/mca.4

6

Thanks! I've updated the license text.

28

I updated this to amd64. I may actually backport this, but I can modify it as part of the MFC. There may be other changes which are needed as part of any MFC.

[markj]

Thanks for writing this.

I wonder how to make the page more discoverable. I'd think we should have platform-specific man pages which describe platform features, so amd64.4 could link to mca.4, pkru.3, etc.. But that's a larger project of course.

share/man/man4/mca.4

22

33

Should we mention the syslog facility/level?

[jhb]

share/man/man4/mca.4

33

I would perhaps say "the system log" rather than "Syslog".

65–67

This language will probably read less stale in the more distant future.

68

79

You don't have to, but if you would find it more readable, you could create a table with columns instead of a tagged list. See for example bhyve_config(5) which uses separate columns for the default value and description. siginfo(3) is another manual page that uses a .Bl -column.

In this case I could imagine a column for the name, one for if the sysctl is writable (Y/N), one for the default value, and the last for the description.

102

I don't know that Haswell needs to be quoted here?

267

Maybe Xr syslogd(8) here?

Not sure if it's worth adding a mention of mcelog in ports? (I'm not convinced mcelog is very useful)

[jtl]

share/man/man4/mca.4

33

I added the facility. The level varies with the message. I also tried to strike a compromise between your suggestion and @jhb's suggestion:
"The system log (using the LOG_KERN syslog (3) facility)"

79

Thanks for the suggestion. I can see the value of this, but I think I will leave it the way it is at the moment. I'm concerned that using a table would hurt readability. I have added commentary around the meaning of the default values. I also would add another column to indicate whether it is available as a tunable. With all of that, I'm concerned that the main text would have too narrow a column.

[jtl]

Updated to incorporate review feedback.

[ziaee]

I tried to test this, but the patch failed to apply

share/man/man4/mca.4

12

... Should we do this, so people find this page if they search the manual for x86? I don't know if they would or not.