[src/trunk]: src/share/man/man9 Kernel-internal documentation for pckbport.

[bjh21 <bjh21%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/1866389fd44a
branches:  trunk
changeset: 559601:1866389fd44a
user:      bjh21 <bjh21%NetBSD.org@localhost>
date:      Sat Mar 20 21:28:59 2004 +0000

description:
Kernel-internal documentation for pckbport.

diffstat:

 share/man/man9/Makefile   |   16 ++-
 share/man/man9/pckbport.9 |  320 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 334 insertions(+), 2 deletions(-)

diffs (truncated from 361 to 300 lines):

diff -r 84f59888e060 -r 1866389fd44a share/man/man9/Makefile
--- a/share/man/man9/Makefile   Sat Mar 20 21:25:55 2004 +0000
+++ b/share/man/man9/Makefile   Sat Mar 20 21:28:59 2004 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.156 2004/02/18 13:35:46 yamt Exp $
+#       $NetBSD: Makefile,v 1.157 2004/03/20 21:28:59 bjh21 Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -23,7 +23,7 @@
        malloc.9 mbuf.9 mca.9 memcmp.9 memcpy.9 memmove.9 memset.9 \
        microtime.9 mstohz.9 namecache.9 namei.9 need_resched.9 \
        opencrypto.9 \
-       panic.9 pci.9 pci_configure_bus.9 pci_intr.9 \
+       panic.9 pci.9 pci_configure_bus.9 pci_intr.9 pckbport.9 \
        pcmcia.9 pfil.9 physio.9 pmap.9 pmatch.9 pmc.9 \
        pool.9 pool_cache.9 powerhook_establish.9 ppsratecheck.9 \
        properties.9 preempt.9 \
@@ -327,6 +327,18 @@
        pci.9 PCI_REVISION.9
 MLINKS+=pci_configure_bus.9 pci_conf_hook.9 \
        pci_configure_bus.9 pci_conf_interrupt.9
+MLINKS+=pckbport.9 pckbport_attach.9 \
+       pckbport.9 pckbport_attach_slot.9 \
+       pckbport.9 pckbport_cnattach.9 \
+       pckbport.9 pckbportintr.9 \
+       pckbport.9 pckbport_set_inputhandle.9 \
+       pckbport.9 pckbport_flush.9 \
+       pckbport.9 pckbport_poll_cmd.9 \
+       pckbport.9 pckbport_enqueue_cmd.9 \
+       pckbport.9 pckbport_poll_data.9 \
+       pckbport.9 pckbport_set_poll.9 \
+       pckbport.9 pckbport_xt_translation.9 \
+       pckbport.9 pckbport_slot_enable.9
 MLINKS+=pcmcia.9 pcmcia_function_init.9 \
        pcmcia.9 pcmcia_function_enable.9 \
        pcmcia.9 pcmcia_function_disable.9 \
diff -r 84f59888e060 -r 1866389fd44a share/man/man9/pckbport.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/pckbport.9 Sat Mar 20 21:28:59 2004 +0000
@@ -0,0 +1,320 @@
+.\" $NetBSD: pckbport.9,v 1.1 2004/03/20 21:28:59 bjh21 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 March 20, 2004
+.Os
+.Dt PCKBPORT 9
+.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.
+.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.
+.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, and to be passed to
+.Fn pckbportintr .
+.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 places 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 ,