proc.h File Reference

---

Detailed Description

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

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

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 <procdefs.h>
#include <linkcfgdefs.h>

Include dependency graph for proc.h:

Go to the source code of this file.

Defines
#define	PROC_Destroy   PROC_destroy
#define	PROC_Attach   PROC_attach
#define	PROC_Detach   PROC_detach
#define	PROC_GetState   PROC_getState
#define	PROC_Load   PROC_load
#define	PROC_LoadSection   PROC_loadSection
#define	PROC_Read   PROC_read
#define	PROC_Write   PROC_write
#define	PROC_Start   PROC_start
#define	PROC_Stop   PROC_stop
#define	PROC_Control   PROC_control
Functions
DLLEXPORT DSP_STATUS	PROC_setup (IN LINKCFG_Object *linkCfg)
	Sets up the necessary data structures for the PROC sub-component.
DLLEXPORT DSP_STATUS	PROC_destroy (void)
	Destroys the data structures for the PROC component, allocated earlier by a call to PROC_setup ().
DLLEXPORT DSP_STATUS	PROC_attach (IN ProcessorId procId, PROC_Attrs *attr)
	Attaches the client to the specified DSP and also initializes the DSP (if required).
DLLEXPORT DSP_STATUS	PROC_detach (IN ProcessorId procId)
	Detaches the client from specified processor. If the caller is the owner of the processor, this function releases all the resources that this component uses and puts the DSP in an unusable state (from application perspective).
DLLEXPORT DSP_STATUS	PROC_getState (IN ProcessorId procId, OUT PROC_State *procState)
	Gets the current status of DSP by querying the Link Driver.
DLLEXPORT DSP_STATUS	PROC_load (IN ProcessorId procId, IN Char8 *imagePath, IN Uint32 argc, IN Char8 **argv)
	Loads the specified DSP executable on the target DSP. It ensures that the caller owns the DSP.
DLLEXPORT DSP_STATUS	PROC_loadSection (IN ProcessorId procId, IN Char8 *imagePath, IN Uint32 sectID)
	Loads the specified section of DSP executable onto the target DSP. It ensures that the client owns the DSP.
DLLEXPORT DSP_STATUS	PROC_read (IN ProcessorId procId, IN Uint32 dspAddr, IN Uint32 numBytes, IN OUT Pvoid buffer)
	This function allows GPP side applications to read from the DSP memory space.
DLLEXPORT DSP_STATUS	PROC_write (IN ProcessorId procId, IN Uint32 dspAddr, IN Uint32 numBytes, IN Pvoid buffer)
	This function allows GPP side applications to write to the DSP memory space.
DLLEXPORT DSP_STATUS	PROC_start (IN ProcessorId procId)
	Starts execution of the loaded code on DSP from the starting point specified in the DSP executable loaded earlier by call to PROC_load ().
DLLEXPORT DSP_STATUS	PROC_stop (IN ProcessorId procId)
	Stops the DSP.
DLLEXPORT DSP_STATUS	PROC_control (IN ProcessorId procId, IN Int32 cmd, Pvoid arg)
	Provides a hook to perform device dependent control operations on the DSP.
DLLEXPORT DSP_STATUS	PROC_GetSymbolAddress (IN ProcessorId procId, IN Char8 *symbolName, OUT Uint32 *dspAddr)
	Gets the DSP address corresponding to a symbol within a DSP executable currently loaded on the DSP.
DLLEXPORT DSP_STATUS	PROC_Setup (void)

---

Define Documentation

#define PROC_Destroy   PROC_destroy

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

Deprecated:

The deprecated API PROC_Destroy has been replaced with PROC_destroy. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

#define PROC_Attach   PROC_attach

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

Deprecated:

The deprecated API PROC_Attach has been replaced with PROC_attach. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

#define PROC_Detach   PROC_detach

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

Deprecated:

The deprecated API PROC_Detach has been replaced with PROC_detach. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

#define PROC_GetState   PROC_getState

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

Deprecated:

The deprecated API PROC_GetState has been replaced with PROC_getState. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

#define PROC_Load   PROC_load

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

Deprecated:

The deprecated API PROC_Load has been replaced with PROC_load. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

#define PROC_LoadSection   PROC_loadSection

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

Deprecated:

The deprecated API PROC_LoadSection has been replaced with PROC_loadSection. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

#define PROC_Read   PROC_read

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

Deprecated:

The deprecated API PROC_Read has been replaced with PROC_read. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

#define PROC_Write   PROC_write

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

Deprecated:

The deprecated API PROC_Write has been replaced with PROC_write. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

#define PROC_Start   PROC_start

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

Deprecated:

The deprecated API PROC_Start has been replaced with PROC_start. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

#define PROC_Stop   PROC_stop

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

Deprecated:

The deprecated API PROC_Stop has been replaced with PROC_stop. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

#define PROC_Control   PROC_control

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

Deprecated:

The deprecated API PROC_Control has been replaced with PROC_control. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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

---

Function Documentation

DLLEXPORT DSP_STATUS PROC_setup

(

IN LINKCFG_Object *

linkCfg )

Sets up the necessary data structures for the PROC sub-component.

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

Function:

PROC_setup

Parameters:

linkCfg

Pointer to the configuration information structure for DSP/BIOS LINK. If NULL, indicates that default configuration should be used.

Returns:

DSP_SOK Operation successfully completed. DSP_SALREADYSETUP The DSPLink driver is already setup in this process. DSP_ECONFIG Error in specified dynamic configuration. Please check CFG_<PLATFORM>.c DSP_EMEMORY Operation failed due to memory error. DSP_EFAIL General failure.

Precondition:

The configuration information structure has been updated with application specific information. If no configuration is specified the default configuration will be used.

Postcondition:

None

See also:

PROC_destroy ============================================================================

DLLEXPORT DSP_STATUS PROC_destroy

(

void

)

Destroys the data structures for the PROC component, allocated earlier by a call to PROC_setup ().

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

Function:

PROC_destroy

Parameters:

None

Returns:

DSP_SOK Operation successfully completed. DSP_SDESTROYED The final client has finalized the driver. DSP_EACCESSDENIED The DSPLink driver was not setup in this process. DSP_ESETUP The DSPLink driver was not setup. DSP_EMEMORY Operation failed due to memory error. DSP_EFAIL General failure.

Precondition:

All DSP/BIOS Link operations are complete.

Postcondition:

None

See also:

PROC_setup ============================================================================

DLLEXPORT DSP_STATUS PROC_attach	(	IN ProcessorId	procId,
		PROC_Attrs *	attr
	)

Attaches the client to the specified DSP and also initializes the DSP (if required).

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

Function:

PROC_attach

Parameters:

procId	DSP identifier.
attr	Attributes for the processor on which attach is to be done.

Returns:

DSP_SOK Operation successfully completed. DSP_SALREADYATTACHED Successful attach. Also, indicates that another client has already attached to DSP. DSP_EINVALIDARG Parameter ProcId is invalid. DSP_EACCESSDENIED Not allowed to access the DSP. DSP_EALREADYCONNECTED Another thread of the same process has already attached to the processor. DSP_EWRONGSTATE Incorrect state for completing the requested operation. DSP_EFAIL General failure, unable to attach to processor.

Precondition:

procId must be valid. PROC_setup has been successful.

Postcondition:

None

See also:

PROC_detach ============================================================================

DLLEXPORT DSP_STATUS PROC_detach

(

IN ProcessorId

procId )

Detaches the client from specified processor. If the caller is the owner of the processor, this function releases all the resources that this component uses and puts the DSP in an unusable state (from application perspective).

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

Function:

PROC_detach

Parameters:

procId

DSP identifier.

Returns:

DSP_SOK Operation successfully completed. DSP_SDETACHED The final process has detached from the specific processor. DSP_EINVALIDARG Invalid ProcId parameter. DSP_ESETUP The DSPLink driver was not setup. DSP_EACCESSDENIED Not allowed to access the DSP. DSP_EATTACHED Not attached to the target processor. DSP_EWRONGSTATE Incorrect state for completing the requested operation. DSP_EFAIL General failure, unable to detach.

Precondition:

procId must be valid. All DSP/BIOS Link operations are complete.

Postcondition:

None

See also:

PROC_attach ============================================================================

DLLEXPORT DSP_STATUS PROC_getState	(	IN ProcessorId	procId,
		OUT PROC_State *	procState
	)

Gets the current status of DSP by querying the Link Driver.

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

Function:

PROC_getState

Parameters:

procId	DSP identifier.
procState	Placeholder for processor state.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid ProcId and/or procState argument.

Precondition:

procId must be valid. procState must be a valid pointer.

Postcondition:

None

See also:

PROC_load, PROC_start, PROC_stop, PROC_Idle ============================================================================

DLLEXPORT DSP_STATUS PROC_load	(	IN ProcessorId	procId,
		IN Char8 *	imagePath,
		IN Uint32	argc,
		IN Char8 **	argv
	)

Loads the specified DSP executable on the target DSP. It ensures that the caller owns the DSP.

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

Function:

PROC_load

Parameters:

procId	DSP identifier.
imagePath	Full path to the image file to load on DSP.
argc	Number of argument to be passed to the base image upon start.
argv	Arguments to be passed to DSP main application.

Returns:

DSP_SOK Operation successfully completed. DSP_SALREADYLOADED The specified processor has already been loaded. DSP_EINVALIDARG Invalid ProcId argument. DSP_EACCESSDENIED Not allowed to access the DSP. DSP_ESETUP The DSPLink driver has not been setup. DSP_EATTACHED This process has not attached to the specified processor. DSP_EPENDING H/W specific error. The request can’t be serviced at this point of time. DSP_EFILE Invalid base image. DSP_ESIZE Size of the .args section is not sufficient to hold the passed arguments. DSP_EFAIL General failure, unable to load image on DSP. DSP_EWRONGSTATE Incorrect state for completing the requested operation.

Precondition:

procId must be valid. imagePath must be a valid pointer. If argc is 0 then argv must be NULL pointer. If argc is non-zero then argv must be a valid pointer. PROC_setup and PROC_attach have been successful.

Postcondition:

None

See also:

PROC_attach, PROC_loadSection ============================================================================

DLLEXPORT DSP_STATUS PROC_loadSection	(	IN ProcessorId	procId,
		IN Char8 *	imagePath,
		IN Uint32	sectID
	)

Loads the specified section of DSP executable onto the target DSP. It ensures that the client owns the DSP.

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

Function:

PROC_loadSection

Parameters:

procId	DSP identifier.
imagePath	Full path to the image file.
sectID	Section ID of section to load.

Returns:

DSP_SOK Operation successfully completed. DSP_EINVALIDARG Invalid ProcId argument. DSP_EPENDING H/W specific error. The request can’t be serviced at this point of time. DSP_EFILE Invalid ImagePath parameter. DSP_EINVALIDSECTION Invalid section name. DSP_EACCESSDENIED Not allowed to access the DSP. DSP_EFAIL General failure, unable to load section on DSP. DSP_EWRONGSTATE Incorrect state for completing the requested operation.

Precondition:

procId must be valid. imagePath must be a valid pointer. PROC_attach has been successful.

Postcondition:

None

See also:

PROC_attach, PROC_load ============================================================================

DLLEXPORT DSP_STATUS PROC_read	(	IN ProcessorId	procId,
		IN Uint32	dspAddr,
		IN Uint32	numBytes,
		IN OUT Pvoid	buffer
	)

This function allows GPP side applications to read from the DSP memory space.

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

Function:

PROC_read

Parameters:

procId	Processor ID of the target DSP.
dspAddr	Address of the DSP memory region from where to read.
numBytes	Number of bytes to be read
buffer	User specified buffer to contain the data from DSP memory space

Returns:

DSP_SOK Operation successfully completed. DSP_EPENDING H/W specific error. The request can’t be serviced at this point of time. DSP_EINVALIDARG Invalid argument. DSP_EFAIL General failure, unable to load section on DSP.

Precondition:

procId must be valid. buffer must be valid. PROC_attach has been successful. For DM642, the memory region must be mapped to GPP address space.

Postcondition:

None

See also:

PROC_write ============================================================================

DLLEXPORT DSP_STATUS PROC_write	(	IN ProcessorId	procId,
		IN Uint32	dspAddr,
		IN Uint32	numBytes,
		IN Pvoid	buffer
	)

This function allows GPP side applications to write to the DSP memory space.

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

Function:

PROC_write

Parameters:

procId	Processor ID of the target DSP.
dspAddr	Address of the DSP memory region from where the data is to be written to.
numBytes	Number of bytes to be written
buffer	User specified buffer with data to be written into DSP memory space

Returns:

DSP_SOK Operation successfully completed. DSP_EPENDING H/W specific error. The request can’t be serviced at this point of time. DSP_EINVALIDARG Invalid argument. DSP_EFAIL General failure, unable to load section on DSP.

Precondition:

procId must be valid. buffer must be valid. PROC_attach has been successful. For DM642, the memory region must be mapped to GPP address space.

Postcondition:

None

See also:

PROC_read ============================================================================

DLLEXPORT DSP_STATUS PROC_start

(

IN ProcessorId

procId )

Starts execution of the loaded code on DSP from the starting point specified in the DSP executable loaded earlier by call to PROC_load ().

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

Function:

PROC_start

Parameters:

procId

DSP Identifier.

Returns:

DSP_SOK Operation successfully completed. DSP_SALREADYSTARTED The specified processor has already been started. DSP_EINVALIDARG Invalid ProcId argument. DSP_EPENDING H/W specific error. The request can’t be serviced at this point of time. DSP_EACCESSDENIED Not allowed to access the DSP. DSP_ESETUP The DSPLink driver has not been setup. DSP_EATTACHED This process has not attached to the specified processor. DSP_EALREADYSTARTED The specified processor has already been started in this process DSP_EWRONGSTATE Incorrect state for completing the requested operation. DSP_ECONFIG The specified processor could not be started. Driver handshake failed due to DSP driver initialization/configuration failure. DSP_EFAIL General failure, unable to start DSP.

Precondition:

procId must be valid. PROC_attach has been successful. If the application uses POOL, POOL_open i.e POOL configuration has been successful. All setup and initialization needed for DSP to start execution has been done.

Postcondition:

None

See also:

PROC_attach, PROC_load, PROC_stop ============================================================================

DLLEXPORT DSP_STATUS PROC_stop

(

IN ProcessorId

procId )

Stops the DSP.

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

Function:

PROC_stop

Parameters:

procId

DSP Identifier.

Returns:

DSP_SOK Operation successfully completed. DSP_SSTOPPED The final process has stopped the DSP execution. DSP_EINVALIDARG Invalid ProcId argument. DSP_EACCESSDENIED Not allowed to access the DSP. DSP_ESETUP The DSPLink driver has not been setup. DSP_EATTACHED This process has not attached to the specified processor. DSP_ESTARTED The specified processor has not been started. DSP_EWRONGSTATE Incorrect state for completing the requested operation. DSP_EFAIL General failure, unable to stop DSP.

Precondition:

procId must be valid. All DSP/BIOS Link operations are complete.

Postcondition:

None

See also:

PROC_attach, PROC_load, PROC_start ============================================================================

DLLEXPORT DSP_STATUS PROC_control	(	IN ProcessorId	procId,
		IN Int32	cmd,
		Pvoid	arg
	)

Provides a hook to perform device dependent control operations on the DSP.

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

Function:

PROC_control

Parameters:

procId	DSP Identifier.
cmd	Command id.
arg	Optional argument for the specified command.

Returns:

DSP_SOK Operation successfully completed. DSP_EFAIL General failure.

Precondition:

procId must be valid. PROC_attach has been successful.

Postcondition:

None

See also:

PROC_attach ============================================================================

DLLEXPORT DSP_STATUS PROC_GetSymbolAddress	(	IN ProcessorId	procId,
		IN Char8 *	symbolName,
		OUT Uint32 *	dspAddr
	)

Gets the DSP address corresponding to a symbol within a DSP executable currently loaded on the DSP.

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

Function:

PROC_GetSymbolAddress

Parameters:

procId	DSP Identifier.
symbolName	name of the symbol.
dspAddr	pointer to get the dsp address corresponding to symbolName.

Modifies:

None ============================================================================

DLLEXPORT DSP_STATUS PROC_Setup

(

void

)

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

Deprecated:

The deprecated API POOL_TranslateAddr has been replaced with POOL_translateAddr. This has been done to follow DSP/BIOS codinf guidelines and have a uniform naming convention for the API's on both GPP as well as DSP.

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