NAME
cn_init_magic,
cn_trap,
cn_isconsole,
cn_check_magic,
cn_destroy_magic,
cn_set_magic,
cn_get_magic —
console magic key
sequence management
SYNOPSIS
#include <sys/systm.h>
void
cn_init_magic(
cnm_state_t
*cnms);
void
cn_trap();
int
cn_isconsole(
dev_t
dev);
void
cn_check_magic(
dev_t
dev,
int k,
cnm_state_t *cnms);
void
cn_destroy_magic(
cnm_state_t
*cnms);
int
cn_set_magic(
char
*magic);
int
cn_get_magic(
char
*magic,
int len);
DESCRIPTION
The
NetBSD 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.
Drivers that generate console input should make use of these routines. A
different
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
cnm_state_t. Once a
cnm_state_t is allocated, it should be initialized with
cn_init_magic() so it can be used by
cn_check_magic(). If a driver thinks it might be the console
input device it can set the magic sequence with
cn_set_magic() to any arbitrary string. Whenever the driver
receives input, it should call
cn_check_magic() to process
the data and determine whether the magic sequence has been hit.
The magic key sequence can be accessed through the
hw.cnmagic sysctl variable. This is
the raw data and may be keycodes rather than processed characters, depending
on the console device.
FUNCTIONS
The following functions describe the console magic interface.
-
-
- cn_init_magic(cnm)
- Initialize the console magic state pointed to by
cnm to a usable state.
-
-
- cn_trap()
- Trap into the kernel debugger or ROM monitor. By default
this routine is defined to be console_debugger() but can
be overridden in MI header files.
-
-
- cn_isconsole(dev)
- Determine whether a given dev is the
system console. This macro tests to see if dev is
the same as cn_tab->cn_dev but can be overridden
in MI header files.
-
-
- cn_check_magic(dev,
k, cnms)
- All input should be passed through
cn_check_magic() so the state machine remains in a
consistent state. cn_check_magic() calls
cn_isconsole() with dev to
determine if this is the console. If that returns true then it runs the
input value k through the state machine. If the
state machine completes a match of the current console magic sequence
cn_trap() is called. Some input may need to be
translated to state machine values such as the serial line
BREAK
sequence.
-
-
- cn_destroy_magic(cnms)
- This should be called once what cnms
points to is no longer needed.
-
-
- cn_set_magic(magic)
- cn_set_magic() encodes a
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
0x27
and can be used to encode special values:
- 0x27
- The literal value
0x27
.
- 0x01
- Serial
BREAK
sequence.
- 0x02
Nul
character.
Returns 0
on success or a non-zero error value.
-
-
- cn_get_magic(magic,
len)
- Extract the current magic sequence from the state machine
and return up to len bytes of it in the buffer
pointed to by magic. It uses the same encoding
accepted by cn_set_magic(). Returns
0
on success or a non-zero error value.
SEE ALSO
sysctl(8),
cons(9)
HISTORY
The
NetBSD console magic key sequence management
framework first appeared in
NetBSD 1.6.
AUTHORS
The
NetBSD console magic key sequence management
framework was designed and implemented by
Eduardo
Horvath ⟨eeh@NetBSD.org⟩.