Detailed Description

Ipc Manager.

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

This module is primarily used to configure IPC, synchronize processors, and initialize the IPC runtime. The memory for SharedRegion zero must be valid before Ipc_start() can be called. Ipc_start() must be called before any other IPC APIs are used.

The Ipc header should be included in an application as follows:

  #include <ti/ipc/Ipc.h>

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

Go to the source code of this file.

Defines
#define	Ipc_S_BUSY 2
	The resource is still in use.
#define	Ipc_S_ALREADYSETUP 1
	The module has been already setup.
#define	Ipc_S_SUCCESS 0
	Operation is successful.
#define	Ipc_E_FAIL -1
	Generic failure.
#define	Ipc_E_INVALIDARG -2
	Argument passed to function is invalid.
#define	Ipc_E_MEMORY -3
	Operation resulted in memory failure.
#define	Ipc_E_ALREADYEXISTS -4
	The specified entity already exists.
#define	Ipc_E_NOTFOUND -5
	Unable to find the specified entity.
#define	Ipc_E_TIMEOUT -6
	Operation timed out.
#define	Ipc_E_INVALIDSTATE -7
	Module is not initialized or in an invalid state.
#define	Ipc_E_OSFAILURE -8
	A failure occurred in an OS-specific call.
#define	Ipc_E_RESOURCE -9
	Specified resource is not available.
#define	Ipc_E_RESTART -10
	Operation was interrupted. Please restart the operation.
#define	Ipc_E_NOTREADY -11
	Operation was not ready.
Functions
Int	Ipc_attach (UInt16 remoteProcId)
	Attach to remote processor.
Int	Ipc_detach (UInt16 remoteProcId)
	Detach from the remote processor.
Bool	Ipc_isAttached (UInt16 remoteProcId)
	Query whether attached to a remote processor.
Int	Ipc_readConfig (UInt16 remoteProcId, UInt32 tag, Ptr cfg, SizeT size)
	Reads the config entry from the config area.
Int	Ipc_start (Void)
	Reserves memory, creates default GateMP and HeapMemMP.
Int	Ipc_stop (Void)
	Resets the Ipc state.
Int	Ipc_writeConfig (UInt16 remoteProcId, UInt32 tag, Ptr cfg, SizeT size)
	Writes the config entry to the config area.

Define Documentation

#define Ipc_S_BUSY 2

The resource is still in use.

#define Ipc_S_ALREADYSETUP 1

The module has been already setup.

#define Ipc_S_SUCCESS 0

Operation is successful.

#define Ipc_E_FAIL -1

Generic failure.

#define Ipc_E_INVALIDARG -2

Argument passed to function is invalid.

#define Ipc_E_MEMORY -3

Operation resulted in memory failure.

#define Ipc_E_ALREADYEXISTS -4

The specified entity already exists.

#define Ipc_E_NOTFOUND -5

Unable to find the specified entity.

#define Ipc_E_TIMEOUT -6

Operation timed out.

#define Ipc_E_INVALIDSTATE -7

Module is not initialized or in an invalid state.

#define Ipc_E_OSFAILURE -8

A failure occurred in an OS-specific call.

#define Ipc_E_RESOURCE -9

Specified resource is not available.

#define Ipc_E_RESTART -10

Operation was interrupted. Please restart the operation.

#define Ipc_E_NOTREADY -11

Operation was not ready.

Function Documentation

Int Ipc_attach ( UInt16 remoteProcId )

Attach to remote processor.

This function uses shared memory to synchronize self with the remote processor. Both processors must call this function to attach to each other. Ipc_start() must be called before calling Ipc_attach(). A processor must attach to the owner of SharedRegion zero before it can successfully attach to another processor. Attempting to attach to another processor first returns Ipc_E_FAIL.

This function opens the default GateMP and SharedRegion zero heap. The Notify, NameServerRemoteNotify, and MessageQ transport instances are created for communicating with the specified remote processor in SharedRegion zero heap. The user's Ipc attach function is called.

For BIOS, this function should be called within a 'while' loop within a Task. A Task_sleep() or Task_yield() should be called within the loop to allow other threads in the system to execute. This function needs to be called in a loop because the remote processor may not be in a ready state.

Note: For BIOS, if the config parameter Ipc.procSync is set to Ipc.ProcSync_ALL, there is no need to call this function as it is internally called by Ipc_start().

  while (Ipc_attach(remoteProcId) < 0) {
      Task_sleep(1);
  }

Parameters:

remoteProcId remote processor's MultiProc id

Returns:

Status

Ipc_S_SUCCESS: attach was successful
Ipc_S_ALREADYSETUP: already attached
Ipc_E_MEMORY: operation failed due to a memory error
Ipc_E_FAIL: General failure
Ipc_E_NOTREADY: remote processor not ready

See also:: Ipc_detach Ipc_isAttached

Int Ipc_detach ( UInt16 remoteProcId )

Detach from the remote processor.

A processor must detach from all other processors before it can successfully detach from the owner of SharedRegion zero. Attempting to detach from the owner of SharedRegion zero first returns Ipc_E_FAIL.

If a processor successfully attached to a remote processor 'N' times, it must call Ipc_detach 'N' times to be completely detached. Ipc_detach returns Ipc_S_BUSY for the first 'N - 1' times its called. Ipc_detach returns Ipc_S_SUCCESS, if successful, on the 'N' time its called. If called on a remote processor that is detached, Ipc_S_SUCCESS is returned.

This function should be called within a loop to make sure the processor successfully detached from the remote processor. If called from the processor with the bigger procId, this function closes the instances created for communicating with the specified remote processor. If called from the processor with the smaller procId, this function returns Ipc_E_NOTREADY while the processor with the bigger procId has not finished detaching. Once the processor with the bigger procId is finished detaching, this function deletes the instances created for communicating with the specified remote processor.

For BIOS, this function should be called within a 'while' loop in a Task because the slave may have to wait for the master to detach. Furthermore, a Task_sleep() or Task_yield() should be called within the same 'while' loop to allow other threads in the system to execute.

  while (TRUE) {
      status = Ipc_detach(remoteProcId);
      if (status == Ipc_E_NOTREADY) {
          Task_sleep(1);
      }
      else if (status < 0) {
          System_printf("Ipc_detach failed \n");
          break;
      }
      else {
          break;
      }
  }

Parameters:

remoteProcId remote processor's MultiProc id

Returns:

Status

Ipc_S_SUCCESS: operation was successful
Ipc_S_BUSY: attach count != 0
Ipc_E_FAIL: operation failed
Ipc_E_NOTREADY: processor not ready to detach

See also:: Ipc_attach Ipc_isAttached

Bool Ipc_isAttached ( UInt16 remoteProcId )

Query whether attached to a remote processor.

Returns TRUE if attached to a remote processor and FALSE otherwise. If remoteProcId == MultiProc_self(), FALSE is always returned.

Parameters:

remoteProcId remote processor's MultiProc id

Returns:: TRUE if attached, FALSE if not attached

See also:: Ipc_attach Ipc_detach

Int Ipc_readConfig	(	UInt16	remoteProcId,
		UInt32	tag,
		Ptr	cfg,
		SizeT	size
	)

Reads the config entry from the config area.

For more information about this API, refer to the documentation for Ipc_writeConfig

Parameters:

remoteProcId	remote processor's MultiProc id
tag	tag to identify a config entry
cfg	address where the entry will be copied
size	size of config entry

Returns:

Status

Ipc_S_SUCCESS: operation was successful
Ipc_E_FAIL: operation failed

See also:: Ipc_writeConfig

Int Ipc_start ( Void )

Reserves memory, creates default GateMP and HeapMemMP.

This function needs to be called before Ipc_attach(). It should only be called once, unless the return value is Ipc_E_NOTREADY. This indicates that either the SharedRegion zero is not valid or has not been setup yet so Ipc_start may be called again. Once sucessfully started, subsequent calls returns Ipc_S_ALREADYSETUP.

Ipc reserves some shared memory in SharedRegion zero for synchronization. GateMP reserves some shared memory for managing the gates and for the default GateMP. The same amount of memory must be reserved by each processor, but only the owner of SharedRegion zero clears the reserved memory and creates the default GateMP. The default heap for each SharedRegion is created by the owner of each SharedRegion.

Note: For BIOS, if the config parameter Ipc.procSync is set to Ipc.ProcSync_ALL, this function calls Ipc_attach() internally.

Returns:

Status

Ipc_S_SUCCESS: operation was successful
Ipc_S_ALREADYSETUP: already successfully called
Ipc_E_NOTREADY: shared memory is not ready
Ipc_E_FAIL: operation failed

Int Ipc_stop ( Void )

Resets the Ipc state.

This function should be called only once and only after detaching from all processors. Once called, Ipc is placed back to the same state as it was before Ipc_start() was called.

Returns:

Status

Ipc_S_SUCCESS: operation was successful

Int Ipc_writeConfig	(	UInt16	remoteProcId,
		UInt32	tag,
		Ptr	cfg,
		SizeT	size
	)

Writes the config entry to the config area.

The Ipc_writeConfig and Ipc_readConfig APIs are used to pass configuration information from one core to another. This 'information' is passed via a pointer to shared memory with a given size and is identified via a unique tag. A typical use case of this API would be passing configuration information from a Slave core to the Host at startup-time. For example, if MessageQ is used, this information might include the queue name, message heap sizes, etc.

The APIs will write into SharedRegion 0 (SR0) and will use the tag to uniquely identify the structure (cfg) and size written into SR0 which both sides must agree on.

Parameters:

remoteProcId	remote processor's MultiProc id
tag	tag to identify a config entry
cfg	address where the entry will be copied
size	size of config entry

Returns:

Status

Ipc_S_SUCCESS: if operation was successful
Ipc_E_FAIL: if operation failed

See also:: Ipc_readConfig

Ipc.h File Reference

Detailed Description

Defines

Functions

Define Documentation

Function Documentation