Queueing Disciplines
[Traffic Control]


Detailed Description

Qdisc Handles
In general, qdiscs are identified by the major part of a traffic control handle (the upper 16 bits).

A few special values exist though:

1) Adding a Qdisc
 // Allocate a new empty qdisc to be filled out
 struct rtnl_qdisc *qdisc = rtnl_qdisc_alloc();

 // ... specify the kind of the Qdisc
 rtnl_qdisc_set_kind(qdisc, "pfifo");

 // Specify the device the qdisc should be attached to
 rtnl_qdisc_set_ifindex(qdisc, ifindex);

 // ... specify the parent qdisc
 rtnl_qdisc_set_parent(qdisc, TC_H_ROOT);

 // Specifying the handle is not required but makes reidentifying easier
 // and may help to avoid adding a qdisc twice.
 rtnl_qdisc_set_handle(qdisc, 0x000A0000);

 // Now on to specify the qdisc specific options, see the relevant qdisc
 // modules for documentation, in this example we set the upper limit of
 // the packet fifo qdisc to 64
 rtnl_qdisc_fifo_set_limit(qdisc, 64);

 rtnl_qdisc_add(handle, qdisc, NLM_R_REPLACE);

 // Free up the memory
 rtnl_qdisc_put(qdisc);
2) Deleting a Qdisc
 // Allocate a new empty qdisc to be filled out with the parameters
 // specifying the qdisc to be deleted. Alternatively a fully equiped
 // Qdisc object from a cache can be used.
 struct rtnl_qdisc *qdisc = rtnl_qdisc_alloc();

 // The interface index of the device the qdisc is on and the parent handle
 // are the least required fields to be filled out.
 // Note: Specify TC_H_ROOT or TC_H_INGRESS as parent handle to delete the
 //       root respectively root ingress qdisc.
 rtnl_qdisc_set_ifindex(qdisc, ifindex);
 rtnl_qdisc_set_parent(qdisc, parent_handle);

 // If required for identification, the handle can be specified as well.
 rtnl_qdisc_set_handle(qdisc, qdisc_handle);

 // Not required but maybe helpful as sanity check, the kind of the qdisc
 // can be specified to avoid mistakes.
 rtnl_qdisc_set_kind(qdisc, "pfifo");

 // Finally delete the qdisc with rtnl_qdisc_delete(), alternatively
 // rtnl_qdisc_build_delete_request() can be invoked to generate an
 // appropritate netlink message to send out.
 rtnl_qdisc_delete(handle, qdisc);

 // Free up the memory
 rtnl_qdisc_put(qdisc);


Modules

 Blackhole
 Class Based Queueing (CBQ)
 Differentiated Services Marker (DSMARK)
 Packet/Bytes FIFO (pfifo/bfifo)
 The FIFO qdisc comes in two flavours:.
 Hierachical Token Bucket (HTB)
 Network Emulator
 For further documentation see http://linux-net.osdl.org/index.php/Netem.
 (Fast) Prio
 
1) Typical PRIO configuration

 Random Early Detection (RED)
 Stochastic Fairness Queueing (SFQ)
 
Parameter Description
  • Quantum: Number of bytes to send out per slot and round.

 Token Bucket Filter (TBF)

Data Structures

struct  rtnl_qdisc_ops
 Qdisc Operations. More...

QDisc Module API

int rtnl_qdisc_register (struct rtnl_qdisc_ops *ops)
 Register a qdisc module.
int rtnl_qdisc_unregister (struct rtnl_qdisc_ops *ops)
 Unregister a qdisc module.

QDisc Addition

nl_msg * rtnl_qdisc_build_add_request (struct rtnl_qdisc *qdisc, int flags)
 Build a netlink message to add a new qdisc.
int rtnl_qdisc_add (struct nl_handle *handle, struct rtnl_qdisc *qdisc, int flags)
 Add a new qdisc.

QDisc Modification

nl_msg * rtnl_qdisc_build_change_request (struct rtnl_qdisc *qdisc, struct rtnl_qdisc *new)
 Build a netlink message to change attributes of a existing qdisc.
int rtnl_qdisc_change (struct nl_handle *handle, struct rtnl_qdisc *qdisc, struct rtnl_qdisc *new)
 Change attributes of a qdisc.

QDisc Deletion

nl_msg * rtnl_qdisc_build_delete_request (struct rtnl_qdisc *qdisc)
 Build a netlink request message to delete a qdisc.
int rtnl_qdisc_delete (struct nl_handle *handle, struct rtnl_qdisc *qdisc)
 Delete a qdisc.

General

rtnl_qdisc * rtnl_qdisc_alloc (void)
 Allocate a new qdisc object.
void rtnl_qdisc_put (struct rtnl_qdisc *qdisc)
 Give back reference on rqdisc object.
void rtnl_qdisc_free (struct rtnl_qdisc *qdisc)
 Free qdisc object.

Qdisc Cache Management

nl_cache * rtnl_qdisc_alloc_cache (struct nl_handle *handle)
 Build a qdisc cache including all qdiscs currently configured in the kernel.
rtnl_qdisc * rtnl_qdisc_get_by_parent (struct nl_cache *cache, int ifindex, uint32_t parent)
 Look up qdisc by its parent in the provided cache.
rtnl_qdisc * rtnl_qdisc_get (struct nl_cache *cache, int ifindex, uint32_t handle)
 Look up qdisc by its handle in the provided cache.

Qdisc Specific Options

nl_msg * rtnl_qdisc_get_opts (struct rtnl_qdisc *qdisc)
 Return qdisc specific options for use in TCA_OPTIONS.

Iterators

void rtnl_qdisc_foreach_child (struct rtnl_qdisc *qdisc, struct nl_cache *cache, void(*cb)(struct nl_object *, void *), void *arg)
 Call a callback for each child class of a qdisc.
void rtnl_qdisc_foreach_cls (struct rtnl_qdisc *qdisc, struct nl_cache *cache, void(*cb)(struct nl_object *, void *), void *arg)
 Call a callback for each filter attached to the qdisc.

Attribute Modification

void rtnl_qdisc_set_ifindex (struct rtnl_qdisc *qdisc, int ifindex)
 Set the interface index of a qdisc to the specified value.
int rtnl_qdisc_get_ifindex (struct rtnl_qdisc *qdisc)
 Get the interface index of a qdisc.
void rtnl_qdisc_set_handle (struct rtnl_qdisc *qdisc, uint32_t handle)
 Set the handle of a qdisc to the specified value.
uint32_t rtnl_qdisc_get_handle (struct rtnl_qdisc *qdisc)
 Get the handle of a qdisc.
void rtnl_qdisc_set_parent (struct rtnl_qdisc *qdisc, uint32_t parent)
 Set the parent handle of a qdisc to the specified value.
uint32_t rtnl_qdisc_get_parent (struct rtnl_qdisc *qdisc)
 Get the parent handle of a qdisc.
void rtnl_qdisc_set_kind (struct rtnl_qdisc *qdisc, const char *name)
 Set the kind of a qdisc to the specified value.
char * rtnl_qdisc_get_kind (struct rtnl_qdisc *qdisc)
 Get the kind of a qdisc.
uint64_t rtnl_qdisc_get_stat (struct rtnl_qdisc *qdisc, enum rtnl_tc_stats_id id)
 Get the statistic specified by the id.


Function Documentation

int rtnl_qdisc_register ( struct rtnl_qdisc_ops ops  ) 

Register a qdisc module.

Parameters:
ops qdisc module operations

Definition at line 130 of file qdisc.c.

References rtnl_qdisc_ops::qo_kind, and rtnl_qdisc_ops::qo_next.

int rtnl_qdisc_unregister ( struct rtnl_qdisc_ops ops  ) 

Unregister a qdisc module.

Parameters:
ops qdisc module operations

Definition at line 151 of file qdisc.c.

References rtnl_qdisc_ops::qo_kind, and rtnl_qdisc_ops::qo_next.

struct nl_msg* rtnl_qdisc_build_add_request ( struct rtnl_qdisc *  qdisc,
int  flags 
)

Build a netlink message to add a new qdisc.

Parameters:
qdisc qdisc to add
flags additional netlink message flags
Builds a new netlink message requesting an addition of a qdisc. The netlink message header isn't fully equipped with all relevant fields and must be sent out via nl_send_auto_complete() or supplemented as needed.

Common message flags used:

Returns:
New netlink message

Definition at line 336 of file qdisc.c.

References NLM_F_CREATE.

Referenced by rtnl_qdisc_add().

int rtnl_qdisc_add ( struct nl_handle *  handle,
struct rtnl_qdisc *  qdisc,
int  flags 
)

Add a new qdisc.

Parameters:
handle netlink handle
qdisc qdisc to delete
flags additional netlink message flags
Builds a netlink message by calling rtnl_qdisc_build_add_request(), sends the request to the kernel and waits for the ACK to be received and thus blocks until the request has been processed.

Common message flags used:

Returns:
0 on success or a negative error code

Definition at line 363 of file qdisc.c.

References nl_send_auto_complete(), nl_wait_for_ack(), nlmsg_free(), and rtnl_qdisc_build_add_request().

struct nl_msg* rtnl_qdisc_build_change_request ( struct rtnl_qdisc *  qdisc,
struct rtnl_qdisc *  new 
)

Build a netlink message to change attributes of a existing qdisc.

Parameters:
qdisc qdisc to change
new new qdisc attributes
Builds a new netlink message requesting an change of qdisc attributes. The netlink message header isn't fully equipped with all relevant fields and must be sent out via nl_send_auto_complete() or supplemented as needed.

Returns:
New netlink message

Definition at line 400 of file qdisc.c.

References NLM_F_REPLACE.

Referenced by rtnl_qdisc_change().

int rtnl_qdisc_change ( struct nl_handle *  handle,
struct rtnl_qdisc *  qdisc,
struct rtnl_qdisc *  new 
)

Change attributes of a qdisc.

Parameters:
handle netlink handle
qdisc qdisc to change
new new qdisc attributes
Builds a netlink message by calling rtnl_qdisc_build_change_request(), sends the request to the kernel and waits for the ACK to be received and thus blocks until the request has been processed.

Returns:
0 on success or a negative error code

Definition at line 418 of file qdisc.c.

References nl_send_auto_complete(), nl_wait_for_ack(), nlmsg_free(), and rtnl_qdisc_build_change_request().

struct nl_msg* rtnl_qdisc_build_delete_request ( struct rtnl_qdisc *  qdisc  ) 

Build a netlink request message to delete a qdisc.

Parameters:
qdisc qdisc to delete
Builds a new netlink message requesting a deletion of a qdisc. The netlink message header isn't fully equipped with all relevant fields and must thus be sent out via nl_send_auto_complete() or supplemented as needed.

Returns:
New netlink message

Definition at line 454 of file qdisc.c.

References nlmsg_append(), nlmsg_build_simple(), tcmsg::tcm_family, tcmsg::tcm_handle, tcmsg::tcm_ifindex, and tcmsg::tcm_parent.

Referenced by rtnl_qdisc_delete().

int rtnl_qdisc_delete ( struct nl_handle *  handle,
struct rtnl_qdisc *  qdisc 
)

Delete a qdisc.

Parameters:
handle netlink handle
qdisc qdisc to delete
Builds a netlink message by calling rtnl_qdisc_build_delete_request(), sends the request to the kernel and waits for the ACK to be received and thus blocks until the request has been processed.

Returns:
0 on success or a negative error code

Definition at line 487 of file qdisc.c.

References nl_send_auto_complete(), nl_wait_for_ack(), nlmsg_free(), and rtnl_qdisc_build_delete_request().

struct rtnl_qdisc* rtnl_qdisc_alloc ( void   ) 

Allocate a new qdisc object.

Returns:
New qdisc object

Definition at line 515 of file qdisc.c.

References nl_object_alloc_from_ops().

void rtnl_qdisc_put ( struct rtnl_qdisc *  qdisc  ) 

Give back reference on rqdisc object.

Parameters:
qdisc Qdisc object to be given back.
Decrements the reference counter and frees the object if the last reference has been released.

Definition at line 527 of file qdisc.c.

References nl_object_put().

void rtnl_qdisc_free ( struct rtnl_qdisc *  qdisc  ) 

Free qdisc object.

Parameters:
qdisc Qdisc object to be freed.
Note:
Always use rtnl_qdisc_put() unless you're absolutely sure that no other user may have a reference on this object.

Definition at line 538 of file qdisc.c.

References nl_object_free().

struct nl_cache* rtnl_qdisc_alloc_cache ( struct nl_handle *  handle  ) 

Build a qdisc cache including all qdiscs currently configured in the kernel.

Parameters:
handle netlink handle
Allocates a new cache, initializes it properly and updates it to include all qdiscs currently configured in the kernel.

Note:
The caller is responsible for destroying and freeing the cache after using it.
Returns:
The cache or NULL if an error has occured.

Definition at line 562 of file qdisc.c.

References nl_cache_alloc_from_ops(), nl_cache_free(), and nl_cache_update().

struct rtnl_qdisc* rtnl_qdisc_get_by_parent ( struct nl_cache *  cache,
int  ifindex,
uint32_t  parent 
)

Look up qdisc by its parent in the provided cache.

Parameters:
cache qdisc cache
ifindex interface the qdisc is attached to
parent parent handle
Returns:
pointer to qdisc inside the cache or NULL if no match was found.

Definition at line 585 of file qdisc.c.

References nl_object_get().

Referenced by rtnl_class_leaf_qdisc().

struct rtnl_qdisc* rtnl_qdisc_get ( struct nl_cache *  cache,
int  ifindex,
uint32_t  handle 
)

Look up qdisc by its handle in the provided cache.

Parameters:
cache qdisc cache
ifindex interface the qdisc is attached to
handle qdisc handle
Returns:
pointer to qdisc inside the cache or NULL if no match was found.

Definition at line 610 of file qdisc.c.

References nl_object_get().

struct nl_msg* rtnl_qdisc_get_opts ( struct rtnl_qdisc *  qdisc  ) 

Return qdisc specific options for use in TCA_OPTIONS.

Parameters:
qdisc qdisc carrying the optiosn
Returns:
new headerless netlink message carrying the options as payload

Definition at line 641 of file qdisc.c.

References rtnl_qdisc_ops::qo_get_opts.

void rtnl_qdisc_foreach_child ( struct rtnl_qdisc *  qdisc,
struct nl_cache *  cache,
void(*)(struct nl_object *, void *)  cb,
void *  arg 
)

Call a callback for each child class of a qdisc.

Parameters:
qdisc the parent qdisc
cache a class cache including all classes of the interface the specified qdisc is attached to
cb callback function
arg argument to be passed to callback function

Definition at line 667 of file qdisc.c.

References nl_cache_foreach_filter(), rtnl_class_alloc(), rtnl_class_put(), rtnl_class_set_ifindex(), rtnl_class_set_kind(), and rtnl_class_set_parent().

void rtnl_qdisc_foreach_cls ( struct rtnl_qdisc *  qdisc,
struct nl_cache *  cache,
void(*)(struct nl_object *, void *)  cb,
void *  arg 
)

Call a callback for each filter attached to the qdisc.

Parameters:
qdisc the parent qdisc
cache a filter cache including at least all the filters attached to the specified qdisc
cb callback function
arg argument to be passed to callback function

Definition at line 693 of file qdisc.c.

References nl_cache_foreach_filter(), rtnl_cls_alloc(), rtnl_cls_put(), rtnl_cls_set_ifindex(), and rtnl_cls_set_parent().

void rtnl_qdisc_set_ifindex ( struct rtnl_qdisc *  qdisc,
int  ifindex 
)

Set the interface index of a qdisc to the specified value.

Parameters:
qdisc qdisc to be changed
ifindex new interface index

Definition at line 721 of file qdisc.c.

int rtnl_qdisc_get_ifindex ( struct rtnl_qdisc *  qdisc  ) 

Get the interface index of a qdisc.

Parameters:
qdisc qdisc handle
Returns:
Interface index or RTNL_LINK_NOT_FOUND if not set

Definition at line 731 of file qdisc.c.

void rtnl_qdisc_set_handle ( struct rtnl_qdisc *  qdisc,
uint32_t  handle 
)

Set the handle of a qdisc to the specified value.

Parameters:
qdisc qdisc to be changed
handle new handle

Definition at line 741 of file qdisc.c.

uint32_t rtnl_qdisc_get_handle ( struct rtnl_qdisc *  qdisc  ) 

Get the handle of a qdisc.

Parameters:
qdisc qdisc handle
Returns:
Handle or 0 if not set

Definition at line 751 of file qdisc.c.

void rtnl_qdisc_set_parent ( struct rtnl_qdisc *  qdisc,
uint32_t  parent 
)

Set the parent handle of a qdisc to the specified value.

Parameters:
qdisc qdisc to be changed
parent new parent handle

Definition at line 761 of file qdisc.c.

uint32_t rtnl_qdisc_get_parent ( struct rtnl_qdisc *  qdisc  ) 

Get the parent handle of a qdisc.

Parameters:
qdisc qdisc handle
Returns:
Parent handle or 0 if not set

Definition at line 771 of file qdisc.c.

void rtnl_qdisc_set_kind ( struct rtnl_qdisc *  qdisc,
const char *  name 
)

Set the kind of a qdisc to the specified value.

Parameters:
qdisc qdisc to be changed
name new kind name

Definition at line 781 of file qdisc.c.

char* rtnl_qdisc_get_kind ( struct rtnl_qdisc *  qdisc  ) 

Get the kind of a qdisc.

Parameters:
qdisc qdisc handle
Returns:
Kind or NULL if not set

Definition at line 792 of file qdisc.c.

uint64_t rtnl_qdisc_get_stat ( struct rtnl_qdisc *  qdisc,
enum rtnl_tc_stats_id  id 
)

Get the statistic specified by the id.

Parameters:
qdisc qdisc handle
id statistic id
Returns:
The current counter of the specified statistic

Definition at line 803 of file qdisc.c.


Generated on Fri Apr 27 14:14:07 2007 for libnl by  doxygen 1.5.1