NetBSD/share/man/man9/cnmagic.9

202 lines
5.9 KiB
Groff
Raw Normal View History

2004-10-06 09:57:33 +04:00
.\" $NetBSD: cnmagic.9,v 1.13 2004/10/06 05:57:33 dbj Exp $
2000-11-09 01:41:58 +03:00
.\"
.\" Copyright (c) 2000 Eduardo Horvath
.\" All rights reserved.
.\"
2000-11-09 01:41:58 +03:00
.\" 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
2000-11-09 01:41:58 +03:00
.\" 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.
.\"
2000-11-09 01:41:58 +03:00
.\" 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.
.\"
2000-11-09 01:41:58 +03:00
.\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )--
.\"
.Dd November 11, 2000
2001-06-05 16:54:35 +04:00
.Dt CNMAGIC 9
2000-11-09 01:41:58 +03:00
.Os
.Sh NAME
.Nm cn_trap ,
.Nm cn_isconsole ,
.Nm cn_check_magic ,
.Nm cn_init_magic ,
.Nm cn_set_magic ,
.Nm cn_get_magic ,
.Nm cn_destroy_magic
.Nd console magic key sequence management
.Sh SYNOPSIS
.In sys/systm.h
.Va typedef struct cnm_state cnm_state_t;
2000-11-09 01:41:58 +03:00
.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_init_magic "cnm_state_t *cnms"
.Ft int
.Fn cn_set_magic "char *magic"
.Ft int
.Fn cn_get_magic "char *magic" "int len"
.Ft void
.Fn cn_destroy_magic "cnm_state_t *cnms"
.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
2001-06-21 15:59:00 +04:00
devices and break into the debugger or ROM monitor with a minimum of interrupt
2000-11-09 01:41:58 +03:00
latency.
.Pp
2002-10-14 17:43:14 +04:00
Drivers that generate console input should make use of these routines.
A different
2000-11-09 01:41:58 +03:00
.Va cnm_state_t
2002-10-14 17:43:14 +04:00
should be used for each separate input stream.
Multiple devices that share the same input stream, such as USB
keyboards can share the same
2000-11-09 01:41:58 +03:00
.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
2000-11-09 01:41:58 +03:00
.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
2002-10-14 17:43:14 +04:00
to any arbitrary string.
Whenever the driver receives input, it should call
2000-11-09 01:41:58 +03:00
.Fn cn_check_magic
2001-06-21 15:59:00 +04:00
to process the data and determine whether the magic sequence has
2000-11-09 01:41:58 +03:00
been hit.
.Pp
The magic key sequence can be accessed through the
.Va hw.cnmagic
.Ic sysctl
2002-10-14 17:43:14 +04:00
variable.
This is the raw data and may be keycodes rather than
2001-06-21 15:59:00 +04:00
processed characters, depending on the console device.
2000-11-09 01:41:58 +03:00
.Pp
Here is a description of the console magic interface:
.Bl -tag -width indent
.It Fn "void cn_init_magic" "cnm_state_t *cnm"
.Pp
Initialize the console magic state pointed to by
.Fa cnm
2001-06-21 15:59:00 +04:00
to a usable state.
2000-11-09 01:41:58 +03:00
.It Fn "void cnm_trap"
.Pp
2002-10-14 17:43:14 +04:00
Trap into the kernel debugger or ROM monitor.
By default this routine is defined to be
2000-11-09 01:41:58 +03:00
.Fn console_debugger
2001-06-21 15:59:00 +04:00
but can be overridden in MI header files.
2000-11-09 01:41:58 +03:00
.It Fn "int cn_isconsole" "dev_t dev"
.Pp
Determine whether a given
.Fa dev
2002-10-14 17:43:14 +04:00
is the system console.
This macro tests to see if
2000-11-09 01:41:58 +03:00
.Fa dev
is the same as
.Va cn_tab-\*[Gt]cn_dev
2001-06-21 15:59:00 +04:00
but can be overridden in MI header files.
2000-11-09 01:41:58 +03:00
.It Fn "void cn_check_magic" "dev_t dev" "int k" "cnm_state_t *cnms"
.Pp
2001-06-21 15:59:00 +04:00
All input should be passed through
2000-11-09 01:41:58 +03:00
.Fn cn_check_magic
so the state machine remains in a consistent state.
.Fn cn_check_magic
calls
.Fn cn_isconsole
with
.Fa dev
2002-10-14 17:43:14 +04:00
to determine if this is the console.
If that returns true then it runs the input value
2000-11-09 01:41:58 +03:00
.Fa k
2002-10-14 17:43:14 +04:00
through the state machine.
If the state machine completes a match of the current console magic sequence
2000-11-09 01:41:58 +03:00
.Fn cn_trap
2002-10-14 17:43:14 +04:00
is called.
Some input may need to be translated to state machine
values such as the serial line
.Li BREAK
2000-11-09 01:41:58 +03:00
sequence.
.It Fn "void cn_destroy_magic" "cnm_state_t *cnms"
.Pp
This should be called once what
.Fa cnms
points to is no longer needed.
.It Fn "int cn_set_magic" "char *magic"
.Fn cn_set_magic
encodes a
.Li nul
2000-11-09 01:41:58 +03:00
terminated string arbitrary string into values that can be used by
2002-10-14 17:43:14 +04:00
the state machine and installs it as the global magic sequence.
The escape sequence is character value
2000-11-09 01:41:58 +03:00
.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
2004-06-03 01:11:15 +04:00
.Li Nul
2000-11-09 01:41:58 +03:00
character.
.El
Returns
.Li 0
on success or a non-zero error value.
.It Fn "int cn_get_magic" "char *magic" "int len"
2004-10-06 09:57:33 +04:00
Extract the current magic sequence from the state machine and return
2000-11-09 01:41:58 +03:00
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
.Sh HISTORY
The
.Nx
console magic key sequence management framework
first appeared in
2000-11-09 01:41:58 +03:00
.Nx 1.6 .
2001-12-26 04:07:45 +03:00
.Sh AUTHORS
The
.Nx
console magic key sequence management framework was designed and
implemented by
.An Eduardo Horvath
.Aq eeh@NetBSD.org .