00001 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 00002 /* 00003 * Copyright (c) 2005,2006 INRIA 00004 * 00005 * This program is free software; you can redistribute it and/or modify 00006 * it under the terms of the GNU General Public License version 2 as 00007 * published by the Free Software Foundation; 00008 * 00009 * This program is distributed in the hope that it will be useful, 00010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 * GNU General Public License for more details. 00013 * 00014 * You should have received a copy of the GNU General Public License 00015 * along with this program; if not, write to the Free Software 00016 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00017 * 00018 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr> 00019 * Modified by Emmanuelle Laprise to remove dependance on LLC headers 00020 */ 00021 #ifndef NET_DEVICE_H 00022 #define NET_DEVICE_H 00023 00024 #include <string> 00025 #include <stdint.h> 00026 #include "ns3/callback.h" 00027 #include "ns3/object.h" 00028 #include "ns3/ptr.h" 00029 #include "address.h" 00030 #include "ipv4-address.h" 00031 #include "ipv6-address.h" 00032 00033 namespace ns3 { 00034 00035 class Node; 00036 class Channel; 00037 class Packet; 00038 00039 /** 00040 * \ingroup node 00041 * \defgroup netdevice NetDevice 00042 */ 00043 /** 00044 * \ingroup netdevice 00045 * 00046 * \brief Network layer to device interface 00047 * 00048 * This interface defines the API which the IP and ARP 00049 * layers need to access to manage an instance of a network device 00050 * layer. It currently does not support MAC-level 00051 * multicast but this should not be too hard to add by adding 00052 * extra methods to register MAC multicast addresses to 00053 * filter out unwanted packets before handing them to the 00054 * higher layers. 00055 * 00056 * In Linux, this interface is analogous to the interface 00057 * just above dev_queue_xmit() (i.e., IP packet is fully 00058 * constructed with destination MAC address already selected). 00059 * 00060 * If you want to write a new MAC layer, you need to subclass 00061 * this base class and implement your own version of the 00062 * NetDevice::SendTo method. 00063 */ 00064 class NetDevice : public Object 00065 { 00066 public: 00067 static TypeId GetTypeId (void); 00068 virtual ~NetDevice(); 00069 00070 /** 00071 * \param name name of the device (e.g. "eth0") 00072 */ 00073 virtual void SetName(const std::string name) = 0; 00074 /** 00075 * \return name name of the device (e.g. "eth0") 00076 */ 00077 virtual std::string GetName(void) const = 0; 00078 /** 00079 * \param index ifIndex of the device 00080 */ 00081 virtual void SetIfIndex(const uint32_t index) = 0; 00082 /** 00083 * \return index ifIndex of the device 00084 */ 00085 virtual uint32_t GetIfIndex(void) const = 0; 00086 00087 00088 /** 00089 * \return the channel this NetDevice is connected to. The value 00090 * returned can be zero if the NetDevice is not yet connected 00091 * to any channel. 00092 */ 00093 virtual Ptr<Channel> GetChannel (void) const = 0; 00094 00095 /** 00096 * \return the current Address of this interface. 00097 */ 00098 virtual Address GetAddress (void) const = 0; 00099 /** 00100 * \param mtu MTU value, in bytes, to set for the device 00101 * \return whether the MTU value was within legal bounds 00102 * 00103 * Override for default MTU defined on a per-type basis. 00104 */ 00105 virtual bool SetMtu (const uint16_t mtu) = 0; 00106 /** 00107 * \return the link-level MTU in bytes for this interface. 00108 * 00109 * This value is typically used by the IP layer to perform 00110 * IP fragmentation when needed. 00111 */ 00112 virtual uint16_t GetMtu (void) const = 0; 00113 /** 00114 * \return true if link is up; false otherwise 00115 */ 00116 virtual bool IsLinkUp (void) const = 0; 00117 /** 00118 * \param callback the callback to invoke 00119 * 00120 * Register a callback invoked whenever the link 00121 * status changes to UP. This callback is typically used 00122 * by the IP/ARP layer to flush the ARP cache 00123 * whenever the link goes up. 00124 */ 00125 virtual void SetLinkChangeCallback (Callback<void> callback) = 0; 00126 /** 00127 * \return true if this interface supports a broadcast address, 00128 * false otherwise. 00129 */ 00130 virtual bool IsBroadcast (void) const = 0; 00131 /** 00132 * \return the broadcast address supported by 00133 * this netdevice. 00134 * 00135 * Calling this method is invalid if IsBroadcast returns 00136 * not true. 00137 */ 00138 virtual Address GetBroadcast (void) const = 0; 00139 00140 /** 00141 * \return value of m_isMulticast flag 00142 */ 00143 virtual bool IsMulticast (void) const = 0; 00144 00145 /** 00146 * \brief Make and return a MAC multicast address using the provided 00147 * multicast group 00148 * 00149 * RFC 1112 says that an Ipv4 host group address is mapped to an Ethernet 00150 * multicast address by placing the low-order 23-bits of the IP address into 00151 * the low-order 23 bits of the Ethernet multicast address 00152 * 01-00-5E-00-00-00 (hex). Similar RFCs exist for Ipv6 and Eui64 mappings. 00153 * This method performs the multicast address creation function appropriate 00154 * to the underlying MAC address of the device. This MAC address is 00155 * encapsulated in an abstract Address to avoid dependencies on the exact 00156 * MAC address format. 00157 * 00158 * A default imlementation of GetMulticast is provided, but this 00159 * method simply NS_ASSERTS. In the case of net devices that do not support 00160 * multicast, clients are expected to test NetDevice::IsMulticast and avoid 00161 * attempting to map multicast packets. Subclasses of NetDevice that do 00162 * support multicasting are expected to override this method and provide an 00163 * implementation appropriate to the particular device. 00164 * 00165 * \param multicastGroup The IP address for the multicast group destination 00166 * of the packet. 00167 * \return The MAC multicast Address used to send packets to the provided 00168 * multicast group. 00169 * 00170 * \warning Calling this method is invalid if IsMulticast returns not true. 00171 * \see Ipv4Address 00172 * \see Address 00173 * \see NetDevice::IsMulticast 00174 */ 00175 virtual Address GetMulticast (Ipv4Address multicastGroup) const = 0; 00176 00177 /** 00178 * \brief Get the MAC multicast address corresponding 00179 * to the IPv6 address provided. 00180 * \param addr IPv6 address 00181 * \return the MAC multicast address 00182 * \warning Calling this method is invalid if IsMulticast returns not true. 00183 */ 00184 virtual Address GetMulticast (Ipv6Address addr) const = 0; 00185 00186 /** 00187 * \brief Return true if the net device is acting as a bridge. 00188 * 00189 * \return value of m_isBridge flag 00190 */ 00191 virtual bool IsBridge (void) const = 0; 00192 00193 /** 00194 * \brief Return true if the net device is on a point-to-point link. 00195 * 00196 * \return value of m_isPointToPoint flag 00197 */ 00198 virtual bool IsPointToPoint (void) const = 0; 00199 /** 00200 * \param packet packet sent from above down to Network Device 00201 * \param dest mac address of the destination (already resolved) 00202 * \param protocolNumber identifies the type of payload contained in 00203 * this packet. Used to call the right L3Protocol when the packet 00204 * is received. 00205 * 00206 * Called from higher layer to send packet into Network Device 00207 * to the specified destination Address 00208 * 00209 * \return whether the Send operation succeeded 00210 */ 00211 virtual bool Send(Ptr<Packet> packet, const Address& dest, uint16_t protocolNumber) = 0; 00212 /** 00213 * \param packet packet sent from above down to Network Device 00214 * \param source source mac address (so called "MAC spoofing") 00215 * \param dest mac address of the destination (already resolved) 00216 * \param protocolNumber identifies the type of payload contained in 00217 * this packet. Used to call the right L3Protocol when the packet 00218 * is received. 00219 * 00220 * Called from higher layer to send packet into Network Device 00221 * with the specified source and destination Addresses. 00222 * 00223 * \return whether the Send operation succeeded 00224 */ 00225 virtual bool SendFrom(Ptr<Packet> packet, const Address& source, const Address& dest, uint16_t protocolNumber) = 0; 00226 /** 00227 * \returns the node base class which contains this network 00228 * interface. 00229 * 00230 * When a subclass needs to get access to the underlying node 00231 * base class to print the nodeid for example, it can invoke 00232 * this method. 00233 */ 00234 virtual Ptr<Node> GetNode (void) const = 0; 00235 00236 /** 00237 * \param node the node associated to this netdevice. 00238 * 00239 * This method is called from ns3::Node::AddDevice. 00240 */ 00241 virtual void SetNode (Ptr<Node> node) = 0; 00242 00243 /** 00244 * \returns true if ARP is needed, false otherwise. 00245 * 00246 * Called by higher-layers to check if this NetDevice requires 00247 * ARP to be used. 00248 */ 00249 virtual bool NeedsArp (void) const = 0; 00250 00251 00252 /** 00253 * Packet types are used as they are in Linux. GCC name resolution on 00254 * typedef enum {} PacketType is broken for the foreseeable future, so 00255 * if you need to use ns-3 PacketType in a driver that also uses the 00256 * Linux packet types you're hosed unless we define a shadow type, 00257 * which we do here. 00258 */ 00259 enum PacketType 00260 { 00261 PACKET_HOST = 1, /**< Packet addressed oo us */ 00262 NS3_PACKET_HOST = PACKET_HOST, 00263 PACKET_BROADCAST, /**< Packet addressed to all */ 00264 NS3_PACKET_BROADCAST = PACKET_BROADCAST, 00265 PACKET_MULTICAST, /**< Packet addressed to multicast group */ 00266 NS3_PACKET_MULTICAST = PACKET_MULTICAST, 00267 PACKET_OTHERHOST, /**< Packet addressed to someone else */ 00268 NS3_PACKET_OTHERHOST = PACKET_OTHERHOST, 00269 }; 00270 00271 /** 00272 * \param device a pointer to the net device which is calling this callback 00273 * \param packet the packet received 00274 * \param protocol the 16 bit protocol number associated with this packet. 00275 * This protocol number is expected to be the same protocol number 00276 * given to the Send method by the user on the sender side. 00277 * \param sender the address of the sender 00278 * \returns true if the callback could handle the packet successfully, false 00279 * otherwise. 00280 */ 00281 typedef Callback<bool,Ptr<NetDevice>,Ptr<const Packet>,uint16_t,const Address &> ReceiveCallback; 00282 00283 /** 00284 * \param cb callback to invoke whenever a packet has been received and must 00285 * be forwarded to the higher layers. 00286 * 00287 */ 00288 virtual void SetReceiveCallback (ReceiveCallback cb) = 0; 00289 00290 00291 /** 00292 * \param device a pointer to the net device which is calling this callback 00293 * \param packet the packet received 00294 * \param protocol the 16 bit protocol number associated with this packet. 00295 * This protocol number is expected to be the same protocol number 00296 * given to the Send method by the user on the sender side. 00297 * \param sender the address of the sender 00298 * \param receiver the address of the receiver 00299 * \param packetType type of packet received (broadcast/multicast/unicast/otherhost) 00300 * \returns true if the callback could handle the packet successfully, false 00301 * otherwise. 00302 */ 00303 typedef Callback< bool, Ptr<NetDevice>, Ptr<const Packet>, uint16_t, 00304 const Address &, const Address &, enum PacketType > PromiscReceiveCallback; 00305 00306 /** 00307 * \param cb callback to invoke whenever a packet has been received in promiscuous mode and must 00308 * be forwarded to the higher layers. 00309 * 00310 * Enables netdevice promiscuous mode and sets the callback that 00311 * will handle promiscuous mode packets. Note, promiscuous mode 00312 * packets means _all_ packets, including those packets that can be 00313 * sensed by the netdevice but which are intended to be received by 00314 * other hosts. 00315 */ 00316 virtual void SetPromiscReceiveCallback (PromiscReceiveCallback cb) = 0; 00317 00318 /** 00319 * \return true if this interface supports a bridging mode, false otherwise. 00320 */ 00321 virtual bool SupportsSendFrom (void) const = 0; 00322 00323 }; 00324 00325 } // namespace ns3 00326 00327 #endif /* NET_DEVICE_H */