1.\" $NetBSD: pckbport.9,v 1.5 2009/03/09 19:24:32 joerg Exp $ 2.\" 3.\" Copyright (c) 2004 Ben Harris 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd August 5, 2004 29.Dt PCKBPORT 9 30.Os 31.Sh NAME 32.Nm pckbport , 33.Nm pckbport_attach , 34.Nm pckbport_attach_slot , 35.Nm pckbport_cnattach , 36.Nm pckbportintr , 37.Nm pckbport_set_inputhandler , 38.Nm pckbport_flush , 39.Nm pckbport_poll_cmd , 40.Nm pckbport_enqueue_cmd , 41.Nm pckbport_poll_data , 42.Nm pckbport_set_poll , 43.Nm pckbport_xt_translation , 44.Nm pckbport_slot_enable 45.Nd PC keyboard port interface 46.Sh SYNOPSIS 47.In dev/pckbport/pckbportvar.h 48.Ft pckbport_tag_t 49.Fn pckbport_attach "void *" "struct pckbport_accessops const *" 50.Ft "struct device *" 51.Fn pckbport_attach_slot "struct device *" pckbport_tag_t pckbport_slot_t 52.Ft int 53.Fn pckbport_cnattach "void *" "struct pckbport_accessops const *" \ 54pckbport_slot_t 55.Ft void 56.Fn pckbportintr pckbport_tag_t pckbport_slot_t int 57.Ft void 58.Fn pckbport_set_inputhandler pckbport_tag_t pckbport_slot_t \ 59pckbport_inputfcn "void *" "char *" 60.Ft void 61.Fn pckbport_flush pckbport_tag_t pckbport_slot_t 62.Ft int 63.Fn pckbport_poll_cmd pckbport_tag_t pckbport_slot_t "u_char *" int int \ 64"u_char *" int 65.Ft int 66.Fn pckbport_enqueue_cmd pckbport_tag_t pckbport_slot_t "u_char *" int int \ 67int "u_char *" 68.Ft int 69.Fn pckbport_poll_data pckbport_tag_t pckbport_slot_t 70.Ft void 71.Fn pckbport_set_poll pckbport_tag_t pckbport_slot_t int 72.Ft int 73.Fn pckbport_xt_translation pckbport_tag_t pckbport_slot_t int 74.Ft void 75.Fn pckbport_slot_enable pckbport_tag_t pckbport_slot_t int 76.Sh DESCRIPTION 77The machine-independent 78.Nm 79subsystem provides an interface layer corresponding to the serial 80keyboard and mouse interface used on the 81.Tn IBM PS/2 82and many other machines. 83It interfaces a controller driver such as 84.Xr pckbc 4 85to device drivers such as 86.Xr pckbd 4 87and 88.Xr pms 4 . 89.Pp 90A single controller can have up to two ports (known as 91.Dq slots ) , 92and these are identified by values of type 93.Fa pckbport_slot_t . 94The values 95.Dv PCKBPORT_KBD_SLOT 96and 97.Dv PCKBPORT_AUX_SLOT 98should be used for keyboard and mouse ports respectively. 99Each controller is identified by an opaque value of type 100.Fa pckbport_tag_t . 101.Ss Controller interface 102A PC keyboard controller registers itself by calling 103.Fn pckbport_attach cookie ops , 104with 105.Fa ops 106being a pointer to a 107.Fa struct pckbport_accessops 108containing pointers to functions for driving the controller, which will 109all be called with 110.Fa cookie 111as their first argument. 112.Fn pckbport_attach 113returns the 114.Fa pckbport_tag_t 115assigned to the controller. 116The controller is then expected to call 117.Fn pckbport_attach_slot 118for each slot with which it is equipped, passing the 119.Fa "struct device *" 120corresponding to the controller. 121This function returns a pointer to the child device attached to the slot, 122or 123.Dv NULL 124if no such device was attached. 125.Pp 126The elements of 127.Fa "struct pckbport_accessops" 128each take as their first two arguments the 129.Fa cookie 130passed to 131.Fn pckbport_attach 132and the slot in question. 133The elements are: 134.Bl -tag -width Fn 135.It Fa int Fn (*t_xt_translation) "void *cookie" "pckbport_slot_t slot" \ 136"int on" 137If 138.Fa on 139is non-zero, enable, otherwise disable, AT-to-XT keycode translation 140on the slot specified. 141Returns 1 on success, 0 on failure (or if the controller does not support such 142translation). 143.It Fa int Fn (*t_send_devcmd) "void *cookie" "pckbport_slot_t slot" \ 144"u_char byte" 145Send a single 146.Fa byte 147to the device without waiting for completion. 148Returns 1 on success, 0 on failure. 149.It Fa int Fn (*t_poll_data1) "void *cookie" "pckbport_slot_t slot" 150Wait for and return one byte of data from the device, without using interrupts. 151This function will only be called after 152.Fn "(*t_set_poll)" 153has been used to put the slot in polling mode. 154If no data are forthcoming from the device after about 100ms, return \-1. 155.It Fa void Fn (*t_slot_enable) "void *cookie" "pckbport_slot_t slot" "int on" 156If 157.Fa on 158is non-zero, enable, otherwise disable, the slot. 159If a slot is disabled, it can be powered down, and is not expected to 160generate any interrupts. 161When first attached, ports should be disabled. 162.It Fa void Fn (*t_intr_establish) "void *cookie" "pckbport_slot_t slot" 163Set up an interrupt handler for the slot. 164Called when a device gets attached to it. 165.It Fa void Fn (*t_set_poll) "void *cookie" "pckbport_slot_t slot" "int on" 166If 167.Fa on 168is non-zero, enable, otherwise disable, polling mode on the slot. 169In polling mode, data received from the device are provided to 170.Fn (*t_poll_data1) 171and not passed to 172.Fn pckbportintr , 173whether or not interrupts are enabled. 174In non-polling mode, 175data from the device are expected to cause interrupts. 176The controller interrupt handler should call 177.Fn pckbportintr tag slot byte 178once for each 179.Va byte 180received from the device. 181When first attached, a port should be in non-polling mode. 182.El 183.Ss Device interface 184Devices that attach to 185.Nm 186controllers do so using the normal 187.Xr autoconf 9 188mechanism. 189Their 190.Fn (*ca_match) 191and 192.Fn (*ca_attach) 193functions get passed a 194.Fa "struct pckbport_attach_args" 195which contains the controller and slot number where the device was found. 196Device drivers can use the following functions to communicate with the 197controller. 198Each takes 199.Fa tag 200and 201.Fa slot 202arguments to specify the slot to be acted on. 203.Bl -tag -width Fn 204.It Fn pckbport_set_inputhandler tag slot fn arg name 205Arrange for 206.Fa fn 207to be called with argument 208.Fa arg 209whenever an unsolicited byte is received from the slot. 210The function will be called at 211.Fn spltty . 212.It Fn pckbport_flush tag slot 213Ensure that there is no pending input from the slot. 214.It Fn pckbport_poll_cmd tag slot cmd len responselen respbuf slow 215Issue a complete device command, 216.Fa cmd , 217.Fa len 218bytes long, expecting a response 219.Fa responselen 220bytes long, which will be placed in 221.Fa respbuf . 222If 223.Fa slow 224is true, the command is expected to take over a second to execute. 225.Fn pckbport_poll_cmd 226handles getting an acknowledgement from the device and retrying the command 227if necessary. 228Returns 0 on success, and an error value on failure. 229This function should only be called during autoconfiguration or when the 230slot has been placed into polling mode by 231.Fn pckbport_set_poll . 232.It Fn pckbport_enqueue_cmd tag slot cmd len responselen sync respbuf 233Issue a complete device command, 234.Fa cmd , 235.Fa len 236bytes long, expecting a response 237.Fa responselen 238bytes long, which will be places in 239.Fa respbuf . 240If 241.Fa sync 242is true, 243.Fn pckbport_enqueue_cmd 244waits for the command to complete before returning, otherwise it returns 245immediately. 246It is not safe to set 247.Fa sync 248when calling from an interrupt context. 249The 250.Nm pckbport 251layer handles getting an acknowledgement from the device and retrying 252the command if necessary. 253Returns 0 on success, and an error value on failure. 254.It Fn pckbport_poll_data tag slot 255Low-level command to poll for a single byte of data from the device, but 256ignoring bytes that are part of the response to a command issued through 257.Fn pckbport_enqueue_command . 258.It Fn pckbport_set_poll tag slot on 259If 260.Fa on 261is true, enable polling on the slot, otherwise disable it. 262In polling mode, 263.Fn pckbport_poll_cmd 264can be used to issue commands and 265.Fn pckbport_poll_data 266to read unsolicited data, without enabling interrupts. 267In non-polling mode, commands should be issued using 268.Fn pckbport_enqueue_cmd , 269unsolicited data are handled by the input function, and disabling interrupts 270will suspend 271.Nm 272operation. 273.It Fn pckbport_xt_translation tag slot on 274Passthrough of 275.Fn (*t_xt_translation) 276(see above). 277.It Fn pckbport_slot enable tag slot on 278Passthrough of 279.Fn (*t_slot_enable) 280(see above). 281.El 282.Ss Console interface 283On systems that can attach consoles through 284.Nm , 285the controller's console attachment function (called very early in 286autoconfiguration) calls 287.Fn pckbport_cnattach cookie ops slot . 288The first two arguments are the same as for 289.Fn pckbport_attach , 290while the third indicates which slot the console keyboard is attached to. 291.Fn pckbport_cnattach 292either calls 293.Fn pckbd_cnattach , 294if it is available, or 295.Fn pckbport_machdep_cnattach . 296The latter allows machine-dependent keyboard drivers to attach themselves, 297but it is only called if a device with the 298.Ql pckbport_machdep_cnattach 299attribute is configured into the system. 300.Fn pckbport_cnattach 301returns 0 on success and an error value on failure. 302.Fn pckbport_machdep_cnattach 303is expected to do the same. 304.Sh CODE REFERENCES 305The 306.Nm 307code, and the 308.Xr pckbd 4 309and 310.Xr pms 4 311device drivers are in 312.Pa sys/dev/pckbport . 313.Sh SEE ALSO 314.Xr pckbc 4 , 315.Xr pckbd 4 , 316.Xr pms 4 , 317.Xr autoconf 9 , 318.Xr spl 9 319.Sh HISTORY 320The 321.Nm 322system appeared in 323.Nx 2.0 . 324Before that, 325.Xr pckbd 4 326and 327.Xr pms 4 328attached directly to 329.Xr pckbc 4 330without any sensible way of using a different controller. 331