Language

click

Click configuration language

Description

The Click language describes Click router configurations.

Two basic statements can implement any router. Declaration statements create elements, and connection statements define packet flow among them. Think of a Click router configuration as a directed graph of elements. Then declarations list the graph’s vertices and connections list its edges.

A declaration looks like this:

name :: class(config);

This introduces an element called name with element class class and configuration arguments config.

A connection looks like this:

name1 [port1] -> [port2] name2;

This connects name1’s output port port1 and name2’s input port port2. The two names must refer to previously declared elements, and the two ports must be nonnegative integers.

Each element must be declared exactly once before being used in any connection. It is an error to declare an element name more than once in the same scope. It is not an error to repeat a connection, however.

Lexically, Click identifiers, such as element names and class names, are sequences of letters, numbers, underscores, at-signs, and slashes that do not begin or end with a slash. Configuration strings are sequences of characters delimited by parentheses, possibly including balanced parentheses and quoted strings. The semicolons that terminate statements are generally optional (in some cases described later they are required to avoid ambiguity). Lexical issues are described in more depth below.

Any configuration can be completely defined with these statements. The rest of the Click language offers extensive shorthand and abstraction features that simplify router programming.

Shorthand

Declaration shorthand

Empty configuration strings can be omitted.

name :: class;

Multiple elements can be declared using a comma-separated list of names.

name1, name2, ..., nameN :: class(config);

You may also declare an element without specifying its name. The system will choose an element name for you. Such elements are called anonymous. For example:

class(config);

is equivalent to

generatedname :: class(config);

The generatedname has the form ‘class@number’; Click chooses the number so that the name is unique. These numbers are predictable: when the system parses a Click file twice, that file’s anonymous elements will get the same generated names each time. Users may also declare elements with names like ‘class@number’, though we suggest that users avoid the ‘@’ character in their element names.

Connection shorthand

You can string together several connections into a single statement if the output element of one is the same as the input element of the other:

a [1] -> [2] x [3] -> [4] b;

means

a [1] -> [2] x;
x [3] -> [4] b;

A missing port number implies port [0]. These two lines mean the same thing:

n1 [0] -> [0] n2;
n1 -> n2;

Elements may also be declared inside connections, either with names or anonymously. For instance,

... -> [p1] name :: class(config) [p2] -> ...;

means

name :: class(config);
... -> [p1] name [p2] -> ...;

Similarly,

... -> [p1] class(config) [p2] -> ...;

means

generatedname :: class(config);
... -> [p1] generatedname [p2] -> ...;

Many-to-one connections

A many-to-one connection connects many elements to the same port.

n1, n2, n3 -> x;

means

n1 -> x;
n2 -> x;
n3 -> x;

Port numbers are supported:

n1 [p1], n2 [p2] -> [p3] x;

means

n1 [p1] -> [p3] x;
n2 [p2] -> [p3] x;

One-to-many connections are also allowed; put the comma-separated list on the right.

You may declare elements within a many-to-one connection, but unlike with declaration shorthand, each declaration applies to only one name. For example

n1, n2 :: class -> n3;

means

n2 :: class;
n1 -> n3;
n2 -> n3;

Note that n1 was not declared.

Many-to-many connections

A many-to-many connection connects many outputs to many inputs. For example, consider a simple Classifier. This code:

c :: Classifier(00/01, 00/02, 00/03);
next :: class;

c [0] -> Paint(0) -> next;
c [1] -> Paint(1) -> next;
c [2] -> Paint(2) -> next;

can more concisely be written like this, using the ‘=>’ many-to-many connector:

c [0], c [1], c [2] => Paint(0), Paint(1), Paint(2) -> next;

or, even more concisely, any of the following:

c [0,1,2] => Paint(0), Paint(1), Paint(2) -> next;
c [0-2] => Paint(0), Paint(1), Paint(2) -> next;
c => Paint(0), Paint(1), Paint(2) -> next;

Each many-to-many connection must list the same number of output ports (on the left) as input ports (on the right). However, if one side of the connection has exactly one element and no port, Click implicitly assigns that element’s ports sequentially starting from 0.

Element groups

Element groups cleanly express small detours from a connection path. For example, consider:

c :: Classifier(00/01);
x -> c -> y;
c [1] -> Paint(1) -> y;

Expressing the detour with an element group preserves the configuration’s overall linear flow:

x -> c :: Classifier(00/01) => (
input [0] -> output;
input [1] -> Paint(1) -> output
) -> y;

An element group is one or more Click statements enclosed in parentheses. Within the parentheses, the special pseudoelements "input" and "output" refer to connections from outside the group. Click expands the group at parse time, so connections through "input" and "output" have no run-time overhead. The following five lines are equivalent:

x -> y;
x -> ( input -> output ) -> y;
x -> ( [0] -> [0] ) -> y;
x -> (->) -> y;
x -> ( [0]->[0]; [1]->[1] ) => ( [0]->[0]; [1]->[1] ) -> y;

Lines three through five use the fact that Click infers "input" at the beginning of a connection, and "output" at the end of a connection, when element names are missing. (This language feature can require explicit semicolons to avoid ambiguity.) Line five also uses the fact that connections may be repeated without error (the line expands to "x -> y; x -> y"). It is an error to use an "input" pseudoelement’s input ports or an "output" pseudoelement’s output ports.

Element groups have implicit, overridable port specifications that list all their ports in sequential order. For example, these three lines are equivalent:

x => ( [0]->[0]; [1]->[1] ) -> y;
x => [0,1] ( [0]->[0]; [1]->[1] ) [0,1] -> y;
x -> y; x [1] -> y;

It is an error to define an element group with nonsequential ports, or to leave one or more of its ports unconnected:

x => [0] ( [0]->[0]; [1]->Idle ) -> y; /* Error! */
x => ( [0]->[0]; [2]->Idle ) -> y; /* Error! */

An element group does not define a new scope. Its contents may refer to elements declared outside of the group, and declarations inside the group are visible after the group closes. This differs from compound elements, described next, which have a related syntax but introduce a new scope.

Compound Elements

A compound element is a scoped collection of elements that behaves like a single element. A compound element can be used anywhere an element class is expected (that is, in a declaration or connection). Syntactically, a compound element is a set of Click statements enclosed in braces ‘{ }’. Inside the braces, the special names ‘input’ and ‘output’ represent connections from or to the outside. Before a router is put on line, compound elements are systematically expanded until none remain; thus, they have no run-time overhead.

Here are some examples. This code, with a compound element,

a -> { input -> X -> output } -> b;

expands to

a -> X -> b;

Here is a more complicated example, with multiple ports:

compound :: {
input -> X -> output;
input [1] -> Y -> [1] output;
};
a -> compound -> b;
c -> [1] compound [1] -> d;

expands to

a -> X -> b;
c -> Y -> d;

The "input" and "output" pseudoelements incur no run-time overhead.

The actual expansions will differ from these examples because the elements will have different names. A prefix is prepended to the components’ names, providing locality relative to other names in the configuration. The new names have the form ‘compoundname/componentname’, where compoundname is the name of the compound element being expanded, and componentname is the name of the component element inside that compound. For example,

compound :: { input -> x :: X -> output };
a -> compound -> b;

is really expanded to

a -> compound/x :: X -> b;

For this purpose, anonymous compound elements are given constructed names like ‘@number’. Nothing prevents a user from declaring an element named like a compound element component. We suggest that users generally avoid using the "/" character in their element names.

It is an error to use an "input" pseudoelement’s input ports or an "output" pseudoelement’s output ports. It is also an error to leave an intermediate port unused—for example, to use "input [0]" and "input [2]" but not "input [1]".

The ‘elementclass’ statement

The ‘elementclass’ statement lets the user name a frequently-occurring compound element, and use the name as if it were a primitive element class. Syntactically, it looks like this:

elementclass identifier compoundelement ;

After this statement, every occurrence of the identifier will be replaced with the compoundelement. For example, this code, with an ‘elementclass’:

elementclass MyQueue {
input -> Queue -> Shaper(1000) -> output;
}
q :: MyQueue;
a -> q -> b;

is equivalent to this code, without it:

q :: { input -> Queue -> Shaper(1000) -> output };
a -> q -> b;

which roughly expands to:

a -> Queue -> Shaper(1000) -> b;

The user can declare element classes that have the names of previously existing element classes:

elementclass Queue {
input -> Queue -> Shaper(1000) -> output;
}

Element classes are nonrecursive and lexically scoped, so the ‘Queue’ inside this definition refers to the original ‘Queue’. The scope of an element class definition extends from immediately after its closing right brace to the end of the enclosing scope.

A variant of the elementclass statement makes synonyms for preexisting element classes. For example, this statement

elementclass MyQueue Queue;

makes MyQueue a synonym for Queue.

Configuration parameters

Compound elements may take configuration parameters, which are expanded into the configuration strings of its components. The parameters are named at the beginning of the compound element. Each parameter looks like a Perl variable—a dollar sign followed by one or more letters, numbers, and underscores. For example, this compound element

{ $a, $b | ... }

takes two configuration parameters, named ‘$a’ and ‘$b’. Keyword arguments are also supported. For example, this compound element

{ COUNT $count | ... }

takes a COUNT keyword parameter. Mismatched configuration parameters cause errors; for example:

{ $a, $b | ... } (1) // Error: too few arguments
{ $a, $b | ... } (1, 2, 3) // Error: too many arguments
{ COUNT $count | ... } (1) // Error: missing ’COUNT’ parameter

The special keyword ‘__REST__’ matches any additional arguments supplied to the compound element. For example:

{ $a, COUNT $count, __REST__ $rest | ... }
(1, 2, COUNT 3, FOO 4)

This compound element will be expanded with ‘$a’ set to ‘1’, ‘$count’ set to ‘3’, and ‘$rest’ set to ‘2, FOO 4’.

In a compound element definition, all positional parameters must precede any keyword parameters, and ‘__REST__’, if present, must appear last of all.

As the compound is expanded, its components’ configuration strings are searched for references to the parameters. Any such references are replaced with the supplied arguments. For example, this code:

... -> { $a | input ->
A(1, $a, 3) -> output } (100) -> ...

expands to this:

... -> A(1, 100, 3) -> ...

You can avoid substitution by putting the dollar #side single quotes.

Use braces, like ‘${a}’, to avoid including following letters in a variable name. Click also supports the shell-like ‘${VAR-DEFAULT}’ syntax, which substitutes the value of ‘$VAR’, or ‘DEFAULT’ if that variable was not set. See also PARAMETER DEFINITIONS, below.

Overloading

A single compound element may contain multiple overloaded definitions separated from one another by two vertical bars "||". Different definitions may have different numbers of input ports, different numbers of output ports, or different sets of configuration arguments. For example, this extended MyQueue compound element takes an optional capacity argument, just like Queue itself:

elementclass MyQueue {
  input -> Queue -> Shaper(1000) -> output;
||
  $cap | input -> Queue($cap)
               -> Shaper(1000) -> output;
}

For each use of an overloaded compound element, Click will choose the first definition that matches the provided number of input ports, number of output ports, and configuration arguments. It is an error if no definition matches these properties exactly.

It is also possible to extend an existing element class with new overloaded definitions with "...". For example, this definition introduces a two-argument version of Queue:

elementclass Queue {
$cap, $rate | input -> Queue($cap)
-> Shaper($rate) -> output;
|| ...
}

(The ellipsis in this example must be typed verbatim.) The overloadings visible at a given declaration are those that lexically precede that declaration. For example, the following example is an error since the two-argument version of Test is not visible at the declaration where it is required:

elementclass Test { $a | /* nothing */ }
test :: Test(1, 2);
elementclass Test { $a, $b | /* nothing */ || ... }

Configuration Strings

Click configuration strings are comma-separated lists of arguments, where each argument is a space-separated list of objects. This section describes some common object types. See the element documentation for argument types expected by a particular element.

Configuration strings may contain comments (‘// ... EOL’ and ‘/* ... */’), which are replaced with single space characters. Inside single- or double-quoted strings, commas, spaces, and comment-starting sequences lose their regular meaning and are treated as normal characters.

The most common object types are:

Strings. Any sequence of characters. Single- or double-quoted strings are allowed (and required, if the string contains a space or comma). Inside double-quoted strings, backslash substitutions are performed; see below. You can concatenate strings by juxtaposing them. For example, ‘a"b"c’ is equivalent to ‘abc’.
Booleans. ‘0’, ‘false’, and ‘no’ mean false; ‘1’, ‘true’, and ‘yes’ mean true.
Integers preceded by an optional ‘+’ or ‘-’ sign. Decimal, octal (first digit ‘0’), and hexadecimal (starting with ‘0x’) are allowed.
Real numbers in decimal notation.
Times and delays in decimal real notation, followed by an optional unit: ‘s’/‘sec’, ‘ms’, ‘us’, ‘ns’, ‘m’/‘min’, ‘h’/‘hr’.
Bandwidths in decimal real notation, followed by an optional unit: ‘bps’ or ‘Bps’ for bits or bytes per second, with an optional SI prefix ‘k’, ‘M’, or ‘G’. The default unit is generally ‘Bps’.
IP addresses in the conventional ‘n.n.n.n’ form (for example, ‘18.26.4.15’).
IP network prefixes in the CIDR form ‘n.n.n.n/k’ (for example, ‘18.26.4/24’).
IPv6 addresses in any of the conventional forms (for example, ‘::’, ‘1080::8:800:200C:417A’, or ‘::18.26.4.15’).
Ethernet addresses in the standard ‘x-x-x-x-x-x’ form (for example, ‘0-a0-c9-9c-fd-9c’), or the more conventional ‘x:x:x:x:x:x’ form.
Element names.

Some elements, like Classifier, take arguments that don’t fit any of these types. See the element documentation for details.

If the last argument in a configuration string is empty (containing only whitespace and comments), then it is ignored. Thus, ‘Element(1, )’, ‘Element(1, /* comment */)’, and ‘Element(1)’ behave exactly alike.

Configuration strings may also contain parameter references, such as ‘$interface’. The parameter values are substituted in. Parameters may be defined either by compound element arguments, by explicit ‘define’ statements, or on the command line.

Backslash Substitutions

The following backslash substitutions are performed inside double quotes. Additionally, as a special case, a bare data substitution sequence ‘\< ... >’ acts as if it were enclosed in double quotes. (Inside single quotes, ‘\< ... >’ is not special.)

C-like substitutions. Specifically, ‘\a’, ‘\b’, ‘\t’, ‘\n’, ‘\v’, ‘\f’, ‘\r’, ‘\\’, and ‘\[1, 2, or 3 octal digits]’ have their C meanings. ‘\x[any number of hex digits]’ is replaced with the byte defined by the last 2 hex digits.
Data substitutions. An escape sequence ‘\< ... hex digits and spaces ... >’ is replaced with the data represented by the hex digits. For example, the sequence ‘\< 48 45 4c 4C 4f >’ is replaced with ‘HELLO’.
Backlash-newline sequences (‘\[LF]’, ‘\[CR]’, or ‘\[CR][LF]’) are removed.
Any other ‘\[CHAR]’ sequence is replaced with ‘[CHAR]’.

Requirements

The ‘require’ statement is used to link a configuration with optional packages and libraries. Its argument is a comma-separated list of requirements.

Packages, which are dynamic objects including new compiled element definitions, are included with ‘require(package)’ declarations:

require(package fastclassifier, package specialcode);

Installation programs can use the package names to find and upload any necessary package code. The required package names are also checked against a list of currently active packages when a configuration is installed. If any required packages are unavailable, an error is reported.

Libraries, which are Click configuration files that (for instance) might declare new compound element definitions, are included with ‘require(library)’ declarations:

require(library mycompounds.click);

Installation programs search CLICKPATH for the named library file. ‘require(library)’ can only be used at file scope, and a given library file is included at most once, no matter how many times it is mentioned in ‘require’ statements.

Parameter Definitions

Parameters are defined using the ‘define’ statement. Its argument is a comma-separated list of pairs, each pair consisting of a configuration variable and a value:

define($DEVNAME eth0, $COUNT 1);

This sets the ‘$DEVNAME’ parameter to ‘eth0’ and the ‘$COUNT’ parameter to ‘1’. Definitions are lexically scoped, so definitions inside a compound element are not visible outside it. However, all definitions in a given scope take place simultaneously, regardless of their ordering. The following two configurations have the same effect:

define($a 2); Message($a)

Message($a); define($a 2)

It is an error to define a parameter more than once in any single scope. Click programs such as click and click-install allow parameters to specified on the command line; these override any global parameters with the same names.

Lexical Issues

Click identifiers are nonempty sequences of letters, numbers, underscores ‘_’, at-signs ‘@’, and slashes ‘/’ that do not begin or end with a slash. The system uses ‘@’ and ‘/’ for special purposes: ‘@’ in constructed names for anonymous elements and prefixes, and ‘/’ in names for components of compound elements. Users are discouraged from using these characters in their own identifiers. Identifiers are case-sensitive. No component of an identifier may consist solely of numbers; for example, ‘1/x’ is an illegal identifier.

The keywords ‘elementclass’, ‘require’, ‘provide’, and ‘define’ may not be used as identifiers. The normal identifiers ‘input’ and ‘output’ have special meaning inside compound element definitions.

The following characters and multi-character sequences are single Click tokens:

-> => :: ; , ( ) [ ] { } | || ...

Whitespace (using the C definition) and comments separate Click tokens. Click uses C++-style comments: from ‘//’ to the end of the line, or from ‘/*’ to the next ‘*/’. Either form of comment terminates an identifier, so this Click fragment

an/identifier/with/slashes//too/many

has an identifier ‘an/identifier/with/slashes’ and a comment ‘//too/many’. No identifier contains two consecutive slashes.

Parameters, which are used in compound elements, look like Perl variables. A parameter consists of a dollar sign ‘$’ followed by one or more letters, numbers, and underscores.

A configuration string starts immediately following a left parenthesis ‘(’, and continues up to the next unbalanced right parenthesis ‘)’. However, parentheses inside single or double quotes or comments do not affect balancing. Here are several examples; in each case, the configuration string consists of the text between the ‘#’ marks (including the ‘#’ marks themselves).

C1(#simple string#)
C2(#string with (balanced parens)#)
C3(#string with ")quoted" paren#)
C4(#// end-of-line comment)
still going!#)
C5(#/* slash-star comment) */ and backslash \#)

A Click program may contain C preprocessor-style line directives. These lines start with ‘#’ and have the form ‘# linenumber "filename"’ or ‘#line linenumber "filename"’; they change the filenames and line numbers used for error messages. The filename portion is optional. Line directives are not recognized inside configuration strings.

BNF Grammar

stmts ::= stmts stmt | empty
stmt ::= connection
    | elementclassstmt | requirestmt
    | definestmt | ";"
connection ::= elements opt-conntail | conntail
opt-conntail ::= conntail | empty
conntail ::= arrow elements opt-conntail | arrow
arrow ::= "->" | "=>"
elements ::= element | elements "," element
element ::= opt-port element-reference opt-port
element-reference ::= element-name
    | element-name "::" class opt-config
    | class opt-config
    | group
element-name ::= identifier
opt-port ::= "[" ports "]" | empty
ports ::= portnumber | ports "," portnumber
opt-config ::= "(" configstring ")" | empty
class ::= identifier | "{" compounds "}"
    | "{" compounds "||" "..." "}"
compounds ::= compound | compounds "||" compound
compound ::= stmts | opt-formals "|" stmts
opt-formals ::= formals | empty
formals ::= formal | formals "," formal
formal ::= parameter | identifier parameter
group ::= "(" stmts ")"
elementclassstmt ::= "elementclass" identifier class
requirestmt ::= "require" "(" configstring ")"
definestmt ::= "define" "(" configstring ")"
empty ::=

Author

Eddie Kohler, kohler@seas.harvard.edu
http://www.pdos.lcs.mit.edu/click/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Language

click

Description

Shorthand

Declaration shorthand

Connection shorthand

Many-to-one connections

Many-to-many connections

Element groups

Compound Elements

The ‘elementclass’ statement

Configuration parameters

Overloading

Configuration Strings

Backslash Substitutions

Requirements

Parameter Definitions

Lexical Issues

Archives

BNF Grammar

See Also

Author

Clone this wiki locally