1.\" $NetBSD: crashme.9,v 1.6 2024/07/24 12:48:17 uwe Exp $ 2.\" 3.\" Copyright (c) 2019 Matthew R. Green 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd January 7, 2019 28.Dt CRASHME 9 29.Os 30.Sh NAME 31.Nm crashme , 32.Nm crashme_add , 33.Nm crashme_remove 34.Nd in-kernel testing of crash handling 35.Sh SYNOPSIS 36.In sys/crashme.h 37.Ft int 38.Fn crashme_add "crashme_node *cn" 39.Ft int 40.Fn crashme_remove "crashme_node *cn" 41.Sh DESCRIPTION 42The 43.Nm 44functions provide access to dynamically add and remove crashme nodes. 45These nodes are simply named callbacks that are expected to cause the 46system to crash. 47.Pp 48The crashme functionality is only available in kernels with the 49.Ic options DEBUG 50set in the kernel 51.Xr config 5 52file. 53.Pp 54Each crashme node is maintained in a 55.Vt crashme_node 56structure which has the following public members: 57.Bd -literal -offset indent 58typedef int (*crashme_fn)(int /* flags */); 59 60typedef struct crashme_node { 61 const char *cn_name; 62 const char *cn_longname; 63 crashme_fn cn_fn; 64} crashme_node; 65.Ed 66.Pp 67The 68caller must fill in the 69.Fa cn_name , 70.Fa cn_longname , 71and 72.Fa cn_fn 73members. 74.Pp 75The 76.Fa cn_fn 77function is passed 78.Ar flags 79parameter from sysctl. 80It shall return 0 upon success or non zero on failure. 81.Sh SYSCTL SUPPORT 82The following 83.Xr sysctl 8 84variables are provided by the 85.Nm 86subsystem: 87.Bl -tag -offset indent -width Va 88.It Va debug.crashme_enable 89Must be set to 1 for any 90.Nm 91node to be executed. 92.El 93.Pp 94The following 95.Xr sysctl 8 96variables trigger crashes in different ways when written to: 97.Bl -tag -offset indent -width Va 98.It Va debug.crashme.panic 99Call 100.Xr panic 9 . 101.It Va debug.crashme.null_deref 102Dereference a null pointer. 103.It Va debug.crashme.null_jump 104Call a null function pointer, i.e., jump to the instruction address 105zero. 106.It Va debug.crashme.ddb 107Enter 108.Xr ddb 4 109directly by calling 110.Fn Debugger . 111Requires 112.Ic options DDB . 113.El 114.Sh SEE ALSO 115.Xr ddb 4 , 116.Xr options 4 , 117.Xr sysctl 8 , 118.Xr panic 9 . 119.Sh HISTORY 120The 121.Nm 122driver appeared in 123.Nx 9.0 . 124.Sh AUTHORS 125.An Matthew R. Green 126