]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man4/proto.4
disk(9): Fix a few mandoc related errors
[FreeBSD/FreeBSD.git] / 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.