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