.\"	$NetBSD: adb.4,v 1.4 2018/08/31 19:36:28 sevan Exp $
.\"
.\" Copyright (c) 2003 Alex Zepeda <zipzippy@sonic.net>
.\" Copyright (c) 1997 Colin Wood
.\" 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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed by Alex Zepeda, and
.\"      Colin Wood for the NetBSD Projet.
.\" 4. 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 31, 2018
.Dt ADB 4
.Os
.Sh NAME
.Nm adb
.Nd Apple Desktop Bus driver
.Sh SYNOPSIS
.Cd "adb* at obio?"
.Pp
.Cd "options MRG_ADB"
.Pp
.In machine/adbsys.h
.Sh DESCRIPTION
The Apple Desktop Bus
.Pq Tn ADB
is the single-master, multiple-slave, low-speed serial bus
interface used by Macintosh computers to connect input devices
such as keyboards, mice, trackpads, trackballs, and graphics tablets
to the machine.
.Nx
provides support for the Apple Desktop Bus as found on all supported
mac68k models, as well as macppc models with on-board
.Tn ADB
(PowerBooks and
.Dq Old World
models).
.Pp
The
.Nm
driver accesses the
.Tn ADB
controller using the so-called
.Dq HWDIRECT
method.
This method of access bypasses the Macintosh ROM and uses only
.Nx
routines for ADB access.
This is the only method supported on macppc and is the default for
mac68k systems.
.Pp
On mac68k systems there is an alternate method of accessing the
.Tn ADB
controller.
With the Macintosh ROM Glue
.Pq Tn MRG
method, the routines written for MacOS are used.
To enable this method of
.Tn ADB
access, uncomment the line:
.Pp
.Cd options MRG_ADB
.Pp
in your kernel configuration file.
.Pp
The
.Xr ioctl 2
call is used to control the
.Tn ADB
event device.
The following is a list of available
.Xr ioctl 2
commands:
.Bl -tag -width ADBIOC_GETREPEAT
.It Dv ADBIOC_DEVSINFO
Get
.Tn ADB
Device Info
.Pp
The
.Nm
event device will return an array of information containing an entry
for each device connected to the bus.
Each entry contains the current address, default address, and
handler ID for the corresponding
.Tn ADB
device.
.It Dv ADBIOC_GETREPEAT
Get Keyboard Repeat Info
.Pp
Returns a structure containing the current keyboard repeat delay
and keyboard repeat interval.
.It Dv ADBIOC_SETREPEAT
Set Keyboard Repeat Rate
.Pp
Sets the keyboard repeat delay and interval to the values specified
by
.Ar argp .
.It Dv ADBIOC_RESET
.Tn ADB
Reset
.Pp
Perform a reset of the
.Tn ADB
which will reinitialize all of the devices attached to the bus.
.It Dv ADBIOC_LISTENCMD
ADB Listen Command
.Pp
Send data to the register of the
.Tn ADB
device specified by
.Ar argp .
This command is not fully implemented at this time.
.El
.Sh SUPPORTED DEVICES
.Nx
includes support for the following
.Tn ADB
devices, sorted by driver name:
.Bl -tag -width akbd -offset indent
.It abtn
ADB mouse button?
.It aed
ADB event device
.It akbd
ADB keyboard
.It ams
ADB mouse
.It apm
APM emulation
.El
.Sh FILES
.Bl -tag -width /dev/adb -compact
.It Pa /dev/adb
The
.Tn ADB
event device.
.El
.Sh DIAGNOSTICS
.Bl -diag
.It aed0 at adb0 addr 0: ADB Event device
This is a normal autoconfiguration message noting the presence of the
.Nm
event device.
.It adb0 at obio0 offset 0x16000 irq 18: 2 targets
A standard autoconfiguration message indicating the initialization
of the
.Tn ADB
subsystem.
.It "adb: no devices found."
No
.Tn ADB
devices were found to be connected to the bus during autoconfiguration.
.It "adb: using %s series hardware support."
Indicates the class of
.Tn ADB
hardware support the machine uses.
.It "adb: hardware type unknown for this machine."
The
.Tn ADB
hardware in this machine is currently unsupported.
.It "adb: no ROM ADB driver in this kernel for this machine."
The kernel lacks the necessary Macintosh ROM Glue
.Pq Tn MRG
support for accessing the
.Tn ADB
hardware on this machine.
.It "adb: using serial console."
A serial console will be used for user input rather than the
.Tn ADB
event device.
.It "adb: %s at %d."
An
.Tn ADB
device of the type specified by
.Em %s
has been found at location
.Em %d .
.El
.Sh SEE ALSO
.Xr aed 4 ,
.Xr akbd 4 ,
.Xr ams 4 ,
.Xr apm 4
.Sh HISTORY
The
.Nm
interface first appeared in
.Nx 0.9 .
It has been under development ever since.
.Sh AUTHORS
.An -nosplit
.An "Bradley A. Grantham"
wrote the original
.Nm
driver, including the
.Tn MRG
support.
The hardware direct interface was written by
.An "John P. Wittkowski" .
The PowerManager interface was written by
.An "Takashi Hamada" .
.Sh BUGS
.Bl -bullet
.It
Not every class of
.Tn ADB
hardware is supported yet.
.It
The talk command is currently unimplemented.
.It
The listen command is not implemented yet.
.It
Not all multi-button mice are currently supported.
.It
Only mapped and relative-position
.Tn ADB
devices
.Pq i.e. keyboards and mice
are supported.
Thus absolute-position and other exotic devices will not work.
.It
Some of the diagnostic messages in this man page need to be updated.
.El
.Pp
Some mac68k machines contain so-called dirty ROM.
These machines are the: Mac SE/30, Mac II, Mac IIx, and Mac IIcx.
Machines with dirty ROM may experience trouble booting if the MRG code
is used, especially under the following conditions:
.Bl -bullet -compact -offset indent
.It
Both a keyboard and a mouse are not attached to the computer.
.It
An extended keyboard is attached to the computer.
.El
.Pp
On (some) machines with dirty ROM, the ROM indicates the presence of a
.Dq ghost
keyboard or mouse.
When this nonexistent device is probed for, the result is an infinite
loop.
This is believed to be triggered by the
.Nm
driver probing for extended mice, and non-EMP Logitech mice.