diff options
Diffstat (limited to 'static/netbsd/man9/cnmagic.9')
| -rw-r--r-- | static/netbsd/man9/cnmagic.9 | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/static/netbsd/man9/cnmagic.9 b/static/netbsd/man9/cnmagic.9 new file mode 100644 index 00000000..2ab75c28 --- /dev/null +++ b/static/netbsd/man9/cnmagic.9 @@ -0,0 +1,198 @@ +.\" $NetBSD: cnmagic.9,v 1.17 2024/09/07 19:13:29 rillig Exp $ +.\" +.\" Copyright (c) 2000 Eduardo Horvath +.\" All rights reserved. +.\" +.\" 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 for the +.\" NetBSD Project. See https://www.NetBSD.org/ for +.\" information about NetBSD. +.\" 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. +.\" +.\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )-- +.\" +.Dd July 7, 2019 +.Dt CNMAGIC 9 +.Os +.Sh NAME +.Nm cn_init_magic , +.Nm cn_trap , +.Nm cn_isconsole , +.Nm cn_check_magic , +.Nm cn_destroy_magic , +.Nm cn_set_magic , +.Nm cn_get_magic +.Nd console magic key sequence management +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn cn_init_magic "cnm_state_t *cnms" +.Ft void +.Fn cn_trap +.Ft int +.Fn cn_isconsole "dev_t dev" +.Ft void +.Fn cn_check_magic "dev_t dev" "int k" "cnm_state_t *cnms" +.Ft void +.Fn cn_destroy_magic "cnm_state_t *cnms" +.Ft int +.Fn cn_set_magic "char *magic" +.Ft int +.Fn cn_get_magic "char *magic" "int len" +.Sh DESCRIPTION +The +.Nx +console magic key sequence management framework is designed to provide +flexible methods to set, change, and detect magic key sequences on console +devices and break into the debugger or ROM monitor with a minimum of interrupt +latency. +.Pp +Drivers that generate console input should make use of these routines. +A different +.Va cnm_state_t +should be used for each separate input stream. +Multiple devices that share the same input stream, such as USB +keyboards, can share the same +.Va cnm_state_t . +Once a +.Va cnm_state_t +is allocated, it should be initialized with +.Fn cn_init_magic +so it can be used by +.Fn cn_check_magic . +If a driver thinks it might be the console input device it can set the +magic sequence with +.Fn cn_set_magic +to any arbitrary string. +Whenever the driver receives input, it should call +.Fn cn_check_magic +to process the data and determine whether the magic sequence has +been hit. +.Pp +The magic key sequence can be accessed through the +.Va hw.cnmagic +.Ic sysctl +variable. +This is the raw data and may be keycodes rather than +processed characters, depending on the console device. +.Sh FUNCTIONS +The following functions describe the console magic interface. +.Bl -tag -width indent +.It Fn cn_init_magic "cnm" +Initialize the console magic state pointed to by +.Fa cnm +to a usable state. +.It Fn cn_trap +Trap into the kernel debugger or ROM monitor. +By default this routine is defined to be +.Fn console_debugger +but can be overridden in MI header files. +.It Fn cn_isconsole "dev" +Determine whether a given +.Fa dev +is the system console. +This macro tests to see if +.Fa dev +is the same as +.Va cn_tab->cn_dev +but can be overridden in MI header files. +.It Fn cn_check_magic "dev" "k" "cnms" +All input should be passed through +.Fn cn_check_magic +so the state machine remains in a consistent state. +.Fn cn_check_magic +calls +.Fn cn_isconsole +with +.Fa dev +to determine if this is the console. +If that returns true then it runs the input value +.Fa k +through the state machine. +If the state machine completes a match of the current console magic sequence +.Fn cn_trap +is called. +Some input may need to be translated to state machine +values such as the serial line +.Li BREAK +sequence. +.It Fn cn_destroy_magic "cnms" +This should be called once what +.Fa cnms +points to is no longer needed. +.It Fn cn_set_magic "magic" +.Fn cn_set_magic +encodes a +.Li nul +terminated arbitrary string into values that can be used by +the state machine and installs it as the global magic sequence. +The escape sequence is character value +.Li 0x27 +and can be used to encode special values: +.Pp +.Bl -tag -width "0x001" -compact -offset indent +.It 0x27 +The literal value +.Li 0x27 . +.It 0x01 +Serial +.Li BREAK +sequence. +.It 0x02 +.Li Nul +character. +.El +.Pp +Returns +.Li 0 +on success or a non-zero error value. +.It Fn cn_get_magic "magic" "len" +Extract the current magic sequence from the state machine and return +up to +.Fa len +bytes of it in the buffer pointed to by +.Fa magic . +It uses the same encoding accepted by +.Fn cn_set_magic . +Returns +.Li 0 +on success or a non-zero error value. +.El +.Sh SEE ALSO +.Xr ddb 4 , +.Xr sysctl 8 , +.Xr cons 9 +.Sh HISTORY +The +.Nx +console magic key sequence management framework +first appeared in +.Nx 1.6 . +.Sh AUTHORS +The +.Nx +console magic key sequence management framework was designed and +implemented by +.An Eduardo Horvath +.Aq eeh@NetBSD.org . |