1--------------------------------------------
2This file describes how to use and how to hack networking subsystem of
3the Barrelfish.
4
5--------------------------------------------
6Using networking subsystem:
7Currently Barrelfish supports following NIC devices
8rtl8029 (Realtek RTL8029AS, emulation support QEMU)
9e1000 (Intel 82576 1GbE NIC)
10e10k (Intel 82599 10GbE NIC)
11eMAC (on SCC)
12
13If you want to use any of above then you should edit the menu.lst file to
14reflect which card you want to use.  The following example shows how to
15use e1000 card.
16
17Add following lines to menu.lst
18{{{
19module	/x86_64/sbin/e1000n
20module	/x86_64/sbin/NGD_mng cardname=e1000
21module	/x86_64/sbin/netd cardname=e1000
22}}}
23
24e1000n: The first line will start a driver domain which will be responsible for
25sending and receiving packets on one queue within the NIC.
26
27NGD_mng: The second line starts the "net device manager" service which is
28responsible for port management and handling of hardware queues present within
29NIC (if any).  The "cardname=e1000" argument tells this "net device manager"
30that it is responsible for NIC card e1000.
31
32netd: The third line starts the netd service is responsible for doing DHCP
33to get an IP for the NIC, running ARP lookups on behalf of all other
34applications, and handling the traffic which no other application wants.
35This daemon also has an argument stating which card it will be responsible for.
36
37
38--------------------------------------------
39How to use networking from within application?
40Every application that wants to use the networking should initialize the
41networking.  It can be done by calling a following function.
42{{{
43lwip_init(char *card_name, uint64_t  qid)
44}}}
45Here, card_name is the name of the NIC device to be used (eg: e1000), and
46queue_id the id of the hardware queue that should be used.  The queue_id 0
47is always safe option, and queue 0 is assumed to be a shared queue.
48Following is the example call:
49{{{
50lwip_init("e1000", 0);
51}}}
52
53One of the variant of this function  "lwip_init_auto" tries to guess the
54NIC device name automatically by some rudimentary logic, but it does not
55yet work for all devices and in all situations.
56
57Once "lwip_init" returns successfully, the application can start using the
58networking.  The networking interface is based on the "Light Weight
59Internet Protocol (LWIP)".  Also applications like "webserver",
60"echoserver", "vmit" use networking, and hence can be referred to
61check how to use the Barrelfish networking.
62
63--------------------------------------------
64Known limitations:
65The presence of DHCP server within same LAN is assumed to give an IP
66address.
67
68Currently, only one NIC device can be effectively used in one running
69instance of Barrelfish.
70The reason behind this is that currently, netd is stateless.  Even though most
71of the networking code can work even in presence of multiple active NIC
72devices of different type, netd is still not completely ready for this
73possibility.
74
75--------------------------------------------
76
77
78