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_PRINT
    00055
    00056
    00057 /*! Initialize ARP system.
    00058     Clears ARP table and prepares it for use. This is typically done
    00059     once at program initialization. */
    00060 void arpInit(void);
    00061
    00062 /*! Set IP and Ethernet hardware/MAC address.
    00063     This must be done before valid replies can be generated for ARP
    00064     requests. Typically done once at program initialization. */
    00065 void arpSetAddress(struct netEthAddr* myeth, uint32_t myip);
    00066
    00067 /*! Processes incoming ARP packets.
    00068     This function is to be called when an ARP type packet has arrived
    00069     over the network.  If the packet type is an ARP request for us,
    00070     an ARP reply will be generated and sent. */
    00071 void arpArpIn(unsigned int len, struct netEthArpHeader* packet);
    00072
    00073 /*! Process incoming IP packets to harvest IP<->MAC relationships.
    00074     This function should be called when IP packets are received over the
    00075     network.  It does nothing more than harvest the IP<->MAC address
    00076     relationships from the ethernet and IP header of the packet.  The
    00077     packet is not changed nor processed.  Nothing is sent on the network.
    00078     Use of this command is not required, but it is a good way to
    00079     automatically fill the ARP table with information about nodes that are
    00080     active on the network.
    00081
    00082     \warning On very busy or heavily populated netorks, this can quickly
    00083     fill the ARP table with unnecessary entries, and/or cause some CPU load.
    00084 */
    00085 void arpIpIn(struct netEthIpHeader* packet);
    00086
    00087 /*! Process outgoing IP packet to fill in ethernet header information.
    00088     To be sent on a network, an IP packet must have the correct ethernet
    00089     header information appended to the front.  This function will fill
    00090     in this information.
    00091
    00092     A physical destination IP address argument is needed to support
    00093     sending to a gateway (i.e. when a packet is destined for a node that
    00094     is not on this network, IP addressing is as usual, but we phyiscally
    00095     send the packet to the gateway's ethernet address/interface).
    00096
    00097     \warning Technically, if an IP<->MAC address mapping is not in the
    00098     ARP table, then the IP packet should be held while an ARP request is
    00099     made, and the reply received.  However, in single-threaded ram-limited
    00100     embedded systems, such a holdup is unacceptable.  This function instead
    00101     sends the packet as an ethernet broadcast if a mapping cannot be found.
    00102
    00103     \todo Send the packet broadcast AND send an ARP request, if a mapping
    00104     is not found.
    00105 */
    00106 void arpIpOut(struct netEthIpHeader* packet, uint32_t phyDstIp);
    00107
    00108 /*! Periodic ARP cache maintenance.
    00109     This function is to be called once per second and will slowly
    00110     expire old ARP cache entries. */
    00111 void arpTimer(void);
    00112
    00113
    00114 /*! Check if this IP address is present in the ARP cache. Internal function.
    00115     If IP address is found, function returns index of entry.  If not found,
    00116     returns -1. */
    00117 int arpMatchIp(uint32_t ipaddr);
    00118
    00119 //! Print diagnotic information about ARP packet.
    00120 void arpPrintHeader(struct netArpHeader* packet);
    00121 //! Print diagnotic information about ARP cache.
    00122 void arpPrintTable(void);
    00123
    00124 #endif
    00125 //@}