Srio User API

Serial RapidIO

1. Introduction........................................................................................................................................3

2. Serial Rapidio System......................................................................................................................3

3. SRIO User API Calls........................................................................................................................4

3.1 Srio Open...................................................................................................................................4

3.2 SrioClose....................................................................................................................................5

3.3 Srio Device Ready....................................................................................................................5

3.4 Srio Who Am I...........................................................................................................................6

3.5 Srio Get Last Error....................................................................................................................7

3.6 Srio is discovered......................................................................................................................7

3.7 Srio is Transmit Enable............................................................................................................8

3.8 Srio Get My Device Id...............................................................................................................8

3.9 Srio Get Device Information.....................................................................................................9

3.10 Srio Get System Information.................................................................................................10

3.11 Srio Read Register..................................................................................................................10

3.12 Srio Write Register..................................................................................................................11

3.13 Srio Doorbell Send..................................................................................................................12

3.14 Srio Receive Doorbell.............................................................................................................12

3.15 Srio Message Send................................................................................................................13

3.16 Srio Receive Message...........................................................................................................14

3.17 Srio Read.................................................................................................................................15

3.18 Srio Write..................................................................................................................................15

3.19 Srio Bulk Read.........................................................................................................................16

3.20 Srio Bulk Write.........................................................................................................................17

3.21 Srio Read Local Buffer...........................................................................................................18

1

3.22 Srio Get Event Type...............................................................................................................18

4. Appendix A........................................................................................................................................20

4.1 Error Codes..............................................................................................................................20

4.2 Data Structure.........................................................................................................................21

2

1. Introduction This document covers brief details about serial rapidio user API`s. This document

would be helpful to, the software developer uses serial rapidio interface. All API calls are bundled as a user space library (SrioUserApi.a). In document, API calls are arranged in order of usability. First Srio API call should be SrioOpen, which create bridge between user space and kernel space and check for readiness of serial rapidio interface. There after any API calls can be made; at the end SrioClose should be called. Error numbers, their meanings and data structure details are given in appendix A.

2. Serial Rapidio System Processor

PowerPC 85xx; tested on power pc 8548.

OS

Integrity RTOS

Features Supported

Doorbell message

o 16 bit data, 8 message inbox.

o 16bit data, source id 16bit, targeted 16bit, reserved 16 bit total 512(8*64) byte Ram memory will be used.

o Message priority 0(low),1,2(high)

Messages

o Mailbox 0; maximum length of message 4k bytes, 8 message inbox. Message length should be multiple of 8; allowed messages lengths are 8, 16, 32, 64, 128, 256, 512, 1024 or 4096 byte.

32k RAM memory will be used.

o Mailbox 1; maximum length of message 4k bytes, 8 message inbox. Message length should be multiple of 8; allowed messages lengths are 8, 16, 32, 64, 128, 256, 512, 1024 or 4096 byte.

o 32k RAM memory will be used.

o Message priority 0(low),1,2(high)

3

o Information about Sender id and message length is not available; application has to embed that information if required.

IO operation: NREAD NWRITE 32bit data

Bulk read/ Bulk write; 4mb maximum length. 4mb inbound buffer.

Configuration read : Read register space of other card

System requirement

RAM: around 5mb Ram will be used by serial rapidio interface.

DMA: Channel 0 is being used.

SRIO memory: Minimum 10 MB of CPU address space.

3. SRIO User API Calls

3.1 Srio Open

Function name

STATUS SrioOpen (SrioHandle *SessionHandle)

Description

Creates bridge between user space to kernel space deriver; on success it will return a handle, which should further used throughout session. This function should be called before any other function call, if this call success then only further function call should be made.

Parameters

Parameters Data Type In/Out Description

SessionHandle SrioHandle * In, Out Handle for a particular Session

Return Value

RIO_ SUCCESS,

4

RIO_SRIO_DISABLED,

RIO_SERDES_DISABLED,

RIO_UNKNOWN_DEVICE,

RIO_FATAL_ERROR,

RIO_NO_LINK,

RIO_NOT_READY;

3.2 SrioClose

Function name

STATUS SrioClose (SrioHandle SessionHandle)

Description

It shall close an opened session;

Parameters


SessionHandle SrioHandle In Session Handle

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE;

3.3 Srio Device Ready

Function name

STATUS SrioIsDeviceReady (SrioHandle SessionHandle)

Description

This function shall check and report readiness of srio interface and driver. If interface is ready then only any API call should be made.

Parameters

5



Return Value

RIO_ SUCCESS,

RIO_SRIO_DISABLED,

RIO_SERDES_DISABLED,

RIO_UNKNOWN_DEVICE,

RIO_FATAL_ERROR,

RIO_NO_LINK,

RIO_NOT_READY,

RIO_INVALID_HANDLE;

3.4 Srio Who Am I

Function name

STATUS SrioWhoAmI (SrioHandle SessionHandle, Value *WhoAmI)

Description

Reports, processor is configured as srio host, standby host or agent.

Parameters



WhoAmI Value * In, Out 1 – Host 2 – Stand by Host 3 – Agent

RIO_HOST, RIO_STANDBY_HOST, RIO_AGENT

Return Value

6

RIO_ SUCCESS,

RIO_INVALID_HANDLE;

3.5 Srio Get Last Error

Function name

STATUS SrioGetLastError (SrioHandle SessionHandle)

Description

This function gets last occurred error number.

Parameters



Return Value

RIO_ SUCCESS : No error

RIO_INVALID_HANDLE,

SRIO_LAST_ERROR;

3.6 Srio is discovered

Function name

STATUS SrioIsDiscovered (SrioHandle SessionHandle)

Description

Reports processor is discovered by host or not. If processor is not discovered by host, it cannot initiate any data transaction.

Parameters

7



Return Value

RIO_ SUCCESS : Device discovered

RIO_INVALID_HANDLE,

RIO_NOT_READY : Device is not discovered.

3.7 Srio is Transmit Enable

Function name

STATUS SrioIsTxEnabled (SrioHandle SessionHandle)

Description

This function checks and reports whether transmission of srio data packet is enabled or not.

Parameters



Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE,

RIO_NOT_READY;

3.8 Srio Get My Device Id

Function name

8

STATUS SrioGetMyDeviceId (SrioHandle SessionHandle, Value *mydevid)

Description

This function gets, device id of processer in srio network.

Parameters



mydevid Value * In, Out Srio Device Id of processer

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE;

3.9 Srio Get Device Information

Function name

STATUS SrioGetDevice (SrioHandle SessionHandle, struct srio_devid_table *devinfo)

Description

This function gets number of device available in srio network and their respective device ID’s.

Parameters



devinfo struct srio_devid_table * In, OutStructure gives number of

devices and their device ID’s

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE;

9

3.10 Srio Get System Information

Function name

STATUS SrioGetSysInfo (SrioHandle SessionHandle, struct srio_sys_info *sysInfo)

Description

This function shall get srio system information; which includes port width, line width, system size, speed.

Parameters



sysInfo struct srio_sys_info * In, OutStructure gives information

about srio system

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE;

3.11 Srio Read Register

Function name

STATUS SrioReadRegister (SrioHandle SessionHandle, Value DestId, Value Offset, Value *RegValue)

Description

This function shall read specified register of a specified processor from given offset.

Parameters



DestId Value In Destination id of processor

Offset Value In Register offset,

10

Range 0x00000 - 0xD34EC

RegValue Value * In/ Out Register Value

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE,

RIO_ERR_INVALID_PARAMETER;

3.12 Srio Write Register

Function name

STATUS SriowriteRegister (SrioHandle SessionHandle, Value DestId, Value Offset, Value RegValue)

Description

This function shall write specified register of specified processor at given offset.

Parameters




Offset Value InRegister offset,

Range 0x00000 - 0xD34EC

RegValue Value * In/ Out Value to write

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE,

RIO_NOT_READY,

11

RIO_ERR_INVALID_PARAMETER,

RIO_INVALID_DEVID;

3.13 Srio Doorbell Send

Function name

STATUS SrioSendDoorbell (SrioHandle SessionHandle, Value DestId, UINT2 DoorBellMsg, UINT1 Priority)

Description

This function shall send doorbell to a specified processor; doorbell message size should be 16bit.Allowed message priority levels are 0, 1 and 2.

Parameters




DoorBellMsg UINT2 In doorbell message to send

Priority UINT1 In Message priority

Allowed 0, 1 and 2

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE,

RIO_MESSAGE_UNIT_BUSY,

RIO_DB_SEND_FAILED,

RIO_INVALID_DEVID;

12

3.14 Srio Receive Doorbell

Function name

STATUS SrioReceiveDoorbell (SrioHandle SessionHandle, Value *DoorBellMsg, Value *SenderId)

Description

This function shall check doorbell inbox for unread message; if there is a message reads 16bit message and sender device id.

Parameters



DoorBellMsg UINT2* InReceived doorbell

message

SenderId Value * In, Out Sender device ID

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE,

RIO_INBOUND_QUEUE_EMPTY;

3.15 Srio Message Send

Function name

STATUS SrioSendMessage (SrioHandle SessionHandle, Value DestId, UINT1 MboxNum, Address Buffer, Value ByteCount, UINT1 Priority)

Description

This function shall send message to a specified mail box of specified processor. This can be used to send message of maximum length 4k. Three level priorities 0, 1 and 2 can be assigned to message; where 0 got lowest and 2 got highest priority.

13

Parameters




MboxNum UINT1 In Mail Box number ( 0 or 1 )

Buffer Address In Message to send

ByteCount Value In

Message length (allowed 8,16,64,128,256,512,1024,2048,4096

)

Priority UINT1 In Message priority (0 1 2)

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE,

RIO_MESSAGE_UNIT_BUSY,

RIO_MSG_SEND_FAILED,


RIO_INVALID_DEVID;

3.16 Srio Receive Message

Function name

STATUS SrioReceiveMessage (SrioHandle SessionHandle, UINT1 MboxNum, Value *Buffer, Value Length)

Description

This function shall check specified mail box for message. If there is an unread message, then that will be copied to given buffer.

Parameters


14


MboxNum UINT1 In Mail Box number ( 0 or 1)

Buffer Value * In, Out received Message

Length Value In

Message length (allowed 8,16,64,128,256,512,1024,2048,4096

)

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE,


RIO_INBOUND_QUEUE_EMPTY;

3.17 Srio Read

Function name

STATUS SrioRead (SrioHandle SessionHandle, Value DestId, Value * Value)

Description

This function shall read 32bit data from specified processor buffer.

Parameters




Value Value * In, Out Value read from specified processor buffer

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE,

RIO_INVALID_DEVID;

15

3.18 Srio Write

Function name

STATUS SrioWrite (SrioHandle SessionHandle, Value DestId, Value Data)

Description

This function shall write 32bit data to specified processor buffer.

Parameters



DestId Value InDestination id of

processor

Data Value In Value to write

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE,

RIO_NWRITE_FAILED,

RIO_INVALID_DEVID;

3.19 Srio Bulk Read

Function name

STATUS SrioBulkRead (SrioHandle SessionHandle, Value DestId,

Value *Buffer, Value Length)

Description

Read bulk data from specified processor buffer; maximum 4MB data can be read.

Parameters

16




Buffer Value * In, Outdata from specified

processor buffer

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE,

RIO_DMA_BUSY,

RIO_INVALID_DEVID;

3.20 Srio Bulk Write

Function name

STATUS SrioBulkWrite (SrioHandle SessionHandle, Value DestId,

Address Buffer, Value ByteCount)

Description

This function shall write data into specified processor buffer. Maximum 4MB of data can be written.

Parameters




Buffer Address Value Buffer address

ByteCount Value Value Size of data, Max size 4MB

Return Value

RIO_ SUCCESS,

17

RIO_INVALID_HANDLE,

RIO_DMA_BUSY,

RIO_INVALID_DEVID;

3.21 Srio Read Local Buffer

Function name

STATUS SrioReadLocalBuffer (SrioHandle SessionHandle, Value *Buffer,

Value Length)

Description

This function shall read given number of bytes from local in bound buffer. Data sent from any other processor gets stored in local buffer.

Parameters



Buffer Value * In, Out Data read from local buffer

Length Value In Size of data, Max size 4MB

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE;

18

3.22 Srio Get Event Type

Function name

STATUS SrioGetEventType (SrioHandle SessionHandle, int *EventType)

Description

This function shall get type of recently occurred event; mainly it will inform about data reception. When there is no event; calling this function will return NO_EVENT. If there is an event, function will return exact event type; now its application responsibility to call respective receive function call (doorbell or message receive) and read received data.

Parameters



EventType int *In, Out

Event type

NO_EVENT,EVENT_DB,EVENT_MSG0,EVENT_MSG1

Return Value

RIO_ SUCCESS,

RIO_INVALID_HANDLE;

19

4. Appendix A

4.1 Error Codes

Error Code Value Description

RIO_ SUCCESS 0x0 Success, requested operation is successful

SRIO_LAST_ERROR 0x5 Last error

RIO_ERR_INVALID_PARAMETER 0x1001

One or more input parameters had an invalid value

RIO_NO_LINK 0x1002No neighbor srio device; srio either switch or processor not configured properly

RIO_NO_MEM 0x1003 Dynamic Memory allocation failed

RIO_UNKNOWN_DEVICE 0x1004 Code is not running on mpc8548

RIO_FATAL_ERROR 0x1005Rapid IO interface is configured as parallel interface; srio interface cannot be used

RIO_ATMU_FULL 0x1006No free ATMU window available, hence setting up srio interface failed.

RIO_MESSAGE_UNIT_BUSY 0x1007

Message unit is busy; messages send/receive failed.

RIO_INBOUND_QUEUE_EMPTY 0x1008 No message in message inbox

RIO_SRIO_DISABLED 0x1009 Srio interface is not enabled in processor

RIO_SERDES_DISABLED 0x100A SERDES not enabled

RIO_LAW_FULL 0x100BLAW is full; srio failed to configure LAW for srio

20

memory

RIO_NOT_READY 0x100CProcessor not yet discovered/master bit is not enabled, data transaction not possible

RIO_LAW_TLB_NOT_CONFIGURED 0x100D

LAW and TLB are not configured for srio memory; srio interface cannot be used

RIO_MEMORY_MAP_ERROR 0x100E

Unable to get srio memory range from BSP; srio interface cannot be used.

RIO_DB_SEND_FAILED 0x100FDoor bell send failed, no response received from destination processor.

RIO_DMA_BUSY 0x1010 DMA controller is busy, bulk read/write failed

RIO_NWRITE_FAILED 0x1011Writing 32bit data failed; no response from destination processor.

RIO_MSG_SEND_FAILED 0x1012Message send failed, no response received from destination processor.

RIO_BULK_WRITE_FAILED 0x1013

Sending bulk data failed, no response received from destination processor

RIO_INVALID_DEVID 0x1014 Destination ID provided is invalid

RIO_INVALID_HANDLE 0x2000 Given session handle is in valid

4.2 Data Structure

Sysinfo

typedef struct srio_sys_info

{

UINT2 portwidth; /* port width */

UINT2 lanewidth; /* training status of port */

UINT4 syssize; /*large/small max device 65536/256 */

char speed[15]; /* 1.25,2.5,3.125Gbps per lane */

}srio_sys_info_t;

21

Device Id Table

typedef struct srio_devid_table

{

UINT1 devid[MAX_DEVICES];

UINT2 numofdevice;

}srio_devid_table_t;

MAX_DEVICES 256

22

Srio User API

Documents

Transcript of Srio User API