updated info for click-1.2.1; added documentation to FAQ about creating your own elements

AUTHORS

@@ -19,7 +19,7 @@ Eddie Kohler
 kohler@aciri.org
 design, core, language, Linux /proc interface, Linux kernel module,
 standard elements, tools, documentation, distribution, IP rewriting
-elements, ClickController, other elements, Tasks
+elements, ClickController, other elements, Tasks, Linux 2.4
 
 Mazu Networks, Inc.
 http://www.mazunetworks.com/
@@ -34,16 +34,20 @@ Massimiliano Poletto
 maxp@lcs.mit.edu
 IP rewriting elements, stride scheduling element, round robin scheduler
 
+Nickolai B. Zeldovich
+kolya@lcs.mit.edu
+Linux 2.4
+
 
 Thanks to:
 
 John Jannotti
 jj@lcs.mit.edu
-initial design work, Ethernet switch elements, user-level pcap/BPF elements
+initial design, Ethernet switch elements, user-level pcap/BPF elements
 
 M. Frans Kaashoek
 kaashoek@lcs.mit.edu
-initial design work
+initial design
 
 Alex Snoeren
 snoeren@lcs.mit.edu

DISTFILES

@@ -61,6 +61,7 @@ conf/udpgen.click
 etc
 etc/linux-2.2.17-patch
 etc/linux-2.2.18-patch
+etc/linux-2.2.19-patch
 etc/linux-2.4.4-patch
 
 etc/samplepackage
@@ -88,6 +89,8 @@ include/click/click_udp.h
 include/click/clp.h
 include/click/confparse.hh
 include/click/crc32.h
+include/click/cxxprotect.h
+include/click/cxxunprotect.h
 include/click/element.hh
 include/click/elemfilter.hh
 include/click/error.hh
@@ -186,15 +189,6 @@ linuxmodule/read-pmc.c
 linuxmodule/sched.cc
 linuxmodule/skbmgr.cc
 
-apps
-apps/ClickController
-apps/ClickController/README
-apps/ClickController/ClickController.java
-apps/ClickController/ControlSocket.java
-apps/ClickController/NewConnectionDialog.java
-apps/ClickController/RouterTreeModel.java
-apps/ClickController/Util.java
-
 tools
 tools/Makefile.in
 

FAQ

@@ -12,9 +12,9 @@ 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. Most of the patch will apply no matter what version of
-   Linux 2.2 you use. The problems are with device drivers, which seem to
-   change a lot between versions.
+   for Linux 2.2.17, 2.2.18, 2.2.19, and 2.4.4. Most of the patch will
+   apply no matter what version of Linux 2.2 you use. The problems are with
+   device drivers, which seem to change a lot between versions.
 
 
 Q. How fast can Click route packets?
@@ -43,6 +43,13 @@ A. As a kernel thread. It continually loops over a list of things to do,
    will get run, but not as often as on a machine without Click.
 
 
+Q. Is there a version of Click for Linux 2.4?
+
+A. Click now compiles under a patched version of Linux 2.4! (We supply the
+   patch.) Your mileage may vary; we still use Linux 2.2 for most of our
+   work.
+
+
 SECTION 2: QUESTIONS ABOUT POLLING
 ----------------------------------
 
@@ -60,3 +67,97 @@ Q. Can I use Click without updating device drivers (that is, without
 
 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'?

INSTALL

@@ -24,9 +24,13 @@ cannot compile a version. Run
 
 to see more options for `./configure'.
 
-(If the distribution does not contain a `configure' script, you probably
-checked out the distribution from CVS. Change into the source directory and
-run `autoconf', then continue as above.)
+   Notes: You can also build Click in a different directory than the source
+          directory. Just change into the build directory and run
+          `PATH_TO_SRCDIR/configure'.)
+
+          If the distribution does not contain a `configure' script, you
+          probably checked out the distribution from CVS. Change into the
+          source directory and run `autoconf', then continue as above.)
 
 After running `./configure', the `make install' command will install the
 user-level executable `click', the kernel module `click.o', the
@@ -77,6 +81,9 @@ and running Linux kernels.
     from www.kernel.org. Unpack this distribution into /usr/src/linux.
     (Save the old kernel source tree, if you had one.)
 
+    We also supply patches for Linux 2.2.17, 2.2.19, and a preliminary
+    patch for Linux 2.4.4/2.4.5.
+
  3. Install the Click Linux kernel patch:
 
 	cd /usr/src/linux

NEWS

 Click NEWS
+
+Version 1.2.1   26.Jun.2001
+
+* General
+
+** Added preliminary support for Linux 2.4! The patch is in
+   etc/linux-2.4.4-patch; it also applies to Linux 2.4.5. Click can receive
+   and send packets, and there is preliminary support for polling, as well.
+   We will be improving Linux 2.4's stability with time. Thanks to Nickolai
+   B. Zeldovich.
+
+** Many bug fixes, particularly to ARPResponder, ToLinux, LookupIPRoute,
+   cp_unparse_real2, cpArguments.
+
+** Updated etc/samplepackage to bring it up to date. It is a good starting
+   point for building your own package.
+
+* Elements
+
+** In the kernel, FromDevice, PollDevice, and ToDevice watch for
+   notifications when devices go up or down. Now you can remove a device
+   that the Click configuration refers to; the relevant element will simply
+   stop pushing or pulling packets. If you add the device back again, the
+   relevant element will seamlessly attach to it. Also added the
+   `ALLOW_NONEXISTENT' keyword argument to these elements.
+
+** In the kernel, AddressInfo supports device names as Ethernet address
+   shorthand. So you can say `EtherEncap(..., eth0, ...)' and it will use
+   eth0's Ethernet address.
+
+** Added KernelHandlerProxy element, and added the `PROXY' keyword argument
+   to ControlSocket. Now you can use a ControlSocket to talk to a kernel
+   configuration -- for example, with ClickController. Element donated by
+   Mazu Networks, Inc.
+
+** FromDump can read modified tcpdump files generated by Linux tcpdump.
+
+** ICMPSendPings has more keyword arguments. ICMPPingResponder now sets the
+   destination IP address annotation. ICMPRewriter can rewrite ping
+   responses as well as TCP and UDP responses.
+
+** Added DelayUnqueue, DelayShaper, and IP6Print elements.
+
+* Tools
+
+** Added click-flatten tool.
+
+* C++ API changes
+
+** Renamed `u_intXX_t' types to `uintXX_t'.
+
+** Elements no longer need to `#include <click/package.hh>'.
+
+** Added cpFilename confparse type at user level, which includes tilde
+   expansion.
+
+** `hashcode()', the function used by BigHashMap and HashMap to calculate
+   hash values, is now an overloaded function, not a member function. See
+   include/click/ipflowid.hh for an example.
+
 
 Version 1.2.0   3.May.2001
 

README

-THE CLICK MODULAR ROUTER RELEASE 1.2.0
+THE CLICK MODULAR ROUTER RELEASE 1.2.1
 ======================================
 
     This is the README file for the source release for the Click modular
@@ -79,13 +79,16 @@ directly interacts with device drivers, while the user-level driver uses
 packet sockets (on Linux) or the pcap library (everywhere else).
 
 User-Level Program
-------------------
+..................
 
     Run the user-level program by giving it the name of a configuration
 file: `click CONFIGFILE'.
 
 Linux Kernel Module
--------------------
+...................
+
+    You must patch your Linux kernel first. See `INSTALL' for more
+information.
 
     See the `doc/click.o.8' manual page for a detailed description. To
 summarize, install a configuration by running `click-install CONFIGFILE'.
@@ -99,7 +102,7 @@ then install a configuration by hand with `cat CONFIGFILE >
 `/proc/click/errors'. But `click-install' is easier.
 
 Configurations
---------------
+..............
 
     A few configurations are included in the `conf' directory, including a
 Perl script that generated the IP router configurations used in our TOCS
@@ -107,6 +110,12 @@ paper (`conf/make-ip-conf.pl') and a set of patterns for the Click pattern
 optimizer, click-xform (`conf/ip.clickpat'). Please check back to our Web
 site for more up-to-date configurations.
 
+ADDING YOUR OWN ELEMENTS
+------------------------
+
+    Please see the FAQ in this directory if you want to know how to add
+elements to Click.
+
 COPYRIGHT AND LICENSE
 =====================
 
@@ -131,4 +140,6 @@ source code. Write us at
 	  Thomer M. Gil
 	  Robert Morris
 	  Max Poletto
+	  Nickolai B. Zeldovich
 	  M. Frans Kaashoek
+	  John Jannotti