1.\" 2.\" Copyright (c) 2014 Marcel Moolenaar 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd April 29, 2014 29.Dt PROTO 4 30.Os 31.\" 32.Sh NAME 33.Nm proto 34.Nd Driver for prototyping and H/W diagnostics 35.\" 36.Sh SYNOPSIS 37To compile this driver into the kernel, 38place the following line in your 39kernel configuration file: 40.Bd -ragged -offset indent 41.Cd "device proto" 42.Ed 43.Pp 44Alternatively, to load the driver as a 45module at boot time, place the following line in 46.Xr loader.conf 5 : 47.Bd -literal -offset indent 48proto_load="YES" 49.Ed 50.\" 51.Sh DESCRIPTION 52The 53.Nm 54device driver attaches to PCI devices when no other device drivers are 55present and creates device special files for all resources associated 56with the device. 57The driver itself has no knowledge of the device it attaches to. 58Programs can open these device special files and perform register-level 59reads and writes. 60As such, the 61.Nm 62device driver is nothing but a conduit or gateway between user space 63programs and the hardware device. 64.Pp 65Examples for why this is useful include hardware diagnostics and prototyping. 66In both these use cases, it is far more convenient to develop and run the 67logic in user space. 68Especially hardware diagnostics requires a somewhat user-friendly interface 69and adequate reporting. 70Neither is done easily as kernel code. 71.\" 72.Sh FILES 73All device special files corresponding to a PCI device are located under 74.Pa /dev/proto/pci<d>:<b>:<s>:<f> 75with 76.Pa pci<d>:<b>:<s>:<f> 77representing the location of the PCI device in the PCI hierarchy. 78A location includes: 79.Pp 80.Bl -tag -width XXXXXX -compact 81.It <d> 82The PCI domain number 83.It <b> 84The PCI bus number 85.It <s> 86The PCI slot or device number 87.It <f> 88The PCI function number 89.El 90.Pp 91Every PCI device has a device special file called 92.Pa pcicfg . 93This device special file gives access to the PCI configuration space. 94For each valid base address register (BAR), a device special file is created 95that contains the BAR offset and the resource type. 96A resource type can be either 97.Pa io 98or 99.Pa mem 100representing I/O port or memory mapped I/O space (resp.) 101.\" 102.Sh EXAMPLES 103A single function PCI device in domain 0, on bus 1, in slot 2 and having a 104single memory mapped I/O region will have the following device special files: 105.Pp 106.Bl -tag -width XXXXXX -compact 107.It Pa /dev/proto/pci0:1:2:0/10.mem 108.It Pa /dev/proto/pci0:1:2:0/pcicfg 109.El 110.\" 111.Sh AUTHORS 112The 113.Nm 114device driver and this manual page were written by 115.An Marcel Moolenaar Aq Mt marcel@xcllnt.net . 116.Sh SECURITY CONSIDERATIONS 117Because programs have direct access to the hardware, the 118.Nm 119driver is inherently insecure. 120It is not advisable to use this driver on a production machine. 121.\" 122.Sh MISSING FUNCTIONALITY 123The 124.Nm 125driver does not yet support interrupts. 126Since interrupts cannot be handled by the driver itself, they must be converted 127into signals and delivered to the program that has registered for interrupts. 128.Pp 129In order to test the transmission or reception of data, some means of doing 130direct memory access (DMA) by the device must be possible. 131This too must be under the control of the program. 132The details of how a program can set up and 133initiate DMA still need to be fleshed out. 134.Pp 135Support for non-PCI devices has not been implemented yet. 136