Click homefaq
 

FAQs about click

General Questions

Is Click experimental software?

Yes.

The Click Linux patch does not apply cleanly to my version of Linux.

Try a version of Linux for which we distribute a specific patch. See the INSTALL file for a list of patches.

How fast can Click route packets?

On a 700 MHz Pentium III, we could get 456,000 64-byte packets a second through a Click router with eight active DEC Tulip fast Ethernet cards. Current rates are also good.

How do you do that?

Device driver improvements, including polling, and language-level optimizations.

Can I get that many packets through a Click router?

You should be able to do that right now if you use DEC Tulip fast Ethernet cards or Intel E1000 gigabit Ethernet cards. These are the main device drivers that we have changed to use our polling extensions to Linux.

How does Click run inside a Linux kernel?

As a kernel thread.

What are the Grid elements?

Grid is a set of protocols for routing in multi-hop ad-hoc wireless networks. See http://pdos.lcs.mit.edu/grid for further details.

How do I search the Click Mailing list archives?

Use Google search with the site:pdos.csail.mit.edu tag.

How do I make a simple Click router configuration?

Edit and run conf/make-ip-conf.pl script to generate a full Click IP router

Click uses 100% of the CPU is this normal?

Click uses push/pull processing and some elements continuously generate push/pull requests even if no packets are present. See http://pdos.csail.mit.edu/papers/click:tocs00/paper.pdf for more details.

Questions About Polling

How can I change a device driver to use the Click polling extensions?

Benjie Chen, who designed the extensions, never wrote a document describing how to do this. For now, you'll have to look at our additions to Linux's 'struct device', and the way they are used by our drivers. You can always write us and ask for help: click@pdos.lcs.mit.edu.

Can I use Click without updating device drivers (that is, without polling)?

Sure. Just use FromDevice elements instead of PollDevice elements. Your performance will generally be worse than Linux; we haven't particularly optimized this.

Creating Your Own Elements

How can I add my own element class to Click?

There are two ways to add an element class to Click: in the main Click collection, or in a package. We recommend that you use packages for nontrivial collections of elements. It has several advantages -- for example, it will keep your code separate from the main Click code. Check out the sample package in 'etc/samplepackage'. However, if you just want to compile a single new element, it will be easier to add it to the main Click collection. This answer shows how.

First, write your element class.

Each element class should be written as two C++ source files, FILE.cc and FILE.hh. The easiest way to create an element this is to copy an existing element and change the C++ class's name. You must change at least the following function:

const char *class_name() const;	// return your element's name

Other common functions to override include:

void push(int i, Packet *);	// process push request on input i
Packet *pull(int i);		// process pull request on output i
Packet *simple_action(Packet *); // for agnostic elements

const char *port_count() const; // return port count code
const char *processing() const; // return processing code
int configure(Vector<String> &, ErrorHandler *);
				// process configuration string
void add_handlers();		// set up element handlers
int initialize(ErrorHandler *);	// initialize element
void cleanup(CleanupStage);	// clean up element state

All these functions are described in the Click programming manual, which is constructed from comments in the source code.

Make sure that your .cc file exports the element class with EXPORT_ELEMENT. For example, the nullelement.cc file ends with:

EXPORT_ELEMENT(NullElement)

EXPORT_ELEMENT takes a single argument, the name of the C++ class corresponding to your element. You can have multiple EXPORT_ELEMENT lines if your source file declares multiple element classes. If your element is meant only for the user-level driver, add this line near EXPORT_ELEMENT:

ELEMENT_REQUIRES(userlevel)

Or, if it is meant for the Linux kernel module:

ELEMENT_REQUIRES(linuxmodule)

ELEMENT_REQUIRES can also take element names and package names like 'ip6':

ELEMENT_REQUIRES(linuxmodule Storage ip6)

Second, put your element in an 'elements/' directory.

Choose the directory that seems most appropriate for your element. Often, this is 'elements/local', which is designed for locally-created elements. If you place your element in 'local', make sure you provide the '--enable-local' argument to 'configure'.

Third, run 'make elemlist'.

'make elemlist' checks the source files in the 'elements/' subdirectories for EXPORT_ELEMENT directives, and compiles a list of elements that Click should compile. After running 'make elemlist', check the 'userlevel/elements.conf' and 'linuxmodule/elements.conf' files to see if your .cc file made it into this list.

Finally, run 'make install'!

You are done.

My element wasn't compiled! Click reports 'unknown element class'.

First, check whether Click's build process found your element, by running grep ELEMENTNAME CLICKDIR/userlevel/elements.conf. (If you are having trouble with the Linux kernel module, search CLICKDIR/linuxmodule/elements.conf instead.) The elements.conf file is generated automatically, and contains information about every element Click plans to compile. If the grep command has no output, then Click didn't find your element. Check these things:

  • Do you have an EXPORT_ELEMENT statement?
  • Does your element require something with ELEMENT_REQUIRES that is not available?
  • Did you run 'make elemlist'?
  • Is the relevant elements/ directory enabled? (For instance, for elements/local, did you run './configure ... --enable-local'?)

If the elements.conf file does list your element, then Click attempted to compile your element and everything should work. If you still get 'unknown element class', check these things:

  • Userlevel only: Are you running an installed version of Click? (For instance, are you typing click FILE.click instead of CLICKDIR/userlevel/click FILE.click?) If so, then you will not be able to use your new element until you run make install.
  • Linuxmodule only: Did you unload the old version of the kernel module and load the new one that contains your element? The easiest way to do this is with make install; click-install -u FILE.click; the -u option unloads & reloads the kernel module.

How can I make Click compile a C++ file that doesn't contain an element?

Add an ELEMENT_PROVIDES statement to your .cc file. The Click build process searches for C and C++ files with 'ELEMENT_PROVIDES' as well as 'EXPORT_ELEMENT'. You'll have to come up with a one-word tag describing the functionality that your .cc file provides. See the end of 'elements/userlevel/fakepcap.cc' for an example; it looks like this:

...
CLICK_ENDDECLS
ELEMENT_REQUIRES(userlevel|ns)
ELEMENT_PROVIDES(FakePcap)

Elements that use the 'FakePcap' functionality explicitly require it with ELEMENT_REQUIRES; see 'elements/userlevel/fromdump.cc' for an example.

One of my elements must be linked against another library. How can I make userlevel Click link with that library?

Add the required linker flags to an 'ELEMENT_LIBS' statement in your element's .cc file. For example:

...
CLICK_ENDDECLS
EXPORT_ELEMENT(MyElement)
ELEMENT_LIBS(-L/usr/local/lib -lmy_library)

Every element that needs a library should contain the relevant ELEMENT_LIBS.

How do I build click statically?

Run configuration with the following CXXFLAGS:

./configure CXXFLAGS="-static" ...

How do I cross compile userlevel click?

This example is taken from building on i386 freebsd for arm linux, and assumes you have the appropriate cross-compile tools, arm-linux-g++, etc.

Start in your top-level cilck source directory and run the following:

 autoconf
./configure --disable-linuxmodule --host=arm-linux --build=i386-bsd --enable-tools=mixed 

--enable-tool=mixed makes some tools be cross-compiled (notably, click-align), and some tools be compiled to run on the build host (i.e. click-mkmindriver, which is part of the build process).

gmake tools elementmap.xml 

This builds the click tools and creates an index of all the elements in click. Take your click configuration, called MY_CONFIG, and tell mkmindriver to create a makefile that builds click with only the elements found in MY_CONFIG:

./tools/click-mkmindriver/click-mkmindriver  -C . -u -A -d./userlevel --elements "Print" -p MY_PKG -f MY_CONFIG 

This will generate a custom makefile which builds MY_PKGclick:

gmake -C ./userlevel/ MINDRIVER=MY_PKG 
arm-linux-strip ./tools/click-align/click-align
arm-linux-strip ./userlevel/MY_PKGclick 

Stripping the debugging symbols will make the binaries smaller. click-align is cross-compiled and stripped so you can dynamically generate a click config on your target archictecture and run click-align on it. (This entry was taken from a message by Douglas S. J. De Couto)

How can I use a HashMap without getting compiler errors?

You have to include bighasmap.cc and explicitely instantiate the HashMap at the bottom of your_element.cc.

// macro magic to use bighashmap
#include <click/bighashmap.cc>
#if EXPLICIT_TEMPLATE_INSTANCES
template class HashMap<Packet*, IPAddress*>;
#endif
CLICK_ENDDECLS
EXPORT_ELEMENT(YourElement)

I'm getting compile error in the function beetlemonkey, what do I do to fix this?

You most likely haven an error like this:

cd '/home/mvhaen/simulations/click' && gmake -k
g++-3.3.4 -DHAVE_CONFIG_H -I../include -I../include -I. -I.. -DCLICK_NS -g -O2 -c elements.cc
elements.cc: In function `Click::Element* beetlemonkey(unsigned int)':
elements.cc:284: error: ISO C++ forbids declaration of `type name' with no type
elements.cc:284: error: uninitialized const in `new' of `const int'
elements.cc:284: error: cannot convert `const int*' to `Click::Element*' in return
elements.cc:285: error: cannot convert `char**' to `Click::Element*' in return
elements.cc:286: error: syntax error before `(' token
elements.cc:287: error: ISO C++ forbids declaration of `type name' with no type
elements.cc:287: error: uninitialized const in `new' of `const int'
elements.cc:287: error: cannot convert `const int*' to `Click::Element*' in return
elements.cc: In function `void click_export_elements()':
elements.cc:582: error: syntax error before `(' token
elements.cc:586: error: `class_name' undeclared (first use this function)
elements.cc:586: error: (Each undeclared identifier is reported only once for each function it appears in.)
elements.cc:586: error: syntax error before `::' token
elements.cc:588: error: syntax error before `(' token
elements.cc: In function `void click_unexport_elements()':
elements.cc:906: error: syntax error before `(' token
elements.cc:908: error: syntax error before `::' token
elements.cc:909: error: syntax error before `(' token
gmake[1]: *** [elements.o] Error 1 

And it is probably caused by one of your elements header files being malformed. Make sure that the method class_name is defined on 1 line like this:

const char* class_name() const { return "OLSRNeighborInfoBase"; }

and not like this:

const char* class_name() const
{
      return "OLSRNeighborInfoBase";
}

You can find the element causing this by looking at elements.cc, you will see something like this:

 case 105: return new OLSRNeighborInfoBase;
 case 106: return new const;
 case 107: return new char;
 case 108: return new *class_name();
 case 109: return new const;

In this case go to the header file of OLSRNeighborInfoBase.

Then run 'make elemlist all' to finally resolve the issue. Or repeat if there are more element headers like this.

Hint: watch out with editors that can automatically format your source code, they tend to cause this problem. It is safe to use them on .cc files, but not the .hh files.

 
faq.txt · Last modified: 2010/09/27 16:19 by rchertov
 
Recent changes RSS feed Driven by DokuWiki