share/man/man4/proto.4

   1 .\"
   2 .\" Copyright (c) 2014, 2015 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 August 7, 2015
  29 .Dt PROTO 4
  30 .Os
  31 .\"
  32 .Sh NAME
  33 .Nm proto
  34 .Nd Generic prototyping and diagnostics driver
  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 .Pp
  51 To have the driver attach to a device instead of its regular driver,
  52 mention it in the list of devices assigned to the following loader variable:
  53 .Bd -ragged -offset indent
  54 hw.proto.attach="desc[,desc]"
  55 .Ed
  56 .\"
  57 .Sh DESCRIPTION
  58 The
  59 .Nm
  60 device driver attaches to PCI or ISA devices when no other device drivers
  61 are present for those devices and it creates device special files for all
  62 resources associated with the device.
  63 The driver itself has no knowledge of the device it attaches to.
  64 Programs can open these device special files and perform register-level
  65 reads and writes.
  66 As such, the
  67 .Nm
  68 device driver is nothing but a conduit or gateway between user space
  69 programs and the hardware device.
  70 .Pp
  71 Examples for why this is useful include hardware diagnostics and prototyping.
  72 In both these use cases, it is far more convenient to develop and run the
  73 logic in user space.
  74 Especially hardware diagnostics requires a somewhat user-friendly interface
  75 and adequate reporting.
  76 Neither is done easily as kernel code.
  77 .Ss I/O port resources
  78 Device special files created for I/O port resources allow
  79 .Xr lseek 2 ,
  80 .Xr read 2 ,
  81 .Xr write 2
  82 and
  83 .Xr ioctl 2
  84 operations to be performed on them.
  85 The
  86 .Xr read 2
  87 and
  88 .Xr write 2
  89 system calls are used to perform input and output (resp.) on the port.
  90 The amount of data that can be read or written at any single time is either
  91 1, 2 or 4 bytes.
  92 While the
  93 .Nm
  94 driver does not prevent reading or writing 8 bytes at a time for some
  95 architectures, it should not be assumed that such actually produces
  96 correct results.
  97 The
  98 .Xr lseek 2
  99 system call is used to select the port number, relative to the I/O port
 100 region being represented by the device special file.
 101 If, for example, the device special file corresponds to an I/O port region
 102 from 0x3f8 to 0x3ff inclusive, then an offset of 4 given to lseek with a
 103 whence value of SEEK_SET will target port 0x3fc on the next read or write
 104 operation.
 105 The
 106 .Xr ioctl 2
 107 system call can be used for the
 108 .Dv PROTO_IOC_REGION
 109 request.
 110 This ioctl request returns the extend of the resource covered by this
 111 device special file. The extend is returned in the following structure:
 112 .Bd -literal
 113 struct proto_ioc_region {
 114         unsigned long   address;
 115         unsigned long   size;
 116 };
 117 .Ed
 118 .Ss Memory mapped I/O resources
 119 The device special files created for memory mapped I/O resources behave
 120 in the same way as those created for I/O port resources.
 121 Additionally, device special files for memory mapped I/O resources allow
 122 the memory to be mapped into the process' address space using
 123 .Xr mmap 2 .
 124 Reads and writes to the memory address returned by
 125 .Xr mmap 2
 126 go directly to the hardware.
 127 As such the use of
 128 .Xr read 2
 129 and
 130 .Xr write 2
 131 can be avoided, reducing the access overhead significantly.
 132 Alignment and access width constraints put forth by the underlying device
 133 apply.
 134 Also, make sure the compiler does not optimize memory accesses away or has
 135 them coalesced into bigger accesses.
 136 .Ss DMA pseudo resource
 137 A device special file named
 138 .Pa busdma
 139 is created for the purpose of doing DMA.
 140 It only supports
 141 .Xr ioctl 2
 142 and only for the
 143 .Dv PROTO_IOC_BUSDMA
 144 request.
 145 This device special file does not support
 146 .Xr read 2
 147 nor
 148 .Xr write 2 .
 149 The
 150 .Dv PROTO_IOC_BUSDMA
 151 request has an argument that is both in and out and is defined as
 152 follows:
 153 .Bd -literal
 154 struct proto_ioc_busdma {
 155         unsigned int    request;
 156         unsigned long   key;
 157         union {
 158                 struct {
 159                         unsigned long   align;
 160                         unsigned long   bndry;
 161                         unsigned long   maxaddr;
 162                         unsigned long   maxsz;
 163                         unsigned long   maxsegsz;
 164                         unsigned int    nsegs;
 165                         unsigned int    datarate;
 166                         unsigned int    flags;
 167                 } tag;
 168                 struct {
 169                         unsigned long   tag;
 170                         unsigned int    flags;
 171                         unsigned long   virt_addr;
 172                         unsigned long   virt_size;
 173                         unsigned int    phys_nsegs;
 174                         unsigned long   phys_addr;
 175                         unsigned long   bus_addr;
 176                         unsigned int    bus_nsegs;
 177                 } md;
 178                 struct {
 179                         unsigned int    op;
 180                         unsigned long   base;
 181                         unsigned long   size;
 182                 } sync;
 183         } u;
 184         unsigned long   result;
 185 };
 186 .Ed
 187 The
 188 .Va request
 189 field is used to specify which DMA operation is to be performed.
 190 The
 191 .Va key
 192 field is used to specify which object the operation applies to.
 193 An object is either a tag or a memory descriptor (md).
 194 The following DMA operations are defined:
 195 .Bl -tag -width XXXX
 196 .It PROTO_IOC_BUSDMA_TAG_CREATE
 197 Create a root tag.
 198 The
 199 .Va result
 200 field is set on output with the key of the DMA tag.
 201 The tag is created with the constraints given by the
 202 .Va tag
 203 sub-structure. These constraints correspond roughly to those that can be
 204 given to the
 205 .Xr bus_dma_tag_create 9
 206 function.
 207 .It PROTO_IOC_BUSDMA_TAG_DERIVE
 208 Create a derived tag.
 209 The
 210 .Va key
 211 field is used to identify the parent tag from which to derive the new tag.
 212 The key of the derived tag is returned in the
 213 .Va result
 214 field.
 215 The derived tag combines the constraints of the parent tag with those
 216 given by the
 217 .Va tag
 218 sub-structure.
 219 The combined constraints are written back to the
 220 .Va tag
 221 sub-structure on return.
 222 .It PROTO_IOC_BUSDMA_TAG_DESTROY
 223 Destroy a root or derived tag previously created.
 224 The
 225 .Va key
 226 field specifies the tag to destroy.
 227 A tag can only be destroyed when not referenced anymore.
 228 This means that derived tags that have this tag as a parent and memory
 229 descriptors created from this tag must be destroyed first.
 230 .It PROTO_IOC_BUSDMA_MEM_ALLOC
 231 Allocate memory that satisfies the constraints put forth by the tag
 232 given in the
 233 .Va tag
 234 field of the
 235 .Va md
 236 sub-structure.
 237 The key of the memory descriptor for this memory is returned in the
 238 .Va result
 239 field.
 240 The
 241 .Va md
 242 sub-structure is filled on return with details of the allocation.
 243 The kernel virtual address and the size of the allocated memory are returned
 244 in the
 245 .Va virt_addr
 246 and
 247 .Va virt_size
 248 fields.
 249 The number of contigous physical memory segments and the address of the first
 250 segment are returned in the
 251 .Va phys_nsegs
 252 and
 253 .Va phys_addr
 254 fields.
 255 Allocated memory is automatically loaded and thus mapped into bus space.
 256 The number of bus segments and the address of the first segment are returned
 257 in the
 258 .Va bus_nsegs
 259 and
 260 .Va bus_addr
 261 fields.
 262 The behaviour of this operation banks heavily on how
 263 .Xr bus_dmamem_alloc 9
 264 is implemented, which means that memory is currently always allocated as a
 265 single contigous region of physical memory.
 266 In practice this also tends to give a single contigous region in bus space.
 267 This may change over time.
 268 .It PROTO_IOC_BUSDMA_MEM_FREE
 269 Free previously allocated memory and destroy the memory desciptor.
 270 The
 271 .Nm
 272 driver is not in a position to track whether the memory has been mapped in
 273 the process' address space, so the application is responsible for unmapping
 274 the memory before it is freed.
 275 The
 276 .Nm
 277 driver also cannot protect against the hardware writing to or reading from
 278 the memory, even after it has been freed.
 279 When the memory is reused for other purposes it can be corrupted or cause
 280 the hardware to behave in unpredictable ways when DMA has not stopped
 281 completely before freeing.
 282 .It PROTO_IOC_BUSDMA_MD_CREATE
 283 Create an empty memory descriptor with the tag specified in the
 284 .Va tag
 285 field of the
 286 .Va md
 287 sub-structure.
 288 The key of the memory descriptor is returned in the
 289 .Va result
 290 field.
 291 .It PROTO_IOC_BUSDMA_MD_DESTROY
 292 Destroy the previously created memory descriptor specified by the
 293 .Va key
 294 field.
 295 When the memory descriptor is still loaded, it is unloaded first.
 296 .It PROTO_IOC_BUSDMA_MD_LOAD
 297 Load a contigous region of memory in the memory descriptor specified by the
 298 .Va key
 299 field.
 300 The size and address in the process' virtual address space are specified
 301 by the
 302 .Va virt_size
 303 and
 304 .Va virt_addr
 305 fields.
 306 On return, the
 307 .Va md
 308 sub-structure contains the result of the operation.
 309 The number of physical segments and the address of the first segment is
 310 returned in the
 311 .Va phys_nsegs
 312 and
 313 .Va phys_addr
 314 fields.
 315 The number of bus space segments and the address of the first segment in
 316 bus space is returned in the
 317 .Va bus_nsegs
 318 and
 319 .Va bus_addr
 320 fields.
 321 .It PROTO_IOC_BUSDMA_MD_UNLOAD
 322 Unload the memory descriptor specified by the
 323 .Va key
 324 field.
 325 .It PROTO_IOC_BUSDMA_SYNC
 326 Guarantee that all hardware components have a coherent view of the memory
 327 tracked by the memory descriptor, specified by the
 328 .Va key
 329 field.
 330 A sub-section of the memory can be targeted by specifying the relative
 331 offset and size of the memory to make coherent.
 332 The offset and size are given by the
 333 .Va base
 334 and
 335 .Va size
 336 fields of the
 337 .Va sync
 338 sub-structure.
 339 The
 340 .Va op
 341 field holds the sync operation to be performed.
 342 This is similar to the
 343 .Xr bus_dmamap_sync 9
 344 function.
 345 .El
 346 .Ss PCI configuration space
 347 Access to PCI configuration space is possible through the
 348 .Pa pcicfg
 349 device special file.
 350 The device special file supports
 351 .Xr lseek 2 ,
 352 .Xr read 2
 353 and
 354 .Xr write 2 .
 355 Usage is the asme as for I/O port resources.
 356 .Sh FILES
 357 All device special files corresponding to a PCI device are located under
 358 .Pa /dev/proto/pci<d>:<b>:<s>:<f>
 359 with
 360 .Pa pci<d>:<b>:<s>:<f>
 361 representing the location of the PCI device in the PCI hierarchy.
 362 A PCI location includes:
 363 .Pp
 364 .Bl -tag -width XXXXXX -compact -offset indent
 365 .It <d>
 366 The PCI domain number
 367 .It <b>
 368 The PCI bus number
 369 .It <s>
 370 The PCI slot or device number
 371 .It <f>
 372 The PCI function number
 373 .El
 374 .Pp
 375 Every PCI device has a device special file called
 376 .Pa pcicfg .
 377 This device special file gives access to the PCI configuration space.
 378 A device special file called
 379 .Pa busdma
 380 is also created.
 381 This device special file provides the interfaces needed for doing DMA.
 382 For each valid base address register (BAR), a device special file is created
 383 that contains the BAR offset and the resource type.
 384 A resource type can be either
 385 .Pa io
 386 or
 387 .Pa mem
 388 representing I/O port or memory mapped I/O space (resp.)
 389 .Pp
 390 ISA devices do not have a location. Instead, they are identified by the
 391 first I/O port address or first memory mapped I/O address.
 392 Consequently, all device special files corresponding to an ISA device are
 393 located under
 394 .Pa /dev/proto/isa:<addr>
 395 with
 396 .Pa addr
 397 the address in hexadecimal notation.
 398 For each I/O port or memory mapped I/O address, a device special file is
 399 created that contains the resource identification used by the kernel and
 400 the resource type.
 401 The resource type can be either
 402 .Pa io
 403 or
 404 .Pa mem
 405 representing I/O port or memory mapped I/O space (resp.)
 406 When the device has a DMA channel assigned to it, a device special file
 407 with the name
 408 .Pa busdma
 409 is created as well.
 410 This device special file provides the interfaces needed for doing DMA.
 411 .Pp
 412 If the ISA device is not a Plug-and-Play device nor present in the ACPI
 413 device tree, it must have the appropriate hints so that the kernel can
 414 reserve the resources for it.
 415 .\"
 416 .Sh EXAMPLES
 417 A single function PCI device in domain 0, on bus 1, in slot 2 and having a
 418 single memory mapped I/O region will have the following device special files:
 419 .Pp
 420 .Bl -tag -width XXXXXX -compact -offset indent
 421 .It Pa /dev/proto/pci0:1:2:0/10.mem
 422 .It Pa /dev/proto/pci0:1:2:0/pcicfg
 423 .El
 424 .Pp
 425 A legacy floppy controller will have the following device files:
 426 .Pp
 427 .Bl -tag -width XXXXXX -compact -offset indent
 428 .It Pa /dev/proto/isa:0x3f0/00.io
 429 .It Pa /dev/proto/isa:0x3f0/01.io
 430 .It Pa /dev/proto/isa:0x3f0/busdma
 431 .El
 432 .\"
 433 .Sh SEE ALSO
 434 .Xr ioctl 2 ,
 435 .Xr lseek 2 ,
 436 .Xr mmap 2 ,
 437 .Xr read 2 ,
 438 .Xr write 2 ,
 439 .Xr bus_dma_tag_create 9 ,
 440 .Xr bus_dmamap_sync 9 ,
 441 .Xr bus_dmamem_alloc 9
 442 .\"
 443 .Sh AUTHORS
 444 The
 445 .Nm
 446 device driver and this manual page were written by
 447 .An Marcel Moolenaar Aq Mt marcel@xcllnt.net .
 448 .Sh SECURITY CONSIDERATIONS
 449 Because programs have direct access to the hardware, the
 450 .Nm
 451 driver is inherently insecure.
 452 It is not advisable to use this driver on a production machine.
 453 .\"
 454 .Sh MISSING FUNCTIONALITY
 455 The
 456 .Nm
 457 driver does not fully support memory descriptors that need multiple
 458 physical memory segments or multiple bus space segments.
 459 At the very least, an operation is needed on the DMA pseudo resource
 460 for the application to obtain all segments.
 461 .Pp
 462 The
 463 .Nm
 464 driver does not yet support interrupts.
 465 Since interrupts cannot be handled by the driver itself, they must be
 466 converted into signals and delivered to the program that has registered
 467 for interrupts.
 468 A satisfactory mechanism for keeping the interrupt masked during the
 469 signal handling is still being worked out.
 470 .Pp
 471 DMA support for devices other than busmaster devices is not present yet.
 472 The details of how a program is to interact with the DMA controller still
 473 need to be fleshed out.