rte_distributor.h File Reference

Go to the source code of this file.

Functions
struct rte_distributor *	rte_distributor_create (const char *name, unsigned int socket_id, unsigned int num_workers, unsigned int alg_type)
int	rte_distributor_process (struct rte_distributor *d, struct rte_mbuf **mbufs, unsigned int num_mbufs)
int	rte_distributor_returned_pkts (struct rte_distributor *d, struct rte_mbuf **mbufs, unsigned int max_mbufs)
int	rte_distributor_flush (struct rte_distributor *d)
void	rte_distributor_clear_returns (struct rte_distributor *d)
int	rte_distributor_get_pkt (struct rte_distributor *d, unsigned int worker_id, struct rte_mbuf **pkts, struct rte_mbuf **oldpkt, unsigned int retcount)
int	rte_distributor_return_pkt (struct rte_distributor *d, unsigned int worker_id, struct rte_mbuf **oldpkt, int num)
void	rte_distributor_request_pkt (struct rte_distributor *d, unsigned int worker_id, struct rte_mbuf **oldpkt, unsigned int count)
int	rte_distributor_poll_pkt (struct rte_distributor *d, unsigned int worker_id, struct rte_mbuf **mbufs)

Detailed Description

RTE distributor

The distributor is a component which is designed to pass packets one-at-a-time to workers, with dynamic load balancing.

Definition in file rte_distributor.h.

Function Documentation

rte_distributor_create()

struct rte_distributor* rte_distributor_create	(	const char *	name,
		unsigned int	socket_id,
		unsigned int	num_workers,
		unsigned int	alg_type
	)

Function to create a new distributor instance

Reserves the memory needed for the distributor operation and initializes the distributor to work with the configured number of workers.

Parameters

name	The name to be given to the distributor instance.
socket_id	The NUMA node on which the memory is to be allocated
num_workers	The maximum number of workers that will request packets from this distributor
alg_type	Call the legacy API, or use the new burst API. legacy uses 32-bit flow ID, and works on a single packet at a time. Latest uses 15- bit flow ID and works on up to 8 packets at a time to workers.

Returns

The newly created distributor instance

Examples:

examples/distributor/main.c.

rte_distributor_process()

int rte_distributor_process	(	struct rte_distributor *	d,
		struct rte_mbuf **	mbufs,
		unsigned int	num_mbufs
	)

Process a set of packets by distributing them among workers that request packets. The distributor will ensure that no two packets that have the same flow id, or tag, in the mbuf will be processed on different cores at the same time.

The user is advocated to set tag for each mbuf before calling this function. If user doesn't set the tag, the tag value can be various values depending on driver implementation and configuration.

This is not multi-thread safe and should only be called on a single lcore.

Parameters

d	The distributor instance to be used
mbufs	The mbufs to be distributed
num_mbufs	The number of mbufs in the mbufs array

Returns

The number of mbufs processed.

Examples:

examples/distributor/main.c.

rte_distributor_returned_pkts()

int rte_distributor_returned_pkts	(	struct rte_distributor *	d,
		struct rte_mbuf **	mbufs,
		unsigned int	max_mbufs
	)

Get a set of mbufs that have been returned to the distributor by workers

This should only be called on the same lcore as rte_distributor_process()

Parameters

d	The distributor instance to be used
mbufs	The mbufs pointer array to be filled in
max_mbufs	The size of the mbufs array

Returns

The number of mbufs returned in the mbufs array.

Examples:

examples/distributor/main.c.

rte_distributor_flush()

int rte_distributor_flush

(

struct rte_distributor *

d

)

Flush the distributor component, so that there are no in-flight or backlogged packets awaiting processing

This should only be called on the same lcore as rte_distributor_process()

Parameters

d	The distributor instance to be used

Returns

The number of queued/in-flight packets that were completed by this call.

Examples:

examples/distributor/main.c.

rte_distributor_clear_returns()

void rte_distributor_clear_returns

(

struct rte_distributor *

d

)

Clears the array of returned packets used as the source for the rte_distributor_returned_pkts() API call.

This should only be called on the same lcore as rte_distributor_process()

Parameters

d	The distributor instance to be used

Examples:

examples/distributor/main.c.

rte_distributor_get_pkt()

int rte_distributor_get_pkt	(	struct rte_distributor *	d,
		unsigned int	worker_id,
		struct rte_mbuf **	pkts,
		struct rte_mbuf **	oldpkt,
		unsigned int	retcount
	)

API called by a worker to get new packets to process. Any previous packets given to the worker is assumed to have completed processing, and may be optionally returned to the distributor via the oldpkt parameter.

Parameters

d	The distributor instance to be used
worker_id	The worker instance number to use - must be less that num_workers passed at distributor creation time.
pkts	The mbufs pointer array to be filled in (up to 8 packets)
oldpkt	The previous packets, if any, being processed by the worker
retcount	The number of packets being returned

Returns

The number of packets in the pkts array

Examples:

examples/distributor/main.c.

rte_distributor_return_pkt()

int rte_distributor_return_pkt	(	struct rte_distributor *	d,
		unsigned int	worker_id,
		struct rte_mbuf **	oldpkt,
		int	num
	)

API called by a worker to return a completed packet without requesting a new packet, for example, because a worker thread is shutting down

Parameters

d	The distributor instance to be used
worker_id	The worker instance number to use - must be less that num_workers passed at distributor creation time.
oldpkt	The previous packets being processed by the worker
num	The number of packets in the oldpkt array

rte_distributor_request_pkt()

void rte_distributor_request_pkt	(	struct rte_distributor *	d,
		unsigned int	worker_id,
		struct rte_mbuf **	oldpkt,
		unsigned int	count
	)

API called by a worker to request a new packet to process. Any previous packets given to the worker are assumed to have completed processing, and may be optionally returned to the distributor via the oldpkt parameter. Unlike rte_distributor_get_pkt(), this function does not wait for new packets to be provided by the distributor.

NOTE: after calling this function, rte_distributor_poll_pkt() should be used to poll for the packets requested. The rte_distributor_get_pkt() API should not be used to try and retrieve the new packets.

Parameters

d	The distributor instance to be used
worker_id	The worker instance number to use - must be less that num_workers passed at distributor creation time.
oldpkt	The returning packets, if any, processed by the worker
count	The number of returning packets

rte_distributor_poll_pkt()

int rte_distributor_poll_pkt	(	struct rte_distributor *	d,
		unsigned int	worker_id,
		struct rte_mbuf **	mbufs
	)

API called by a worker to check for new packets that were previously requested by a call to rte_distributor_request_pkt(). It does not wait for the new packets to be available, but returns if the request has not yet been fulfilled by the distributor.

Parameters

d	The distributor instance to be used
worker_id	The worker instance number to use - must be less that num_workers passed at distributor creation time.
mbufs	The array of mbufs being given to the worker

Returns

The number of packets being given to the worker thread, -1 if no packets are yet available (burst API - RTE_DIST_ALG_BURST) 0 if no packets are yet available (legacy single API - RTE_DIST_ALG_SINGLE)