Main Page Modules Alphabetical List Data Structures File List Data Fields Globals
IXP425 NPE Message Handler (IxNpeMh) APIThe 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
|
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
|
|
Enumeration Type Documentation
|
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
|
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:
-
Initialization of internal data structures (e.g. solicited and unsolicited callback tables).
-
Configuration of the interface with the NPEs (e.g. enabling of NPE "outFIFO not empty" interrupts).
-
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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:
-
Unmapping of kernel memory mapped by the function ixNpeMhInitialize.
- Returns:
- The function returns a status indicating success or failure.
|
|
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.
|
|
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.
|
|