1.1 --- a/src/devices/emu/emu.h	Thu Oct 30 10:01:27 2008 -0700
     1.2 +++ b/src/devices/emu/emu.h	Thu Oct 30 10:30:33 2008 -0700
     1.3 @@ -4,7 +4,58 @@
     1.4   *
     1.5   * \section Emulated Net Device Model
     1.6   *
     1.7 - * This is a description of the emulated network device model.
     1.8 + * The emulated net device allows a simulation node to talk to a real network
     1.9 + * and send and receive packets that are processed by the corresponding ns-3
    1.10 + * node.
    1.11   *
    1.12 - * It is very detailed and comprehensive and answers all possible questions.
    1.13 + * The emulated net device relies on a specified interface being in promiscuous
    1.14 + * mode.  It opens a raw socket and binds to that interface.  We perform MAC
    1.15 + * spoofing to separate simulation network traffic from other network traffic
    1.16 + * that may be flowing to and from the host.
    1.17 + *
    1.18 + * Normally, the use case for emulated net devices is in collections of
    1.19 + * small simulations that connect to the outside world through specific 
    1.20 + * interfaces.  For example, one could construct a number of virtual
    1.21 + * machines and connect them via a host-only network.  To use the emulated
    1.22 + * net device, you would need to set all of the host-only interfaces in
    1.23 + * promiscuous mode and provide an appropriate device name, "eth1" for example.
    1.24 + *
    1.25 + * One could also use the emulated net device in a testbed situation
    1.26 + * where the host on which the simulation is running has a specific interface
    1.27 + * of interest which drives the testbed hardware.  You would also need to set 
    1.28 + * this specific interface into promiscuous mode and provide an appropriate 
    1.29 + * device name to the ns-3 emulated net device.
    1.30 + *
    1.31 + * The emulated net device only works if the underlying interface is up in 
    1.32 + * promiscuous mode.  We could just turn it on, but the situation is that we 
    1.33 + * expect the other considerations listed above to have been dealt with.
    1.34 + * To verify that these issues are dealt with, we just make sure that the end 
    1.35 + * result of that process has taken place and that the specified interface is
    1.36 + * in promiscuous mode.
    1.37 + *
    1.38 + * Packets will be sent out over the device, but we use MAC spoofing.  The
    1.39 + * MAC addresses will be generated using the Organizationally Unique Identifier
    1.40 + * (OUI) 00:00:00 as a base.  This vendor code is not assigned to any 
    1.41 + * organization and so should not conflict with any real hardware.  
    1.42 +
    1.43 + * It is always up to you to determine that using these MAC addresses is
    1.44 + * okay on your network and won't conflict with anything else (including another
    1.45 + * simulation using emu devices) on your network.  If you are using the 
    1.46 + * emulated net device in separate simulations you must consider global MAC 
    1.47 + * address assignment issues and ensure that MAC addresses are unique across
    1.48 + * all simulations.  The emulated net device respects the MAC address provided
    1.49 + * in the SetAddress method so you can do this manually.  For larger simulations,
    1.50 + * you may want to set the OUI in the MAC address allocation function.
    1.51 + *
    1.52 + * IP addresses corresponding to the emulated net devices are the addresses 
    1.53 + * generated in the simulation, which are generated in the usual way via helper
    1.54 + * functions.
    1.55 + *
    1.56 + * The emulated net device comes with a helper function as all ns-3 devices do.
    1.57 + * One unique aspect is that there is no channel associated with the underlying
    1.58 + * medium.  We really have no idea what this medium is, and so have not made an
    1.59 + * effort to model it abstractly.  The primary thing to be aware of is the 
    1.60 + * implication this has for static global routing.  The global router module
    1.61 + * attempts to walk the channels looking for adjacent networks.  Since there 
    1.62 + * is no channel, the global router will be unable to do this.
    1.63   */