diff --git a/lib/libsys/kexec_load.2 b/lib/libsys/kexec_load.2 new file mode 100644 --- /dev/null +++ b/lib/libsys/kexec_load.2 @@ -0,0 +1,125 @@ +.\" Copyright (c) 2025 +.\" Juniper Networks, Inc. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 26, 2025 +.Dt KEXEC_LOAD 2 +.Os +.Sh NAME +.Nm kexec_load +.Nd prepare new kernel to reboot into +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/kexec.h +.Ft int +.Fn kexec_load "uint64_t entry" "unsigned long count" \ + "struct kexec_segment *segments" "unsigned long flags" +.Sh DESCRIPTION +The +.Fn kexec_load +system call loads a new kernel that can be executed later by +.Fn reboot 2 . +.Pp +The +.Fa flags +argument is a bitmask of flags that control the operation of the call. +This argument is currently unused. +.Pp +The +.Fa entry +argument is the physical address of the entry point of the new kernel image. +.Pp +The +.Fa count +argument is the number of segments in the image, currently limited to 16. +.Pp +The +.Fa segments +argument is an array of +.Fa count +members of the following structure: +.Bd -literal -offset indent +struct kexec_segment { + void *buf; + size_t bufsz; + vm_paddr_t mem; + vm_size_t memsz; +}; +.Ed +.Pp +The +.Va buf +and +.Va bufsz +members specify a memory region in the caller's address space containing the +source of the segment. +The +.Va mem +and +.Va memsz +members specify the target physical region of the segment. +.Va bufsz +must be less than or equal to +.Va memsz , +and +.Va mem +and +.Va memsz +must be page aligned. +.Pp +The +.Fn kexec_load 2 +system call stages the kernel image in safe memory along with all +machine-dependent image data until +.Fn reboot 2 +is called with the +.Va RB_KEXEC +flag to load the image and execute the new kernel. +.Sh RETURN VALUES +The +.Fn kexec_load +system call returns 0 on success. +On failure, -1 is returned, and +.Va errno +is set to indicate the error. +.Sh ERRORS +The following errors may be returned: +.Bl -tag -width Er +.It Bq Er EINVAL +Too many segments in image. +.It Bq Er EINVAL +The value of +.Va bufsz +is larger than +.Va memsz +in one or more segments. +.It Bq Er EINVAL +Machine-dependent load error. +.It Bq Er EBUSY +Another +.Fn kexec_load +call is in progress. diff --git a/lib/libsys/reboot.2 b/lib/libsys/reboot.2 --- a/lib/libsys/reboot.2 +++ b/lib/libsys/reboot.2 @@ -126,6 +126,10 @@ is actually interpreted by the .Xr init 8 program in the newly booted system. +.It Dv RB_KEXEC +Execute a new kernel loaded via +.Fn kexec_load 2 . +If no kernel was loaded, reboot as normal. .El .Pp When no options are given (i.e., @@ -149,6 +153,7 @@ The caller is not the super-user. .El .Sh SEE ALSO +.Xr kexec_load 2 , .Xr crash 8 , .Xr halt 8 , .Xr init 8 ,