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