.\" $NetBSD: cnmagic.9,v 1.14 2010/06/08 19:44:28 jruoho 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 http://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 June 8, 2010
.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-\*[Gt]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 string 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 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 .