diff options
Diffstat (limited to 'share/man/man4/proto.4')
| -rw-r--r-- | share/man/man4/proto.4 | 299 |
1 files changed, 297 insertions, 2 deletions
diff --git a/share/man/man4/proto.4 b/share/man/man4/proto.4 index f541836..9638d4f 100644 --- a/share/man/man4/proto.4 +++ b/share/man/man4/proto.4 @@ -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 following device files: .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 on a production machine. .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 |
