41  * \ingroup devices

    41  * \ingroup tap-bridge

    42  * \defgroup tap-bridge TapBridge

    44  * \brief A bridge to make it appear that a host is connected to an ns-3 net device.

    43  * \brief A bridge to make it appear that a real host process is connected to 

    45  *

    44  * an ns-3 net device.

    46  * The Tap Bridge lives in a kind of a gray world somewhere between a Linux host and

    45  *

    47  * an ns-3 bridge device.  From the Linux perspective, this code appears as the user

    46  * The Tap Bridge lives in a kind of a gray world somewhere between a

    48  * mode handler for a Tap net device.  That is, when the Linux host writes to the

    47  * Linux host and an ns-3 bridge device.  From the Linux perspective,

    49  * /dev/tap device that we create for it, the write is redirected into the TapBridge

    48  * this code appears as the user mode handler for a Tap net device.  That

    50  * and from that perspective, becomes a read.  The TapBridge then redirects the data

    49  * is, when the Linux host writes to a /dev/tap device (that is either

    51  * written (by the Linux host) to the tap device on out the ns-3 net device to which

    50  * manually or automatically created depending on basic operating mode 

    52  * we are bridged.  When a packet comes in from the ns-3 world to the ns-3 net device

    51  * -- more on this later), the write is redirected into the TapBridge that

    53  * we are bridging, it appears via a callback from that net device.  Our job is to

    52  * lives in the ns-3 world; and from this perspective, becomes a read.

    54  * take those bits and write them back to the host using the user mode handler for

    53  * In other words, a Linux process writes a packet to a tap device and

    55  * /dev/tapx.  This write to the device will then appear to the Linux host as if a 

    54  * this packet is redirected to an ns-3 process where it is received by

    56  * packet has arrived on its device.

    55  * the TapBridge as a result of a read operation there.  The TapBridge

    57  *

    56  * then sends the packet to the ns-3 net device to which it is bridged.

    58  * The upshot is that the Tap Bridge appears to bridge a tap device on a Linux host 

    57  * In the other direction, a packet received by an ns-3 net device is

    59  * in the "real world" to an ns-3 net device in the simulation.  In order to do this

    58  * bridged to the TapBridge (it appears via a callback from that net

    60  * we need a "ghost node" in the simulation to hold the bridged ns-3 net device and 

    59  * device.  The TapBridge then takes that packet and writes it back to

    61  * this Tap Bridge.  This node will not be able to actually do anything else in the 

    60  * the host using the Linux TAP mechanism.  This write to the device will

    62  * simulation with respect to the Tap Bridge and its bridged net device.  This is 

    61  * then appear to the Linux host as if a packet has arrived on its

    63  * because:

    62  * device.

    64  *

    65  * - Bits sent to the Tap Bridge using its Send() method are completely ignored.  

    66  *   The Tap Bridge is not, itself, connected to any network.

    67  * - The bridged ns-3 net device is has had its receive callback disconnected from

    68  *   the ns-3 node and reconnected to the Tap Bridge.  All data received by a 

    69  *   bridged device will be sent to the Linux host and will not be received by the

    70  *   node.  You can send but you cannot ever receive.

    72  * You will be able to perform typical ns-3 operations on the ghost node if you so

    64  * The upshot is that the Tap Bridge appears to bridge a tap device on a

    73  * desire.  The internet stack, for example, must be there and functional on that

    65  * Linux host in the "real world" to an ns-3 net device in the simulation

    74  * node in order to participate in IP address assignment and global routing.

    66  * and make is appear that a ns-3 net device is actually installed in the

    75  * However, interfaces talking any Tap Bridge or associated bridged net devices 

    67  * Linux host.  In order to do this on the ns-3 side, we need a "ghost

    76  * will not work completely.  If you understand exactly what you are doing, you 

    68  * node" in the simulation to hold the bridged ns-3 net device and the

    77  * can set up other interfaces and devices on the ghost node and use them; but we 

    69  * TapBridge.  This node should not actually do anything else in the

    78  * generally recommend that you treat this node as a ghost of the Linux host and 

    70  * simulation since its job is simply to make the net device appear in

    79  * leave it alone.

    71  * Linux.  This is not just arbitrary policy, it is because:

    72  *

    73  * - Bits sent to the Tap Bridge from higher layers in the ghost node (using

    74  *   the TapBridge Send() method) are completely ignored.  The Tap Bridge is 

    75  *   not, itself, connected to any network, neither in Linux nor in ns-3;

    76  * - The bridged ns-3 net device is has had its receive callback disconnected

    77  *   from the ns-3 node and reconnected to the Tap Bridge.  All data received 

    78  *   by a bridged device will be sent to the Linux host and will not be 

    79  *   received by the node.  From the perspective of the ghost node, you can 

    80  *   send over this device but you cannot ever receive.

    81  *

    82  * Of course, if you understand all of the issues you can take control of

    83  * your own destiny and do whatever you want -- we do not actively

    84  * prevent you from using the ghost node for anything you decide.  You

    85  * will be able to perform typical ns-3 operations on the ghost node if

    86  * you so desire.  The internet stack, for example, must be there and

    87  * functional on that node in order to participate in IP address

    88  * assignment and global routing.  However, as mentioned above,

    89  * interfaces talking any Tap Bridge or associated bridged net devices

    90  * will not work completely.  If you understand exactly what you are

    91  * doing, you can set up other interfaces and devices on the ghost node

    92  * and use them; or take advantage of the operational send side of the

    93  * bridged devices to create traffic generators.  We generally recommend

    94  * that you treat this node as a ghost of the Linux host and leave it to

    95  * itself, though.

   345    * MAC address, but it is not used.  The MAC address assigned to the internet

   387    * MAC address, but it is not used.

   346    * host actually comes from the bridged (N.B. the "ed") device and not from 

   347    * the bridge device.

   389    * The MAC address to use as the hardware address on the host.

   429    * The MAC address to use as the hardware address on the host.  This can

   430    * come from one of two places depending on the operating mode.  

   431    *

   432    * If the TapBridge is in LocalDevice mode, this value comes from the MAC

   433    * address assigned to the bridged ns-3 net device and matches the MAC 

   434    * address of the underlying network TAP which we configured to have the 

   435    * same value.

   436    * 

   437    * If the TapBridge is in BridgedDevice mode, this value is learned from

   438    * from the packets received by the underlying netowrk TAP.  This is

   439    * because we did not configure the TAP, but have got to spoof packets

   440    * destined for there.