Added doxygen documentation to the ARP module
diff --git a/contiki/doc/Doxyfile b/contiki/doc/Doxyfile
index 730e69b..8b7c7fe 100644
--- a/contiki/doc/Doxyfile
+++ b/contiki/doc/Doxyfile
@@ -66,6 +66,8 @@
../ctk/ctk-draw.h \
../ctk/ctk-vncserver.c \
../uip/uip.h \
+ ../uip/uip_arp.h \
+ ../uip/uip_arp.c \
../ek/loader.h \
../ek/dispatcher.h \
../lib/cc.h \
diff --git a/contiki/uip/uip_arp.c b/contiki/uip/uip_arp.c
index a2ff17c..ca26f5e 100644
--- a/contiki/uip/uip_arp.c
+++ b/contiki/uip/uip_arp.c
@@ -1,5 +1,20 @@
+/**
+ * \file
+ * Implementation of the ARP Address Resolution Protocol.
+ * \author Adam Dunkels <adam@dunkels.com>
+ *
+ * The Address Resolution Protocol ARP is used for mapping between IP
+ * addresses and link level addresses such as the Ethernet MAC
+ * addresses. ARP uses broadcast queries to ask for the link level
+ * address of a known IP address and the host which is configured with
+ * the IP address for which the query was meant, will respond with its
+ * link level address.
+ *
+ * \note This ARP implementation only supports Ethernet.
+ */
+
/*
- * Copyright (c) 2001-2002, Adam Dunkels.
+ * Copyright (c) 2001-2003, Adam Dunkels.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -10,10 +25,7 @@
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
- * 3. All advertising materials mentioning features or use of this software
- * must display the following acknowledgement:
- * This product includes software developed by Adam Dunkels.
- * 4. The name of the author may not be used to endorse or promote
+ * 3. The name of the author may not be used to endorse or promote
* products derived from this software without specific prior
* written permission.
*
@@ -31,7 +43,7 @@
*
* This file is part of the uIP TCP/IP stack.
*
- * $Id: uip_arp.c,v 1.6 2003/08/24 22:40:46 adamdunkels Exp $
+ * $Id: uip_arp.c,v 1.7 2003/09/05 21:03:36 adamdunkels Exp $
*
*/
@@ -94,6 +106,11 @@
#define BUF ((struct arp_hdr *)&uip_buf[0])
#define IPBUF ((struct ethip_hdr *)&uip_buf[0])
/*-----------------------------------------------------------------------------------*/
+/**
+ * Initialize the ARP module.
+ *
+ */
+/*-----------------------------------------------------------------------------------*/
void
uip_arp_init(void)
{
@@ -102,6 +119,15 @@
}
}
/*-----------------------------------------------------------------------------------*/
+/**
+ * Periodic ARP processing function.
+ *
+ * This function performs periodic timer processing in the ARP module
+ * and should be called at regular intervals. The recommended interval
+ * is 10 seconds between the calls.
+ *
+ */
+/*-----------------------------------------------------------------------------------*/
void
uip_arp_timer(void)
{
@@ -180,6 +206,19 @@
tabptr->time = arptime;
}
/*-----------------------------------------------------------------------------------*/
+/**
+ * ARP processing for incoming IP packets
+ *
+ * This function should be called by the device driver when an IP
+ * packet has been received. The function will check if the address is
+ * in the ARP cache, and if so the ARP cache entry will be
+ * refreshed. If no ARP cache entry was found, a new one is created.
+ *
+ * This function expects an IP packet with a prepended Ethernet header
+ * in the uip_buf[] buffer, and the length of the packet in the global
+ * variable uip_len.
+ */
+/*-----------------------------------------------------------------------------------*/
void
uip_arp_ipin(void)
{
@@ -199,6 +238,28 @@
return;
}
/*-----------------------------------------------------------------------------------*/
+/**
+ * ARP processing for incoming ARP packets.
+ *
+ * This function should be called by the device driver when an ARP
+ * packet has been received. The function will act differently
+ * depending on the ARP packet type: if it is a reply for a request
+ * that we previously sent out, the ARP cache will be filled in with
+ * the values from the ARP reply. If the incoming ARP packet is an ARP
+ * request for our IP address, an ARP reply packet is created and put
+ * into the uip_buf[] buffer.
+ *
+ * When the function returns, the value of the global variable uip_len
+ * indicates whether the device driver should send out a packet or
+ * not. If uip_len is zero, no packet should be sent. If uip_len is
+ * non-zero, it contains the length of the outbound packet that is
+ * present in the uip_buf[] buffer.
+ *
+ * This function expects an ARP packet with a prepended Ethernet
+ * header in the uip_buf[] buffer, and the length of the packet in the
+ * global variable uip_len.
+ */
+/*-----------------------------------------------------------------------------------*/
void
uip_arp_arpin(void)
{
@@ -247,6 +308,33 @@
return;
}
/*-----------------------------------------------------------------------------------*/
+/**
+ * Prepend Ethernet header to an outbound IP packet and see if we need
+ * to send out an ARP request.
+ *
+ * This function should be called before sending out an IP packet. The
+ * function checks the destination IP address of the IP packet to see
+ * what Ethernet MAC address that should be used as a destination MAC
+ * address on the Ethernet.
+ *
+ * If the destination IP address is in the local network (determined
+ * by logical ANDing of netmask and our IP address), the function
+ * checks the ARP cache to see if an entry for the destination IP
+ * address is found. If so, an Ethernet header is prepended and the
+ * function returns. If no ARP cache entry is found for the
+ * destination IP address, the packet in the uip_buf[] is replaced by
+ * an ARP request packet for the IP address. The IP packet is dropped
+ * and it is assumed that they higher level protocols (e.g., TCP)
+ * eventually will retransmit the dropped packet.
+ *
+ * If the destination IP address is not on the local network, the IP
+ * address of the default router is used instead.
+ *
+ * When the function returns, a packet is present in the uip_buf[]
+ * buffer, and the length of the packet is in the global variable
+ * uip_len.
+ */
+/*-----------------------------------------------------------------------------------*/
void
uip_arp_out(void)
{
diff --git a/contiki/uip/uip_arp.h b/contiki/uip/uip_arp.h
index d3e9165..55e455b 100644
--- a/contiki/uip/uip_arp.h
+++ b/contiki/uip/uip_arp.h
@@ -1,5 +1,12 @@
+/**
+ * \file
+ * Macros and definitions for the ARP module.
+ * \author Adam Dunkels <adam@dunkels.com>
+ */
+
+
/*
- * Copyright (c) 2001-2002, Adam Dunkels.
+ * Copyright (c) 2001-2003, Adam Dunkels.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
@@ -10,10 +17,7 @@
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
- * 3. All advertising materials mentioning features or use of this software
- * must display the following acknowledgement:
- * This product includes software developed by Adam Dunkels.
- * 4. The name of the author may not be used to endorse or promote
+ * 3. The name of the author may not be used to endorse or promote
* products derived from this software without specific prior
* written permission.
*
@@ -31,7 +35,7 @@
*
* This file is part of the uIP TCP/IP stack.
*
- * $Id: uip_arp.h,v 1.3 2003/06/30 20:36:28 adamdunkels Exp $
+ * $Id: uip_arp.h,v 1.4 2003/09/05 21:03:36 adamdunkels Exp $
*
*/
@@ -40,12 +44,19 @@
#include "uip.h"
+
+/**
+ * Representation of a 48-bit Ethernet address.
+ */
struct uip_eth_addr {
u8_t addr[6];
};
extern struct uip_eth_addr uip_ethaddr;
+/**
+ * The Ethernet header.
+ */
struct uip_eth_hdr {
struct uip_eth_addr dest;
struct uip_eth_addr src;
@@ -93,17 +104,58 @@
void uip_arp_timer(void);
+/**
+ * Set the default router's IP address.
+ *
+ * \param addr A pointer to a 4-byte array containing the IP address
+ * of the default router.
+ */
#define uip_setdraddr(addr) do { uip_arp_draddr[0] = addr[0]; \
uip_arp_draddr[1] = addr[1]; } while(0)
+
+/**
+ * Set the netmask.
+ *
+ * \param addr A pointer to a 4-byte array containing the IP address
+ * of the netmask.
+ */
#define uip_setnetmask(addr) do { uip_arp_netmask[0] = addr[0]; \
uip_arp_netmask[1] = addr[1]; } while(0)
+/**
+ * Get the default router's IP address.
+ *
+ * \param addr A pointer to a 4-byte array that will be filled in with
+ * the IP address of the default router.
+ */
#define uip_getdraddr(addr) do { addr[0] = uip_arp_draddr[0]; \
addr[1] = uip_arp_draddr[1]; } while(0)
+
+/**
+ * Get the netmask.
+ *
+ * \param addr A pointer to a 4-byte array that will be filled in with
+ * the value of the netmask.
+ */
#define uip_getnetmask(addr) do { addr[0] = uip_arp_netmask[0]; \
addr[1] = uip_arp_netmask[1]; } while(0)
+
+/**
+ * Specifiy the Ethernet MAC address.
+ *
+ * The ARP code needs to know the MAC address of the Ethernet card in
+ * order to be able to respond to ARP queries and to generate working
+ * Ethernet headers.
+ *
+ * \note This macro only specifies the Ethernet MAC address to the ARP
+ * code. It cannot be used to change the MAC address of the Ethernet
+ * card.
+ *
+ * \param eaddr A pointer to a struct uip_eth_addr containing the
+ * Ethernet MAC address of the Ethernet card.
+ */
#define uip_setethaddr(eaddr) do {uip_ethaddr.addr[0] = eaddr.addr[0]; \
uip_ethaddr.addr[1] = eaddr.addr[1];\
uip_ethaddr.addr[2] = eaddr.addr[2];\
@@ -113,7 +165,9 @@
-/* Internal variables that are set using the macros uip_setdraddr and
- uip_setnetmask. */
+/**
+ * \internal Internal variables that are set using the macros
+ * uip_setdraddr and uip_setnetmask.
+ */
extern u16_t uip_arp_draddr[2], uip_arp_netmask[2];
#endif /* __UIP_ARP_H__ */