[dhcp] Split PXE menuing code out of dhcp.c
[people/cooldavid/gpxe.git] / src / include / gpxe / dhcp.h
1 #ifndef _GPXE_DHCP_H
2 #define _GPXE_DHCP_H
3
4 /** @file
5  *
6  * Dynamic Host Configuration Protocol
7  *
8  */
9
10 #include <stdint.h>
11 #include <gpxe/in.h>
12 #include <gpxe/list.h>
13 #include <gpxe/refcnt.h>
14 #include <gpxe/tables.h>
15 #include <gpxe/uuid.h>
16 #include <gpxe/netdevice.h>
17
18 struct job_interface;
19 struct dhcp_options;
20 struct dhcp_packet;
21
22 /** BOOTP/DHCP server port */
23 #define BOOTPS_PORT 67
24
25 /** BOOTP/DHCP client port */
26 #define BOOTPC_PORT 68
27
28 /** PXE server port */
29 #define PXE_PORT 4011
30
31 /** Construct a tag value for an encapsulated option
32  *
33  * This tag value can be passed to Etherboot functions when searching
34  * for DHCP options in order to search for a tag within an
35  * encapsulated options block.
36  */
37 #define DHCP_ENCAP_OPT( encapsulator, encapsulated ) \
38         ( ( (encapsulator) << 8 ) | (encapsulated) )
39 /** Extract encapsulating option block tag from encapsulated tag value */
40 #define DHCP_ENCAPSULATOR( encap_opt ) ( (encap_opt) >> 8 )
41 /** Extract encapsulated option tag from encapsulated tag value */
42 #define DHCP_ENCAPSULATED( encap_opt ) ( (encap_opt) & 0xff )
43 /** Option is encapsulated */
44 #define DHCP_IS_ENCAP_OPT( opt ) DHCP_ENCAPSULATOR( opt )
45
46 /**
47  * @defgroup dhcpopts DHCP option tags
48  * @{
49  */
50
51 /** Padding
52  *
53  * This tag does not have a length field; it is always only a single
54  * byte in length.
55  */
56 #define DHCP_PAD 0
57
58 /** Minimum normal DHCP option */
59 #define DHCP_MIN_OPTION 1
60
61 /** Subnet mask */
62 #define DHCP_SUBNET_MASK 1
63
64 /** Routers */
65 #define DHCP_ROUTERS 3
66
67 /** DNS servers */
68 #define DHCP_DNS_SERVERS 6
69
70 /** Syslog servers */
71 #define DHCP_LOG_SERVERS 7
72
73 /** Host name */
74 #define DHCP_HOST_NAME 12
75
76 /** Domain name */
77 #define DHCP_DOMAIN_NAME 15
78
79 /** Root path */
80 #define DHCP_ROOT_PATH 17
81
82 /** Vendor encapsulated options */
83 #define DHCP_VENDOR_ENCAP 43
84
85 /** PXE boot server multicast address */
86 #define DHCP_PXE_BOOT_SERVER_MCAST DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 7 )
87
88 /** PXE boot menu */
89 #define DHCP_PXE_BOOT_MENU DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 9 )
90
91 /** PXE boot menu */
92 struct dhcp_pxe_boot_menu {
93         /** "Type" */
94         uint16_t type;
95         /** Description length */
96         uint8_t desc_len;
97         /** Description */
98         char desc[0];
99 } __attribute__ (( packed ));
100
101 /** PXE boot menu prompt */
102 #define DHCP_PXE_BOOT_MENU_PROMPT DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 10 )
103
104 /** PXE boot menu prompt */
105 struct dhcp_pxe_boot_menu_prompt {
106         /** Timeout
107          *
108          * A value of 0 means "time out immediately and select first
109          * boot item, without displaying the prompt".  A value of 255
110          * means "display menu immediately with no timeout".  Any
111          * other value means "display prompt, wait this many seconds
112          * for keypress, if key is F8, display menu, otherwise select
113          * first boot item".
114          */
115         uint8_t timeout;
116         /** Prompt to press F8 */
117         char prompt[0];
118 } __attribute__ (( packed ));
119
120 /** PXE boot menu item */
121 #define DHCP_PXE_BOOT_MENU_ITEM DHCP_ENCAP_OPT ( DHCP_VENDOR_ENCAP, 71 )
122
123 /** PXE boot menu item */
124 struct dhcp_pxe_boot_menu_item {
125         /** "Type"
126          *
127          * This field actually identifies the specific boot server (or
128          * cluster of boot servers offering identical boot files).
129          */
130         uint16_t type;
131         /** "Layer"
132          *
133          * Just don't ask.
134          */
135         uint16_t layer;
136 } __attribute__ (( packed ));
137
138 /** Requested IP address */
139 #define DHCP_REQUESTED_ADDRESS 50
140
141 /** Lease time */
142 #define DHCP_LEASE_TIME 51
143
144 /** Option overloading
145  *
146  * The value of this option is the bitwise-OR of zero or more
147  * DHCP_OPTION_OVERLOAD_XXX constants.
148  */
149 #define DHCP_OPTION_OVERLOAD 52
150
151 /** The "file" field is overloaded to contain extra DHCP options */
152 #define DHCP_OPTION_OVERLOAD_FILE 1
153
154 /** The "sname" field is overloaded to contain extra DHCP options */
155 #define DHCP_OPTION_OVERLOAD_SNAME 2
156
157 /** DHCP message type */
158 #define DHCP_MESSAGE_TYPE 53
159 #define DHCPNONE 0
160 #define DHCPDISCOVER 1
161 #define DHCPOFFER 2
162 #define DHCPREQUEST 3
163 #define DHCPDECLINE 4
164 #define DHCPACK 5
165 #define DHCPNAK 6
166 #define DHCPRELEASE 7
167 #define DHCPINFORM 8
168
169 /** DHCP server identifier */
170 #define DHCP_SERVER_IDENTIFIER 54
171
172 /** Parameter request list */
173 #define DHCP_PARAMETER_REQUEST_LIST 55
174
175 /** Maximum DHCP message size */
176 #define DHCP_MAX_MESSAGE_SIZE 57
177
178 /** Vendor class identifier */
179 #define DHCP_VENDOR_CLASS_ID 60
180
181 /** Client identifier */
182 #define DHCP_CLIENT_ID 61
183
184 /** Client identifier */
185 struct dhcp_client_id {
186         /** Link-layer protocol */
187         uint8_t ll_proto;
188         /** Link-layer address */
189         uint8_t ll_addr[MAX_LL_ADDR_LEN];
190 } __attribute__ (( packed ));
191
192 /** TFTP server name
193  *
194  * This option replaces the fixed "sname" field, when that field is
195  * used to contain overloaded options.
196  */
197 #define DHCP_TFTP_SERVER_NAME 66
198
199 /** Bootfile name
200  *
201  * This option replaces the fixed "file" field, when that field is
202  * used to contain overloaded options.
203  */
204 #define DHCP_BOOTFILE_NAME 67
205
206 /** Client system architecture */
207 #define DHCP_CLIENT_ARCHITECTURE 93
208
209 /** Client network device interface */
210 #define DHCP_CLIENT_NDI 94
211
212 /** UUID client identifier */
213 #define DHCP_CLIENT_UUID 97
214
215 /** UUID client identifier */
216 struct dhcp_client_uuid {
217         /** Identifier type */
218         uint8_t type;
219         /** UUID */
220         union uuid uuid;
221 } __attribute__ (( packed ));
222
223 #define DHCP_CLIENT_UUID_TYPE 0
224
225 /** Etherboot-specific encapsulated options
226  *
227  * This encapsulated options field is used to contain all options
228  * specific to Etherboot (i.e. not assigned by IANA or other standards
229  * bodies).
230  */
231 #define DHCP_EB_ENCAP 175
232
233 /** Priority of this options block
234  *
235  * This is a signed 8-bit integer field indicating the priority of
236  * this block of options.  It can be used to specify the relative
237  * priority of multiple option blocks (e.g. options from non-volatile
238  * storage versus options from a DHCP server).
239  */
240 #define DHCP_EB_PRIORITY DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x01 )
241
242 /** "Your" IP address
243  *
244  * This option is used internally to contain the value of the "yiaddr"
245  * field, in order to provide a consistent approach to storing and
246  * processing options.  It should never be present in a DHCP packet.
247  */
248 #define DHCP_EB_YIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x02 )
249
250 /** "Server" IP address
251  *
252  * This option is used internally to contain the value of the "siaddr"
253  * field, in order to provide a consistent approach to storing and
254  * processing options.  It should never be present in a DHCP packet.
255  */
256 #define DHCP_EB_SIADDR DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x03 )
257
258 /** Keep SAN drive registered
259  *
260  * If set to a non-zero value, gPXE will not detach any SAN drive
261  * after failing to boot from it.  (This option is required in order
262  * to perform a Windows Server 2008 installation direct to an iSCSI
263  * target.)
264  */
265 #define DHCP_EB_KEEP_SAN DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0x08 )
266
267 /*
268  * Tags in the range 0x10-0x7f are reserved for feature markers
269  *
270  */
271
272 /** Skip PXE DHCP protocol extensions such as ProxyDHCP
273  *
274  * If set to a non-zero value, gPXE will not wait for ProxyDHCP offers
275  * and will ignore any PXE-specific DHCP options that it receives.
276  */
277 #define DHCP_EB_NO_PXEDHCP DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xb0 )
278
279 /** Network device descriptor
280  *
281  * Byte 0 is the bus type ID; remaining bytes depend on the bus type.
282  *
283  * PCI devices:
284  * Byte 0 : 1 (PCI)
285  * Byte 1 : PCI vendor ID MSB
286  * Byte 2 : PCI vendor ID LSB
287  * Byte 3 : PCI device ID MSB
288  * Byte 4 : PCI device ID LSB
289  */
290 #define DHCP_EB_BUS_ID DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xb1 )
291
292 /** Network device descriptor */
293 struct dhcp_netdev_desc {
294         /** Bus type ID */
295         uint8_t type;
296         /** Vendor ID */
297         uint16_t vendor;
298         /** Device ID */
299         uint16_t device;
300 } __attribute__ (( packed ));
301
302 /** BIOS drive number
303  *
304  * This is the drive number for a drive emulated via INT 13.  0x80 is
305  * the first hard disk, 0x81 is the second hard disk, etc.
306  */
307 #define DHCP_EB_BIOS_DRIVE DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbd )
308
309 /** Username
310  *
311  * This will be used as the username for any required authentication.
312  * It is expected that this option's value will be held in
313  * non-volatile storage, rather than transmitted as part of a DHCP
314  * packet.
315  */
316 #define DHCP_EB_USERNAME DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbe )
317
318 /** Password
319  *
320  * This will be used as the password for any required authentication.
321  * It is expected that this option's value will be held in
322  * non-volatile storage, rather than transmitted as part of a DHCP
323  * packet.
324  */
325 #define DHCP_EB_PASSWORD DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xbf )
326
327 /** Reverse username
328  *
329  * This will be used as the reverse username (i.e. the username
330  * provided by the server) for any required authentication.  It is
331  * expected that this option's value will be held in non-volatile
332  * storage, rather than transmitted as part of a DHCP packet.
333  */
334 #define DHCP_EB_REVERSE_USERNAME DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xc0 )
335
336 /** Reverse password
337  *
338  * This will be used as the reverse password (i.e. the password
339  * provided by the server) for any required authentication.  It is
340  * expected that this option's value will be held in non-volatile
341  * storage, rather than transmitted as part of a DHCP packet.
342  */
343 #define DHCP_EB_REVERSE_PASSWORD DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xc1 )
344
345 /** gPXE version number */
346 #define DHCP_EB_VERSION DHCP_ENCAP_OPT ( DHCP_EB_ENCAP, 0xeb )
347
348 /** iSCSI primary target IQN */
349 #define DHCP_ISCSI_PRIMARY_TARGET_IQN 201
350
351 /** iSCSI secondary target IQN */
352 #define DHCP_ISCSI_SECONDARY_TARGET_IQN 202
353
354 /** iSCSI initiator IQN */
355 #define DHCP_ISCSI_INITIATOR_IQN 203
356
357 /** Maximum normal DHCP option */
358 #define DHCP_MAX_OPTION 254
359
360 /** End of options
361  *
362  * This tag does not have a length field; it is always only a single
363  * byte in length.
364  */
365 #define DHCP_END 255
366
367 /** @} */
368
369 /**
370  * Count number of arguments to a variadic macro
371  *
372  * This rather neat, non-iterative solution is courtesy of Laurent
373  * Deniau.
374  *
375  */
376 #define _VA_ARG_COUNT(  _1,  _2,  _3,  _4,  _5,  _6,  _7,  _8,          \
377                         _9, _10, _11, _12, _13, _14, _15, _16,          \
378                        _17, _18, _19, _20, _21, _22, _23, _24,          \
379                        _25, _26, _27, _28, _29, _30, _31, _32,          \
380                        _33, _34, _35, _36, _37, _38, _39, _40,          \
381                        _41, _42, _43, _44, _45, _46, _47, _48,          \
382                        _49, _50, _51, _52, _53, _54, _55, _56,          \
383                        _57, _58, _59, _60, _61, _62, _63,   N, ... ) N
384 #define VA_ARG_COUNT( ... )                                             \
385         _VA_ARG_COUNT ( __VA_ARGS__,                                    \
386                         63, 62, 61, 60, 59, 58, 57, 56,                 \
387                         55, 54, 53, 52, 51, 50, 49, 48,                 \
388                         47, 46, 45, 44, 43, 42, 41, 40,                 \
389                         39, 38, 37, 36, 35, 34, 33, 32,                 \
390                         31, 30, 29, 28, 27, 26, 25, 24,                 \
391                         23, 22, 21, 20, 19, 18, 17, 16,                 \
392                         15, 14, 13, 12, 11, 10,  9,  8,                 \
393                          7,  6,  5,  4,  3,  2,  1,  0 )
394
395 /** Construct a DHCP option from a list of bytes */
396 #define DHCP_OPTION( ... ) VA_ARG_COUNT ( __VA_ARGS__ ), __VA_ARGS__
397
398 /** Construct a DHCP option from a list of characters */
399 #define DHCP_STRING( ... ) DHCP_OPTION ( __VA_ARGS__ )
400
401 /** Construct a byte-valued DHCP option */
402 #define DHCP_BYTE( value ) DHCP_OPTION ( value )
403
404 /** Construct a word-valued DHCP option */
405 #define DHCP_WORD( value ) DHCP_OPTION ( ( ( (value) >> 8 ) & 0xff ),   \
406                                          ( ( (value) >> 0 ) & 0xff ) )
407
408 /** Construct a dword-valued DHCP option */
409 #define DHCP_DWORD( value ) DHCP_OPTION ( ( ( (value) >> 24 ) & 0xff ), \
410                                           ( ( (value) >> 16 ) & 0xff ), \
411                                           ( ( (value) >> 8  ) & 0xff ), \
412                                           ( ( (value) >> 0  ) & 0xff ) )
413
414 /** Construct a DHCP encapsulated options field */
415 #define DHCP_ENCAP( ... ) DHCP_OPTION ( __VA_ARGS__, DHCP_END )
416
417 /**
418  * A DHCP option
419  *
420  * DHCP options consist of a mandatory tag, a length field that is
421  * mandatory for all options except @c DHCP_PAD and @c DHCP_END, and a
422  * payload.  
423  */
424 struct dhcp_option {
425         /** Tag
426          *
427          * Must be a @c DHCP_XXX value.
428          */
429         uint8_t tag;
430         /** Length
431          *
432          * This is the length of the data field (i.e. excluding the
433          * tag and length fields).  For the two tags @c DHCP_PAD and
434          * @c DHCP_END, the length field is implicitly zero and is
435          * also missing, i.e. these DHCP options are only a single
436          * byte in length.
437          */
438         uint8_t len;
439         /** Option data */
440         uint8_t data[0];
441 } __attribute__ (( packed ));
442
443 /**
444  * Length of a DHCP option header
445  *
446  * The header is the portion excluding the data, i.e. the tag and the
447  * length.
448  */
449 #define DHCP_OPTION_HEADER_LEN ( offsetof ( struct dhcp_option, data ) )
450
451 /** Maximum length for a single DHCP option */
452 #define DHCP_MAX_LEN 0xff
453
454 /**
455  * A DHCP header
456  *
457  */
458 struct dhcphdr {
459         /** Operation
460          *
461          * This must be either @c BOOTP_REQUEST or @c BOOTP_REPLY.
462          */
463         uint8_t op;
464         /** Hardware address type
465          *
466          * This is an ARPHRD_XXX constant.  Note that ARPHRD_XXX
467          * constants are nominally 16 bits wide; this could be
468          * considered to be a bug in the BOOTP/DHCP specification.
469          */
470         uint8_t htype;
471         /** Hardware address length */
472         uint8_t hlen;
473         /** Number of hops from server */
474         uint8_t hops;
475         /** Transaction ID */
476         uint32_t xid;
477         /** Seconds since start of acquisition */
478         uint16_t secs;
479         /** Flags */
480         uint16_t flags;
481         /** "Client" IP address
482          *
483          * This is filled in if the client already has an IP address
484          * assigned and can respond to ARP requests.
485          */
486         struct in_addr ciaddr;
487         /** "Your" IP address
488          *
489          * This is the IP address assigned by the server to the client.
490          */
491         struct in_addr yiaddr;
492         /** "Server" IP address
493          *
494          * This is the IP address of the next server to be used in the
495          * boot process.
496          */
497         struct in_addr siaddr;
498         /** "Gateway" IP address
499          *
500          * This is the IP address of the DHCP relay agent, if any.
501          */
502         struct in_addr giaddr;
503         /** Client hardware address */
504         uint8_t chaddr[16];
505         /** Server host name (null terminated)
506          *
507          * This field may be overridden and contain DHCP options
508          */
509         char sname[64];
510         /** Boot file name (null terminated)
511          *
512          * This field may be overridden and contain DHCP options
513          */
514         char file[128];
515         /** DHCP magic cookie
516          *
517          * Must have the value @c DHCP_MAGIC_COOKIE.
518          */
519         uint32_t magic;
520         /** DHCP options
521          *
522          * Variable length; extends to the end of the packet.  Minimum
523          * length (for the sake of sanity) is 1, to allow for a single
524          * @c DHCP_END tag.
525          */
526         uint8_t options[0];
527 };
528
529 /** Opcode for a request from client to server */
530 #define BOOTP_REQUEST 1
531
532 /** Opcode for a reply from server to client */
533 #define BOOTP_REPLY 2
534
535 /** BOOTP reply must be broadcast
536  *
537  * Clients that cannot accept unicast BOOTP replies must set this
538  * flag.
539  */
540 #define BOOTP_FL_BROADCAST 0x8000
541
542 /** DHCP magic cookie */
543 #define DHCP_MAGIC_COOKIE 0x63825363UL
544
545 /** DHCP minimum packet length
546  *
547  * This is the mandated minimum packet length that a DHCP participant
548  * must be prepared to receive.
549  */
550 #define DHCP_MIN_LEN 552
551
552 /** Timeouts for sending DHCP packets */
553 #define DHCP_MIN_TIMEOUT ( 1 * TICKS_PER_SEC )
554 #define DHCP_MAX_TIMEOUT ( 10 * TICKS_PER_SEC )
555
556 /** Maximum time that we will wait for ProxyDHCP responses */
557 #define PROXYDHCP_MAX_TIMEOUT ( 2 * TICKS_PER_SEC )
558
559 /** Settings block name used for DHCP responses */
560 #define DHCP_SETTINGS_NAME "dhcp"
561
562 /** Settings block name used for ProxyDHCP responses */
563 #define PROXYDHCP_SETTINGS_NAME "proxydhcp"
564
565 /** Setting block name used for BootServerDHCP responses */
566 #define PXEBS_SETTINGS_NAME "pxebs"
567
568 extern int dhcp_create_packet ( struct dhcp_packet *dhcppkt,
569                                 struct net_device *netdev, uint8_t msgtype,
570                                 const void *options, size_t options_len,
571                                 void *data, size_t max_len );
572 extern int dhcp_create_request ( struct dhcp_packet *dhcppkt,
573                                  struct net_device *netdev,
574                                  unsigned int msgtype, struct in_addr ciaddr,
575                                  void *data, size_t max_len );
576 extern int start_dhcp ( struct job_interface *job, struct net_device *netdev );
577 extern int start_pxebs ( struct job_interface *job, struct net_device *netdev,
578                          struct in_addr pxe_server, unsigned int pxe_type );
579
580 #endif /* _GPXE_DHCP_H */