From d2443b2186712dd7c977b47e06444396e1e493ff Mon Sep 17 00:00:00 2001 From: Jose Fonseca Date: Tue, 27 May 2003 00:37:33 +0000 Subject: Merged DRM documentation. --- linux-core/drm_lock.c | 73 +++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 53 insertions(+), 20 deletions(-) (limited to 'linux-core/drm_lock.c') diff --git a/linux-core/drm_lock.c b/linux-core/drm_lock.c index cc9571ed..29db1079 100644 --- a/linux-core/drm_lock.c +++ b/linux-core/drm_lock.c @@ -1,4 +1,12 @@ -/* lock.c -- IOCTLs for locking -*- linux-c -*- +/** + * \file drm_lock.h + * IOCTLs for locking + * + * \author Rickard E. (Rik) Faith + * \author Gareth Hughes + */ + +/* * Created: Tue Feb 2 08:37:54 1999 by faith@valinux.com * * Copyright 1999 Precision Insight, Inc., Cedar Park, Texas. @@ -23,15 +31,12 @@ * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR * OTHER DEALINGS IN THE SOFTWARE. - * - * Authors: - * Rickard E. (Rik) Faith - * Gareth Hughes */ #define __NO_VERSION__ #include "drmP.h" +/** No-op ioctl. */ int DRM(noop)(struct inode *inode, struct file *filp, unsigned int cmd, unsigned long arg) { @@ -39,7 +44,15 @@ int DRM(noop)(struct inode *inode, struct file *filp, unsigned int cmd, return 0; } - +/** + * Take the heavyweight lock. + * + * \param lock lock pointer. + * \param context locking context. + * \return one if the lock is held, or zero otherwise. + * + * Attempt to mark the lock as held by the given context, via the \p cmpxchg instruction. + */ int DRM(lock_take)(__volatile__ unsigned int *lock, unsigned int context) { unsigned int old, new, prev; @@ -66,8 +79,18 @@ int DRM(lock_take)(__volatile__ unsigned int *lock, unsigned int context) return 0; } -/* This takes a lock forcibly and hands it to context. Should ONLY be used - inside *_unlock to give lock to kernel before calling *_dma_schedule. */ +/** + * This takes a lock forcibly and hands it to context. Should ONLY be used + * inside *_unlock to give lock to kernel before calling *_dma_schedule. + * + * \param dev DRM device. + * \param lock lock pointer. + * \param context locking context. + * \return always one. + * + * Resets the lock file pointer. + * Marks the lock as held by the given context, via the \p cmpxchg instruction. + */ int DRM(lock_transfer)(drm_device_t *dev, __volatile__ unsigned int *lock, unsigned int context) { @@ -82,6 +105,17 @@ int DRM(lock_transfer)(drm_device_t *dev, return 1; } +/** + * Free lock. + * + * \param dev DRM device. + * \param lock lock. + * \param context context. + * + * Resets the lock file pointer. + * Marks the lock as not held, via the \p cmpxchg instruction. Wakes any task + * waiting on the lock queue. + */ int DRM(lock_free)(drm_device_t *dev, __volatile__ unsigned int *lock, unsigned int context) { @@ -103,18 +137,17 @@ int DRM(lock_free)(drm_device_t *dev, return 0; } -/* If we get here, it means that the process has called DRM_IOCTL_LOCK - without calling DRM_IOCTL_UNLOCK. - - If the lock is not held, then let the signal proceed as usual. - - If the lock is held, then set the contended flag and keep the signal - blocked. - - - Return 1 if the signal should be delivered normally. - Return 0 if the signal should be blocked. */ - +/** + * If we get here, it means that the process has called DRM_IOCTL_LOCK + * without calling DRM_IOCTL_UNLOCK. + * + * If the lock is not held, then let the signal proceed as usual. If the lock + * is held, then set the contended flag and keep the signal blocked. + * + * \param priv pointer to a drm_sigdata structure. + * \return one if the signal should be delivered normally, or zero if the + * signal should be blocked. + */ int DRM(notifier)(void *priv) { drm_sigdata_t *s = (drm_sigdata_t *)priv; -- cgit v1.2.3