Chapter 39
FreeBSD Networking: liboskit_freebsd_net.a

A note of caution. The design of the networking framework is nowhere near where it should be. However, we, the OSKit developers, felt that networking is important and decided to release what we have. The current implementation has been tested with only the most frequently used calls for TCP and UDP over a single ethernet interface, with a default router on the subnet to which the interface is connected. XXX We have done a simple router test with two interfaces.

39.1 Introduction

This chapter describes the use and implementation of the FreeBSD TCP/IP networking stack.

Note: The file startup/start_network.c provides a convenience function start_network() to quickly start up your network. Then you may use the socket et al functions in the C library, as demonstrated in socket_bsd.c in the example directory. The file socket_com.c contains the same example but uses the COM interfaces without C library support.

 
Limitation/pecularity of the current implementation:

We have not yet implemented “principals” as described in the filesystem framework. All operations run with full privileges.

oskit_socket_t instances created by the networking stack do not currently implement the following methods1: getsockopt, recvmsg/sendmsg

Also, the local loopback interface does not work because it is not properly set up. If you try to connect to 127.0.0.1 or to the local IP address, you’ll see a division by zero trap in freebsd/src/sys/netinet/ip_output.c:302 because the if_mtu field is uninitialized. Required fix is to call the required ”ifconfig” functions for the loopback interface.

39.2 Header Files

39.2.1 freebsd.h: definitions for the FreeBSD-derived networking code

SYNOPSIS

#include <oskit/net/freebsd.h>

DESCRIPTION

Contains function definitions for the functions needed to initialize and use the FreeBSD networking stack.

It defines some convenience functions to initialize the code, to set up an interface and to establish a default route. It defines struct oskit_freebsd_net_ether_if which is opaque to OS clients.

39.3 Interfaces

39.3.1 oskit_freebsd_net_init: initialize the networking code

SYNOPSIS

#include <oskit/net/freebsd.h>

oskit_error_t oskit_freebsd_net_init( [out] oskit_socket_factory_t **outfact);

DIRECTION

OS --> Network stack

DESCRIPTION

This function initializes the FreeBSD networking code.

PARAMETERS
outfact:
*outfact will contain a oskit_socket_factory_t * which can be used according to the specifications in the OSKit socket_factory COM interface in Chapter 10.
RETURNS

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

 
Limitation/pecularity of the current implementation:

oskit_freebsd_net_init will always succeed, and may panic otherwise.

39.3.2 oskit_freebsd_net_open_ether_if: find and open an ethernet interface

SYNOPSIS

#include <oskit/net/freebsd.h>

oskit_error_t oskit_freebsd_net_open_ether_if( struct oskit_etherdev *dev, [out] struct oskit_freebsd_net_ether_if ** out_eif);

DIRECTION

OS --> Network stack

DESCRIPTION

This function is a convenience function to open an ethernet device and create the necessary oskit_netio_t instances to “connect” the netio device drivers to the protocol stack.

Note: The code uses the following internal structure to keep track of an ethernet interface, defined in oskit/net/freebsd.h

struct oskit_freebsd_net_ether_if {

  oskit_etherdev_t *dev; /* ethernet device */
  oskit_netio_t *send_nio; /* netio for sending packets */
  oskit_netio_t *recv_nio; /* netio for receiving packets */
  oskit_devinfo_t info; /* device info */
  unsigned char haddr[OSKIT_ETHERDEV_ADDR_SIZE]; /* MAC address */
  struct ifnet *ifp; /* actual interface seen by BSD code */

};

ifp is the actual interface as seen by the BSD code. recv_nio points to the netio COM interface receiving packets from the ethernet device dev and passing them to the BSD networking code. send_nio is the netio used by the code to send packets. haddr contains the MAC address, and info the device info associated with dev.

PARAMETERS
dev:
The ethernet device to be used with the interface. Note that the FreeBSD net library will take this reference over.
out_eif :
*out_eif points to an oskit_freebsd_net_ether_if structure on success.
RETURNS

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

39.3.3 oskit_freebsd_net_open_first_ether_if: find and open first ethernet interface

SYNOPSIS

#include <oskit/net/freebsd.h>

oskit_error_t oskit_freebsd_net_open_first_ether_if( [out] struct oskit_freebsd_net_ether_if ** out_eif);

DIRECTION

OS --> Network stack

DESCRIPTION

This function is a convenience function to find and open the first ethernet device2 and to create an associated oskit_freebsd_net_ether_if structure.  
Limitation/pecularity of the current implementation:

It leaks references to other ethernet devices, if any.

PARAMETERS
out_eif :
*out_eif points to an oskit_freebsd_net_ether_if structure on success.
RETURNS

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

39.3.4 oskit_freebsd_net_close_ether_if: close an ethernet interface

SYNOPSIS

#include <oskit/net/freebsd.h>

void oskit_freebsd_net_close_ether_if(struct oskit_freebsd_net_ether_if *eif);

DIRECTION

OS --> Network stack

DESCRIPTION

The function closes the interface and frees the oskit_freebsd_net_ether_if structure.

This is currently done by releasing the two netio instances and the oskit_etherdev_t instance in struct oskit_freebsd_net_ether_if.

PARAMETERS
eif :
Interface to be closed.

39.3.5 oskit_freebsd_net_ifconfig: configure an interface

SYNOPSIS

#include <oskit/net/freebsd.h>

oskit_error_t oskit_freebsd_net_ifconfig( struct oskit_freebsd_net_ether_if *eif, char *name, char *ipaddr, char *netmask);

DIRECTION

OS --> Network stack

DESCRIPTION

This is a temporary convenience function which does the setup usually performed by FreeBSD’s ifconfig(8) command. This function is equivalent to the following command:

 ifconfig de0 inet 155.99.214.164 link2 netmask 255.255.255.0
with 155.99.214.164 being the IP address to be used by the ethernet interface, 255.255.255.0 the netmask of the local subnet, and de0 the (arbitrary) name of the interface.
PARAMETERS
eif :
A structure describing the physical interface as returned by oskit_freebsd_net_open_ether_if.
name:
The name of the interface. Should be a 3 byte string of the "abn" where a and b are letters and n is a number. Use different names for different interfaces.
ipaddr:
The address to be used by the interface in "xxx.xxx.xxx.xxx" notation.
netmask:
The netmask of the subnet to be used by the interface in "xxx.xxx.xxx.xxx" notation.
RETURNS

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

39.3.6 oskit_freebsd_net_add_default_route: set a default route

SYNOPSIS

#include <oskit/net/freebsd.h>

oskit_error_t oskit_freebsd_net_add_default_route(char *gateway);

DIRECTION

OS --> Network stack

DESCRIPTION

This function sets a default route.

 
Limitation/pecularity of the current implementation:

Take a look at the implementation in freebsd/net/bsdnet_add_default_route.c.

PARAMETERS
gateway:
The IP address of the default gateway to be set in "xxx.xxx.xxx.xxx" notation.
RETURNS

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