svn commit: r286439 - head/share/man/man4
Marcel Moolenaar
marcel at FreeBSD.org
Sat Aug 8 04:59:28 UTC 2015
Author: marcel
Date: Sat Aug 8 04:59:27 2015
New Revision: 286439
URL: https://svnweb.freebsd.org/changeset/base/286439
Log:
Document the application interface.
Modified:
head/share/man/man4/proto.4
Modified: head/share/man/man4/proto.4
==============================================================================
--- head/share/man/man4/proto.4 Sat Aug 8 01:45:53 2015 (r286438)
+++ head/share/man/man4/proto.4 Sat Aug 8 04:59:27 2015 (r286439)
@@ -25,7 +25,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd July 19, 2015
+.Dd August 7, 2015
.Dt PROTO 4
.Os
.\"
@@ -74,7 +74,285 @@ logic in user space.
Especially hardware diagnostics requires a somewhat user-friendly interface
and adequate reporting.
Neither is done easily as kernel code.
-.\"
+.Ss I/O port resources
+Device special files created for I/O port resources allow
+.Xr lseek 2 ,
+.Xr read 2 ,
+.Xr write 2
+and
+.Xr ioctl 2
+operations to be performed on them.
+The
+.Xr read 2
+and
+.Xr write 2
+system calls are used to perform input and output (resp.) on the port.
+The amount of data that can be read or written at any single time is either
+1, 2 or 4 bytes.
+While the
+.Nm
+driver does not prevent reading or writing 8 bytes at a time for some
+architectures, it should not be assumed that such actually produces
+correct results.
+The
+.Xr lseek 2
+system call is used to select the port number, relative to the I/O port
+region being represented by the device special file.
+If, for example, the device special file corresponds to an I/O port region
+from 0x3f8 to 0x3ff inclusive, then an offset of 4 given to lseek with a
+whence value of SEEK_SET will target port 0x3fc on the next read or write
+operation.
+The
+.Xr ioctl 2
+system call can be used for the
+.Dv PROTO_IOC_REGION
+request.
+This ioctl request returns the extend of the resource covered by this
+device special file. The extend is returned in the following structure:
+.Bd -literal
+struct proto_ioc_region {
+ unsigned long address;
+ unsigned long size;
+};
+.Ed
+.Ss Memory mapped I/O resources
+The device special files created for memory mapped I/O resources behave
+in the same way as those created for I/O port resources.
+Additionally, device special files for memory mapped I/O resources allow
+the memory to be mapped into the process' address space using
+.Xr mmap 2 .
+Reads and writes to the memory address returned by
+.Xr mmap 2
+go directly to the hardware.
+As such the use of
+.Xr read 2
+and
+.Xr write 2
+can be avoided, reducing the access overhead significantly.
+Alignment and access width constraints put forth by the underlying device
+apply.
+Also, make sure the compiler does not optimize memory accesses away or has
+them coalesced into bigger accesses.
+.Ss DMA pseudo resource
+A device special file named
+.Pa busdma
+is created for the purpose of doing DMA.
+It only supports
+.Xr ioctl 2
+and only for the
+.Dv PROTO_IOC_BUSDMA
+request.
+This device special file does not support
+.Xr read 2
+nor
+.Xr write 2 .
+The
+.Dv PROTO_IOC_BUSDMA
+request has an argument that is both in and out and is defined as
+follows:
+.Bd -literal
+struct proto_ioc_busdma {
+ unsigned int request;
+ unsigned long key;
+ union {
+ struct {
+ unsigned long align;
+ unsigned long bndry;
+ unsigned long maxaddr;
+ unsigned long maxsz;
+ unsigned long maxsegsz;
+ unsigned int nsegs;
+ unsigned int datarate;
+ unsigned int flags;
+ } tag;
+ struct {
+ unsigned long tag;
+ unsigned int flags;
+ unsigned long virt_addr;
+ unsigned long virt_size;
+ unsigned int phys_nsegs;
+ unsigned long phys_addr;
+ unsigned long bus_addr;
+ unsigned int bus_nsegs;
+ } md;
+ struct {
+ unsigned int op;
+ unsigned long base;
+ unsigned long size;
+ } sync;
+ } u;
+ unsigned long result;
+};
+.Ed
+The
+.Va request
+field is used to specify which DMA operation is to be performed.
+The
+.Va key
+field is used to specify which object the operation applies to.
+An object is either a tag or a memory descriptor (md).
+The following DMA operations are defined:
+.Bl -tag -width XXXX
+.It PROTO_IOC_BUSDMA_TAG_CREATE
+Create a root tag.
+The
+.Va result
+field is set on output with the key of the DMA tag.
+The tag is created with the constraints given by the
+.Va tag
+sub-structure. These constraints correspond roughly to those that can be
+given to the
+.Xr bus_dma_tag_create 9
+function.
+.It PROTO_IOC_BUSDMA_TAG_DERIVE
+Create a derived tag.
+The
+.Va key
+field is used to identify the parent tag from which to derive the new tag.
+The key of the derived tag is returned in the
+.Va result
+field.
+The derived tag combines the constraints of the parent tag with those
+given by the
+.Va tag
+sub-structure.
+The combined constraints are written back to the
+.Va tag
+sub-structure on return.
+.It PROTO_IOC_BUSDMA_TAG_DESTROY
+Destroy a root or derived tag previously created.
+The
+.Va key
+field specifies the tag to destroy.
+A tag can only be destroyed when not referenced anymore.
+This means that derived tags that have this tag as a parent and memory
+descriptors created from this tag must be destroyed first.
+.It PROTO_IOC_BUSDMA_MEM_ALLOC
+Allocate memory that satisfies the constraints put forth by the tag
+given in the
+.Va tag
+field of the
+.Va md
+sub-structure.
+The key of the memory descriptor for this memory is returned in the
+.Va result
+field.
+The
+.Va md
+sub-structure is filled on return with details of the allocation.
+The kernel virtual address and the size of the allocated memory are returned
+in the
+.Va virt_addr
+and
+.Va virt_size
+fields.
+The number of contigous physical memory segments and the address of the first
+segment are returned in the
+.Va phys_nsegs
+and
+.Va phys_addr
+fields.
+Allocated memory is automatically loaded and thus mapped into bus space.
+The number of bus segments and the address of the first segment are returned
+in the
+.Va bus_nsegs
+and
+.Va bus_addr
+fields.
+The behaviour of this operation banks heavily on how
+.Xr bus_dmamem_alloc 9
+is implemented, which means that memory is currently always allocated as a
+single contigous region of physical memory.
+In practice this also tends to give a single contigous region in bus space.
+This may change over time.
+.It PROTO_IOC_BUSDMA_MEM_FREE
+Free previously allocated memory and destroy the memory desciptor.
+The
+.Nm
+driver is not in a position to track whether the memory has been mapped in
+the process' address space, so the application is responsible for unmapping
+the memory before it is freed.
+The
+.Nm
+driver also cannot protect against the hardware writing to or reading from
+the memory, even after it has been freed.
+When the memory is reused for other purposes it can be corrupted or cause
+the hardware to behave in unpredictable ways when DMA has not stopped
+completely before freeing.
+.It PROTO_IOC_BUSDMA_MD_CREATE
+Create an empty memory descriptor with the tag specified in the
+.Va tag
+field of the
+.Va md
+sub-structure.
+The key of the memory descriptor is returned in the
+.Va result
+field.
+.It PROTO_IOC_BUSDMA_MD_DESTROY
+Destroy the previously created memory descriptor specified by the
+.Va key
+field.
+When the memory descriptor is still loaded, it is unloaded first.
+.It PROTO_IOC_BUSDMA_MD_LOAD
+Load a contigous region of memory in the memory descriptor specified by the
+.Va key
+field.
+The size and address in the process' virtual address space are specified
+by the
+.Va virt_size
+and
+.Va virt_addr
+fields.
+On return, the
+.Va md
+sub-structure contains the result of the operation.
+The number of physical segments and the address of the first segment is
+returned in the
+.Va phys_nsegs
+and
+.Va phys_addr
+fields.
+The number of bus space segments and the address of the first segment in
+bus space is returned in the
+.Va bus_nsegs
+and
+.Va bus_addr
+fields.
+.It PROTO_IOC_BUSDMA_MD_UNLOAD
+Unload the memory descriptor specified by the
+.Va key
+field.
+.It PROTO_IOC_BUSDMA_SYNC
+Guarantee that all hardware components have a coherent view of the memory
+tracked by the memory descriptor, specified by the
+.Va key
+field.
+A sub-section of the memory can be targeted by specifying the relative
+offset and size of the memory to make coherent.
+The offset and size are given by the
+.Va base
+and
+.Va size
+fields of the
+.Va sync
+sub-structure.
+The
+.Va op
+field holds the sync operation to be performed.
+This is similar to the
+.Xr bus_dmamap_sync 9
+function.
+.El
+.Ss PCI configuration space
+Access to PCI configuration space is possible through the
+.Pa pcicfg
+device special file.
+The device special file supports
+.Xr lseek 2 ,
+.Xr read 2
+and
+.Xr write 2 .
+Usage is the asme as for I/O port resources.
.Sh FILES
All device special files corresponding to a PCI device are located under
.Pa /dev/proto/pci<d>:<b>:<s>:<f>
@@ -152,6 +430,16 @@ A legacy floppy controller will have the
.It Pa /dev/proto/isa:0x3f0/busdma
.El
.\"
+.Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr lseek 2 ,
+.Xr mmap 2 ,
+.Xr read 2 ,
+.Xr write 2 ,
+.Xr bus_dma_tag_create 9 ,
+.Xr bus_dmamap_sync 9 ,
+.Xr bus_dmamem_alloc 9
+.\"
.Sh AUTHORS
The
.Nm
@@ -166,6 +454,13 @@ It is not advisable to use this driver o
.Sh MISSING FUNCTIONALITY
The
.Nm
+driver does not fully support memory descriptors that need multiple
+physical memory segments or multiple bus space segments.
+At the very least, an operation is needed on the DMA pseudo resource
+for the application to obtain all segments.
+.Pp
+The
+.Nm
driver does not yet support interrupts.
Since interrupts cannot be handled by the driver itself, they must be
converted into signals and delivered to the program that has registered
More information about the svn-src-head
mailing list