diff options
Diffstat (limited to 'share/man/man4/proto.4')
-rw-r--r-- | share/man/man4/proto.4 | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/share/man/man4/proto.4 b/share/man/man4/proto.4 new file mode 100644 index 0000000..74aa49a --- /dev/null +++ b/share/man/man4/proto.4 @@ -0,0 +1,135 @@ +.\" +.\" Copyright (c) 2014 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 April 29, 2014 +.Dt PROTO 4 +.Os +.\" +.Sh NAME +.Nm proto +.Nd Driver for prototyping and H/W diagnostics +.\" +.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 +.\" +.Sh DESCRIPTION +The +.Nm +device driver attaches to PCI devices when no other device drivers are +present and 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 location includes: +.Pp +.Bl -tag -width XXXXXX -compact +.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. +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.) +.\" +.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 +.It Pa /dev/proto/pci0:1:2:0/10.mem +.It Pa /dev/proto/pci0:1:2:0/pcicfg +.El +.\" +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Marcel Moolenaar Aq 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. +.Pp +In order to test the transmission or reception of data, some means of doing +direct memory access (DMA) by the device must be possible. +This too must be under the control of the program. +The details of how a program can set up and +initiate DMA still need to be fleshed out. +.Pp +Support for non-PCI devices has not been implemented yet. |