.\" .\" Copyright (c) 2014, 2015 Marcel Moolenaar .\" 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. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd July 19, 2015 .Dt PROTO 4 .Os .\" .Sh NAME .Nm proto .Nd Generic prototyping and diagnostics driver .\" .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "device proto" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent proto_load="YES" .Ed .Pp To have the driver attach to a device instead of its regular driver, mention it in the list of devices assigned to the following loader variable: .Bd -ragged -offset indent hw.proto.attach="desc[,desc]" .Ed .\" .Sh DESCRIPTION The .Nm device driver attaches to PCI or ISA devices when no other device drivers are present for those devices and it creates device special files for all resources associated with the device. The driver itself has no knowledge of the device it attaches to. Programs can open these device special files and perform register-level reads and writes. As such, the .Nm device driver is nothing but a conduit or gateway between user space programs and the hardware device. .Pp Examples for why this is useful include hardware diagnostics and prototyping. In both these use cases, it is far more convenient to develop and run the logic in user space. Especially hardware diagnostics requires a somewhat user-friendly interface and adequate reporting. Neither is done easily as kernel code. .\" .Sh FILES All device special files corresponding to a PCI device are located under .Pa /dev/proto/pci::: with .Pa pci::: representing the location of the PCI device in the PCI hierarchy. A PCI location includes: .Pp .Bl -tag -width XXXXXX -compact -offset indent .It The PCI domain number .It The PCI bus number .It The PCI slot or device number .It The PCI function number .El .Pp Every PCI device has a device special file called .Pa pcicfg . This device special file gives access to the PCI configuration space. A device special file called .Pa busdma is also created. This device special file provides the interfaces needed for doing DMA. For each valid base address register (BAR), a device special file is created that contains the BAR offset and the resource type. A resource type can be either .Pa io or .Pa mem representing I/O port or memory mapped I/O space (resp.) .Pp ISA devices do not have a location. Instead, they are identified by the first I/O port address or first memory mapped I/O address. Consequently, all device special files corresponding to an ISA device are located under .Pa /dev/proto/isa: with .Pa addr the address in hexadecimal notation. For each I/O port or memory mapped I/O address, a device special file is created that contains the resource identification used by the kernel and the resource type. The resource type can be either .Pa io or .Pa mem representing I/O port or memory mapped I/O space (resp.) When the device has a DMA channel assigned to it, a device special file with the name .Pa busdma is created as well. This device special file provides the interfaces needed for doing DMA. .Pp If the ISA device is not a Plug-and-Play device nor present in the ACPI device tree, it must have the appropriate hints so that the kernel can reserve the resources for it. .\" .Sh EXAMPLES A single function PCI device in domain 0, on bus 1, in slot 2 and having a single memory mapped I/O region will have the following device special files: .Pp .Bl -tag -width XXXXXX -compact -offset indent .It Pa /dev/proto/pci0:1:2:0/10.mem .It Pa /dev/proto/pci0:1:2:0/pcicfg .El .Pp A legacy floppy controller will have the following device files: .Pp .Bl -tag -width XXXXXX -compact -offset indent .It Pa /dev/proto/isa:0x3f0/00.io .It Pa /dev/proto/isa:0x3f0/01.io .It Pa /dev/proto/isa:0x3f0/busdma .El .\" .Sh AUTHORS The .Nm device driver and this manual page were written by .An Marcel Moolenaar Aq Mt marcel@xcllnt.net . .Sh SECURITY CONSIDERATIONS Because programs have direct access to the hardware, the .Nm driver is inherently insecure. It is not advisable to use this driver on a production machine. .\" .Sh MISSING FUNCTIONALITY The .Nm driver does not yet support interrupts. Since interrupts cannot be handled by the driver itself, they must be converted into signals and delivered to the program that has registered for interrupts. A satisfactory mechanism for keeping the interrupt masked during the signal handling is still being worked out. .Pp DMA support for devices other than busmaster devices is not present yet. The details of how a program is to interact with the DMA controller still need to be fleshed out.