[deliverable/linux.git] / Documentation / networking / tc-actions-env-rules.txt


The "environmental" rules for authors of any new tc actions are:

1) If you stealeth or borroweth any packet thou shalt be branching
from the righteous path and thou shalt cloneth.

For example if your action queues a packet to be processed later,
or intentionally branches by redirecting a packet, then you need to
clone the packet.

There are certain fields in the skb tc_verd that need to be reset so we
avoid loops, etc.  A few are generic enough that skb_act_clone()
resets them for you, so invoke skb_act_clone() rather than skb_clone().

2) If you munge any packet thou shalt call pskb_expand_head in the case
someone else is referencing the skb. After that you "own" the skb.
You must also tell us if it is ok to munge the packet (TC_OK2MUNGE),
this way any action downstream can stomp on the packet.

3) Dropping packets you don't own is a no-no. You simply return
TC_ACT_SHOT to the caller and they will drop it.

The "environmental" rules for callers of actions (qdiscs etc) are:

*) Thou art responsible for freeing anything returned as being
TC_ACT_SHOT/STOLEN/QUEUED. If none of TC_ACT_SHOT/STOLEN/QUEUED is
returned, then all is great and you don't need to do anything.

Post on netdev if something is unclear.
Commit	Line	Data
d892afe2	1
25985edc	2	The "environmental" rules for authors of any new tc actions are:
d892afe2 JHS	3
	4	1) If you stealeth or borroweth any packet thou shalt be branching
	5	from the righteous path and thou shalt cloneth.
	6
d9195881 ML	7	For example if your action queues a packet to be processed later,
d9195881 ML	8	or intentionally branches by redirecting a packet, then you need to
d892afe2	9	clone the packet.
d9195881	10
d892afe2	11	There are certain fields in the skb tc_verd that need to be reset so we
d9195881 ML	12	avoid loops, etc. A few are generic enough that skb_act_clone()
d9195881 ML	13	resets them for you, so invoke skb_act_clone() rather than skb_clone().
d892afe2 JHS	14
	15	2) If you munge any packet thou shalt call pskb_expand_head in the case
	16	someone else is referencing the skb. After that you "own" the skb.
	17	You must also tell us if it is ok to munge the packet (TC_OK2MUNGE),
	18	this way any action downstream can stomp on the packet.
	19
d9195881	20	3) Dropping packets you don't own is a no-no. You simply return
d892afe2 JHS	21	TC_ACT_SHOT to the caller and they will drop it.
d892afe2 JHS	22
25985edc	23	The "environmental" rules for callers of actions (qdiscs etc) are:
d892afe2	24
d9195881	25	*) Thou art responsible for freeing anything returned as being
d892afe2	26	TC_ACT_SHOT/STOLEN/QUEUED. If none of TC_ACT_SHOT/STOLEN/QUEUED is
d9195881	27	returned, then all is great and you don't need to do anything.
d892afe2 JHS	28
	29	Post on netdev if something is unclear.
	30