Buffer

Describes a buffer. The other DMAI modules perform operations on instances of this module. There are submodules of this module such as BufferGfx which can also use the Buffer functions. Typical Buffer module usage for a 1KB buffer (no error checks):. More...

Data Structures

struct  Buffer_Attrs
 Attributes used when creating a Buffer instance. More...

Typedefs

typedef struct _Buffer_Object * Buffer_Handle
 Handle through which to reference a Buffer instance.

Enumerations

enum  Buffer_Type {
  Buffer_Type_BASIC = 0,
  Buffer_Type_GRAPHICS = 1,
  Buffer_Type_COUNT
}
 Types of Buffers. More...

Functions

Buffer_Handle Buffer_create (Int32 size, Buffer_Attrs *attrs)
 Creates and allocates a contiguous Buffer.
Buffer_Handle Buffer_clone (Buffer_Handle hBuf)
 Creates and clone of an existing Buffer. Only the attributes used while creating the cloned Buffer will be used.
Void Buffer_print (Buffer_Handle hBuf)
 Prints information about a buffer.
Int Buffer_delete (Buffer_Handle hBuf)
 Deletes and frees a contiguous Buffer.
Void Buffer_getAttrs (Buffer_Handle hBuf, Buffer_Attrs *attrs)
 Get the Buffer_Attrs corresponding to existing buffer.
Void Buffer_setUseMask (Buffer_Handle hBuf, UInt16 useMask)
 Set the current use mask.
Void Buffer_freeUseMask (Buffer_Handle hBuf, UInt16 useMask)
 Free bits in the current use mask. When the resulting use mask is 0, the Buffer is considered free.
Void Buffer_resetUseMask (Buffer_Handle hBuf)
 Set the current use mask to the original use mask, essentially marking the Buffer as busy.
UInt16 Buffer_getUseMask (Buffer_Handle hBuf)
 Get the current use mask of a Buffer.
Int Buffer_getId (Buffer_Handle hBuf)
 Get the id of a Buffer. The id identifies a Buffer in a BufTab.
Int8 * Buffer_getUserPtr (Buffer_Handle hBuf)
 Get the user pointer of the Buffer. This pointer can be used to access the Buffer using the CPU.
Int32 Buffer_getPhysicalPtr (Buffer_Handle hBuf)
 Get the physical pointer of the Buffer. This pointer can be used by device drivers and DMA to access the Buffer.
Int32 Buffer_getSize (Buffer_Handle hBuf)
 Get the size of a Buffer.
Buffer_Type Buffer_getType (Buffer_Handle hBuf)
 Get the type of a Buffer.
Int32 Buffer_getNumBytesUsed (Buffer_Handle hBuf)
 When a DMAI module has processed data and written it to a Buffer, it records the actual number of bytes used (which may or may not be the same as the size).
Void Buffer_setNumBytesUsed (Buffer_Handle hBuf, Int32 numBytes)
 Set the number of bytes used in a Buffer. If you process data outside of DMAI, call this function to tell the DMAI modules how many bytes it should process in the Buffer.
Int Buffer_setUserPtr (Buffer_Handle hBuf, Int8 *ptr)
 Set the User pointer for a Buffer reference.
Int Buffer_setSize (Buffer_Handle hBuf, Int32 size)
 Set the size of a Buffer reference.
Int Buffer_setVirtualSize (Buffer_Handle hBuf, Int32 size)
 Set the virtual size of a Buffer.
Bool Buffer_isReference (Buffer_Handle hBuf)
 Investigate whether a Buffer instance is a reference or not.
BufTab_Handle Buffer_getBufTab (Buffer_Handle hBuf)
 Get the BufTab instance which a Buffer belongs to, if any.
Int Buffer_copy (Buffer_Handle hSrcBuf, Buffer_Handle hDstBuf)
 Copies Buffer object from source to destination.

Variables

const Memory_AllocParams Buffer_Memory_Params_DEFAULT
 The default parameters for the Memory module while creating a Buffer.
const Buffer_Attrs Buffer_Attrs_DEFAULT
 The default parameters when creating a Buffer.

Detailed Description

Describes a buffer. The other DMAI modules perform operations on instances of this module. There are submodules of this module such as BufferGfx which can also use the Buffer functions. Typical Buffer module usage for a 1KB buffer (no error checks):.

     #include <xdc/std.h>
     #include <ti/sdo/dmai/Dmai.h>
     #include <ti/sdo/dmai/Buffer.h>
     Buffer_Handle hBuf;
     Buffer_Attrs bAttrs = Buffer_Attrs_DEFAULT;
     Dmai_init();
     hBuf = Buffer_create(1024, &bAttrs);
     // Operate on Buffer
     Buffer_delete(hBuf);

Typedef Documentation

typedef struct _Buffer_Object* Buffer_Handle

Handle through which to reference a Buffer instance.


Enumeration Type Documentation

Types of Buffers.

Enumerator:
Buffer_Type_BASIC  The basic Buffer used for e.g. I/O or Sound.
Buffer_Type_GRAPHICS  The extended graphics Buffer described in BufferGfx.
Buffer_Type_COUNT 


Function Documentation

Buffer_Handle Buffer_create ( Int32  size,
Buffer_Attrs attrs 
)

Creates and allocates a contiguous Buffer.

Parameters:
[in] size Size in bytes of buffer to create.
[in] attrs Buffer_Attrs to use for creating the Buffer.
Return values:
Handle for use in subsequent operations (see Buffer_Handle).
NULL for failure.

Buffer_Handle Buffer_clone ( Buffer_Handle  hBuf  ) 

Creates and clone of an existing Buffer. Only the attributes used while creating the cloned Buffer will be used.

Parameters:
[in] hBuf The Buffer_Handle of the Buffer to clone.
Return values:
Handle for use in subsequent operations (see Buffer_Handle).
NULL for failure.
Remarks:
Buffer_create or BufTab_create must be called before this function.

Void Buffer_print ( Buffer_Handle  hBuf  ) 

Prints information about a buffer.

Parameters:
[in] hBuf The Buffer_Handle of the Buffer to print information for.
Remarks:
Buffer_create or BufTab_create must be called before this function.

Int Buffer_delete ( Buffer_Handle  hBuf  ) 

Deletes and frees a contiguous Buffer.

Parameters:
[in] hBuf The Buffer_Handle of the Buffer to delete.
Return values:
Dmai_EOK for success.
Negative value for failure, see Dmai.h.
Remarks:
Buffer_create or BufTab_create must be called before this function.

Void Buffer_getAttrs ( Buffer_Handle  hBuf,
Buffer_Attrs attrs 
)

Get the Buffer_Attrs corresponding to existing buffer.

Parameters:
[in] hBuf The Buffer_Handle to match Buffer_Attrs for.
[out] attrs The Buffer_Attrs structure to fill in.
Remarks:
Buffer_create or BufTab_create must be called before this function.

Void Buffer_setUseMask ( Buffer_Handle  hBuf,
UInt16  useMask 
)

Set the current use mask.

Parameters:
[in] hBuf The Buffer_Handle to set the use mask for.
[in] useMask The useMask to set.
Remarks:
Buffer_create or BufTab_create must be called before this function.

Void Buffer_freeUseMask ( Buffer_Handle  hBuf,
UInt16  useMask 
)

Free bits in the current use mask. When the resulting use mask is 0, the Buffer is considered free.

Parameters:
[in] hBuf The Buffer_Handle to free the use mask of.
[in] useMask The use mask to strip using "BufferUseMask &= ~useMask";
Remarks:
Buffer_create or BufTab_create must be called before this function.

Void Buffer_resetUseMask ( Buffer_Handle  hBuf  ) 

Set the current use mask to the original use mask, essentially marking the Buffer as busy.

Parameters:
[in] hBuf The Buffer_Handle to reset.
Remarks:
Buffer_create or BufTab_create must be called before this function.

UInt16 Buffer_getUseMask ( Buffer_Handle  hBuf  ) 

Get the current use mask of a Buffer.

Parameters:
[in] hBuf The Buffer_Handle to get the current use mask of.
Return values:
useMask of the Buffer.
Remarks:
Buffer_create or BufTab_create must be called before this function.

Int Buffer_getId ( Buffer_Handle  hBuf  ) 

Get the id of a Buffer. The id identifies a Buffer in a BufTab.

Parameters:
[in] hBuf The Buffer_Handle to get the id of.
Return values:
id of the Buffer.
Remarks:
Buffer_create or BufTab_create must be called before this function.

Int8* Buffer_getUserPtr ( Buffer_Handle  hBuf  ) 

Get the user pointer of the Buffer. This pointer can be used to access the Buffer using the CPU.

Parameters:
[in] hBuf The Buffer_Handle to get the user pointer of.
Return values:
User pointer of the Buffer.
Remarks:
Buffer_create or BufTab_create must be called before this function.

Int32 Buffer_getPhysicalPtr ( Buffer_Handle  hBuf  ) 

Get the physical pointer of the Buffer. This pointer can be used by device drivers and DMA to access the Buffer.

Parameters:
[in] hBuf The Buffer_Handle to get the user pointer of.
Return values:
Physical pointer of the Buffer.
Remarks:
You should not use this pointer in your application directly.

Buffer_create or BufTab_create must be called before this function.

Int32 Buffer_getSize ( Buffer_Handle  hBuf  ) 

Get the size of a Buffer.

Parameters:
[in] hBuf The Buffer_Handle to get the size of.
Return values:
Size of the Buffer.
Remarks:
Buffer_create or BufTab_create must be called before this function.

Buffer_Type Buffer_getType ( Buffer_Handle  hBuf  ) 

Get the type of a Buffer.

Parameters:
[in] hBuf The Buffer_Handle to get the type of.
Return values:
Type of the Buffer (see Buffer_Type).
Remarks:
Buffer_create or BufTab_create must be called before this function.

Int32 Buffer_getNumBytesUsed ( Buffer_Handle  hBuf  ) 

When a DMAI module has processed data and written it to a Buffer, it records the actual number of bytes used (which may or may not be the same as the size).

Parameters:
[in] hBuf The Buffer_Handle to get the number of bytes used of.
Return values:
Number of bytes used in the Buffer.
Remarks:
A DMAI processing function or Buffer_setNumBytesUsed() should be used on this module before calling this function.

Buffer_create or BufTab_create must be called before this function.

Void Buffer_setNumBytesUsed ( Buffer_Handle  hBuf,
Int32  numBytes 
)

Set the number of bytes used in a Buffer. If you process data outside of DMAI, call this function to tell the DMAI modules how many bytes it should process in the Buffer.

Parameters:
[in] hBuf The Buffer_Handle to set the number of bytes used for.
[in] numBytes The number of bytes used in the Buffer.
Remarks:
Buffer_create or BufTab_create must be called before this function.

Int Buffer_setUserPtr ( Buffer_Handle  hBuf,
Int8 *  ptr 
)

Set the User pointer for a Buffer reference.

Parameters:
[in] hBuf The Buffer_Handle to set the pointer for. Needs to have been created as a reference (see Buffer_Attrs.reference.
[in] ptr Pointer to set.
Return values:
Dmai_EOK for success.
Negative value for failure, see Dmai.h.
Remarks:
The Buffer instance passed need to having been created as a reference, see Buffer_Attrs.reference.

Buffer_create or BufTab_create must be called before this function.

Int Buffer_setSize ( Buffer_Handle  hBuf,
Int32  size 
)

Set the size of a Buffer reference.

Parameters:
[in] hBuf The Buffer_Handle to set the pointer for. Needs to have been created as a reference (see Buffer_Attrs.reference.
[in] size Size to set.
Return values:
Dmai_EOK for success.
Negative value for failure, see Dmai.h.
Remarks:
The Buffer instance passed need to having been created as a reference, see Buffer_Attrs.reference.

Buffer_create or BufTab_create must be called before this function.

Int Buffer_setVirtualSize ( Buffer_Handle  hBuf,
Int32  size 
)

Set the virtual size of a Buffer.

Parameters:
[in] hBuf The Buffer_Handle to set the pointer for. Needs to have been created as a reference (see Buffer_Attrs.reference.
[in] size Size to set.
Return values:
Dmai_EOK for success.
Negative value for failure, see Dmai.h.
Remarks:
The Buffer instance passed need to having been created as a reference, see Buffer_Attrs.reference.

Buffer_create or BufTab_create must be called before this function.

This API as temporary workaround to handle disjoined buffers. It will become obsolete, once PSP supports multiple buffer planes, and DMAI makes corresponding changes.

Bool Buffer_isReference ( Buffer_Handle  hBuf  ) 

Investigate whether a Buffer instance is a reference or not.

param[in] hBuf The Buffer_Handle to investigate.

Return values:
TRUE if the Buffer instance is a reference.
FALSE if not.

BufTab_Handle Buffer_getBufTab ( Buffer_Handle  hBuf  ) 

Get the BufTab instance which a Buffer belongs to, if any.

Parameters:
[in] hBuf Get the BufTab_Handle of the BufTab this Buffer belong to, if any.
Return values:
BufTab_Handle of the BufTab instance a Buffer belongs to.
NULL if the Buffer does not belong to a BufTab.

Int Buffer_copy ( Buffer_Handle  hSrcBuf,
Buffer_Handle  hDstBuf 
)

Copies Buffer object from source to destination.

Parameters:
[in] hSrcBuf The Buffer_Handle of the Buffer to copy.
[out] hDstBuf The Buffer_Handle of the destination Buffer.
Remarks:
The destination Buffer will become a reference buffer and can be safely freed using Buffer_delete.

The buffer pointed to by the destination Buffer object will be freed before the copy occurs.


Variable Documentation

const Memory_AllocParams Buffer_Memory_Params_DEFAULT

The default parameters for the Memory module while creating a Buffer.

 type         = Memory_CONTIGPOOL,
 flags        = Memory_NONCACHED,
 align        = Memory_DEFAULTALIGNMENT,
 seg          = 0

The default parameters when creating a Buffer.

 memParams    = Buffer_Memory_Params_DEFAULT,
 type         = Buffer_Type_BASIC,
 useMask      = 1
 reference    = FALSE


Copyright 2011, Texas Instruments Incorporated