Main Page   Modules   Alphabetical List   Data Structures   File List   Data Fields   Globals  

IXP425 NPE Message Handler (IxNpeMh) API

The public API for the IXP425 NPE Message Handler component. More...

Data Structures

struct  IxNpeMhMessage
 The 2-word message structure to send to and receive from the NPEs. More...


Defines

#define IX_NPEMH_MIN_MESSAGE_ID
 minimum valid message ID

#define IX_NPEMH_MAX_MESSAGE_ID
 maximum valid message ID

#define IX_NPEMH_SEND_RETRIES_DEFAULT
 default msg send retries


Typedefs

typedef UINT32 IxNpeMhMessageId
 message ID

typedef void(* IxNpeMhCallback )(IxNpeMhNpeId, IxNpeMhMessage)
 This prototype shows the format of a message callback function.


Enumerations

enum  IxNpeMhNpeId {
  IX_NPEMH_NPEID_NPEA,
  IX_NPEMH_NPEID_NPEB,
  IX_NPEMH_NPEID_NPEC,
  IX_NPEMH_NUM_NPES
}
 The ID of a particular NPE. More...

enum  IxNpeMhNpeInterrupts {
  IX_NPEMH_NPEINTERRUPTS_NO,
  IX_NPEMH_NPEINTERRUPTS_YES
}
 Indicator specifying whether or not NPE interrupts should drive receiving of messages from the NPEs. More...


Functions

IX_STATUS ixNpeMhInitialize (IxNpeMhNpeInterrupts npeInterrupts)
 This function will initialise the IxNpeMh component.

IX_STATUS ixNpeMhUnload (void)
 This function will uninitialise the IxNpeMh component.

IX_STATUS ixNpeMhUnsolicitedCallbackRegister (IxNpeMhNpeId npeId, IxNpeMhMessageId messageId, IxNpeMhCallback unsolicitedCallback)
 This function will register an unsolicited callback for a particular NPE and message ID.

IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister (IxNpeMhNpeId npeId, IxNpeMhMessageId minMessageId, IxNpeMhMessageId maxMessageId, IxNpeMhCallback unsolicitedCallback)
 This function will register an unsolicited callback for a particular NPE and range of message IDs.

IX_STATUS ixNpeMhMessageSend (IxNpeMhNpeId npeId, IxNpeMhMessage message, UINT32 maxSendRetries)
 This function will send a message to a particular NPE.

IX_STATUS ixNpeMhMessageWithResponseSend (IxNpeMhNpeId npeId, IxNpeMhMessage message, IxNpeMhMessageId solicitedMessageId, IxNpeMhCallback solicitedCallback, UINT32 maxSendRetries)
 This function is equivalent to the ixNpeMhMessageSend() function, but must be used when the message being sent will solicited a response.

IX_STATUS ixNpeMhMessagesReceive (IxNpeMhNpeId npeId)
 This function will receive messages from a particular NPE and pass each message to the client via a solicited callback (for solicited messages) or an unsolicited callback (for unsolicited messages).

IX_STATUS ixNpeMhShow (IxNpeMhNpeId npeId)
 This function will display the current state of the IxNpeMh component.

IX_STATUS ixNpeMhShowReset (IxNpeMhNpeId npeId)
 This function will reset the current state of the IxNpeMh component.


Detailed Description

The public API for the IXP425 NPE Message Handler component.


Define Documentation

#define IX_NPEMH_MAX_MESSAGE_ID
 

maximum valid message ID

Definition at line 68 of file IxNpeMh.h.

#define IX_NPEMH_MIN_MESSAGE_ID
 

minimum valid message ID

Definition at line 67 of file IxNpeMh.h.

#define IX_NPEMH_SEND_RETRIES_DEFAULT
 

default msg send retries

Definition at line 70 of file IxNpeMh.h.


Typedef Documentation

IxNpeMhCallback
 

This prototype shows the format of a message callback function.

This prototype shows the format of a message callback function. The message callback will be passed the message to be handled and will also be told from which NPE the message was received. The message callback will either be registered by ixNpeMhUnsolicitedCallbackRegister() or passed as a parameter to ixNpeMhMessageWithResponseSend(). It will be called from within an ISR triggered by the NPE's "outFIFO not empty" interrupt (see ixNpeMhInitialize()). The parameters passed are the ID of the NPE that the message was received from, and the message to be handled.

Re-entrancy: This function is only a prototype, and will be implemented by the client. It does not need to be re-entrant.

Definition at line 134 of file IxNpeMh.h.

typedef UINT32 IxNpeMhMessageId
 

message ID

Definition at line 115 of file IxNpeMh.h.


Enumeration Type Documentation

enum IxNpeMhNpeId
 

The ID of a particular NPE.

Note:
In this context, for IXP425 Silicon (B0):
  • NPE-A has HDLC, HSS, AAL and UTOPIA Coprocessors.
  • NPE-B has Ethernet Coprocessor.
  • NPE-C has Ethernet, AES, DES and HASH Coprocessors.
  • IXP425 Product Line have different combinations of coprocessors.
Enumeration values:
IX_NPEMH_NPEID_NPEA  ID for NPE-A.
IX_NPEMH_NPEID_NPEB  ID for NPE-B.
IX_NPEMH_NPEID_NPEC  ID for NPE-C.
IX_NPEMH_NUM_NPES  Number of NPEs.

Definition at line 83 of file IxNpeMh.h.

enum IxNpeMhNpeInterrupts
 

Indicator specifying whether or not NPE interrupts should drive receiving of messages from the NPEs.

Enumeration values:
IX_NPEMH_NPEINTERRUPTS_NO  Don't use NPE interrupts.
IX_NPEMH_NPEINTERRUPTS_YES  Do use NPE interrupts.

Definition at line 98 of file IxNpeMh.h.


Function Documentation

IX_STATUS ixNpeMhInitialize IxNpeMhNpeInterrupts  npeInterrupts  ) 
 

This function will initialise the IxNpeMh component.

Parameters:
IxNpeMhNpeInterrupts npeInterrupts (in) - This parameter dictates whether or not the IxNpeMh component will service NPE "outFIFO not empty" interrupts to trigger receiving and processing of messages from the NPEs. If not then the client must use ixNpeMhMessagesReceive() to control message receiving and processing.
This function will initialise the IxNpeMh component. It should only be called once, prior to using the IxNpeMh component. The following actions will be performed by this function:
  1. Initialization of internal data structures (e.g. solicited and unsolicited callback tables).
  2. Configuration of the interface with the NPEs (e.g. enabling of NPE "outFIFO not empty" interrupts).
  3. Registration of ISRs that will receive and handle messages when the NPEs' "outFIFO not empty" interrupts fire (if npeInterrupts equals IX_NPEMH_NPEINTERRUPTS_YES).

Returns:
The function returns a status indicating success or failure.

IX_STATUS ixNpeMhMessageSend IxNpeMhNpeId  npeId,
IxNpeMhMessage  message,
UINT32  maxSendRetries
 

This function will send a message to a particular NPE.

Parameters:
IxNpeMhNpeId npeId (in) - The ID of the NPE to send the message to.
IxNpeMhMessage message (in) - The message to send.
UINT32 maxSendRetries (in) - Max num. of retries to perform if the NPE's inFIFO is full.
This function will send a message to a particular NPE. It will be the client's responsibility to ensure that the message is properly formed. The return status will signify to the client if the message was successfully sent or not.

If the message is sent to the NPE then this function will return a status of success. Note that this will only mean the message has been placed in the NPE's inFIFO. There will be no way of knowing that the NPE has actually read the message, but once in the incoming message queue it will be safe to assume that the NPE will process it.

The inFIFO may fill up sometimes if the Xscale is sending messages faster than the NPE can handle them. This forces us to retry attempts to send the message until the NPE services the inFIFO. The client should specify a ceiling value for the number of retries suitable to their needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for the maxSendRetries parameter for this function. Each retry exceeding this default number will incur a blocking delay of 1 microsecond, to avoid consuming too much AHB bus bandwidth while performing retries.

Note this function must only be used for messages. that do not solicit responses. If the message being sent will solicit a response then the ixNpeMhMessageWithResponseSend() function must be used to ensure that the response is correctly handled.

Re-entrancy: This function will be callable from any thread at any time. IxOsServices will be used for any necessary resource protection.

Returns:
The function returns a status indicating success or failure.

IX_STATUS ixNpeMhMessagesReceive IxNpeMhNpeId  npeId  ) 
 

This function will receive messages from a particular NPE and pass each message to the client via a solicited callback (for solicited messages) or an unsolicited callback (for unsolicited messages).

Parameters:
IxNpeMhNpeId npeId (in) - The ID of the NPE to receive and process messages from.
This function will receive messages from a particular NPE and pass each message to the client via a solicited callback (for solicited messages) or an unsolicited callback (for unsolicited messages).

If the IxNpeMh component is initialised to service NPE "outFIFO not empty" interrupts (see ixNpeMhInitialize()) then there is no need to call this function. This function is only provided as an alternative mechanism to control the receiving and processing of messages from the NPEs.

Note this function cannot be called from within an ISR as it will use resource protection mechanisms.

Re-entrancy: This function will be callable from any thread at any time. IxOsServices will be used for any necessary resource protection.

Returns:
The function returns a status indicating success or failure.

IX_STATUS ixNpeMhMessageWithResponseSend IxNpeMhNpeId  npeId,
IxNpeMhMessage  message,
IxNpeMhMessageId  solicitedMessageId,
IxNpeMhCallback  solicitedCallback,
UINT32  maxSendRetries
 

This function is equivalent to the ixNpeMhMessageSend() function, but must be used when the message being sent will solicited a response.

Parameters:
IxNpeMhNpeId npeId (in) - The ID of the NPE to send the message to.
IxNpeMhMessage message (in) - The message to send.
IxNpeMhMessageId solicitedMessageId (in) - The ID of the solicited response message.
IxNpeMhCallback solicitedCallback (in) - The function to use to pass the response message back to the client. A value of NULL will cause the response message to be discarded.
UINT32 maxSendRetries (in) - Max num. of retries to perform if the NPE's inFIFO is full.
This function is equivalent to the ixNpeMhMessageSend() function, but must be used when the message being sent will solicited a response.

The client must specify the ID of the solicited response message to allow the response to be recognised when it is received. The client must also specify a callback function to handle the received response. The IxNpeMh component will not offer the facility to send a message to a NPE and receive a response within the same context.

Note if the client is not interested in the response, specifying a NULL callback will cause the response message to be discarded.

The solicited callback will be stored and called some time later from an ISR that will be triggered by the NPE's "outFIFO not empty" interrupt (see ixNpeMhInitialize()) to handle the response message corresponding to the message sent. Response messages will be handled in the order they are received.

The inFIFO may fill up sometimes if the Xscale is sending messages faster than the NPE can handle them. This forces us to retry attempts to send the message until the NPE services the inFIFO. The client should specify a ceiling value for the number of retries suitable to their needs. IX_NPEMH_SEND_RETRIES_DEFAULT can be used as a default value for the maxSendRetries parameter for this function. Each retry exceeding this default number will incur a blocking delay of 1 microsecond, to avoid consuming too much AHB bus bandwidth while performing retries.

Re-entrancy: This function will be callable from any thread at any time. IxOsServices will be used for any necessary resource protection.

Returns:
The function returns a status indicating success or failure.

IX_STATUS ixNpeMhShow IxNpeMhNpeId  npeId  ) 
 

This function will display the current state of the IxNpeMh component.

Re-entrancy: This function will be callable from any thread at any time. However, no resource protection will be used so as not to impact system performance. As this function is only reading statistical information then this is acceptable.

Parameters:
IxNpeMhNpeId npeId (in) - The ID of the NPE to display state information for.
Returns:
The function returns a status indicating success or failure.

IX_STATUS ixNpeMhShowReset IxNpeMhNpeId  npeId  ) 
 

This function will reset the current state of the IxNpeMh component.

Re-entrancy: This function will be callable from any thread at any time. However, no resource protection will be used so as not to impact system performance. As this function is only writing statistical information then this is acceptable.

Parameters:
IxNpeMhNpeId npeId (in) - The ID of the NPE to reset state information for.
Returns:
The function returns a status indicating success or failure.

IX_STATUS ixNpeMhUnload void   ) 
 

This function will uninitialise the IxNpeMh component.

This function will uninitialise the IxNpeMh component. It should only be called once, and only if the IxNpeMh component has already been initialised. No other IxNpeMh API functions should be called until ixNpeMhInitialize is called again. If possible, this function should be called before a soft reboot or unloading a kernel module to perform any clean up operations required for IxNpeMh.

The following actions will be performed by this function:

  1. Unmapping of kernel memory mapped by the function ixNpeMhInitialize.

Returns:
The function returns a status indicating success or failure.

IX_STATUS ixNpeMhUnsolicitedCallbackForRangeRegister IxNpeMhNpeId  npeId,
IxNpeMhMessageId  minMessageId,
IxNpeMhMessageId  maxMessageId,
IxNpeMhCallback  unsolicitedCallback
 

This function will register an unsolicited callback for a particular NPE and range of message IDs.

Parameters:
IxNpeMhNpeId npeId (in) - The ID of the NPE whose messages the unsolicited callback will handle.
IxNpeMhMessageId minMessageId (in) - The minimum message ID in the range of message IDs the unsolicited callback will handle.
IxNpeMhMessageId maxMessageId (in) - The maximum message ID in the range of message IDs the unsolicited callback will handle.
IxNpeMhCallback unsolicitedCallback (in) - The unsolicited callback function. A value of NULL will deregister any previously registered callback(s) for this NPE and range of message IDs.
This function will register an unsolicited callback for a particular NPE and range of message IDs. It is a convenience function that is effectively the same as calling ixNpeMhUnsolicitedCallbackRegister() for each ID in the specified range. See ixNpeMhUnsolicitedCallbackRegister() for more information.

Re-entrancy: This function will be callable from any thread at any time. IxOsServices will be used for any necessary resource protection.

Returns:
The function returns a status indicating success or failure.

IX_STATUS ixNpeMhUnsolicitedCallbackRegister IxNpeMhNpeId  npeId,
IxNpeMhMessageId  messageId,
IxNpeMhCallback  unsolicitedCallback
 

This function will register an unsolicited callback for a particular NPE and message ID.

Parameters:
IxNpeMhNpeId npeId (in) - The ID of the NPE whose messages the unsolicited callback will handle.
IxNpeMhMessageId messageId (in) - The ID of the messages the unsolicited callback will handle.
IxNpeMhCallback unsolicitedCallback (in) - The unsolicited callback function. A value of NULL will deregister any previously registered callback for this NPE and message ID.
This function will register an unsolicited message callback for a particular NPE and message ID.

If an unsolicited callback is already registered for the specified NPE and message ID then the callback will be overwritten. Only one client will be responsible for handling a particular message ID associated with a NPE. Registering a NULL unsolicited callback will deregister any previously registered callback.

The callback function will be called from an ISR that will be triggered by the NPE's "outFIFO not empty" interrupt (see ixNpeMhInitialize()) to handle any unsolicited messages of the specific message ID received from the NPE. Unsolicited messages will be handled in the order they are received.

If no unsolicited callback can be found for a received message then it is assumed that the message is solicited.

If more than one client may be interested in a particular unsolicited message then the suggested strategy is to register a callback for the message that can itself distribute the message to multiple clients as necessary.

See also ixNpeMhUnsolicitedCallbackForRangeRegister().

Re-entrancy: This function will be callable from any thread at any time. IxOsServices will be used for any necessary resource protection.

Returns:
The function returns a status indicating success or failure.

Automatically generated from sources. © Intel Corp. 2003