Installation Instructions

---

KECho consists of some modifications to the Linux 2.4.19 kernel and some new kernel modules, which are kept separate from the kernel tree because the same code is shared between the ECho libraries and KECho modules.
If you need help for applying the patch and compiling your kernel, read on. If you need help for the KECho modules (and you will), see further below. Also note that the KECho runs on i386 architectures only, a StrongARM SA1110 version for the Linux familiar distribution will be added here soon. Please follow the steps below, we hope to have a simpler installation procedure in the near future :-)

1. Get a clean Linux source code, kernel version 2.4.19, e.g., from kernel.org (linux-2.4.19.tar.gz) and install it into your /usr/src directory. Give it a meaningful name (e.g., linux-2.4.19-kecho) and make a soft link to it (ln -s linux-2.4.19-kecho linux). Go into /usr/src/linux and open Makefile, set the EXTRAVERSION to some meaningful, e.g., -kecho (in that case your modules will be in /usr/lib/modules/2.4.19-kecho).
2. Copy the patch file into this new directory (/usr/src/linux) and apply it to the source tree: patch -p1 < kecho.patch.
3. Set your config file, e.g., using make menuconfig and make sure to exclude 'modular DWCS scheduler' and to include 'Event-based QoS Support'. You can use this .config file as an example.
4. Compile the kernel: make bzImage.
5. Compile the modules: make modules.
6. Install the kernel: cp ./arch/i386/boot/bzImage /boot/kernel-2.4.19-kecho.
7. Install the modules: make modules_install.
8. Go to /usr/include and backup the directories asm, net, and linux (e.g., copy them to bak_net, bak_asm, bak_linux). Then make softlinks: ln -s /usr/src/linux/include/linux linux and repeat that for asm and net.
9. If necessary, go to /boot and make a ramdisk: mkinitrd initrd-2.4.19.img 2.4.19-kecho (if your modules are in /usr/lib/modules/2.4.19-kecho). 
10. Open /etc/lilo.conf (or any other bootloader you use) and make a new entry (e.g., copy an existing entry and just change the names of the Linux kernel, the ramdisk (if existing), and the label. You can make it the default kernel or not, whatever you prefer (e.g., in lilo.conf look for the default= line). Then run /sbin/lilo.
11. Reboot and hope for the best...
    

    KECho modules:

1. Download the tarball with the KECho modules.
2. Install it whereever you like, e.g., your home directory (gunzip -d kecho-vx.x.tgz, tar xvf kecho-vx.x.tar).
3. Steps 5-9 need to be done only once on one computer, they install some important ECho-related stuff, which KECho relies on. If you recompile KECho in the future, you can skip those steps and just continue at step 10. The ECho-related steps might give you some warnings or even errors, but they shouldn't matter as long as you end up with two files -- format_server and group_server2 -- in /usr/local/bin, you are ok. Also, /usr/local will be used by ECho to install some libraries, executables, and header files. If you prefer a different directory, use --prefix=dir_name as a flag for the ./configure calls below (note however that in that case the Makefiles created by configure might have a few smaller bugs and you might have to fix the Makefiles by hand). Finally, if anything ever complains about missing header files, copy them by hand to /usr/local/include or any other directory where you might need it.
4. As mentioned before, two servers are necessary to run KECho, called format_server and group_server2. Before you compile, make sure you know what machine these servers will run on.
   
5. Go into gen_thread and type: ./configure; make; make install.
6. Go into pbio and type: ./configure. Then open config.h and look for the entry FORMAT_SERVER_HOST and make sure it's the name of the host you want the format server to run on. Also make sure that the entry FORMAT_SERVER_DOMAIN is empty (""""). Then type make; make install.
   
7. Go into atl and type: ./configure; make; make install.
   
8. Go into cm and type: ./configure; make; make install.
9. Go into comm_group and type: ./configure. Then open config.h and look for the entry GROUP_SERVER_HOST and make sure it's the name of the host you want the format server to run on. Also make sure that the entry GROUP_SERVER_DOMAIN is empty (""""). Then type make; make install.
10. Now it's time to compile the KECho modules. Go into the following directories (in any order): atl, cm, comm_group, drisc, ecalls, ecl, kecho, pbio, sockwatch, utils. In each directory type: make clean; cp Makefile.kecho Makefile; make clean; make
11. Now execute the installer script: ./installer and you are done.

    How to use it:

1. There is a simple example in EXAMPLES/test1_kthread, just go in there, type make clean; make; make install and you have two new modules, sender1 and reader1.
2. Start the servers on the machine you selected before, e.g.: /usr/local/bin/format_server; /usr/local/bin/group_server2.
3. KECho currently relies on a file called /tmp/directory, which has to be on each computer you use and has to have one entry: the name and IP address of the computer that runs the servers (e.g.: my_machine.my_domain    192.168.1.100), where both are separated by a <tab>.
4. Use the scripts in EXAMPLES/test1_kthread to load/unload the modules: ./load_all and ./remove_all.
5. Once the modules are loaded on all machines you use (you can run sender1 and reader1 on one machine or on separate machines), load the sender (insmod sender1) and when it successfully starts a KECho channel it will submit an event every two second (use dmesg to see kernel messages). Then also start reader1 (insmod reader1) and once it has opened and subscribed to the channel, you should see messages verifying event arrival with dmesg.
   

    Some more information:

1. In both sender.c and reader.c you'll find these entries: #define APP_NAME 1 "TEST1" and #define GRP_TYPE1 "TEST1". These two strings together are used to identify an event channel. Use a descriptive string for these two entries, all kernel threads using this channel have to know these strings. See, for example, setup_comm_group, which is used to 'register' a new event channel with the group server. In the same call, you also have to specify a host name and port number, which are used by other applications that want to join this event channel. The fourth attribute is a timeout value, the group server will discard channel information after this time expires (in seconds), meaning that all other hosts have request the channel information from the group server within this time.
2. To stop an experiment, just remove your modules first, then use ./remove_all to remove the KECho modules.
3. Note that even though in sender.c we only submit events and do not receive any, we still invoke CMpoll_network periodically. Since sender.c has created the event channel, all other threads will contact it to join this channel, therefore, we need to poll for incoming requests.
4. I will add some more information with time, including information on how to use ECalls to customize event delivery, use KECho from application level (you can try to run EXAMPLES/test6_app), use filters in KECho, etc.
   

    Who do I contact if I have a question?

For questions and suggestions about KECho please contact Christian Poellabauer at chris@cc.gatech.edu.