| blob | f7d93923a9851279a4478d3efc8a6ac55a043230 |
1 .\" $NetBSD: pckbport.9,v 1.4 2004/08/07 10:03:29 wiz 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 *" \
54 pckbport_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 \
59 pckbport_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 \
67 int "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
77 The machine-independent
78 .Nm
79 subsystem provides an interface layer corresponding to the serial
80 keyboard and mouse interface used on the
81 .Tn IBM PS/2
82 and many other machines.
83 It interfaces a controller driver such as
84 .Xr pckbc 4
85 to device drivers such as
86 .Xr pckbd 4
87 and
88 .Xr pms 4 .
89 .Pp
90 A single controller can have up to two ports (known as
91 .Dq slots ) ,
92 and these are identified by values of type
93 .Fa pckbport_slot_t .
94 The values
95 .Dv PCKBPORT_KBD_SLOT
96 and
97 .Dv PCKBPORT_AUX_SLOT
98 should be used for keyboard and mouse ports respectively.
99 Each controller is identified by an opaque value of type
100 .Fa pckbport_tag_t .
101 .Ss Controller interface
102 A PC keyboard controller registers itself by calling
103 .Fn pckbport_attach cookie ops ,
104 with
105 .Fa ops
106 being a pointer to a
107 .Fa struct pckbport_accessops
108 containing pointers to functions for driving the controller, which will
109 all be called with
110 .Fa cookie
111 as their first argument.
112 .Fn pckbport_attach
113 returns the
114 .Fa pckbport_tag_t
115 assigned to the controller.
116 The controller is then expected to call
117 .Fn pckbport_attach_slot
118 for each slot with which it is equipped, passing the
119 .Fa "struct device *"
120 corresponding to the controller.
121 This function returns a pointer to the child device attached to the slot,
122 or
123 .Dv NULL
124 if no such device was attached.
125 .Pp
126 The elements of
127 .Fa "struct pckbport_accessops"
128 each take as their first two arguments the
129 .Fa cookie
130 passed to
131 .Fn pckbport_attach
132 and the slot in question.
133 The elements are:
134 .Bl -tag -width Fn
135 .It Fa int Fn (*t_xt_translation) "void *cookie" "pckbport_slot_t slot" \
136 "int on"
137 If
138 .Fa on
139 is non-zero, enable, otherwise disable, AT-to-XT keycode translation
140 on the slot specified.
141 Returns 1 on success, 0 on failure (or if the controller does not support such
142 translation).
143 .It Fa int Fn (*t_send_devcmd) "void *cookie" "pckbport_slot_t slot" \
144 "u_char byte"
145 Send a single
146 .Fa byte
147 to the device without waiting for completion.
148 Returns 1 on success, 0 on failure.
149 .It Fa int Fn (*t_poll_data1) "void *cookie" "pckbport_slot_t slot"
150 Wait for and return one byte of data from the device, without using interrupts.
151 This function will only be called after
152 .Fn "(*t_set_poll)"
153 has been used to put the slot in polling mode.
154 If 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"
156 If
157 .Fa on
158 is non-zero, enable, otherwise disable, the slot.
159 If a slot is disabled, it can be powered down, and is not expected to
160 generate any interrupts.
161 When first attached, ports should be disabled.
162 .It Fa void Fn (*t_intr_establish) "void *cookie" "pckbport_slot_t slot"
163 Set up an interrupt handler for the slot.
164 Called when a device gets attached to it.
165 .It Fa void Fn (*t_set_poll) "void *cookie" "pckbport_slot_t slot" "int on"
166 If
167 .Fa on
168 is non-zero, enable, otherwise disable, polling mode on the slot.
169 In polling mode, data received from the device are provided to
170 .Fn (*t_poll_data1)
171 and not passed to
172 .Fn pckbportintr ,
173 whether or not interrupts are enabled.
174 In non-polling mode,
175 data from the device are expected to cause interrupts.
176 The controller interrupt handler should call
177 .Fn pckbportintr tag slot byte
178 once for each
179 .Va byte
180 received from the device.
181 When first attached, a port should be in non-polling mode.
182 .El
183 .Ss Device interface
184 Devices that attach to
185 .Nm
186 controllers do so using the normal
187 .Xr autoconf 9
188 mechanism.
189 Their
190 .Fn (*ca_match)
191 and
192 .Fn (*ca_attach)
193 functions get passed a
194 .Fa "struct pckbport_attach_args"
195 which contains the controller and slot number where the device was found.
196 Device drivers can use the following functions to communicate with the
197 controller.
198 Each takes
199 .Fa tag
200 and
201 .Fa slot
202 arguments to specify the slot to be acted on.
203 .Bl -tag -width Fn
204 .It Fn pckbport_set_inputhandler tag slot fn arg name
205 Arrange for
206 .Fa fn
207 to be called with argument
208 .Fa arg
209 whenever an unsolicited byte is received from the slot.
210 The function will be called at
211 .Fn spltty .
212 .It Fn pckbport_flush tag slot
213 Ensure that there is no pending input from the slot.
214 .It Fn pckbport_poll_cmd tag slot cmd len responselen respbuf slow
215 Issue a complete device command,
216 .Fa cmd ,
217 .Fa len
218 bytes long, expecting a response
219 .Fa responselen
220 bytes long, which will be placed in
221 .Fa respbuf .
222 If
223 .Fa slow
224 is true, the command is expected to take over a second to execute.
225 .Fn pckbport_poll_cmd
226 handles getting an acknowledgement from the device and retrying the command
227 if necessary.
228 Returns 0 on success, and an error value on failure.
229 This function should only be called during autoconfiguration or when the
230 slot 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
233 Issue a complete device command,
234 .Fa cmd ,
235 .Fa len
236 bytes long, expecting a response
237 .Fa responselen
238 bytes long, which will be places in
239 .Fa respbuf .
240 If
241 .Fa sync
242 is true,
243 .Fn pckbport_enqueue_cmd
244 waits for the command to complete before returning, otherwise it returns
245 immediately.
246 It is not safe to set
247 .Fa sync
248 when calling from an interrupt context.
249 The
250 .Nm pckbport
251 layer handles getting an acknowledgement from the device and retrying
252 the command if necessary.
253 Returns 0 on success, and an error value on failure.
254 .It Fn pckbport_poll_data tag slot
255 Low-level command to poll for a single byte of data from the device, but
256 ignoring 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
259 If
260 .Fa on
261 is true, enable polling on the slot, otherwise disable it.
262 In polling mode,
263 .Fn pckbport_poll_cmd
264 can be used to issue commands and
265 .Fn pckbport_poll_data
266 to read unsolicited data, without enabling interrupts.
267 In non-polling mode, commands should be issued using
268 .Fn pckbport_enqueue_cmd ,
269 unsolicited data are handled by the input function, and disabling interrupts
270 will suspend
271 .Nm
272 operation.
273 .It Fn pckbport_xt_translation tag slot on
274 Passthrough of
275 .Fn (*t_xt_translation)
276 (see above).
277 .It Fn pckbport_slot enable tag slot on
278 Passthrough of
279 .Fn (*t_slot_enable)
280 (see above).
281 .El
282 .Ss Console interface
283 On systems that can attach consoles through
284 .Nm ,
285 the controller's console attachment function (called very early in
286 autoconfiguration) calls
287 .Fn pckbport_cnattach cookie ops slot .
288 The first two arguments are the same as for
289 .Fn pckbport_attach ,
290 while the third indicates which slot the console keyboard is attached to.
291 .Fn pckbport_cnattach
292 either calls
293 .Fn pckbd_cnattach ,
294 if it is available, or
295 .Fn pckbport_machdep_cnattach .
296 The latter allows machine-dependent keyboard drivers to attach themselves,
297 but it is only called if a device with the
298 .Ql pckbport_machdep_cnattach
299 attribute is configured into the system.
300 .Fn pckbport_cnattach
301 returns 0 on success and an error value on failure.
302 .Fn pckbport_machdep_cnattach
303 is expected to do the same.
304 .Sh CODE REFERENCES
305 The
306 .Nm
307 code, and the
308 .Xr pckbd 4
309 and
310 .Xr pms 4
311 device 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
320 The
321 .Nm
322 system appeared in
323 .Nx 2.0 .
324 Before that,
325 .Xr pckbd 4
326 and
327 .Xr pms 4
328 attached directly to
329 .Xr pckbc 4
330 without any sensible way of using a different controller.