From c35fb58c359be38bbefdd4666d855fd9c17e666d Mon Sep 17 00:00:00 2001 From: Jose Fonseca Date: Sun, 23 Feb 2003 15:21:36 +0000 Subject: [PATCH] A few documention fixes and additions. --- src/mesa/drivers/common/mm.c | 55 +++---- src/mesa/drivers/common/mm.h | 14 +- src/mesa/drivers/dri/common/mm.c | 55 +++---- src/mesa/drivers/dri/common/mm.h | 14 +- src/mesa/drivers/dri/radeon/radeon_context.c | 34 ++-- src/mesa/drivers/dri/radeon/radeon_context.h | 147 +++++++++++------- src/mesa/drivers/dri/radeon/radeon_ioctl.c | 62 ++++++-- src/mesa/drivers/dri/radeon/server/radeon.h | 2 +- .../drivers/dri/radeon/server/radeon_common.h | 36 +++-- .../drivers/dri/radeon/server/radeon_dri.c | 34 +++- .../drivers/dri/radeon/server/radeon_sarea.h | 4 +- 11 files changed, 281 insertions(+), 176 deletions(-) diff --git a/src/mesa/drivers/common/mm.c b/src/mesa/drivers/common/mm.c index a2b8e4fc868..55994dd9d73 100644 --- a/src/mesa/drivers/common/mm.c +++ b/src/mesa/drivers/common/mm.c @@ -1,6 +1,6 @@ /** * \file mm.c - * \brief Memory management. + * \brief Memory block management. */ /* @@ -37,9 +37,9 @@ */ /** - * \brief Dump memmory information about the heap. + * \brief Dump memory information about the heap. * - * \param heap memmory heap. + * \param heap memory heap. * * \note For debugging purposes. * @@ -67,7 +67,7 @@ void mmDumpMemInfo( memHeap_t *heap ) /** - * \brief Memmory heap initialization. + * \brief Memory heap initialization. * * \param offset offset in bytes. * \param size total size in bytes @@ -98,20 +98,20 @@ memHeap_t *mmInit(int ofs, /** - * \brief Slice a free memmory block. + * \brief Slice a free memory block. * - * \param p memmory block. - * \param startofs start offset to slice. - * \param size of the slice. - * \param reserved flag. - * \param alignment block alignment. + * \param p memory block. + * \param startofs slice start offset. + * \param size slice size. + * \param reserved reserved flag. + * \param alignment slice alignment. * * \return pointer to the slice block on success, or NULL on failure. * * \internal - * Creates a new block to the left with the remaining memory before the slice - * start (if any), a block to the right with the remaing memmory after the - * slice (if any), and the reduced memmory block itself as the slice. + * Creates a new block to the left with the memory before the slice start (if + * any), a block to the right with the memory after the slice (if any), and + * returns the reduced memory block itself as the slice. */ static TMemBlock* SliceBlock(TMemBlock *p, int startofs, int size, @@ -155,23 +155,24 @@ static TMemBlock* SliceBlock(TMemBlock *p, /** - * \brief Allocate a memmory block. + * \brief Allocate a memory block. * - * Allocate \p size bytes with \p 2^align2 bytes alignment, - * restrict the search to free memory after \p startSearch. - * Depth and back buffers should be in different 4MB banks - * to get better page hits if possible. + * Allocate \p size bytes with a \p 2^align2 bytes alignment, restricting the + * search to free memory after \p startSearch. Depth and back buffers should + * be in different 4MB banks to get better page hits if possible. * - * \param heap memmory heap. + * \param heap memory heap. * \param size size to allocate in bytes. - * \param align2 base 2 log of the alignment in bytes. - * \param startSearch linear offset from start of the heap to begin the search. + * \param align2 base 2 log of the block alignment in bytes. + * \param startSearch linear offset from start of the heap to begin the + * search. * * \return pointer to the allocated block on success, or NULL on failure. * * \internal * Walks through the free blocks on the heap and if it finds one above - * startSearch and large enough slices it via SliceBlock() and returns the result. + * \p startSearch and large enough slices it via SliceBlock() and returns the + * result. */ PMemBlock mmAllocMem( memHeap_t *heap, int size, int align2, int startSearch) { @@ -204,9 +205,9 @@ PMemBlock mmAllocMem( memHeap_t *heap, int size, int align2, int startSearch) /** - * \brief Join two successive free memmory blocks. + * \brief Join two successive free memory blocks. * - * \param p pointer to first memmory block. + * \param p pointer to first memory block. * * \return 1 on success, or 0 on failure. * @@ -227,7 +228,7 @@ static __inline__ int Join2Blocks(TMemBlock *p) /** - * \brief Free a memmory block. + * \brief Free a memory block. * * \param pointer to a block. * @@ -271,9 +272,9 @@ int mmFreeMem(PMemBlock b) /** - * \brief Destroy the memmory heap. + * \brief Destroy the memory heap. * - * \param heap memmory heap. + * \param heap memory heap. * * \internal * Frees each block in the heap. diff --git a/src/mesa/drivers/common/mm.h b/src/mesa/drivers/common/mm.h index 8d558d55b63..fa980ad39b9 100644 --- a/src/mesa/drivers/common/mm.h +++ b/src/mesa/drivers/common/mm.h @@ -1,6 +1,6 @@ /** * \file mm.h - * \brief Memory management. + * \brief Memory block management. */ /* @@ -30,7 +30,7 @@ #define MM_INC /** - * \brief Memmory block/heap. + * \brief Memory block/heap. */ struct mem_block_t { struct mem_block_t *next; /**< \brief pointer to next block in the heap */ @@ -43,30 +43,30 @@ struct mem_block_t { }; /** - * \brief Memmory block. + * \brief Memory block. */ typedef struct mem_block_t TMemBlock; /** - * \brief Memmory block pointer. + * \brief Memory block pointer. */ typedef struct mem_block_t *PMemBlock; /** - * \brief Memmory heap. + * \brief Memory heap. * * \note A heap is just the first block in a chain */ typedef struct mem_block_t memHeap_t; /** - * \brief Get Memmory block size. + * \brief Get Memory block size. */ static __inline__ int mmBlockSize(PMemBlock b) { return b->size; } /** - * \brief Get Memmory block offset. + * \brief Get Memory block offset. */ static __inline__ int mmOffset(PMemBlock b) { return b->ofs; } diff --git a/src/mesa/drivers/dri/common/mm.c b/src/mesa/drivers/dri/common/mm.c index a2b8e4fc868..55994dd9d73 100644 --- a/src/mesa/drivers/dri/common/mm.c +++ b/src/mesa/drivers/dri/common/mm.c @@ -1,6 +1,6 @@ /** * \file mm.c - * \brief Memory management. + * \brief Memory block management. */ /* @@ -37,9 +37,9 @@ */ /** - * \brief Dump memmory information about the heap. + * \brief Dump memory information about the heap. * - * \param heap memmory heap. + * \param heap memory heap. * * \note For debugging purposes. * @@ -67,7 +67,7 @@ void mmDumpMemInfo( memHeap_t *heap ) /** - * \brief Memmory heap initialization. + * \brief Memory heap initialization. * * \param offset offset in bytes. * \param size total size in bytes @@ -98,20 +98,20 @@ memHeap_t *mmInit(int ofs, /** - * \brief Slice a free memmory block. + * \brief Slice a free memory block. * - * \param p memmory block. - * \param startofs start offset to slice. - * \param size of the slice. - * \param reserved flag. - * \param alignment block alignment. + * \param p memory block. + * \param startofs slice start offset. + * \param size slice size. + * \param reserved reserved flag. + * \param alignment slice alignment. * * \return pointer to the slice block on success, or NULL on failure. * * \internal - * Creates a new block to the left with the remaining memory before the slice - * start (if any), a block to the right with the remaing memmory after the - * slice (if any), and the reduced memmory block itself as the slice. + * Creates a new block to the left with the memory before the slice start (if + * any), a block to the right with the memory after the slice (if any), and + * returns the reduced memory block itself as the slice. */ static TMemBlock* SliceBlock(TMemBlock *p, int startofs, int size, @@ -155,23 +155,24 @@ static TMemBlock* SliceBlock(TMemBlock *p, /** - * \brief Allocate a memmory block. + * \brief Allocate a memory block. * - * Allocate \p size bytes with \p 2^align2 bytes alignment, - * restrict the search to free memory after \p startSearch. - * Depth and back buffers should be in different 4MB banks - * to get better page hits if possible. + * Allocate \p size bytes with a \p 2^align2 bytes alignment, restricting the + * search to free memory after \p startSearch. Depth and back buffers should + * be in different 4MB banks to get better page hits if possible. * - * \param heap memmory heap. + * \param heap memory heap. * \param size size to allocate in bytes. - * \param align2 base 2 log of the alignment in bytes. - * \param startSearch linear offset from start of the heap to begin the search. + * \param align2 base 2 log of the block alignment in bytes. + * \param startSearch linear offset from start of the heap to begin the + * search. * * \return pointer to the allocated block on success, or NULL on failure. * * \internal * Walks through the free blocks on the heap and if it finds one above - * startSearch and large enough slices it via SliceBlock() and returns the result. + * \p startSearch and large enough slices it via SliceBlock() and returns the + * result. */ PMemBlock mmAllocMem( memHeap_t *heap, int size, int align2, int startSearch) { @@ -204,9 +205,9 @@ PMemBlock mmAllocMem( memHeap_t *heap, int size, int align2, int startSearch) /** - * \brief Join two successive free memmory blocks. + * \brief Join two successive free memory blocks. * - * \param p pointer to first memmory block. + * \param p pointer to first memory block. * * \return 1 on success, or 0 on failure. * @@ -227,7 +228,7 @@ static __inline__ int Join2Blocks(TMemBlock *p) /** - * \brief Free a memmory block. + * \brief Free a memory block. * * \param pointer to a block. * @@ -271,9 +272,9 @@ int mmFreeMem(PMemBlock b) /** - * \brief Destroy the memmory heap. + * \brief Destroy the memory heap. * - * \param heap memmory heap. + * \param heap memory heap. * * \internal * Frees each block in the heap. diff --git a/src/mesa/drivers/dri/common/mm.h b/src/mesa/drivers/dri/common/mm.h index 8d558d55b63..fa980ad39b9 100644 --- a/src/mesa/drivers/dri/common/mm.h +++ b/src/mesa/drivers/dri/common/mm.h @@ -1,6 +1,6 @@ /** * \file mm.h - * \brief Memory management. + * \brief Memory block management. */ /* @@ -30,7 +30,7 @@ #define MM_INC /** - * \brief Memmory block/heap. + * \brief Memory block/heap. */ struct mem_block_t { struct mem_block_t *next; /**< \brief pointer to next block in the heap */ @@ -43,30 +43,30 @@ struct mem_block_t { }; /** - * \brief Memmory block. + * \brief Memory block. */ typedef struct mem_block_t TMemBlock; /** - * \brief Memmory block pointer. + * \brief Memory block pointer. */ typedef struct mem_block_t *PMemBlock; /** - * \brief Memmory heap. + * \brief Memory heap. * * \note A heap is just the first block in a chain */ typedef struct mem_block_t memHeap_t; /** - * \brief Get Memmory block size. + * \brief Get Memory block size. */ static __inline__ int mmBlockSize(PMemBlock b) { return b->size; } /** - * \brief Get Memmory block offset. + * \brief Get Memory block offset. */ static __inline__ int mmOffset(PMemBlock b) { return b->ofs; } diff --git a/src/mesa/drivers/dri/radeon/radeon_context.c b/src/mesa/drivers/dri/radeon/radeon_context.c index fd9ab8a33f9..96be52fa882 100644 --- a/src/mesa/drivers/dri/radeon/radeon_context.c +++ b/src/mesa/drivers/dri/radeon/radeon_context.c @@ -208,8 +208,8 @@ static const char * const radeon_extensions[] = * * \param ctx GL context. * - * Enables the imaging extensions and every extension specified in in the - * radeon_extensions table. + * Enables the imaging extensions plus every extension specified in in the + * ::radeon_extensions table. */ static void radeonInitExtensions( GLcontext *ctx ) { @@ -270,7 +270,10 @@ static void radeonInitDriverFuncs( GLcontext *ctx ) * __DRIscreenPrivateRec::private, such as the SAREA pointer, DMA buffers * addresses and texture heaps. * - * Calls the radeonInit* functions to populate the driver callback functions. + * Calls the \c radeonInit* functions to populate the driver callback + * functions. Among these are radeonInitState(), radeonInitExtensions(), + * radeonInitDriverFuncs(), radeonInitIoctlFuncs(), radeonInitStateFuncs(), + * radeonInitTextureFuncs() and radeonInitSelect(). * * If compiled with debug support, reads the RADEON_DEBUG environment variable * and sets the debugging flags accordingly. @@ -641,8 +644,8 @@ radeonDestroyBuffer(__DRIdrawablePrivate *driDrawPriv) * * \param dPriv DRI specific drawable data. * - * If in double buffer mode it dispatches the call, either to - * radeonCopyBuffer() or radeonPageFlip() if page flipping is enabled. + * If in double buffer mode then it dispatches the call to radeonCopyBuffer() + * or radeonPageFlip() if page flipping is also enabled. */ static void radeonSwapBuffers( __DRIdrawablePrivate *dPriv ) @@ -754,12 +757,12 @@ radeonUnbindContext( __DRIcontextPrivate *driContextPriv ) /** * \brief Open/close fullscreen mode. * - * Fullscreen mode isn't used for much -- could be a way to shrink - * front/back buffers & get more texture memory if the client has - * changed the video resolution. + * \note Fullscreen mode isn't used for much - it could be a way to shrink + * front/back buffers and get more texture memory if the client has changed the + * video resolution. * - * Pageflipping is now done automatically whenever there is a single - * 3d client. + * \par + * Pageflipping is now done automatically whenever there is a single 3D client. * * \param driContextPriv DRI specific context data. Not used. * @@ -790,7 +793,8 @@ __driRegisterExtensions( void ) * * \return GL_TRUE on success or GL_FALSE on faillure. * - * Called as callback from __driCreateScreen below. + * Calls radeonCreateScreen() and if it fails calls radeonDestroyScreen() + * before returning. */ static GLboolean radeonInitDriver( __DRIscreenPrivate *sPriv ) @@ -807,6 +811,8 @@ radeonInitDriver( __DRIscreenPrivate *sPriv ) /** * \brief Driver interface structure + * + * Holds the DRI driver callbacks. */ static struct __DriverAPIRec radeonAPI = { radeonInitDriver, @@ -827,9 +833,11 @@ static struct __DriverAPIRec radeonAPI = { /** * \brief Bootstrap function for the driver. * - * The __driCreateScreen name is the symbol that libGL.so fetches. + * The \e __driCreateScreen name is the symbol that libGL.so fetches. * - * \return pointer to a __DRIscreenPrivate. + * \return pointer to a ::__DRIscreenPrivate structure. + * + * Calls __driUtilCreateScreen() with ::radeonAPI. */ void *__driCreateScreen(Display *dpy, int scrn, __DRIscreen *psc, int numConfigs, __GLXvisualConfig *config) diff --git a/src/mesa/drivers/dri/radeon/radeon_context.h b/src/mesa/drivers/dri/radeon/radeon_context.h index b1dcf8b321e..ec6824652e4 100644 --- a/src/mesa/drivers/dri/radeon/radeon_context.h +++ b/src/mesa/drivers/dri/radeon/radeon_context.h @@ -53,37 +53,56 @@ typedef struct radeon_context *radeonContextPtr; #include "radeon_swtcl.h" #endif +/** + * \brief Color buffer state. + */ struct radeon_colorbuffer_state { - GLuint clear; - GLint drawOffset, drawPitch; + GLuint clear; /**< \brief Clear value */ + GLint drawOffset; /**< \brief Drawing offset */ + Glint drawPitch; /**< \brief Drawing pitch */ }; - +/** + * \brief Depth buffer state. + */ struct radeon_depthbuffer_state { - GLuint clear; - GLfloat scale; + GLuint clear; /**< \brief Clear value */ + GLfloat scale; /**< \brief Depth scale */ }; +/** + * \brief Pixel state. + */ struct radeon_pixel_state { - GLint readOffset, readPitch; + GLint readOffset; /**< \brief Reading offset */ + Glint readPitch; /**< \brief Reading pitch */ }; +/** + * \brief Scissor state. + */ struct radeon_scissor_state { XF86DRIClipRectRec rect; - GLboolean enabled; + GLboolean enabled; /**< \brief Whether scissoring enable */ - GLuint numClipRects; /**< \brief Cliprects active */ - GLuint numAllocedClipRects; /**< \brief Cliprects available */ - XF86DRIClipRectPtr pClipRects; + GLuint numClipRects; /**< \brief Number of active cliprects */ + GLuint numAllocedClipRects; /**< \brief Number of available cliprects */ + XF86DRIClipRectPtr pClipRects; /**< \brief Cliprects */ }; +/** + * \brief Stencil buffer state. + */ struct radeon_stencilbuffer_state { - GLboolean hwBuffer; + GLboolean hwBuffer; /**< \brief Hardware buffer available? */ GLuint clear; /**< \brief rb3d_stencilrefmask value */ }; +/** + * \brief Stipple state. + */ struct radeon_stipple_state { - GLuint mask[32]; + GLuint mask[32]; /**< \brief Mask */ }; @@ -92,7 +111,10 @@ struct radeon_stipple_state { #define TEX_1 0x2 #define TEX_ALL 0x3 -typedef struct radeon_tex_obj radeonTexObj, *radeonTexObjPtr; + +typedef struct radeon_tex_obj radeonTexObj; /**< \brief Alias for radeon_tex_obj. */ +typedef struct radeon_tex_obj *radeonTexObjPtr; /**< \brief Alias for radeon_tex_obj. */ + /** * \brief Texture object in locally shared texture space. @@ -110,23 +132,25 @@ struct radeon_tex_obj { GLuint bufAddr; /** - * Flags for whether or not images need to be uploaded to local or AGP + * \brief Flags for whether or not images need to be uploaded to local or AGP * texture space */ GLuint dirty_images; /** - * Flags (1 per texunit) for whether or not this texobj has dirty hardware - * state (pp_*) that needs to be brought into the texunit. + * \brief Flags (one per texture unit) for whether or not this texture + * object has dirty hardware state (\c pp_*) that needs to be brought into + * the texunit. */ GLuint dirty_state; /** \brief Texture heap currently stored in */ GLint heap; + /** \brief Texture images */ drmRadeonTexImage image[RADEON_MAX_TEXTURE_LEVELS]; - /* Total size of the texture including all mipmap levels */ + /** \brief Total size of the texture including all mipmap levels */ GLint totalSize; /** @@ -151,15 +175,20 @@ struct radeon_tex_obj { /*@}*/ }; - +/** + * \brief Texture environment state. + */ struct radeon_texture_env_state { - radeonTexObjPtr texobj; - GLenum format; - GLenum envMode; + radeonTexObjPtr texobj; /**< \brief texture object */ + GLenum format; /**< \brief format */ + GLenum envMode; /**< \brief environment mode */ }; +/** + * \brief Texture state + */ struct radeon_texture_state { - struct radeon_texture_env_state unit[RADEON_MAX_TEXTURE_UNITS]; + struct radeon_texture_env_state unit[RADEON_MAX_TEXTURE_UNITS]; /**< \brief for each unit */ }; @@ -168,12 +197,12 @@ struct radeon_texture_state { */ struct radeon_state_atom { struct radeon_state_atom *next, *prev; - const char *name; /**< \brief for debug */ + const char *name; /**< \brief for debugging purposes */ int cmd_size; /**< \brief size in bytes */ - GLuint is_tcl; + GLuint is_tcl; /**< \brief whether is associated with TCL */ int *cmd; /**< \brief one or more cmd's */ int *lastcmd; /**< \brief one or more cmd's */ - GLboolean (*check)( GLcontext * ); /**< \brief is this state active? */ + GLboolean (*check)( GLcontext * ); /**< \brief callback to determin whether this state is active */ }; @@ -376,9 +405,9 @@ struct radeon_state_atom { #define SHN_STATE_SIZE 2 - - - +/** + * \brief Hardware state management. + */ struct radeon_hw_state { /** * \name State @@ -423,13 +452,13 @@ struct radeon_hw_state { * \brief Derived state for internal purposes: */ struct radeon_state { - struct radeon_colorbuffer_state color; - struct radeon_depthbuffer_state depth; - struct radeon_pixel_state pixel; - struct radeon_scissor_state scissor; - struct radeon_stencilbuffer_state stencil; - struct radeon_stipple_state stipple; - struct radeon_texture_state texture; + struct radeon_colorbuffer_state color; /**< \brief Color buffer */ + struct radeon_depthbuffer_state depth; /**< \brief Depth buffer */ + struct radeon_pixel_state pixel; /**< \brief Pixel */ + struct radeon_scissor_state scissor; /**< \brief Scissor */ + struct radeon_stencilbuffer_state stencil; /**< \brief Stencil buffer */ + struct radeon_stipple_state stipple; /**< \brief Stipple */ + struct radeon_texture_state texture; /**< \brief Textures */ }; /** @@ -437,7 +466,7 @@ struct radeon_state { */ struct radeon_texture { radeonTexObj objects[RADEON_NR_TEX_HEAPS]; /**< \brief texture objects */ - radeonTexObj swapped; /**< \brief swapped texture lists */ + radeonTexObj swapped; /**< \brief swapped texture */ memHeap_t *heap[RADEON_NR_TEX_HEAPS]; /**< \brief texture heaps */ GLint age[RADEON_NR_TEX_HEAPS]; /**< \brief aging */ @@ -470,12 +499,14 @@ struct radeon_dma_buffer { * e.g. vertices for indexed vertices. */ struct radeon_dma_region { - struct radeon_dma_buffer *buf; - char *address; /**< \brief buf->address */ - int start, end, ptr; /**< \brief offsets from start of radeon_dma_region::buf */ - int aos_start; /**< \brief array of structures start */ - int aos_stride; /**< \brief array of structures stride */ - int aos_size; /**< \brief array of structures size */ + struct radeon_dma_buffer *buf; /**< \brief DMA buffer */ + char *address; /**< \brief buf->address */ + int start; /**< \brief start offset from start of radeon_dma_region::buf */ + int end; /**< \brief end offset from start of radeon_dma_region::buf */ + int ptr; /**< \brief offsets from start of radeon_dma_region::buf */ + int aos_start; /**< \brief array of structures start */ + int aos_stride; /**< \brief array of structures stride */ + int aos_size; /**< \brief array of structures size */ }; @@ -484,11 +515,11 @@ struct radeon_dma_region { */ struct radeon_dma { /** - * \brief Active dma region. + * \brief Active DMA region. * * Allocations for vertices and retained regions come from here. Also used * for emitting random vertices, these may be flushed by calling - * radeon_dma::flush_current. + * radeon_dma::flush. */ struct radeon_dma_region current; @@ -497,7 +528,7 @@ struct radeon_dma { */ void (*flush)( radeonContextPtr ); - char *buf0_address; /**< \brief start of buf[0], for index calcs */ + char *buf0_address; /**< \brief start of buf[0], for index calculations */ GLuint nr_released_bufs; /**< \brief flush after so many buffers released */ }; @@ -532,13 +563,14 @@ struct radeon_store { }; -/* radeon_tcl.c +/** + * \brief TCL information. */ struct radeon_tcl_info { GLuint vertex_format; GLint last_offset; GLuint hw_primitive; - GLuint tcl_flag; + GLuint tcl_flag; /**< \brief Whether TCL is inabled */ struct radeon_dma_region *aos_components[8]; GLuint nr_aos_components; @@ -556,10 +588,12 @@ struct radeon_tcl_info { - +/** + * \brief Retained buffer. + */ struct radeon_ioctl { - GLuint vertex_offset; - GLuint vertex_size; + GLuint vertex_offset; /**< \brief offset of the vertex buffer */ + GLuint vertex_size; /**< \brief size of the vertex buffer */ }; @@ -577,8 +611,8 @@ struct radeon_context { * \name Driver and hardware state management */ /*@{*/ - struct radeon_hw_state hw; - struct radeon_state state; + struct radeon_hw_state hw; /**< \brief Hardware state */ + struct radeon_state state; /**< \brief Internal state */ /*@}*/ /** @@ -608,7 +642,7 @@ struct radeon_context { * \name Vertex buffers */ /*@{*/ - struct radeon_ioctl ioctl; + struct radeon_ioctl ioctl; /**< \brief Retained vertex buffer */ struct radeon_dma dma; /**< \brief DMA information */ struct radeon_store store; /**< \brief Command buffer */ /*@}*/ @@ -624,7 +658,8 @@ struct radeon_context { /*@{*/ GLuint do_usleeps; GLuint do_irqs; /**< \brief Do IRQs */ - GLuint irqsEmitted; + GLuint irqsEmitted; /**< \brief IRQ transition counter. + * \sa radeonWaitForFrameCompletion(). */ drmRadeonIrqWait iw; /*@}*/ @@ -635,7 +670,7 @@ struct radeon_context { GLuint numClipRects; /**< \brief Number of cliprects */ XF86DRIClipRectPtr pClipRects; /**< \brief cliprects for the draw buffer */ unsigned int lastStamp; - GLboolean lost_context; + GLboolean lost_context; /**< \brief re-emit all state */ radeonScreenPtr radeonScreen; /**< \brief Screen private DRI data */ RADEONSAREAPrivPtr sarea; /**< \brief Private SAREA data */ /*@}*/ @@ -688,7 +723,7 @@ struct radeon_context { /** * \brief Pack color. * - * \param cpp desired characters (bytes) per pixel. Either 2 or 4. + * \param cpp desired characters (bytes) per pixel. Shouble be either 2 or 4. * \param r red color component. * \param r green color component. * \param b blue color component. diff --git a/src/mesa/drivers/dri/radeon/radeon_ioctl.c b/src/mesa/drivers/dri/radeon/radeon_ioctl.c index 40c6e2ad8bb..5200052c450 100644 --- a/src/mesa/drivers/dri/radeon/radeon_ioctl.c +++ b/src/mesa/drivers/dri/radeon/radeon_ioctl.c @@ -122,8 +122,10 @@ static void radeon_emit_state_list( radeonContextPtr rmesa, * * If radeon_context::lost_context is set then all state is emited by moving * everything in radeon_hw_state::dirty prior to the radeon_emit_state_list() - * call. For woring around a Quake3 lock-up radeon_hw_state::zbs is always made - * \e dirty. + * call. + * + * \note For working around a Quake3 lock-up radeon_hw_state::zbs is always + * made \e dirty. */ void radeonEmitState( radeonContextPtr rmesa ) { @@ -426,7 +428,7 @@ void radeonFlushCmdBuf( radeonContextPtr rmesa, const char *caller ) * DMA buffer as the new current DMA region. * * In case of failure in the first try to get a new DMA buffer, flushes any - * previously released buffers, wait's for engine idle and tries once more, + * previously released buffers, waits for engine is idle and tries once more, * aborting if it fails. */ void radeonRefillCurrentDmaRegion( radeonContextPtr rmesa ) @@ -545,15 +547,15 @@ void radeonReleaseDmaRegion( radeonContextPtr rmesa, } /** - * \brief Allocates a new region from rmesa->dma.current. + * \brief Allocates a new region from radeon_dma::current. * * \param rmesa Radeon context. * \param region region will received the allocated region. * \param bytes size. * \param alignment alignment. * - * If there isn't enough space in current, grab a new buffer (and discard what - * was left of current). + * If there isn't enough space in the current DMA buffer, grab a new buffer + * (and discard what was left of it). */ void radeonAllocDmaRegion( radeonContextPtr rmesa, struct radeon_dma_region *region, @@ -618,7 +620,7 @@ void radeonAllocDmaRegionVerts( radeonContextPtr rmesa, * * \param rmesa Radeon context. * - * \return last frame number on success, or a nec + * \return last frame number. * * Gets the last frame number via the DRM_RADEON_GETPARAM command in recent * DRMs, or via the RADEON_LAST_FRAME_REG register. @@ -702,14 +704,48 @@ static void radeonWaitIrq( radeonContextPtr rmesa ) * * \param rmesa Radeon context. * - * Waits until the number of processed frames reaches the one specifies in the + * Waits until the number of processed frames reaches RADEONSAREAPriv::last_frame in the * SAREA. * - * If IRQs are enabled and one has been emited then wait on the IRQ and send - * one afterwards. + * The idea is to only emit IRQ's if the graphics card is the bottleneck -- ie + * only do it if we find that the previous frame hasn't completed. When the + * card is the bottlneck one'd like to do something like: * - * It assumes that the hardware was locked prior to the call but all waits are - * internally done with the hardware unlocked. + *\code + * render frame 0 + * swap buffers + * emit IRQ 0 + * render frame 1 + * wait on IRQ 0 (i.e. wait for last frame to complete) + * swap buffers + * emit IRQ 1, + * ... + * \endcode + * + * But, if there's no need to wait for hardware (i.e., the application/driver + * is bottleneck), then one'd prefer: + * + * \code + * render frame 0 + * swapbuffers + * render frame 1 + * swapbuffers + * ... + * \endcode + * + * without any doing any IRQ or waiting. + * + * The radeon_context::irqsEmitted determines transition between these modes. + * It is set to 10 if it ever has to wait, and decremented otherwise. If it + * finds it has to wait, checks radeon_context::irqsEmitted to determine if + * there is an IRQ pending that we can wait on -- otherwise do busy wait. + * Finally, after the waiting/not-waiting is over, checks + * radeon_context::irqsEmitted, if non-zero, emits an IRQ. + * + * If IRQ's aren't supported for whatever reason, it always busy waits. + * + * This function assumes that the hardware was locked prior to the call but + * all waits are internally done with the hardware unlocked. */ static void radeonWaitForFrameCompletion( radeonContextPtr rmesa ) { @@ -902,7 +938,7 @@ void radeonPageFlip( const __DRIdrawablePrivate *dPriv ) * Locks the hardware and throttles the number of clear ioctl's done, allowing * up to #RADEON_MAX_CLEARS. For each set of cliprects, intersects them with * the clearing rectangle (if not clearing all) and uploads them to the SAREA, - * setups a drmRadeonClearType structure sends it to the DRM_RADEON_CLEAR + * setups a drmRadeonClearT structure sends it to the DRM_RADEON_CLEAR * command. */ static void radeonClear( GLcontext *ctx, GLbitfield mask, GLboolean all, diff --git a/src/mesa/drivers/dri/radeon/server/radeon.h b/src/mesa/drivers/dri/radeon/server/radeon.h index c2430bd0548..49aabbd6c0e 100644 --- a/src/mesa/drivers/dri/radeon/server/radeon.h +++ b/src/mesa/drivers/dri/radeon/server/radeon.h @@ -161,7 +161,7 @@ typedef struct { unsigned int frontPitchOffset; unsigned int backPitchOffset; - unsigned int depthPitchOffset + unsigned int depthPitchOffset; int irq; /**< \brief IRQ number */ unsigned int gen_int_cntl; diff --git a/src/mesa/drivers/dri/radeon/server/radeon_common.h b/src/mesa/drivers/dri/radeon/server/radeon_common.h index 2a8425df89d..5a3ae0be293 100644 --- a/src/mesa/drivers/dri/radeon/server/radeon_common.h +++ b/src/mesa/drivers/dri/radeon/server/radeon_common.h @@ -2,6 +2,9 @@ * \file server/radeon_common.h * \brief Common header definitions for Radeon 2D/3D/DRM driver suite. * + * \note Some of these structures are meant for backward compatability and + * aren't used by the subset driver. + * * \author Gareth Hughes * \author Kevin E. Martin * \author Keith Whitwell @@ -91,12 +94,11 @@ * \brief DRM_RADEON_CP_INIT ioctl argument type. */ typedef struct { - /** \brief request */ enum { - DRM_RADEON_INIT_CP = 0x01, /**< \brief initialize CP */ - DRM_RADEON_CLEANUP_CP = 0x02, /**< \brief clean up CP */ - DRM_RADEON_INIT_R200_CP = 0x03 /**< \brief initialize R200 CP */ - } func; + DRM_RADEON_INIT_CP = 0x01, /**< \brief initialize CP */ + DRM_RADEON_CLEANUP_CP = 0x02, /**< \brief clean up CP */ + DRM_RADEON_INIT_R200_CP = 0x03 /**< \brief initialize R200 CP */ + } func; /**< \brief request */ unsigned long sarea_priv_offset; /**< \brief SAREA private offset */ int is_pci; /**< \brief is current card a PCI card? */ int cp_mode; /**< \brief CP mode */ @@ -145,12 +147,13 @@ typedef union drmRadeonClearR { * \brief DRM_RADEON_CLEAR ioctl argument type. */ typedef struct drmRadeonClearT { - unsigned int flags; - unsigned int clear_color; - unsigned int clear_depth; - unsigned int color_mask; - unsigned int depth_mask; /* misnamed field: should be stencil */ - drmRadeonClearRect *depth_boxes; + unsigned int flags; /**< \brief bitmask of the planes to clear */ + unsigned int clear_color; /**< \brief color buffer clear value */ + unsigned int clear_depth; /**< \brief depth buffer clear value */ + unsigned int color_mask; /**< \brief color buffer clear mask */ + unsigned int depth_mask; /**< \brief stencil buffer clear value + * \todo Misnamed field. */ + drmRadeonClearRect *depth_boxes; /**< \brief depth buffer cliprects */ } drmRadeonClearType; typedef struct drmRadeonFullscreenT { @@ -297,7 +300,7 @@ typedef struct { /** * \brief Command buffer. * - * \todo Replace with true dma stream? + * \todo Replace with true DMA stream? */ typedef struct { int bufsz; /**< \brief buffer size */ @@ -483,10 +486,13 @@ typedef struct drm_radeon_mem_free { int region_offset; } drmRadeonMemFree; +/** + * \brief DRM_RADEON_INIT_HEAP argument type. + */ typedef struct drm_radeon_mem_init_heap { - int region; - int size; - int start; + int region; /**< \brief region type */ + int size; /**< \brief region size */ + int start; /**< \brief region start offset */ } drmRadeonMemInitHeap; /** diff --git a/src/mesa/drivers/dri/radeon/server/radeon_dri.c b/src/mesa/drivers/dri/radeon/server/radeon_dri.c index 4222aae043e..ebbe4344a1e 100644 --- a/src/mesa/drivers/dri/radeon/server/radeon_dri.c +++ b/src/mesa/drivers/dri/radeon/server/radeon_dri.c @@ -3,8 +3,8 @@ * \brief File to perform the device-specific initialization tasks typically * done in the X server. * - * Here they are converted to run in the client (or perhaps a - * standalone process), and to work with fbdev rather than the X + * Here they are converted to run in the client (or perhaps a standalone + * process), and to work with the frambe buffer device rather than the X * server infrastructure. */ @@ -42,7 +42,7 @@ * \param entries number of free entries to wait. * * It polls the free entries from the chip until it reaches the requested value - * or a timeout (3000 tries) occurs. Aborts the program if the FIFO timesout. + * or a timeout (3000 tries) occurs. Aborts the program if the FIFO times out. */ static void RADEONWaitForFifo( struct MiniGLXDisplayRec *dpy, int entries ) @@ -429,7 +429,7 @@ static int RADEONDRIKernelInit(struct MiniGLXDisplayRec *dpy, * \param info driver private data. * * This function is a wrapper around the DRM_RADEON_INIT_HEAP command, passing - * all the parameters in a drmRadeonMemInitHeap structure. + * all the parameters in a drm_radeon_mem_init_heap structure. */ static void RADEONDRIAgpHeapInit(struct MiniGLXDisplayRec *dpy, RADEONInfoPtr info) @@ -526,6 +526,15 @@ static void RADEONDRIIrqInit(struct MiniGLXDisplayRec *dpy, * \param info driver private data. * * \return non-zero on sucess, or zero on failure. + * + * Performs static frame buffer allocation. Opens the DRM device and add maps + * to the SAREA, framebuffer and MMIO regions. Fills in \p info with more + * information. Creates a \e server context to grab the lock for the + * initialization ioctls and calls the other initliaztion functions in this + * file. Starts the CP engine via the DRM_RADEON_CP_START command. + * + * Setups a RADEONDRIRec structure to be passed to radeon_dri.so for its + * initialization. */ static int RADEONScreenInit( struct MiniGLXDisplayRec *dpy, RADEONInfoPtr info ) { @@ -1003,7 +1012,7 @@ static int __driInitScreenConfigs( struct MiniGLXDisplayRec *dpy, * * \return one on success, or zero on failure. * - * Saves some registers and returns one. + * Saves some registers and returns 1. * * \sa __driValidateMode(). */ @@ -1026,7 +1035,7 @@ static int __driValidateMode( struct MiniGLXDisplayRec *dpy ) * * \return one on success, or zero on failure. * - * Restores registers that fbdev has clobbered and returns one. + * Restores registers that fbdev has clobbered and returns 1. * * \sa __driValidateMode(). */ @@ -1048,6 +1057,11 @@ static int __driPostValidateMode( struct MiniGLXDisplayRec *dpy ) * \param dpy display handle. * * \return one on success, or zero on failure. + * + * Fills in \p info with some default values and some information from \p dpy + * and then calls RADEONScreenInit() for the screen initialization. + * + * Before exiting clears the framebuffer memomry accessing it directly. */ static int __driInitFBDev( struct MiniGLXDisplayRec *dpy ) { @@ -1102,10 +1116,14 @@ static int __driInitFBDev( struct MiniGLXDisplayRec *dpy ) } -/* The screen is being closed, so clean up any state and free any +/** + * \brief The screen is being closed, so clean up any state and free any * resources used by the DRI. * * \param dpy display handle. + * + * Unmaps the SAREA, closes the DRM device file descriptor and frees the driver + * private data. */ static void __driHaltFBDev( struct MiniGLXDisplayRec *dpy ) { @@ -1120,7 +1138,7 @@ static void __driHaltFBDev( struct MiniGLXDisplayRec *dpy ) /** - * \brief Exported driver interface. + * \brief Exported driver interface for Mini GLX. * * \sa MiniGLXDriverRec. */ diff --git a/src/mesa/drivers/dri/radeon/server/radeon_sarea.h b/src/mesa/drivers/dri/radeon/server/radeon_sarea.h index fb801285f08..949ac39c361 100644 --- a/src/mesa/drivers/dri/radeon/server/radeon_sarea.h +++ b/src/mesa/drivers/dri/radeon/server/radeon_sarea.h @@ -284,9 +284,9 @@ typedef struct { * Counters for throttling rendering of clients. */ /*@{*/ - unsigned int last_frame; + unsigned int last_frame; /**< \brief last emmited frame */ unsigned int last_dispatch; - unsigned int last_clear; + unsigned int last_clear; /**< \brief last emmited clear */ /*@}*/ /**