KASSERT(9): some updates
- Add a little bit of introductory text - Improve the existing example: ANSI C, use a better assertion than a NULL check (which is discouraged) - Document the widely used MPASS macro in this page - Drop the cross-reference to config(8) Reviewed by: kib, markj, rpokala, Pau Amma <pauamma@gundo.com> MFC after: 1 week Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D39131
This commit is contained in:
Mitchell Horne
parent
43db15b16a
commit
87132d1dce
@ -1,8 +1,11 @@
|
||||
.\" -*- nroff -*-
|
||||
.\" SPDX-License-Identifier: BSD-2-Clause
|
||||
.\"
|
||||
.\" Copyright (c) 2000 Jonathan M. Bresler
|
||||
.\"
|
||||
.\" All rights reserved.
|
||||
.\" Copyright (c) 2023 The FreeBSD Foundation
|
||||
.\"
|
||||
.\" Portions of this documentation were written by Mitchell Horne
|
||||
.\" under sponsorship from the FreeBSD Foundation.
|
||||
.\"
|
||||
.\" This program is free software.
|
||||
.\"
|
||||
@ -28,59 +31,102 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 14, 2000
|
||||
.Dd March 16, 2023
|
||||
.Dt KASSERT 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm KASSERT
|
||||
.Nd kernel expression verification macro
|
||||
.Nd kernel expression verification macros
|
||||
.Sh SYNOPSIS
|
||||
.Cd "options INVARIANTS"
|
||||
.Pp
|
||||
.In sys/param.h
|
||||
.In sys/systm.h
|
||||
.Fn KASSERT expression msg
|
||||
.Fn MPASS expression
|
||||
.Sh DESCRIPTION
|
||||
In a kernel compiled with
|
||||
.Cd "options INVARIANTS" ,
|
||||
the
|
||||
.Fn KASSERT
|
||||
macro tests the given
|
||||
.Fa expression
|
||||
and if it is false,
|
||||
calls the
|
||||
Assertions are widely used within the
|
||||
.Fx
|
||||
kernel to verify programmatic assumptions.
|
||||
For violations of run-time assumptions and invariants, it is desirable to fail
|
||||
as soon and as loudly as possible.
|
||||
Assertions are optional code; for non-recoverable error conditions an explicit
|
||||
call to
|
||||
.Xr panic 9
|
||||
function, terminating the running system.
|
||||
is usually preferred.
|
||||
.Pp
|
||||
In a kernel that does not have
|
||||
The
|
||||
.Fn KASSERT
|
||||
macro tests the given boolean
|
||||
.Fa expression .
|
||||
If
|
||||
.Fa expression
|
||||
evaluates to
|
||||
.Dv false ,
|
||||
and the kernel is compiled with
|
||||
.Cd "options INVARIANTS" ,
|
||||
the
|
||||
.Fn KASSERT
|
||||
macro is defined to be a no-op.
|
||||
The
|
||||
second argument is a
|
||||
.Xr panic 9
|
||||
function is called.
|
||||
This terminates the running system at the point of the error, possibly dropping
|
||||
into the kernel debugger or initiating a kernel core dump.
|
||||
The second argument,
|
||||
.Fa msg ,
|
||||
is a
|
||||
.Xr printf 9
|
||||
format string and its arguments,
|
||||
enclosed in parentheses.
|
||||
The formatted string will become the panic string.
|
||||
.Pp
|
||||
In a kernel that is built without
|
||||
.Cd "options INVARIANTS" ,
|
||||
the assertion macros are defined to be no-ops.
|
||||
This eliminates the runtime overhead of widespread assertions from release
|
||||
builds of the kernel.
|
||||
Therefore, checks which can be performed in a constant amount of time can be
|
||||
added as assertions without concern about their performance impact.
|
||||
More expensive checks, such as those that output to console, or verify the
|
||||
integrity of a chain of objects are generally best hidden behind the
|
||||
.Cd DIAGNOSTIC
|
||||
kernel option.
|
||||
.Pp
|
||||
The
|
||||
.Fn MPASS
|
||||
macro (read as: "must-pass")
|
||||
is a convenience wrapper around
|
||||
.Fn KASSERT
|
||||
that automatically generates a sensible assertion message including file and
|
||||
line information.
|
||||
.Sh EXAMPLES
|
||||
The kernel function
|
||||
.Fn vput
|
||||
must not be called with a
|
||||
.Dv NULL
|
||||
pointer.
|
||||
A hypothetical
|
||||
.Vt struct foo
|
||||
object must not have its 'active' flag set when calling
|
||||
.Fn foo_dealloc :
|
||||
.Bd -literal -offset indent
|
||||
void
|
||||
vput(vp)
|
||||
struct vnode *vp;
|
||||
foo_dealloc(struct foo *fp)
|
||||
{
|
||||
struct proc *p = curproc;
|
||||
KASSERT(vp != NULL, ("vput: null vp"));
|
||||
|
||||
KASSERT((fp->foo_flags & FOO_ACTIVE) == 0,
|
||||
("%s: fp %p is still active", __func__, fp));
|
||||
...
|
||||
}
|
||||
.Ed
|
||||
.Pp
|
||||
The assertion
|
||||
.Bd -literal -offset indent
|
||||
MPASS(td == curthread);
|
||||
.Ed
|
||||
.Pp
|
||||
located on line 87 of a file named foo.c would generate the following panic
|
||||
message:
|
||||
.Bd -literal -offset indent
|
||||
panic: Assertion td == curthread failed at foo.c:87
|
||||
.Ed
|
||||
.Sh SEE ALSO
|
||||
.Xr config 8 ,
|
||||
.Xr panic 9
|
||||
.Sh AUTHORS
|
||||
This manual page was written by
|
||||
.An Jonathan M. Bresler Aq Mt jmb@FreeBSD.org .
|
||||
.An Jonathan M. Bresler Aq Mt jmb@FreeBSD.org
|
||||
and
|
||||
.An Mitchell Horne Aq Mt mhorne@FreeBSD.org .
|
||||
|
||||
@ -1334,6 +1334,7 @@ MLINKS+=intr_event.9 intr_event_add_handler.9 \
|
||||
intr_event.9 intr_event_handle.9 \
|
||||
intr_event.9 intr_event_remove_handler.9 \
|
||||
intr_event.9 intr_priority.9
|
||||
MLINKS+=KASSERT.9 MPASS.9
|
||||
MLINKS+=kern_yield.9 maybe_yield.9 \
|
||||
kern_yield.9 should_yield.9
|
||||
MLINKS+=kernacc.9 useracc.9
|
||||
|
||||
Loading…
Reference in New Issue
Block a user