Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


PCKBPORT(9)                Kernel Developer's Manual               PCKBPORT(9)

NAME
     pckbport, pckbport_attach, pckbport_attach_slot, pckbport_cnattach,
     pckbportintr, pckbport_set_inputhandler, pckbport_flush,
     pckbport_poll_cmd, pckbport_enqueue_cmd, pckbport_poll_data,
     pckbport_set_poll, pckbport_xt_translation, pckbport_slot_enable - PC
     keyboard port interface

SYNOPSIS
     #include <dev/pckbport/pckbportvar.h>

     pckbport_tag_t
     pckbport_attach(void *, struct pckbport_accessops const *);

     struct device *
     pckbport_attach_slot(struct device *, pckbport_tag_t, pckbport_slot_t);

     int
     pckbport_cnattach(void *, struct pckbport_accessops const *,
         pckbport_slot_t);

     void
     pckbportintr(pckbport_tag_t, pckbport_slot_t, int);

     void
     pckbport_set_inputhandler(pckbport_tag_t, pckbport_slot_t,
         pckbport_inputfcn, void *, char *);

     void
     pckbport_flush(pckbport_tag_t, pckbport_slot_t);

     int
     pckbport_poll_cmd(pckbport_tag_t, pckbport_slot_t, u_char *, int, int,
         u_char *, int);

     int
     pckbport_enqueue_cmd(pckbport_tag_t, pckbport_slot_t, u_char *, int, int,
         int, u_char *);

     int
     pckbport_poll_data(pckbport_tag_t, pckbport_slot_t);

     void
     pckbport_set_poll(pckbport_tag_t, pckbport_slot_t, int);

     int
     pckbport_xt_translation(pckbport_tag_t, pckbport_slot_t, int);

     void
     pckbport_slot_enable(pckbport_tag_t, pckbport_slot_t, int);

DESCRIPTION
     The machine-independent pckbport subsystem provides an interface layer
     corresponding to the serial keyboard and mouse interface used on the IBM
     PS/2 and many other machines.  It interfaces a controller driver such as
     pckbc(4) to device drivers such as pckbd(4) and pms(4).

     A single controller can have up to two ports (known as "slots"), and
     these are identified by values of type pckbport_slot_t.  The values
     PCKBPORT_KBD_SLOT and PCKBPORT_AUX_SLOT should be used for keyboard and
     mouse ports respectively.  Each controller is identified by an opaque
     value of type pckbport_tag_t.

   Controller interface
     A PC keyboard controller registers itself by calling
     pckbport_attach(cookie, ops), with ops being a pointer to a struct
     pckbport_accessops containing pointers to functions for driving the
     controller, which will all be called with cookie as their first argument.
     pckbport_attach() returns the pckbport_tag_t assigned to the controller.
     The controller is then expected to call pckbport_attach_slot() for each
     slot with which it is equipped, passing the struct device * corresponding
     to the controller.  This function returns a pointer to the child device
     attached to the slot, or NULL if no such device was attached.

     The elements of struct pckbport_accessops each take as their first two
     arguments the cookie passed to pckbport_attach() and the slot in
     question.  The elements are:

     int (*t_xt_translation)(void *cookie, pckbport_slot_t slot, int on)
                       If 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).

     int (*t_send_devcmd)(void *cookie, pckbport_slot_t slot, u_char byte)
                       Send a single byte to the device without waiting for
                       completion.  Returns 1 on success, 0 on failure.

     int (*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 (*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.

     void (*t_slot_enable)(void *cookie, pckbport_slot_t slot, int on)
                       If 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.

     void (*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.

     void (*t_set_poll)(void *cookie, pckbport_slot_t slot, int on)
                       If on is non-zero, enable, otherwise disable, polling
                       mode on the slot.  In polling mode, data received from
                       the device are provided to (*t_poll_data1)() and not
                       passed to 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 pckbportintr(tag, slot, byte) once
                       for each byte received from the device.  When first
                       attached, a port should be in non-polling mode.

   Device interface
     Devices that attach to pckbport controllers do so using the normal
     autoconf(9) mechanism.  Their (*ca_match)() and (*ca_attach)() functions
     get passed a 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 tag
     and slot arguments to specify the slot to be acted on.

     pckbport_set_inputhandler(tag, slot, fn, arg, name)
                       Arrange for fn to be called with argument arg whenever
                       an unsolicited byte is received from the slot.  The
                       function will be called at spltty().

     pckbport_flush(tag, slot)
                       Ensure that there is no pending input from the slot.

     pckbport_poll_cmd(tag, slot, cmd, len, responselen, respbuf, slow)
                       Issue a complete device command, cmd, len bytes long,
                       expecting a response responselen bytes long, which will
                       be placed in respbuf.  If slow is true, the command is
                       expected to take over a second to execute.
                       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 pckbport_set_poll().

     pckbport_enqueue_cmd(tag, slot, cmd, len, responselen, sync, respbuf)
                       Issue a complete device command, cmd, len bytes long,
                       expecting a response responselen bytes long, which will
                       be places in respbuf.  If sync is true,
                       pckbport_enqueue_cmd() waits for the command to
                       complete before returning, otherwise it returns
                       immediately.  It is not safe to set sync when calling
                       from an interrupt context.  The 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.

     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
                       pckbport_enqueue_command().

     pckbport_set_poll(tag, slot, on)
                       If on is true, enable polling on the slot, otherwise
                       disable it.  In polling mode, pckbport_poll_cmd() can
                       be used to issue commands and pckbport_poll_data() to
                       read unsolicited data, without enabling interrupts.  In
                       non-polling mode, commands should be issued using
                       pckbport_enqueue_cmd(), unsolicited data are handled by
                       the input function, and disabling interrupts will
                       suspend pckbport operation.

     pckbport_xt_translation(tag, slot, on)
                       Passthrough of (*t_xt_translation)() (see above).

     pckbport_slot(enable, tag, slot, on)
                       Passthrough of (*t_slot_enable)() (see above).

   Console interface
     On systems that can attach consoles through pckbport, the controller's
     console attachment function (called very early in autoconfiguration)
     calls pckbport_cnattach(cookie, ops, slot).  The first two arguments are
     the same as for pckbport_attach(), while the third indicates which slot
     the console keyboard is attached to.  pckbport_cnattach() either calls
     pckbd_cnattach(), if it is available, or pckbport_machdep_cnattach().
     The latter allows machine-dependent keyboard drivers to attach
     themselves, but it is only called if a device with the
     `pckbport_machdep_cnattach' attribute is configured into the system.
     pckbport_cnattach() returns 0 on success and an error value on failure.
     pckbport_machdep_cnattach() is expected to do the same.

CODE REFERENCES
     The pckbport code, and the pckbd(4) and pms(4) device drivers are in
     sys/dev/pckbport.

SEE ALSO
     pckbc(4), pckbd(4), pms(4), autoconf(9), spl(9)

HISTORY
     The pckbport system appeared in NetBSD 2.0.  Before that, pckbd(4) and
     pms(4) attached directly to pckbc(4) without any sensible way of using a
     different controller.

NetBSD 10.99                    August 5, 2004                    NetBSD 10.99