unison/doc/howtos/howtos-net-device.h

/*!
  \page net-device How to create a new OSI layer 1 + 2 implementation ?
  \anchor howtos-net-device

  <b>Question:</b> How do I integrate a new OSI layer 1 + 2 implementation ?

  <b>Answer:</b> The OSI layers 1 and 2 are represented by the ns3::NetDevice
  and ns3::Channel classes. To plug transparently in ns-3, a new layer 1+2 model
  thus simply needs to provide two new subclasses of these two base classes.

  To make that subclassing process easy, two skeleton classes are provided in
  the src/node directory: simple-net-device.h (ns3::SimpleNetDevice) and 
  simple-channel.h (ns3::SimpleChannel) implement a broadcast passthru medium 
  using 48bit MAC addresses without any kind of MAC access algorithm or PHY 
  layer modeling.

  The ns3::SimpleChannel class is really very simple: it provides
  an implementation for the ns3::Channel::GetNDevices and ns3::Channel::GetDevice
  methods defined in the Channel base class and, then defines the channel-specific
  send and add methods:
- The Add method is used by SimpleNetDevice::SetChannel to register a new 
  SimpleNetDevice with its associated channel.
- The Send method is used by SimpleNetDevice::Send to send a packet over the
  broadcast medium and ensure that it gets delivered to all associated devices
  (except the sender).

\code
class SimpleChannel : public Channel
{
public:
  static TypeId GetTypeId (void);
  SimpleChannel ();

  void Send (Ptr<Packet> p, uint16_t protocol, Mac48Address to, Mac48Address from,
	     Ptr<SimpleNetDevice> sender);

  void Add (Ptr<SimpleNetDevice> device);

  // inherited from ns3::Channel
  virtual uint32_t GetNDevices (void) const;
  virtual Ptr<NetDevice> GetDevice (uint32_t i) const;

private:
  std::vector<Ptr<SimpleNetDevice> > m_devices;
};
\endcode

The SimpleNetDevice class is also trivial since it implements no special
MAC-layer processing:
\code
class SimpleNetDevice : public NetDevice
{
public:
  static TypeId GetTypeId (void);
  SimpleNetDevice ();

  void Receive (Ptr<Packet> packet, uint16_t protocol, Mac48Address to, Mac48Address from);
  void SetChannel (Ptr<SimpleChannel> channel);
  void SetAddress (Mac48Address address);

  // inherited from NetDevice base class.
  virtual void SetName(const std::string name);
  ...
};
\endcode

The code below illustrates how the three model-specific methods defined above are
implemented:

\code
void 
SimpleNetDevice::Receive (Ptr<Packet> packet, uint16_t protocol, 
			  Mac48Address to, Mac48Address from)
{
  if (to == m_address || to == Mac48Address::GetBroadcast ())
    {
      m_rxCallback (this, packet, protocol, from);
    }
}
void 
SimpleNetDevice::SetChannel (Ptr<SimpleChannel> channel)
{
  m_channel = channel;
  m_channel->Add (this);
}
void 
SimpleNetDevice::SetAddress (Mac48Address address)
{
  m_address = address;
}
\endcode

Building a topology with such a device is then a matter of
instanciating a set of SimpleNetDevice objects connected on a shared
SimpleChannel:
\code
NodeContainer nodes;
nodes.Create (10);
Ptr<SimpleChannel> channel = CreateObject<SimpleChannel> ();
for (uint32_t i = 0; i < nodes.GetN (); ++i)
  {
    CreateSimpleDevice (nodes.Get (i), channel);
  }
\endcode

With the following CreateSimpleDevice function:
\code
static Ptr<SimpleNetDevice>
CreateSimpleDevice (Ptr<Node> node, Ptr<SimpleChannel> channel)
{
  Ptr<SimpleNetDevice> device = CreateObject<SimpleNetDevice> ();
  device->SetAddress (Mac48Address:Allocate ());
  device->SetChannel (channel);
  node->AddDevice (device);
  return device;
}
\endcode

Of course, ultimately, you need to provide a helper class for this new device and channel
to save each user from having to re-implement their own CreateSimpleDevice helper 
function:

\code
class SimpleHelper
{
public:
  NetDeviceContainer Install (NodeContainer nodes, Ptr<SimpleChannel> channel);
  NetDeviceContainer Install (NodeContainer nodes);
};
\endcode

with the following straightforward implementation, inspired by the CreateSimpleDevice 
function defined above:

\code
NetDeviceContainer
SimpleHelper::Install (NodeContainer nodes, Ptr<SimpleChannel> channel)
{
  NetDeviceContainer devices;
  for (NodeContainer::Iterator i = nodes.Begin (); i != nodes.End (); ++i)
    {
      Ptr<SimpleNetDevice> dev = CreateObject<SimpleNetDevice> ();
      dev->SetAddress (Mac48Address::Allocate ());
      dev->SetChannel (channel);
      (*i)->AddDevice (dev);
      devices.Add (dev);
    }
  return devices;
}
NetDeviceContainer
SimpleHelper::Install (NodeContainer nodes)
{
  return Install (nodes, CreateObject<SimpleChannel> ());
}
\endcode

Of course, at some point, this device helper class should also contain a couple of 
ascii and pcap tracing helper functions but, since the default SimpleNetDevice
class we used as an example here does not report any trace event, it would
be of little use.

*/