CLICK FAQ
=========

SECTION 1: GENERAL QUESTIONS
----------------------------

Q. Is Click experimental software?

A. Yes.


Q. The Click Linux patch does not apply cleanly.

A. You need a specific version of Linux. We currently distribute pactches
   for Linux 2.2.18, 2.2.19 [patch also works for 2.2.20 and 2.2.21],
   2.4.18, and 2.4.20. These patches may also work for later versions.


Q. How fast can Click route packets?

A. 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.


Q. How do you do that?

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


Q. Can I get that many packets through a Click router?

A. You should be able to do that right now if you use DEC Tulip fast
   Ethernet cards. This is currently the only device driver that we have
   changed to use our polling extensions to Linux.


Q. How does Click run inside a Linux kernel?

A. As a kernel thread. It continually loops over a list of things to do,
   and does them---basically busy waiting. Other processes on the machine
   will get run, but not as often as on a machine without Click.


Q. What are the Grid elements?

A. 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.


SECTION 2: QUESTIONS ABOUT POLLING
----------------------------------

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

A. Benjie Chen, who designed the extensions, should be writing a document
   that describes how to do this. For now, though, you'll have to look at
   our additions to Linux's `struct device', and the way they are used by
   our Tulip driver. You can always write us and ask for help:
   <click@pdos.lcs.mit.edu>.


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

A. Sure you can. Just use FromDevice elements instead of PollDevice
   elements. Your performance will suck though.


SECTION 3: CREATING YOUR OWN ELEMENTS
-------------------------------------

Q. How can I add my own element class to Click?

A. 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 functions:

	const char *class_name() const;	// return your element's name
	Element *clone() const;		// return a newly allocated element

     Other common functions to override include:

	const char *processing() const; // return processing code
	int configure(const Vector<String> &, ErrorHandler *);
					// process configuration string
	int initialize(ErrorHandler *);	// initialize element
	void uninitialize();		// uninitialize element

	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

     All these functions are described in the Click programming manual,
     doc/click.texi.

     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.


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

A. 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'?)
	Is your element's .cc file present in `userlevel/elements.conf' or
     `linuxmodule/elements.conf'?
