331 lines
10 KiB
Groff
331 lines
10 KiB
Groff
.\" $NetBSD: pckbport.9,v 1.4 2004/08/07 10:03:29 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2004 Ben Harris
|
|
.\" 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. 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.
|
|
.\"
|
|
.Dd August 5, 2004
|
|
.Os
|
|
.Dt PCKBPORT 9
|
|
.Sh NAME
|
|
.Nm pckbport ,
|
|
.Nm pckbport_attach ,
|
|
.Nm pckbport_attach_slot ,
|
|
.Nm pckbport_cnattach ,
|
|
.Nm pckbportintr ,
|
|
.Nm pckbport_set_inputhandler ,
|
|
.Nm pckbport_flush ,
|
|
.Nm pckbport_poll_cmd ,
|
|
.Nm pckbport_enqueue_cmd ,
|
|
.Nm pckbport_poll_data ,
|
|
.Nm pckbport_set_poll ,
|
|
.Nm pckbport_xt_translation ,
|
|
.Nm pckbport_slot_enable
|
|
.Nd PC keyboard port interface
|
|
.Sh SYNOPSIS
|
|
.In dev/pckbport/pckbportvar.h
|
|
.Ft pckbport_tag_t
|
|
.Fn pckbport_attach "void *" "struct pckbport_accessops const *"
|
|
.Ft "struct device *"
|
|
.Fn pckbport_attach_slot "struct device *" pckbport_tag_t pckbport_slot_t
|
|
.Ft int
|
|
.Fn pckbport_cnattach "void *" "struct pckbport_accessops const *" \
|
|
pckbport_slot_t
|
|
.Ft void
|
|
.Fn pckbportintr pckbport_tag_t pckbport_slot_t int
|
|
.Ft void
|
|
.Fn pckbport_set_inputhandler pckbport_tag_t pckbport_slot_t \
|
|
pckbport_inputfcn "void *" "char *"
|
|
.Ft void
|
|
.Fn pckbport_flush pckbport_tag_t pckbport_slot_t
|
|
.Ft int
|
|
.Fn pckbport_poll_cmd pckbport_tag_t pckbport_slot_t "u_char *" int int \
|
|
"u_char *" int
|
|
.Ft int
|
|
.Fn pckbport_enqueue_cmd pckbport_tag_t pckbport_slot_t "u_char *" int int \
|
|
int "u_char *"
|
|
.Ft int
|
|
.Fn pckbport_poll_data pckbport_tag_t pckbport_slot_t
|
|
.Ft void
|
|
.Fn pckbport_set_poll pckbport_tag_t pckbport_slot_t int
|
|
.Ft int
|
|
.Fn pckbport_xt_translation pckbport_tag_t pckbport_slot_t int
|
|
.Ft void
|
|
.Fn pckbport_slot_enable pckbport_tag_t pckbport_slot_t int
|
|
.Sh DESCRIPTION
|
|
The machine-independent
|
|
.Nm
|
|
subsystem provides an interface layer corresponding to the serial
|
|
keyboard and mouse interface used on the
|
|
.Tn IBM PS/2
|
|
and many other machines.
|
|
It interfaces a controller driver such as
|
|
.Xr pckbc 4
|
|
to device drivers such as
|
|
.Xr pckbd 4
|
|
and
|
|
.Xr pms 4 .
|
|
.Pp
|
|
A single controller can have up to two ports (known as
|
|
.Dq slots ) ,
|
|
and these are identified by values of type
|
|
.Fa pckbport_slot_t .
|
|
The values
|
|
.Dv PCKBPORT_KBD_SLOT
|
|
and
|
|
.Dv PCKBPORT_AUX_SLOT
|
|
should be used for keyboard and mouse ports respectively.
|
|
Each controller is identified by an opaque value of type
|
|
.Fa pckbport_tag_t .
|
|
.Ss Controller interface
|
|
A PC keyboard controller registers itself by calling
|
|
.Fn pckbport_attach cookie ops ,
|
|
with
|
|
.Fa ops
|
|
being a pointer to a
|
|
.Fa struct pckbport_accessops
|
|
containing pointers to functions for driving the controller, which will
|
|
all be called with
|
|
.Fa cookie
|
|
as their first argument.
|
|
.Fn pckbport_attach
|
|
returns the
|
|
.Fa pckbport_tag_t
|
|
assigned to the controller.
|
|
The controller is then expected to call
|
|
.Fn pckbport_attach_slot
|
|
for each slot with which it is equipped, passing the
|
|
.Fa "struct device *"
|
|
corresponding to the controller.
|
|
This function returns a pointer to the child device attached to the slot,
|
|
or
|
|
.Dv NULL
|
|
if no such device was attached.
|
|
.Pp
|
|
The elements of
|
|
.Fa "struct pckbport_accessops"
|
|
each take as their first two arguments the
|
|
.Fa cookie
|
|
passed to
|
|
.Fn pckbport_attach
|
|
and the slot in question.
|
|
The elements are:
|
|
.Bl -tag -width Fn
|
|
.It Fa int Fn (*t_xt_translation) "void *cookie" "pckbport_slot_t slot" \
|
|
"int on"
|
|
If
|
|
.Fa on
|
|
is non-zero, enable, otherwise disable, AT-to-XT keycode translation
|
|
on the slot specified.
|
|
Returns 1 on success, 0 on failure (or if the controller does not support such
|
|
translation).
|
|
.It Fa int Fn (*t_send_devcmd) "void *cookie" "pckbport_slot_t slot" \
|
|
"u_char byte"
|
|
Send a single
|
|
.Fa byte
|
|
to the device without waiting for completion.
|
|
Returns 1 on success, 0 on failure.
|
|
.It Fa int Fn (*t_poll_data1) "void *cookie" "pckbport_slot_t slot"
|
|
Wait for and return one byte of data from the device, without using interrupts.
|
|
This function will only be called after
|
|
.Fn "(*t_set_poll)"
|
|
has been used to put the slot in polling mode.
|
|
If no data are forthcoming from the device after about 100ms, return \-1.
|
|
.It Fa void Fn (*t_slot_enable) "void *cookie" "pckbport_slot_t slot" "int on"
|
|
If
|
|
.Fa on
|
|
is non-zero, enable, otherwise disable, the slot.
|
|
If a slot is disabled, it can be powered down, and is not expected to
|
|
generate any interrupts.
|
|
When first attached, ports should be disabled.
|
|
.It Fa void Fn (*t_intr_establish) "void *cookie" "pckbport_slot_t slot"
|
|
Set up an interrupt handler for the slot.
|
|
Called when a device gets attached to it.
|
|
.It Fa void Fn (*t_set_poll) "void *cookie" "pckbport_slot_t slot" "int on"
|
|
If
|
|
.Fa on
|
|
is non-zero, enable, otherwise disable, polling mode on the slot.
|
|
In polling mode, data received from the device are provided to
|
|
.Fn (*t_poll_data1)
|
|
and not passed to
|
|
.Fn pckbportintr ,
|
|
whether or not interrupts are enabled.
|
|
In non-polling mode,
|
|
data from the device are expected to cause interrupts.
|
|
The controller interrupt handler should call
|
|
.Fn pckbportintr tag slot byte
|
|
once for each
|
|
.Va byte
|
|
received from the device.
|
|
When first attached, a port should be in non-polling mode.
|
|
.El
|
|
.Ss Device interface
|
|
Devices that attach to
|
|
.Nm
|
|
controllers do so using the normal
|
|
.Xr autoconf 9
|
|
mechanism.
|
|
Their
|
|
.Fn (*ca_match)
|
|
and
|
|
.Fn (*ca_attach)
|
|
functions get passed a
|
|
.Fa "struct pckbport_attach_args"
|
|
which contains the controller and slot number where the device was found.
|
|
Device drivers can use the following functions to communicate with the
|
|
controller.
|
|
Each takes
|
|
.Fa tag
|
|
and
|
|
.Fa slot
|
|
arguments to specify the slot to be acted on.
|
|
.Bl -tag -width Fn
|
|
.It Fn pckbport_set_inputhandler tag slot fn arg name
|
|
Arrange for
|
|
.Fa fn
|
|
to be called with argument
|
|
.Fa arg
|
|
whenever an unsolicited byte is received from the slot.
|
|
The function will be called at
|
|
.Fn spltty .
|
|
.It Fn pckbport_flush tag slot
|
|
Ensure that there is no pending input from the slot.
|
|
.It Fn pckbport_poll_cmd tag slot cmd len responselen respbuf slow
|
|
Issue a complete device command,
|
|
.Fa cmd ,
|
|
.Fa len
|
|
bytes long, expecting a response
|
|
.Fa responselen
|
|
bytes long, which will be placed in
|
|
.Fa respbuf .
|
|
If
|
|
.Fa slow
|
|
is true, the command is expected to take over a second to execute.
|
|
.Fn pckbport_poll_cmd
|
|
handles getting an acknowledgement from the device and retrying the command
|
|
if necessary.
|
|
Returns 0 on success, and an error value on failure.
|
|
This function should only be called during autoconfiguration or when the
|
|
slot has been placed into polling mode by
|
|
.Fn pckbport_set_poll .
|
|
.It Fn pckbport_enqueue_cmd tag slot cmd len responselen sync respbuf
|
|
Issue a complete device command,
|
|
.Fa cmd ,
|
|
.Fa len
|
|
bytes long, expecting a response
|
|
.Fa responselen
|
|
bytes long, which will be places in
|
|
.Fa respbuf .
|
|
If
|
|
.Fa sync
|
|
is true,
|
|
.Fn pckbport_enqueue_cmd
|
|
waits for the command to complete before returning, otherwise it returns
|
|
immediately.
|
|
It is not safe to set
|
|
.Fa sync
|
|
when calling from an interrupt context.
|
|
The
|
|
.Nm pckbport
|
|
layer handles getting an acknowledgement from the device and retrying
|
|
the command if necessary.
|
|
Returns 0 on success, and an error value on failure.
|
|
.It Fn pckbport_poll_data tag slot
|
|
Low-level command to poll for a single byte of data from the device, but
|
|
ignoring bytes that are part of the response to a command issued through
|
|
.Fn pckbport_enqueue_command .
|
|
.It Fn pckbport_set_poll tag slot on
|
|
If
|
|
.Fa on
|
|
is true, enable polling on the slot, otherwise disable it.
|
|
In polling mode,
|
|
.Fn pckbport_poll_cmd
|
|
can be used to issue commands and
|
|
.Fn pckbport_poll_data
|
|
to read unsolicited data, without enabling interrupts.
|
|
In non-polling mode, commands should be issued using
|
|
.Fn pckbport_enqueue_cmd ,
|
|
unsolicited data are handled by the input function, and disabling interrupts
|
|
will suspend
|
|
.Nm
|
|
operation.
|
|
.It Fn pckbport_xt_translation tag slot on
|
|
Passthrough of
|
|
.Fn (*t_xt_translation)
|
|
(see above).
|
|
.It Fn pckbport_slot enable tag slot on
|
|
Passthrough of
|
|
.Fn (*t_slot_enable)
|
|
(see above).
|
|
.El
|
|
.Ss Console interface
|
|
On systems that can attach consoles through
|
|
.Nm ,
|
|
the controller's console attachment function (called very early in
|
|
autoconfiguration) calls
|
|
.Fn pckbport_cnattach cookie ops slot .
|
|
The first two arguments are the same as for
|
|
.Fn pckbport_attach ,
|
|
while the third indicates which slot the console keyboard is attached to.
|
|
.Fn pckbport_cnattach
|
|
either calls
|
|
.Fn pckbd_cnattach ,
|
|
if it is available, or
|
|
.Fn pckbport_machdep_cnattach .
|
|
The latter allows machine-dependent keyboard drivers to attach themselves,
|
|
but it is only called if a device with the
|
|
.Ql pckbport_machdep_cnattach
|
|
attribute is configured into the system.
|
|
.Fn pckbport_cnattach
|
|
returns 0 on success and an error value on failure.
|
|
.Fn pckbport_machdep_cnattach
|
|
is expected to do the same.
|
|
.Sh CODE REFERENCES
|
|
The
|
|
.Nm
|
|
code, and the
|
|
.Xr pckbd 4
|
|
and
|
|
.Xr pms 4
|
|
device drivers are in
|
|
.Pa sys/dev/pckbport .
|
|
.Sh SEE ALSO
|
|
.Xr pckbc 4 ,
|
|
.Xr pckbd 4 ,
|
|
.Xr pms 4 ,
|
|
.Xr autoconf 9 ,
|
|
.Xr spl 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
system appeared in
|
|
.Nx 2.0 .
|
|
Before that,
|
|
.Xr pckbd 4
|
|
and
|
|
.Xr pms 4
|
|
attached directly to
|
|
.Xr pckbc 4
|
|
without any sensible way of using a different controller.
|