[image] Allow for zero embedded images
[people/asdlkf/gpxe.git] / src / drivers / net / mlx_ipoib / doc / README.boot_over_ib
1 .Boot over IB over Mellanox HCAs README - Pre-Alpha release
2 ==========================================================
3 Document #2442, Rev 0.10, December 2005
4
5
6 1. General
7 -----------
8 This README describes the Boot over IB package which enables booting a Linux 
9 kernel from a remote server using one of the Mellanox Technologies HCA 
10 devices. The package is based on Etherboot 5.4.1.
11
12 The package actually implements a network driver for Etherboot. The wire 
13 protocol is compliant with IP Over IB 
14 (see http://www.ietf.org/html.charters/ipoib-charter.html for related 
15 documents).
16
17 Etherboot uses a traditional setup of a DHCP server and a TFTP server to 
18 perform a remote boot in a similar manner to Ethernet NICs. The binary code is 
19 exported by the device as an expansion ROM image.
20
21
22 2. Supported Devices
23 ---------------------
24 The following Mellanox Technologies HCA devices are supported:
25
26         PCI Device ID           Mellanox HCA Device
27         ----------------------------------------------
28         23108                   InfiniHost (P/N MT23108)
29         25208                   InfiniHost III Ex (P/N MT25208) (InfiniHost)
30         25218                   InfiniHost III Ex (P/N MT25208) (MemFree)
31         25204                   InfiniHost III Lx (P/N MT25204)
32
33         
34         Note:   For devices with more than one IB port, port 1 is used for 
35         communications.
36
37
38 3. Compiling
39 ----------------
40 From the src directory:
41 Run" make bin/<device>.<ext>
42 where device can be any of:
43         MT23108
44         MT25218
45         MT25208
46         MT25204
47         
48 and ext can be rom, zrom etc. (see Etherbot doumentation for more details)
49
50 4. Directory Structure
51 -----------------------
52 All driver files are available under src/drivers/net/mlx_ipoib/. Under this 
53 directory the following files can be found:
54         
55         ***     doc - Contains related documents including this file.
56         ***             patches - Contains needed patch files.
57         ***     samples - Contains sample files.
58         ***     . Contains driver source files.
59         
60
61 5. Burning the Flash Memory
62 ----------------------------
63 The binary code resides in the same Flash device of the device firmware. 
64 However the binary files are distinct and do not affect each other. Mellanox's 
65 'mlxburn' tool is available for burning, however, it is not possible to burn 
66 the expansion ROM image by itself; rather, both the firmware and expansion ROM 
67 images must be burnt simultaneously.
68
69 'mlxburn' is part of the Mellanox Firmware Tools (MFT) package  available for 
70 download from www.mellanox.com under 'Firmware Downloads'.
71
72 Example:
73 The following command burns a firmware image and an expansion ROM image to an 
74 InfiniHost Adapter Card (P/N MHX-CE128-T.ini):
75           
76    mlxburn -fw fw-23108-a1-rel.mlx -exp_rom MT23108.bin
77                          /dev/mst/mt23108_pci_cr0 -conf MHX-CE128-T.ini
78
79 *** Important Note: The .ini file must support burning expansion ROMs. For 
80 example, the following lines must appear in the .ini file. If they do not, 
81 please add them manually.
82
83 [ADAPTER]
84 exp_rom_en = true
85
86 Mellanox's web site contains firmware binary files with extension .bin.gz. 
87 These files contain contain EVERYTHING the goes in the flash memory and thus 
88 are NOT suitable for including the expansion rom image. Therefore, one use the 
89 files with .mlx extension also available from Mellanox's web site.
90
91         
92
93 6. Preparing the DHCP Server
94 -----------------------------
95 DHCP messages over IP Over IB are transmitted as broadcasts. In order to 
96 distinguish between messages belonging to a certain DHCP session, the messages 
97 must carry the client identifier option (see ietf documentation referred to 
98 above). As of November 2005, ISC DHCP servers do not support this feature. 
99 They are expected to support this at the end of 2005. In order to work this 
100 out, the appropriate patch must be applied (see patches directory). It has 
101 been tested on version isc-dhcpd-V3.0.4b2.
102
103 The DHCP server must run on a machine which supports IP Over IB. The Mellanox 
104 IBGD package (gen1 or gen2) can be used to provide this.
105 To run the DHCP server from the command line use: dhcpd ib0
106
107 7. DHCP Server Configuration File
108 ----------------------------------
109 In order for the DHCP server to provide configuration records for clients, an 
110 appropriate configuration file dhcpd.conf must be created and put under /etc/. 
111 A sample configuration file with comments can be found in the samples directory.
112
113
114 8. OpenSM
115 ----------
116 To successfully boot over IB, the IB network must contain a Subnet Manager 
117 which configures the IB network. OpenSM is part of the IBGD distribution and 
118 can be used to accomplish that. Note that OpenSM may be run on the same host 
119 running the DHCP server but it is not mandatory.
120
121
122 9. TFTP Server
123 ---------------
124 When the DHCP session is completed, the client has the IP address of the TFTP 
125 server from which it should download the kernel image. This TFTP server must 
126 run on a machine with InfiniBand support. The client loads first a loader 
127 image based on PXE API which then loads the kernel image. The image can be 
128 found in the Linux kernel homepage:
129
130 http://www.kernel.org/pub/linux/boot/syslinux/
131
132
133 10. BIOS Configuration
134 -----------------------
135 The expansion ROM image presents itself to the BIOS as a boot device. As a 
136 result, the BIOS will add it to the list of boot devices. The priority of this 
137 list can be modified when entering the BIOS setup. The boot over IB     image must 
138 be set first for the BIOS to attempt to use it first.
139
140
141 11. Operation
142 --------------
143 When booting the client, a message appears on the screen describing the device 
144 found and the revision of the code. The user has 3 seconds to press a key for 
145 increased functionality:
146 'V' will increase verbosity.
147 'I' will prinit some information to aid in configuring the DHCP configuration 
148     file. In this case the display will hold for 5 seconds to let the user 
149         grasp the information.
150         
151 Note that increasing verbosity will significantly slow boot time and will 
152 print lots of debug messages to the screen.
153
154
155 12. Diskless Machines
156 ----------------------
157 Most often it is required to boot a diskless machine. In these  cases the 
158 kernel mounts its root file system over NFS over one of the interfaces. For 
159 this to happen on a client with only InfiniBand interfaces, the kernel image 
160 must be configured accordingly and must include IP Over IB support. This can 
161 be achieved either by compiling this into the kernel or using initrd images 
162 that contain IP Over IB support.
163
164
165 13. Changing Defaults
166 ----------------------
167 As stated the driver uses port 1 for its communications. To use another port 
168 edit the file src/drivers/net/ib_driver.h and modify the definition of 
169 PXE_IB_PORT.
170
171
172 14. Installing a package from Mellanox
173 --------------------------------------
174 When using a package obtained from Mellanox Technologies' web site, the
175 directory src/bin will contain the driver binary files. The files have a .bin
176 extension and are equivalent to the same files with .zrom extension.