Roff Manpage

.\" Copyright (c) 2000 Whistle Communications, Inc.
.\" All rights reserved.
.\"
.\" Subject to the following obligations and disclaimer of warranty, use and
.\" redistribution of this software, in source or object code forms, with or
.\" without modifications are expressly permitted by Whistle Communications;
.\" provided, however, that:
.\" 1. Any and all reproductions of the source or object code must include the
.\"    copyright notice above and the following disclaimer of warranties; and
.\" 2. No rights are granted, in any manner or form, to use Whistle
.\"    Communications, Inc. trademarks, including the mark "WHISTLE
.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
.\"    such appears in the above copyright notice or in the software.
.\"
.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
.\" OF SUCH DAMAGE.
.\"
.\" Author: Archie Cobbs <archie@FreeBSD.org>
.\"
.Dd June 23, 2011
.Dt NG_ETHER 4
.Os
.Sh NAME
.Nm ng_ether
.Nd Ethernet netgraph node type
.Sh SYNOPSIS
.In netgraph/ng_ether.h
.Sh DESCRIPTION
The
.Nm ether
netgraph node type allows Ethernet interfaces to interact with
the
.Xr netgraph 4
networking subsystem.
Once the
.Nm
module is loaded into the kernel, a node is automatically created
for each Ethernet interface in the system.
Each node will attempt to name itself with the same name
as the associated interface.
.Pp
Three hooks are supported:
.Va lower , upper ,
and
.Va orphans .
The hook name
.Va divert
may be used as an alias for
.Va lower ,
and is provided for backward compatibility.
In reality, the two names represent the same hook.
.Pp
The
.Va lower
hook is a connection to the raw Ethernet device.
When connected, all incoming packets are forwarded to this hook,
instead of being passed to the kernel for upper layer processing.
Writing to this hook results in a raw Ethernet frame being transmitted
by the device.
Normal outgoing packets are not affected by
.Va lower
being connected.
.Pp
The
.Va upper
hook is a connection to the upper protocol layers.
When connected, all outgoing packets are forwarded to this hook,
instead of being transmitted by the device.
Writing to this hook results in a raw Ethernet frame being received by
the kernel just as if it had come in over the wire.
Normal incoming packets are not affected by
.Va upper
being connected.
.Pp
The
.Va orphans
hook is equivalent to
.Va lower ,
except that only unrecognized packets (that would otherwise be discarded)
are written to the hook, while other normal incoming traffic is unaffected.
Unrecognized packets written to
.Va upper
will be forwarded back out to
.Va orphans
if connected.
.Pp
In all cases, frames are raw Ethernet frames with the standard
14 byte Ethernet header (but no checksum).
.Pp
When no hooks are connected,
.Va upper
and
.Va lower
are in effect connected together,
so that packets flow normally upwards and downwards.
.Sh HOOKS
This node type supports the following hooks:
.Bl -tag -width ".Va orphans"
.It Va lower
Connection to the lower device link layer.
.It Va upper
Connection to the upper protocol layers.
.It Va orphans
Like
.Va lower ,
but only receives unrecognized packets.
.El
.Sh CONTROL MESSAGES
This node type supports the generic control messages, plus the following:
.Bl -tag -width foo
.It Dv NGM_ETHER_GET_IFNAME Pq Ic getifname
Returns the name of the associated interface as a
.Dv NUL Ns -terminated
.Tn ASCII
string.
Normally this is the same as the name of the node.
.It Dv NGM_ETHER_GET_IFINDEX Pq Ic getifindex
Returns the global index of the associated interface as a 32 bit integer.
.It Dv NGM_ETHER_GET_ENADDR Pq Ic getenaddr
Returns the device's unique six byte Ethernet address.
.It Dv NGM_ETHER_SET_ENADDR Pq Ic setenaddr
Sets the device's unique six byte Ethernet address.
This control message is equivalent to using the
.Dv SIOCSIFLLADDR
.Xr ioctl 2
system call.
.It Dv NGM_ETHER_SET_PROMISC Pq Ic setpromisc
Enable or disable promiscuous mode.
This message includes a single 32 bit integer flag that enables or
disables promiscuous mode on the interface.
Any non-zero value enables promiscuous mode.
.It Dv NGM_ETHER_GET_PROMISC Pq Ic getpromisc
Get the current value of the node's promiscuous flag.
The returned value is always either one or zero.
Note that this flag reflects the node's own promiscuous setting
and does not necessarily reflect the promiscuous state of the actual
interface, which can be affected by other means (e.g.,
.Xr bpf 4 ) .
.It Dv NGM_ETHER_SET_AUTOSRC Pq Ic setautosrc
Sets the automatic source address override flag.
This message includes a single 32 bit integer flag that causes
all outgoing packets to have their source Ethernet
address field overwritten with the device's unique Ethernet address.
If this flag is set to zero, the source address in outgoing packets
is not modified.
The default setting for this flag is disabled.
.It Dv NGM_ETHER_GET_AUTOSRC Pq Ic getautosrc
Get the current value of the node's source address override flag.
The returned value is always either one or zero.
.It Dv NGM_ETHER_ADD_MULTI Pq Ic addmulti
Join Ethernet multicast group.
This control message is equivalent to using the
.Dv SIOCADDMULTI
.Xr ioctl 2
system call.
.It Dv NGM_ETHER_DEL_MULTI Pq Ic delmulti
Leave Ethernet multicast group.
This control message is equivalent to using the
.Dv SIOCDELMULTI
.Xr ioctl 2
system call.
.It Dv NGM_ETHER_DETACH Pq Ic detach
Detach from underlying Ethernet interface and shut down node.
.El
.Sh SHUTDOWN
Upon receipt of the
.Dv NGM_SHUTDOWN
control message, all hooks are disconnected, promiscuous mode is disabled,
but the node is not removed.
Node can be shut down only using
.Dv NGM_ETHER_DETACH
control message.
If the interface itself is detached (e.g., because of PC Card removal), the
node disappears as well.
.Sh EXAMPLES
This command dumps all unrecognized packets received by the
.Dq Li fxp0
interface to standard output decoded in hex and
.Tn ASCII :
.Pp
.Dl "nghook -a fxp0: orphans"
.Pp
This command sends the contents of
.Pa sample.pkt
out the interface
.Dq Li fxp0 :
.Pp
.Dl "cat sample.pkt | nghook fxp0: orphans"
.Pp
These commands insert an
.Xr ng_tee 4
node between the
.Va lower
and
.Va upper
protocol layers, which can be used for
tracing packet flow, statistics, etc.:
.Bd -literal -offset indent
ngctl mkpeer fxp0: tee lower right
ngctl connect fxp0: lower upper left
.Ed
.Sh SEE ALSO
.Xr arp 4 ,
.Xr netgraph 4 ,
.Xr netintro 4 ,
.Xr ifconfig 8 ,
.Xr ngctl 8 ,
.Xr nghook 8
.Sh AUTHORS
.An Julian Elischer Aq Mt julian@FreeBSD.org
.An Archie Cobbs Aq Mt archie@FreeBSD.org
.Sh BUGS
The automatic KLD module loading mechanism that works for most
other Netgraph node types does not work for the
.Nm ether
node type,
because
.Nm ether
nodes are not created on demand; instead, they are created when
Ethernet interfaces are attached or when the KLD is first loaded.
Therefore, if the KLD is not statically compiled into the kernel,
it is necessary to load the KLD manually in order to bring the
.Nm ether
nodes into existence.

.\"
.\" Copyright (c) 2003 Hiten Pandya <hmp@FreeBSD.org>
.\" Copyright (c) 2009-2010 The FreeBSD Foundation
.\" All rights reserved.
.\"
.\" Portions of this software were developed at the Centre for Advanced
.\" Internet Architectures, Swinburne University of Technology, Melbourne,
.\" Australia by Lawrence Stewart under sponsorship from the FreeBSD
.\" Foundation.
.\"
.\" 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,
.\"    without modification, immediately at the beginning of the file.
.\" 2. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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 April 26, 2010
.Dt ALQ 9
.Os
.Sh NAME
.Nm alq ,
.Nm alq_open_flags ,
.Nm alq_open ,
.Nm alq_writen ,
.Nm alq_write ,
.Nm alq_flush ,
.Nm alq_close ,
.Nm alq_getn ,
.Nm alq_get ,
.Nm alq_post_flags ,
.Nm alq_post
.Nd Asynchronous Logging Queues
.Sh SYNOPSIS
.In sys/alq.h
.Ft int
.Fo alq_open_flags
.Fa "struct alq **app"
.Fa "const char *file"
.Fa "struct ucred *cred"
.Fa "int cmode"
.Fa "int size"
.Fa "int flags"
.Fc
.Ft int
.Fo alq_open
.Fa "struct alq **app"
.Fa "const char *file"
.Fa "struct ucred *cred"
.Fa "int cmode"
.Fa "int size"
.Fa "int count"
.Fc
.Ft int
.Fn alq_writen "struct alq *alq" "void *data" "int len" "int flags"
.Ft int
.Fn alq_write "struct alq *alq" "void *data" "int flags"
.Ft void
.Fn alq_flush "struct alq *alq"
.Ft void
.Fn alq_close "struct alq *alq"
.Ft struct ale *
.Fn alq_getn "struct alq *alq" "int len" "int flags"
.Ft struct ale *
.Fn alq_get "struct alq *alq" "int flags"
.Ft void
.Fn alq_post_flags "struct alq *alq" "struct ale *ale" "int flags"
.Ft void
.Fn alq_post "struct alq *alq" "struct ale *ale"
.Sh DESCRIPTION
The
.Nm
facility provides an asynchronous fixed or variable length recording
mechanism, known as Asynchronous Logging Queues.
It can record to any
.Xr vnode 9 ,
thus providing the ability to journal logs to character
devices as well as regular files.
All functions accept a
.Vt "struct alq"
argument, which is an opaque type that maintains state information
for an Asynchronous Logging Queue.
The logging facility runs in a separate kernel thread, which services
all log entry requests.
.Pp
An
.Dq asynchronous log entry
is defined as
.Vt "struct ale" ,
which has the following members:
.Bd -literal -offset indent
struct ale {
	intptr_t	ae_bytesused;	/* # bytes written to ALE. */
	char		*ae_data;	/* Write ptr. */
	int		ae_pad;		/* Unused, compat. */
};
.Ed
.Pp
An
.Nm
can be created in either fixed or variable length mode.
A variable length
.Nm
accommodates writes of varying length using
.Fn alq_writen
and
.Fn alq_getn .
A fixed length
.Nm
accommodates a fixed number of writes using
.Fn alq_write
and
.Fn alq_get ,
each of fixed size (set at queue creation time).
Fixed length mode is deprecated in favour of variable length mode.
.Sh FUNCTIONS
The
.Fn alq_open_flags
function creates a new variable length asynchronous logging queue.
The
.Fa file
argument is the name of the file to open for logging.
If the file does not yet exist,
.Fn alq_open
will attempt to create it.
The
.Fa cmode
argument will be passed to
.Fn vn_open
as the requested creation mode, to be used if the file will be created by
.Fn alq_open .
Consumers of this API may wish to pass
.Dv ALQ_DEFAULT_CMODE ,
a default creation mode suitable for most applications.
The
.Fa cred
argument specifies the credentials to use when opening and performing I/O on the file.
The
.Fa size
argument sets the size (in bytes) of the underlying queue.
The ALQ_ORDERED flag may be passed in via
.Fa flags
to indicate that the ordering of writer threads waiting for a busy
.Nm
to free up resources should be preserved.
.Pp
The deprecated
.Fn alq_open
function is implemented as a wrapper around
.Fn alq_open_flags
to provide backwards compatibility to consumers that have not been updated to
utilise the newer
.Fn alq_open_flags
function.
It passes all arguments through to
.Fn alq_open_flags
untouched except for
.Fa size
and
.Fa count ,
and sets
.Fa flags
to 0.
To create a variable length mode
.Nm ,
the
.Fa size
argument should be set to the size (in bytes) of the underlying queue and the
.Fa count
argument should be set to 0.
To create a fixed length mode
.Nm ,
the
.Fa size
argument should be set to the size (in bytes) of each write and the
.Fa count
argument should be set to the number of
.Fa size
byte chunks to reserve capacity for.
.Pp
The
.Fn alq_writen
function writes
.Fa len
bytes from
.Fa data
to the designated variable length mode queue
.Fa alq .
If
.Fn alq_writen
could not write the entry immediately and
.Dv ALQ_WAITOK
is set in
.Fa flags ,
the function will be allowed to
.Xr msleep_spin 9
with the
.Dq Li alqwnord
or
.Dq Li alqwnres
wait message.
A write will automatically schedule the queue
.Fa alq
to be flushed to disk.
This behaviour can be controlled by passing ALQ_NOACTIVATE via
.Fa flags
to indicate that the write should not schedule
.Fa alq
to be flushed to disk.
.Pp
The deprecated
.Fn alq_write
function is implemented as a wrapper around
.Fn alq_writen
to provide backwards compatibility to consumers that have not been updated to
utilise variable length mode queues.
The function will write
.Fa size
bytes of data (where
.Fa size
was specified at queue creation time) from the
.Fa data
buffer to the
.Fa alq .
Note that it is an error to call
.Fn alq_write
on a variable length mode queue.
.Pp
The
.Fn alq_flush
function is used for flushing
.Fa alq
to the log medium that was passed to
.Fn alq_open .
If
.Fa alq
has data to flush and is not already in the process of being flushed, the
function will block doing IO.
Otherwise, the function will return immediately.
.Pp
The
.Fn alq_close
function will close the asynchronous logging queue
.Fa alq
and flush all pending write requests to the log medium.
It will free all resources that were previously allocated.
.Pp
The
.Fn alq_getn
function returns an asynchronous log entry from
.Fa alq ,
initialised to point at a buffer capable of receiving
.Fa len
bytes of data.
This function leaves
.Fa alq
in a locked state, until a subsequent
.Fn alq_post
or
.Fn alq_post_flags
call is made.
If
.Fn alq_getn
could not obtain
.Fa len
bytes of buffer immediately and
.Dv ALQ_WAITOK
is set in
.Fa flags ,
the function will be allowed to
.Xr msleep_spin 9
with the
.Dq Li alqgnord
or
.Dq Li alqgnres
wait message.
The caller can choose to write less than
.Fa len
bytes of data to the returned asynchronous log entry by setting the entry's
ae_bytesused field to the number of bytes actually written.
This must be done prior to calling
.Fn alq_post .
.Pp
The deprecated
.Fn alq_get
function is implemented as a wrapper around
.Fn alq_getn
to provide backwards compatibility to consumers that have not been updated to
utilise variable length mode queues.
The asynchronous log entry returned will be initialised to point at a buffer
capable of receiving
.Fa size
bytes of data (where
.Fa size
was specified at queue creation time).
Note that it is an error to call
.Fn alq_get
on a variable length mode queue.
.Pp
The
.Fn alq_post_flags
function schedules the asynchronous log entry
.Fa ale
(obtained from
.Fn alq_getn
or
.Fn alq_get )
for writing to
.Fa alq .
The ALQ_NOACTIVATE flag may be passed in via
.Fa flags
to indicate that the queue should not be immediately scheduled to be flushed to
disk.
This function leaves
.Fa alq
in an unlocked state.
.Pp
The
.Fn alq_post
function is implemented as a wrapper around
.Fn alq_post_flags
to provide backwards compatibility to consumers that have not been updated to
utilise the newer
.Fn alq_post_flags
function.
It simply passes all arguments through to
.Fn alq_post_flags
untouched, and sets
.Fa flags
to 0.
.Sh IMPLEMENTATION NOTES
The
.Fn alq_writen
and
.Fn alq_write
functions both perform a
.Xr bcopy 3
from the supplied
.Fa data
buffer into the underlying
.Nm
buffer.
Performance critical code paths may wish to consider using
.Fn alq_getn
(variable length queues) or
.Fn alq_get
(fixed length queues) to avoid the extra memory copy.
Note that a queue remains locked between calls to
.Fn alq_getn
or
.Fn alq_get
and
.Fn alq_post
or
.Fn alq_post_flags ,
so this method of writing to a queue is unsuitable for situations where the
time between calls may be substantial.
.Sh LOCKING
Each asynchronous logging queue is protected by a spin mutex.
.Pp
Functions
.Fn alq_flush
and
.Fn alq_open
may attempt to acquire an internal sleep mutex, and should
consequently not be used in contexts where sleeping is
not allowed.
.Sh RETURN VALUES
The
.Fn alq_open
function returns one of the error codes listed in
.Xr open 2 ,
if it fails to open
.Fa file ,
or else it returns 0.
.Pp
The
.Fn alq_writen
and
.Fn alq_write
functions return
.Er EWOULDBLOCK
if
.Dv ALQ_NOWAIT
was set in
.Fa flags
and either the queue is full or the system is shutting down.
.Pp
The
.Fn alq_getn
and
.Fn alq_get
functions return
.Dv NULL
if
.Dv ALQ_NOWAIT
was set in
.Fa flags
and either the queue is full or the system is shutting down.
.Pp
NOTE: invalid arguments to non-void functions will result in
undefined behaviour.
.Sh SEE ALSO
.Xr syslog 3 ,
.Xr kproc 9 ,
.Xr ktr 9 ,
.Xr msleep_spin 9 ,
.Xr vnode 9
.Sh HISTORY
The
Asynchronous Logging Queues (ALQ) facility first appeared in
.Fx 5.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm
facility was written by
.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org
and extended by
.An Lawrence Stewart Aq Mt lstewart@freebsd.org .
.Pp
This manual page was written by
.An Hiten Pandya Aq Mt hmp@FreeBSD.org
and revised by
.An Lawrence Stewart Aq Mt lstewart@freebsd.org .

.\"     $NetBSD: panic.9,v 1.2 1996/10/09 17:20:04 explorer Exp $
.\"
.\" SPDX-License-Identifier: BSD-4-Clause
.\"
.\" Copyright (c) 1996 Michael Graff.
.\" All rights reserved.
.\" Copyright (c) 2023 The FreeBSD Foundation
.\"
.\" Portions of this documentation were written by Mitchell Horne
.\" under sponsorship from the FreeBSD Foundation.
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed by Michael Graff
.\"      for the NetBSD Project.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 March 17, 2023
.Dt PANIC 9
.Os
.Sh NAME
.Nm panic
.Nd bring down system on fatal error
.Sh SYNOPSIS
.In sys/types.h
.In sys/systm.h
.Vt extern char *panicstr;
.Ft void
.Fn panic "const char *fmt" ...
.Ft void
.Fn vpanic "const char *fmt" "va_list ap"
.Fn KERNEL_PANICKED
.Sh DESCRIPTION
The
.Fn panic
and
.Fn vpanic
functions terminate the running system.
The message
.Fa fmt
is a
.Xr printf 3
style format string.
The message is printed to the console and
.Va panicstr
is set pointing to the address of the message text.
This can be retrieved from a core dump at a later time.
.Pp
Upon entering the
.Fn panic
function the panicking thread disables interrupts and calls
.Xr critical_enter 9 .
This prevents the thread from being preempted or interrupted while the system
is still in a running state.
Next, it will instruct the other CPUs in the system to stop.
This synchronizes with other threads to prevent concurrent panic conditions
from interfering with one another.
In the unlikely event of concurrent panics, only one panicking thread will proceed.
.Pp
Control will be passed to the kernel debugger via
.Fn kdb_enter .
This is conditional on a debugger being installed and enabled by the
.Va debugger_on_panic
variable; see
.Xr ddb 4
and
.Xr gdb 4 .
The debugger may initiate a system reset, or it may eventually return.
.Pp
Finally,
.Xr kern_reboot 9
is called to restart the system, and a kernel dump will be requested.
If
.Fn panic
is called recursively (from the disk sync routines, for example),
.Fn kern_reboot
will be instructed not to sync the disks.
.Pp
The
.Fn vpanic
function implements the main body of
.Fn panic .
It is suitable to be called by functions which perform their own
variable-length argument processing.
In all other cases,
.Fn panic
is preferred.
.Pp
The
.Fn KERNEL_PANICKED
macro is the preferred way to determine if the system has panicked.
It returns a boolean value.
Most often this is used to avoid taking an action that cannot possibly succeed
in a panic context.
.Sh EXECUTION CONTEXT
.\" TODO: This text describes the kernel debugger / kernel dump execution
.\" context as well. It could be moved to a future kdb(9) page, and this
.\" section would become a pointer.
Once the panic has been initiated, code executing in a panic context is subject
to the following restrictions:
.Bl -bullet
.It
Single-threaded execution.
The scheduler is disabled, and other CPUs are stopped/forced idle.
Functions that manipulate the scheduler state must be avoided.
This includes, but is not limited to,
.Xr wakeup 9
and
.Xr sleepqueue 9
functions.
.It
Interrupts are disabled.
Device I/O (e.g. to the console) must be achieved with polling.
.It
Dynamic memory allocation cannot be relied on, and must be avoided.
.It
Lock acquisition/release will be ignored, meaning these operations will appear
to succeed.
.It
Sleeping on a resource is not strictly prohibited, but will result in an
immediate return from the sleep function.
Time-based sleeps such as
.Xr pause 9
may be performed as a busy-wait.
.El
.Sh RETURN VALUES
The
.Fn panic
and
.Fn vpanic
functions do not return.
.Sh SEE ALSO
.Xr printf 3 ,
.Xr ddb 4 ,
.Xr gdb 4 ,
.Xr KASSERT 9 ,
.Xr kern_reboot 9