Big chunk of documention of xf86drm.c. Some oddities left to document, and still needs a review to catch typos.

2 files changed, 688 insertions, 17 deletions

diff --git a/src/miniglx/xf86drm.c b/src/miniglx/xf86drm.c
index a7c6d710744..39598bd94ce 100644
--- a/src/miniglx/xf86drm.c
+++ b/src/miniglx/xf86drm.c
@@ -49,7 +49,7 @@
 # include <stdarg.h>
 # include "drm.h"
 
-/** Not all systems have MAP_FAILED defined */
+/* Not all systems have MAP_FAILED defined */
 #ifndef MAP_FAILED
 #define MAP_FAILED ((void *)-1)
 #endif
@@ -74,7 +74,7 @@
 #endif
 
 #ifndef makedev
-				/** This definition needs to be changed on
+				/* This definition needs to be changed on
                                    some systems if dev_t is a structure.
                                    If there is a header file we can get it
                                    from, there would be best. */
@@ -82,6 +82,14 @@
 #endif
 
 
+/**
+ * \brief Output a message to stderr.
+ *
+ * \param format printf() like format string.
+ *
+ * \internal
+ * Wrapper arround vfprintf().
+ */
 static void
 drmMsg(const char *format, ...)
 {
@@ -96,7 +104,9 @@ drmMsg(const char *format, ...)
     }
 }
 
-
+/*
+ * Not used.
+ */
 static unsigned long drmGetKeyFromFd(int fd)
 {
     struct stat     st;
@@ -107,6 +117,19 @@ static unsigned long drmGetKeyFromFd(int fd)
 }
 
 
+/**
+ * \brief Open the DRM device, creating it if necessary.
+ *
+ * \param dev major and minor numbers of the device.
+ * \param minor minor number of the device.
+ * 
+ * \return a file descriptor on success, or a negative value on error.
+ *
+ * \internal
+ * Assembles the device name from \p minor and opens it, creating the device
+ * special file node with the major and minor numbers specified by \p dev and
+ * parent directory if necessary and was called by root.
+ */
 static int drmOpenDevice(long dev, int minor)
 {
     struct stat          st;
@@ -165,6 +188,19 @@ static int drmOpenDevice(long dev, int minor)
     return -errno;
 }
 
+
+/**
+ * \brief Open the DRM device
+ *
+ * \param minor device minor number.
+ * \param create allow to create the device if set.
+ *
+ * \return a file descriptor on success, or a negative value on error.
+ * 
+ * \internal
+ * Calls drmOpenDevice() if \p create is set, otherwise assembles the device
+ * name from \p minor and opens it.
+ */
 static int drmOpenMinor(int minor, int create)
 {
     int  fd;
@@ -177,10 +213,16 @@ static int drmOpenMinor(int minor, int create)
     return -errno;
 }
 
+
 /**
- * drmAvailable() looks for (DRM_MAJOR, 0) and returns 1 if it returns
- * information for DRM_IOCTL_VERSION.  For backward compatibility with
- * older Linux implementations, /proc/dri is also checked.
+ * \brief Determine whether the DRM kernel driver has been loaded.
+ * 
+ * \return 1 if the DRM driver is loaded, 0 otherwise.
+ *
+ * \internal 
+ * Determine the presence of the kernel driver by attempting to open the 0
+ * minor and get version information.  For backward compatibility with older
+ * Linux implementations, /proc/dri is also checked.
  */
 int drmAvailable(void)
 {
@@ -203,6 +245,20 @@ int drmAvailable(void)
     return retval;
 }
 
+
+/**
+ * \brief Open the device by bus ID.
+ *
+ * \param busid bus ID.
+ *
+ * \return a file descriptor on success, or a negative value on error.
+ *
+ * \internal
+ * Attempts to open every possible minor (up to DRM_MAX_MINOR) and compares the
+ * device bus ID with the one supplied.
+ *
+ * \sa drmOpenMinor() and drmGetBusid().
+ */
 static int drmOpenByBusid(const char *busid)
 {
     int        i;
@@ -227,6 +283,23 @@ static int drmOpenByBusid(const char *busid)
     return -1;
 }
 
+
+/**
+ * \brief Open the device by name.
+ *
+ * \param name driver name.
+ * 
+ * \return a file descriptor on success, or a negative value on error.
+ * 
+ * \internal
+ * Opens the first minor number that matches the driver name and isn't already
+ * in use.  If it's in use it then it will already have a bus ID assigned.
+ * 
+ * For Linux backward-compatibility /proc support also reads
+ * /proc/dri/.../name.
+ *
+ * \sa drmOpenMinor(), drmGetVersion() and drmGetBusid().
+ */
 static int drmOpenByName(const char *name)
 {
     int           i;
@@ -247,10 +320,6 @@ static int drmOpenByName(const char *name)
 #endif
     }
 
-    /*
-     * Open the first minor number that matches the driver name and isn't
-     * already in use.  If it's in use it will have a busid assigned already.
-     */
     for (i = 0; i < DRM_MAX_MINOR; i++) {
 	if ((fd = drmOpenMinor(i, 1)) >= 0) {
 	    if ((version = drmGetVersion(fd))) {
@@ -309,11 +378,21 @@ static int drmOpenByName(const char *name)
     return -1;
 }
 
+
 /**
- * drmOpen() looks up the specified name and busid, and opens the device
- * found.  The entry in /dev/dri is created if necessary (and if root).
+ * \brief Open the DRM device.
  *
- * \return a file descriptor, or a negative value on error.
+ * Looks up the specified name and bus ID, and opens the device found.  The
+ * entry in /dev/dri is created if necessary and if called by root.
+ *
+ * \param name driver name. Not referenced if bus ID is supplied.
+ * \param busid bus ID. Zero if not known.
+ * 
+ * \return a file descriptor on success, or a negative value on error.
+ * 
+ * \internal
+ * Calls drmOpenByBusid() if \p busid is specified or drmOpenByName()
+ * otherwise.
  */
 int drmOpen(const char *name, const char *busid)
 {
@@ -322,6 +401,16 @@ int drmOpen(const char *name, const char *busid)
     return drmOpenByName(name);
 }
 
+
+/**
+ * \brief Free the version information returned by drmGetVersion().
+ *
+ * \param v pointer to the version information.
+ *
+ * \internal
+ * Frees the memory pointed by \p %v as well as all the non-null strings
+ * pointed by it.
+ */
 void drmFreeVersion(drmVersionPtr v)
 {
     if (!v) return;
@@ -331,6 +420,18 @@ void drmFreeVersion(drmVersionPtr v)
     free(v);
 }
 
+
+/**
+ * \brief Free the non-public version information returned by the kernel.
+ *
+ * \param v pointer to the version information.
+ *
+ * \internal
+ * Frees the memory pointed by \p %v as well as all the non-null strings
+ * pointed by it.
+ * 
+ * \sa Used by drmGetVersion().
+ */
 static void drmFreeKernelVersion(drm_version_t *v)
 {
     if (!v) return;
@@ -340,6 +441,17 @@ static void drmFreeKernelVersion(drm_version_t *v)
     free(v);
 }
 
+
+/**
+ * \brief Copy version information.
+ * 
+ * \param d destination pointer.
+ * \param s source pointer.
+ * 
+ * \internal
+ * Used by drmGetVersion() to translate the information returned by the ioctl
+ * interface in a private structure into the public structure counterpart.
+ */
 static void drmCopyVersion(drmVersionPtr d, const drm_version_t *s)
 {
     d->version_major      = s->version_major;
@@ -353,10 +465,21 @@ static void drmCopyVersion(drmVersionPtr d, const drm_version_t *s)
     d->desc               = strdup(s->desc);
 }
 
+
 /**
- * Obtain the driver version information via an ioctl.
+ * \brief Query the driver version information.
  *
- * Similar information is available via /proc/dri.
+ * \param fd file descriptor.
+ * 
+ * \return pointer to a drmVersion structure which should be freed with
+ * drmFreeVersion().
+ * 
+ * \note Similar information is available via /proc/dri.
+ * 
+ * \internal
+ * Get the version information via sucessives DRM_IOCTL_VERSION ioctls, first
+ * with zeros to get the string lengths, and then the strings into the
+ * allocated space and null-terminating them.
  */
 drmVersionPtr drmGetVersion(int fd)
 {
@@ -404,8 +527,13 @@ drmVersionPtr drmGetVersion(int fd)
     return retval;
 }
 
+
 /**
- * Set version information for the DRM user space library.
+ * \brief Set version information for the DRM user space library.
+ * 
+ * \param fd file descriptor.
+ *
+ * \return version information.
  * 
  * This version number is driver indepedent.
  */
@@ -426,11 +554,29 @@ drmVersionPtr drmGetLibVersion(int fd)
     return (drmVersionPtr)version;
 }
 
+
+/**
+ * \brief Free the bus ID information.
+ *
+ * \param busid bus ID information string as given by drmGetBusid().
+ */
 void drmFreeBusid(const char *busid)
 {
     free((void *)busid);
 }
 
+
+/**
+ * \brief Get the bus ID of the device.
+ *
+ * \param fd file descriptor.
+ *
+ * \return bus ID string.
+ *
+ * \internal
+ * Get the bus ID via sucessive DRM_IOCTL_GET_UNIQUE ioctls to get the string
+ * length and data.
+ */
 char *drmGetBusid(int fd)
 {
     drm_unique_t u;
@@ -445,6 +591,18 @@ char *drmGetBusid(int fd)
     return u.unique;
 }
 
+
+/**
+ * \brief Set the bus ID of the device.
+ *
+ * \param fd file descriptor.
+ * \param busid bus ID string.
+ *
+ * \return zero on sucess, negative on failure.
+ *
+ * \internal
+ * Set the bus ID via the DRM_IOCTL_SET_UNIQUE ioctl.
+ */
 int drmSetBusid(int fd, const char *busid)
 {
     drm_unique_t u;
@@ -458,6 +616,57 @@ int drmSetBusid(int fd, const char *busid)
     return 0;
 }
 
+
+/**
+ * \brief Specifies a range of memory that is available for mapping by a
+ * non-root process.
+ *
+ * \param fd file descriptor.
+ * \param offset usually the physical address. The actual meaning depends of
+ * the \p type parameter. See below.
+ * \param size of the memory in bytes.
+ * \param type type of the memory to be mapped.
+ * \param flags combination of several flags to modify the function actions.
+ * \param handle will be set to a value that may be used as the offset
+ * parameter for mmap().
+ * 
+ * \return zero on success or a negative value on error.
+ *
+ * \par Mapping the frame buffer
+ * For the frame buffer
+ * - \p offset will be the physical address of the start of the frame buffer,
+ * - \p size will be the size of the frame buffer in bytes, and
+ * - \p type will be DRM_FRAME_BUFFER.
+ *
+ * \par
+ * The area mapped will be uncached. If MTRR support is available in the
+ * kernel, the frame buffer area will be set to write combining. 
+ *
+ * \par Mapping the MMIO register area
+ * For the MMIO register area,
+ * - \p offset will be the physical address of the start of the register area,
+ * - \p size will be the size of the register area bytes, and
+ * - \p type will be DRM_REGISTERS.
+ * \par
+ * The area mapped will be uncached. 
+ * 
+ * \par Mapping the SAREA
+ * For the SAREA,
+ * - \p offset will be ignored and should be set to zero,
+ * - \p size will be the desired size of the SAREA in bytes,
+ * - \p type will be DRM_SHM.
+ * 
+ * \par
+ * A shared memory area of the requested size will be created and locked in
+ * kernel memory. This area may be mapped into client-space by using the handle
+ * returned. 
+ * 
+ * \note May only be called by root.
+ *
+ * \internal
+ * Passes the arguments into a drm_map_t structure to the DRM_IOCTL_ADD_MAP
+ * ioctl.
+ */
 int drmAddMap(int fd,
 	      drmHandle offset,
 	      drmSize size,
@@ -477,6 +686,25 @@ int drmAddMap(int fd,
     return 0;
 }
 
+
+/**
+ * \brief Make buffers available for DMA transfers.
+ * 
+ * \param fd file descriptor.
+ * \param count number of buffers.
+ * \param size size of each buffer.
+ * \param flags buffer allocation flags.
+ * \param agp_offset offset in the AGP aperture 
+ *
+ * \return number of buffers allocated, negative on error.
+ *
+ * \internal
+ * Wrapper around DRM_IOCTL_ADD_BUFS.
+ *
+ * \sa drm_buf_desc_t.
+ * Passes the arguments into a drm_buf_desc_t structure to the
+ * DRM_IOCTL_ADD_BUFS ioctl.
+ */
 int drmAddBufs(int fd, int count, int size, drmBufDescFlags flags,
 	       int agp_offset)
 {
@@ -494,6 +722,20 @@ int drmAddBufs(int fd, int count, int size, drmBufDescFlags flags,
 }
 
 
+/**
+ * \brief Free buffers.
+ *
+ * \param fd file descriptor.
+ * \param count number of buffers to free.
+ * \param list list of buffers to be freed.
+ *
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \note This function is primarily used for debugging.
+ * 
+ * \internal
+ * Wrapper around DRM_IOCTL_FREE_BUFS ioctl.
+ */
 int drmFreeBufs(int fd, int count, int *list)
 {
     drm_buf_free_t request;
@@ -504,11 +746,35 @@ int drmFreeBufs(int fd, int count, int *list)
     return 0;
 }
 
+
+/**
+ * \brief Close the device.
+ *
+ * \param fd file descriptor.
+ *
+ * \internal
+ * Close the file descriptor.
+ */
 int drmClose(int fd)
 {
     return close(fd);
 }
 
+
+/**
+ * \brief Map a region of memory.
+ *
+ * \param fd file descriptor.
+ * \param handle handle returned by drmAddMap().
+ * \param size size in bytes. Must match the size used by drmAddMap().
+ * \param address will contain the user-space virtual address where the mapping
+ * begins.
+ *
+ * \return zero on success, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper for mmap().
+ */
 int drmMap(int fd,
 	   drmHandle handle,
 	   drmSize size,
@@ -528,12 +794,38 @@ int drmMap(int fd,
     return 0;
 }
 
+
+/**
+ * \brief Unmap mappings obtained with drmMap().
+ *
+ * \param address address as given by drmMap().
+ * \param size size in bytes. Must match the size used by drmMap().
+ * 
+ * \return zero on success, or a negative value on failure.
+ *
+ * \internal
+ * Wrapper for unmap().
+ */
 int drmUnmap(drmAddress address, drmSize size)
 {
     return munmap(address, size);
 }
 
 
+/**
+ * \brief Map all DMA buffers into client-virtual space.
+ *
+ * \param fd file descriptor.
+ *
+ * \return a pointer to a drmBufMap structure.
+ *
+ * \note The client may not use these buffers until obtaining buffer indices
+ * with drmDMA().
+ * 
+ * \internal
+ * Calls the DRM_IOCTL_MAP_BUFS ioctl and copy the returned information about
+ * the buffers into the client-visible data structures...
+ */ 
 drmBufMapPtr drmMapBufs(int fd)
 {
     drm_buf_map_t bufs;
@@ -553,7 +845,7 @@ drmBufMapPtr drmMapBufs(int fd)
 	    return NULL;
 	}
 				/* Now, copy it all back into the
-                                   client-visible data structure... */
+                                   client-visible data structures... */
 	retval = malloc(sizeof(*retval));
 	retval->count = bufs.count;
 	retval->list  = malloc(bufs.count * sizeof(*retval->list));
@@ -568,6 +860,15 @@ drmBufMapPtr drmMapBufs(int fd)
     return NULL;
 }
 
+
+/**
+ * \brief Unmap buffers allocated with drmMapBufs().
+ *
+ * \return zero on success, or negative value on failure.
+ *
+ * \internal
+ * Calls munmap() for every buffer stored in \p bufs.
+ */
 int drmUnmapBufs(drmBufMapPtr bufs)
 {
     int i;
@@ -578,8 +879,21 @@ int drmUnmapBufs(drmBufMapPtr bufs)
     return 0;
 }
 
+
 #define DRM_DMA_RETRY		16
 
+/**
+ * \brief Reserve DMA buffers.
+ *
+ * \param fd file descriptor.
+ * \param request 
+ * 
+ * \return zero on success, or a negative value on failure.
+ *
+ * \internal
+ * Assemble the arguments into a drm_dma_t structure and keeps issuing the
+ * DRM_IOCTL_DMA ioctl until success or until maximum number of retries.
+ */
 int drmDMA(int fd, drmDMAReqPtr request)
 {
     drm_dma_t dma;
@@ -608,6 +922,21 @@ int drmDMA(int fd, drmDMAReqPtr request)
     }
 }
 
+
+/**
+ * \brief Obtain heavyweight hardware lock.
+ *
+ * \param fd file descriptor.
+ * \param context context.
+ * \param flags flags that determine the sate of the hardware when the function
+ * returns.
+ * 
+ * \return always zero.
+ * 
+ * \internal
+ * Translate the flags and do the DRM_IOCTL_LOCK ioctl until the lock is
+ * sucessfully acquired.
+ */
 int drmGetLock(int fd, drmContext context, drmLockFlags flags)
 {
     drm_lock_t lock;
@@ -626,6 +955,18 @@ int drmGetLock(int fd, drmContext context, drmLockFlags flags)
     return 0;
 }
 
+
+/**
+ * \brief Release the hardware lock.
+ *
+ * \param fd file descriptor.
+ * \param context context.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_UNLOCK ioctl.
+ */
 int drmUnlock(int fd, drmContext context)
 {
     drm_lock_t lock;
@@ -635,6 +976,24 @@ int drmUnlock(int fd, drmContext context)
     return ioctl(fd, DRM_IOCTL_UNLOCK, &lock);
 }
 
+
+/**
+ * \brief Create context.
+ *
+ * Used by the X server during GLXContext initialization. This causes
+ * per-context kernel-level resources to be allocated.
+ *
+ * \param fd file descriptor.
+ * \param handle is set on sucess. To be used by the client when requesting DMA
+ * dispatch with drmDMA().
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \note May only be called by root.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_ADD_CTX ioctl.
+ */
 int drmCreateContext(int fd, drmContextPtr handle)
 {
     drm_ctx_t ctx;
@@ -646,6 +1005,22 @@ int drmCreateContext(int fd, drmContextPtr handle)
 }
 
 
+/**
+ * \brief Destroy context.
+ *
+ * Free any kernel-level resources allocated with drmCreateContext() associated
+ * with the context.
+ * 
+ * \param fd file descriptor.
+ * \param handle handle given by drmCreateContext().
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \note May only be called by root.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_RM_CTX ioctl.
+ */
 int drmDestroyContext(int fd, drmContext handle)
 {
     drm_ctx_t ctx;
@@ -654,18 +1029,54 @@ int drmDestroyContext(int fd, drmContext handle)
     return 0;
 }
 
+
+/**
+ * \brief Acquire the AGP device.
+ *
+ * Must be called before any of the other AGP related calls.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_ACQUIRE ioctl.
+ */
 int drmAgpAcquire(int fd)
 {
     if (ioctl(fd, DRM_IOCTL_AGP_ACQUIRE, NULL)) return -errno;
     return 0;
 }
 
+
+/**
+ * \brief Release the AGP device.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_RELEASE ioctl.
+ */
 int drmAgpRelease(int fd)
 {
     if (ioctl(fd, DRM_IOCTL_AGP_RELEASE, NULL)) return -errno;
     return 0;
 }
 
+
+/**
+ * \brief Set the AGP mode.
+ *
+ * \param fd file descriptor.
+ * \param mode AGP mode.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_ENABLE ioctl.
+ */
 int drmAgpEnable(int fd, unsigned long mode)
 {
     drm_agp_mode_t m;
@@ -675,6 +1086,24 @@ int drmAgpEnable(int fd, unsigned long mode)
     return 0;
 }
 
+
+/**
+ * \brief Allocate a chunk of AGP memory.
+ *
+ * \param fd file descriptor.
+ * \param size requested memory size in bytes. Will be rounded to page boundary.
+ * \param type type of memory to allocate.
+ * \param address if not zero, will be set to the physical address of the
+ * allocated memory.
+ * \param handle on sucess will be set to a handle of the allocated memory.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_ALLOC ioctl.
+ *
+ * \sa drm_agp_buffer_t;
+ */
 int drmAgpAlloc(int fd, unsigned long size, unsigned long type,
 		unsigned long *address, unsigned long *handle)
 {
@@ -689,6 +1118,20 @@ int drmAgpAlloc(int fd, unsigned long size, unsigned long type,
     return 0;
 }
 
+
+/**
+ * \brief Free a chunk of AGP memory.
+ *
+ * \param fd file descriptor.
+ * \param handle handle to the allocated memory, as given by drmAgpAllocate().
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_FREE ioctl.
+ *
+ * \sa drm_agp_buffer_t.
+ */
 int drmAgpFree(int fd, unsigned long handle)
 {
     drm_agp_buffer_t b;
@@ -699,6 +1142,21 @@ int drmAgpFree(int fd, unsigned long handle)
     return 0;
 }
 
+
+/**
+ * \brief Bind a chunk of AGP memory.
+ *
+ * \param fd file descriptor.
+ * \param handle handle to the allocated memory, as given by drmAgpAllocate().
+ * \param offset offset in bytes. It will round to page boundary.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_BIND ioctl.
+ * 
+ * \sa drm_agp_binding_t.
+ */
 int drmAgpBind(int fd, unsigned long handle, unsigned long offset)
 {
     drm_agp_binding_t b;
@@ -709,6 +1167,20 @@ int drmAgpBind(int fd, unsigned long handle, unsigned long offset)
     return 0;
 }
 
+
+/**
+ * \brief Unbind a chunk of AGP memory.
+ *
+ * \param fd file descriptor.
+ * \param handle handle to the allocated memory, as given by drmAgpAllocate().
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_UNBIND ioctl.
+ *
+ * \sa drm_agp_binding_t.
+ */
 int drmAgpUnbind(int fd, unsigned long handle)
 {
     drm_agp_binding_t b;
@@ -719,6 +1191,17 @@ int drmAgpUnbind(int fd, unsigned long handle)
     return 0;
 }
 
+
+/**
+ * \brief Get AGP driver major version number.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return major version number on success, or a negative value on failure..
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_INFO ioctl.
+ */
 int drmAgpVersionMajor(int fd)
 {
     drm_agp_info_t i;
@@ -727,6 +1210,17 @@ int drmAgpVersionMajor(int fd)
     return i.agp_version_major;
 }
 
+
+/**
+ * \brief Get AGP driver minor version number.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return minor version number on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_INFO ioctl.
+ */
 int drmAgpVersionMinor(int fd)
 {
     drm_agp_info_t i;
@@ -735,6 +1229,17 @@ int drmAgpVersionMinor(int fd)
     return i.agp_version_minor;
 }
 
+
+/**
+ * \brief Get AGP mode.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return mode on sucess, or zero on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_INFO ioctl.
+ */
 unsigned long drmAgpGetMode(int fd)
 {
     drm_agp_info_t i;
@@ -743,6 +1248,17 @@ unsigned long drmAgpGetMode(int fd)
     return i.mode;
 }
 
+
+/**
+ * \brief Get AGP aperture base.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return aperture base on sucess, zero on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_INFO ioctl.
+ */
 unsigned long drmAgpBase(int fd)
 {
     drm_agp_info_t i;
@@ -751,6 +1267,17 @@ unsigned long drmAgpBase(int fd)
     return i.aperture_base;
 }
 
+
+/**
+ * \brief Get AGP aperture size.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return aperture size on sucess, zero on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_INFO ioctl.
+ */
 unsigned long drmAgpSize(int fd)
 {
     drm_agp_info_t i;
@@ -759,6 +1286,17 @@ unsigned long drmAgpSize(int fd)
     return i.aperture_size;
 }
 
+
+/**
+ * \brief Get used AGP memory.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return memory used on sucess, or zero on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_INFO ioctl.
+ */
 unsigned long drmAgpMemoryUsed(int fd)
 {
     drm_agp_info_t i;
@@ -767,6 +1305,17 @@ unsigned long drmAgpMemoryUsed(int fd)
     return i.memory_used;
 }
 
+
+/**
+ * \brief Get available AGP memory.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return memory available on sucess, or zero on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_INFO ioctl.
+ */
 unsigned long drmAgpMemoryAvail(int fd)
 {
     drm_agp_info_t i;
@@ -775,6 +1324,17 @@ unsigned long drmAgpMemoryAvail(int fd)
     return i.memory_allowed;
 }
 
+
+/**
+ * \brief Get hardware vendor ID.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return vendor ID on sucess, or zero on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_INFO ioctl.
+ */
 unsigned int drmAgpVendorId(int fd)
 {
     drm_agp_info_t i;
@@ -783,6 +1343,17 @@ unsigned int drmAgpVendorId(int fd)
     return i.id_vendor;
 }
 
+
+/**
+ * \brief Get hardware device ID.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return zero on sucess, or zero on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_AGP_INFO ioctl.
+ */
 unsigned int drmAgpDeviceId(int fd)
 {
     drm_agp_info_t i;
@@ -792,6 +1363,17 @@ unsigned int drmAgpDeviceId(int fd)
 }
 
 
+/**
+ * \brief Wait for VBLANK.
+ *
+ * \param fd file descriptor.
+ * \param vbl pointer to a drmVBlank structure.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_WAIT_VBLANK ioctl.
+ */
 int drmWaitVBlank(int fd, drmVBlankPtr vbl)
 {
     int ret;
@@ -804,6 +1386,17 @@ int drmWaitVBlank(int fd, drmVBlankPtr vbl)
 }
 
 
+/**
+ * \brief Install IRQ handler.
+ *
+ * \param fd file descriptor.
+ * \param irq IRQ number.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_CONTROL ioctl.
+ */
 int drmCtlInstHandler(int fd, int irq)
 {
     drm_control_t ctl;
@@ -814,6 +1407,17 @@ int drmCtlInstHandler(int fd, int irq)
     return 0;
 }
 
+
+/**
+ * \brief Uninstall IRQ handler.
+ *
+ * \param fd file descriptor.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_CONTROL ioctl.
+ */
 int drmCtlUninstHandler(int fd)
 {
     drm_control_t ctl;
@@ -825,6 +1429,19 @@ int drmCtlUninstHandler(int fd)
 }
 
 
+/**
+ * \brief Get IRQ from bus ID.
+ *
+ * \param fd file descriptor.
+ * \param busnum bus number.
+ * \param devnum device number.
+ * \param funcnum function number.
+ * 
+ * \return IRQ number on sucess, or a negative value on failure.
+ * 
+ * \internal
+ * Wrapper around the DRM_IOCTL_IRQ_BUSID ioctl.
+ */
 int drmGetInterruptFromBusID(int fd, int busnum, int devnum, int funcnum)
 {
     drm_irq_busid_t p;
@@ -837,6 +1454,16 @@ int drmGetInterruptFromBusID(int fd, int busnum, int devnum, int funcnum)
 }
 
 
+/**
+ * \brief Send a command.
+ *
+ * \param fd file descriptor.
+ * \param drmCommandIndex command index 
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ */
 int drmCommandNone(int fd, unsigned long drmCommandIndex)
 {
     void *data = NULL; /* dummy */
@@ -850,6 +1477,19 @@ int drmCommandNone(int fd, unsigned long drmCommandIndex)
     return 0;
 }
 
+
+/**
+ * \brief Send a read command.
+ *
+ * \param fd file descriptor.
+ * \param drmCommandIndex command index 
+ * \param data destination pointer of the data to be read.
+ * \param size size of the data to be read.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ */
 int drmCommandRead(int fd, unsigned long drmCommandIndex,
                    void *data, unsigned long size )
 {
@@ -864,6 +1504,19 @@ int drmCommandRead(int fd, unsigned long drmCommandIndex,
     return 0;
 }
 
+
+/**
+ * \brief Send a write command.
+ *
+ * \param fd file descriptor.
+ * \param drmCommandIndex command index 
+ * \param data source pointer of the data to be written.
+ * \param size size of the data to be written.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ */
 int drmCommandWrite(int fd, unsigned long drmCommandIndex,
                    void *data, unsigned long size )
 {
@@ -878,6 +1531,19 @@ int drmCommandWrite(int fd, unsigned long drmCommandIndex,
     return 0;
 }
 
+
+/**
+ * \brief Send a read-write command.
+ *
+ * \param fd file descriptor.
+ * \param drmCommandIndex command index 
+ * \param data source pointer of the data to be read and written.
+ * \param size size of the data to be read and written.
+ * 
+ * \return zero on sucess, or a negative value on failure.
+ * 
+ * \internal
+ */
 int drmCommandWriteRead(int fd, unsigned long drmCommandIndex,
                    void *data, unsigned long size )
 {
diff --git a/src/miniglx/xf86drm.h b/src/miniglx/xf86drm.h
index 59595a211ae..967888ae47a 100644
--- a/src/miniglx/xf86drm.h
+++ b/src/miniglx/xf86drm.h
@@ -60,6 +60,11 @@ typedef unsigned int  drmContext,  *drmContextPtr;  /**< GLXContext handle */
 typedef unsigned int  drmDrawable, *drmDrawablePtr; /**< Unused */
 typedef unsigned int  drmMagic,    *drmMagicPtr;    /**< Magic for auth */
 
+/**
+ * \brief Driver version information.
+ *
+ * \sa drmGetVersion() and drmSetVersion().
+ */
 typedef struct _drmVersion {
     int     version_major;        /**< Major version */
     int     version_minor;        /**< Minor version */