# QMSS Low Level Driver Functions
[QMSS]

## Functions

static void | Qmss_queuePush (Qmss_QueueHnd hnd, void *descAddr, uint32_t packetSize, uint32_t descSize, Qmss_Location location)
static void | Qmss_queuePushDesc (Qmss_QueueHnd hnd, void *descAddr)
static void | Qmss_queuePushDescSize (Qmss_QueueHnd hnd, void *descAddr, uint32_t descSize)
static void * | Qmss_queuePop (Qmss_QueueHnd hnd)
static void | Qmss_queuePopDescSize (Qmss_QueueHnd hnd, void **descAddr, uint32_t *packetSize)
static Qmss_QueuePushHnd | Qmss_getQueuePushHandle (Qmss_QueueHnd hnd)
static void | Qmss_queueDivert (Qmss_QueueHnd srcQnum, Qmss_QueueHnd dstQnum, Qmss_Location location)
static void | Qmss_queueEmpty (Qmss_QueueHnd hnd)
static uint32_t | Qmss_getQueueEntryCount (Qmss_QueueHnd hnd)
static uint32_t | Qmss_getQueueByteCount (Qmss_QueueHnd hnd)
static uint32_t | Qmss_getQueuePacketSize (Qmss_QueueHnd hnd)
Qmss_Result | Qmss_programAccumulator (Qmss_PdspId pdspId, Qmss_AccCmdCfg *cfg)
Qmss_Result | Qmss_disableAccumulator (Qmss_PdspId pdspId, uint8_t channel)
Qmss_Result | Qmss_configureAccTimer (Qmss_PdspId pdspId, uint16_t timerConstant)
Qmss_Result | Qmss_programReclaimQueue (Qmss_PdspId pdspId, Qmss_QueueHnd hnd)
Qmss_Result | Qmss_programDiversionQueue (Qmss_PdspId pdspId, Qmss_QueueHnd divQ, Qmss_QueueHnd divCompletionQ)
Qmss_Result | Qmss_init (Qmss_InitCfg *initCfg, Qmss_GlobalConfigParams *qmssGblCfgParams)
Qmss_Result | Qmss_startCfg (Qmss_StartCfg *startCfg)
Qmss_Result | Qmss_start (void)
Qmss_Result | Qmss_getMemoryRegionCfg (Qmss_MemRegCfg *memRegInfo)
Qmss_Result | Qmss_insertMemoryRegion (Qmss_MemRegInfo *memRegCfg)
Qmss_QueueHnd | Qmss_initDescriptor (Qmss_DescCfg *descCfg, uint32_t *numAllocated)
Qmss_QueueHnd | Qmss_queueOpen (Qmss_QueueType queType, int32_t queNum, uint8_t *isAllocated)
Qmss_QueueHnd | Qmss_queueOpenInRange (uint32_t startQueNum, uint32_t endQueNum, uint8_t *isAllocated)
Qmss_Result | Qmss_queueClose (Qmss_QueueHnd hnd)
uint32_t | Qmss_getQueueThreshold (Qmss_QueueHnd hnd)
Qmss_Result | Qmss_setQueueThreshold (Qmss_QueueHnd hnd, uint16_t hilo, uint8_t threshold)
uint32_t | Qmss_getStarvationCount (Qmss_QueueHnd hnd)
uint16_t | Qmss_getQueueThresholdStatus (Qmss_QueueHnd hnd)
Qmss_Queue | Qmss_getQueueNumber (Qmss_QueueHnd hnd)
Qmss_QueueHnd | Qmss_getQueueHandle (Qmss_Queue queue)
Qmss_Result | Qmss_downloadFirmware (Qmss_PdspId pdspId, void *image, uint32_t size)
Qmss_Result | Qmss_setEoiVector (Qmss_IntdInterruptType type, uint8_t accumCh)
Qmss_Result | Qmss_ackInterrupt (uint8_t interruptNum, uint8_t value)
uint32_t | Qmss_getVersion (void)
const char * | Qmss_getVersionStr (void)
Qmss_Result | Qmss_setQosQueueBase (uint32_t queueNum)
Qmss_Result | Qmss_getQosQueueBase (uint32_t *queueNum)
Qmss_Result | Qmss_configureQosTimer (uint32_t timerConstant)
Qmss_Result | Qmss_enableQosCluster (uint32_t clusterIndex)
Qmss_Result | Qmss_disableQosCluster (uint32_t clusterIndex)
Qmss_Result | Qmss_configureQosQueue (uint32_t queIndex, Qmss_QosQueueCfg *cfg)
Qmss_Result | Qmss_configureQosCluster (uint32_t clusterIndex, Qmss_QosClusterCfg *cfg)
Qmss_Result | Qmss_getQosQueueForwardPktStats (uint32_t queIndex)
Qmss_Result | Qmss_getQosQueueDroppedPktStats (uint32_t queIndex)
Qmss_Result | Qmss_resetQosQueueStats (uint32_t queIndex)
Qmss_Result | Qmss_configureQosSrioCluster (uint32_t clusterIndex, Qmss_QosSrioCfg *cfg)
Qmss_Result | Qmss_enableQosSrioCluster (uint32_t clusterIndex)
Qmss_Result | Qmss_disableQosSrioCluster (uint32_t clusterIndex)
Qmss_Result | Qmss_setQosSchedQueueBase (uint32_t queueNum)
Qmss_Result | Qmss_getQosSchedQueueBase (uint32_t *queueNum)
Qmss_Result | Qmss_configureQosSchedTimer (uint32_t timerConstant)
Qmss_Result | Qmss_enableQosSchedPort (uint32_t port)
Qmss_Result | Qmss_disableQosSchedPort (uint32_t port)
Qmss_Result | Qmss_putCfgQosSchedPort (uint32_t port, Qmss_QosSchedPortCfg *cfg)
Qmss_Result | Qmss_getCfgQosSchedPort (uint32_t port, Qmss_QosSchedPortCfg *cfg)
Qmss_Result | Qmss_getQosSchedStats (Qmss_QosSchedStats *stats, uint32_t port, uint32_t group, uint32_t queue, uint32_t which_reset)
uint32_t | Qmss_getQosSchedFwVersion (void)

## Function Documentation

Qmss_Result Qmss_ackInterrupt | ( | uint8_t | interruptNum,
|  | uint8_t | value |
| ) |  |  |

Description
This function decrements the interrupt count. The Interrupt Count Registers contains a count of the interrupts that have triggered and not been processed. Writing a non-zero value to the register subtracts that value from the count. Writing a 0 clears the count. The count saturates at 3.

Note: Clearing the count does not clear the interrupt. The EOI Vector must be set using Qmss_setEoiVector API.

Parameters:

  `[in]` | interruptNum | Interrupt Number that should be acknowledged.
  `[in]` | value | Value to decrement by or zero to clear.

**No validation is done to check if the interrupt number is within range to reduce overhead.**

Postcondition:
  Count is decremented or cleared depending on input parameter.

Return values:

  | Success | - QMSS_ACC_SOK
  | Failure | - QMSS_NOT_INITIALIZED
  | Failure | - QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_configureAccTimer | ( | Qmss_PdspId | pdspId,
|  | uint16_t | timerConstant |
| ) |  |  |

Description
This function programs the timer constant used by the firmware to generate the timer tick.

The Accumulator time "tick" is controlled by a local timer connected to the PDSP core. This timer has a programmable count based on the sub-system clock. When this count expires, a local "tick" is registered in the firmware. The tick is used when timing channel interrupts based on the "Timer Load Count" value supplied in the timer configuration.

The value of "Timer Constant" is the number of QM sub-system clocks divided by 2 that comprise a single "tick" in the accumulator firmware.

For example, if the QM sub-system clock is 350MHz, and the desired firmware "tick" is 20us, the proper Timer Constant for this command is computed as follows:

Timer Constant = (350,000,000 cycles/sec) * (0.000020 sec) / (2 cycles) Timer Constant = 3,500

The firmware initializes with a default constant value of 4375. This corresponds to firmware tick of 25us.

Parameters:

  `[in]` | pdspId | Accumulator to program Qmss_PdspId_PDSP1 selects firmware downloaded to PDSP 1 Qmss_PdspId_PDSP2 selects firmware downloaded to PDSP 2
  `[in]` | timerConstant | 16 bit wide value calculated as explained above

Postcondition:
  Timer constant is programmed and in use.

Return values:

  | Value | reported by accumulator
  | Success | - QMSS_ACC_SOK
  | Failure | - QMSS_NOT_INITIALIZED
  | Failure | - Accumulator status - QMSS_ACC_IDLE, QMSS_ACC_INVALID_COMMAND

Qmss_Result Qmss_configureQosCluster | ( | uint32_t | clusterIndex,
|  | Qmss_QosClusterCfg * | cfg |
| ) |  |  |

Description
This function is used to configure a QoS cluster. Only disabled clusters can be modified by the host. When a cluster is disabled all packet in the QoS queue contained in that cluster are discarded.

Parameters:

  `[in]` | clusterIndex | Index of the cluster to configure - Valid range is 0 to 7
  `[in]` | cfg | cluster configuration parameters

Precondition:
  The cluster must be disabled using Qmss_disableQosCluster() API before calling this function.

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - QMSS_QCMD_INVALID_INDEX QMSS_QCMD_INVALID_MODE QMSS_QCMD_INVALID_RR_HIGH_Q QMSS_QCMD_INVALID_RR_LOW_Q QMSS_QCMD_INVALID_RR_EGRESS_Q QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_configureQosQueue | ( | uint32_t | queIndex,
|  | Qmss_QosQueueCfg * | cfg |
| ) |  |  |

Description
This function is used to configure a QoS queue. Only disabled clusters can be modified by the host. When a cluster is disabled all packet in the QoS queue contained in that cluster are discarded.

Parameters:

  `[in]` | queIndex | Index of the queue to configure - Valid range is 0 to 31
  `[in]` | cfg | Queue configuration parameters

Precondition:
  The cluster must be disabled using Qmss_disableQosCluster() API before calling this function.

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - QMSS_QCMD_INVALID_INDEX
  | Failure | - QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_configureQosSchedTimer | ( | uint32_t | timerConstant | ) |

Description
This function is used to configure the QoS packet scheduler's credit interval timer

Parameters:

  `[in]` | timerConstant | The PDSP timer determines when credit is passed out. The timer is configured by supplying a timer constant. The constant is computed as follows:

timerConstant = (QMSS_Clock_Frequency * Desired_Interval) / 2

Return values:

  | Success | - QMSS_QOS_SCHED_RETCODE_SUCCESS
  | Failure | - The following errors are detected by the firmware: QMSS_QOS_SCHED_INVALID_COMMAND QMSS_QOS_SCHED_INVALID_INDEX QMSS_QOS_SCHED_INVALID_OPTION The following errors are detected by the LLD: QMSS_QOS_SCHED_INVALID_PORT

Qmss_Result Qmss_configureQosSrioCluster | ( | uint32_t | clusterIndex,
|  | Qmss_QosSrioCfg * | cfg |
| ) |  |  |

Description
This function is used to configure the SRIO tracking cluster. The cluster must be disabled before calling this function.

Parameters:

  `[in]` | clusterIndex | Index of the cluster to configure - Valid value is 0
  `[in]` | cfg | cluster configuration parameters

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - QMSS_QCMD_INVALID_INDEX, QMSS_QCMD_INVALID_SRIO_NUM_Q

Qmss_Result Qmss_configureQosTimer | ( | uint32_t | timerConstant | ) |

Description
This function is used to configure the QoS credit interval timer

**No validation is done on the input parameters**.

Parameters:

  `[in]` | timerConstant | The PDSP timer determines when credit is passed out. The timer is configured by supplying a timer constant. The constant is computed as follows:

timerConstant = (QMSS_Clock_Frequency * Desired_Interval) / 2

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - Command buffer return status - QMSS_QCMD_INVALID_COMMAND, QMSS_QCMD_INVALID_INDEX, QMSS_QCMD_INVALID_OPTION, QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_disableAccumulator | ( | Qmss_PdspId | pdspId,
|  | uint8_t | channel |
| ) |  |  |

Description
This function disables the accumulator functionality for the specified channel

Parameters:

  `[in]` | pdspId | Accumulator to program. Qmss_PdspId_PDSP1 selects firmware downloaded to PDSP 1 Qmss_PdspId_PDSP2 selects firmware downloaded to PDSP 2
  `[in]` | channel | Channel to disable

Postcondition:
  Channel is disabled.

Return values:

  | Value | reported by accumulator
  | Success | - QMSS_ACC_SOK
  | Failure | - QMSS_NOT_INITIALIZED
  | Failure | - QMSS_INVALID_PARAM
  | Failure | - Accumulator status - QMSS_ACC_IDLE, QMSS_ACC_INVALID_COMMAND, QMSS_ACC_INVALID_CHANNEL, QMSS_ACC_CHANNEL_NOT_ACTIVE, QMSS_ACC_CHANNEL_ALREADY_ACTIVE, QMSS_ACC_INVALID_QUEUE_NUMBER, QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_disableQosCluster | ( | uint32_t | clusterIndex | ) |

Description
This function is used to disable a QoS cluster. Only disabled clusters can be modified by the host. When a cluster is disabled all packet in the QoS queue contained in that cluster are discarded.

**No validation is done on the input parameters**.

Parameters:

  `[in]` | clusterIndex | Index of the cluster to disable - Valid range is 0 to 7

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - Command buffer return status - QMSS_QCMD_INVALID_COMMAND, QMSS_QCMD_INVALID_INDEX, QMSS_QCMD_INVALID_OPTION, QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_disableQosSchedPort | ( | uint32_t | port | ) |

Description
This function is used to disable a QoS scheduler port. Only disabled ports can be modified by the host. When a port is disabled all packet in the QoS queue contained in that port are discarded.

Parameters:

  `[in]` | port | Port to disable - Valid range is 0 to 1

Return values:

  | Success | - QMSS_QOS_SCHED_RETCODE_SUCCESS
  | Failure | - The following errors are detected by the firmware: QMSS_QOS_SCHED_INVALID_COMMAND QMSS_QOS_SCHED_INVALID_INDEX QMSS_QOS_SCHED_INVALID_OPTION The following errors are detected by the LLD: QMSS_QOS_SCHED_INVALID_PORT

Qmss_Result Qmss_disableQosSrioCluster | ( | uint32_t | clusterIndex | ) |

Description
This function is used to disable a QoS SRIO cluster.

Parameters:

  `[in]` | clusterIndex | Index of the cluster to enable - Valid value is 0

Precondition:
  The cluster and queue configuration must be performed by the host before calling this function.

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - Command buffer return status - QMSS_QCMD_INVALID_COMMAND, QMSS_QCMD_INVALID_INDEX, QMSS_QCMD_INVALID_OPTION

Qmss_Result Qmss_downloadFirmware | ( | Qmss_PdspId | pdspId,
|  | void * | image,
|  | uint32_t | size |
| ) |  |  |

Description
Downloads the PDSP firmware to PDSP. Not supported in simulator

**Not tested**.

Parameters:

  `[in]` | pdspId | PDSP number where the firmware should be downloaded
  `[in]` | image | Pointer to the firmware image
  `[in]` | size | Size of firmware image in bytes

Return values:

  | Success | - Firmware is downloaded to PDSP
  | Failure | - QMSS_NOT_INITIALIZED
  | Failure | - QMSS_INVALID_PARAM
  | Failure | - QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_enableQosCluster | ( | uint32_t | clusterIndex | ) |

Description
This function is used to enable a QoS cluster.

**No validation is done on the input parameters**.

Parameters:

  `[in]` | clusterIndex | Index of the cluster to enable - Valid range is 0 to 7

Precondition:
  The cluster and queue configuration must be performed by the host before calling this function.

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - Command buffer return status - QMSS_QCMD_INVALID_COMMAND, QMSS_QCMD_INVALID_INDEX, QMSS_QCMD_INVALID_OPTION, QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_enableQosSchedPort | ( | uint32_t | port | ) |

Description
This function is used to enable a QoS port.

Parameters:

  `[in]` | port | Port to enable - Valid range is 0 to 1

Precondition:
  The port's configuration must be performed by the host before calling this function.

Return values:

  | Success | - QMSS_QOS_SCHED_RETCODE_SUCCESS
  | Failure | - The following errors are detected by the firmware: QMSS_QOS_SCHED_INVALID_COMMAND QMSS_QOS_SCHED_INVALID_INDEX QMSS_QOS_SCHED_INVALID_OPTION The following errors are detected by the LLD: QMSS_QOS_SCHED_INVALID_PORT

Qmss_Result Qmss_enableQosSrioCluster | ( | uint32_t | clusterIndex | ) |

Description
This function is used to enable a QoS SRIO cluster.

Parameters:

  `[in]` | clusterIndex | Index of the cluster to enable - Valid value is 0

Precondition:
  The cluster and queue configuration must be performed by the host before calling this function.

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - Command buffer return status - QMSS_QCMD_INVALID_COMMAND, QMSS_QCMD_INVALID_INDEX, QMSS_QCMD_INVALID_OPTION

Qmss_Result Qmss_getCfgQosSchedPort | ( | uint32_t | port,
|  | Qmss_QosSchedPortCfg * | cfg |
| ) |  |  |

Description
This function is used to retrieve the current configuration of a QoS scheduler port. It sends a command to the firmware which copies the configuration from the active area to the shadow area (the active area continues to run!)

This function can be used either for diagnostic purposes to verify the configuration, or to query the current configuration, modify it, and put it back using Qmss_putCfgQosSchedPort.

Parameters:

  `[in]` | port | Port to query - Valid range is 0 to 1
  `[out]` | cfg | Port configuration parameters

Return values:

  | Success | - QMSS_QOS_SCHED_RETCODE_SUCCESS
  | Failure | - The following errors are detected by the firmware: QMSS_QOS_SCHED_INVALID_INDEX The following errors are detected by the LLD: QMSS_QOS_SCHED_INVALID_PORT

Qmss_Result Qmss_getMemoryRegionCfg | ( | Qmss_MemRegCfg * | memRegInfo | ) |

Description
This function is used to obtain the QMSS memory region configuration. The function returns the descriptor base address, descriptor size and the number of descriptors for each configured memory region.

Parameters:

  `[out]` | memRegInfo | Pointer to the memory region configuration structure allocated by caller.

Precondition:
  Qmss_init function should be called before calling this function.

Return values:

  | Success | - QMSS_SOK
  | Failure | - QMSS_INVALID_PARAM
  | Failure | - QMSS_NOT_INITIALIZED

Qmss_Result Qmss_getQosQueueBase | ( | uint32_t * | queueNum | ) |

Description
This function is used to get the QoS ingress base queue number. The QoS ingress queue are restricted to a set of 32 starting at a fixed base which must be a multiple of 32.

**No validation is done on the input parameters**.

Parameters:

  `[out]` | queueNum | Base queue number

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - Command buffer return status - QMSS_QCMD_INVALID_COMMAND, QMSS_QCMD_INVALID_INDEX, QMSS_QCMD_INVALID_OPTION

Qmss_Result Qmss_getQosQueueDroppedPktStats | ( | uint32_t | queIndex | ) |

Description
This function is used to get the number of packets dropped due to congestion

Parameters:

  `[in]` | queIndex | Index of the queue whose stats are to be read - Valid range is 0 to 31

Return values:

  | Success | - Dropped packet count
  | Failure | - QMSS_QCMD_INVALID_INDEX

Qmss_Result Qmss_getQosQueueForwardPktStats | ( | uint32_t | queIndex | ) |

Description
This function is used to get the number of packets forwarded to the ergress queue

Parameters:

  `[in]` | queIndex | Index of the queue whose stats are to be read - Valid range is 0 to 31

Return values:

  | Success | - Forwarded packet count
  | Failure | - QMSS_QCMD_INVALID_INDEX

uint32_t Qmss_getQosSchedFwVersion | ( | void |  | ) |

Description
The function is used to get the version information of the current QoS scheduler firmware running on the PDSP.

Return values:

  | Version | Information.

Qmss_Result Qmss_getQosSchedQueueBase | ( | uint32_t * | queueNum | ) |

Description
This function is used to get the QoS ingress base queue number. The QoS ingress queue are restricted to a set of 32 starting at a fixed base which must be a multiple of 32.

**No validation is done on the input parameters**.

Parameters:

  `[out]` | queueNum | Base queue number

Return values:

  | Success | - QMSS_QOS_SCHED_RETCODE_SUCCESS
  | Failure | - Command buffer return status - QMSS_QOS_SCHED_INVALID_COMMAND, QMSS_QOS_SCHED_INVALID_INDEX, QMSS_QOS_SCHED_INVALID_OPTION

Qmss_Result Qmss_getQosSchedStats | ( | Qmss_QosSchedStats * | stats,
|  | uint32_t | port,
|  | uint32_t | group,
|  | uint32_t | queue,
|  | uint32_t | which_reset |
| ) |  |  |

Description
This function returns the bytes and packets forwarded and discarded by the port. The statistics are synchronously and atomically collected and reset.

Parameters:

  `[out]` | stats | Statistics structure to contain returned stats. NULL is valid in order to reset and discard the stats.
  `[in]` | port | Port to request stats - Valid range is 0 to 1
  `[in]` | group | Group to request stats - Valid range is 0 to 4
  `[in]` | queue | Queue in group to request stats - Valid range is 0 to 7
  `[in]` | which_reset | Bitfield listing the stats to reset. Can be one or more of QMSS_QOS_SCHED_STATS_FORWARDED_BYTES | QMSS_QOS_SCHED_STATS_FORWARDED_PACKETS | QMSS_QOS_SCHED_STATS_DISCARDED_BYTES | QMSS_QOS_SCHED_STATS_DISCARDED_PACKETS

Return values:

  | Success | - QMSS_QOS_SCHED_RETCODE_SUCCESS
  | Failure | The following errors are detected by the firmware: QMSS_QOS_SCHED_INVALID_INDEX The following errors are detected by the LLD: QMSS_QOS_SCHED_INVALID_PORT QMSS_QOS_SCHED_INVALID_GROUP QMSS_QOS_SCHED_INVALID_QUEUE

static uint32_t Qmss_getQueueByteCount | ( | Qmss_QueueHnd | hnd | ) | `[inline, static]`

Description
This function returns the total number of bytes that are contained in all of the packets that are currently queued on the queue.

Parameters:

  `[in]` | hnd | Queue handle.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | Queue | byte count

static uint32_t Qmss_getQueueEntryCount | ( | Qmss_QueueHnd | hnd | ) | `[inline, static]`

Description
This function returns the number of packets that are currently queued on the queue.

Parameters:

  `[in]` | hnd | Queue handle.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | Queue | entry count

Qmss_QueueHnd Qmss_getQueueHandle | ( | Qmss_Queue | queue | ) |

Description
Given the queue manager and queue number within the queue manager the function returns the corresponding queue handle

Parameters:

  `[in]` | queue | Queue Manager number and Queue Number within the Queue Manager

Return values:

  | Queue | handle corresponding to the queue manager and queue number

Qmss_Queue Qmss_getQueueNumber | ( | Qmss_QueueHnd | hnd | ) |

Description
Given the queue handle the function returns the queue manager and queue number within the queue manager corresponding to the handle

Parameters:

  `[in]` | hnd | Queue handle

Return values:

  | Queue | Manager and Queue Number within the Queue Manager

static uint32_t Qmss_getQueuePacketSize | ( | Qmss_QueueHnd | hnd | ) | `[inline, static]`

Description
This function returns the packet size of the packet queued at the head of the queue.

Parameters:

  `[in]` | hnd | Queue handle.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | Queue | packet size

static Qmss_QueuePushHnd Qmss_getQueuePushHandle | ( | Qmss_QueueHnd | hnd | ) | `[inline, static]`

Description
Given the queue handle the function returns the address of queue management register D. register D is used to write the descriptor address during a queue push operation.

Parameters:

  `[in]` | hnd | Queue handle

Return values:

  | 4 | byte memory address.

uint32_t Qmss_getQueueThreshold | ( | Qmss_QueueHnd | hnd | ) |

Description
This function returns the threshold at which the queue threshold pin is asserted

Parameters:

  `[in]` | hnd | Queue handle.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | Queue | threshold

uint16_t Qmss_getQueueThresholdStatus | ( | Qmss_QueueHnd | hnd | ) |

Description
This function returns the threshold status of the queue. There are 2 conditions under which the threshold bit is set

The threshold bit is set for a queue if the number of element in a queue is above or below a certain threshold number of items configured using Qmss_setQueueThreshold() API.

The threshold bit is set for a queue if there is atleast 1 element on the queue when the threshold is not set Qmss_setQueueThreshold() API

Parameters:

  `[in]` | hnd | Queue handle.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | 0 | - Configured threshold is not met
  | 1 | - Configured threshold is met

uint32_t Qmss_getStarvationCount | ( | Qmss_QueueHnd | hnd | ) |

Description
The starvation count is incremented every time the Free Descriptor/Buffer queue is read when empty. This function returns the starvation count of queue.

Parameters:

  `[in]` | hnd | Queue handle.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | 8 | bit Starvation count

uint32_t Qmss_getVersion | ( | void |  | ) |

Description
The function is used to get the version information of the QMSS LLD.

Return values:

  | Version | Information.

const char* Qmss_getVersionStr | ( | void |  | ) |

Description
The function is used to get the version string for the QMSS LLD.

Return values:

  | Version | String.

Qmss_Result Qmss_init | ( | Qmss_InitCfg * | initCfg,
|  | Qmss_GlobalConfigParams * | qmssGblCfgParams |
| ) |  |  |

Description
This function initializes the Queue Manager subsystem low level driver This function is called once in the system to setup the queue manager low level driver with information pertaining to linking RAM and descriptor memory region.

Parameters:

  `[in]` | initCfg | Initialization structure that contains memory region configuration information. Linking RAM memory address should be a global address
  `[in]` | qmssGblCfgParams | Initialization structure that contains the QMSS device specific information.

Postcondition:
  QMSS instance is created.

Return values:

  | Success | - QMSS_SOK
  | Failure | - QMSS_INVALID_PARAM
  | Failure | - QMSS_RESOURCE_INIT_DENIED
  | Failure | - QMSS_RESOURCE_LINKING_RAM0_INIT_DENIED
  | Failure | - QMSS_RESOURCE_LINKING_RAM1_INIT_DENIED

Qmss_QueueHnd Qmss_initDescriptor | ( | Qmss_DescCfg * | descCfg,
|  | uint32_t * | numAllocated |
| ) |  |  |

Description
This function is used to obtain previously allocated descriptors. The function opens a destination queue as specified in the input parameters and pushes the requested number of descriptors if available onto it.

Parameters:

  `[in]` | descCfg | Specifies the number of descriptors, memory region from where it should be allocated and the destination queue to push to.
  `[out]` | numAllocated | Number of descriptors actually allocated.

Precondition:
  Qmss_init function should be called before calling this function.

Return values:

  | Success | - Destination queue handle on which the allocated descriptors are stored. The queue must be closed by the caller using Qmss_queueClose() when done.
  | Failure | - QMSS_NOT_INITIALIZED
  | Failure | - QMSS_INVALID_PARAM
  | Failure | - QMSS_MEMREGION_NOT_INITIALIZED
  | Failure | - QMSS_QUEUE_OPEN_ERROR
  | Failure | - QMSS_RESOURCE_MEM_REGION_USE_DENIED

Qmss_Result Qmss_insertMemoryRegion | ( | Qmss_MemRegInfo * | memRegCfg | ) |

Description
This function is used to configure memory region at runtime. The function configures specified memory region with descriptor base address, descriptor size and the number of descriptors.

Parameters:

  `[out]` | memRegCfg | Pointer to the memory region configuration structure allocated by caller. Descriptor memory address should be a global address

Precondition:
  Qmss_init function should be called before calling this function. Memory Region specified should not have been configured before.

Return values:

  | Success | - Inserted Memory region index. Range is 0 to 19.
  | Failure | - QMSS_INVALID_PARAM
  | Failure | - QMSS_NOT_INITIALIZED
  | Failure | - QMSS_MEMREGION_ALREADY_INITIALIZED
  | Failure | - QMSS_MEMREGION_INVALID_PARAM
  | Failure | - QMSS_MAX_DESCRIPTORS_CONFIGURED
  | Failure | - QMSS_MEMREGION_INVALID_INDEX
  | Failure | - QMSS_MEMREGION_OVERLAP
  | Failure | - QMSS_QUEUE_OPEN_ERROR
  | Failure | - QMSS_RESOURCE_MEMORY_REGION_INIT_DENIED
  | Failure | - QMSS_RESOURCE_LINKING_RAM_INIT_DENIED

Qmss_Result Qmss_programAccumulator | ( | Qmss_PdspId | pdspId,
|  | Qmss_AccCmdCfg * | cfg |
| ) |  |  |

Description
This function programs the accumulator with values passed in the cfg structure

Parameters:

  `[in]` | pdspId | Accumulator to program Qmss_PdspId_PDSP1 selects firmware downloaded to PDSP 1 Qmss_PdspId_PDSP2 selects firmware downloaded to PDSP 2
  `[in]` | cfg | Initialization structure that contains accumulator configurable fields

Postcondition:
  Accumulator channel is programmed.

Return values:

  | Value | reported by accumulator
  | Success | - QMSS_ACC_SOK
  | Failure | - QMSS_NOT_INITIALIZED
  | Failure | - QMSS_INVALID_PARAM
  | Failure | - Accumulator status - QMSS_ACC_IDLE, QMSS_ACC_INVALID_COMMAND, QMSS_ACC_INVALID_CHANNEL, QMSS_ACC_CHANNEL_NOT_ACTIVE, QMSS_ACC_CHANNEL_ALREADY_ACTIVE, QMSS_ACC_INVALID_QUEUE_NUMBER, QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_programDiversionQueue | ( | Qmss_PdspId | pdspId,
|  | Qmss_QueueHnd | divQ,
|  | Qmss_QueueHnd | divCompletionQ |
| ) |  |  |

Description
The Accumulator firmware supports an optional diversion queue which can be used remotely cause a queue diversion. When enabled, any descriptor placed on the diversion queue will be loaded, and its Timestamp field will be written to the QM diversion register. The descriptor pointer will then be pushed onto the diversion completion queue.

Setting the diversion queue to ‘0’ disables diversion queue monitoring. The firmware initializes with a default diversion queue of ‘0’ (disabled).

Parameters:

  `[in]` | pdspId | Accumulator to program Qmss_PdspId_PDSP1 selects firmware downloaded to PDSP 1 Qmss_PdspId_PDSP2 selects firmware downloaded to PDSP 2
  `[in]` | divQ | Diversion queue handle. This is the queue which is monitored for diversion requests
  `[in]` | divCompletionQ | Return queue handle. After diversion request is completed, the descriptor is returned in this queue.

Postcondition:
  Diversion queue is configured.

Return values:

  | Value | reported by accumulator
  | Success | - QMSS_ACC_SOK
  | Failure | - QMSS_NOT_INITIALIZED
  | Failure | - QMSS_INVALID_PARAM
  | Failure | - Accumulator status - QMSS_ACC_IDLE, QMSS_ACC_INVALID_COMMAND

Qmss_Result Qmss_programReclaimQueue | ( | Qmss_PdspId | pdspId,
|  | Qmss_QueueHnd | hnd |
| ) |  |  |

Description

The Accumulator firmware also supports an optional reclamation queue which can be used for packet discards. Any descriptor placed on the reclamation queue will be recycled in the same manner as if it had been submitted to CDMA.

The descriptor packet information field is used to determine the return queue and the return handling, including options to unlink host descriptors and push to either the front or the back of the return queue. Setting queue to zero disables the reclamation feature

Parameters:

  `[in]` | pdspId | Accumulator to program Qmss_PdspId_PDSP1 selects firmware downloaded to PDSP 1 Qmss_PdspId_PDSP2 selects firmware downloaded to PDSP 2
  `[in]` | hnd | Reclamation queue number

Postcondition:
  Reclamation queue is configured.

Return values:

  | Value | reported by accumulator
  | Success | - QMSS_ACC_SOK
  | Failure | - QMSS_NOT_INITIALIZED
  | Failure | - Accumulator status - QMSS_ACC_IDLE, QMSS_ACC_INVALID_COMMAND

Qmss_Result Qmss_putCfgQosSchedPort | ( | uint32_t | port,
|  | Qmss_QosSchedPortCfg * | cfg |
| ) |  |  |

Description
This function is used to configure a QoS scheduler port. The configuration operates on a shadow configuration such that the configuration can occur whether or not the port is enabled.

The entire configuration must be specified. If unknown the previous config can be retrieved with Qmss_getCfgQosSchedPort then modified.

This function copies the new configuration to the shadow area, then sends a command to the firmware to accept the change. This minimizes network downtime during reconfiguration.

If the queues or groups are renumbered by changing counts, the descriptors are left in the original queues. Thus if renumbering is needed, it is suggested to disable the port before reconfiguring. If only the credits are changed, the reconfiguration should be done with the port enabled.

Parameters:

  `[in]` | port | Port to configure - Valid range is 0 to QMSS_QOS_SCHED_MAX_PHYS_PORTS
  `[in]` | cfg | Port configuration parameters

Return values:

  | Success | - QMSS_QOS_SCHED_RETCODE_SUCCESS
  | Failure | - The following errors are detected by the firmware: QMSS_QOS_SCHED_INVALID_INDEX The following errors are detected by the LLD: QMSS_QOS_SCHED_INVALID_PORT QMSS_QOS_SCHED_INVALID_GROUP QMSS_QOS_SCHED_INVALID_QUEUE QMSS_QOS_SCHED_INVALID_WRRTYPE QMSS_QOS_SCHED_INVALID_CIRTYPE QMSS_QOS_SCHED_INVALID_CONGTYPE QMSS_QOS_SCHED_INVALID_QUEUE_NUM

Qmss_Result Qmss_queueClose | ( | Qmss_QueueHnd | hnd | ) |

Description
This function closes a queue. The queue reference count is decremented. The queue is freed only if the reference count is zero.

Parameters:

  `[in]` | hnd | Queue handle.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Postcondition:
  Queue is freed if the reference count is zero and available for reallocation.

Return values:

  | Success | - Current reference count.
  | Failure | - QMSS_INVALID_PARAM

static void Qmss_queueDivert | ( | Qmss_QueueHnd | srcQnum,
|  | Qmss_QueueHnd | dstQnum,
|  | Qmss_Location | location |
| ) |  |  | `[inline, static]`

Description
This function diverts the entire content of source queue to the destination queue. "location" indicates whether the contents should be merged on to the head or tail of the destination queue.

Parameters:

  `[in]` | srcQnum | Source queue handle.
  `[in]` | dstQnum | Destination queue handle.
  `[in]` | location | Head/Tail.

Precondition:
  Qmss_queueOpen function for source queue and destination queue should be called before calling this function.

Postcondition:
  Contents of source queue is moved to the destination queue. Source queue is empty.

Return values:

  | None |

static void Qmss_queueEmpty | ( | Qmss_QueueHnd | hnd | ) | `[inline, static]`

Description
This function deletes all the contents of the queue.

Parameters:

  `[in]` | hnd | Queue handle.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Postcondition:
  Queue is empty

Return values:

  | None |

Qmss_QueueHnd Qmss_queueOpen | ( | Qmss_QueueType | queType,
|  | int32_t | queNum,
|  | uint8_t * | isAllocated |
| ) |  |  |

Description
This function opens the requested queue. A queue can be opened in two ways: 1) If "queNum" is set to QMSS_PARAM_NOT_SPECIFIED, then a new available queue of type "queType" is allocated. 2) If "queNum" is a valid queue number i.e., >= 0, then a queue is allocated if free else a handle to a previously opened queue is returned. In this case "queType" parameter is not used.

Parameters:

  `[in]` | queType | Specifies the type of queue that should be opened.
  `[in]` | queNum | Specifies the queue number that should be opened.
  `[out]` | isAllocated | Indicates whether the requested queue is a new queue allocation(1). or was already allocated. If the queue was previously allocated this parameter returns the reference count.

Return values:

  | Success | - Queue Handle. Used as an input parameter for operation on this queue.
  | Failure | - QMSS_RESOURCE_USE_DENIED
  | Failure | - <0

Qmss_QueueHnd Qmss_queueOpenInRange | ( | uint32_t | startQueNum,
|  | uint32_t | endQueNum,
|  | uint8_t * | isAllocated |
| ) |  |  |

Description
This function opens the requested queue if a free queue is avialable within the given start and end range.

Parameters:

  `[in]` | startQueNum | Specifies the start of the queue number range.
  `[in]` | endQueNum | Specifies the end of the queue number range.
  `[out]` | isAllocated | Indicates whether the requested queue is a new queue allocation(1). or was already allocated. If the queue was previously allocated this parameter returns the reference count.

Return values:

  | Success | - Queue Handle. Used as an input parameter for operation on this queue.
  | Failure | - <0

static void* Qmss_queuePop | ( | Qmss_QueueHnd | hnd | ) | `[inline, static]`

Description
This function pop's a descriptor off the queue specified by the queue handle.

The lower 4 bits of the descriptor address contain the size of the descriptor that was specified during the queue push operation. Caller should mask the lower order 4 bits before using the descriptor.

**No validation is done on the input parameters**

Parameters:

  `[in]` | hnd | Queue handle.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | Success | - Descriptor address and size
  | 0 | - If queue is empty

static void Qmss_queuePopDescSize | ( | Qmss_QueueHnd | hnd,
|  | void ** | descAddr,
|  | uint32_t * | packetSize |
| ) |  |  | `[inline, static]`

Description
This function pop's a descriptor off the queue specified by the queue handle. It also returns the packet size of the popped decriptor. The packet size is available only if it was specified during the push operation.

**This function is not multicore/multithread safe.**

It is possible that the descriptor is popped by another core/task between the time taken to read the packet size and the descriptor address by the first core/task.

The caller should provide appropriate locks.

The packet size field is part of the descriptor and should be used to ensure correctness.

The lower 4 bits of the descriptor address contain the size of the descriptor that was specified during the queue push operation. Caller should mask the lower order 4 bits before using the descriptor.

**No validation is done on the input parameters**

Parameters:

  `[in]` | hnd | Queue handle.
  `[out]` | descAddr | Descriptor address and size.
  `[out]` | packetSize | Packet size in bytes.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | None |

static void Qmss_queuePush | ( | Qmss_QueueHnd | hnd,
|  | void * | descAddr,
|  | uint32_t | packetSize,
|  | uint32_t | descSize,
|  | Qmss_Location | location |
| ) |  |  | `[inline, static]`

Description
This function pushes a descriptor onto a queue specified by the queue handle. The "descSize" is used to specify the size of the descriptor being pushed. The optional parameter "packetSize" is used specify the size of packet during pop operation. The optional parameter "location" is used to override the default(tail) and push the packet to the head of the queue.

**No validation is done on the input parameters**.

Parameters:

  `[in]` | hnd | Queue handle.
  `[in]` | descAddr | Memory address of the descriptor. Should be a global address.
  `[in]` | packetSize | Size of packet pointed to by the descriptor.
  `[in]` | descSize | Size of the descriptor. Minimum size is 16 bytes. Maximum size is 256 bytes
  `[in]` | location | 0 - Tail. 1 - Head

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | None |

static void Qmss_queuePushDesc | ( | Qmss_QueueHnd | hnd,
|  | void * | descAddr |
| ) |  |  | `[inline, static]`

Description
It pushes a descriptor onto a queue specified by the queue handle. Does not allow specifying optional parameters. The descriptor size is not written to the queue. This function should be used to push descriptors that will not be prefetched by the CPDMA.

Parameters:

  `[in]` | hnd | Queue handle.
  `[in]` | descAddr | Memory address of the descriptor. Should be a global address.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | None |

static void Qmss_queuePushDescSize | ( | Qmss_QueueHnd | hnd,
|  | void * | descAddr,
|  | uint32_t | descSize |
| ) |  |  | `[inline, static]`

Description
It pushes a descriptor onto a queue specified by the queue handle. Does not allow specifying optional parameters.

The "descSize" is used to specify the size of the descriptor being pushed. This function should be used to push descriptors that will be prefetched by the CPDMA.

**No validation is done on the input parameters**.

Parameters:

  `[in]` | hnd | Queue handle.
  `[in]` | descAddr | Memory address of the descriptor. Should be a global address.
  `[in]` | descSize | Size of the descriptor. Minimum size is 16 bytes. Maximum size is 256 bytes

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | None |

Qmss_Result Qmss_resetQosQueueStats | ( | uint32_t | queIndex | ) |

Description
This function is used to reset the statistics(Forwarded and Dropped packet count) of a queue

Parameters:

  `[in]` | queIndex | Index of the queue whose stats are to be reset - Valid range is 0 to 31

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - QMSS_QCMD_INVALID_INDEX
  | Failure | - QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_setEoiVector | ( | Qmss_IntdInterruptType | type,
|  | uint8_t | accumCh |
| ) |  |  |

Description
This function sets the end of interrupt vector value for the specified interrupt. This API is used by the host to indicate

- The end of interrupt processing to the accumulator. The accumulator is then free to write to the accumulator ping/pong page released by the host.
- The end of interrupt processing for buffer descriptor starvation event on receive SOP and MOP for any of the RX DMA units in the CDMA.

Parameters:

  `[in]` | type | Interrupt to program. Qmss_IntdInterruptType_HIGH selects the interrupts corresponding to the high priority accumulator Qmss_IntdInterruptType_LOW selects the interrupts corresponding to the low priority accumulator Qmss_IntdInterruptType_CDMA selects the interrupts corresponding to the low priority accumulator
  `[in]` | accumCh | Accumulator channel which is mapped to interrupt number via Qmss_xxxEoiVector mapping table. The resulting interrupt number is set.

**No validation is done to check if the interrupt number is within range to reduce overhead.**

Postcondition:
  EOI vector value is set indicating end of host interrupt processing.

Return values:

  | Success | - QMSS_ACC_SOK
  | Failure | - QMSS_NOT_INITIALIZED
  | Failure | - QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_setQosQueueBase | ( | uint32_t | queueNum | ) |

Description
This function is used to set the QoS ingress base queue number. The QoS ingress queue are restricted to a set of 64 starting at a fixed base which must be a multiple of 32.

Each device has a block of queues reserved for this purpose. It is defined in CSL as QMSS_TRAFFIC_SHAPING_QUEUE_BASE and QMSS_MAX_TRAFFIC_SHAPING_QUEUE.

On some devices, the QMSS_MAX_TRAFFIC_SHAPING_QUEUE may be limited to something less than 64. If more queues are needed, then the traffic shaping/QoS subsystem allows any range of general purpose queues used. In other words, QMSS_TRAFFIC_SHAPING_QUEUE_BASE is just a suggestion.

If general queues are used, they should be reserved through Qmss_queueOpen, similar to example code in test_descAlloc.c inside QOS_TEST.

**No validation is done on the input parameters**.

Parameters:

  `[in]` | queueNum | Base queue number

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - Command buffer return status - QMSS_QCMD_INVALID_COMMAND, QMSS_QCMD_INVALID_INDEX, QMSS_QCMD_INVALID_OPTION, QMSS_RESOURCE_INIT_DENIED

Qmss_Result Qmss_setQosSchedQueueBase | ( | uint32_t | queueNum | ) |

Description
This function is used to set the QoS ingress base queue number. The QoS ingress queue are restricted to a set of 80 starting at a fixed base which must be a multiple of 32.

The queues are statically mapped to ports and groups. Assuming there are 8 queues per group and 5 groups per port the assignment is:

Port | Group | Assigned Queues
--- | --- | ---
0 | 0 | base + 0 - 7
0 | 1 | base + 8 -15
0 | 2 | base + 16-23
0 | 3 | base + 24-31
0 | 4 | base + 32-39
1 | 0 | base + 40-47
1 | 1 | base + 48-55
1 | 2 | base + 56-63
1 | 3 | base + 64-71
1 | 4 | base + 72-79

Each device has a block of queues reserved for this purpose. It is defined in CSL as QMSS_TRAFFIC_SHAPING_QUEUE_BASE and QMSS_MAX_TRAFFIC_SHAPING_QUEUE.

On some devices, the QMSS_MAX_TRAFFIC_SHAPING_QUEUE may be limited to something less than 80. If more queues are needed, then the traffic shaping/QoS subsystem allows any range of general purpose queues used. In other words, QMSS_TRAFFIC_SHAPING_QUEUE_BASE is just a suggestion.

If general queues are used, they should be reserved through Qmss_queueOpen, similar to example code in test_descAlloc.c inside QOS_TEST.

**No validation is done on the input parameters**.

Parameters:

  `[in]` | queueNum | Base queue number

Return values:

  | Success | - QCMD_RETCODE_SUCCESS
  | Failure | - Command buffer return status - QMSS_QOS_SCHED_INVALID_COMMAND, QMSS_QOS_SCHED_INVALID_INDEX, QMSS_QOS_SCHED_INVALID_OPTION

Qmss_Result Qmss_setQueueThreshold | ( | Qmss_QueueHnd | hnd,
|  | uint16_t | hilo,
|  | uint8_t | threshold |
| ) |  |  |

Description
This function sets the threshold at which the queue threshold pin is asserted and threshold bit in threshold status register is set. "hilo" indicates whether the number of items in the queue should be greater than/equal to OR less than the confgiured threshold value before the queue ecnt status bit is asserted and threshold bit in threshold status register is set. The threshold value is 10'h3ff when it is ten or higher. It is (2^threshold-1) for other values.

Parameters:

  `[in]` | hnd | Queue handle.
  `[in]` | hilo | 1 - High 0 - Low.
  `[in]` | threshold | Threshold value.

Precondition:
  Qmss_queueOpen function should be called before calling this function.

Return values:

  | Qmss_Result |

Qmss_Result Qmss_start | ( | void |  | ) |

Description
This function initializes the Queue Manager SubsSystem local object blocks in memory local to each core.

This function must be called atleast once for every core.

Precondition:
  Qmss_init function should be called before calling this function.

Return values:

  | Success | - QMSS_SOK
  | Failure | - QMSS_NOT_INITIALIZED

Qmss_Result Qmss_startCfg | ( | Qmss_StartCfg * | startCfg | ) |

Description
This function initializes the Queue Manager SubsSystem local object blocks in memory local to each core and initializes any start parameters like the RM instance.

This function must be called atleast once for every core. It can either be called directly through the application if RM is to be used or it will be called via Qmss_start if RM is not to be used.

Precondition:
  Qmss_init function should be called before calling this function.

Return values:

  | Success | - QMSS_SOK
  | Failure | - QMSS_NOT_INITIALIZED

Copyright 2012, Texas Instruments Incorporated