udp.c implements the udp layer in the network service. When a udp device file (e.g., /dev/udp) is opened, udp_open() is called. When a read, write, or ioctl request is made, udp_read(), udp_write(), and udp_ioctl() is called. When the process no longer needs to read or write to the device, udp_close() is called.

Understanding the arrays udp_port_table[] (described in detail on line 61036) and udp_fd_table[] (described in detail on line 61067) is necessary to understanding the udp code. For the following inet.conf file:

eth0 DP8390 0 { default; };
psip1;

two "udp ports", one associated with the ethernet device and one associated with the psip device, will be opened. When a process opens a udp device (e.g., /dev/udp), an element in the udp_fd_table[] is claimed and configured and then used to send and receive udp packets.

Note that "udp ports" as defined by RFC 768 are not the same as the udp ports mentioned above. The udp ports as defined by RFC 768 can range from 0 - 65535 and the udp ports mentioned above range from 0 - 3. It is unfortunate that the "udp ports" mentioned above were so named. To minimize confusion, the udp ports referenced by RFC 768 will be referred to as "common udp ports" whereas the udp ports mentioned above will be either referred to simply as "udp ports" or "physical udp ports".

UDP_FD_NR is the number of udp file descriptors:

UDP_FD_NR = 4 * IP_PORT_MAX = 4 * 4 (remember that there can be two ethernet and two psip ports)

udp_port / udp_port_table[]

For the following example inet.conf file:

eth0 DP8390 0 { default; };
psip1;

there are 2 physical udp ports. Port 0 corresponds to the ethernet device whose corresponding udp device is /dev/udp0 and port 1 corresponds to the psip device whose corresponding udp device is /dev/udp1.

For this configuration file, udp_port_table[] will have two elements, udp_port_table[0] and udp_port_table[1]. udp_init() initializes these two elements to indicate they are unused and then calls udp_main(). udp_main(), in turn, calls ip_open(), which claims an element in ip_fd_table[] (in other words, an "ip file descriptor" is opened). In this way, the udp code and the ip code are interconnected. Note that there is a 1:1 relationship between udp_port_table[] elements and ip_fd_table[] elements. What this means is that a udp device (e.g., /dev/udp0) will use the same ip file descriptor (i.e., the same element of ip_fd_table[]) to handle every request (read, write, and i/o). On the other hand, there is a one-to-many relationship between udp ports and udp file descriptors.



Each element of udp_port_table[] is of type udp_port_t:

typedef struct udp_port

{

          int up_flags;

          int up_state;

          int up_ipfd;

          int up_ipdev;

          acc_t *up_wr_pack;

          ipaddr_t up_ipaddr;

          struct udp_fd *up_next_fd;

          struct udp_fd *up_write_fd;

          struct udp_fd *up_port_any;

          struct udp_fd *up_port_hash[UDP_PORT_HASH_NR];

} udp_port_t;

int up_flags:

#define UPF_EMPTY 0x0
0061039 #define UPF_WRITE_IP 0x1
0061040 #define UPF_WRITE_SP 0x2
0061041 #define UPF_READ_IP 0x4
0061042 #define UPF_READ_SP 0x8
0061043 #define UPF_SUSPEND 0x10
0061044 #define UPF_MORE2WRITE 0x20

Most of these flags are meaningless.

int up_state:

#define UPS_EMPTY 0
0061047 #define UPS_SETPROTO 1
0061048 #define UPS_GETCONF 2
0061049 #define UPS_MAIN 3
0061050 #define UPS_ERROR 4

During initialization, udp_main() is called to initialize the udp port. If the underlying ip port has been already configured, the udp port will be successfully initialized and the udp port's state will become UPS_MAIN, its normal operational state.

int up_ipfd:

As described above, ip_open() is called to open an ip file descriptor. up_ipfd is then set to this file descriptor (i.e., the index of the claimed element in ip_fd_table[]). In this way, the udp code and the ip code are linked. For example, immediately after opening the ip file descriptor, the udp code uses the up_ipfd field to configure the newly opened ip file descriptor.

int up_ipdev:

up_ipdev is equal to the port number of both the udp physical port and its associated ip physical port (which will be the same). For example, for the configuration file above, the udp physical port (and the associated ip physical port) corresponding to the first line (the ethernet entry) will have its up_ipdev field equal to 0 and the second line (the psip entry) will have its up_ipdev field equal to 1.

acc_t *up_wr_pack:

After a packet (e.g., a udp packet) has its udp header assembled but before it is passed to the lower layer (i.e., the ip layer), the packet is placed in this field. Note that this field is not a queue and that there will be at most a single packet placed here at any given time.


ipaddr_t up_ipaddr:

During the initialization of the udp port, udp_put_data() is called (indirectly) to set the ip address of the udp port to the ip address of the udp port's underlying ip port (which was set either by RARP or the "ifconfig -h host-IP-address" command).


struct udp_fd *up_next_fd:
struct udp_fd *up_write_fd:

If a write operation is suspended, up_write_fd is the udp file descriptor whose write operation is suspended.

struct udp_fd *up_port_any:
struct udp_fd *up_port_hash[UDP_PORT_HASH_NR]:

up_port_any and up_port_hash are both link lists of udp file descriptors. When a udp packet arrives at the ethernet/psip port, udp_ip_arrived() searches through both of these linked lists for the corresponding udp file descriptor(s).

UDP_PORT_HASH_NR is #define'd in udp.c as 16. up_port_hash[] is an array that uses a hash to find the corresponding udp file descriptor quickly.

udp_fd / udp_fd_table[]

udp file descriptors (udp_fd's) make up udp_fd_table[]. When a process opens up a udp device file (e.g., /dev/udp), an element in udp_fd_table[] is set up. Many udp file descriptors are associated with each udp physical port (elements in udp_port_table[]). On the other hand, there is a 1:1 ratio between udp physical ports and ip file descriptors (elements in ip_fd_table[]).

typedef struct udp_fd

{

          int uf_flags;

          udp_port_t *uf_port;

          ioreq_t uf_ioreq;

          int uf_srfd;

          nwio_udpopt_t uf_udpopt;

          get_userdata_t uf_get_userdata;

          put_userdata_t uf_put_userdata;

          acc_t *uf_rdbuf_head;

          acc_t *uf_rdbuf_tail;

          size_t uf_rd_count;

          size_t uf_wr_count;

          time_t uf_exp_tim;

          struct udp_fd *uf_port_next;

} udp_fd_t;



typedef struct nwio_udpopt

{

          unsigned long nwuo_flags;

          udpport_t nwuo_locport;

          udpport_t nwuo_remport;

          ipaddr_t nwuo_locaddr;

          ipaddr_t nwuo_remaddr;

} nwio_udpopt_t;

int uf_flags:

uf_flags is a combination of the following flags:

#define UFF_EMPTY 0x0
#define UFF_INUSE 0x1
#define UFF_IOCTL_IP 0x2
#define UFF_READ_IP 0x4
#define UFF_WRITE_IP 0x8
#define UFF_OPTSET 0x10

uf_flags for all the udp file descriptors is initialized to UFF_EMPTY. When the udp file descipriptor is opened, uf_flags is set to UFF_INUSE and will remain so until the udp file descriptor is closed. After the udp file descriptor is opened, udp_ioctl() is called to configure the file descriptor, during which time the UFF_IOCTL_IP flag is set.

If a read request is received and cannot be immediately satisifed, UFF_READ_IP is set. However, all write requests are handled immediately and therefore the UFF_WRITE_IP flag is not important.

udp_port_t *uf_port:

uf_port is the udp physical port number that corresponds with this udp file descriptor. If /dev/udp0 was opened, uf_port will be a pointer to udp_port_table[0]. If /dev/udp1 was opened, uf_port will be a pointer to udp_port_table[1].


ioreq_t uf_ioreq:

If an ioctl request is made of the udp file descriptor (for example, a request to configure the file descriptor), uf_ioreq is set to the request. The different values that uf_ioreq can be are NWIOSUDPOPT (Set UDP OPTions) and NWIOGUDPOPT (Get UDP OPTions). The value of uf_ioreq is contained within a message received by the file system.


int uf_srfd:

The udp file descriptor's associated slot in sr_fd_table[].

nwio_udpopt_t uf_udpopt: (see below)
get_userdata_t uf_get_userdata:
put_userdata_t uf_put_userdata:

uf_get_userdata and uf_put_userdata are set to sr_get_userdata() and sr_put_userdata(), respectively. These values were passed in as arguments in sr_open().

acc_t *uf_rdbuf_head:
acc_t *uf_rdbuf_tail:

uf_rdbuf_head is the head and uf_rdbuf_tail is the tail of the udp file descriptor's read queue. Packets destined for the udp file descriptor are passed up from the lower layers (e.g., from the ethernet code to the ip code and finally to this queue). udp_read() eventually reads from this queue.

size_t uf_rd_count:
size_t uf_wr_count:

The number of bytes requested in a read/write request.

uf_rd_count is the number of bytes requested to be read from the read queue (see uf_rdbuf_head/uf_rdbuf_tail above) and uf_wr_count is the number of bytes requested to be written to lower layers (e.g., the ip code).

time_t uf_exp_tim:

When the read queue of a udp file descriptor is empty and a packet is placed in the queue, the timer (uf_exp_tim) is set. If this timer expires before the packet is read, this packet and all packets that have been subsequently to the read queue are discarded.


struct udp_fd *uf_port_next:

When a udp file descriptor is opened, hash_fd() places the file descriptor in a linked list. uf_port_next links the file descriptor to the next file descriptor in the linked list.


nwio_udpopt_t:
unsigned long nwuo_flags:
udpport_t nwuo_locport:
udpport_t nwuo_remport:
ipaddr_t nwuo_locaddr:
ipaddr_t nwuo_remaddr:


NWUO_RA_SET and NWUO_RP_SET specify that the Remote Address (RA) and the Remote Port (RP) are set for the udp file descriptor and that all packets written to the udp file descriptor are sent to the address/port nwuo_remaddr/nwuo_remport.

If the NWUO_LP_ANY flag is set, the port specified in the outgoing udp header is the port specified in the pseudo udp header that is written to the udp file descriptor along with the payload data. Otherwise, the port is taken from the udp file descriptor's configuration (specifically, the file descriptor's nwuo_locport field).

From ip(4):

"NWUO_RA_SET sets the remote IP address the value of nwuo_remaddr. Only packets from that address will be delivered and all packets will be sent to that address."

"NWUO_RP_SET sets the remote UDP port to the value of nwuo_remport. Only packets with a matching remote port will be delivered and all packets will be sent to that port."

"NWUO_LP_SEL requests the server to pick a port. This port will be in the range from 32768 to 65535 and it will be unique. NWUO_LP_SET sets the local port to the value of the nwuo_locport field. NWUO_LP_ANY does not select a port. Reception of data is therefore not possible but it is possible to send data."

These fields are set during the udp file descriptor's configuration.

UDP_FD_NR is #define'd on line 61021 as 16. udp_fd_table[] is described above.

udp_prep()

udp_prep() allocates memory for udp_port_table[], whose length is equal to the number of interfaces configured. For the following inet.conf file:

eth0 DP8390 0 { default; };
psip1;

there will be 2 interfaces, one for the ethernet port and one for the psip port.

udp_prep() is called a single time from inet.c.

alloc()

On the Minix system, the memory for a process is divided in the following manner:



Instructions (e.g., MOV AX, BX) are stored in the text segment, initialized global variables are stored in the data segment, and uninitialized global variables are stored in the bss. Dynamically allocated memory is allocated from the heap (generally using malloc()), and automatic variables (among other things) are allocated from the stack.

The "break" is the boundary between the (data + bss + the space previously allocated from the heap) and the unallocated space from the heap. alloc(size_t size) increases the size of the (data + bss + already allocated space from the heap) (by calling sbrk()) and returns a pointer to the newly claimed area. If size, alloc()'s only parameter, is a multiple of 4, size bytes are claimed. If size is not a multiple of 4, the value is rounded up to the next multiple of 4 and this space is claimed.

udp_init()

Like udp_prep(), udp_init() is called only once. udp_init() initializes udp_port_table[] and calls sr_add_minor() and udp_main() to complete the initialization of the udp layer.

The following loop initializes udp_fd_table[], which has UDP_FD_NR elements (UDP_FD_NR = 16).

"UFF" stands for "Udp File descriptor Flag".

Code between "#if ZERO" and its matching "#endif" is not executed. Since udp_fd_table[] has already been zeroized by alloc() (see line 61108) and NULL and UFF_EMPTY are both equal to 0, this block does not need to be executed.

bf_logon()

bf_logon() is used by eth_init(), psip_init(), ip_init(), icmp_init(), tcp_init(), and udp_init() to register their functions for freeing buffers. For example, eth_init() calls bf_logon() with an argument of eth_buffree().

After bf_logon() is finished, freereq[] is configured as follows:

freereq[0]=eth_buffree
freereq[1]=psip_buffree
freereq[2]=ip_buffree
freereq[3]=icmp_buffree
freereq[4]=tcp_buffree
freereq[5]=udp_buffree

The following loop initializes
eth0 DP8390 0 { default; };
psip1;

there will be two elements initialized, one for the ethernet port and one for the psip port.

An understanding of udp_port_table[] is necessary.


udp_port / udp_port_table[]

For the following example inet.conf file:

eth0 DP8390 0 { default; };
psip1;

there are 2 physical udp ports. Port 0 corresponds to the ethernet device whose corresponding udp device is /dev/udp0 and port 1 corresponds to the psip device whose corresponding udp device is /dev/udp1.

For this configuration file, udp_port_table[] will have two elements, udp_port_table[0] and udp_port_table[1]. udp_init() initializes these two elements to indicate they are unused and then calls udp_main(). udp_main(), in turn, calls ip_open(), which claims an element in ip_fd_table[] (in other words, an "ip file descriptor" is opened). In this way, the udp code and the ip code are interconnected. Note that there is a 1:1 relationship between udp_port_table[] elements and ip_fd_table[] elements. What this means is that a udp device (e.g., /dev/udp0) will use the same ip file descriptor (i.e., the same element of ip_fd_table[]) to handle every request (read, write, and i/o). On the other hand, there is a one-to-many relationship between udp ports and udp file descriptors.



Each element of udp_port_table[] is of type udp_port_t:

typedef struct udp_port

{

          int up_flags;

          int up_state;

          int up_ipfd;

          int up_ipdev;

          acc_t *up_wr_pack;

          ipaddr_t up_ipaddr;

          struct udp_fd *up_next_fd;

          struct udp_fd *up_write_fd;

          struct udp_fd *up_port_any;

          struct udp_fd *up_port_hash[UDP_PORT_HASH_NR];

} udp_port_t;

int up_flags:

#define UPF_EMPTY 0x0
0061039 #define UPF_WRITE_IP 0x1
0061040 #define UPF_WRITE_SP 0x2
0061041 #define UPF_READ_IP 0x4
0061042 #define UPF_READ_SP 0x8
0061043 #define UPF_SUSPEND 0x10
0061044 #define UPF_MORE2WRITE 0x20

Most of these flags are meaningless.

int up_state:

#define UPS_EMPTY 0
0061047 #define UPS_SETPROTO 1
0061048 #define UPS_GETCONF 2
0061049 #define UPS_MAIN 3
0061050 #define UPS_ERROR 4

During initialization, udp_main() is called to initialize the udp port. If the underlying ip port has been already configured, the udp port will be successfully initialized and the udp port's state will become UPS_MAIN, its normal operational state.

int up_ipfd:

As described above, ip_open() is called to open an ip file descriptor. up_ipfd is then set to this file descriptor (i.e., the index of the claimed element in ip_fd_table[]). In this way, the udp code and the ip code are linked. For example, immediately after opening the ip file descriptor, the udp code uses the up_ipfd field to configure the newly opened ip file descriptor.

int up_ipdev:

up_ipdev is equal to the port number of both the udp physical port and its associated ip physical port (which will be the same). For example, for the configuration file above, the udp physical port (and the associated ip physical port) corresponding to the first line (the ethernet entry) will have its up_ipdev field equal to 0 and the second line (the psip entry) will have its up_ipdev field equal to 1.

acc_t *up_wr_pack:

After a packet (e.g., a udp packet) has its udp header assembled but before it is passed to the lower layer (i.e., the ip layer), the packet is placed in this field. Note that this field is not a queue and that there will be at most a single packet placed here at any given time.


ipaddr_t up_ipaddr:

During the initialization of the udp port, udp_put_data() is called (indirectly) to set the ip address of the udp port to the ip address of the udp port's underlying ip port (which was set either by RARP or the "ifconfig -h host-IP-address" command).


struct udp_fd *up_next_fd:
struct udp_fd *up_write_fd:

If a write operation is suspended, up_write_fd is the udp file descriptor whose write operation is suspended.

struct udp_fd *up_port_any:
struct udp_fd *up_port_hash[UDP_PORT_HASH_NR]:

up_port_any and up_port_hash are both link lists of udp file descriptors. When a udp packet arrives at the ethernet/psip port, udp_ip_arrived() searches through both of these linked lists for the corresponding udp file descriptor(s).

UDP_PORT_HASH_NR is #define'd in udp.c as 16. up_port_hash[] is an array that uses a hash to find the corresponding udp file descriptor quickly.

This is short-lived. up_state will be set to UPS_SETPROTO on line 61173.

sr_fd / sr_fd_table[] / sr_add_minor()

One of the most important data arrays in the network service is sr_fd_table[], an array of 64 struct sr_fd's. Each sr_fd element in sr_fd_table[] corresponds to either a device or an opened file descriptor to a device (i.e., a "channel"):

typedef struct sr_fd

{

          int srf_flags;

          int srf_fd;

          int srf_port;

          sr_open_t srf_open;

          sr_close_t srf_close;

          sr_write_t srf_write;

          sr_read_t srf_read;

          sr_ioctl_t srf_ioctl;

          sr_cancel_t srf_cancel;

          mq_t *srf_ioctl_q, *srf_ioctl_q_tail;

          mq_t *srf_read_q, *srf_read_q_tail;

          mq_t *srf_write_q, *srf_write_q_tail;

} sr_fd_t;

For each device (e.g., /dev/udp0), an element in sr_fd_table[] is configured by sr_add_minor(). For example, for the following inet.conf file:

eth0 DP8390 0 { default; };
psip1;

an element (i.e., a struct sr_fd) is configured for each of the following devices:

/dev/eth0 sr_fd_table[1]
/dev/ip0 sr_fd_table[2]
/dev/tcp0 sr_fd_table[3]
/dev/udp0 sr_fd_table[4]

/dev/psip1 sr_fd_table[17]
/dev/ip1 sr_fd_table[18]
/dev/tcp1 sr_fd_table[19]
/dev/udp1 sr_fd_table[20]




sr_add_minor() is called in the initialization routines for the various protocols: mnx_eth.c (osdep_eth_init()), psip.c (psip_enable()), ip.c (ip_init()), tcp.c (tcp_init()), and udp.c (udp_init()).



When a device file (e.g., /dev/udp0) is opened by a process, the element that corresponds to the device is copied to an element that is currently unoccupied (see sr_open()). In this way, a "channel" is opened. Using this technique, a channel can be opened, closed, and manipulated without affecting the elements of the descriptors initially set by sr_add_minor().


int srf_flags:

srf_flags is a combination of the following:

#define SFF_FREE 0x00
#define SFF_MINOR 0x01
#define SFF_INUSE 0x02
#define SFF_BUSY 0x3C
#define SFF_IOCTL_IP 0x04
#define SFF_READ_IP 0x08
#define SFF_WRITE_IP 0x10
#define SFF_PENDING_REQ 0x30
#define SFF_SUSPENDED 0x1C0
#define SFF_IOCTL_SUSP 0x40
#define SFF_READ_SUSP 0x80
#define SFF_WRITE_SUSP

srf_flags is initialized to SFF_FREE for each element in sr_fd_table[]. If the channel corresponds to a device file, srf_flags is set to SFF_INUSE | SFF_MINOR. If the channel does not correspond to a device file, srf_flags is set simply to SFF_INUSE.

When a request comes in for a read, write, or ioctl operation and the network service is not already processing another request for the same operation, srf_flags is set to SFF_READ_IP, SFF_WRITE_IP, or SFF_IOCTL_IP. However, if an operation is attempted but the underlying protocol is still processing a previous request of the same nature (e.g., udp_write()), the appropriate flag (SFF_IOCTL_SUSP, SFF_READ_SUSP, or SFF_WRITE_SUSP) in srf_flags is set.


int srf_fd, srf_port:

srf_fd and srf_port are both set by sr_add_minor(). For the channels in srf_fd_table[] that correspond to the device files (e.g., /dev/udp0), srf_fd is set to the minor device number of the device. For example, if /dev/udp0 is added to sr_fd_table[] and the interface number of the device file is 0 (see comments for ip_conf[]), then the minor device number is:

if2minor(ifno, dev) = ((0)*16 + UDP_DEV = 0 + 4 = 4

For the channels in srf_fd_table[] that do not correspond to a device file, srf_fd is the file descriptor for the appropriate protocol. For example, if the file system requests that a udp channel be opened, srf_open is dereferenced and udp_open() is called. udp_open() opens a udp file descriptor and returns the index of the corresponding element in udp_fd_table[]. srf_fd is set to the index of this element.

Later, when the file system requests a read or a write on the open channel, srf_fd is passed into the protocol-specific read or write function (e.g., udp_read()), allowing the protocol-specific function to locate the appropriate file descriptor (e.g., udp file descriptor).

srf_port is more straight-forward. srf_port is the index in the protocol's port table. For example, if a system has two udp device files (/dev/udp0 and /dev/udp1), udp_port_table[] will have two entries, 0 and 1. Therefore, srf_port for the entry in sr_fd_table[] that corresponds to /dev/udp0 will be 0 and srf_port for the entry that corresponds to /dev/udp1 will be 1.


sr_open_t srf_open:
sr_close_t srf_close:
sr_write_t srf_write:
sr_read_t srf_read:
sr_ioctl_t srf_ioctl:
sr_cancel_t srf_cancel:

The fields above are all protocol-specific functions and and are all set by sr_add_minor(). For example, when sr_add_minor() is called by udp_init(), srf_open, srf_close, srf_write, srf_read, srf_ioctl, and srf_cancel are set to the pointers of the functions udp_open(), udp_close(), udp_write(), udp_read(), udp_ioctl(), and udp_cancel(). Later, when the file system makes a request to the network service, these functions will be called. For example, if the file system requests that data is written to a channel, srf_write is dereferenced and, if the channel is a udp channel, udp_write() is called.

mq_t *srf_ioctl_q, *srf_ioctl_q_tail:
mq_t *srf_read_q, *srf_read_q_tail:
mq_t *srf_write_q, *srf_write_q_tail:

The fields above are linked lists of ioctl, read, and write messages waiting to be processed. When a message requesting an ioctl, read, or write operation is received, the message is placed at the end of the linked list (unless there are no previous messages of this type that have not already been processed).


After the initialization of the network service, sr_rec() is called upon receipt of messages from the file system in the endless loop within main(). sr_rec() then calls a function to handle the specific request. For open requests, sr_rec() calls sr_open(); for read, write, and io requests, sr_rec() calls sr_rwio(); for close requests, sr_rec() calls sr_close(); for cancel requests, sr_rec() calls sr_cancel().

udp_main()

udp_main(udp_port) is called in two scenarios:

1) The udp physical port udp_port, udp_main()'s only parameter, is being initialized. During the initialization, udp_main() calls ip_open() to open up an ip file descriptor before calling ip_ioctl() twice to configure the newly opened ip file descriptor (the first call) and to get the ip address of the underlying ip port (the second call).

2) After this initial call to udp_main(), all subsequent calls will finish up the udp port's initialization (if necessary). After this initialization is complete, udp_main() attempts to configure (by calling udp_ioctl()) any udp file descriptors whose configuration was previously suspended and then finally calls read_ip_packets() to process any ip packets waiting to be delivered to udp_port.

udp_main()

udp_main(udp_port) is called in two scenarios:

1) The udp physical port udp_port, udp_main()'s only parameter, is being initialized. During the initialization, udp_main() calls ip_open() to open up an ip file descriptor before calling ip_ioctl() twice to configure the newly opened ip file descriptor (the first call) and to get the ip address of the underlying ip port (the second call).

2) After this initial call to udp_main(), all subsequent calls will finish up the udp port's initialization (if necessary). After this initialization is complete, udp_main() attempts to configure (by calling udp_ioctl()) any udp file descriptors whose configuration was previously suspended and then finally calls read_ip_packets() to process any ip packets waiting to be delivered to udp_port.

It is important to understand that lines 61172 - 61208 initialize the udp physical port udp_port, udp_main()'s only parameter. If the initialization is suspended for whatever reason, subsequent calls to udp_main() will continue where the code was previously suspended. In normal operation, the udp physical port's state is UPS_MAIN.

The up_ipfd field of a udp physical port is the udp port's associated ip file descriptor.

Note that the first and second arguments are the same. The first argument is the ip port number that corresponds to this udp port number and the second argument is the udp port number. udp_port_table[0] will always correspond to ip_port_table[0], udp_port_table[1] will always correspond to ip_port_table[1], and so on. These port numbers will always be the same. So, for example, if udp_port_table[0] was being configured, the first and second arguments would be zero.


ip_open()

ip_open() finds an available ip file descriptor in ip_fd_table[], sets a few of the ip file descriptor's fields, and then returns the index of the ip file descriptor within ip_fd_table[]. ip_open() is called by higher-level code (e.g., udp_main()) and the returned ip file descriptor is then associated with a higher-level port (e.g., udp port).



Note that there will only be a few ip file descriptors open at any given time. There will be an ip file descriptor opened for each interface for each client (udp, tcp, and icmp) and there will be one ip file descriptor opened each time the /dev/ip file is opened directly (as opposed to when, for example, the /dev/udp file is opened).

If this point in the code is reached by udp_init() calling udp_main(), ip_open() is unlikely to fail to acquire an ip file descriptor (i.e., ip_open() returns a negative value). This would only occur if there were more than 32 protocols above ip (there are 32 ip file descriptors; in other words ip_fd_table[] has 32 elements).

ip_ioctl()

ip_ioctl(fd, req) performs one of several tasks on the ip file descriptor whose index within ip_fd_table[] is fd, the first parameter. The task performed depends on req, the second parameter.

NWIOSIPOPT: Set the options (the if_ipopt field of the ip file descriptor) on the ip file descriptor. For example, during the initialization of a physical udp port, ip_ioctl() is called with req equal to NWIOSIPOPT.

An example of an ip iption (i.e., ip flag) is the NWIO_EN_BROAD flag. This flag is set if the ip file descriptor accepts broadcast packets. The options desired are obtained from the user process. For example, if a udp port opened up the ip file descriptor, udp_get_data() is (indirectly) called to obtain the configuration data.

NWIOGIPOPT: Send the ip file descriptor's options to the user process requesting the information. The information is sent in a struct of type nwio_ipopt_t.

NWIOSIPCONF: Configure the ip port (for example, the ip address can be configured) that corresponds to the ip file descriptor fd. The fields are obtained from the user process. For a detailed description of the different settings, click here.

NWIOGIPCONF: Send the ip address/subnet information (i.e., send a nwio_ipconf_t struct) to the next higher layer. For example, if the next higher layer is udp, ip_ioctl() calls (indirectly) udp_put_data(), which sets the ip address for the udp port (i.e., sets the up_ipaddr field of the corresponding element in udp_port_table[]).

NWIOGIPIROUTE, NWIOSIPIROUTE, NWIOGIPOROUTE, NWIODIPIROUTE, NWIOSIPOROUTE: It is possible to influence the route taken by a packet. These ioctl requests alter the input and output routing tables.

ip_ioctl() cannot return NW_SUSPEND when called with NWIOSIPOPT as the second parameter.

ip_ioctl() calls udp_get_data() (indirectly), which sets up_state to UPS_GETCONF (if there aren't any problems). If up_state is indeed set to UPS_GETCONF, the code falls through.

ip_ioctl()

ip_ioctl(fd, req) performs one of several tasks on the ip file descriptor whose index within ip_fd_table[] is fd, the first parameter. The task performed depends on req, the second parameter.

NWIOSIPOPT: Set the options (the if_ipopt field of the ip file descriptor) on the ip file descriptor. For example, during the initialization of a physical udp port, ip_ioctl() is called with req equal to NWIOSIPOPT.

An example of an ip iption (i.e., ip flag) is the NWIO_EN_BROAD flag. This flag is set if the ip file descriptor accepts broadcast packets. The options desired are obtained from the user process. For example, if a udp port opened up the ip file descriptor, udp_get_data() is (indirectly) called to obtain the configuration data.

NWIOGIPOPT: Send the ip file descriptor's options to the user process requesting the information. The information is sent in a struct of type nwio_ipopt_t.

NWIOSIPCONF: Configure the ip port (for example, the ip address can be configured) that corresponds to the ip file descriptor fd. The fields are obtained from the user process. For a detailed description of the different settings, click here.

NWIOGIPCONF: Send the ip address/subnet information (i.e., send a nwio_ipconf_t struct) to the next higher layer. For example, if the next higher layer is udp, ip_ioctl() calls (indirectly) udp_put_data(), which sets the ip address for the udp port (i.e., sets the up_ipaddr field of the corresponding element in udp_port_table[]).

NWIOGIPIROUTE, NWIOSIPIROUTE, NWIOGIPOROUTE, NWIODIPIROUTE, NWIOSIPOROUTE: It is possible to influence the route taken by a packet. These ioctl requests alter the input and output routing tables.

If the ip port does not already have an assigned ip address, ip_ioctl() returns NW_SUSPEND.

The second time ip_ioctl() (indirectly) calls udp_put_data(), udp_put_data() sets up_state to UPS_MAIN (if the first call to ip_ioctl() was successful).

If the code has reached this point, the initialization of the udp physical port is complete and the port is now in its normal operational state (UPS_MAIN). Note that a udp port cannot be read from or written to until its state is UPS_MAIN.

The code below attempts to configure the udp file descriptors whose previous configuration attempts were suspended and then calls read_ip_packets() to process any packets waiting to be delivered to udp file descriptors associated with this udp port.

If there are any open udp file descriptors associated with the udp physical port udp_port, udp_main()'s only parameter, that are waiting for ioctl, call udp_ioctl() for the udp file descriptor. Obviously, if udp_main() is called as part of the initialization, no udp file descriptor is waiting for ioctl since no udp file descriptor has yet been opened.

udp_ioctl()

udp_ioctl() handles the following ioctl requests for udp file descriptors:


NWIOSUDPOPT: Set UDP OPTions. udp_ioctl() calls udp_setopt(), which gets data (specifically, a nwio_udpopt_t struct) from the user process and sets the options accordingly. Before a udp file descriptor can be used, the file descriptor must be configured by udp_ioctl().


NWIOGUDPOPT: Get UDP OPTions. Sends a nwio_udpopt_t struct to the process that opened the udp file descriptor which contains the configuration data for the udp file descriptor.


udp_ioctl() is called (indirectly) by sr_rwio().

read_ip_packets() / udp

read_ip_packets() is called only a single time, during the initialization of the udp code.

read_ip_packets() reads all packets (by repeatedly calling ip_read()) in the udp port's associated ip file descriptor's read queue until all of the packets have either been delivered to the processes that issued the read requests (provided that the packets have not expired) or placed in the udp file descriptor's read queue.

read_ip_packets() is also called by udp_get_data(). However, this line of code is never executed (see comment for line 61391).

udp_open()

udp_open(port, srfd, get_getuserdata, put_userdata, put_pkt), called from sr_open(), finds the first unused element in udp_fd_table[], configures this udp file descriptor with the arguments passed in, and returns the index of the (newly configured) element within udp_fd_table[].

The parameters are explained below:

When a process opens one of the udp devices (e.g., /dev/udp), sr_open() claims an unused element in sr_fd_table[] and copies the element of sr_fd_table[] that corresponds to the device to this unused element. This element number is then passed in as the second argument (srfd). Later, when the process wishes to read or write or perform ioctl on this open file descriptor, it includes this sr file descriptor in the message that it sends the file system.

For the following example inet.conf file:

eth0 DP8390 0 { default; };
psip1;

there are 2 ports. Port 0 corresponds to the ethernet device and port 1 corresponds to the psip port.

get_userdata is a pointer to the function that gets the data from the process. This function will always be sr_get_userdata().

sr_put_userdata is a pointer to the function that copies data into the user process. This function will always be sr_put_userdata().

The put_pkt parameter is not used in this function.

Find the first unused entry in udp_fd_table[]. The index of this element is eventually returned by udp_open().

If the 16 UDP file descriptors are all unavailable, return EAGAIN.

EAGAIN stands for "resource temporarily unavailable." EAGAIN is #define'd in include/errno.h.

Mark the element as being used.

Link the newly claimed udp file descriptor to its associated udp port and its associated sr file descriptor.

Recall the relationship between the various arrays:

Clear all the udp file descriptor's flags (UDP_DEF_OPT is #define'd as NWUO_NOFLAGS; NWUO_NOFLAGS is #define'd as 0x0000L).

Before the udp file descriptor may be read from or written to, the udp file descriptor must be configured using the NWIOSUDPOPT (NetWork IO Set UDP OPTions) ioctl call. A NWIOSUDPOPT ioctl call causes udp_setopt() (line 61473) to be called. udp_setopt() sets many of the uf_udpopt fields.

The uf_get_userdata and uf_put_userdata fields are set to pointers to sr_get_userdata() and sr_put_userdata(), respectively. These values were passed in as arguments in sr_add_minor().


sr_get_userdata()

sr_get_userdata() is the counterpart to sr_put_userdata() and does one of two things:

1) Copies data from a user process to a buffer (to be more specific, a chain of accessors) within the network service (this process). This can be either ioctl data (in which case, for_ioctl is TRUE) or data. For example, udp_setopt() (indirectly) calls sr_get_userdata() to get configuration data. Also, restart_write_fd() (indirectly) calls sr_get_userdata() before passing data onto the ip code.

2) Sends a REVIVE message to the file system (FS). For example, if an illegal option is selected while configuring a udp file descriptor, reply_thr_get() is called, which then (indirectly) calls sr_get_userdata(), passing in EBADMODE for the parameter count. restart_write_fd() also (indirectly) calls sr_get_userdata() to send a REVIVE message back to the FS indicating the number of bytes read after copying the data from the user process.

sr_get_userdata() is often called twice in close succession. The first time to attempt to copy the data from the user process and then the second time to send a message to the FS indicating whether the copy operation was successful and, if it was successful, the number of bytes copied.

In my opinion, like sr_put_userdata(), this function should have been made into two functions. As it is, it is too confusing.

Return the index of the newly claimed udp_fd_table[] element.

udp_get_data()

udp_get_data() is called only indirectly by the ip code. udp_get_data() has a number of uses, which makes it a somewhat difficult function to understand.

During the initialization of a udp port (when the state of the udp port is UPS_SETPROTO), udp_get_data() is called twice. The first time udp_get_data() is called, the ip code tries to initialize the udp port's underlying ip file descriptor. udp_get_data() is called the second time (through reply_thr_get()) to change the state of the udp port to UPS_GETCONF.

After initialization (when the state of the udp port is UPS_MAIN), udp_get_data() is called to send either packets or configuration data to the underlying layer (i.e., the ip layer). For a write to a udp file descriptor, a packet is placed in the udp file descriptor's associated udp port's write field and udp_get_data() is then called by ip_write() to move the data to the ip layer. If ip_ioctl() is called to configure a udp port, ip_ioctl() calls udp_get_data() to get configuration data for the port (including, for example, the ip address of the port).

After a write operation is called, udp_get_data() is called a second time to clear some of the udp port's fields in preparation for the next write.

Find the udp port whose index within udp_port_table[] is port, the first parameter of udp_get_data().

If the state of the port is UPS_SETPROTO, get configuration data for the underlying ip file descriptor. If the state is UPS_MAIN (the operational state), get packets.

During initialization, as described above, ip_ioctl() calls udp_get_data() (indirectly through reply_thr_get()) to change the udp port's state to UPS_GETCONF.

If the initialization of the udp port was previously not able to finish, this is a chance for the initialization to finally finish. Also, handle unprocessed udp ioctl requests (if there are any) and handle unprocessed ip packets (again, if there are any).


udp_main()

udp_main(udp_port) is called in two scenarios:

1) The udp physical port udp_port, udp_main()'s only parameter, is being initialized. During the initialization, udp_main() calls ip_open() to open up an ip file descriptor before calling ip_ioctl() twice to configure the newly opened ip file descriptor (the first call) and to get the ip address of the underlying ip port (the second call).

2) After this initial call to udp_main(), all subsequent calls will finish up the udp port's initialization (if necessary). After this initialization is complete, udp_main() attempts to configure (by calling udp_ioctl()) any udp file descriptors whose configuration was previously suspended and then finally calls read_ip_packets() to process any ip packets waiting to be delivered to udp_port.

During initialization (as described above), ip_ioctl() (indirectly) calls udp_get_data() to get configuration data appropriate for a udp port's underlying ip file descriptor (in the form of an nwio_ipopt_t struct).

nwio_ipopt

The nwio_ipopt struct is used to pass ip option values from a higher-layer level (e.g., icmp, udp) to the ip layer during the configuration of an ip file descriptor. Note that an ip file descriptor cannot be used until it is configured.

typedef struct nwio_ipopt

{

          u32_t nwio_flags;

          ipaddr_t nwio_rem;

          ip_hdropt_t nwio_hdropt;

          u8_t nwio_tos;

          u8_t nwio_ttl;

          u8_t nwio_df;

          ipproto_t nwio_proto;

} nwio_ipopt_t;

u32_t nwio_flags:

nwio_flags will be a combination of the flags below. Most of the flags within a set are exclusionary. For example, both NWIO_REMSPEC and NWIO_REMANY can't both be set.

Note that "EN" stands for "ENable" and "DI" stands for "DIsable".

#define NWIO_EXCL 0x00000001l
#define NWIO_SHARED 0x00000002l
#define NWIO_COPY 0x00000003l

From ip(4):

"The options covered by NWIO_ACC_MASK control the number of channels that can use one IP protocol. If NWIO_EXCL is specified then only that channel can use a certain IP protocol. If NWIO_SHARED then multiple channels that all have to specify NWIO_SHARED can use the same IP protocol, but incoming packets will be delivered to a most one channel. NWIO_COPY does not impose any restrictions. Every channel gets a copy of an incoming packet."

Note that, for whatever reason, NWIO_EXCL behaves exactly as NWIO_COPY. Every channel receives a copy of an incoming packet.

The access flags are important during the read of an ip file descriptor.

#define NWIO_EN_LOC 0x00000010l
#define NWIO_DI_LOC 0x00100000l
#define NWIO_EN_BROAD 0x00000020l
#define NWIO_DI_BROAD 0x00200000l

NWIO_EN_LOC specifies that this file descriptor can receive packets destined for this machine and NWIO_EN_BROAD specifies that this file descriptor can receive broadcast packets.

#define NWIO_REMSPEC 0x00000100l
#define NWIO_REMANY 0x01000000l

If the NWIO_REMANY flag is set, this file descriptor can send packets to any destination. If, on the other hand, the NWIO_REMSPEC flag is set, this file descriptor can only communicate with a single host. This host is specified by nwio_rem (see below).

#define NWIO_PROTOSPEC 0x00000200l
#define NWIO_PROTOANY 0x02000000l

If NWIO_PROTOANY is set, the ip file descriptor will accept packets of any protocol type. However, if NWIO_PROTOSPEC is set, only packets with a protocol type of nwio_proto (see below) are accepted.

#define NWIO_HDR_O_SPEC 0x00000400l
#define NWIO_HDR_O_ANY 0x04000000l

If the NWIO_HDR_O_SPEC flag in nwio_flags is set, nwio_hdropt (see below) must be set. If this is the case, the extra header information for all outgoing packets will be taken from nwio_hdropt, nwio_tos, nwio_ttl, and nwio_df (see below).

#define NWIO_RWDATONLY 0x00001000l
#define NWIO_RWDATALL 0x10000000l

NWIO_RWDATALL is a little tricky. If the NWIO_RWDATALL flag is set, the header was omitted when passing the packet down to ip code and the NWIO_EN_LOC, NWIO_DI_BROAD, NWIO_REMSPEC, NWIO_PROTOSPEC and NWIO_HDR_O_SPEC flags must all be set (and NWIO_REMANY and NWIO_PROTOANY cannot be set). In other words, this file descriptor can only send the data to one destination using one protocol.

During the configuration of an ip file descriptor being opened by the udp code, ip_ioctl() calls udp_get_data() (indirectly) to get configuration information. udp_get_data() returns the following configuration information:

NWIO_COPY | NWIO_EN_LOC | NWIO_EN_BROAD | NWIO_REMANY | NWIO_PROTOSPEC | NWIO_HDR_O_ANY | NWIO_RWDATALL

ipaddr_t nwio_rem:

If the NWIO_REMSPEC flag in nwio_flags is set (see above), nwio_rem is the ip address of the destination host.


ip_hdropt_t nwio_hdropt:

The ip header length is flexible to allow for extra options. For example, in addition to the normal fields (e.g., destination ip address), an ip header may specify the route it wishes to take or request that the route be recorded.

that it wishes to record a route or to ip_chk_hdropt().


u8_t nwio_tos:

"tos" stands for "Type Of Service". nwio_tos is initialized to 0 but can be changed by ip_ioctl().


u8_t nwio_ttl:

"ttl" stands for "Time To Live", which is the number of hops that a packet can take before being dropped by a router. nwio_ttl is initialized to 255 but can be changed by ip_ioctl().


u8_t nwio_df:

nwio_df specifies whether fragmentation is allowed or not. nwio_df is initialized to FALSE but, again, can be changed by ip_ioctl().


ipproto_t nwio_proto:

nwio_proto can take one of the values below. Obviously, if the udp code opens up an ip file descriptor, nwio_proto will be IPPROTO_UDP. The same is true for icmp and tcp.

#define IPPROTO_ICMP 1
#define IPPROTO_TCP 6
#define IPPROTO_UDP 17

This field is used in conjunction with the NWIO_PROTOSPEC flag in nwio_flags. If this flag is set, nwio_proto must be set.

bf_memreq()

After the buffers have been initialized, accessors[] looks like the following:



bf_memreq() allocates accessors to the caller. For example, if 1514 bytes of buffer space are requested immediately after the network process starts and each buffer is 512 bytes (the default), then accessors[] will look like the following:



Note that three elements of accessors[] have been removed from buf512_freelist and that the head of the chain of the 3 accessors is returned by bf_memreq(). Also note that the acc_linkC and buf_linkC fields have been set to one and acc_length and acc_offset have been set to their appropriate values.

So what happens if there are not enough buffers on the buf512_freelist to satisfy a request? On lines 2280-2290 of buf.c, functions that free buffers for the specific clients (e.g., eth_buffree()) are called until there are enough buffers on buf512_freelist.

For a complete description of the network service's buffer management, click here.

ptr2acc_data()

The macro ptr2acc_data is #define'd in inet/generic/buf.h as:

#define ptr2acc_data(/* acc_t * */ a) (bf_temporary_acc=(a), \
(&bf_temporary_acc->acc_buffer->buf_data_p[bf_temporary_acc-> \
acc_offset]))

ptr2acc_data() simply returns a pointer to the actual data within an accessor.

ptr2acc_data() is usually called so that the fields of a header (e.g., ip header) can be analyzed.

Choose values for nwio_proto and nwio_flags that make sense for an ip file descriptor supporting the udp layer.

Remove the first packet in the udp port's write queue and send the file system (FS) a message indicating success. offset, udp_get_data()'s second parameter, contains the message to be sent to the FS.

After a (successful or unsuccessful) write operation, ip_write.c's error_reply() is called with a value of 0 (zero) for count in order to get ready for the next write.

ip_ioctl.c's reply_thr_get() (indirectly) calls udp_get_data() to send the results of operations within ip_ioctl().

Free the packet, whether the write operation was successful or unsuccessful.


bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

After a packet (e.g., a udp packet) has its udp header assembled but before it is passed to the lower layer (i.e., the ip layer), the packet is placed in this field. Since the packet has either been processed or rejected by the ip layer, the field may be cleared.

It is VERY important to note that NW_WRITE_SP is never set. In previous versions of the network service, ip_write() (line 62324) could return NW_SUSPEND, which would set the UPF_WRITE_SP flag for the udp port. However, ip_write() currently only returns NW_OK. Therefore, the code on lines 61322 - 61335 is never executed and, for this reason, these lines will not be documented).

UPF_WRITE_IP was set preceding the call to ip_write() on line 62323. Since the operation (whether successful or unsuccessful) is over, the flag is cleared.

If called from ip_write() on line 43040, this else clause is executed. udp_get_data() passes the packet from the udp port's write queue that was placed there by restart_write_fd().

bf_cut()

If a section of a linked list needs to be duplicated, bf_cut(data, offset, length) is called. For example, if a section of length 50 starting at an offset of 75 of the linked list below needs to be duplicated, bf_cut(data, 75, 50) is called:



Note that the original linked list remains unchanged and that acc_linkC for all the accessors in the new linked list is one.

If length (the second parameter) is zero, simply duplicate the first accessor in the linked list but set acc_length=0 and acc_next=null. In other words, create a linked list of length one accessor whose acc_length is 0.

bf_cut() is used in a number of scenarios, including cutting a received ethernet packet to size.

For a full description of the network service's buffer management, click here.

udp_put_data()

During the initialization of the udp layer, the udp code calls ip_ioctl() twice. The second time, the udp code calls ip_ioctl() with an argument of NWIOGIPCONF. ip_ioctl() then (indirectly) calls udp_put_data() twice. The first call to udp_put_data() is to get the underlying ip file descriptor's ip address (to which it sets the udp port's up_ipaddr field). The second call to udp_put_data() simply sets the udp port's state to UPS_MAIN.

After the initialization (when the state of the udp port is UPS_MAIN), udp_put_data() is called only by ip_read() to handle the (unlikely) case that the underlying ip file descriptor was not already configured.

During the initialization of the udp layer, the udp code calls ip_ioctl() twice. The second time, the udp code calls ip_ioctl() with an argument of NWIOGIPCONF. ip_ioctl() then (indirectly) calls udp_put_data() twice. The first call to udp_put_data() is to get the underlying ip file descriptor's ip address (to which it sets the udp port's up_ipaddr field). The second call to udp_put_data() simply sets the udp port's state to UPS_MAIN.

If the call to ip_ioctl() during the udp layer's initialization was successful, simply set the state of the udp port's to UPS_MAIN. If, however, the call to ip_ioctl() was not successful because the ip file descriptor's underlying ip port's ip address was not set, call udp_main() to try the initialization again.

udp_main()

udp_main(udp_port) is called in two scenarios:

1) The udp physical port udp_port, udp_main()'s only parameter, is being initialized. During the initialization, udp_main() calls ip_open() to open up an ip file descriptor before calling ip_ioctl() twice to configure the newly opened ip file descriptor (the first call) and to get the ip address of the underlying ip port (the second call).

2) After this initial call to udp_main(), all subsequent calls will finish up the udp port's initialization (if necessary). After this initialization is complete, udp_main() attempts to configure (by calling udp_ioctl()) any udp file descriptors whose configuration was previously suspended and then finally calls read_ip_packets() to process any ip packets waiting to be delivered to udp_port.

During the initialization of the udp layer, the udp code calls ip_ioctl() with an argument of NWIOGIPCONF. ip_ioctl() then (indirectly) calls udp_get_data(). The udp code makes this call to ip_ioctl() in order to get the underlying ip file descriptor's ip address (to which it sets the udp port's up_ipaddr field).

nwio_ipconf_t

Type nwio_ipconf_t contains the ip address information of an ip port (i.e., an element in ip_port_table[]:

typedef struct nwio_ipconf

{

          u32_t nwic_flags;

          ipaddr_t nwic_ipaddr;

          ipaddr_t nwic_netmask;

} nwio_ipconf_t;

nwic_flags: reflects whether the ip address and the subnet mask have been set. The different flags are as follows:

#define NWIC_NOFLAGS 0x0
#define NWIC_FLAGS 0x3
#define NWIC_IPADDR_SET 0x1
#define NWIC_NETMASK_SET 0x2

nwic_ipaddr: the ip address (e.g., 192.168.5.5)

nwic_netmask: the subnet mask (e.g., 255.255.255.0)

bf_packIffLess()

If the data in a linked list of accessors is less than min_len (the second parameter), bf_packIffLess(pack, min_len) packs the data by calling bf_pack().

bf_packIffLess() is often called to ensure that a packet's header is in a single contiguous buffer so that the individual fields of the header can be easily accessed.

For a detailed description of the network service's buffer management, click here.

ptr2acc_data()

The macro ptr2acc_data is #define'd in inet/generic/buf.h as:

#define ptr2acc_data(/* acc_t * */ a) (bf_temporary_acc=(a), \
(&bf_temporary_acc->acc_buffer->buf_data_p[bf_temporary_acc-> \
acc_offset]))

ptr2acc_data() simply returns a pointer to the actual data within an accessor.

ptr2acc_data() is usually called so that the fields of a header (e.g., ip header) can be analyzed.

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

udp_get_data() is called only from ip_read() if IFF_OPTSET has not been set (i.e., the ip file descriptor has not been configured). Under normal circumstances, this flag will be set during the network initialization. If this flag has not been set, the network service terminates.

compare()

compare is #define'd in inet/generic/assert.h:

#define compare(a,t,b) (!((a) t (b)) ? bad_compare(this_file, __LINE__, \
(a), #a " " #t " " #b, (b)) : (void) 0)

and bad_compare() is defined in inet/inet.c.

If the relationship between the 3 arguments in compare() does not hold, some debugging output is emitted and then Minix is terminated.

For example, if compare(result, >=, 0) is called and result (the first argument) is -1, Minix will be terminated.

read_ip_packets() / udp

read_ip_packets() is called only a single time, during the initialization of the udp code.

read_ip_packets() reads all packets (by repeatedly calling ip_read()) in the udp port's associated ip file descriptor's read queue until all of the packets have either been delivered to the processes that issued the read requests (provided that the packets have not expired) or placed in the udp file descriptor's read queue.

read_ip_packets() is also called by udp_get_data(). However, this line of code is never executed (see comment for line 61391).

udp_get_data() will not be called with a non-zero value for data if the state of the udp port is UDP_MAIN. Since if_put_pkt will be set to udp_ip_arrived() for an ip file descriptor opened by the udp code, ip_read() (indirectly) calls udp_ip_arrived() instead of udp_get_data().

udp_ip_arrived()

udp_ip_arrived() is called either (indirectly) from the ip code or from udp_put_data() and is one of the last functions called for a read request from a user process. udp_ip_arrived() does some checks (e.g., a checksum check) and figures out the destination udp file descriptor before calling udp_packet2user() to deliver the packet to the process that requested the read.

udp_ioctl()

udp_ioctl() handles the following ioctl requests for udp file descriptors:


NWIOSUDPOPT: Set UDP OPTions. udp_ioctl() calls udp_setopt(), which gets data (specifically, a nwio_udpopt_t struct) from the user process and sets the options accordingly. Before a udp file descriptor can be used, the file descriptor must be configured by udp_ioctl().


NWIOGUDPOPT: Get UDP OPTions. Sends a nwio_udpopt_t struct to the process that opened the udp file descriptor which contains the configuration data for the udp file descriptor.


udp_ioctl() is called (indirectly) by sr_rwio().

Find the udp file descriptor with an index of fd (the first parameter of udp_ioctl()) within udp_fd_table[].

Find the udp port that corresponds to the udp file descriptor.

Indicate that an ioctl operation is in progress and specify which operation (NWIOSUDPOPT or NWIOGUDPOPT) has been requested (next line).

During the initialization of the network service, all udp ports are initialized. Near the end of this initialization, the state of the udp port is set to UPS_MAIN.

NWIOSUDPOPT stands for "NetWork IO Set UDP OPTions." This operation attempts to set the options for a udp file descriptor.

Before a udp file descriptor may be used (e.g., before the udp file descriptor may be read), its options must be set.

udp_setopt()

udp_setopt() is called by only a single function, udp_ioctl().

Before a udp file descriptor can be used, the file descriptor must be configured by udp_setopt(). udp_setopt() gets the configuration data from the process that opened the file descriptor, verifies that the configuration data is valid, sets the uf_udpopt field of the udp file descriptor to reflect the new configuration, and then marks the file descriptor as configured (i.e., sets the UFF_OPTSET flag in uf_flags).

NWIOGUDPOPT stands for "NetWork IO Get UDP OPTions." This operation returns the options (in a nwio_udpopt_t struct) of a udp file descriptor to the user process that opened it.

The steps involved are:

1) Acquire a buffer (lines 61452-61454).
2) Copy the options and the ip address of the port to the buffer (lines 61456-61457).
3) Send the buffer to the user process (lines 61458-61459).


From ip(4):

"The NWIOGUDPOPT ioctl returns the current options that result from the
default options and the options set with NWIOSUDPOPT. When NWUO_LP_SEL
or NWUO_LP_SET is selected, the local port is returned in nwuo_locport.
When NWUO_RP_SET is selected, the remote port is returned in nwuo_remport.
The local address is always returned in nwuo_locaddr, and when NWUO_RA_SET is selected, the remote address is returned in nwuo_remaddr."


nwio_udpopt_t

struct nwio_udpopt_t contains configuration information for a udp file descriptor. The uf_udpopt field of a udp file descriptor has type nwio_udpopt_t.

typedef struct nwio_udpopt 

{ 

     unsigned long nwuo_flags; 

     udpport_t nwuo_locport; 

     udpport_t nwuo_remport; 

     ipaddr_t nwuo_locaddr; 

     ipaddr_t nwuo_remaddr; 

} nwio_udpopt_t;

nwuo_flags:

#define NWUO_NOFLAGS 0x0000L
#define NWUO_ACC_MASK 0x0003L
#define NWUO_EXCL 0x00000001L
#define NWUO_SHARED 0x00000002L
#define NWUO_COPY 0x00000003L

File descriptors that share the same port must have the same access permissions (i.e., their NWUO_EXCL, NWUO_SHARED, and NWUO_COPY flags are the same).

There does appear to be an error in the code, however. If the NWUO_EXCL (exclusive access) flag is set, only one udp file descriptor should have access to the common udp port (0-65535). Unfortunately, this is not the case. Also, NWUO_COPY has no significance and is never used in the code.

#define NWUO_LOCPORT_MASK 0x000CL
#define NWUO_LP_SEL 0x00000004L
#define NWUO_LP_SET 0x00000008L
#define NWUO_LP_ANY 0x0000000CL

One of the flag sets that cannot be disabled. There are three different choices:

NWUO_LP_SEL: The network service chooses the port. This port will be in the 49152-65535 range and will be unique. Note that this is inconsistent with the ip(4) documentation (which says that the port will be in the 32768-65535 range).

NWUO_LP_SET: The local port is specified in the nwuo_locport field of the nwio_udpopt_t struct (see below).

NWUO_LP_ANY: The file descriptor accepts packets destined for any port.


#define NWUO_LOCADDR_MASK 0x0010L
#define NWUO_EN_LOC 0x00000010L
#define NWUO_DI_LOC 0x00100000L

If enabled, accept packets destined for local address specified by the nwuo_locaddr field of the nwio_udpopt_t struct (see below).

#define NWUO_BROAD_MASK 0x0020L
#define NWUO_EN_BROAD 0x00000020L
#define NWUO_DI_BROAD 0x00200000L

If enabled, accept broadcast packets. If disabled, reject broadcast packets.


#define NWUO_REMPORT_MASK 0x0100L
#define NWUO_RP_SET 0x00000100L
#define NWUO_RP_ANY 0x01000000L
#define NWUO_REMADDR_MASK 0x0200L
#define NWUO_RA_SET 0x00000200L
#define NWUO_RA_ANY 0x02000000L

A udp file descriptor can be configured to only send packets to a specific udp port and ip address. If NWUO_RP_SET and NWUO_RA_SET are enabled, a remote port (nwuo_remport) and a remote address (nwuo_locaddr) must be specified. If NWUO_RP_ANY and/or NWUO_RA_ANY are/is set, the destination may be any udp port and/or any ip address. See below.

#define NWUO_RW_MASK 0x1000L
#define NWUO_RWDATONLY 0x00001000L
#define NWUO_RWDATALL 0x10000000L

If NWUO_RWDATONLY is set, only the data is sent to the ip layer. If NWUO_RWDATALL is set, the source and destination ip addresses, the source and destination udp ports, and other information (e.g., ip options) are sent (in addition to the data) to the ip layer.


#define NWUO_IPOPT_MASK 0x2000L
#define NWUO_EN_IPOPT 0x00002000L
#define NWUO_DI_IPOPT 0x20000000L

If NWUO_EN_IPOPT (ENable IP OPTions) is set, ip options are sent to the ip layer and received from the ip layer. If NWUO_DI_IPOPT (DIsable IP OPTions) is set, ip options are not sent to the ip layer and stripped from the packets received from the ip layer.



If there are any illegal combinations of flags (e.g., the NWUO_RWDATONLY and an inappropriate ..._ANY flag is set), the network service sends the user process an EBADMODE message.

EBADMODE is #define'd in /include/errno.h:

#define EBADMODE (_SIGN 53) /* badmode in ioctl */


nwuo_locport, nwuo_locaddr: The local udp port and address of the udp file descriptor.

nwuo_remport, nwuo_remaddr: (optional) The remote udp port and address of the remote system. If only a single destination is desired, these two fields are set.

bf_memreq()

After the buffers have been initialized, accessors[] looks like the following:



bf_memreq() allocates accessors to the caller. For example, if 1514 bytes of buffer space are requested immediately after the network process starts and each buffer is 512 bytes (the default), then accessors[] will look like the following:



Note that three elements of accessors[] have been removed from buf512_freelist and that the head of the chain of the 3 accessors is returned by bf_memreq(). Also note that the acc_linkC and buf_linkC fields have been set to one and acc_length and acc_offset have been set to their appropriate values.

So what happens if there are not enough buffers on the buf512_freelist to satisfy a request? On lines 2280-2290 of buf.c, functions that free buffers for the specific clients (e.g., eth_buffree()) are called until there are enough buffers on buf512_freelist.

For a complete description of the network service's buffer management, click here.

ptr2acc_data()

The macro ptr2acc_data is #define'd in inet/generic/buf.h as:

#define ptr2acc_data(/* acc_t * */ a) (bf_temporary_acc=(a), \
(&bf_temporary_acc->acc_buffer->buf_data_p[bf_temporary_acc-> \
acc_offset]))

ptr2acc_data() simply returns a pointer to the actual data within an accessor.

ptr2acc_data() is usually called so that the fields of a header (e.g., ip header) can be analyzed.

The uf_get_userdata and uf_put_userdata fields are set to pointers to sr_get_userdata() and sr_put_userdata(), respectively. These values were passed in as arguments in sr_add_minor().

Recall that each udp file descriptor has a corresponding sr file descriptor. The uf_srfd field of the udp file descriptor contains this sr file descriptor.

reply_thr_get() / reply_thr_put() / udp

reply_thr_get() calls (indirectly) sr_get_userdata(), which reports to the file system (FS) whether a previous operation requested by a process was successful. reply, reply_thr_get()'s second parameter, indicates whether the previous operation was successful.

After sending the message to the FS, sr_get_userdata() processes the messages in the write or ioctl queue.

reply_thr_put() does nearly the same thing as reply_thr_get(). However, instead of reporting whether write and ioctl operations were successful, reply_thr_put() reports on read and ioctl operations.

Only NWIOSUDPOPT and NWIOGUDPOPT requests are valid requests. All other requests are rejected.

reply_thr_get() / reply_thr_put() / udp

reply_thr_get() calls (indirectly) sr_get_userdata(), which reports to the file system (FS) whether a previous operation requested by a process was successful. reply, reply_thr_get()'s second parameter, indicates whether the previous operation was successful.

After sending the message to the FS, sr_get_userdata() processes the messages in the write or ioctl queue.

reply_thr_put() does nearly the same thing as reply_thr_get(). However, instead of reporting whether write and ioctl operations were successful, reply_thr_put() reports on read and ioctl operations.

If the operation wasn't suspended, clear the UFF_IOCTL_IP flag. In other words, the ioctl request has been handled.

udp_setopt()

udp_setopt() is called by only a single function, udp_ioctl().

Before a udp file descriptor can be used, the file descriptor must be configured by udp_setopt(). udp_setopt() gets the configuration data from the process that opened the file descriptor, verifies that the configuration data is valid, sets the uf_udpopt field of the udp file descriptor to reflect the new configuration, and then marks the file descriptor as configured (i.e., sets the UFF_OPTSET flag in uf_flags).

Get the configuration data from the process that opened the udp file descriptor. uf_get_userdata was set to sr_get_userdata() on line 61257.


sr_get_userdata()

sr_get_userdata() is the counterpart to sr_put_userdata() and does one of two things:

1) Copies data from a user process to a buffer (to be more specific, a chain of accessors) within the network service (this process). This can be either ioctl data (in which case, for_ioctl is TRUE) or data. For example, udp_setopt() (indirectly) calls sr_get_userdata() to get configuration data. Also, restart_write_fd() (indirectly) calls sr_get_userdata() before passing data onto the ip code.

2) Sends a REVIVE message to the file system (FS). For example, if an illegal option is selected while configuring a udp file descriptor, reply_thr_get() is called, which then (indirectly) calls sr_get_userdata(), passing in EBADMODE for the parameter count. restart_write_fd() also (indirectly) calls sr_get_userdata() to send a REVIVE message back to the FS indicating the number of bytes read after copying the data from the user process.

sr_get_userdata() is often called twice in close succession. The first time to attempt to copy the data from the user process and then the second time to send a message to the FS indicating whether the copy operation was successful and, if it was successful, the number of bytes copied.

In my opinion, like sr_put_userdata(), this function should have been made into two functions. As it is, it is too confusing.


nwio_udpopt_t

struct nwio_udpopt_t contains configuration information for a udp file descriptor. The uf_udpopt field of a udp file descriptor has type nwio_udpopt_t.

typedef struct nwio_udpopt 

{ 

     unsigned long nwuo_flags; 

     udpport_t nwuo_locport; 

     udpport_t nwuo_remport; 

     ipaddr_t nwuo_locaddr; 

     ipaddr_t nwuo_remaddr; 

} nwio_udpopt_t;

nwuo_flags:

#define NWUO_NOFLAGS 0x0000L
#define NWUO_ACC_MASK 0x0003L
#define NWUO_EXCL 0x00000001L
#define NWUO_SHARED 0x00000002L
#define NWUO_COPY 0x00000003L

File descriptors that share the same port must have the same access permissions (i.e., their NWUO_EXCL, NWUO_SHARED, and NWUO_COPY flags are the same).

There does appear to be an error in the code, however. If the NWUO_EXCL (exclusive access) flag is set, only one udp file descriptor should have access to the common udp port (0-65535). Unfortunately, this is not the case. Also, NWUO_COPY has no significance and is never used in the code.

#define NWUO_LOCPORT_MASK 0x000CL
#define NWUO_LP_SEL 0x00000004L
#define NWUO_LP_SET 0x00000008L
#define NWUO_LP_ANY 0x0000000CL

One of the flag sets that cannot be disabled. There are three different choices:

NWUO_LP_SEL: The network service chooses the port. This port will be in the 49152-65535 range and will be unique. Note that this is inconsistent with the ip(4) documentation (which says that the port will be in the 32768-65535 range).

NWUO_LP_SET: The local port is specified in the nwuo_locport field of the nwio_udpopt_t struct (see below).

NWUO_LP_ANY: The file descriptor accepts packets destined for any port.


#define NWUO_LOCADDR_MASK 0x0010L
#define NWUO_EN_LOC 0x00000010L
#define NWUO_DI_LOC 0x00100000L

If enabled, accept packets destined for local address specified by the nwuo_locaddr field of the nwio_udpopt_t struct (see below).

#define NWUO_BROAD_MASK 0x0020L
#define NWUO_EN_BROAD 0x00000020L
#define NWUO_DI_BROAD 0x00200000L

If enabled, accept broadcast packets. If disabled, reject broadcast packets.


#define NWUO_REMPORT_MASK 0x0100L
#define NWUO_RP_SET 0x00000100L
#define NWUO_RP_ANY 0x01000000L
#define NWUO_REMADDR_MASK 0x0200L
#define NWUO_RA_SET 0x00000200L
#define NWUO_RA_ANY 0x02000000L

A udp file descriptor can be configured to only send packets to a specific udp port and ip address. If NWUO_RP_SET and NWUO_RA_SET are enabled, a remote port (nwuo_remport) and a remote address (nwuo_locaddr) must be specified. If NWUO_RP_ANY and/or NWUO_RA_ANY are/is set, the destination may be any udp port and/or any ip address. See below.

#define NWUO_RW_MASK 0x1000L
#define NWUO_RWDATONLY 0x00001000L
#define NWUO_RWDATALL 0x10000000L

If NWUO_RWDATONLY is set, only the data is sent to the ip layer. If NWUO_RWDATALL is set, the source and destination ip addresses, the source and destination udp ports, and other information (e.g., ip options) are sent (in addition to the data) to the ip layer.


#define NWUO_IPOPT_MASK 0x2000L
#define NWUO_EN_IPOPT 0x00002000L
#define NWUO_DI_IPOPT 0x20000000L

If NWUO_EN_IPOPT (ENable IP OPTions) is set, ip options are sent to the ip layer and received from the ip layer. If NWUO_DI_IPOPT (DIsable IP OPTions) is set, ip options are not sent to the ip layer and stripped from the packets received from the ip layer.



If there are any illegal combinations of flags (e.g., the NWUO_RWDATONLY and an inappropriate ..._ANY flag is set), the network service sends the user process an EBADMODE message.

EBADMODE is #define'd in /include/errno.h:

#define EBADMODE (_SIGN 53) /* badmode in ioctl */


nwuo_locport, nwuo_locaddr: The local udp port and address of the udp file descriptor.

nwuo_remport, nwuo_remaddr: (optional) The remote udp port and address of the remote system. If only a single destination is desired, these two fields are set.

Below is an example of a mask (NWUO_LOCADDR_MASK) and the associated enable flag (NWUO_EN_LOC) and the associated disable flag (NWUO_DI_LOC).



Get the requested (new) enable and disable flags and the old enable and disable flags. The flags for the udp file descriptor will be a product of the requested flags and the old flags.

It is not allowed to both enable and disable a flag within the NWUO_ACC_MASK set of flags.

If the new access enable flags are not set, use the old flags.

If a new port is not specified for the udp file descriptor, use the old one.

This block checks for inconsistent udp options.

If only the data is to be sent to the ip layer, the ip address and udp port need to be known (in other words, there cannot be ..._ANY flags set). In addition, if only the data is to be sent to the ip layer, no ip options may be passed back and forth.

Go through all of the udp file desciptors and compare each with the file descriptor currently being configured (i.e., udp_fd). If any of the file descriptors share the same port but do not have the same access permissions (i.e., their NWUO_EXCL, NWUO_SHARED, and NWUO_COPY flags are not the same), send the user process that is configuring the udp file descriptors a message indicating an error.

There does appear to be an error in the code, however. If the NWUO_EXCL (exclusive access) flag is set, only one udp file descriptor should have access to the port. Unfortunately, this is not reflected in the code.

This is the udp file descriptor that is currently being compared. Skip over it.

hash_fd() / unhash_fd() / udp

Hash tables enable quick lookups. The hash table used by the udp code enables a udp file descriptor to be found quickly using its common udp port number (0-65535).

hash_fd(udp_fd) either places the udp file descriptor udp_fd, hash_fd()'s only parameter, at the head of the up_port_any linked list of the file descriptor's udp port (if the file descriptor is not associated with a specific udp port) or the function calculates the hash of the udp file descriptor based on its udp port number and places it at the head of the linked list for that hash value (e.g., up_port_hash[10)).

unhash_fd(udp_fd) removes the udp file descriptor udp_fd, unhash_fd()'s only parameter, from the linked list where hash_fd() inserted it.

Note that the port used for the hash is not the physical udp port.

This is the last check before declaring a udp file descriptor's options as valid (i.e., before setting the UFF_OPTSET flag in the uf_flags field of the udp file descriptor).

Previously (on line 61505), new_en_flags (enable flags) and new_di_flags (disable flags) were checked to verify that a process was not attempting to both enable and disable a any one flag. Here, the code verifies that at least one flag within each set (i.e., within each "mask") is enabled.

As soon as the UFF_OPSET flag is set, the udp file descriptor may be used (i.e., read from/written to).

The options are acceptable. Set the UFF_OPTSET flag.

The options are not acceptable. Turn off the UFF_OPTSET flag.

hash_fd() / unhash_fd() / udp

Hash tables enable quick lookups. The hash table used by the udp code enables a udp file descriptor to be found quickly using its common udp port number (0-65535).

hash_fd(udp_fd) either places the udp file descriptor udp_fd, hash_fd()'s only parameter, at the head of the up_port_any linked list of the file descriptor's udp port (if the file descriptor is not associated with a specific udp port) or the function calculates the hash of the udp file descriptor based on its udp port number and places it at the head of the linked list for that hash value (e.g., up_port_hash[10)).

unhash_fd(udp_fd) removes the udp file descriptor udp_fd, unhash_fd()'s only parameter, from the linked list where hash_fd() inserted it.

Note that the port used for the hash is not the physical udp port.

Inform the file system that the operation was successful. Note, however, that this doesn't necessarily mean that the UFF_OPTSET flag was set and that the udp file descriptor is usable (see line 61663).


reply_thr_get() / reply_thr_put() / udp

reply_thr_get() calls (indirectly) sr_get_userdata(), which reports to the file system (FS) whether a previous operation requested by a process was successful. reply, reply_thr_get()'s second parameter, indicates whether the previous operation was successful.

After sending the message to the FS, sr_get_userdata() processes the messages in the write or ioctl queue.

reply_thr_put() does nearly the same thing as reply_thr_get(). However, instead of reporting whether write and ioctl operations were successful, reply_thr_put() reports on read and ioctl operations.

find_unused_port()

find_unused_port() attempts to claim an unused port number. The first port number that is requested is equal to the index number of the udp file descriptor plus 0xC000 (49152). If this port is not available, the port number is incremented until an unclaimed port number is found. So for the sixth udp file descriptor (i.e., udp_fd_table[5]), find_unused_port() first tries port 49157 (49152 + 5), then tries 49158, and so on until an available port if found.

find_unused_port() is called only a single time: while setting a udp file descriptor's options with udp_setopt() (more specifically, if a user process attempts to set the NWUO_LP_SEL (Local Port SELect) flag).

htons() / ntohs() / htonl() / ntohl()

From htons(3):

"htons() converts a 16-bit quantity from host byte order to network byte order."

Different CPU architectures group multiple bytes differently. For example, on a "little-endian" machine (an example of which is the Intel CPU), the value 0x1234 is stored in memory as 0x3412. However, on a "big-endian" machine, the value 0x1234 is stored in memory as 0x1234.

It is important that values in a header are sent across a network in a consistent manner independent of the architecture of the sending or receiving system. For this reason, a standard was chosen. The standard chosen was big-endian although it could have just as well been little-endian.

htons() is defined in /include/net/hton.h, as:
#define htons(x) (_tmp=(x), ((_tmp>>8) & 0xff) | ((_tmp<<8) & 0xff00))

ntohs() converts a 16-bit quantity from network byte order to host byte order, the reverse of htons().

htonl() and ntohl() are identical to htons() and ntohs() except that they convert 32-bit quantities instead of 16-bit quantities.

Processes generally supply header information when sending packets. The data in these fields is converted to the network format (i.e., big-endian) by the process before the process copies the data to the network service.

is_unused_port()

is_unused_port() searches through all of the udp file descriptors (i.e., searches through udp_fd_table[]) for a given common udp port (0-65535). If the port is not found, is_unused_port() returns TRUE.

htons() / ntohs() / htonl() / ntohl()

From htons(3):

"htons() converts a 16-bit quantity from host byte order to network byte order."

Different CPU architectures group multiple bytes differently. For example, on a "little-endian" machine (an example of which is the Intel CPU), the value 0x1234 is stored in memory as 0x3412. However, on a "big-endian" machine, the value 0x1234 is stored in memory as 0x1234.

It is important that values in a header are sent across a network in a consistent manner independent of the architecture of the sending or receiving system. For this reason, a standard was chosen. The standard chosen was big-endian although it could have just as well been little-endian.

htons() is defined in /include/net/hton.h, as:
#define htons(x) (_tmp=(x), ((_tmp>>8) & 0xff) | ((_tmp<<8) & 0xff00))

ntohs() converts a 16-bit quantity from network byte order to host byte order, the reverse of htons().

htonl() and ntohl() are identical to htons() and ntohs() except that they convert 32-bit quantities instead of 16-bit quantities.

Processes generally supply header information when sending packets. The data in these fields is converted to the network format (i.e., big-endian) by the process before the process copies the data to the network service.

is_unused_port()

is_unused_port() searches through all of the udp file descriptors (i.e., searches through udp_fd_table[]) for a given common udp port (0-65535). If the port is not found, is_unused_port() returns TRUE.

reply_thr_get() / reply_thr_put() / udp

reply_thr_get() calls (indirectly) sr_get_userdata(), which reports to the file system (FS) whether a previous operation requested by a process was successful. reply, reply_thr_get()'s second parameter, indicates whether the previous operation was successful.

After sending the message to the FS, sr_get_userdata() processes the messages in the write or ioctl queue.

reply_thr_put() does nearly the same thing as reply_thr_get(). However, instead of reporting whether write and ioctl operations were successful, reply_thr_put() reports on read and ioctl operations.

The uf_get_userdata field of the udp file descriptor was set by udp_open() (see line 61258).

reply_thr_get() / reply_thr_put() / udp

reply_thr_get() calls (indirectly) sr_get_userdata(), which reports to the file system (FS) whether a previous operation requested by a process was successful. reply, reply_thr_get()'s second parameter, indicates whether the previous operation was successful.

After sending the message to the FS, sr_get_userdata() processes the messages in the write or ioctl queue.

reply_thr_put() does nearly the same thing as reply_thr_get(). However, instead of reporting whether write and ioctl operations were successful, reply_thr_put() reports on read and ioctl operations.

The uf_get_userdata field of the udp file descriptor was set by udp_open() (see line 61257).

is_unused_port()

is_unused_port() searches through all of the udp file descriptors (i.e., searches through udp_fd_table[]) for a given common udp port (0-65535). If the port is not found, is_unused_port() returns TRUE.

If the udp file descriptor is not in use (i.e., UFF_OPTSET is not set), its port number is not important. If the udp file descriptor is used again, it will need to acquire a new port number.

read_ip_packets() / udp

read_ip_packets() is called only a single time, during the initialization of the udp code.

read_ip_packets() reads all packets (by repeatedly calling ip_read()) in the udp port's associated ip file descriptor's read queue until all of the packets have either been delivered to the processes that issued the read requests (provided that the packets have not expired) or placed in the udp file descriptor's read queue.

read_ip_packets() is also called by udp_get_data(). However, this line of code is never executed (see comment for line 61391).

The UPF_READ_IP flag is meaningless and is essentially always set. At the end of this do...while() block, this flag is cleared. However, the while conditional will always be true (see comment for line 61758) and so the code will always loop back to this line where the flag is set again. The UPF_READ_IP flag is also cleared in udp_put_data(). However, this code will never be executed (see the comment for line 61391).

UDP_MAX_DATAGRAM is the maximum size for a udp datagram and is #define'd in inet/generic/udp.h:

#define UDP_MAX_DATAGRAM 40000 /* 8192 */


ip_read()

If there are unexpired packets in the ip file descriptor fd's read queue, ip_read(fd, count) passes count (ip_read()'s second parameter) bytes off to the next-higher layer by calling packet2user(). If the packets in the file descriptor's read queue have expired, ip_read() discards the packets.

ip_read() is (indirectly) called by sr_rwio() when a process reads an ip device file (e.g., /dev/ip).

In the udp code, ip_read() is called by read_ip_packets() during the initialization of the udp code. Normally, ip_read() is not called by the udp code after the initialization.

This conditional (!(udp_port->up_flags & UPF_READ_IP)) is never false. It is a little unclear why this was done rather than simply using "while (1)". One possible explanation is that this was done to give more time to the network replies.

udp_read()

If there is a packet in the udp file descriptor's read queue and the packet has not expired, udp_read() sends the packet to the process that requested the read. If the packet cannot be delivered (either because the packet has expired or it hasn't arrived yet), udp_read() suspends the read operation (i.e., returns NW_SUSPEND to sr_rwio() and sets the UFF_READ_IP flag). If the packet has expired, all packets in the read queue of the udp file descriptor are discarded.

Find the udp file descriptor that has an index of fd (udp_read()'s first parameter) within udp_fd_table[]. Also, verify that the file descriptor has been configured by udp_ioctl() (line 61425). Note that after udp_ioctl() configures the udp file descriptor, it marks the file descriptor as configured (i.e., it sets the UFF_OPTSET flag).

count, udp_read()'s second parameter, is the number of bytes requested to be read.

uf_rdbuf_head is the queue of packets received by the a href="general-comment-display.php?commentid=35" target=new>udp file descriptor.

When the read queue of a udp file descriptor is empty and a packet is placed in the queue, the timer (uf_exp_tim) is set. If this timer expires before the packet is read, this packet and all packets that have been subsequently placed in the queue are discarded.

If the packet has not expired (the normal case), udp_packet2user() is called.


get_time()

get_time() returns the number of clock ticks since reboot.

Several of the clients (eth, arp, ip, tcp, and udp) use get_time() to determine an appropriate timeout value for a given operation. For example, the arp code calls get_time() to determine an appropriate amount of time to wait for a response from an arp request before giving up.

udp_packet2user()

udp_packet2user(udp_fd) delivers the first packet in the read queue (if it has not expired) of the udp file descriptor udp_fd, udp_packet2user's only parameter, to the process that opened the file descriptor and then sends a message to the file system specifying whether the operation was successful.

If the NWUO_RWDATONLY flag of the file descriptor is set, the packet is delivered without the pseudo udp header.

If this point in the code has been reached, the packet has expired. Remove all the packets in the read queue.

The acc_ext_link field of an accessor links multiple packets in a queue (in this case, the read queue).

For a full description of the network service's buffer management, click here.

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

By setting the UFF_READ_IP flag in uf_flags and returning NW_SUSPEND, udp_read() indicates that the udp file descriptor is waiting for a packet from the lower layers (i.e., the ip code).

The UFF_READ_IP flag (unlike the UPF_READ_IP flag) is a very important flag. If the UFF_READ_IP flag is set, a read request was received for the udp file descriptor but the request could not be satisifed. Eventually, when a packet for the udp file descriptor arrives (and udp_ip_arrived() is called), the UFF_READ_IP flag will indicate that the process that opened the file descriptor wants to read this packet.

udp_packet2user() clears the UFF_READ_IP flag after copying the packet to the process that requested the read.

udp_packet2user()

udp_packet2user(udp_fd) delivers the first packet in the read queue (if it has not expired) of the udp file descriptor udp_fd, udp_packet2user's only parameter, to the process that opened the file descriptor and then sends a message to the file system specifying whether the operation was successful.

If the NWUO_RWDATONLY flag of the file descriptor is set, the packet is delivered without the pseudo udp header.

The read queue of the udp file descriptor is as follows:



Each rectangle in the figure is an accessor with an associated buffer. The accessors within a packet are linked by the acc_next field (red lines) and the packets are linked by the acc_ext_link field (green lines). This figure shows three packets linked together.

The first packet in the queue (the packet that will soon be delivered to the process that requested the read) is removed from the queue.

bf_bufsize()

bf_bufsize() returns the total buffer size of a linked list of accessors (i.e., the sum of acc_length for the accessors in a linked list).

For a detailed description of the network service's buffer management, click here.

Strip the pseudo udp header, including ip options (if they exist), from the packet if the NWUO_RWDATONLY flag is set.

From ip(4):

"With NWUO_RWDATONLY only the data part of a UDP packet is sent to the server and only the data part is received from the server".

UDP_IO_HDR_SIZE is the size of the pseudo udp header and is #define'd in /include/net/gen/udp.h:

#define UDP_IO_HDR_SIZE 16


bf_packIffLess()

If the data in a linked list of accessors is less than min_len (the second parameter), bf_packIffLess(pack, min_len) packs the data by calling bf_pack().

bf_packIffLess() is often called to ensure that a packet's header is in a single contiguous buffer so that the individual fields of the header can be easily accessed.

For a detailed description of the network service's buffer management, click here.

ptr2acc_data()

The macro ptr2acc_data is #define'd in inet/generic/buf.h as:

#define ptr2acc_data(/* acc_t * */ a) (bf_temporary_acc=(a), \
(&bf_temporary_acc->acc_buffer->buf_data_p[bf_temporary_acc-> \
acc_offset]))

ptr2acc_data() simply returns a pointer to the actual data within an accessor.

ptr2acc_data() is usually called so that the fields of a header (e.g., ip header) can be analyzed.udp_io_hdr

The "pseudo" udp header (not the standard udp header) is of type uih_io_hdr_t. uih_io_hdr_t is declared in include/net/gen/udp_hdr.h:

typedef struct udp_io_hdr

{

	ipaddr_t uih_src_addr;

	ipaddr_t uih_dst_addr;

	udpport_t uih_src_port;

	udpport_t uih_dst_port;

	u16_t uih_ip_opt_len;

	u16_t uih_data_len;

} udp_io_hdr_t;

uih_src_addr, uih_dst_addr, uih_src_port, uih_dst_port: Source and destination ip addresses and ports

uih_ip_opt_len: length of the ip options (zero if none exist)

uih_data_len: length of the data

If a udp file descriptor is configured appropriately, a process writing data to the udp file descriptor must prepend a pseudo udp header to the data, thereby specifying the values (given above) in the outgoing udp and ip headers. A udp pseudo header is also prepended to an otherwise header-less packet being copied to the process that requested a read.

Remove the pseudo udp header from the packet.

bf_cut()

If a section of a linked list needs to be duplicated, bf_cut(data, offset, length) is called. For example, if a section of length 50 starting at an offset of 75 of the linked list below needs to be duplicated, bf_cut(data, 75, 50) is called:



Note that the original linked list remains unchanged and that acc_linkC for all the accessors in the new linked list is one.

If length (the second parameter) is zero, simply duplicate the first accessor in the linked list but set acc_length=0 and acc_next=null. In other words, create a linked list of length one accessor whose acc_length is 0.

bf_cut() is used in a number of scenarios, including cutting a received ethernet packet to size.

For a full description of the network service's buffer management, click here.

The pseudo udp header is no longer needed.


bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

If this conditional is true, the process that requested the read did not request the entire packet. Give the process what it requested but report an error to the file system (see line 61843).

bf_cut()

If a section of a linked list needs to be duplicated, bf_cut(data, offset, length) is called. For example, if a section of length 50 starting at an offset of 75 of the linked list below needs to be duplicated, bf_cut(data, 75, 50) is called:



Note that the original linked list remains unchanged and that acc_linkC for all the accessors in the new linked list is one.

If length (the second parameter) is zero, simply duplicate the first accessor in the linked list but set acc_length=0 and acc_next=null. In other words, create a linked list of length one accessor whose acc_length is 0.

bf_cut() is used in a number of scenarios, including cutting a received ethernet packet to size.

For a full description of the network service's buffer management, click here.

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

The uf_put_userdata field is set to sr_put_userdata() by sr_add_minor(). This call to sr_put_userdata() copies the packet to the process that requested the read.


sr_put_userdata()

sr_put_userdata(fd, offset, data, for_ioctl) is the counterpart to sr_get_userdata() and (like sr_get_userdata()) does one of two things:

1) Copies data from a buffer (to be more specific, a chain of accessors) within the network service (this process) to a buffer within the user process. This can be either ioctl data (in which case, for_ioctl is TRUE) or read/write data (for_ioctl is FALSE). For example, udp_ioctl() (indirectly) calls sr_put_userdata() to give configuration data to a user process. Also, udp_packet2user() (indirectly) calls sr_get_userdata() to pass data to the user process.

2) Sends a message to the FS. For example, if a read is attempted on a udp file descriptor before the file descriptor is configured, reply_thr_put() is called, which then (indirectly) calls sr_put_userdata(), passing in EBADMODE for the parameter count.

In my opinion, like sr_get_userdata(), this should have been made into two functions. As it is, it is too confusing.

The process did not request the entire packet. Report it to the file system.

EPACKSIZE is #define'd in /include/errno.h:

#define EPACKSIZE (_SIGN 50) /* invalid packet size for some protocol */

The read operation, whether successful or unsuccessful, is finished. Therefore, clear the udp file descriptor's read flag (UFF_READ_IP).

Again, the uf_put_userdata field was set to sr_put_userdata() by sr_add_minor(). This call to sr_put_userdata() sends a message to the file system, indicating whether the previous copy (see line 61839) was successful and, if it was successful, reports the number of bytes transferred.


sr_put_userdata()

sr_put_userdata(fd, offset, data, for_ioctl) is the counterpart to sr_get_userdata() and (like sr_get_userdata()) does one of two things:

1) Copies data from a buffer (to be more specific, a chain of accessors) within the network service (this process) to a buffer within the user process. This can be either ioctl data (in which case, for_ioctl is TRUE) or read/write data (for_ioctl is FALSE). For example, udp_ioctl() (indirectly) calls sr_put_userdata() to give configuration data to a user process. Also, udp_packet2user() (indirectly) calls sr_get_userdata() to pass data to the user process.

2) Sends a message to the FS. For example, if a read is attempted on a udp file descriptor before the file descriptor is configured, reply_thr_put() is called, which then (indirectly) calls sr_put_userdata(), passing in EBADMODE for the parameter count.

In my opinion, like sr_get_userdata(), this should have been made into two functions. As it is, it is too confusing.

udp_ip_arrived()

udp_ip_arrived() is called either (indirectly) from the ip code or from udp_put_data() and is one of the last functions called for a read request from a user process. udp_ip_arrived() does some checks (e.g., a checksum check) and figures out the destination udp file descriptor before calling udp_packet2user() to deliver the packet to the process that requested the read.

Find the relevant udp port in udp_port_table[].

The code lines below (lines 61877-61900) separate the ip header from rest of the packet.

ip_hdr_acc now points to a linked list of accessors that holds the ip header.

The minimum size of an ip packet is #define'd in /include/net/gen/in.h:

#define IP_MIN_HDR_SIZE 20



bf_cut()

If a section of a linked list needs to be duplicated, bf_cut(data, offset, length) is called. For example, if a section of length 50 starting at an offset of 75 of the linked list below needs to be duplicated, bf_cut(data, 75, 50) is called:



Note that the original linked list remains unchanged and that acc_linkC for all the accessors in the new linked list is one.

If length (the second parameter) is zero, simply duplicate the first accessor in the linked list but set acc_length=0 and acc_next=null. In other words, create a linked list of length one accessor whose acc_length is 0.

bf_cut() is used in a number of scenarios, including cutting a received ethernet packet to size.

For a full description of the network service's buffer management, click here.

bf_packIffLess()

If the data in a linked list of accessors is less than min_len (the second parameter), bf_packIffLess(pack, min_len) packs the data by calling bf_pack().

bf_packIffLess() is often called to ensure that a packet's header is in a single contiguous buffer so that the individual fields of the header can be easily accessed.

For a detailed description of the network service's buffer management, click here.

ptr2acc_data()

The macro ptr2acc_data is #define'd in inet/generic/buf.h as:

#define ptr2acc_data(/* acc_t * */ a) (bf_temporary_acc=(a), \
(&bf_temporary_acc->acc_buffer->buf_data_p[bf_temporary_acc-> \
acc_offset]))

ptr2acc_data() simply returns a pointer to the actual data within an accessor.

ptr2acc_data() is usually called so that the fields of a header (e.g., ip header) can be analyzed.

ih_vers_ihl is stored in a single byte of the ih_vers_ihl field. Therefore, it is necessary to mask out the unwanted bits.

IH_IHL_MASK is #define'd as:

#define IH_IHL_MASK 0xf

Since ih_vers_ihl is the header length (including the options) divided by 4, shifting left by 2 gives the actual length.


ip_hdr_t

struct ip_hdr_t is the structure of an ip header. "ih" (e.g., ih_src, ih_dst) stands for "Ip Header".

ip_hdr_t is declared in /include/net/gen/ip_hdr.h:

typedef struct ip_hdr

{

         u8_t ih_vers_ihl, ih_tos;

         u16_t ih_length, ih_id, ih_flags_fragoff;

         u8_t ih_ttl, ih_proto;

         u16_t ih_hdr_chk;

         ipaddr_t ih_src, ih_dst;

} ip_hdr_t;

ih_vers_ihl: The lower 4 bits is the length of the header plus options (if there are any) shifted by 2 bit positions (i.e., its actual length is 4 times as great as the value stored in ih_vers_ihl). An example of an option is a router list that a packet should follow to its destination.

The upper four bits is the version number (e.g., IPv4).


ih_tos: tos stands for "Type Of Service" and is the priority of the ip packet. A value of zero is the lowest priority. Both UDP and TCP have a default TOS of zero.

#define TCP_DEF_TOS 0
#define UDP_TOS 0


ih_length: The length of the entire ip packet, including the ip header.


ih_id: The value of ih_id for the first packet sent out is determined by ip_init() and is equal to the number of clock ticks since reboot (i.e., the value returned by get_time) and is incremented for each packet sent out. This value is used to combine fragments at the receiving end if fragmentation has occurred.


ih_flags_fragoff: ih_flags_fragoff is a combination of flags and a (possible) fragmentation offset ("fragoff").

If the packet should not be fragmented, ih_flags_fragoff is set to IH_DONT_FRAG. If there are additional fragments (e.g., the 3rd fragment of 4 fragments), ih_flags_fragoff is set to IH_MORE_FRAGS.

If the packet is indeed just a fragment of a packet, this value indicates the starting byte position (in 8 byte increments) of the original ip packet's data. So for example, if an ip packet of data size (not including the ip header) is broken up into two fragments of 1496 and 504 bytes each, the first fragment would have a fragmentation offset of 0 bytes and the second fragment would have a fragmentation offset of 1496 bytes and ih_flags_fragoff is therefore 187 (1496 / 8 = 187).


ih_ttl: "Time to live" for the packet. As a packet is routed to the destination, each router decrements the packet's ttl. When the ttl reaches 0, the router sends an "icmp unreachable" packet to the source. The ttl is designed to prevent packets that can't reach their destination from indefinitely bouncing around between routers. UDP's default TTL is 30:

#define UDP_TTL 30

Note that the Minix code also uses this value as a timeout value (in seconds). This code was written before the ttl field was redefined to be strictly a hope count. The original IP RFC defines the ttl field as the time to live in seconds.


ih_proto: The protocol of the ip packet. For example, if the packet is a udp packet, ih_proto will be 17. If the packet is a tcp packet, ih_proto will be 6.


ih_hdr_chk: Checksum for the header.


ih_src, ih_dst: Source and destination ip address of the ip packet.

             IP HEADER (as given by RFC 791)           

   



    0                   1                   2                   3   

    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   |Version|  IHL  |Type of Service|          Total Length         |

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   |         Identification        |Flags|      Fragment Offset    |

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   | Time to Live  |   Protocol    |   Header Checksum             |

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   |                       Source Address                          |

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   |                    Destination Address                        |

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   |                    Options                    |    Padding    |

   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Make sure that the ip header is in one contiguous buffer. This may not be the case if the ip header has options.

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

bf_cut()

If a section of a linked list needs to be duplicated, bf_cut(data, offset, length) is called. For example, if a section of length 50 starting at an offset of 75 of the linked list below needs to be duplicated, bf_cut(data, 75, 50) is called:



Note that the original linked list remains unchanged and that acc_linkC for all the accessors in the new linked list is one.

If length (the second parameter) is zero, simply duplicate the first accessor in the linked list but set acc_length=0 and acc_next=null. In other words, create a linked list of length one accessor whose acc_length is 0.

bf_cut() is used in a number of scenarios, including cutting a received ethernet packet to size.

For a full description of the network service's buffer management, click here.

bf_packIffLess()

If the data in a linked list of accessors is less than min_len (the second parameter), bf_packIffLess(pack, min_len) packs the data by calling bf_pack().

bf_packIffLess() is often called to ensure that a packet's header is in a single contiguous buffer so that the individual fields of the header can be easily accessed.

For a detailed description of the network service's buffer management, click here.

ptr2acc_data()

The macro ptr2acc_data is #define'd in inet/generic/buf.h as:

#define ptr2acc_data(/* acc_t * */ a) (bf_temporary_acc=(a), \
(&bf_temporary_acc->acc_buffer->buf_data_p[bf_temporary_acc-> \
acc_offset]))

ptr2acc_data() simply returns a pointer to the actual data within an accessor.

ptr2acc_data() is usually called so that the fields of a header (e.g., ip header) can be analyzed.

On line 61879 (or alternatively on line 61886), the data in the buffer that corresponded to the ip header was copied to the variable ip_hdr. Therefore, this part of the buffer can now be discarded.

bf_delhead()

If only the beginning of a linked list can be freed, bf_delhead() is called. If acc_linkC and buf_linkC are one for all of the relevant accessors and their associated buffers in the linked list, the operation is straight-forward:



bf_delhead() is often called to remove the header (e.g., ip header) from a packet.

For a detailed description of the network service's buffer management, click here.

There's something very wrong if the data remaining after the ip packet was stripped isn't even as large as a udp header.

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

bf_packIffLess()

If the data in a linked list of accessors is less than min_len (the second parameter), bf_packIffLess(pack, min_len) packs the data by calling bf_pack().

bf_packIffLess() is often called to ensure that a packet's header is in a single contiguous buffer so that the individual fields of the header can be easily accessed.

For a detailed description of the network service's buffer management, click here.

ptr2acc_data()

The macro ptr2acc_data is #define'd in inet/generic/buf.h as:

#define ptr2acc_data(/* acc_t * */ a) (bf_temporary_acc=(a), \
(&bf_temporary_acc->acc_buffer->buf_data_p[bf_temporary_acc-> \
acc_offset]))

ptr2acc_data() simply returns a pointer to the actual data within an accessor.

ptr2acc_data() is usually called so that the fields of a header (e.g., ip header) can be analyzed.

htons() / ntohs() / htonl() / ntohl()

From htons(3):

"htons() converts a 16-bit quantity from host byte order to network byte order."

Different CPU architectures group multiple bytes differently. For example, on a "little-endian" machine (an example of which is the Intel CPU), the value 0x1234 is stored in memory as 0x3412. However, on a "big-endian" machine, the value 0x1234 is stored in memory as 0x1234.

It is important that values in a header are sent across a network in a consistent manner independent of the architecture of the sending or receiving system. For this reason, a standard was chosen. The standard chosen was big-endian although it could have just as well been little-endian.

htons() is defined in /include/net/hton.h, as:
#define htons(x) (_tmp=(x), ((_tmp>>8) & 0xff) | ((_tmp<<8) & 0xff00))

ntohs() converts a 16-bit quantity from network byte order to host byte order, the reverse of htons().

htonl() and ntohl() are identical to htons() and ntohs() except that they convert 32-bit quantities instead of 16-bit quantities.

Processes generally supply header information when sending packets. The data in these fields is converted to the network format (i.e., big-endian) by the process before the process copies the data to the network service.

If the data in the buffers is not as large as the udp header claims (i.e., as large as the value in uh_length), there's a problem.

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

The ip header (obviously) contains the source and destination ip addresses.

The checksum for a udp packet is optional. If the checksum exists, compare the checksum field with the checksum calculated from the packet.

The checksum is calculated with the following data:

• the header and the data in the udp packet
  
• the source IP address
  
• the destination IP address
  
• the Protocol Identifier (17 for UDP)
  
• the size of the UDP message (including both data and header)
  

For a detailed description of the checksum algorithm, click here.

pack_oneCsum()

pack_oneCsum() computes the checksum of a udp packet. It accomplishes this by computing the checksum (by calling oneC_sum() of each of the packet's buffers).

Note that a checksum is used to determine if errors occurred during the transmission of data.

pack_oneCsum() is very similar to icmp_pack_oneCsum(). The two functions probably should have been consolidated into one.

oneC_sum()

A checksum is used to determine if errors occurred during the transmission of data. The checksum algorithm used by oneC_sum() (which is also the Internet standard) is described by RFC 1071.

Essentially, the algorithm goes through data and adds all the bytes together (using one's complement addition). The high 16 bits of the resulting 32 bit value is then added to the low 16 bits (again, using one's complement addition). The checksum field is then set to the one's complement of this 16 bit sum. (Recall that the one's complement of 0xF0F0 is 0x0F0F.) Since AND'ing any 16 bit number and its 16 bit one's complement will equal 0xFFFF, the checksum of the packet (without the checksum field) AND'ed with the checksum field will equal 0xFFFF (provided the packet was not corrupted after the checksum field was calculated). For example, the checksum of a udp header (including the checksum field) will equal 0xFFFF if the packet was not corrupted in delivery.


From RFC 1071:

In outline, the Internet checksum algorithm is fairly simple:

(1) Adjacent octets to be checksummed are paired to form 16-bit
integers, and the 1's complement sum of these 16-bit integers is
formed.

(2) To generate a checksum, the checksum field itself is cleared,
the 16-bit 1's complement sum is computed over the octets
concerned, and the 1's complement of this sum is placed in the
checksum field.

(3) To check a checksum, the 1's complement sum is computed over the
same set of octets, including the checksum field. If the result
is all 1 bits (-0 in 1's complement arithmetic), the check
succeeds.

Below is a "C" code algorithm that describes the process above. This algorithm is also from RFC 1071. Note that count is the running count of all the bytes in the data and checksum is the return value.

       {

           /* Compute Internet Checksum for "count" bytes

            *         beginning at location "addr".

            */

       register long sum = 0;



        while( count > 1 )  {

           /*  This is the inner loop */

               sum += * (unsigned short) addr++;

               count -= 2;

       }



           /*  Add left-over byte, if any */

       if( count > 0 )

               sum += * (unsigned char *) addr;



           /*  Fold 32-bit sum to 16 bits */

       while (sum>>16)

           sum = (sum & 0xffff) + (sum >> 16);



       checksum = ~sum;

   }

oneC_sum()

A checksum is used to determine if errors occurred during the transmission of data. The checksum algorithm used by oneC_sum() (which is also the Internet standard) is described by RFC 1071.

Essentially, the algorithm goes through data and adds all the bytes together (using one's complement addition). The high 16 bits of the resulting 32 bit value is then added to the low 16 bits (again, using one's complement addition). The checksum field is then set to the one's complement of this 16 bit sum. (Recall that the one's complement of 0xF0F0 is 0x0F0F.) Since AND'ing any 16 bit number and its 16 bit one's complement will equal 0xFFFF, the checksum of the packet (without the checksum field) AND'ed with the checksum field will equal 0xFFFF (provided the packet was not corrupted after the checksum field was calculated). For example, the checksum of a udp header (including the checksum field) will equal 0xFFFF if the packet was not corrupted in delivery.


From RFC 1071:

In outline, the Internet checksum algorithm is fairly simple:

(1) Adjacent octets to be checksummed are paired to form 16-bit
integers, and the 1's complement sum of these 16-bit integers is
formed.

(2) To generate a checksum, the checksum field itself is cleared,
the 16-bit 1's complement sum is computed over the octets
concerned, and the 1's complement of this sum is placed in the
checksum field.

(3) To check a checksum, the 1's complement sum is computed over the
same set of octets, including the checksum field. If the result
is all 1 bits (-0 in 1's complement arithmetic), the check
succeeds.

Below is a "C" code algorithm that describes the process above. This algorithm is also from RFC 1071. Note that count is the running count of all the bytes in the data and checksum is the return value.

       {

           /* Compute Internet Checksum for "count" bytes

            *         beginning at location "addr".

            */

       register long sum = 0;



        while( count > 1 )  {

           /*  This is the inner loop */

               sum += * (unsigned short) addr++;

               count -= 2;

       }



           /*  Add left-over byte, if any */

       if( count > 0 )

               sum += * (unsigned char *) addr;



           /*  Fold 32-bit sum to 16 bits */

       while (sum>>16)

           sum = (sum & 0xffff) + (sum >> 16);



       checksum = ~sum;

   }

oneC_sum()

A checksum is used to determine if errors occurred during the transmission of data. The checksum algorithm used by oneC_sum() (which is also the Internet standard) is described by RFC 1071.

Essentially, the algorithm goes through data and adds all the bytes together (using one's complement addition). The high 16 bits of the resulting 32 bit value is then added to the low 16 bits (again, using one's complement addition). The checksum field is then set to the one's complement of this 16 bit sum. (Recall that the one's complement of 0xF0F0 is 0x0F0F.) Since AND'ing any 16 bit number and its 16 bit one's complement will equal 0xFFFF, the checksum of the packet (without the checksum field) AND'ed with the checksum field will equal 0xFFFF (provided the packet was not corrupted after the checksum field was calculated). For example, the checksum of a udp header (including the checksum field) will equal 0xFFFF if the packet was not corrupted in delivery.


From RFC 1071:

In outline, the Internet checksum algorithm is fairly simple:

(1) Adjacent octets to be checksummed are paired to form 16-bit
integers, and the 1's complement sum of these 16-bit integers is
formed.

(2) To generate a checksum, the checksum field itself is cleared,
the 16-bit 1's complement sum is computed over the octets
concerned, and the 1's complement of this sum is placed in the
checksum field.

(3) To check a checksum, the 1's complement sum is computed over the
same set of octets, including the checksum field. If the result
is all 1 bits (-0 in 1's complement arithmetic), the check
succeeds.

Below is a "C" code algorithm that describes the process above. This algorithm is also from RFC 1071. Note that count is the running count of all the bytes in the data and checksum is the return value.

       {

           /* Compute Internet Checksum for "count" bytes

            *         beginning at location "addr".

            */

       register long sum = 0;



        while( count > 1 )  {

           /*  This is the inner loop */

               sum += * (unsigned short) addr++;

               count -= 2;

       }



           /*  Add left-over byte, if any */

       if( count > 0 )

               sum += * (unsigned char *) addr;



           /*  Fold 32-bit sum to 16 bits */

       while (sum>>16)

           sum = (sum & 0xffff) + (sum >> 16);



       checksum = ~sum;

   }

oneC_sum()

A checksum is used to determine if errors occurred during the transmission of data. The checksum algorithm used by oneC_sum() (which is also the Internet standard) is described by RFC 1071.

Essentially, the algorithm goes through data and adds all the bytes together (using one's complement addition). The high 16 bits of the resulting 32 bit value is then added to the low 16 bits (again, using one's complement addition). The checksum field is then set to the one's complement of this 16 bit sum. (Recall that the one's complement of 0xF0F0 is 0x0F0F.) Since AND'ing any 16 bit number and its 16 bit one's complement will equal 0xFFFF, the checksum of the packet (without the checksum field) AND'ed with the checksum field will equal 0xFFFF (provided the packet was not corrupted after the checksum field was calculated). For example, the checksum of a udp header (including the checksum field) will equal 0xFFFF if the packet was not corrupted in delivery.


From RFC 1071:

In outline, the Internet checksum algorithm is fairly simple:

(1) Adjacent octets to be checksummed are paired to form 16-bit
integers, and the 1's complement sum of these 16-bit integers is
formed.

(2) To generate a checksum, the checksum field itself is cleared,
the 16-bit 1's complement sum is computed over the octets
concerned, and the 1's complement of this sum is placed in the
checksum field.

(3) To check a checksum, the 1's complement sum is computed over the
same set of octets, including the checksum field. If the result
is all 1 bits (-0 in 1's complement arithmetic), the check
succeeds.

Below is a "C" code algorithm that describes the process above. This algorithm is also from RFC 1071. Note that count is the running count of all the bytes in the data and checksum is the return value.

       {

           /* Compute Internet Checksum for "count" bytes

            *         beginning at location "addr".

            */

       register long sum = 0;



        while( count > 1 )  {

           /*  This is the inner loop */

               sum += * (unsigned short) addr++;

               count -= 2;

       }



           /*  Add left-over byte, if any */

       if( count > 0 )

               sum += * (unsigned char *) addr;



           /*  Fold 32-bit sum to 16 bits */

       while (sum>>16)

           sum = (sum & 0xffff) + (sum >> 16);



       checksum = ~sum;

   }

The checksum should be 0xFFFF. Otherwise, there was a transmission error.

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

The expiration time is 10 seconds (= 600 clock "ticks"):

UDP_READ_EXP_TIME is #define'd in src/inet/generic/udp.h:

#define UDP_READ_EXP_TIME (10L * HZ)

HZ is #define'd in /include/minix/const.h:

#define HZ 60 /* clock freq (software settable on IBM-PC) */

Acquire the source and destination ports from the UDP header.

From ip(4):

"NWUO_EN_LOC enables the reception of packets with the local IP address as destination; NWUO_EN_BROAD enables the reception of broadcast packets."

The variable dst_type is used on line 62033.

The packet will be delivered to the process that requested the read with a udp "pseudo" header.


bf_memreq()

After the buffers have been initialized, accessors[] looks like the following:



bf_memreq() allocates accessors to the caller. For example, if 1514 bytes of buffer space are requested immediately after the network process starts and each buffer is 512 bytes (the default), then accessors[] will look like the following:



Note that three elements of accessors[] have been removed from buf512_freelist and that the head of the chain of the 3 accessors is returned by bf_memreq(). Also note that the acc_linkC and buf_linkC fields have been set to one and acc_length and acc_offset have been set to their appropriate values.

So what happens if there are not enough buffers on the buf512_freelist to satisfy a request? On lines 2280-2290 of buf.c, functions that free buffers for the specific clients (e.g., eth_buffree()) are called until there are enough buffers on buf512_freelist.

For a complete description of the network service's buffer management, click here.


udp_io_hdr

The "pseudo" udp header (not the standard udp header) is of type uih_io_hdr_t. uih_io_hdr_t is declared in include/net/gen/udp_hdr.h:

typedef struct udp_io_hdr

{

	ipaddr_t uih_src_addr;

	ipaddr_t uih_dst_addr;

	udpport_t uih_src_port;

	udpport_t uih_dst_port;

	u16_t uih_ip_opt_len;

	u16_t uih_data_len;

} udp_io_hdr_t;

uih_src_addr, uih_dst_addr, uih_src_port, uih_dst_port: Source and destination ip addresses and ports

uih_ip_opt_len: length of the ip options (zero if none exist)

uih_data_len: length of the data

If a udp file descriptor is configured appropriately, a process writing data to the udp file descriptor must prepend a pseudo udp header to the data, thereby specifying the values (given above) in the outgoing udp and ip headers. A udp pseudo header is also prepended to an otherwise header-less packet being copied to the process that requested a read.

ptr2acc_data()

The macro ptr2acc_data is #define'd in inet/generic/buf.h as:

#define ptr2acc_data(/* acc_t * */ a) (bf_temporary_acc=(a), \
(&bf_temporary_acc->acc_buffer->buf_data_p[bf_temporary_acc-> \
acc_offset]))

ptr2acc_data() simply returns a pointer to the actual data within an accessor.

ptr2acc_data() is usually called so that the fields of a header (e.g., ip header) can be analyzed.

htons() / ntohs() / htonl() / ntohl()

From htons(3):

"htons() converts a 16-bit quantity from host byte order to network byte order."

Different CPU architectures group multiple bytes differently. For example, on a "little-endian" machine (an example of which is the Intel CPU), the value 0x1234 is stored in memory as 0x3412. However, on a "big-endian" machine, the value 0x1234 is stored in memory as 0x1234.

It is important that values in a header are sent across a network in a consistent manner independent of the architecture of the sending or receiving system. For this reason, a standard was chosen. The standard chosen was big-endian although it could have just as well been little-endian.

htons() is defined in /include/net/hton.h, as:
#define htons(x) (_tmp=(x), ((_tmp>>8) & 0xff) | ((_tmp<<8) & 0xff00))

ntohs() converts a 16-bit quantity from network byte order to host byte order, the reverse of htons().

htonl() and ntohl() are identical to htons() and ntohs() except that they convert 32-bit quantities instead of 16-bit quantities.

Processes generally supply header information when sending packets. The data in these fields is converted to the network format (i.e., big-endian) by the process before the process copies the data to the network service.

Link the udp pseudo header with the udp packet (minus its udp header). In other words, link the udp pseudo header with the data.


bf_cut()

If a section of a linked list needs to be duplicated, bf_cut(data, offset, length) is called. For example, if a section of length 50 starting at an offset of 75 of the linked list below needs to be duplicated, bf_cut(data, 75, 50) is called:



Note that the original linked list remains unchanged and that acc_linkC for all the accessors in the new linked list is one.

If length (the second parameter) is zero, simply duplicate the first accessor in the linked list but set acc_length=0 and acc_next=null. In other words, create a linked list of length one accessor whose acc_length is 0.

bf_cut() is used in a number of scenarios, including cutting a received ethernet packet to size.

For a full description of the network service's buffer management, click here.

If there are ip options, no_ipopt_pack and ipopt_pack will be as follows:



If there are no ip options, ipopt_pack and no_ipopt_pack will be as follows:




If there are ip options, give them to the user if requested and don't give them to to the user if they are not requested (see lines 62061-62064 and 62075-62078).

If there were ip options included in the ip header:

1) copy the udp pseudo header to a new pseudo udp header (lines 61992-61994)
2) create a buffer with the ip options (lines 61995-62001)
3) link the udp pseudo header to the buffer with the options to the data, in that order (lines 62004-62008)

bf_memreq()

After the buffers have been initialized, accessors[] looks like the following:



bf_memreq() allocates accessors to the caller. For example, if 1514 bytes of buffer space are requested immediately after the network process starts and each buffer is 512 bytes (the default), then accessors[] will look like the following:



Note that three elements of accessors[] have been removed from buf512_freelist and that the head of the chain of the 3 accessors is returned by bf_memreq(). Also note that the acc_linkC and buf_linkC fields have been set to one and acc_length and acc_offset have been set to their appropriate values.

So what happens if there are not enough buffers on the buf512_freelist to satisfy a request? On lines 2280-2290 of buf.c, functions that free buffers for the specific clients (e.g., eth_buffree()) are called until there are enough buffers on buf512_freelist.

For a complete description of the network service's buffer management, click here.

opt_size is the size of the IP header options. ip_hdr_size was calculated on line 61880.

htons() / ntohs() / htonl() / ntohl()

From htons(3):

"htons() converts a 16-bit quantity from host byte order to network byte order."

Different CPU architectures group multiple bytes differently. For example, on a "little-endian" machine (an example of which is the Intel CPU), the value 0x1234 is stored in memory as 0x3412. However, on a "big-endian" machine, the value 0x1234 is stored in memory as 0x1234.

It is important that values in a header are sent across a network in a consistent manner independent of the architecture of the sending or receiving system. For this reason, a standard was chosen. The standard chosen was big-endian although it could have just as well been little-endian.

htons() is defined in /include/net/hton.h, as:
#define htons(x) (_tmp=(x), ((_tmp>>8) & 0xff) | ((_tmp<<8) & 0xff00))

ntohs() converts a 16-bit quantity from network byte order to host byte order, the reverse of htons().

htonl() and ntohl() are identical to htons() and ntohs() except that they convert 32-bit quantities instead of 16-bit quantities.

Processes generally supply header information when sending packets. The data in these fields is converted to the network format (i.e., big-endian) by the process before the process copies the data to the network service.

tmp_acc now holds the ip options.


bf_cut()

If a section of a linked list needs to be duplicated, bf_cut(data, offset, length) is called. For example, if a section of length 50 starting at an offset of 75 of the linked list below needs to be duplicated, bf_cut(data, 75, 50) is called:



Note that the original linked list remains unchanged and that acc_linkC for all the accessors in the new linked list is one.

If length (the second parameter) is zero, simply duplicate the first accessor in the linked list but set acc_length=0 and acc_next=null. In other words, create a linked list of length one accessor whose acc_length is 0.

bf_cut() is used in a number of scenarios, including cutting a received ethernet packet to size.

For a full description of the network service's buffer management, click here.

Link the udp pseudo header with the ip options.

no_ipopt_pack->acc_next is the data (see line 61983).

The acc_linkC field of a buffer is the count of the number of buffers that whose acc_next field references it. For example, if the acc_next field of two buffers point to a third buffer, acc_linkC for the third buffer will be 2.

For a detailed description of the network service's buffer management, click here.

In order to quickly find the udp file descriptor that corresponds to the destination common port number (0-65535), the udp code uses a hash. The goal of this hash is to associate a nearly equal number of open file descriptors with each element in udp_port->up_port_hash[] (see lin 62020).

From line 61021:

#define UDP_PORT_HASH_NR 16 /* Must be a power of 2 */

Search through the udp port's up_port_any linked list of udp file descriptors and the linked list of udp file descriptors for the appropriate element of up_port_hash[]. If various conditions hold for a given udp file descriptor (e.g., the destination port is correct), the packet is delivered.

The udp file descriptor's port number (e.g., port 49160) must match with the port number of the packet.

The udp file descriptor that matched above must be associated with the physical udp port (e.g., /dev/udp0) on which the packet arrived. A udp file descriptor may be associated with only a single physical udp port.

The nwuo_flags field of the udp file descriptor is used to determine if the udp file descriptor accepts the packet.

Verify that the udp file descriptor accepts the same types of packets (e.g., broadcast packets).

dst_type is NWUO_EN_LOC (if the physical udp port has an ip address) or NWUO_EN_BROAD (if the physical udp port does not have an ip address). See lines 61953-61957.

If the NWUO_RP_SET flag is set, verify that the udp file descriptor's remote udp port (nwuo_remport) field is the same as the packet's.

From ip(4):

"When NWUO_RP_SET is selected, the remote port is stored in nwuo_remport."

If the NWUO_RA_SET flag is set, verify that the udp file descriptor's remote ip address (nwuo_remaddr) field is the same as the packet's.

From ip(4):

"When NWUO_RA_SET is selected, the remote address is stored in nwuo_remaddr."

i will be 1 if the udp file descriptor is in the udp port's port-specific linked list (i.e., not in the up_port_any linked list).

From ip(4):

"NWUO_SHARED means shared access: only channels that specify shared access can use this port and all packets that are received are handed to at most one channel".

If the udp file descriptor accepts ip options, include the ip options. See the comment for line 61984.

From ip(4):

"When NWUO_EN_IPOPT is set IP, options will be delivered and sent."

Before a packet is placed in a udp file descriptor's read queue, the first accessor is copied and then the copy is placed in the queue. Incrementing acc_linkC forces udp_rd_enqueue() to create this copy of the accessor (see lines 62501-62506). By having a different first accessor for each udp file descriptor, the packets in the read queue of each of the different file descriptors can be linked to different packets if packets arrive before the packets are handed off to their respective processes.

udp_rd_enqueue()

udp_rd_enqueue(udp_fd, pack, exp_tim) places the packet pack, udp_rd_enqueue()'s second parameter, into the read queue of the udp file descriptor udp_fd, udp_rd_enqueue()'s first parameter. If the packet is the first in the queue, udp_rd_enqueue() sets the packet's expiration time to exp_tim, udp_rd_enqueu()'s third parameter.

udp_rd_enqueue() is called in two places by udp_ip_arrived() after a packet arrives. If a read request was made on a udp file descriptor to which the packet is destined, the packet is delivered immediately. If a read request was not made, the packet remains in the udp file descriptor's read queue until the udp file descriptor makes a read request.

If the udp file descriptor is being read (i.e., the UFF_READ_IP flag is set), deliver the packet to the user.


udp_packet2user()

udp_packet2user(udp_fd) delivers the first packet in the read queue (if it has not expired) of the udp file descriptor udp_fd, udp_packet2user's only parameter, to the process that opened the file descriptor and then sends a message to the file system specifying whether the operation was successful.

If the NWUO_RWDATONLY flag of the file descriptor is set, the packet is delivered without the pseudo udp header.

Code lines 62072-62084 mirror lines 62061-62070. The code lines below deliver the packet to the udp file descriptor that is configured to share the port.

If the udp file descriptor accepts ip options, include the ip options. See the comment for line 61984.

From ip(4):

"When NWUO_EN_IPOPT is set IP, options will be delivered and sent."

udp_rd_enqueue()

udp_rd_enqueue(udp_fd, pack, exp_tim) places the packet pack, udp_rd_enqueue()'s second parameter, into the read queue of the udp file descriptor udp_fd, udp_rd_enqueue()'s first parameter. If the packet is the first in the queue, udp_rd_enqueue() sets the packet's expiration time to exp_tim, udp_rd_enqueu()'s third parameter.

udp_rd_enqueue() is called in two places by udp_ip_arrived() after a packet arrives. If a read request was made on a udp file descriptor to which the packet is destined, the packet is delivered immediately. If a read request was not made, the packet remains in the udp file descriptor's read queue until the udp file descriptor makes a read request.

udp_packet2user()

udp_packet2user(udp_fd) delivers the first packet in the read queue (if it has not expired) of the udp file descriptor udp_fd, udp_packet2user's only parameter, to the process that opened the file descriptor and then sends a message to the file system specifying whether the operation was successful.

If the NWUO_RWDATONLY flag of the file descriptor is set, the packet is delivered without the pseudo udp header.

ipopt_pack and no_ipopt_pack are no longer needed so their corresponding accessors can be freed. ipopt_pack and no_ipopt_pack were described on line 61984.


bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

If the packet is successfully delivered to a udp file descriptor (lines 62048-62052) or the packet is a broadcast packet (lines 61953-61961), don't deliver an icmp unreachable packet. Otherwise, send an icmp unreachable packet back to the source.

bf_append()

bf_append() appends one accessor linked list to another accessor linked list. For example, if the payload of an ethernet packet (1500 bytes) is appended to an ethernet header (14 bytes):



the resulting linked list is as follows:

icmp_snd_unreachable()

icmp_snd_unreachable(port_nr, pack, code) builds an icmp unreachable packet (partially using the ip packet pack, icmp_snd_unreachable()'s second parameter) and then places the icmp unreachable packet in the outgoing queue. Icmp unreachable packets are sent if the network, host, or port number specified by the ip packet pack is unreachable.

The function first calls icmp_err_pack() to build a generic icmp packet, sets the ih_type field of the icmp header to ICMP_TYPE_DST_UNRCH and recalibrates the checksum (since the type and code fields of the icmp header have changed) of the icmp header before placing the packet in the icmp port's write queue.

Free up the other accessors. They are also no longer needed.

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

udp_close()

udp_close() closes a udp file descriptor in response to a DEV_CLOSE message received from the file system (FS). More specifically, udp_close() marks the udp file descriptor as available, removes the udp file descriptor from its udp file descriptor linked list within the udp port, and empties the read queue of the udp file descriptor.

Find the udp file descriptor with an index of fd (the first parameter of udp_ioctl()) within udp_fd_table[].

hash_fd() / unhash_fd() / udp

Hash tables enable quick lookups. The hash table used by the udp code enables a udp file descriptor to be found quickly using its common udp port number (0-65535).

hash_fd(udp_fd) either places the udp file descriptor udp_fd, hash_fd()'s only parameter, at the head of the up_port_any linked list of the file descriptor's udp port (if the file descriptor is not associated with a specific udp port) or the function calculates the hash of the udp file descriptor based on its udp port number and places it at the head of the linked list for that hash value (e.g., up_port_hash[10)).

unhash_fd(udp_fd) removes the udp file descriptor udp_fd, unhash_fd()'s only parameter, from the linked list where hash_fd() inserted it.

Note that the port used for the hash is not the physical udp port.

Mark the udp file descriptor as available.

Lines 62128 - 62135 empty out the udp file descriptor's read queue.

bf_afree()

After a chain of accessors is no longer needed, the chain (and not simply the single accessor passed as the parameter) can be freed by calling bf_free(). However, if either acc_linkC or buf_linkC of one of the accessors in the linked list is not equal to one (1), the entire chain will not be freed. For example, if buf_afree(acc1) is called for the following chain:



Then the resulting chain will be:



bf_afree() returns acc1 (accessors[63]) to acc_freelist (recall that acc_freelist is the linked list of acc_t's without an associated buffer). However, buffers512[127] cannot be freed because acc2 (accessors[64]) still references it.

bf_afree() is called after an accessor's associated data is no longer needed (for example, after a packet has been sent off by the ethernet driver).

Before studying udp_write() and restart_write_fd(), it is worthwhile to discuss ip_write(). ip_write() was rewritten and, as a result, no longer returns anything other than NW_OK. This significantly simplifies what udp_write() and restart_write_fd() do. However, neither udp_write() nor restart_write_fd() were rewritten to reflect the changes in ip_write(). There are several blocks of code that can be removed in both functions as well as in udp_get_data(). Our comments will indicate which blocks could have been removed.

It should also be noted that the UFF_WRITE_IP, UPF_WRITE_IP, UPF_MORE2WRITE, and UPF_WRITE_SP flags can be effectively ignored. If a process writes a packet to a udp file descriptor, the packet is either immediately handed off to the ip code or the packet is immediately dropped. In other words, by the time the next write to a udp file descriptor occurs, the udp code has forgotten about the previous write. Note that this does not mean that the packet can't be queued in the ethernet layer before being sent to the ethernet driver.


udp_write()

udp_write() gets a packet from a user process, adds a udp header and an ip header, and then passes the packet to the next lower layer (i.e., the ip code). udp_write() is called (indirectly) by sr_rwio(), which is called when the network service receives a write request from the file system (FS). Most of the work involved in moving the data from the udp layer to the ip layer is done by restart_write_fd().


udp write path

For a write to a udp device (e.g., /dev/udp), the code takes the following path:

sr_rwio()

  udp_write()

    restart_write_fd()

      ip_write()

        ip_send()

          if (packet is destined to a system on the local ethernet network) {

            ipeth_send()

              if (no previous packet being processed by ethernet task)

                eth_send()

                  if (eth_send() can't immediately send packet) 

                    eth_write()

          }

          else if (packet must be routed)

            oroute_frag()

          else if (packet ist destined for a local destination)

            ev_enqueue()

Find the udp file descriptor whose index within udp_fd_table[] is fd, the udp_write()'s first parameter. Also, find the corresponding udp port for the udp file descriptor.

A udp file descriptor must be configured before it can be read from or written to.

reply_thr_get() / reply_thr_put() / udp

reply_thr_get() calls (indirectly) sr_get_userdata(), which reports to the file system (FS) whether a previous operation requested by a process was successful. reply, reply_thr_get()'s second parameter, indicates whether the previous operation was successful.

After sending the message to the FS, sr_get_userdata() processes the messages in the write or ioctl queue.

reply_thr_put() does nearly the same thing as reply_thr_get(). However, instead of reporting whether write and ioctl operations were successful, reply_thr_put() reports on read and ioctl operations.

count, udp_write()'s second parameter, is the number of bytes requested in the write operation.

restart_write_fd() always clears the UFF_WRITE_IP flag and so this flag can be ignored. The UFF_WRITE_IP flag was probably meaningful before ip_write() was rewritten (see comment on line 62138).

restart_write_fd() / udp

restart_write_fd() gets data from the process that requested a write operation (by calling sr_get_userdata()) and then prepends an ip header and a udp header to the data before passing the packet on to the ip layer (by calling ip_write()).

Because the UPF_WRITE_IP flag is never set on line 62190 (see comment on the same line), the UFF_WRITE_IP flag will never be set at this point in the code and therefore ip_write() will always return NW_OK. restart_write_fd() always clears the UFF_WRITE_IP flag on line 62197.

restart_write_fd() / udp

restart_write_fd() gets data from the process that requested a write operation (by calling sr_get_userdata()) and then prepends an ip header and a udp header to the data before passing the packet on to the ip layer (by calling ip_write()).

The UPF_WRITE_IP flag will never be set at this point in the code. Here is the rationale behind this statement:

up_flags is initialized to UPF_EMPTY (i.e., UPF_WRITE_IP is not set) during the initialization of the udp port and therefore the UPF_WRITE_IP flag is not set the first time that this point in the code is reached. On line 62323, immediately before the call to ip_write(), the UPF_WRITE_IP flag is set. However, regardless whether ip_write() is able to satisfy the write request, ip_write() will always call error_reply(), which calls udp_get_data(). In this scenario, udp_get_data()will always clear the UPF_WRITE_IP flag since error_reply() calls udp_get_data() with its third argument equal to 0.

To better understand why the UPF_WRITE_IP flag is never set, it is helpful to study ip_write().

For the reason given above, UPF_MORE2WRITE will never be set.