From 0a04f96bf17bd42d0eb622dc781b8e86f1e0fcbe Mon Sep 17 00:00:00 2001
From: eddietwo <eddietwo>
Date: Wed, 27 Jun 2001 00:34:58 +0000
Subject: [PATCH] updated info for click-1.2.1; added documentation to FAQ
about creating your own elements
---
AUTHORS | 10 +++--
DISTFILES | 12 ++----
FAQ | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
INSTALL | 13 +++++--
NEWS | 60 ++++++++++++++++++++++++++++++
README | 19 ++++++++--
6 files changed, 199 insertions(+), 22 deletions(-)
diff --git a/AUTHORS b/AUTHORS
index 9e0a96e99..24f5b5052 100644
--- a/AUTHORS
+++ b/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
diff --git a/DISTFILES b/DISTFILES
index fe8e678f2..4d01eb826 100644
--- a/DISTFILES
+++ b/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
diff --git a/FAQ b/FAQ
index 9c4e2dd12..e60c32a92 100644
--- a/FAQ
+++ b/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'?
diff --git a/INSTALL b/INSTALL
index e99e5d44f..ac5dc4669 100644
--- a/INSTALL
+++ b/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
diff --git a/NEWS b/NEWS
index 319736cde..2913195ed 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,64 @@
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
diff --git a/README b/README
index f790b7b06..8c4586a0b 100644
--- a/README
+++ b/README
@@ -1,4 +1,4 @@
-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
--
GitLab