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 n 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 .
p 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.
p 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: l -tag -width Fn t 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). t 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. t 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. t 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. t 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. t 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. l -tag -width Fn t 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 . t Fn pckbport_flush tag slot Ensure that there is no pending input from the slot. t 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 . t 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. t 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 . t 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. t Fn pckbport_xt_translation tag slot on Passthrough of .Fn (*t_xt_translation) (see above). t 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
a 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.
Indexes created Sat Sep 20 22:09:52 GMT 2025