TCP/IP API Functions

4.3.5n_stats()

This is an optional function that can be used to display per-net statistics. It could also be used to log such statistics or return a pointer to a status block, depending on your requirements.

Syntax

void *n_stats(int if_number)

where:

if_number is an index into the nets[ ] array of the interface for which statistics are to be dumped.

Return value

Optional.

Usage

This function is only used for debugging purposes. If you need extra debugging information from the device driver, you can arrange for this function to return a pointer to a status block.

TCP/IP API Functions

4.3.6pkt_send()

This function sends the data in the passed PACKET structure and queues the PACKET structure for later release. If the MAC hardware is idle, the actual transmission of the packet should be started by this function, otherwise it should 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 may have to access, strip, or modify the MAC header if they are layered on top of complex lower layers.

Syntax

tStatus pkt_send(PACKET pkt)

where:

Return value

Returns one of the following:

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.

The hardware driver should send nb_plen bytes, starting at nb_prot. When all the bytes are sent, the PACKET structure should 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:

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 should be prepared to be called with more packets before transmission is complete.

Interface transmit functions should 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 4-3 on page 4-26 shows a generic example.

TCP/IP API Functions

Example 4-3

/* compile statistics about completed transmit */

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.