TCP/IP API Functions

3.2.6pkt_send()

This function either sends the data in the passed PACKET structure or queues the PACKET structure for later transmission. If the MAC hardware is idle, the actual transmission of the packet must be started by this function, otherwise it must be scheduled to be sent later, usually by an End Of Transmission (EOT) interrupt from the hardware.

MAC headers for media, such as Ethernet or Token Ring, are placed at the head of the buffer passed by the calling function. Some drivers might have to access, strip, or modify the MAC header if they are layered on top of complex lower layers.

Syntax

int pkt_send(PACKET pkt)

where:

pkt	Is the PACKET structure containing the frame to send.

Return value

Returns one of the following:

0	If successful.

ENP_code If not successful (see ENP_ error codes on page A-2).

Usage

The PACKET structure is defined in the file \inet\netbuf.h. All the information needed to send the packet is filled in before this call is made. The important fields are:

pkt->nb_prot Pointer to data to send.

pkt->nb_plen Length of data to send.

pkt->net

nets[ ] structure for posting statistics.

The hardware driver must send nb_plen bytes, starting at nb_prot. When all the bytes are sent, the PACKET structure must be returned to the free queue by a call to pk_free(), which can be called at interrupt time. Do not free the packet before it has been successfully sent by the hardware, because it can then be reused (and its buffer altered) by the IP stack.

The simplest way to implement this function is to block (busy-wait) until the data is sent. This allows fast prototyping of new drivers, but generally affects performance. The usual design is to:

3-22

Copyright © 1998-2001 ARM Limited. All rights reserved.

ARM DUI 0144B

TCP/IP API Functions

1.Put the packet in an awaiting_send queue.

2.Check to see if the hardware is idle.

3.Call a send_next_from_q() function to dequeue the packet at the head of the send queue.

4.Begin sending the packet.

The EOT interrupt frees the packet that has just been sent and calls the send_next_from_q() function again. Moving all the PACKETS through the awaiting_send queue ensures that they are sent in FIFO order. This significantly improves TCP and application performance.

If your hardware (or a lower layer driver) does not have an EOT interrupt or any analogous mechanism, you may need to use the raw_send() alternative to this function.

Slow devices, such as serial links and hardware that DMAs data directly out of predefined memory areas, can copy the passed buffer into driver-managed memory buffers, free the PACKET, and return immediately. However, these devices must be prepared to be called with more packets before transmission is complete.

Interface transmit functions must also maintain system statistics about packet transmissions. These are kept in the n_mib structure attached to each nets[ ] entry. Exact definitions of all these counters are available in RFC 1213. At a minimum, you should maintain packet byte and error counts, because these can help you debug your product during development and isolate configuration problems in the field. It is recommended that you perform statistics keeping at EOT time, but statistics can be approximated in this call. Example 3-3 on page 3-24 shows a generic example.

ARM DUI 0144B

Copyright © 1998-2001 ARM Limited. All rights reserved.

3-23

TCP/IP API Functions

Example 3-3

/* compile statistics about completed transmit */

eth = (struct ethhdr *)pkt->nb_prot;	/* get ether header */
ifc = pkt->net;
if(send_status==SUCCESSFUL)	/* send_status set by hardware EOT */
{
if(eth->e_dst[0] & 0x01)	/* see if multicast bit is on */
ifc->n_mib->ifOutNUcastPkts++;
else
ifc->n_mib->ifOutUcastPkts++;

ifc->n_mib->ifOutOctets +=pkt->nb_plen;

}

else /* error sending packet */

{

ifc->n_mib->ifOutErrors++;

}

Because this function may not wait for the packet transmission to complete, depending on your implementation, you can return a 0 if the packet has been successfully queued for send, or the send is in progress. Error (nonzero) codes should only be returned if a distinct hardware failure is detected. There is no mechanism to report errors detected in previous packets or during the EOT interrupt.

3-24

Copyright © 1998-2001 ARM Limited. All rights reserved.

ARM DUI 0144B

TCP/IP API Functions

3.2.7raw_send()

This function transmits the data on the device corresponding to the nets[ ] entry passed to it. Any MAC header required is placed at the head of the buffer passed by the calling function. This function must not return until it has finished processing the data in the passed buffer, because the buffer may be reused (corrupting the data) immediately upon return.

Note

The pkt_send() function (pkt_send() on page 3-22) must be used instead of this function if there is an EOT interrupt available on the hardware. This function is designed for old packet driver type drivers that do not support EOT and might not be needed otherwise. The function you are not using (either pkt_send() or raw_send()) must be set to NULL in the nets[ ] structure.

Syntax

int raw_send(NET net, char *data, unsigned data_bytes)

where:
net	Is the net structure on which to send it.
data	Is a pointer to the data buffer to send.
data_bytes	Is the number of bytes to send (length of data).

Return value

Returns one of the following:

0	If successful.
ENP_Code	If not successful (see ENP_ error codes on page A-2).

Usage

Slow devices (such as serial links) and hardware that DMAs data directly out of predefined memory areas can copy the passed buffer into driver managed memory buffers and return immediately. However, these devices must be prepared to be called with more data before transmission is complete.

Interface transmit functions must also maintain system statistics about packet transmissions. These are kept in the n_mib structure attached to each nets[ ] entry. Exact definitions of all these counters are available in RFC 1213.

ARM DUI 0144B

Copyright © 1998-2001 ARM Limited. All rights reserved.

3-25

TCP/IP API Functions

At a minimum, you must maintain packet byte and error counts, because these can aid greatly with debugging your product during development and isolating configuration problems in the field. It is recommended that you perform statistics keeping at EOT time, but these can be approximated in this call. Example 3-4 is a generic example.

Example 3-4

/* compile statistics about completed transmit */

eth = (struct ethhdr *)data;	/* get ether header */
if(send_status == SUCCESSFUL)	/* send_status read from hardware */
{
if(eth->e_dst[0] & 0x01)	/* see if multicast bit is on */
net->n_mib->ifOutNUcastPkts++;
else
net->n_mib->ifOutUcastPkts++;
net_>n_mib->ifOutOctets +=databytes;
}
else	/* error sending packet*/
{
net->n_mib->ifOutErrors++;
}

3-26

Copyright © 1998-2001 ARM Limited. All rights reserved.

ARM DUI 0144B

Chapter 4

DHCP Client Functions

DHCP is used for configuring a network interface using information stored on a remote server. This chapter describes the function calls used to request configuration information for an interface. It contains the following section:

•DHCP client functions on page 4-2.

ARM DUI 0144B

Copyright © 1998-2001 ARM Limited. All rights reserved.

4-1