10.2. SYSTEM APPLICATION PROGRAMMING INTERFACES
In order to provide a standardized programming interface to RapidIO hardware, the RapidIO Technical Working Group has defined sets of standard applications programming interfaces (API), that should be used by configuration and operating system software to interact with the RapidIO hardware. By working through an API rather than directly interacting with the RapidIO hardware and registers, insulation against low level changes is provided. The most basic level of API provided are the hardware abstraction layer (HAL) functions. The higher-level functions should rely on the support functions provided by the HAL functions to ensure portability between different platforms.
Device-specific (vendor-specific) functions are functions defined by a device manufacturer that use hardware resources outside of the scope of the RapidIO specifications. The main purpose of these functions is to provide HAL support to the standard RapidIO functions. An important goal of this software API specification is to minimize or eliminate the use of device-specific functions required for enumeration so that the portability of the API across hardware platforms is maximized.
Virtually all of the APIs, when referencing the RapidIO system, will contain at least three parameters. These parameters are: localport, destid and hopcount. Localport refers to the local RapidIO port that the transaction is either targeted at our should be sent out of. Devices can have more that one RapidIO port on them. Localport is used to identify which port is being referred to. Destid is the 8- or 16-bit deviceID of the device that the transaction is targeted at. Although it describes an 8- or 16-bit quantity the destid field is a 32-bit field. The hopcount field is used when the transaction is targeted at a switch. Maintenance transactions contain a hopcount field which is decremented as it is passed through every switch. If the hopcount field reaches zero, it indicates that the transaction is meant for the current switch device. When a transaction is not targeted at a switch the hopcount field should be set to 0×FF.
10.2.1. Basic Hardware Abstraction Layer (HAL) Functions
The hardware abstraction layer (HAL) provides a standard software interface to the device-specific hardware resources needed to support RapidIO system configuration transactions. At the most basic level, configuration read and write operations are used by the HAL functions to access RapidIO device registers. The HAL functions are accessed by the RapidIO enumeration API during system bringup and may be used for ongoing system maintenance.
This section describes the HAL functions and how they can be used to access local and remote RapidIO device registers. These functions must be implemented by every new device-specific host-processing element to support RapidIO system enumeration and initialization. The HAL functions assume the following:
All configuration read and write operations support only single-word (4-byte) accesses.
As required by the device, the size of the 8-bit or 16-bit deviceID field is determined by the device implementation.
An enumerating processor device may have more than one RapidIO end point (local port).
One purpose of the HAL is to provide a unified software interface to configuration registers in both local and remote RapidIO processing elements. This is done by a universal device-addressing scheme. Such a scheme enables HAL functions to distinguish between accesses to local and remote RapidIO end points without requiring an additional parameter. The result is that only one set of HAL functions must be implemented to support local and remote configuration operations.
All HAL functions use the destid and hopcount parameters to address a RapidIO device. The HAL reserves destid=0×FFFFFFFF and hopcount of 0 for addressing configuration registers within the local RapidIO end point. A destid=0×FFFFFFFF and hopcount of 0 value must be used to address the local processing end point regardless of the actual destination ID value. This reserved combination does not conflict with the address of other RapidIO devices. The localport parameter is used by the HAL functions to identify a specific local port within RapidIO devices that contain multiple ports.
The most basic functions that form the RapidIO initialization HAL are the rioGetNumLocalPorts, rioConfiguratioRead and rioConfigurationWrite functions described below. These functions are simple APIs that are meant to simplify the task of interaction with the RapidIO CAR and CSR registers. The CAR registers contain the capabilities and attributes of a RapidIO end point or switch and the CSR registers can be used to configure the capabilities of a RapidIO endpoint or switch. Either the device vendor or the RTOS vendor, depending on the product, would provide the code supporting these APIs.
rioGetNumLocalPorts
Prototype:
INT32 rioGetNumLocalPorts (
Void
)
Arguments:
None
Return value:
0 Error
n Number of RapidIO ports supportedSynopsis:
rioGetNumLocalPorts() returns the total number of local RapidIO ports supported by the HAL functions. The number n returned by this function should be equal to or greater than 1. A returned value of 0 indicates an error.
rioConfigurationRead
Prototype:
STATUS rioConfigurationRead (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 offset,
UINT32 *readdata
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the target device [IN] |
| hopcount | Hop count [IN] |
| offset | Word-aligned (four byte boundary) offset—in bytes—of the CAR or CSR [IN] |
| *readdata | Pointer to storage for received data [OUT] |
Return value:
| RIO_SUCCESS | The read operation completed successfully and valid data was placed into the specified location. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioConfigurationRead() performs a configuration read transaction from CAR and/or CSR register(s) belonging to a local or remote RapidIO device. The function uses a device-specific hardware interface to generate maintenance transactions to remote devices. This hardware sends a configuration read request to the remote device (specified by destid and/or hopcount) and waits for a corresponding configuration read response. After the function receives a configuration read response it returns data and/or status to the caller. The method for accessing registers in a local device is device-specific.
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioConfigurationWrite
Prototype:
STATUS rioConfigurationWrite (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 offset,
UINT32 *writedata
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the target device [IN] |
| hopcount | Hop count [IN] |
| offset | Word-aligned (four-byte boundary) offset, in bytes, of the CAR or CSR [IN] |
| *writedata | Pointer to storage for data to be written [IN] |
Return value:
| RIO_SUCCESS | The write operation completed successfully. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioConfigurationWrite() performs a configuration write transaction to CAR and/or CSR register(s) belonging to a local or remote RapidIO device. The function uses a device-specific hardware interface to generate maintenance transactions to remote devices. This hardware sends a configuration write request to the remote device (specified by destid and/or hopcount) and waits for a corresponding configuration write response. After the function receives a configuration write response it returns status to the caller. The method for accessing registers in a local device is device-specific.
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
10.2.2. RapidIO Bringup HAL Functions
With these three basic HAL functions, we can create a set of more complex functions that can be used to bring up a system. This section describes the RapidIO functions that should be implemented to support system bringup. Functions are defined only for device registers used during the RapidIO enumeration and initialization process, not for all possible RapidIO device registers. Many of the functions may also be implemented as macros that specify predefined parameters for the HAL functions. The standard RapidIO bringup functions can be combined into a library if they are implemented as a set of subroutines.
rioInitLib
Prototype:
STATUS rioInitLib (
Void
)Arguments:
None
Return value:
| RIO_SUCCESS | Initialization completed successfully. |
| RIO_ERROR | Generic error report. Unable to initialize library. |
Synopsis:
rioInitLib() initializes the RapidIO API library. No routines defined in this chapter may be called unless and untile rioInitLib has been invoked. If rioInitLib returns RIO_ERROR, no routines defined in this chapter may be called.
rioGetFeatures
Prototype:
STATUS rioGetFeatures (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 *features
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| *features | Pointer to storage containing the received features [OUT] |
Return value:
| RIO_SUCCESS | The features were retrieved successfully and placed into the location specified by *features. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioGetFeatures() uses the HAL rioConfigurationRead() function to read from the processing element features CAR of the specified processing element. Values read are placed into the location referenced by the *features pointer. Reported status is similar to rioConfigurationRead().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioGetSwitchPortInfo
Prototype:
STATUS rioGetSwitchPortInfo (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 *portinfo
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| *portinfo | Pointer to storage containing the received port information [OUT] |
Return value:
| RIO_SUCCESS | The port information was retrieved successfully and placed into the location specified by *portinfo. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioGetSwitchPortInfo() uses the HAL rioConfigurationRead() function to read from the Switch Port Information CAR of the specified processing element. Values read are placed into the location referenced by the *portinfo pointer. Reported status is similar to rioConfigurationRead().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioGetExtFeaturesPtr
Prototype:
STATUS rioGetExtFeaturesPtr (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 *extfptr
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| *extfptr | Pointer to storage containing the received extended feature information [OUT] |
Return value:
| RIO_SUCCESS | The extended feature information was retrieved successfully and placed into the location specified by *extfptr. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioGetExtFeaturesPtr() uses the HAL rioConfigurationRead() function to read the pointer to the first entry in the extended features list from the assembly information CAR of the specified processing element. That pointer is placed into the location referenced by the *extfptr pointer. Reported status is similar to rioConfigurationRead().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers. Note that if the EF_PTR field of *extfptr is 0, no extended features are available.
rioGetNextExtFeaturesPtr
Prototype:
STATUS rioGetNextExtFeaturesPtr (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 currfptr,
UINT32 *extfptr
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| currfptr | Pointer to the last reported extended feature [IN] |
| *extfptr | Pointer to storage containing the received extended feature information [OUT] |
Return value:
| RIO_SUCCESS | The extended feature information was retrieved successfully and placed into the location specified by *extfptr. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioGetNextExtFeaturesPtr() uses the HAL rioConfigurationRead() function to read the pointer to the next entry in the extended features. That pointer is placed into the location referenced by the *extfptr pointer. Reported status is similar to rioConfigurationRead().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers. Note that if the EF_PTR field of *extfptr is 0, no further extended features are available. Invoking rioGetNextExtFeaturesPtr when currfptr has an EF_PTR field value of 0 will result in a return code of RIO_ERR_INVALID_PARAMETER.
rioGetSourceOps
Prototype:
STATUS rioGetSourceOps (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 *srcops
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| *srcops | Pointer to storage containing the received source operation information [OUT] |
Return value:
| RIO_SUCCESS | The source operation information was retrieved successfully and placed into the location specified by *srcops. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioGetSourceOps() uses the HAL rioConfigurationRead() function to read from the source operations CAR of the specified processing element. Values read are placed into the location referenced by the *srcops pointer. Reported status is similar to rioConfigurationRead().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioGetDestOps
Prototype:
STATUS rioGetDestOps (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 *dstops
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| *dstops | Pointer to storage containing the received destination operation information [OUT] |
Return value:
| RIO_SUCCESS | The destination operation information was retrieved successfully and placed into the location specified by *dstops. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioGetDestOps() uses the HAL rioConfigurationRead() function to read from the destination operations CAR of the specified processing element. Values read are placed into the location referenced by the *dstops pointer. Reported status is similar to rioConfigurationRead().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioGetAddressMode
Prototype:
STATUS ri oGetAddressMode (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
ADDR_MODE *amode
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| *amode | Pointer to storage containing the received address mode (34-bit, 50-bit, or 66-bit address) information [OUT] |
Return value:
| RIO_SUCCESS | The address mode information was retrieved successfully and placed into the location specified by *amode. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioGetAddressMode() uses the HAL rioConfigurationRead() function to read from the PE logical layer CSR of the specified processing element. The number of address bits generated by the PE (as the source of an operation) and processed by the PE (as the target of an operation) are placed into the location referenced by the *amode pointer. Reported status is similar to rioConfigurationRead().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioGetBaseDeviceId
Prototype:
STATUS rioGetBaseDeviceId (
UINT8 localport,
UINT32 *deviceid
)Arguments:
| localport | Local port number [IN] |
| *deviceid | Pointer to storage containing the base device ID [OUT] |
Return value:
| RIO_SUCCESS | The base device ID information was retrieved successfully and placed into the location specified by *deviceid. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioGetBaseDeviceId() uses the HAL rioConfigurationRead() function to read from the base device ID CSR of the local processing element (the destid and hopcount parameters used by rioConfigurationRead() must be set to HOST_REGS and zero, respectively). Values read are placed into the location referenced by the *deviceid pointer. Reported status is similar to rioConfigurationRead(). This function is useful only for local end point devices.
rioSetBaseDeviceId
Prototype:
STATUS rioSetBaseDeviceId (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 newdeviceid
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| newdeviceid | New base device ID to be set [IN] |
Return value:
| RIO_SUCCESS | The base device ID was updated successfully. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioSetBaseDeviceId() uses the HAL rioConfigurationWrite() function to write the base device ID in the base device ID CSR of the specified processing element (end point devices only). Reported status is similar to rioConfigurationWrite().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioAcquireDeviceLock
Prototype:
STATUS rioAcquireDeviceLock (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT16 hostdeviceid,
UINT16 *hostlockid
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| hostdeviceid | Host base device ID for the local processing element [IN] |
| *hostlockid | Device ID of the host holding the lock if ERR_LOCK is returned [OUT] |
Return value:
| RIO_SUCCESS | The device lock was acquired successfully. |
| RIO_ERR_LOCK | Another host already acquired the specified processor element. ID of the device holding the lock is contained in the location referenced by the *hostlockid parameter. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioAcquireDeviceLock() tries to acquire the hardware device lock for the specified processing element on behalf of the requesting host. The function uses the HAL rioConfigurationWrite() function to write the requesting host device ID into the host base lock device ID CSR of the specified processing element. After the write completes, this function uses the HAL rioConfigurationRead() function to read the value back from the host base lock device ID CSR. The written and read values are compared. If they are equal, the lock was acquired successfully. Otherwise, another host acquired this lock and the device ID for that host is reported.
This function assumes unique host-based device identifiers are assigned to discovering hosts. For more details, refer to Section 10.3 System Bringup Example. A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioReleaseDeviceLock
Prototype:
STATUS rioReleaseDeviceLock (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT16 hostdeviceid,
UINT16 *hostlockid
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| hostdeviceid | Host base device ID for the local processing element [IN] |
| *hostlockid | Device ID of the host holding the lock if ERR_LOCK is returned [OUT] |
Return value:
| RIO_SUCCESS | The device lock was released successfully. |
| RIO_ERR_LOCK | Another host already acquired the specified processor element. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioReleaseDeviceLock() tries to release the hardware device lock for the specified processing element on behalf of the requesting host. The function uses the HAL rioConfigurationWrite() function to write the requesting host device ID into the host base lock device ID CSR of the specified processing element. After the write completes, this function uses the HAL rioConfigurationRead() function to read the value back from the host base lock device ID CSR. The written and read values are compared. If they are equal, the lock was acquired successfully. Otherwise, another host acquired this lock and the device ID for that host is reported.
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioGetComponentTag
Prototype:
STATUS rioGetComponentTag (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 *componenttag
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| *componenttag | Pointer to storage containing the received component tag information [OUT] |
Return value:
| RIO_SUCCESS | The component tag information was retrieved successfully and placed into the location specified by *componenttag. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioGetComponentTag() uses the HAL rioConfigurationRead() function to read from the component tag CSR of the specified processing element. Values read are placed into the location referenced by the *componenttag pointer. Reported status is similar to rioConfigurationRead().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioSetComponentTag
Prototype:
STATUS rioSetComponentTag (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 componenttag
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| componenttag | Component tag value to be set [IN] |
Return value:
| RIO_SUCCESS | The component tag was updated successfully. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioSetComponentTag() uses the HAL rioConfigurationWrite() function to write the component tag into the component tag CSR of the specified processing element. Reported status is similar to rioConfigurationWrite().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioGetPortErrStatus
Prototype:
STATUS rioGetPortErrStatus (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,UINT16 extfoffset,
UINT8 portnum,
UINT32 *porterrorstatus
)Arguments:
| localport | Local port number [IN] |
| destid | Destination ID of the processing element [IN] |
| hopcount | Hop count [IN] |
| extfoffset | Offset from the previously reported extended features pointer [IN] |
| portnum | Port number to be accessed [IN] |
| *porterrorstatus | Pointer to storage for the returned value [OUT] |
Return value:
| RIO_SUCCESS | The read completed successfully and valid data was placed into the location specified by *porterrorstatus. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
Synopsis:
rioGetPortErrStatus() uses the HAL rioConfigurationRead() function to read the contents of the port n error and status CSR of the specified processing element. Reported status is similar to rioConfigurationRead().
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
10.2.3. Routing-table Manipulation HAL Functions
This section describes the RapidIO functions that must be provided to support routing tables used within the switch fabric. The RapidIO Common Transport Specification requires implementing device-identifier-based packet routing. The detailed implementations of routing tables in switches are not described. To simplify the way that software interacts with RapidIO switch devices, the RapidIO HAL defines a couple of routing-table manipulation functions. These functions would be used in conjunction with the standard RapidIO bringup functions to configure the routing tables in a switch.
The routing-table manipulation functions assume the following:
The destination ID of the device that receives a packet routed by the switch is the route destination ID.
The specific port at the route destination ID that receives a packet routed by the switch is the route port number.
The software paradigm used for routing tables is a linear routing table indexed by the route destination ID.
Switches may implement a global routing table, 'per port' routing tables, or a combination of both.
In order to provide a consistent software view of routing tables the following two functions are defined. RioRouteAddEntry and rioRouteGetEntry. These functions are described in the following pages.
rioRouteAddEntry
Prototype:
STATUS rioRouteAddEntry (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT8 tableidx,
UINT16 routedestid,
UINT8 routeportno
)Arguments:
| localport | Local port number (RapidIO switch) [IN] |
| destid | Destination ID of the processing element (RapidIO switch) [IN] |
| hopcount | Hop count [IN] |
| tableidx | Routing table index for per-port switch implementations [IN] |
| routedestid | Route destination ID—used to select an entry into the specified routing table [IN] |
| routeportno | Route port number—value written to the selected routing table entry [IN] |
Return value:
| RIO_SUCCESS | The routing table entry was added successfully. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
| RIO_WARN_INCONSISTENT | Used by rioRouteGetEntry—indicates that the routeportno returned is not the same for all ports. |
Synopsis:
rioRouteAddEntry() adds an entry to a routing table for the RapidIO switch specified by the destid and hopcount parameters. The tableidx parameter is used to select a specific routing table in the case of implementations with 'per-port' routing tables. A value of tableidx=0×FF specifies a global routing table for the RapidIO switch. The routeportno parameter is written to the routing table entry selected by the routedestid parameter.
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioRouteGetEntry
Prototype:
STATUS rioRouteGetEntry (
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT8 tableidx,
UINT16 routedestid,
UINT8 *routeportno
)Arguments:
| localport | Local port number (RapidIO switch) [IN] |
| destid | Destination ID of the processing element (RapidIO switch) [IN] |
| hopcount | Hop count [IN] |
| tableidx | Routing table index for per-port switch implementations [IN] |
| routedestid | Route destination ID—used to select an entry into the specified routing table [IN] |
| *routeportno | Route port number—pointer to value read from the selected routing table entry [OUT] |
Return value:
| RIO_SUCCESS | The routing table entry was added successfully. |
| RIO_ERR_INVALID_PARAMETER | One or more input parameters had an invalid value. |
| RIO_ERR_RIO | The RapidIO fabric returned a Response Packet with ERROR status reported. Error status returned by this function may contain additional information from the Response Packet. |
| RIO_ERR_ACCESS | A device-specific hardware interface was unable to generate a maintenance transaction and reported an error. |
| RIO_WARN_INCONSISTENT | Used by rioRouteGetEntry—indicates that the routeportno returned is not the same for all ports. |
Synopsis:
rioRouteGetEntry() reads an entry from a routing table for the RapidIO switch specified by the destid and hopcount parameters. The tableidx parameter is used to select a specific routing table in the case of implementations with 'per port' routing tables. A value of tableidx=0×FF specifies a global routing table for the RapidIO switch. The value in the routing table entry selected by the routedestid parameter is read from the table and placed into the location referenced by the *routeportno pointer.
Reads from the global routing table may be undefined in the case where per-port routing tables exist. A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
10.2.4. Device Access Routine (DAR) Functions
This section defines the device access routine (DAR) interface that must be provided for RapidIO device configuration. The client for this interface is the boot loader responsible for RapidIO network enumeration and initialization. By using a standard DAR interface, the firmware does not need to include knowledge of device-specific configuration operations. Thus, enumeration and initialization firmware can operate transparently with devices from many component vendors.
For each processor type supported by a DAR provider, linkable object files for DARs should be supplied in ELF format. Device-specific configuration DARs should be supplied in C-language source code format.
The functions provided by device-specific configuration DARs must be able to link and execute within a minimal execution context (e.g. a system-boot monitor or firmware). In general, configuration DARs should not call an external function that is not implemented by the DAR, unless the external function is passed to the configuration DAR by the initialization function. Also, configuration DAR functions may not call standard C-language I/O functions (e.g. printf) or standard C-language library functions that might manipulate the execution environment (e.g. malloc or exit). The functions that must be provided for a RapidIO device-specific configuration DAR are described in the following sections.
For the rioDar_nameGetFunctionTable functions, the rioDar_name portion of the function name is replaced by an appropriate name for the implemented driver.
rioDar_nameGetFunctionTable
Prototype:
UINT32 rioDar_nameGetFunctionTable(
UINT32 specversion,
RDCDAR_OPS_STRUCT *darops,
UINT32 maxdevices,
UINT32 *darspecificdatabyte
)Arguments:
| specversion | Version number of the DAR interface specification indicating the caller's implementation of the type definition structures [IN] |
| *darops | Pointer to a structure of DAR functions that are allocated by the caller and filled in by the called function [OUT] |
| maxdevices | Maximum expected number of RapidIO devices that must be serviced by this configuration DAR [IN] |
| *darspecificdatabytes | Number of bytes needed by the DAR for the DAR private data storage area [OUT] |
Return value:
| RIO_SUCCESS | On successful completion |
Synopsis:
rioDar_nameGetFunctionTable() is called by a client to obtain the list of functions implemented by a RapidIO device-specific configuration DAR module. It shall be called once before enumerating the RapidIO network. The specversion parameter is the version number defined by the revision level of the specification from which the DAR type definition structures are taken. The maxdevices parameter is an estimate of the maximum number of RapidIO devices in the network that this DAR must service. The DAR uses this estimate to determine the size required for the DAR private data storage area. The storage size is returned to the location referenced by the *darspecificdatabytes pointer. After the client calls this function, the client shall allocate a DAR private data storage area of a size no less than that indicated by *darspecificdatabytes. The client shall provide that private data storage area to rioDarInitialize().
rioDarInitialize
Prototype:
UINT32 rioDarInitialize (
UINT32 specversion,
UINT32 maxdevices,
RDCDAR_PLAT_OPS *platops,
RDCDAR_DATA *privdata
)Arguments:
| specversion | Version number of the DAR interface specification indicating the caller's implementation of the type definition structures [IN] |
| maxdevices | Maximum expected number of RapidIO devices that must be serviced by this configuration DAR [IN] |
| *platops | Pointer to a structure of platform functions for use by the DAR [IN] |
| *privdata | Pointer to structure containing DAR private data area [IN/OUT] |
Return value:
| RIO_SUCCESS | On successful completion |
Synopsis:
rioDarInitialize() is called by a client to initialize a RapidIO device-specific configuration DAR module. This function shall be called once after calling the rioDar_nameGetFunctionTable() functions and before enumerating the RapidIO network. The specversion parameter is the version number defined by the revision level of the specification from which the DAR type definition structures are taken. The maxdevices parameter is an estimate of the maximum number of RapidIO devices in the network that this DAR must service. The maxdevices value must be equal to the value used in the corresponding rioDar_nameGetFunctionTable() function call. The client is responsible for allocating the structure referenced by *privdata. The client is also responsible for allocating a DAR private data storage area at least as large as that specified by the rioDar_nameGetFunctionTable() call. The client must initialize the structure referenced by *privdata with the number of bytes allocated to the DAR private data storage area and with the pointer to the storage area. After calling rioDarInitialize(), the client may not deallocate the DAR private data storage area until after the rioDarTerminate() function has been called.
rioDarTerminate
Prototype:
UINT32 rioDarTerminate (
RDCDAR_DATA *privdata
)Arguments:
| *privdata | Pointer to structure containing DAR private data area [IN/OUT] |
Return value:
| RIO_SUCCESS | On successful completion |
Synopsis:
rioDarTerminate() is invoked by a client to terminate a RapidIO device-specific configuration DAR module. This function shall be called once after all use of the DAR services is completed. After calling this function, the client may de-allocate the DAR private data storage area in the structure referenced by *privdata.
rioDarTestMatch
Prototype:
UINT32 rioDarTestMatch (
RDCDAR_DATA *privdata,
UINT8 localport,
UINT32 destid,
UINT8 hopcount
)Arguments:
| *privdata | Pointer to structure containing DAR private data area [IN/OUT] |
| localport | Local port number used to access the network [IN] |
| destid | Destination device ID for the target device [IN] |
| hopcount | Number of switch hops needed to reach the target device [IN] |
Return value:
| RIO_SUCCESS | Device DAR does provide services for this device |
| RIO_ERR_NO_DEVICE_SUPPORT | Device DAR does not provide services for this device. |
Synopsis:
rioDarTestMatch() is invoked by a client to determine whether or not a RapidIO device-specific configuration DAR module provides services for the device specified by destid. The DAR interrogates the device (using the platform functions supplied during DAR initialization), examines the device identity and any necessary device registers, and determines whether or not the device is handled by the DAR. The DAR does not assume that a positive match (return value of 0) means the DAR will actually provide services for the device. The client must explicitly register the device with rioDARregister() if the client will be requesting services.
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioDarRegister
Prototype:
UINT32 rioDarRegister (
RDCDAR_DATA *privdata,
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
)Arguments:
| *privdata | Pointer to structure containing DAR private data [IN/OUT] |
| localport | Local port number used to access the network [IN] |
| destid | Destination device ID for the target device [IN] |
| hopcount | Number of switch hops needed to reach the target device [IN] |
Return value:
| RIO_SUCCESS | Device DAR successfully registered this device. |
| RIO_ERR_NO_DEVICE_SUPPORT | Device DAR does not provide services for this device. |
| RIO_ERR_INSUFFICIENT_RESOURCES | Insufficient storage available in DAR private storage area |
Synopsis:
rioDarRegister() is invoked by a client to register a target device with a RapidIO device-specific configuration DAR. The client must call this function once for each device serviced by the DAR. The client should first use the rioDarTestMatch() function to verify that the DAR is capable of providing services to the device.
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioDarGetMemorySize
Prototype:
UINT32 rioDarGetMemorySize (
RDCDAR_DATA *privdata,
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT32 regionix,
UINT32 *nregions,
UINT32 *regbytes[2],
UINT32 *startoffset[2]
)Arguments:
| *privdata | Pointer to structure containing DAR private data area [IN/OUT] |
| localport | Local port number used to access the network [IN] |
| destid | Destination device ID for the target device [IN] |
| hopcount | Number of switch hops needed to reach the target device [IN] |
| regionix | Index of the memory region being queried (0, 1, 2, 3, ...) [IN] |
| *nregions | Number of memory regions provided by the target device [OUT] |
| *regbytes | Size (in bytes) of the queried memory region [OUT] |
| *startoffset | Starting address offset for the queried memory region [OUT] |
Return value:
| RIO_SUCCESS | Device DAR successfully returned memory size information for the target device. |
| RIO_ERR_NO_DEVICE_SUPPORT | Device DAR could not determine memory size information for the target device. |
Synopsis:
rioDarGetMemorySize() is invoked by a client to determine the number of, the sizes of, and the offsets for the memory regions supported by a RapidIO target device. The function is intended to support the mapping of PCI or other address windows to RapidIO devices. If the regionix parameter is greater than the number of regions provided by the device (*nregions), the DAR should return a value of zero for the *regbytes and *startoffset parameters, and indicate a 'successful' (0) return code. rioDarGetMemorySize always returns at least one region. The first index, index 0, always refers to the region controlled by the local configuration space base address registers. The client must register the target device with the RapidIO device-specific configuration DAR before calling this function.
rioDarGetSwitchInfo
Prototype:
UINT32 rioDarGetSwitchInfo (
RDCDAR_DATA *privdata,
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
RDCDAR_SWITCH_INFO *info
)Arguments:
| *privdata | Pointer to structure containing DAR private data [IN/OUT] |
| localport | Local port number to be used to access network [IN] |
| destid | Destination device ID to reach target switch device [IN] |
| hopcount | Number of switch hops to reach target switch device [IN] |
| *info | Pointer to switch information data structure [OUT] |
Return value:
| RIO_SUCCESS | Device DAR successfully retrieved the information for RDCDAR_PLAT_OPS_STRUCT. |
| RIO_ERR_NO_DEVICE_SUPPORT | Insufficient switch routing resources available. |
| RIO_ERR_NO_SWITCH | Target device is not a switch. |
Synopsis:
rioDarGetSwitchInfo() is invoked by a client to retrieve the data necessary to initialize the RDCDAR_SWITCH_INFO structure. The client must register the target device with the RapidIO device-specific configuration DAR before calling this function.
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioDarSetPortRoute
Prototype:
UINT32 rioDarSetPortRoute (
RDCDAR_DATA *privdata,
UINT8 localport,
UINT32 destid,
UINT8 hopcount,
UINT8 tableidx,
UINT16 routedestid,
UINT8 routeportno
)Arguments:
| *privdata | Pointer to structure containing DAR private data area [IN/OUT] |
| localport | Local port number to be used to access network [IN] |
| destid | Destination device ID to reach target switch device [IN] |
| hopcount | Number of switch hops to reach target switch device [IN] |
| inport | Target switch device input port [IN] |
| tableidx | Routing table index for per-port switch implementations [IN] |
| routedestid | Route destination ID—used to select an entry into the specified routing table [IN] |
| routeportno | Route port number—value written to the selected routing table entry [IN] |
Return value:
| RIO_SUCCESS | Device DAR successfully modified the packet routing configuration for the target switch device. |
| RIO_ERR_NO_DEVICE_SUPPORT | Insufficient switch routing resources available. |
| RIO_ERR_ROUTE_ERROR | Switch cannot support requested routing. |
| RIO_ERR_NO_SWITCH | Target device is not a switch. |
| RIO_ERR_FEATURE_NOT_SUPPORTED | Target device is not capable of per-input-port routing. |
Synopsis:
rioDarSetPortRoute() is invoked by a client to modify the packet routing configuration for a RapidIO target switch device. The client must register the target device with the RapidIO device-specific configuration DAR before calling this function.
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.
rioDarGetPortRoute
Prototype:
UINT32 rioDarGetPortRoute ( RDCDAR_DATA *privdata, UINT8 localport, UINT32 destid, UINT8 hopcount, UINT8 tableidx, UINT16 routedestid, UINT8 *routeportno )
Arguments:
| *privdata | Pointer to structure containing DAR private data area [IN/OUT] |
| localport | Local port number to be used to access network [IN] |
| destid | Destination device ID to reach target switch device [IN] |
| hopcount | Number of switch hops to reach target switch device [IN] |
| tableidx | Routing table index for per-port switch implementations [IN] |
| routedestid | Route destination ID—used to select an entry into the specified routing table [IN] |
| *routeportno | Route port number—pointer to value read from the selected routing table entry [OUT] |
Return value:
| RIO_SUCCESS | Device DAR successfully modified the packet routing configuration for the target switch device. |
| RIO_ERR_NO_DEVICE_SUPPORT | Insufficient switch routing resources available. |
| RIO_ERR_ROUTE_ERROR | Switch cannot support requested routing. |
| RIO_ERR_NO_SWITCH | Target device is not a switch. |
Synopsis:
rioDarGetPortRoute() is invoked by a client to read the packet routing configuration for a RapidIO target switch device. The client must register the target device with the RapidIO device-specific configuration DAR before calling this function.
A destid value of HOST_REGS and hopcount of 0 results in accesses to the local hosts RapidIO registers.