kexec: Add basic kexec_load man page

[jhibbits]

Summary

Also add kexec reboot flag to the reboot man page.

[jhibbits]

lib/libsys/kexec_load.2

29

That date is from when I first started writing the man page. I'll update it when I'm ready to commit.

[0mp]

You'll also need to add the new manual to the Makefile.

lib/libsys/kexec_load.2

3

Refer to style(9).

In particular, the following would be enough for this copyright header:

/*
  * Copyright (c) 2025 Juniper Networks, Inc.  All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */

46

96

99

lib/libsys/reboot.2

28

You may consider bumping this date as well.

[ziaee]

lib/libsys/kexec_load.2

3

"All rights reserved" is also unnecessary. From the FreeBSD Licensing Guide:

"Historically, the phrase 'All Rights Reserved.' was included in all copyright notices. All the BSD releases had it, to comply with the Buenos Aires Convention of 1910 in the Americas. With the ratification of the Berne Convention in 2000 by Nicaragua, the Buenos Aires Convention — and the phrase — became obsolete. As such, the FreeBSD project recommends that new code omit the phrase and encourages existing copyright holders to remove it. In 2018, the project updated its templates to remove it."

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

[ziaee]

lib/libsys/kexec_load.2

37

The LIBRARY section is deprecated in the current mandoc, and now we do this instead.

126

(I don't actually know when it appeared, but this info is super useful!)

[jhibbits]

lib/libsys/kexec_load.2

126

Yes it is. I'm hoping it'll be in 15.1 (a bit late to make 15.0), but will mark it 16.0 for now, since it just hit HEAD this morning.

[jhibbits]

Address feedback from @ziaee and @0mp. Thanks!

[ziaee]

lib/libsys/kexec_load.2

13

12m13

28

I think it would be easier if the explanation of flags was sorted after segments because that's the way it flows in SYNOPSIS.

[imp]

lib/libsys/kexec_load.2

28

The flags argument is present for compatibility with Linux, although it currently must be 0.

Unused implies it can be anything and it doesn't matter.

71

Are there restrictions on where you can put the new kernel?
Are there size restrictions?

79

What happens if I call kexec_load a second time before reboot?

[jhibbits]

lib/libsys/kexec_load.2

71

Good questions, which I'll try to answer in the man page as well.

• You can only load to the physical regions listed in the vm.phys_segs sysctl. On I believe all architectures except amd64 this prevents it from overlapping the existing kernel. On x86, since the kernel is covered in one of those segments, extra care has to be taken in the kexec trampoline code to safely perform the copy and handoff.

• Size is limited to roughly half total physical memory (a little less) since it needs to perform a copy from user space into the kernel staging area, and therefore needs at one point two full copies of the image.

79

Good question, I'll update the man page to reflect it. Each subsequent call to kexec_load() replaces the previously loaded image on success. On failure the previous image remains. An easy way to unload the previous image is to kexec_load() with a segment count of 0.

[jhibbits]

Address feedback. I hope I got everything.

[ziaee]

lib/libsys/kexec_load.2

12

.Lb still needs to be moved down one line to be in SYNOPSIS

[jhibbits]

Committed as a935c2a63 (don't feel like reverting and updating the commit message)