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
_______________________________________________
svn-src-head@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-src-head
To unsubscribe, send any mail to "svn-src-head-unsubscr...@freebsd.org"
