2 .\" Copyright (c) 2014, 2015 Marcel Moolenaar
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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.
34 .Nd Generic prototyping and diagnostics driver
37 To compile this driver into the kernel,
38 place the following line in your
39 kernel configuration file:
40 .Bd -ragged -offset indent
44 Alternatively, to load the driver as a
45 module at boot time, place the following line in
47 .Bd -literal -offset indent
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]"
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
68 device driver is nothing but a conduit or gateway between user space
69 programs and the hardware device.
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
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
84 operations to be performed on them.
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
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
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
107 system call can be used for the
110 This ioctl request returns the extend of the resource covered by this
112 The extend is returned in the following structure:
114 struct proto_ioc_region {
115 unsigned long address;
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
125 Reads and writes to the memory address returned by
127 go directly to the hardware.
132 can be avoided, reducing the access overhead significantly.
133 Alignment and access width constraints put forth by the underlying device
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
140 is created for the purpose of doing DMA.
146 This device special file does not support
152 request has an argument that is both in and out and is defined as
155 struct proto_ioc_busdma {
156 unsigned int request;
162 unsigned long maxaddr;
164 unsigned long maxsegsz;
166 unsigned int datarate;
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;
185 unsigned long result;
190 field is used to specify which DMA operation is to be performed.
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:
197 .It PROTO_IOC_BUSDMA_TAG_CREATE
201 field is set on output with the key of the DMA tag.
202 The tag is created with the constraints given by the
205 These constraints correspond roughly to those that can be given to the
206 .Xr bus_dma_tag_create 9
208 .It PROTO_IOC_BUSDMA_TAG_DERIVE
209 Create a derived tag.
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
216 The derived tag combines the constraints of the parent tag with those
220 The combined constraints are written back to the
222 sub-structure on return.
223 .It PROTO_IOC_BUSDMA_TAG_DESTROY
224 Destroy a root or derived tag previously created.
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
238 The key of the memory descriptor for this memory is returned in the
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
250 The number of contigous physical memory segments and the address of the first
251 segment are returned in the
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
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 descriptor.
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.
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
289 The key of the memory descriptor is returned in the
292 .It PROTO_IOC_BUSDMA_MD_DESTROY
293 Destroy the previously created memory descriptor specified by the
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
301 The size and address in the process' virtual address space are specified
309 sub-structure contains the result of the operation.
310 The number of physical segments and the address of the first segment is
316 The number of bus space segments and the address of the first segment in
317 bus space is returned in the
322 .It PROTO_IOC_BUSDMA_MD_UNLOAD
323 Unload the memory descriptor specified by the
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
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
342 field holds the sync operation to be performed.
343 This is similar to the
344 .Xr bus_dmamap_sync 9
347 .Ss PCI configuration space
348 Access to PCI configuration space is possible through the
351 The device special file supports
356 Usage is the asme as for I/O port resources.
358 All device special files corresponding to a PCI device are located under
359 .Pa /dev/proto/pci<d>:<b>:<s>:<f>
361 .Pa pci<d>:<b>:<s>:<f>
362 representing the location of the PCI device in the PCI hierarchy.
363 A PCI location includes:
365 .Bl -tag -width XXXXXX -compact -offset indent
367 The PCI domain number
371 The PCI slot or device number
373 The PCI function number
376 Every PCI device has a device special file called
378 This device special file gives access to the PCI configuration space.
379 A device special file called
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
389 representing I/O port or memory mapped I/O space (resp.)
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
396 .Pa /dev/proto/isa:<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
403 The resource type can be either
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
412 This device special file provides the interfaces needed for doing DMA.
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.
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:
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
427 A legacy floppy controller will have the following device files:
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
441 .Xr bus_dma_tag_create 9 ,
442 .Xr bus_dmamap_sync 9 ,
443 .Xr bus_dmamem_alloc 9
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
453 driver is inherently insecure.
454 It is not advisable to use this driver on a production machine.
456 .Sh MISSING FUNCTIONALITY
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.
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
470 A satisfactory mechanism for keeping the interrupt masked during the
471 signal handling is still being worked out.
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.