.\" $NetBSD: pckbport.9,v 1.5 2009/03/09 19:24:32 joerg 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
.Dt PCKBPORT 9
.Os
.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.