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