Chapter 40
BOOTP Support: liboskit_bootp.a

40.1 Introduction

The OSKit provides a small library that allows OSKit clients to contact a BOOTP server to obtain the information necessary to configure their network parameters, such as IP address or hostname. The implementation is based on RFC 1048/1533.

40.2 External Dependencies

The current implementation requires the user to provide an implementation of the oskit_etherdev interface. Such interfaces are supported by the OSKit’s device driver components. It also requires access to the system clock. The library obtains access to the system clock by calling oskit_clock_init It releases its reference after the BOOTP protocol has finished. Additionally, bootp_dump uses printf.

40.3 API reference

The following sections describe the functions exported by the BOOTP library in detail. All of these functions, as well as the types necessary to use them, are declared in the header file <oskit/net/bootp.h>.

40.3.1 bootp_net_info: BOOTP protocol information structures

SYNOPSIS
 struct bootp_addr_array {
         struct in_addr *addr;   /* array of addresses */
         int             len;    /* number of addresses */
 };
 
 struct bootp_net_info {
         oskit_u32_t    flags;           /* which fields are valid */
         struct in_addr ip;              /* client IP address */
         struct in_addr netmask;         /* subnet mask */
         struct in_addr server;          /* server that replied  */
         struct bootp_addr_array gateway;        /* gateways */
         struct bootp_addr_array dns_server;     /* DNS server address  */
         struct bootp_addr_array time_server;    /* time server address  */
         struct bootp_addr_array log_server;     /* log server address  */
         struct bootp_addr_array lpr_server;     /* LPR server address  */
         oskit_s32_t    time_offset;     /* offset from UTC */
         char *hostname;                 /* client hostname */
         char *server_name;              /* name of replying server */
         char *bootfile_name;            /* boot file name */
         char *domainname;               /* domain name */
         unsigned char server_hwaddr[ETHER_ADDR_SIZE];   /* server address */
 };
DESCRIPTION

The first field of the struct bootp_net_info structure, flags, denotes which of the other fields are valid. flags is an ORed combination of the flag values below. Each flag corresponds to a field in the structure with the same name (in lower case).

All other fields are of one of three types:

  1. An IP address encoded as a struct in_addr,
  2. A string encoded as a char *,
  3. A list of IP addresses encoded in a struct bootp_addr_array.

The following table gives an overview of the flags that are currently supported and the types of the corresponding fields.




Field Type Function



BOOTP_NET_IP IP address IP address
BOOTP_NET_NETMASK IP address netmask
BOOTP_NET_GATEWAY IP address gateway
BOOTP_NET_SERVER IP address server that answered BOOTP request
BOOTP_NET_DNS_SERVER List of IP addrs domain name servers
BOOTP_NET_TIME_SERVER List of IP addrs time servers
BOOTP_NET_LOG_SERVER List of IP addrs log servers
BOOTP_NET_LPR_SERVER List of IP addrs LPR servers
BOOTP_NET_TIME_OFFSET unsigned int see below
BOOTP_NET_HOSTNAME string hostname
BOOTP_NET_SERVER_NAME string name of the BOOTP server
BOOTP_NET_BOOTFILE_NAME string bootfile name
BOOTP_NET_DOMAINNAME string DNS domain name
BOOTP_NET_SERVER_ADDR unsigned char[6] Ethernet MAC address of BOOTP server



The time_offset field specifies the time offset of the local subnet in seconds from Coordinated Universal Time (UTC). It is a signed 32-bit integer, positive numbers indicate west of the Prime Meridian.

40.3.2 bootp_gen: Generate a BOOTP protocol request

SYNOPSIS

#include <oskit/net/bootp.h>

int bootp_gen(oskit_etherdev_t *dev, [in/out] struct bootp_net_info *info, int retries, int timeout);

DESCRIPTION

This function broadcasts retries BOOTP request packets, waiting timeout milliseconds for a reply.

The only field of info that is used as input for the request is the ip field corresponding to BOOTP_NET_IP. See RFC 1048 for more explanation. Users should set this field if they know their IP address; BOOTP_NET_IP needs to be set in flags if this is the case.

Lists of IP addresses and strings are dynamically allocated as needed, users of boopt_gen should pass the info struct to bootp_free to deallocate them.

PARAMETERS
dev:
A pointer to an oskit_etherdev device interface.
info:
The BOOTP info to be used.
retries:
Number of BOOTP request packets that are sent.
timeout:
Timeout in milliseconds.
RETURNS

Returns zero on success, OSKIT_ETIMEDOUT if the operation timed out, or another error code as specified in <oskit/error.h>

RELATED INFORMATION

bootp_net_info

40.3.3 bootp: Generate a BOOTP protocol request (simple interface)

SYNOPSIS

#include <oskit/net/bootp.h>

int bootp(oskit_etherdev_t *dev, [in/out] struct bootp_net_info *info);

DESCRIPTION

This function performs a BOOTP request with a timeout of 200 milliseconds (1/5 of a second) with five retries using bootp_gen.

The only field of info that is used as input for the request is the ip field corresponding to BOOTP_NET_IP. See RFC 1048 for more explanation. Users should set this field if they know their IP address; BOOTP_NET_IP needs to be set in flags if this is the case.

Lists of IP addresses and strings are dynamically allocated as needed, users of boopt_gen should pass the info struct to bootp_free to deallocate them.

PARAMETERS
dev:
A pointer to an oskit_etherdev device interface.
info:
The BOOTP info to be used.
RETURNS

Returns zero on success, or an error code specified in <oskit/error.h> on error.

RELATED INFORMATION

bootp_net_info

40.3.4 bootp_free: Free the result of a BOOTP request

SYNOPSIS

#include <oskit/net/bootp.h>

void bootp_free([in/out] struct bootp_net_info *info);

DESCRIPTION

The function frees data structures that were allocated during a call to bootp_gen.

PARAMETERS
info:
The BOOTP info to be freed.
RELATED INFORMATION

bootp_gen, bootp_net_info

40.3.5 bootp_dump: Dump the result of a BOOTP via printf

SYNOPSIS

#include <oskit/net/bootp.h>

void bootp_dump(struct bootp_net_info *info);

DESCRIPTION

This function prints the contents stored in a bootp_net_info structure to via printf.

PARAMETERS
info:
The BOOTP info to be printed.
RELATED INFORMATION

bootp_net_info, printf