1.\" $NetBSD: cnmagic.9,v 1.8 2002/02/13 08:18:38 ross Exp $ 2.\" 3.\" Copyright (c) 2000 Eduardo Horvath 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.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed for the 17.\" NetBSD Project. See http://www.netbsd.org/ for 18.\" information about NetBSD. 19.\" 4. The name of the author may not be used to endorse or promote products 20.\" derived from this software without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 27.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 31.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32.\" 33.\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )-- 34.\" 35.Dd November 11, 2000 36.Dt CNMAGIC 9 37.Os 38.Sh NAME 39.Nm cn_trap , 40.Nm cn_isconsole , 41.Nm cn_check_magic , 42.Nm cn_init_magic , 43.Nm cn_set_magic , 44.Nm cn_get_magic , 45.Nm cn_destroy_magic 46.Nd console magic key sequence management 47.Sh SYNOPSIS 48.Fd #include \*[Lt]sys/systm.h\*[Gt] 49.Va typedef struct cnm_state cnm_state_t; 50.Ft void 51.Fn cn_trap 52.Ft int 53.Fn cn_isconsole "dev_t dev" 54.Ft void 55.Fn cn_check_magic "dev_t dev" "int k" "cnm_state_t *cnms" 56.Ft void 57.Fn cn_init_magic "cnm_state_t *cnms" 58.Ft int 59.Fn cn_set_magic "char *magic" 60.Ft int 61.Fn cn_get_magic "char *magic" "int len" 62.Ft void 63.Fn cn_destroy_magic "cnm_state_t *cnms" 64.Sh DESCRIPTION 65The 66.Nx 67console magic key sequence management framework is designed to provide 68flexible methods to set, change, and detect magic key sequences on console 69devices and break into the debugger or ROM monitor with a minimum of interrupt 70latency. 71.Pp 72Drivers that generate console input should make use of these routines. A 73different 74.Va cnm_state_t 75should be used for each separate input stream. Multiple devices that share 76the same input stream, such as USB keyboards can share the same 77.Va cnm_state_t . 78Once a 79.Va cnm_state_t 80is allocated, it should be initialized with 81.Fn cn_init_magic 82so it can be used by 83.Fn cn_check_magic . 84If a driver thinks it might be the console input device it can set the 85magic sequence with 86.Fn cn_set_magic 87to any arbitrary string. Whenever the driver receives input, 88it should call 89.Fn cn_check_magic 90to process the data and determine whether the magic sequence has 91been hit. 92.Pp 93The magic key sequence can be accessed through the 94.Va hw.cnmagic 95.Ic sysctl 96variable. This is the raw data and may be keycodes rather than 97processed characters, depending on the console device. 98.Pp 99Here is a description of the console magic interface: 100.Bl -tag -width indent 101.It Fn "void cn_init_magic" "cnm_state_t *cnm" 102.Pp 103Initialize the console magic state pointed to by 104.Fa cnm 105to a usable state. 106.It Fn "void cnm_trap" 107.Pp 108Trap into the kernel debugger or ROM monitor. By default this 109routine is defined to be 110.Fn console_debugger 111but can be overridden in MI header files. 112.It Fn "int cn_isconsole" "dev_t dev" 113.Pp 114Determine whether a given 115.Fa dev 116is the system console. This macro tests to see if 117.Fa dev 118is the same as 119.Va cn_tab-\*[Gt]cn_dev 120but can be overridden in MI header files. 121.It Fn "void cn_check_magic" "dev_t dev" "int k" "cnm_state_t *cnms" 122.Pp 123All input should be passed through 124.Fn cn_check_magic 125so the state machine remains in a consistent state. 126.Fn cn_check_magic 127calls 128.Fn cn_isconsole 129with 130.Fa dev 131to determine if this is the console. If that returns true then 132it runs the input value 133.Fa k 134through the state machine. If the state machine completes a match 135of the current console magic sequence 136.Fn cn_trap 137is called. Some input may need to be translated to state machine 138values such as the serial line 139.Li BREAK 140sequence. 141.It Fn "void cn_destroy_magic" "cnm_state_t *cnms" 142.Pp 143This should be called once what 144.Fa cnms 145points to is no longer needed. 146.It Fn "int cn_set_magic" "char *magic" 147.Fn cn_set_magic 148encodes a 149.Li nul 150terminated string arbitrary string into values that can be used by 151the state machine and installs it as the global magic sequence. The 152escape sequence is character value 153.Li 0x27 154and can be used to encode special values: 155.Pp 156.Bl -tag -width "0x001" -compact -offset indent 157.It 0x27 158The literal value 159.Li 0x27 . 160.It 0x01 161Serial 162.Li BREAK 163sequence. 164.It 0x02 165.LI Nul 166character. 167.El 168Returns 169.Li 0 170on success or a non-zero error value. 171.It Fn "int cn_get_magic" "char *magic" "int len" 172Extract the current magic sequence from the sate machine and return 173up to 174.Fa len 175bytes of it in the buffer pointed to by 176.Fa magic . 177It uses the same encoding accepted by 178.Fn cn_set_magic . 179Returns 180.Li 0 181on success or a non-zero error value. 182.El 183.Sh SEE ALSO 184.Xr sysctl 8 185.Sh HISTORY 186The 187.Nx 188console magic key sequence management framework 189first appeared in 190.Nx 1.6 . 191.Sh AUTHORS 192The 193.Nx 194console magic key sequence management framework was designed and implemented by 195Eduardo Horvath \*[Lt]eeh@netbsd.org\*[Gt] 196