diff options
author | scottl <scottl@FreeBSD.org> | 2006-04-28 08:36:49 +0000 |
---|---|---|
committer | scottl <scottl@FreeBSD.org> | 2006-04-28 08:36:49 +0000 |
commit | 28ddd4c0ac561360b21529f2be2fd01df90aead2 (patch) | |
tree | 7ccce830bd7d6be8d108f22709030e7707aa9e75 /share | |
parent | accf0051b8a9e90bef40a29035fd1ca895088c28 (diff) | |
download | FreeBSD-src-28ddd4c0ac561360b21529f2be2fd01df90aead2.zip FreeBSD-src-28ddd4c0ac561360b21529f2be2fd01df90aead2.tar.gz |
Add a section about locking protocol for busdma.
Diffstat (limited to 'share')
-rw-r--r-- | share/man/man9/bus_dma.9 | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/share/man/man9/bus_dma.9 b/share/man/man9/bus_dma.9 index d46dda2..34f3667 100644 --- a/share/man/man9/bus_dma.9 +++ b/share/man/man9/bus_dma.9 @@ -792,6 +792,65 @@ code, as discussed above. All .Vt void routines will succeed if provided with valid arguments. +.Sh LOCKING +Two locking protocols are used by +.Nm . +The first is a private global lock that is used to synchronize access to the +bounce buffer pool on the architectures that make use of them. +This lock is strictly a leaf lock that is only used internally to +.Nm +and is not exposed to clients of the API. +.Pp +The second protocol involves protecting various resources stored in the tag. +Since almost all +.Nm +operations are done through requests from the driver that created the tag, +the most efficient way to protect the tag resources is through the lock that +the driver uses. +In cases where +.Nm +acts on its own without being called by the driver, the lock primitive +specified in the tag is acquired and released automatically. +An example of this is when the +.Fn bus_dmamap_load +callback function is called from a defered context instead of the driver +context. +This means that certain +.Nm +functions must always be called with same lock held that is specified in the +tag. These functions include: +.Pp +.Bl -inset -offset indent -compact +.It bus_dmamap_load +.It bus_dmamap_load_uio +.It bus_dmamap_load_mbuf +.It bus_dmamap_load_mbuf_sg +.It bus_dmamap_unload +.It bus_dmamap_sync +.El +.Pp +There is one exception to this rule. +It is common practice to call some of these functions during driver start-up +without any locks held. +So long as there is a guarantee of no possible concurrent use of the tag by +different threads during this operation, it is safe to not hold a lock for +these functions. +.Pp +Certain +.Nm +operations should not be called with the driver lock held, either because +they are already protected by an internal lock, or because they might sleep +due to memory or resource allocation. The following functions must not be +called with any non-sleepable locks held: +.Pp +.Bl -inset -offset indent -compact +.It bus_dma_tag_create +.It bus_dmamap_create +.It bus_dmamem_alloc +.El +.Pp +All other functions do not have a locking protocol and can thus be +called with or without and system or driver locks held. .Sh SEE ALSO .Xr devclass 9 , .Xr device 9 , |