share/man/man4/proto.4

   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
  37 To compile this driver into the kernel,
  38 place the following line in your
  39 kernel configuration file:
  40 .Bd -ragged -offset indent
  41 .Cd "device proto"
  42 .Ed
  43 .Pp
  44 Alternatively, to load the driver as a
  45 module at boot time, place the following line in
  46 .Xr loader.conf 5 :
  47 .Bd -literal -offset indent
  48 proto_load="YES"
  49 .Ed
  50 .\"
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 device driver attaches to PCI devices when no other device drivers are
  55 present and creates device special files for all resources associated
  56 with the device.
  57 The driver itself has no knowledge of the device it attaches to.
  58 Programs can open these device special files and perform register-level
  59 reads and writes.
  60 As such, the
  61 .Nm
  62 device driver is nothing but a conduit or gateway between user space
  63 programs and the hardware device.
  64 .Pp
  65 Examples for why this is useful include hardware diagnostics and prototyping.
  66 In both these use cases, it is far more convenient to develop and run the
  67 logic in user space.
  68 Especially hardware diagnostics requires a somewhat user-friendly interface
  69 and adequate reporting.
  70 Neither is done easily as kernel code.
  71 .\"
  72 .Sh FILES
  73 All device special files corresponding to a PCI device are located under
  74 .Pa /dev/proto/pci<d>:<b>:<s>:<f>
  75 with
  76 .Pa pci<d>:<b>:<s>:<f>
  77 representing the location of the PCI device in the PCI hierarchy.
  78 A location includes:
  79 .Pp
  80 .Bl -tag -width XXXXXX -compact
  81 .It <d>
  82 The PCI domain number
  83 .It <b>
  84 The PCI bus number
  85 .It <s>
  86 The PCI slot or device number
  87 .It <f>
  88 The PCI function number
  89 .El
  90 .Pp
  91 Every PCI device has a device special file called
  92 .Pa pcicfg .
  93 This device special file gives access to the PCI configuration space.
  94 For each valid base address register (BAR), a device special file is created
  95 that contains the BAR offset and the resource type.
  96 A resource type can be either
  97 .Pa io
  98 or
  99 .Pa mem
 100 representing I/O port or memory mapped I/O space (resp.)
 101 .\"
 102 .Sh EXAMPLES
 103 A single function PCI device in domain 0, on bus 1, in slot 2 and having a
 104 single 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
 112 The
 113 .Nm
 114 device driver and this manual page were written by
 115 .An Marcel Moolenaar Aq Mt marcel@xcllnt.net .
 116 .Sh SECURITY CONSIDERATIONS
 117 Because programs have direct access to the hardware, the
 118 .Nm
 119 driver is inherently insecure.
 120 It is not advisable to use this driver on a production machine.
 121 .\"
 122 .Sh MISSING FUNCTIONALITY
 123 The
 124 .Nm
 125 driver does not yet support interrupts.
 126 Since interrupts cannot be handled by the driver itself, they must be converted
 127 into signals and delivered to the program that has registered for interrupts.
 128 .Pp
 129 In order to test the transmission or reception of data, some means of doing
 130 direct memory access (DMA) by the device must be possible.
 131 This too must be under the control of the program.
 132 The details of how a program can set up and
 133 initiate DMA still need to be fleshed out.
 134 .Pp
 135 Support for non-PCI devices has not been implemented yet.