man/man4/proto.4

.\"
.\" 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<d>:<b>:<s>:<f>
with
.Pa pci<d>:<b>:<s>:<f>
representing the location of the PCI device in the PCI hierarchy.
A PCI location includes:
.Pp
.Bl -tag -width XXXXXX -compact -offset indent
.It <d>
The PCI domain number
.It <b>
The PCI bus number
.It <s>
The PCI slot or device number
.It <f>
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:<addr>
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.