BufTab

Describes an array of Buffer objects (of all types, see Buffer_Type). All buffers in a BufTab have the same size and are created with the same attributes. For this reason, one can access the first Buffer in the BufTab to learn about the characteristics of all Buffers in the BufTab. Typical usage below to allocate an array of 10 basic Buffers of size 1KB (no error checking):. More...

Typedefs

typedef struct BufTab_Object * BufTab_Handle
 Handle through which to reference a BufTab.

Functions

BufTab_Handle BufTab_create (Int numBufs, Int32 size, Buffer_Attrs *attrs)
 Creates a BufTab and the buffers belonging to it.
Int BufTab_delete (BufTab_Handle hBufTab)
 Deletes a BufTab.
Int BufTab_chunk (BufTab_Handle hBufTab, Int numBufs, Int32 bufSize)
 Chunk a BufTab in to smaller buffer sizes. This will not change the original allocation during creation, it merely tries to fit many smaller Buffers inside the already allocated Buffers.
Int BufTab_collapse (BufTab_Handle hBufTab)
 Restore the BufTab to the state before BufTab_chunk was called on it. Note that this will undo any calls to BufTab_expand after the BufTab_chunk call.
Int BufTab_expand (BufTab_Handle hBufTab, Int numBufs)
 Expand a BufTab with more buffers.
Buffer_Handle BufTab_getBuf (BufTab_Handle hBufTab, Int bufIdx)
 Return a buffer with a certain index in the BufTab.
Int BufTab_getNumBufs (BufTab_Handle hBufTab)
 Get the number of Buffers in a BufTab.
Void BufTab_print (BufTab_Handle hBufTab)
 Print information about the buffers in the BufTab.
Void BufTab_freeAll (BufTab_Handle hBufTab)
 Mark all buffers in a BufTab as free.
Void BufTab_freeBuf (Buffer_Handle hBuf)
 Mark a Buffer as free in a BufTab.
Buffer_Handle BufTab_getFreeBuf (BufTab_Handle hBufTab)
 Return a free buffer from the BufTab and mark it as used.

Detailed Description

Describes an array of Buffer objects (of all types, see Buffer_Type). All buffers in a BufTab have the same size and are created with the same attributes. For this reason, one can access the first Buffer in the BufTab to learn about the characteristics of all Buffers in the BufTab. Typical usage below to allocate an array of 10 basic Buffers of size 1KB (no error checking):.

     #include <xdc/std.h>
     #include <ti/sdo/dmai/Dmai.h>
     #include <ti/sdo/dmai/BufTab.h>
     BufTab_Handle hBufTab;
     Buffer_Attrs bAttrs = Buffer_Attrs_DEFAULT;

     Dmai_init();
     hBufTab = BufTab_create(10, 1024, &bAttrs);
     // Operate on the Buffers in the BufTab
     BufTab_delete(hBufTab);

Typedef Documentation

typedef struct BufTab_Object* BufTab_Handle

Handle through which to reference a BufTab.


Function Documentation

BufTab_Handle BufTab_create ( Int  numBufs,
Int32  size,
Buffer_Attrs attrs 
)

Creates a BufTab and the buffers belonging to it.

Parameters:
[in] numBufs Number of buffers to allocate.
[in] size Size in bytes of buffers to create.
[in] attrs Buffer_Attrs to use for creating the buffers in the BufTab.
Return values:
BufTab_Handle for use in subsequent operations (see BufTab_Handle).
NULL for failure.

Int BufTab_delete ( BufTab_Handle  hBufTab  ) 

Deletes a BufTab.

Parameters:
[in] hBufTab The BufTab_Handle to delete.
Return values:
Dmai_EOK for success.
Negative value for failure, see Dmai.h.
Remarks:
BufTab_create must be called before this function.

Int BufTab_chunk ( BufTab_Handle  hBufTab,
Int  numBufs,
Int32  bufSize 
)

Chunk a BufTab in to smaller buffer sizes. This will not change the original allocation during creation, it merely tries to fit many smaller Buffers inside the already allocated Buffers.

Each buffer in a BufTab is chunked separately; i.e., if the initial buffer size is not an exact multiple of the new bufSize, the remaining space in the initial buffer becomes unused and does not count when chunking the next buffer in the BufTab.

Parameters:
[in] hBufTab The BufTab_Handle to chunk.
[in] numBufs The desired # of buffers to chunk the BufTab into
[in] bufSize The size in bytes of the buffers to chunk in to.
Return values:
The difference between numBufs and the actual number of buffers in the newly modified BufTab. 0 if the number of buffers matches numBufs.
Negative value for failure, see Dmai.h.
Remarks:
BufTab_create must be called before this function.

If a Buffer inside the BufTab is already in use when this functions is called, it will not be chunked but left as is. Note that this means that you may have a BufTab with varying sizes after this call.

Int BufTab_collapse ( BufTab_Handle  hBufTab  ) 

Restore the BufTab to the state before BufTab_chunk was called on it. Note that this will undo any calls to BufTab_expand after the BufTab_chunk call.

Parameters:
[in] hBufTab The BufTab_Handle to collapse.
Return values:
Dmai_EOK for success.
Negative value for failure, see Dmai.h.
Remarks:
BufTab_create must be called before this function.

Int BufTab_expand ( BufTab_Handle  hBufTab,
Int  numBufs 
)

Expand a BufTab with more buffers.

Parameters:
[in] hBufTab The BufTab_Handle to expand.
[in] numBufs The number of buffers to expand the BufTab with.
Return values:
Dmai_EOK for success.
Negative value for failure, see Dmai.h.
Remarks:
BufTab_create must be called before this function.

In case a BufTab contains buffers of different sizes (which is possible after a BufTab_chunk), the new buffers will be cloned from the Buffer with the smallest size.

Buffer_Handle BufTab_getBuf ( BufTab_Handle  hBufTab,
Int  bufIdx 
)

Return a buffer with a certain index in the BufTab.

Parameters:
[in] hBufTab The BufTab_Handle to which the buffer belongs.
[in] bufIdx The index of the buffer in the BufTab.
Return values:
Handle to the buffer matching the supplied index (see BufTab_Handle).
Remarks:
BufTab_create must be called before this function.

Int BufTab_getNumBufs ( BufTab_Handle  hBufTab  ) 

Get the number of Buffers in a BufTab.

Parameters:
[in] hBufTab The BufTab of which to get the number of buffers.
Return values:
Number of buffers in the BufTab.
Remarks:
BufTab_create must be called before this function.

Void BufTab_print ( BufTab_Handle  hBufTab  ) 

Print information about the buffers in the BufTab.

Parameters:
[in] hBufTab The BufTab_Handle to print information about.
Remarks:
BufTab_create must be called before this function.

Void BufTab_freeAll ( BufTab_Handle  hBufTab  ) 

Mark all buffers in a BufTab as free.

Parameters:
[in] hBufTab The BufTab_Handle of the BufTab to free.
Remarks:
BufTab_create must be called before this function.

Void BufTab_freeBuf ( Buffer_Handle  hBuf  ) 

Mark a Buffer as free in a BufTab.

Parameters:
[in] hBuf The Buffer_Handle of the Buffer to free.
Remarks:
BufTab_create must be called before this function.

Buffer_Handle BufTab_getFreeBuf ( BufTab_Handle  hBufTab  ) 

Return a free buffer from the BufTab and mark it as used.

Parameters:
[in] hBufTab The BufTab_Handle from which to get a buffer.
Return values:
Handle to a free buffer (see BufTab_Handle).
NULL for failure.
Remarks:
BufTab_create must be called before this function.


Copyright 2011, Texas Instruments Incorporated