Main Page | Modules | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

# arp.h

Go to the documentation of this file.

    00001 /*! \file arp.h \brief ARP Protocol Library. */
    00002 //*****************************************************************************
    00003 //
    00004 // File Name    : 'arp.h'
    00005 // Title        : ARP Protocol Library
    00006 // Author       : Pascal Stang
    00007 // Created      : 9/7/2004
    00008 // Revised      : 7/3/2005
    00009 // Version      : 0.1
    00010 // Target MCU   : Atmel AVR series
    00011 // Editor Tabs  : 4
    00012 //
    00013 /// \ingroup network
    00014 /// \defgroup arp ARP Protocol Library (arp.c)
    00015 /// \code #include "net/arp.h" \endcode
    00016 /// \par Description
    00017 ///     To send anything over ethernet (or most any other physical network)
    00018 ///     a packet must be addressed to a physical network node address, often
    00019 ///     called a MAC/hardware/ethernet address.  This MAC address identifies
    00020 ///     a specific interface (like the ethernet card in your computer) on the
    00021 ///     network.
    00022 ///         ARP (Address Resolution Protocol) assists in mapping IP addresses to
    00023 ///     the MAC addresses required to actually get data to its destination.
    00024 ///     In other words, an IP address is not enough to send information over
    00025 ///     ethernet.  You need the MAC address of the network interface/card that
    00026 ///     "owns" that IP address.  ARP maintains a table mapping IP addresses to
    00027 ///     MAC addresses.  This table can be filled by both listening to
    00028 ///     traffic on the network, as well as making specific ARP requests if
    00029 ///     an IP<->MAC mapping is not in the table.
    00030 ///
    00031 /// \note This code is currently below version 1.0, and therefore is considered
    00032 /// to be lacking in some functionality or documentation, or may not be fully
    00033 /// tested.  Nonetheless, you can expect most functions to work.
    00034 ///
    00035 //  This code is distributed under the GNU Public License
    00036 //      which can be found at http://www.gnu.org/licenses/gpl.txt
    00037 //*****************************************************************************
    00038 //@{
    00039
    00040 #ifndef ARP_H
    00041 #define ARP_H
    00042
    00043 #include "global.h"
    00044 #include "net.h"
    00045
    00046 #ifndef ARP_TABLE_SIZE
    00047 #define ARP_TABLE_SIZE  8
    00048 #endif
    00049
    00050 #ifndef ARP_CACHE_TIME_TO_LIVE
    00051 #define ARP_CACHE_TIME_TO_LIVE  100
    00052 #endif
    00053
    00054 //#define ARP_DEBUG
    00055 //#define ARP_DEBUG_PRINT
    00056
    00057
    00058 /*! Initialize ARP system.
    00059     Clears ARP table and prepares it for use. This is typically done
    00060     once at program initialization. */
    00061 void arpInit(void);
    00062
    00063 /*! Set IP and Ethernet hardware/MAC address.
    00064     This must be done before valid replies can be generated for ARP
    00065     requests. Typically done once at program initialization. */
    00066 void arpSetAddress(struct netEthAddr* myeth, uint32_t myip);
    00067
    00068 /*! Processes incoming ARP packets.
    00069     This function is to be called when an ARP type packet has arrived
    00070     over the network.  If the packet type is an ARP request for us,
    00071     an ARP reply will be generated and sent. */
    00072 void arpArpIn(unsigned int len, struct netEthArpHeader* packet);
    00073
    00074 /*! Process incoming IP packets to harvest IP<->MAC relationships.
    00075     This function should be called when IP packets are received over the
    00076     network.  It does nothing more than harvest the IP<->MAC address
    00077     relationships from the ethernet and IP header of the packet.  The
    00078     packet is not changed nor processed.  Nothing is sent on the network.
    00079     Use of this command is not required, but it is a good way to
    00080     automatically fill the ARP table with information about nodes that are
    00081     active on the network.
    00082
    00083     \warning On very busy or heavily populated netorks, this can quickly
    00084     fill the ARP table with unnecessary entries, and/or cause some CPU load.
    00085 */
    00086 void arpIpIn(struct netEthIpHeader* packet);
    00087
    00088 /*! Process outgoing IP packet to fill in ethernet header information.
    00089     To be sent on a network, an IP packet must have the correct ethernet
    00090     header information appended to the front.  This function will fill
    00091     in this information.
    00092
    00093     A physical destination IP address argument is needed to support
    00094     sending to a gateway (i.e. when a packet is destined for a node that
    00095     is not on this network, IP addressing is as usual, but we phyiscally
    00096     send the packet to the gateway's ethernet address/interface).
    00097
    00098     \warning Technically, if an IP<->MAC address mapping is not in the
    00099     ARP table, then the IP packet should be held while an ARP request is
    00100     made, and the reply received.  However, in single-threaded ram-limited
    00101     embedded systems, such a holdup is unacceptable.  This function instead
    00102     sends the packet as an ethernet broadcast if a mapping cannot be found.
    00103
    00104     \todo Send the packet broadcast AND send an ARP request, if a mapping
    00105     is not found.
    00106 */
    00107 void arpIpOut(struct netEthIpHeader* packet, uint32_t phyDstIp);
    00108
    00109 /*! Periodic ARP cache maintenance.
    00110     This function is to be called once per second and will slowly
    00111     expire old ARP cache entries. */
    00112 void arpTimer(void);
    00113
    00114
    00115 /*! Check if this IP address is present in the ARP cache. Internal function.
    00116     If IP address is found, function returns index of entry.  If not found,
    00117     returns -1. */
    00118 int arpMatchIp(uint32_t ipaddr);
    00119
    00120 //! Print diagnotic information about ARP packet.
    00121 void arpPrintHeader(struct netArpHeader* packet);
    00122 //! Print diagnotic information about ARP cache.
    00123 void arpPrintTable(void);
    00124
    00125 #endif
    00126 //@}