F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

a little more dox

Browse Source
This commit is contained in:
Craig Dowell
2009-03-17 16:00:46 -07:00
parent ac181370f3
commit 3eff196614
1 changed files with 102 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
src/devices/tap-bridge/tap.h
View File

@@ -22,9 +22,7 @@
* information is taken from the ns-3 simulation and a tap device matching
* the ns-3 attributes is created for you. In this mode, which we call
* LocalDevice mode, an ns-3 net device is made to appear to be directly
* connected to a real host. In LocalDevice mode, configuration of the TAP
* device is almost completely handled by ns-3. This is useful if you want
* to use real processes in your host to talk over simulated networks.
* connected to a real host.
*
* This is illustrated below
*
@@ -53,23 +51,25 @@
*
* In this case, the ns-3 net device in the ghost node appears as if it were
* actually replacing the TAP device in the Linux host. The ns-3 process
* configures the IP address and MAC address of the TAP device to match the
* values assigned to the ns-3 net device. The IPC link is via the network
* tap mechanism in the underlying OS and acts as a bridge; but a bridge
* between devices that happen to have the same shared MAC address.
* creates the TAP device configures the IP address and MAC address of the
* TAP device to match the values assigned to the ns-3 net device. The IPC
* link is via the network tap mechanism in the underlying OS and acts as a
* conventional bridge; but a bridge between devices that happen to have the
* same shared MAC address.
*
* The LocalDevice mode is the default operating mode of the Tap Bridge.
*
* The second mode, BridgedDevice mode, is more oriented toward allowing existing
* host configurations. This allows the Tap Bridge to be "further bridged" to
* other existing devices via an existing TAP device. This mode is especially
* useful in the case of virtualization where the configuration of the virtual
* hosts may be dictated by an existing system and not easily changed. For
* example, a particular VM scheme may create virtual "vethx" or "vmnetx"
* devices that appear local to virtual hosts. In order to connect to such
* systems, we need to manually create TAP devices on the host system and brigde
* these TAP devices to the existing virtual devices. We then need to have a Tap
* Bridge corresponding created to talk to each of these TAP devices.
* host configurations. This allows ns-3 net devices to appear as part of a host
* operating system bridge (in Linux, we make the ns-3 device part of a "brctl"
* bridge. This mode is especially useful in the case of virtualization where
* the configuration of the virtual hosts may be dictated by another system and
* not be changable to suit ns-3. For example, a particular VM scheme may create
* virtual "vethx" or "vmnetx" devices that appear local to virtual hosts. In
* order to connect to such systems, one would need to manually create TAP devices
* on the host system and brigde these TAP devices to the existing (VM) virtual
* devices. The job of the Tap Bridge in this case is to extend the bridge to
* join the ns-3 net device.
*
* This is illustrated below:
*
@@ -98,17 +98,19 @@
*
* In this case, a collection of virtual machines with associated Virtual
* Devices is created in the virtualization environment (for exampe, OpenVZ
* or VMware). A TAP device is then created for each Virtual Device that is
* desired to be bridged into the ns-3 simulation. The created TAP devices are
* then bridged together with the Virtual Devices using a native OS bridge
* mechanism shown as "OS (brctl) Bridge" in the illustration above..
* or VMware). A TAP device (with a specific name) is then manually created
* for each Virtual Device that will be bridged into the ns-3 simulation.
* These created TAP devices are then bridged together with the Virtual Devices
* using a native OS bridge mechanism shown as "OS (brctl) Bridge" in the
* illustration above.
*
* In the ns-3 simulation a Tap Bridge is created for each TAP Device. The
* name of the TAP Device is assigned to the Tap Bridge using the "DeviceName"
* attribute. The Tap Bridge then opens a network tap to the TAP Device and
* extends the bridge to encompass the ns-3 net device. This makes it appear
* as if an ns-3 simulated net device is a member of the "OS (brctl) Bridge"
* and allows the Virtual Machines to communicate with the ns-3 simulation..
* In the ns-3 simulation, a Tap Bridge is created to match each TAP Device.
* The name of the TAP Device is assigned to the Tap Bridge using the
* "DeviceName" attribute. The Tap Bridge then opens a network tap to the TAP
* Device and logically extends the bridge to encompass the ns-3 net device.
* This makes it appear as if an ns-3 simulated net device is a member of the
* "OS (brctl) Bridge" and allows the Virtual Machines to communicate with the
* ns-3 simulation..
*
* \subsection TapBridgeLocalDeviceMode TapBridge LocalDevice Mode
*
@@ -116,15 +118,16 @@
* device appears to the Linux host computer as a network device just like any
* arbitrary "eth0" or "ath0" might appear. The creation and configuration
* of the TAP device is done by the ns-3 simulation and no manual configuration
* is required. The IP addresses, MAC addresses, gateways, etc., for created
* TAP devices are extracted from the simulation itself by querying the
* configuration of the ns-3 device and the TapBridge Attributes.
* is required by the user. The IP addresses, MAC addresses, gateways, etc.,
* for created TAP devices are extracted from the simulation itself by querying
* the configuration of the ns-3 device and the TapBridge Attributes.
*
* The TapBridge appears to an ns-3 simulation as a channel-less net device.
* This device must not have an IP address associated with it, but the bridged
* (ns-3) net device must have an IP adress. Be aware that this is the inverse
* of an ns-3 BridgeNetDevice which demands that its bridge ports not have IP
* addresses, but allows the bridge device itself to have an IP address.
* of an ns-3 BridgeNetDevice (or a conventional bridge in general) which
* demands that its bridge ports not have IP addresses, but allows the bridge
* device itself to have an IP address.
*
* The host computer will appear in a simulation as a "ghost" node that contains
* one TapBridge for each NetDevice that is being bridged. From the perspective
@@ -151,32 +154,31 @@
*
* The Tap Bridge lives in a kind of a gray world somewhere between a Linux host
* and an ns-3 bridge device. From the Linux perspective, this code appears as
* the user mode handler for a TAP net device. In LocalDevice mode, this TAP is
* automatically created by the ns-3 simulation. When the Linux host writes
* to one of these /dev/tap devices, the write is redirected into the TapBridge
* that lives in the ns-3 world; and from this perspective, the packet write on
* linux becomes a packet read. In other words, a Linux process writes a packet
* to a tap device and this packet is redirected by the network tap mechanism to
* an ns-3 process where it is received by the TapBridge as a result of a read
* operation there. The TapBridge then forwards the packet to the ns-3 net
* device to which it is bridged; and therefore it appears as if the Linux host
* sent a packet directly over an ns-3 net device.
* the user mode handler for a TAP net device. In LocalDevice mode, this TAP
* device is automatically created by the ns-3 simulation. When the Linux host
* writes to one of these automatically created /dev/tap devices, the write is
* redirected into the TapBridge that lives in the ns-3 world; and from this
* perspective, the packet write on Linux becomes a packet read in the Tap Bridge.
* In other words, a Linux process writes a packet to a tap device and this packet
* is redirected by the network tap mechanism toan ns-3 process where it is
* received by the TapBridge as a result of a read operation there. The TapBridge
* then writes the packet to the ns-3 net device to which it is bridged; and
* therefore it appears as if the Linux host sent a packet directly through an
* ns-3 net device onto an ns-3 network.
*
* In the other direction, a packet received by an ns-3 net device is bridged
* (in the ns-3 sense) to the TapBridge. A packet sent to the ns-3 device then
* appears via a callback in the TapBridge. The TapBridge then takes that
* packet and writes it back to the host using the network tap mechanism. This
* write to the device will appear to the Linux host as if a packet has arrived
* on its device; and therefore as if a packet received by the ns-3 net device
* has appeared on the Linux net device.
* In the other direction, a packet received by the ns-3 net device connected to
* the Tap Bridge is sent via promiscuous callback to the TapBridge. The
* TapBridge then takes that packet and writes it back to the host using the
* network tap mechanism. This write to the device will appear to the Linux
* host as if a packet has arrived on its device; and therefore as if a packet
* received by the ns-3 net device has appeared on a Linux net device.
*
* The upshot is that the Tap Bridge appears to bridge a tap device on a
* Linux host in the "real world" to an ns-3 net device in the simulation
* and make is appear that a ns-3 net device is actually installed in the
* Linux host. The network tap used as IPC acts as a network bridge between
* two devices that happen to have the same MAC address. This is okay since
* the two fact that there are two devices with the same address is not known
* outside of the pair.
* Linux host in the "real world" to an ns-3 net device in the simulation.
* Because the TAP device and the bridged ns-3 net device have the same MAC
* address and the network tap IPC link is not exernalized, this particular
* kind of bridge makes ti appear that a ns-3 net device is actually installed
* in the Linux host.
*
* In order to implement this on the ns-3 side, we need a "ghost node" in the
* simulation to hold the bridged ns-3 net device and the TapBridge. This node
@@ -213,9 +215,9 @@
* \subsection TapBridgeBridgedDeviceMode TapBridge BridgedDevice Mode
*
* In BridgedDevice mode, the TapBridge and its associated ns-3 net device are
* arranged in a fundamentally similar was as in LocalDevice mode. The bridging
* functionality is also accomplished in a fundamentally similar way. The
* previous description applies except as noted below.
* arranged in a fundamentally similar was as in LocalDevice mode. The TAP
* device is bridged to the ns-3 net device in the same way. The description
* of LocalDevice mode applies except as noted below.
*
* The most user-visible difference in modes is how the creation and
* configuration of the underlying TAP device is done. In LocalDevice mode,
@@ -223,41 +225,61 @@
* completely by ns-3. In BridgedDevice mode, creation and configuration is
* delegated (due to requirements) to the user. No configuration is done in
* ns-3 other than settting the operating mode of the TapBridge to
* "BridgedDevice" and specifying the name of the pre-configured TAP device,
* both via ns-3 Attributes of the TapBridge.
* "BridgedDevice" and specifying the name of a pre-configured TAP device
* using ns-3 Attributes of the TapBridge.
*
* The primary difference between modes is due to the fact that in BridgedDevice
* mode the MAC addresses of the TAPs will be pre-configured and will therefore
* be different than those in the bridged device. As in LocalDevice mode, the
* Tap Bridge functions as IPC bridge between the TAP device and the ns-3 net
* device, but in BridgedDevice configurations the two devices will have
* different MAC addresses.
* The primary conceptual difference between modes is due to the fact that in
* BridgedDevice mode the MAC addresses of the user-created TAPs will be pre-
* configured and will therefore be different than those in the bridged device.
* As in LocalDevice mode, the Tap Bridge functions as IPC bridge between the
* TAP device and the ns-3 net device, but in BridgedDevice configurations the
* two devices will have different MAC addresses and the bridging functionality
* will be fundamentally the same as in any bridge. Since this implies MAC
* address spoofing, the only ns-3 devices which may paritcipate in a bridge
* in BridgedDevice mode must support SendFrom (i.e., a call to the method
* SupportsSendFrom in the bridged net device must return true).
*
* \subsection TapBridgeBridgedDeviceModeOperation TapBridge BridgedDevice Mode Operation
*
* As described in the LocalDevice mode section, when the Linux host writes to
* one of the /dev/tap devices, the write is redirected into the TapBridge
* that lives in the ns-3 world; and from this perspective, the packet write on
* linux becomes a packet read. The packet at this point will contain a MAC
* source address corresponding to the address of the TAP device. Before this
* packet is sent to the bridged ns-3 net device, the MAC headers are stripped
* off. When the bridged net device actually executes the send, it will replace
* the MAC headers with its own.
* that lives in the ns-3 world. In the case of the BridgedDevice mode, these
* packets will need to be sent out on the ns-3 network as if they were sent on
* the Linux network. This means calling the SendFrom method on the bridged
* device and providing the source and destination MAC addresses found in the
* packet.
*
* In the other direction, a packet received by an ns-3 net device is bridged
* (in the ns-3 sense) to the TapBridge. A packet sent to the ns-3 device then
* appears via a callback in the TapBridge. At this point, there is no MAC
* addressing information on the packet. In LocalDevice mode, the TapBridge
* adds back the MAC address that it found in the ns-3 bridged net device
* configuration. In the BridgedDevice mode, it needs to add back the MAC
* address of the TAP device.
* In the other direction, a packet received by an ns-3 net device is hooked
* via callback to the TapBridge. This must be done in promiscuous mode since
* the goal is to bridge the ns-3 net device onto the OS (brctl) bridge of
* which the TAP device is a part.
*
* There is no functional difference between modes at this level, even though
* the configuration and conceptual models regarding what is going on are quite
* different -- the Tap Bridge is just a bridge. In the LocalDevice model, the
* bridge is between devices having the same MAC address and in the
* different -- the Tap Bridge is just acting like a bridge. In the LocalDevice
* mode, the bridge is between devices having the same MAC address and in the
* BridgedDevice model the bridge is between devices having different MAC
* addresses.
*
* \subsection TapBridgeSingleSourceModeOperation TapBridge SingleSource Mode Operation
*
* As described in above, the Tap Bridge acts like a bridge. Just like every
* other bridge, there is a requirement that participating devices must have
* the ability to receive promiscuously and to spoof the source MAC addresses
* of packets.
*
* We do, however, have a specific requirement to be able to bridge Virtual
* Machines onto wireless STA nodes. Unfortunately, the 802.11 spec doesn't
* provide a good way to implement SendFrom. So we have to work around this.
*
* To this end, we provice the SingleSource mode of the Tap Bridge. This
* mode allows you to create a bridge as described in BridgedDevice mode, but
* only allows one source of packets on the Linux side of the bridge. The
* address on the Linux side is remembered in the Tap Bridge, and all packets
* coming from the Linux side are repeated out the ns-3 side using the ns-3 device
* MAC source address. All packets coming in from the ns-3 side are repeated
* out the Linux side using the remembered MAC address. This allows us to use
* SendFrom on the ns-3 device side which is available on all ns-3 net devices.
*
* \section TapBridgeChannelModel Tap Bridge Channel Model
*