# SRIO LLD Functions
[SRIO LLD]

## Functions

void | Srio_processReceivedBD (Srio_DriverInst *ptr_srioDrvInst, Cppi_Desc *ptrDesc)
void | Srio_rxCompletionIsr (Srio_DrvHandle hSrioDrv)
void | Srio_dioCompletionIsr (Srio_DrvHandle hSrioDrv, uint8_t intDstDoorbell[])
void | Srio_dioTxCompletionIsr (Srio_DrvHandle hSrioDrv, CSL_SrioHandle hSrioCSL)
static void | Srio_flushSockData (Srio_Socket *ptr_srioSocket)
static int32_t | Srio_initSockData (Srio_Socket *ptr_srioSocket)
int32_t | Srio_init (void)
static int32_t | Srio_getDescSize (Qmss_MemRegion memRegion)
static int32_t | Srio_processDrvConfig (Srio_DriverInst *ptr_srioDrvInst)
static int32_t | Srio_processAppConfig (Srio_DriverInst *ptr_srioDrvInst)
Srio_DrvHandle | Srio_start (Srio_DrvConfig *ptr_cfg)
Srio_SockHandle | Srio_sockOpen (Srio_DrvHandle hSrio, Srio_SocketType type, uint16_t isBlocking)
static int32_t | Srio_validateBindingId (uint16_t id, uint8_t tt)
static int32_t | Srio_validateDIOBindingId (uint16_t idMap, uint8_t tt)
int32_t | Srio_sockBind_TYPE11 (Srio_SockHandle srioSock, Srio_SockBindAddrInfo *ptr_bindInfo)
int32_t | Srio_sockBind_TYPE9 (Srio_SockHandle srioSock, Srio_SockBindAddrInfo *ptr_bindInfo)
int32_t | Srio_sockBind_DIO (Srio_SockHandle srioSock, Srio_SockBindAddrInfo *ptr_bindInfo)
int32_t | Srio_sockBind (Srio_SockHandle srioSock, Srio_SockBindAddrInfo *ptr_bindInfo)
Srio_DrvBuffer | Srio_allocTransmitBuffer (Srio_DrvHandle hSrioDrv, uint8_t **ptrData, uint32_t *bufferLen)
void | Srio_freeTransmitBuffer (Srio_DrvHandle hSrioDrv, Srio_DrvBuffer hDrvBuffer)
int32_t | Srio_sockSend_TYPE11 (Srio_SockHandle srioSock, Srio_DrvBuffer hDrvBuffer, uint32_t numBytes, Srio_SockAddrInfo *to)
int32_t | Srio_sockSend_TYPE9 (Srio_SockHandle srioSock, Srio_DrvBuffer hDrvBuffer, uint32_t numBytes, Srio_SockAddrInfo *to)
int32_t | Srio_sockSend_DIO (Srio_SockHandle srioSock, Srio_DrvBuffer hDrvBuffer, uint32_t numBytes, Srio_SockAddrInfo *to)
int32_t | Srio_sockSend (Srio_SockHandle srioSock, Srio_DrvBuffer hDrvBuffer, uint32_t numBytes, Srio_SockAddrInfo *to)
int32_t | Srio_sockRecv (Srio_SockHandle srioSock, Srio_DrvBuffer *hDrvBuffer, Srio_SockAddrInfo *from)
void | Srio_freeRxDrvBuffer (Srio_SockHandle srioSock, Srio_DrvBuffer hDrvBuffer)
int32_t | Srio_setSockOpt (Srio_SockHandle srioSock, Srio_Opt option, void *optval, int32_t optlen)
int32_t | Srio_getSockOpt (Srio_SockHandle srioSock, Srio_Opt option, void *optval, int32_t optlen)
int32_t | Srio_sockClose_TYPE11 (Srio_SockHandle srioSock)
int32_t | Srio_sockClose_TYPE9 (Srio_SockHandle srioSock)
int32_t | Srio_sockClose_DIO (Srio_SockHandle srioSock)
int32_t | Srio_sockClose (Srio_SockHandle srioSock)
uint32_t | Srio_getVersion (void)
const char * | Srio_getVersionStr (void)

## Function Documentation

Srio_DrvBuffer Srio_allocTransmitBuffer | ( | Srio_DrvHandle | hSrioDrv,
|  | uint8_t ** | ptrData,
|  | uint32_t * | bufferLen |
| ) |  |  |

Description
The function is used to allocate a transmit buffer. Applications needs to call this API and get a data buffer from the internal Transmit buffer pool.

Parameters:

  `[in]` | hSrioDrv | SRIO Driver Instance
  `[out]` | ptrData | Data Buffer Address which has been allocated
  `[out]` | bufferLen | Allocated buffer Length

Return values:

  | Success | - Allocated Driver Buffer Handle
  | Error | - NULL

void Srio_dioCompletionIsr | ( | Srio_DrvHandle | hSrioDrv,
|  | uint8_t | intDstDoorbell[] |
| ) |  |  |

Description
The function is the SRIO DIO ISR handler which is used to handle the DIO Interrupts. SRIO Driver users need to ensure that this ISR is plugged with their OS Interrupt Management API. The function expects the Interrupt Destination information to be passed along to the API because the DIO Doorbell interrupt destination mapping is configurable during SRIO device initialization.

Parameters:

  `[in]` | hSrioDrv | SRIO Driver Handle
  `[in]` | intDstDoorbell | This is an array of the interrupt destination to which the doorbells are routed to.

Return values:

  | Not | Applicable

void Srio_dioTxCompletionIsr | ( | Srio_DrvHandle | hSrioDrv,
|  | CSL_SrioHandle | hSrioCSL |
| ) |  |  |

Description
This function is SRIO DIO LSU interrupt handler (ISR) which is used to process the pending DIO Interrupts. SRIO Driver users need to ensure that this function is called from the application registered ISR plugged with their OS Interrupt Management API. The function scans LSU0_ICSR register and fills the completion code in sockets based on the matching srcIDMap.

Parameters:

  `[in]` | hSrioDrv | SRIO Driver Handle
  `[in]` | hSrioCSL | CSL SRIO Handle

Return values:

  | Not | Applicable

static void Srio_flushSockData | ( | Srio_Socket * | ptr_srioSocket | ) | `[static]`

Description
Utility function used internally to clean the socket data list.

Parameters:

  `[in]` | ptr_srioSocket | Pointer to the SRIO socket for which the socket data queues need to be flushed.

Return values:

  | Not | Applicable

void Srio_freeRxDrvBuffer | ( | Srio_SockHandle | srioSock,
|  | Srio_DrvBuffer | hDrvBuffer |
| ) |  |  |

Description
The function is used to clean the memory of a received SRIO packet.

Parameters:

  `[in]` | srioSock | SRIO socket on which the data was received
  `[in]` | hDrvBuffer | The SRIO Driver buffer which was received by the application and now needs to be cleaned up.

Return values:

  | Success | - 0
  | Error | - <0

void Srio_freeTransmitBuffer | ( | Srio_DrvHandle | hSrioDrv,
|  | Srio_DrvBuffer | hDrvBuffer |
| ) |  |  |

Description
The function is used to cleanup an allocated transmit buffer. This API needs to be called only if there is an application error between the allocation and send API. If the send API has been called; the buffers are automatically cleaned up and this API should *not* be called.

Parameters:

  `[in]` | hSrioDrv | SRIO Driver Instance
  `[in]` | hDrvBuffer | Handle to the allocated driver buffer to be cleaned up.

Return values:

  | Not | Applicable

static int32_t Srio_getDescSize | ( | Qmss_MemRegion | memRegion | ) | `[static]`

Description
Utility API which gets the descriptor size for a specific memory region.

Parameters:

  `[in]` | memRegion | Memory Region for which the descriptor size is required.

Return values:

  | Success | - Descriptor size corresponding to the memory region
  | Error | - <0

int32_t Srio_getSockOpt | ( | Srio_SockHandle | srioSock,
|  | Srio_Opt | option,
|  | void * | optval,
|  | int32_t | optlen |
| ) |  |  |

Description
The function is used to get the various configuration parameters in the SRIO Driver.

Parameters:

  `[in]` | srioSock | Socket handle for which configuration is required
  `[in]` | option | The configuration command which is to be executed by this API
  `[out]` | optval | The configuration data which is to be retreived and populated
  `[in]` | optlen | The size of the data buffer

Return values:

  | Success | - 0
  | Error | - <0

uint32_t Srio_getVersion | ( | void |  | ) |

Description
The function is used to get the version information of the SRIO Driver.

Return values:

  | Version | Information.

const char* Srio_getVersionStr | ( | void |  | ) |

Description
The function is used to get the version string for the SRIO driver.

Return values:

  | Version | String.

int32_t Srio_init | ( | void |  | ) |

Description
This is the SRIO Driver Initialization API which needs to be invoked by the users to initialize the SRIO peripheral. This call is *mandatory* and should be called before calling any of the other driver API's.

This should only be called *ONCE* for the device.

Return values:

  | Success | - 0
  | Error | - <0

static int32_t Srio_initSockData | ( | Srio_Socket * | ptr_srioSocket | ) | `[static]`

Description
Utility function used internally to initialize the socket data list. The number of socket data packets allocated matches the MAX pending.

Parameters:

  `[in]` | ptr_srioSocket | Pointer to the SRIO socket for which the socket data queues need to be initialized.

Return values:

  | Success | - 0
  | Error | - <0

static int32_t Srio_processAppConfig | ( | Srio_DriverInst * | ptr_srioDrvInst | ) | `[static]`

Description
The API handles application managed configuration. It uses the information specified in the configuration to program the accumulator & setup the receive flows.

Parameters:

  `[in]` | ptr_srioDrvInst | Driver Instance being created

Return values:

  | Success | - 0
  | Error | - <0

static int32_t Srio_processDrvConfig | ( | Srio_DriverInst * | ptr_srioDrvInst | ) | `[static]`

Description
The API handles driver managed configuration. It uses the information specified in the configuration to program the accumulator, setup the receive flow and the driver receive buffer pools.

Parameters:

  `[in]` | ptr_srioDrvInst | Driver Instance being created

Return values:

  | Success | - 0
  | Error | - <0

void Srio_processReceivedBD | ( | Srio_DriverInst * | ptr_srioDrvInst,
|  | Cppi_Desc * | ptrDesc |
| ) |  |  |

Description
The function is called to process a received buffer descriptor. This is internally called by the ISR and can also be called by applications if they have processed the interrupt by themselves and have been able to retreive a SRIO buffer descriptor which they wish to process.

Parameters:

  `[in]` | ptr_srioDrvInst | Driver Instance
  `[in]` | ptrDesc | Received Buffer descriptor to be processed.

Return values:

  | Not | Applicable

void Srio_rxCompletionIsr | ( | Srio_DrvHandle | hSrioDrv | ) |

Description
The function is the SRIO ISR handler which is used to handle the data management interrupts after a packet has received. SRIO Driver users need to ensure that this ISR is plugged with their OS Interrupt Management API.

Parameters:

  `[in]` | hSrioDrv | SRIO Driver Handle

Return values:

  | Not | Applicable

int32_t Srio_setSockOpt | ( | Srio_SockHandle | srioSock,
|  | Srio_Opt | option,
|  | void * | optval,
|  | int32_t | optlen |
| ) |  |  |

Description
The function is used to set the various configuration parameters in the SRIO Driver.

Parameters:

  `[in]` | srioSock | Socket handle which needs to be configured.
  `[in]` | option | The configuration command which is to be executed by this API
  `[in]` | optval | The configuration data which is passed. Type of data passed is configuration command specific.
  `[in]` | optlen | The size of the configuration data.

Return values:

  | Success | - 0
  | Error | - <0

int32_t Srio_sockBind | ( | Srio_SockHandle | srioSock,
|  | Srio_SockBindAddrInfo * | ptr_bindInfo |
| ) |  |  |

Description
The function is used to bind the SRIO socket to the local properties as specified. The binding information is required for Type9, Type11 and DIO sockets.

Parameters:

  `[in]` | srioSock | Socket handle which is to be bound.
  `[in]` | ptr_bindInfo | Pointer to the binding information.

Return values:

  | Success | - 0
  | Error | - <0

int32_t Srio_sockBind_DIO | ( | Srio_SockHandle | srioSock,
|  | Srio_SockBindAddrInfo * | ptr_bindInfo |
| ) |  |  |

Description
The function is used to bind a DIO SRIO socket to the local properties as specified. The binding information is required for DIO sockets.

Parameters:

  `[in]` | srioSock | Socket handle which is to be bound.
  `[in]` | ptr_bindInfo | Pointer to the binding information.

Return values:

  | Success | - 0
  | Error | - <0

int32_t Srio_sockBind_TYPE11 | ( | Srio_SockHandle | srioSock,
|  | Srio_SockBindAddrInfo * | ptr_bindInfo |
| ) |  |  |

Description
The function is used to bind a Type11 SRIO socket to the local properties as specified. The binding information is required for Type11 sockets.

Parameters:

  `[in]` | srioSock | Socket handle which is to be bound.
  `[in]` | ptr_bindInfo | Pointer to the binding information.

Return values:

  | Success | - 0
  | Error | - <0

int32_t Srio_sockBind_TYPE9 | ( | Srio_SockHandle | srioSock,
|  | Srio_SockBindAddrInfo * | ptr_bindInfo |
| ) |  |  |

Description
The function is used to bind a Type9 SRIO socket to the local properties as specified. The binding information is required for Type9 sockets.

Parameters:

  `[in]` | srioSock | Socket handle which is to be bound.
  `[in]` | ptr_bindInfo | Pointer to the binding information.

Return values:

  | Success | - 0
  | Error | - <0

int32_t Srio_sockClose | ( | Srio_SockHandle | srioSock | ) |

Description
The function is used to close a SRIO socket.

Parameters:

  `[in]` | srioSock | Socket handle to be closed.

Return values:

  | Success | - 0
  | Error | - <0

int32_t Srio_sockClose_DIO | ( | Srio_SockHandle | srioSock | ) |

Description
The function is used to close a DIO SRIO socket.

Parameters:

  `[in]` | srioSock | Socket handle to be closed.

Return values:

  | Success | - 0
  | Error | - <0

int32_t Srio_sockClose_TYPE11 | ( | Srio_SockHandle | srioSock | ) |

Description
The function is used to close a TYPE11 SRIO socket.

Parameters:

  `[in]` | srioSock | Socket handle to be closed.

Return values:

  | Success | - 0
  | Error | - <0

int32_t Srio_sockClose_TYPE9 | ( | Srio_SockHandle | srioSock | ) |

Description
The function is used to close a TYPE9 SRIO socket.

Parameters:

  `[in]` | srioSock | Socket handle to be closed.

Return values:

  | Success | - 0
  | Error | - <0

Srio_SockHandle Srio_sockOpen | ( | Srio_DrvHandle | hSrio,
|  | Srio_SocketType | type,
|  | uint16_t | isBlocking |
| ) |  |  |

Description
The function is used to open a SRIO socket. This API needs to be invoked by the driver users to send and receive data.

Parameters:

  `[in]` | hSrio | Handle to the SRIO driver instance.
  `[in]` | type | Socket type.
  `[in]` | isBlocking | Socket is blocking or not? Set to 1 to create a blocking socket else 0 for a non blocking socket

Return values:

  | Success | - Valid Socket handle
  | Error | - NULL

int32_t Srio_sockRecv | ( | Srio_SockHandle | srioSock,
|  | Srio_DrvBuffer * | hDrvBuffer,
|  | Srio_SockAddrInfo * | from |
| ) |  |  |

Description
The function is used to receive data from the SRIO socket. For blocking sockets this API will block and will only return once data is received for non-blocking sockets the API will return 0 if no data is available. If data is available on the socket; the receive API will pass back the data to the callee. For Raw Sockets data is passed up as a buffer descriptor while for normal sockets the data is passed as pointer to the data payload.

The callee is responsible for cleaning the associated receive packet buffer.

See also:
  Srio_freeRxDrvBuffer, SRIO_GET_DBELL_REG, SRIO_GET_DBELL_BIT

Parameters:

  `[in]` | srioSock | Socket handle on which data is to be received.
  `[in]` | hDrvBuffer | Handle to the driver buffer where the received data will be placed. For Normal sockets this points to the data buffer; for RAW sockets this points to the descriptor and for DIO sockets this has the DOORBELL information.
  `[out]` | from | Populated with the address information of the received packet

Return values:

  | Success | - Number of bytes of data received.
  | Error | - <0

int32_t Srio_sockSend | ( | Srio_SockHandle | srioSock,
|  | Srio_DrvBuffer | hDrvBuffer,
|  | uint32_t | numBytes,
|  | Srio_SockAddrInfo * | to |
| ) |  |  |

Description
The function is used to send data on the specified SRIO sockets. Application developers should have created and bound the socket before calling this.

For messaging sockets (Type9 and Type11) the API handles both cases

- Normal Sockets The application should allocate SRIO Driver buffers using the 'Srio_allocTransmitBuffer' API. The allocated driver buffer should then be populated by the application with the payload and then passed to this API for transmission.
- Raw Sockets The application should pass the pointer to the buffer descriptor to be transmitted. Ensure that the length of the the data buffer being transmitted is double word multiple as specified by Rapid IO.

For DIO Sockets the pointer to the driver buffer points to the location in local memory which is involved in the DIO tranfer. To send a doorbell using the API the hDrvBuffer contains in the upper 16 bits the doorbell register and in the lower 16 bits contains the doorbell bit. The SRIO driver provides the SRIO_SET_DBELL_INFO macro for this.

See also:
  Srio_allocTransmitBuffer, SRIO_SET_DBELL_INFO

Parameters:

  `[in]` | srioSock | Socket handle on which data is to be sent.
  `[in]` | hDrvBuffer | This is the pointer to the driver buffer to be transmitted. (In the case of sending a DIO Doorbell the value is a combination of the DOORBELL register and DOORBELL bit)
  `[in]` | numBytes | Number of bytes to be sent. For RAW sockets this should be the size of the descriptor which is to be pushed into the transmit queue.
  `[in]` | to | The address to which the data is to be sent.

Return values:

  | Success | - 0
  | Error | - <0 (In the case of DIO sockets this is the completion code)

int32_t Srio_sockSend_DIO | ( | Srio_SockHandle | srioSock,
|  | Srio_DrvBuffer | hDrvBuffer,
|  | uint32_t | numBytes,
|  | Srio_SockAddrInfo * | to |
| ) |  |  |

Description
The function is used to send data on the DIO SRIO sockets. Application developers should have created and bound the socket before calling this.

For DIO Sockets the pointer to the driver buffer points to the location in local memory which is involved in the DIO tranfer. To send a doorbell using the API the hDrvBuffer contains in the upper 16 bits the doorbell register and in the lower 16 bits contains the doorbell bit. The SRIO driver provides the SRIO_SET_DBELL_INFO macro for this.

See also:
  Srio_allocTransmitBuffer, SRIO_SET_DBELL_INFO

Parameters:

  `[in]` | srioSock | Socket handle on which data is to be sent.
  `[in]` | hDrvBuffer | This is the pointer to the driver buffer to be transmitted. In the case of sending a DIO Doorbell the value is a combination of the DOORBELL register and DOORBELL bit.
  `[in]` | numBytes | Number of bytes to be sent.
  `[in]` | to | The address to which the data is to be sent.

Return values:

  | Success | - 0
  | Error | - <0 (In case of DIO blocking sockets this is the completion code)

int32_t Srio_sockSend_TYPE11 | ( | Srio_SockHandle | srioSock,
|  | Srio_DrvBuffer | hDrvBuffer,
|  | uint32_t | numBytes,
|  | Srio_SockAddrInfo * | to |
| ) |  |  |

Description
The function is used to send data on the TYPE11 SRIO sockets. Application developers should have created and bound the socket before calling this.

For messaging socket (Type11) the API handles both cases

- Normal Sockets The application should allocate SRIO Driver buffers using the 'Srio_allocTransmitBuffer' API. The allocated driver buffer should then be populated by the application with the payload and then passed to this API for transmission.
- Raw Sockets The application should pass the pointer to the buffer descriptor to be transmitted. Ensure that the length of the the data buffer being transmitted is double word multiple as specified by Rapid IO.

Parameters:

  `[in]` | srioSock | Socket handle on which data is to be sent.
  `[in]` | hDrvBuffer | This is the pointer to the driver buffer to be transmitted.
  `[in]` | numBytes | Number of bytes to be sent. For RAW sockets this should be the size of the descriptor which is to be pushed into the transmit queue.
  `[in]` | to | The address to which the data is to be sent.

Return values:

  | Success | - 0
  | Error | - <0

int32_t Srio_sockSend_TYPE9 | ( | Srio_SockHandle | srioSock,
|  | Srio_DrvBuffer | hDrvBuffer,
|  | uint32_t | numBytes,
|  | Srio_SockAddrInfo * | to |
| ) |  |  |

Description
The function is used to send data on the TYPE9 SRIO sockets. Application developers should have created and bound the socket before calling this.

For messaging socket (Type9) the API handles both cases

- Normal Sockets The application should allocate SRIO Driver buffers using the 'Srio_allocTransmitBuffer' API. The allocated driver buffer should then be populated by the application with the payload and then passed to this API for transmission.
- Raw Sockets The application should pass the pointer to the buffer descriptor to be transmitted. Ensure that the length of the the data buffer being transmitted is double word multiple as specified by Rapid IO.

Parameters:

  `[in]` | srioSock | Socket handle on which data is to be sent.
  `[in]` | hDrvBuffer | This is the pointer to the driver buffer to be transmitted.
  `[in]` | numBytes | Number of bytes to be sent. For RAW sockets this should be the size of the descriptor which is to be pushed into the transmit queue.
  `[in]` | to | The address to which the data is to be sent.

Return values:

  | Success | - 0
  | Error | - <0

Srio_DrvHandle Srio_start | ( | Srio_DrvConfig * | ptr_cfg | ) |

Description
This API is responsible for creating and initializing an instance of the SRIO driver. Application developers need to ensure that they create a driver instance before they can use any of the other SRIO driver APIs.

Parameters:

  `[in]` | ptr_cfg | Pointer to the SRIO driver configuration block.

Return values:

  | Success | - Valid SRIO Driver Instance Handle
  | Error | - NULL

static int32_t Srio_validateBindingId | ( | uint16_t | id,
|  | uint8_t | tt |
| ) |  |  | `[static]`

Description
This is an internal function which is used to validate if the socket can be bound to the specified device id or not. Sockets can only be bound to the device id which is located either in the BRR or in the Device ID CSR Register

Parameters:

  `[in]` | id | Device Id which is to be checked.
  `[in]` | tt | 16 bit or 8 bit identifier.

Return values:

  | Success | - 0
  | Error | - <0

static int32_t Srio_validateDIOBindingId | ( | uint16_t | idMap,
|  | uint8_t | tt |
| ) |  |  | `[static]`

Description
This is an internal function which is used to validate if the socket can be bound to the specified device id or not. The function is used to validate the src id map for DIO sockets. DIO sockets use the SrcID map index for the source id while Type9 and Type11 sockets take the actual soruce id.

Parameters:

  `[in]` | idMap | Source Id map which is to be validated.
  `[in]` | tt | 16 bit or 8 bit identifier.

Return values:

  | Success | - 0
  | Error | - <0

Copyright 2012, Texas Instruments Incorporated