1.\" $NetBSD: crashme.9,v 1.5 2021/12/11 23:47:53 riastradh 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.Xr options 4 50.Dv DEBUG 51option set. 52.Pp 53Each crashme node is maintained in a 54.Vt crashme_node 55structure which has the following public members: 56.Bd -literal 57typedef int (*crashme_fn)(int); 58 59typedef struct crashme_node { 60 const char *cn_name; 61 const char *cn_longname; 62 crashme_fn cn_fn; 63} crashme_node; 64.Ed 65.Pp 66The 67caller must fill in the 68.Fa cn_name , 69.Fa cn_longname , 70and 71.Fa cn_fn 72members. 73.Pp 74The 75.Ar flags 76parameter is passed from sysctl. 77The return value is 0 upon success or non zero for failure. 78.Sh SYSCTL SUPPORT 79The following 80.Xr sysctl 8 81variables are provided by the 82.Nm 83subsystem: 84.Bl -tag -width Li 85.It Li debug.crashme_enable 86Must be set to 1 for any 87.Nm 88node to be executed. 89.El 90.Pp 91The following 92.Xr sysctl 8 93nodes trigger crashes in different ways when written: 94.Bl -tag -width ".Li debug.crashme.null_deref" 95.It Li debug.crashme.panic 96Call 97.Xr panic 9 . 98.It Li debug.crashme.null_deref 99Dereference a null pointer. 100.It Li debug.crashme.null_jump 101Call a null function pointer, i.e., jump to the instruction address 102zero. 103.It Li debug.crashme.ddb 104Enter 105.Xr ddb 9 106directly by calling 107.Xr Debugger 9 . 108Requires 109.Xr options 4 110.Dv DDB . 111.El 112.Sh SEE ALSO 113.Xr options 4 , 114.Xr panic 9 115.Sh HISTORY 116The 117.Nm 118driver appeared in 119.Nx 9.0 . 120.Sh AUTHORS 121.An Matthew R. Green 122