HACKING

   1 Guide for potential hackers on Lightweight Autonomic Network Architecture
   2 -------------------------------------------------------------------------
   3
   4 There's a public Git repository where you can check out the latest
   5 Lightweight Autonomic Network Architecture sources:
   6
   7 $ git clone git://repo.or.cz/ana-net.git
   8
   9 For hacking the source you definately need a bleeding-edge kernel since LANA
  10 is currently developed against the latest linus Git tree. Check it out via
  11
  12 $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git
  13
  14 and read the INSTALL file for compiling and running the kernel, but you
  15 probably already know how to do this. ;-)
  16
  17 Also, using a serial console for testing and debugging purpose is quite
  18 useful, especially when you get a panic or Ooops within interrupt context!
  19 Assuming you are using GRUB2 (there's really no magic for other versions),
  20 simply add 'console=/dev/ttyS0,9600n8' to the kernel cmdline parameters,
  21 e.g.:
  22
  23 menuentry 'Debian/Linux 2.6.38-rc8+' --class debian --class gnu-linux
  24                                      --class gnu --class os {
  25   insmod part_msdos
  26   insmod ext2
  27   set root='(hd0,msdos6)'
  28   search --no-floppy --fs-uuid --set <bla>
  29   linux /boot/vmlinuz-2.6.38-rc8+ root=UUID=<bla> ro console=/dev/ttyS0,9600n8
  30   initrd  /boot/initrd.img-2.6.38-rc8+
  31 }
  32
  33 If you also want to redirect tty output of your devel os to the serial port,
  34 add to the /etc/inittab in the development system:
  35
  36 co:2345:respawn:/sbin/agetty ttyS0 9600 vt100-nav
  37
  38 Then reboot that machine. If you're using this kernel within qemu, the map
  39 the serial device to your host os with qemu <...> -serial /dev/ttyX <...>
  40 (where X is a number for instance) or map it to a file as qemu
  41 <...> -serial file:serial.log <...>. For ttys you can use minicom to connect
  42 and see relevant stack traces if your kernel crashes within interrupt mode
  43 for instance. This gives you at least a stack trace via serial console, so
  44 that you are at least able to see the whole stack printout.
  45
  46 You can obtain minicom on Debian via: # apt-get install minicom
  47 minicom's configuration on your local machine should look like this:
  48
  49   Serial Device         : /dev/ttyXY
  50   Lockfile Location     : /var/lock
  51   Callin Program        :
  52   Callout Program       :
  53   Bps/Par/Bits          : 9600 8N1
  54   Hardware Flow Control : No
  55   Software Flow Control : No
  56
  57 For vim hackers there's also a tiny plugin in opt/vim80warn.vim that
  58 warns you if more than 80 chars have been used on a single line. Install
  59 it by creating a directory ~/.vim/plugin directory and copy this plugin
  60 into this directory, restart vim and you're good to go.
  61
  62 Note that there are also some file naming conventions! fb_*.c|h is a
  63 functional block. Ideally you place all the neccessary code that is related
  64 to the fb into this file, so that the src directory stays clean.
  65 All the other non-fb_* files are regarded as LANA core files, which are
  66 mandatory for the network stack to operate.
  67
  68 Function naming conventions for functional blocks are similar. Always have
  69 a prefix of 'fb_', even for static functions. All the rest follows Linux
  70 kernel coding conventions as described in CODING. You can use the kernels
  71 check_patch.pl script for style errors, trailing whitespaces and so on
  72 before submitting a patch. Next to this, there are xt_* files. These are
  73 extensions ("xt") that are not standalone and are linked to the core.
  74
  75 There's a sem/ folder with Coccinelle scripts that performs semantic
  76 patching on the lana kernelspace code. If you are using Debian, install
  77 Coccinelle with ...
  78
  79   # apt-get install coccinelle
  80
  81 ... and run make within sem/. Possible patches are saved within this folder
  82 after the run. For hacking own Coccinelle scripts, have a look at their
  83 website for documentation http://coccinelle.lip6.fr/ and for usage examples
  84 http://coccinelle.lip6.fr/rules/.
  85
  86 Please send your ideas or patches for LANA mainline inclusion to:
  87 ariane.keller@tik.ee.ethz.ch, wolfgang.muehlbauer@tik.ee.ethz.ch or
  88 dborkma@tik.ee.ethz.ch
  89
  90  +++ Patches Wanted! ;-) +++
  91
  92 There's a public website about the Autonomic Network Architecture project
  93 with previous prototypes and further documentation:
  94
  95 http://www.ana-project.org/
  96 http://repo.or.cz/w/ana-net.git
  97
  98 LANA is developed at the Communication Systems Group of the Swiss federal
  99 institute of technology (ETH Zurich).
 100