DPDK: Data Plane Development Kit

18.02.0-rc0
rte_sched.h File Reference
#include <sys/types.h>
#include <rte_mbuf.h>
#include <rte_meter.h>

Go to the source code of this file.

Data Structures

struct  rte_sched_subport_stats
struct  rte_sched_queue_stats
struct  rte_sched_port_params

Macros

#define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE   4
#define RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS   4
#define RTE_SCHED_QUEUES_PER_PIPE
#define RTE_SCHED_PIPE_PROFILES_PER_PORT   256

Functions

struct rte_sched_port * rte_sched_port_config (struct rte_sched_port_params *params)
void rte_sched_port_free (struct rte_sched_port *port)
int rte_sched_subport_config (struct rte_sched_port *port, uint32_t subport_id, struct rte_sched_subport_params *params)
int rte_sched_pipe_config (struct rte_sched_port *port, uint32_t subport_id, uint32_t pipe_id, int32_t pipe_profile)
uint32_t rte_sched_port_get_memory_footprint (struct rte_sched_port_params *params)
int rte_sched_subport_read_stats (struct rte_sched_port *port, uint32_t subport_id, struct rte_sched_subport_stats *stats, uint32_t *tc_ov)
int rte_sched_queue_read_stats (struct rte_sched_port *port, uint32_t queue_id, struct rte_sched_queue_stats *stats, uint16_t *qlen)
void rte_sched_port_pkt_write (struct rte_mbuf *pkt, uint32_t subport, uint32_t pipe, uint32_t traffic_class, uint32_t queue, enum rte_meter_color color)
void rte_sched_port_pkt_read_tree_path (const struct rte_mbuf *pkt, uint32_t *subport, uint32_t *pipe, uint32_t *traffic_class, uint32_t *queue)
int rte_sched_port_enqueue (struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts)
int rte_sched_port_dequeue (struct rte_sched_port *port, struct rte_mbuf **pkts, uint32_t n_pkts)

Detailed Description

RTE Hierarchical Scheduler

The hierarchical scheduler prioritizes the transmission of packets from different users and traffic classes according to the Service Level Agreements (SLAs) defined for the current network node.

The scheduler supports thousands of packet queues grouped under a 5-level hierarchy:

  1. Port:
    • Typical usage: output Ethernet port;
    • Multiple ports are scheduled in round robin order with equal priority;
  2. Subport:
    • Typical usage: group of users;
    • Traffic shaping using the token bucket algorithm (one bucket per subport);
    • Upper limit enforced per traffic class at subport level;
    • Lower priority traffic classes able to reuse subport bandwidth currently unused by higher priority traffic classes of the same subport;
    • When any subport traffic class is oversubscribed (configuration time event), the usage of subport member pipes with high demand for thattraffic class pipes is truncated to a dynamically adjusted value with no impact to low demand pipes;
  3. Pipe:
    • Typical usage: individual user/subscriber;
    • Traffic shaping using the token bucket algorithm (one bucket per pipe);
  4. Traffic class:
    • Traffic classes of the same pipe handled in strict priority order;
    • Upper limit enforced per traffic class at the pipe level;
    • Lower priority traffic classes able to reuse pipe bandwidth currently unused by higher priority traffic classes of the same pipe;
  5. Queue:
    • Typical usage: queue hosting packets from one or multiple connections of same traffic class belonging to the same user;
    • Weighted Round Robin (WRR) is used to service the queues within same pipe traffic class.

Definition in file rte_sched.h.

Macro Definition Documentation

#define RTE_SCHED_TRAFFIC_CLASSES_PER_PIPE   4

Random Early Detection (RED) Number of traffic classes per pipe (as well as subport). Cannot be changed.

Examples:
examples/ip_pipeline/config_parse_tm.c, examples/qos_sched/app_thread.c, examples/qos_sched/cfg_file.c, and examples/qos_sched/stats.c.

Definition at line 100 of file rte_sched.h.

#define RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS   4

Number of queues per pipe traffic class. Cannot be changed.

Examples:
examples/ip_pipeline/config_parse_tm.c, examples/qos_sched/app_thread.c, examples/qos_sched/cfg_file.c, and examples/qos_sched/stats.c.

Definition at line 103 of file rte_sched.h.

#define RTE_SCHED_QUEUES_PER_PIPE
Value:
RTE_SCHED_QUEUES_PER_TRAFFIC_CLASS)

Number of queues per pipe.

Definition at line 106 of file rte_sched.h.

#define RTE_SCHED_PIPE_PROFILES_PER_PORT   256

Maximum number of pipe profiles that can be defined per port. Compile-time configurable.

Examples:
examples/qos_sched/init.c.

Definition at line 114 of file rte_sched.h.

Function Documentation

struct rte_sched_port* rte_sched_port_config ( struct rte_sched_port_params params)
read

Hierarchical scheduler port configuration

Parameters
paramsPort scheduler configuration parameter structure
Returns
Handle to port scheduler instance upon success or NULL otherwise.
Examples:
examples/ip_pipeline/init.c, and examples/qos_sched/init.c.
void rte_sched_port_free ( struct rte_sched_port *  port)

Hierarchical scheduler port free

Parameters
portHandle to port scheduler instance
int rte_sched_subport_config ( struct rte_sched_port *  port,
uint32_t  subport_id,
struct rte_sched_subport_params *  params 
)

Hierarchical scheduler subport configuration

Parameters
portHandle to port scheduler instance
subport_idSubport ID
paramsSubport configuration parameters
Returns
0 upon success, error code otherwise
Examples:
examples/ip_pipeline/init.c, and examples/qos_sched/init.c.
int rte_sched_pipe_config ( struct rte_sched_port *  port,
uint32_t  subport_id,
uint32_t  pipe_id,
int32_t  pipe_profile 
)

Hierarchical scheduler pipe configuration

Parameters
portHandle to port scheduler instance
subport_idSubport ID
pipe_idPipe ID within subport
pipe_profileID of port-level pre-configured pipe profile
Returns
0 upon success, error code otherwise
Examples:
examples/ip_pipeline/init.c, and examples/qos_sched/init.c.
uint32_t rte_sched_port_get_memory_footprint ( struct rte_sched_port_params params)

Hierarchical scheduler memory footprint size per port

Parameters
paramsPort scheduler configuration parameter structure
Returns
Memory footprint size in bytes upon success, 0 otherwise
int rte_sched_subport_read_stats ( struct rte_sched_port *  port,
uint32_t  subport_id,
struct rte_sched_subport_stats stats,
uint32_t *  tc_ov 
)

Hierarchical scheduler subport statistics read

Parameters
portHandle to port scheduler instance
subport_idSubport ID
statsPointer to pre-allocated subport statistics structure where the statistics counters should be stored
tc_ovPointer to pre-allocated 4-entry array where the oversubscription status for each of the 4 subport traffic classes should be stored.
Returns
0 upon success, error code otherwise
Examples:
examples/qos_sched/stats.c.
int rte_sched_queue_read_stats ( struct rte_sched_port *  port,
uint32_t  queue_id,
struct rte_sched_queue_stats stats,
uint16_t *  qlen 
)

Hierarchical scheduler queue statistics read

Parameters
portHandle to port scheduler instance
queue_idQueue ID within port scheduler
statsPointer to pre-allocated subport statistics structure where the statistics counters should be stored
qlenPointer to pre-allocated variable where the current queue length should be stored.
Returns
0 upon success, error code otherwise
Examples:
examples/qos_sched/stats.c.
void rte_sched_port_pkt_write ( struct rte_mbuf pkt,
uint32_t  subport,
uint32_t  pipe,
uint32_t  traffic_class,
uint32_t  queue,
enum rte_meter_color  color 
)

Scheduler hierarchy path write to packet descriptor. Typically called by the packet classification stage.

Parameters
pktPacket descriptor handle
subportSubport ID
pipePipe ID within subport
traffic_classTraffic class ID within pipe (0 .. 3)
queueQueue ID within pipe traffic class (0 .. 3)
colorPacket color set
Examples:
examples/qos_sched/app_thread.c.
void rte_sched_port_pkt_read_tree_path ( const struct rte_mbuf pkt,
uint32_t *  subport,
uint32_t *  pipe,
uint32_t *  traffic_class,
uint32_t *  queue 
)

Scheduler hierarchy path read from packet descriptor (struct rte_mbuf). Typically called as part of the hierarchical scheduler enqueue operation. The subport, pipe, traffic class and queue parameters need to be pre-allocated by the caller.

Parameters
pktPacket descriptor handle
subportSubport ID
pipePipe ID within subport
traffic_classTraffic class ID within pipe (0 .. 3)
queueQueue ID within pipe traffic class (0 .. 3)
int rte_sched_port_enqueue ( struct rte_sched_port *  port,
struct rte_mbuf **  pkts,
uint32_t  n_pkts 
)

Hierarchical scheduler port enqueue. Writes up to n_pkts to port scheduler and returns the number of packets actually written. For each packet, the port scheduler queue to write the packet to is identified by reading the hierarchy path from the packet descriptor; if the queue is full or congested and the packet is not written to the queue, then the packet is automatically dropped without any action required from the caller.

Parameters
portHandle to port scheduler instance
pktsArray storing the packet descriptor handles
n_pktsNumber of packets to enqueue from the pkts array into the port scheduler
Returns
Number of packets successfully enqueued
Examples:
examples/qos_sched/app_thread.c.
int rte_sched_port_dequeue ( struct rte_sched_port *  port,
struct rte_mbuf **  pkts,
uint32_t  n_pkts 
)

Hierarchical scheduler port dequeue. Reads up to n_pkts from the port scheduler and stores them in the pkts array and returns the number of packets actually read. The pkts array needs to be pre-allocated by the caller with at least n_pkts entries.

Parameters
portHandle to port scheduler instance
pktsPre-allocated packet descriptor array where the packets dequeued from the port scheduler should be stored
n_pktsNumber of packets to dequeue from the port scheduler
Returns
Number of packets successfully dequeued and placed in the pkts array
Examples:
examples/qos_sched/app_thread.c.