Rtnl2SetPhysicalTxQueueCbsParams

Rtnl2SetPhysicalTxQueueCbsParams sets the Credit-Based Shaper parameters on a given Physical Transmit Queue.

Syntax

BOOL Rtnl2SetPhysicalTxQueueCbsParams(
  [in]    RTNL2_HPHYSICAL_TX_QUEUE PhysicalTxQueue, 
  [in]    const RTNL2_CBS_PARAMS *pCbsParams, 
  [in]    ULONG CbsParamsStructSize
);

Parameters

[in] PhysicalTxQueue

A handle to the Physical Transmit Queue obtained from Rtnl2AcquirePhysicalTxQueue.

[in] pCbsParams

A description of the Credit-Based Shaper parameters.

[in] CbsParamsStructSize

The size of the RTNL2_CBS_PARAMS structure.

Return Value

If the function succeeds, it returns TRUE. If the function fails, it returns FALSE. Call GetLastError to obtain an error code.

Possible error codes:

Remarks

The caller MUST memset the structure pointed by pCbsParams to zero before populating it, and it MUST set CbsParamsStructSize to sizeof(RTNL2_CBS_PARAMS).

Depending on the underlying hardware, the granularity of the bandwidth setting can be higher than 1 Kbps, in which case the NL2 rounds the passed value up. As a result, the allocated bandwidth may be slightly higher than the requested value. For example, if the granularity is 16 Kbps and the requested value in RTNL2_CBS_PARAMS.RawBandwidthKbps is 12500, the actual bandwidth will be 12512 Kbps.

If the requested bandwidth in RTNL2_CBS_PARAMS.RawBandwidthKbps is greater than the current link speed, the allocated bandwidth will be equal to the link speed. This adjustment is automatically done whenever the link speed changes. For example, if the requested value in RTNL2_CBS_PARAMS.RawBandwidthKbps is 150000, the actual bandwidth will be clamped to 100000 Kbps on a 100 Mbps link, but will revert to 150000 Kbps if the link speed changes to 1 Gbps.

The value of the bandwidth that the application must pass in RTNL2_CBS_PARAMS.RawBandwidthKbps is the raw occupied bandwidth on the wire. It must take into account the 14-byte Ethernet header, the 4-byte VLAN Tag (if any), the payload, the 4-byte FCS, and the 20-byte gap after the frame (this is the minimum space that a sender must insert between the FCS of a frame and the Ethernet header of the next frame). For example, let’s assume you are planning to transmit two TSN streams through a queue using the Credit-Based Shaper. For Stream 1, the payload is 128 bytes, and 8000 frames are generated every second. For Stream 2, the payload is 46 bytes, and 16000 bytes are generated every second. We also assume that both Streams use VLAN Tags. In that case, the bandwidth that must be allocated for the CBS is

(14+4+128+4+20) * 8 * 8000 = 10880000 Kbps for Stream 1

+ (14+4+46+4+20) * 8 * 16000 = 11264000 Kbps for Stream 2

= 22144000 Kbps

In this example, the application must set RTNL2_CBS_PARAMS.RawBandwidthKbps to 22144000

Characteristics

Requirements

See Also:

• Rtnl2AcquirePhysicalTxQueue
• Rtnl2ReleasePhysicalTxQueue