[LARTC] "Classful Queueing Disciplines" in LARTC HOWTO

[Rob Pitman <rob@pitman.co.za>]

Hi,

I am a newbie to LARTC and to this mailing-list. I have read through the 
Linux Advanced Routing & Traffic Control HOWTO many times, trying to 
understand Classful Queueing Disciplines (and in particular CBQ). I have  
some suggestions that I think will help to make the HOWTO more 
understandable.

Suggestions
====(1)
In section 9.4 (Terminology) the definition for "Classes" states that:

"A classful qdisc may have many classes, which each are internal to the 
qdisc. Each of these classes may contain a real qdisc".

As far as I can understand, each class can actually contain one _or more_ 
qdiscs. Furthermore, (at least in the case of CBQ) a class may also contain 
one or more _classes_ (this really puzzled me. But the HOWTO's example of a 
CBQ configuration, and a reading of /usr/src/linux-2.4/net/sched/sch_cbq.c 
appear to indicate this).


(2)
In section 9.5.2 ("The qdisc family: roots, handles, siblings and parents"), 
the HOWTO does not really make clear the fact that some of the nodes in the 
tree are qdiscs, and some nodes are classes. In particular, the "ASCII-art" 
diagram does not show this; it just shows a bunch of nodes with handles. As 
I understand it, the diagram should be as follows (please tell me if I am 
wrong).


           1:            root qdisc
           |
          1:1            class (child of root qdisc)
         --|--
        /  |  \
       /   |   \
      /    |    \
     /     |     \
    10:   11:    12:     qdiscs contained in 1:1 class
   /  \         /  \
  10:1 10:2   12:1 12:2  classes (children of qdiscs)


Section 9.5.2, paragraph 2 says "The handles of these qdiscs consist of two 
parts...". The text does not explicitly say that _classes_ are also assigned 
handles in the same way (that only became apparent after reading the HOWTO 
several times).


Section 9.5.2 paragraph 3 says "Classes need to have the same major number 
as their parent". Shouldn't this be changed to "Classes need to have the 
same major number as their parent _qdisc_"?


(3)
Section 9.5.2.2 paragraph 1 says "When the kernel decides that it needs to 
extract packets to send to the interface, the root qdisc 1: gets a dequeue 
request, which is passed to 1:1, which is in turn passed to 10:, 11: and 
12: ..". 

I think it would be clearer if this was changed to "....which is passed to 
the 1:1 class, which is in turn passed to the 10:, 11: and 12: qdiscs...".


(4)
Section 9.5.3 ("The PRIO qdisc") has a spelling mistake in paragraph 4: "It 
can also contain more all qdiscs...". I think this should be "It can also 
contain almost all qdiscs...". (I know this is rather nitpicky).


(5)
Section 9.5.3.2 ("Sample configuration") has another ASCII-art diagram where 
it would be clearer if the nodes were labelled as being either qdiscs or 
classes. Node 1: is the root qdisc; nodes 1:1, 1:2 and 1:3 are classes; 
nodes 10:, 20: and 30: are qdiscs.


(6)
Section 9.5.4.2 ("CBQ classful behaviour") paragraph 2: the phrase "lower 
priority classes" should, I believe, be "lower-numbered priority classes" 
(because lower-numbered means higher-priority). The same applies in the 
paragraph that describes the prio parameter.


(7)
Section 9.5.4.4 ("Sample configuration") really took many re-readings to 
understand, and I'm still not sure I do understand. An ASCII-art diagram 
would really help here, showing which nodes are qdiscs and which are 
classes.

The second paragraph starts "This part installs the root node and the 
customary 1:0 class". I think this is an error, it should be the 1:1 class, 
not the 1:0 class.

A bit lower down, the HOWTO shows the commands to add classes 1:3 and 1:4. 
My understanding is that these two _classes_ are being added to the parent 
_class_ 1:1, is this right? This part was confusing, because in previous 
examples _classes_ were added to a parent _qdisc_, or _qdiscs_ were added 
to a parent _class_. This is the first place where _classes_ are added to a 
parent _class_. That's why I suggested (above) that the definition of a 
class be changed to make it clear that a class can contain other classes, 
not only qdiscs.

In the next paragraph the HOWTO says "These are our two classes". But there 
are actually three classes in the configuration. 

In the same paragraph, the last sentence reads "The classids need to be 
within the same major number as the parent CBQ". I think this should be

"The classids need to have the same major number as the parent qdisc"

because it it not clear (except by re-reading a few times) that these two 
classes have _class_ 1:1 as a parent, which in turn has _qdisc_ 1:0 as a 
parent; so classes 1:3 and 1:4 actually need to have the same major number 
as their _grandparent_ node, which is a qdisc.

A bit lower down, the HOWTO shows the commands to attach some filters 
directly to the root qdisc. May I suggest inserting the following sentence 
just _before_ these commands:

'Now we attach "filters" to the root qdisc, to send traffic to the correct 
classes (1:3 and 1:4).'

I hope these suggestions will help to make the HOWTO clearer to the 
uninitiated (like me). Please tell me if I have misunderstood anything.

Regards
Rob Pitman
_______________________________________________
LARTC mailing list / LARTC@mailman.ds9a.nl
http://mailman.ds9a.nl/mailman/listinfo/lartc HOWTO: http://lartc.org/