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