Detailed Description

Defines the interfaces and data structures for the API sub-component CHNL.

============================================================================

Path:: /gpp/inc/usr/

Version:: 1.65.01.06 ============================================================================

Copyright:: Copyright (C) 2002-2009, Texas Instruments Incorporated - https://www.ti.com/

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of Texas Instruments Incorporated nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ============================================================================

#include <dsplink.h>
#include <chnldefs.h>

Include dependency graph for chnl.h:

Go to the source code of this file.

Defines
#define	CHNL_Create CHNL_create
#define	CHNL_Delete CHNL_delete
#define	CHNL_AllocateBuffer CHNL_allocateBuffer
#define	CHNL_FreeBuffer CHNL_freeBuffer
#define	CHNL_Issue CHNL_issue
#define	CHNL_Reclaim CHNL_reclaim
#define	CHNL_Idle CHNL_idle
#define	CHNL_Flush CHNL_flush
#define	CHNL_Control CHNL_control
Functions
EXPORT_API DSP_STATUS	CHNL_create (IN ProcessorId procId, IN ChannelId chnlId, IN ChannelAttrs *attrs)
	Creates resources used for transferring data between GPP and DSP.
EXPORT_API DSP_STATUS	CHNL_delete (IN ProcessorId procId, IN ChannelId chnlId)
	Releases channel resources used for transferring data between GPP and DSP.
EXPORT_API DSP_STATUS	CHNL_allocateBuffer (IN ProcessorId procId, IN ChannelId chnlId, OUT Char8 **bufArray, IN Uint32 size, IN Uint32 numBufs)
	Allocates an array of buffers of specified size and returns them to the client.
EXPORT_API DSP_STATUS	CHNL_freeBuffer (IN ProcessorId procId, IN ChannelId chnlId, IN Char8 **bufArray, IN Uint32 numBufs)
	Frees buffer(s) allocated by CHNL_allocateBuffer.
EXPORT_API DSP_STATUS	CHNL_issue (IN ProcessorId procId, IN ChannelId chnlId, IN ChannelIOInfo *ioReq)
	Issues an input or output request on a specified channel.
EXPORT_API DSP_STATUS	CHNL_reclaim (IN ProcessorId procId, IN ChannelId chnlId, IN Uint32 timeout, IN OUT ChannelIOInfo *ioReq)
	Gets the buffer back that has been issued to this channel. This call blocks for specified timeout value ranging from NO_WAIT to WAIT_FOREVER.
EXPORT_API DSP_STATUS	CHNL_idle (IN ProcessorId procId, IN ChannelId chnlId)
	In the input mode channel, this function resets the channel and causes any currently buffered input data to be discarded.
EXPORT_API DSP_STATUS	CHNL_flush (IN ProcessorId procId, IN ChannelId chnlId)
	Discards all the requested buffers that are pending for transfer both in case of input mode channel as well as output mode channel. One must still have to call the CHNL_reclaim to get back the discarded buffers.
EXPORT_API DSP_STATUS	CHNL_control (IN ProcessorId procId, IN ChannelId chnlId, IN Int32 cmd, Pvoid arg)
	Provides a hook to perform device dependent control operations on channels.

Define Documentation

#define CHNL_Create CHNL_create

============================================================================

Deprecated:: The deprecated API CHNL_Create has been replaced with CHNL_create. This has been done to follow DSP/BIOS coding guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

============================================================================

#define CHNL_Delete CHNL_delete

============================================================================

Deprecated:: The deprecated API CHNL_Delete has been replaced with CHNL_delete. This has been done to follow DSP/BIOS coding guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

============================================================================

#define CHNL_AllocateBuffer CHNL_allocateBuffer

============================================================================

Deprecated:: The deprecated API CHNL_AllocateBuffer has been replaced with CHNL_allocateBuffer. This has been done to follow DSP/BIOS coding guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

============================================================================

#define CHNL_FreeBuffer CHNL_freeBuffer

============================================================================

Deprecated:: The deprecated API CHNL_FreeBuffer has been replaced with CHNL_freeBuffer. This has been done to follow DSP/BIOS coding guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

============================================================================

#define CHNL_Issue CHNL_issue

============================================================================

Deprecated:: The deprecated API CHNL_Issue has been replaced with CHNL_issue. This has been done to follow DSP/BIOS coding guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

============================================================================

#define CHNL_Reclaim CHNL_reclaim

============================================================================

Deprecated:: The deprecated API CHNL_Reclaim has been replaced with CHNL_reclaim. This has been done to follow DSP/BIOS coding guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

============================================================================

#define CHNL_Idle CHNL_idle

============================================================================

Deprecated:: The deprecated API CHNL_Idle has been replaced with CHNL_idle. This has been done to follow DSP/BIOS coding guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

============================================================================

#define CHNL_Flush CHNL_flush

============================================================================

Deprecated:: The deprecated API CHNL_Flush has been replaced with CHNL_flush. This has been done to follow DSP/BIOS coding guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

============================================================================

#define CHNL_Control CHNL_control

============================================================================

Deprecated:: The deprecated API CHNL_Control has been replaced with CHNL_control. This has been done to follow DSP/BIOS coding guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

============================================================================

Function Documentation

EXPORT_API DSP_STATUS CHNL_create	(	IN ProcessorId	procId,
		IN ChannelId	chnlId,
		IN ChannelAttrs *	attrs
	)

Creates resources used for transferring data between GPP and DSP.

============================================================================

Function:: CHNL_create

Parameters:

procId	Processor Identifier.
chnlId	Channel Id to open.
attrs	Channel attributes - if NULL, default attributes are applied.

Returns:: DSP_SOK Operation successfully completed. DSP_EFAIL General failure. DSP_EMEMORY Operation failed due to memory error. DSP_EINVALIDARG Invalid Parameter passed.

Precondition:: Channels for specified processors must be initialized. Processor and channel ids must be valid. Attributes must be valid. PROC_load has been successful. POOL_open i.e. POOL configuration has been successful.

Postcondition:: None

See also:: None ============================================================================

EXPORT_API DSP_STATUS CHNL_delete	(	IN ProcessorId	procId,
		IN ChannelId	chnlId
	)

Releases channel resources used for transferring data between GPP and DSP.

============================================================================

Function:: CHNL_delete

Parameters:

procId	Processor Identifier.
chnlId	Channel Identifier.

Returns:: DSP_SOK Operation successfully completed. DSP_EFAIL General failure. DSP_EMEMORY Operation failed due to memory error. DSP_EINVALIDARG Invalid Parameter passed.

Precondition:: Channels for specified processors should have been initialized. Processor and channel ids should be valid. All CHNL operations are complete.

Postcondition:: None

See also:: CHNL_create ============================================================================

EXPORT_API DSP_STATUS CHNL_allocateBuffer	(	IN ProcessorId	procId,
		IN ChannelId	chnlId,
		OUT Char8 **	bufArray,
		IN Uint32	size,
		IN Uint32	numBufs
	)

Allocates an array of buffers of specified size and returns them to the client.

============================================================================

Function:: CHNL_allocateBuffer

Parameters:

procId	Processor Identifier.
chnlId	Channel Identifier.
size	Size of each buffer.
bufArray	Pointer to receive array of allocated buffers.
numBufs	Number of buffers to allocate.

Returns:: DSP_SOK Operation successfully completed. DSP_EFAIL General failure. DSP_EMEMORY Operation failed due to memory error. DSP_EINVALIDARG Invalid parameter passed.

Precondition:: Channels for specified processors must be initialized. Processor and channel ids must be valid. bufArray must be valid. size must not be zero. numBufs must be less than/equal to MAX_ALLOC_BUFFERS. CHNL_create has been successful. POOL_open i.e. POOL configuration has been successful.

Postcondition:: None

See also:: CHNL_create, CHNL_freeBuffer ============================================================================

EXPORT_API DSP_STATUS CHNL_freeBuffer	(	IN ProcessorId	procId,
		IN ChannelId	chnlId,
		IN Char8 **	bufArray,
		IN Uint32	numBufs
	)

Frees buffer(s) allocated by CHNL_allocateBuffer.

============================================================================

Function:: CHNL_freeBuffer

Parameters:

procId	Processor Identifier.
chnlId	Channel Identifier.
bufArray	Pointer to the array of buffers to freed.
numBufs	Number of buffers to be freed.

Returns:: DSP_SOK Operation successfully completed. DSP_EFAIL General failure. DSP_EMEMORY Operation failed due to memory error. DSP_EINVALIDARG Invalid parameter passed.

Precondition:: Channels for specified processors must be initialized. Processor and channel ids must be valid. bufArray must be valid. numBufs must be less than/equal to MAX_ALLOC_BUFFERS. All data transfer to DSP using CHNL is complete.

Postcondition:: None

See also:: CHNL_create, CHNL_allocateBuffer ============================================================================

EXPORT_API DSP_STATUS CHNL_issue	(	IN ProcessorId	procId,
		IN ChannelId	chnlId,
		IN ChannelIOInfo *	ioReq
	)

Issues an input or output request on a specified channel.

============================================================================

Function:: CHNL_issue

Parameters:

procId	Processor Identifier.
chnlId	Channel Identifier.
ioReq	Information regarding IO.

Returns:: DSP_SOK Operation successfully completed. DSP_EFAIL General failure. DSP_EMEMORY Operation failed due to memory error. DSP_EINVALIDARG Invalid parameter passed.

Precondition:: Channels for specified processors must be initialized. Processor and channel ids must be valid. ioReq must be valid. CHNL_create, CHNL_allocateBuffer has been successful. Corresponding data stream on dsp side has been created. Data buffer is prime'd for data transfer

Postcondition:: Corresponding data reclaim on gpp/dsp side is done.

See also:: CHNL_reclaim ============================================================================

EXPORT_API DSP_STATUS CHNL_reclaim	(	IN ProcessorId	procId,
		IN ChannelId	chnlId,
		IN Uint32	timeout,
		IN OUT ChannelIOInfo *	ioReq
	)

Gets the buffer back that has been issued to this channel. This call blocks for specified timeout value ranging from NO_WAIT to WAIT_FOREVER.

============================================================================

Function:: CHNL_reclaim

Parameters:

procId	Processor Identifier.
chnlId	Channel Identifier.
timeout	Timeout value for this operation. Unit of timeout is OS dependent.
ioReq	Information needed for doing reclaim.

Returns:: DSP_SOK Operation successfully completed. DSP_EFAIL General failure. DSP_EMEMORY Operation failed due to memory error. DSP_EINVALIDARG Invalid parameter passed. CHNL_E_NOIOC Timeout parameter was "NO_WAIT", yet no I/O completions were queued.

Precondition:: Channels for specified processors must be initialized. Processor and channel ids must be valid. CCHNL_issue has been successful.

Postcondition:: None

See also:: CHNL_issue ============================================================================

EXPORT_API DSP_STATUS CHNL_idle	(	IN ProcessorId	procId,
		IN ChannelId	chnlId
	)

In the input mode channel, this function resets the channel and causes any currently buffered input data to be discarded.

============================================================================

Function:: CHNL_idle

In the output mode channel, this function causes any currently queued buffers to be transferred through the channel. It causes the client to wait for as long as it takes for the data to be transferred through the channel.

Parameters:

procId	Processor Identifier.
chnlId	Channel Identifier.

Returns:: DSP_SOK Operation successfully completed. DSP_EFAIL General failure. DSP_EMEMORY Operation failed due to memory error. DSP_EINVALIDARG Invalid parameter passed.

Precondition:: Channels for specified processor must be initialized. Processor and channel ids must be valid. CHNL_create, CHNL_allocateBuffer, CHNL_open has been successful.

Postcondition:: None

See also:: CHNL_create ============================================================================

EXPORT_API DSP_STATUS CHNL_flush	(	IN ProcessorId	procId,
		IN ChannelId	chnlId
	)

Discards all the requested buffers that are pending for transfer both in case of input mode channel as well as output mode channel. One must still have to call the CHNL_reclaim to get back the discarded buffers.

============================================================================

Function:: CHNL_flush

Parameters:

procId	Processor Identifier.
chnlId	Channel Identifier.

Returns:: DSP_SOK Operation successfully completed. DSP_EFAIL General failure. DSP_EMEMORY Operation failed due to memory error. DSP_EINVALIDARG Invalid parameter passed.

Precondition:: Channels for specified processor must be initialized. Processor and channel ids must be valid. CHNL_issue has been successful.

Postcondition:: None

See also:: CHNL_create, CHNL_issue ============================================================================

EXPORT_API DSP_STATUS CHNL_control	(	IN ProcessorId	procId,
		IN ChannelId	chnlId,
		IN Int32	cmd,
		Pvoid	arg
	)

Provides a hook to perform device dependent control operations on channels.

============================================================================

Function:: CHNL_control

Parameters:

procId	Processor Identifier.
chnlId	Channel Identifier.
cmd	Command id.
arg	Optional argument for the specified command.

Returns:: DSP_SOK Operation successfully completed. DSP_EFAIL General failure. DSP_EMEMORY Operation failed due to memory error. DSP_EINVALIDARG Invalid parameter passed.

Precondition:: Channels for specified processor must be initialized. Processor and channel ids must be valid. CHNL_create, CHNL_allocateBuffer has been successful.

Postcondition:: None

See also:: None ============================================================================

chnl.h File Reference

Detailed Description

Defines

Functions

Define Documentation

Function Documentation