diff options
Diffstat (limited to 'static/netbsd/man9/pckbport.9')
| -rw-r--r-- | static/netbsd/man9/pckbport.9 | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/static/netbsd/man9/pckbport.9 b/static/netbsd/man9/pckbport.9 new file mode 100644 index 00000000..9a00360e --- /dev/null +++ b/static/netbsd/man9/pckbport.9 @@ -0,0 +1,330 @@ +.\" $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. |