blob: 845dd1cde864e0a058ec1dec1394c0e291508e6e [file] [log] [blame]
Alexander Afanasyev4d325162012-06-01 12:28:50 -07001.. ndnSIM: NS-3 based NDN simulator
2.. ============================================================
3
4.. .. toctree::
5.. :maxdepth: 2
6
7Introduction
Alexander Afanasyev5d79e682012-11-19 14:12:23 -08008============
Alexander Afanasyev4d325162012-06-01 12:28:50 -07009
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070010The ndnSIM is NS-3 module that implements Named Data Networking (NDN) communication model, the clean slate Internet design. ndnSIM is specially optimized for simulation purposes and has a cleaner and more extensible internal structure comparing to the existing NDN implementation (Project CCNx).
Alexander Afanasyev4d325162012-06-01 12:28:50 -070011
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070012Following the NDN architecture, ndnSIM is implemented as a new network-layer protocol model, which can run on top of any available link-layer protocol model (point-to-point, CSMA, wireless, etc.).
Alexander Afanasyev4d325162012-06-01 12:28:50 -070013
14.. note::
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070015 It will also be possible to run ndnSIM on top of network-layer (IPv4, IPv6) and transport-layer (TCP, UDP) protocols.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070016 However, it is not yet implemented and patches are welcome.
17
18.. This flexibility allows ndnSIM to simulate scenarios of various homogeneous and heterogeneous networks (e.g., NDN-only, NDN-over-IP, etc.).
19
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070020The simulator is implemented in a modular fashion, using separate C++ classes to model behavior of each network-layer entity in NDN: :ndnsim:`pending Interest table (PIT) <Pit>`, :ndnsim:`forwarding information base (FIB) <Fib>`, :ndnsim:`content store <ContentStore>`, :ndnsim:`network <NetDeviceFace>` and :ndnsim:`application <AppFace>` interfaces, :ndnsim:`Interest forwarding strategies <ForwardingStrategy>`, etc.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070021This modular structure allows any component to be easily modified or replaced with no or minimal impact on other components.
22In addition, the simulator provides an extensive collection of interfaces and helpers to perform detailed tracing behavior of every component, as well as NDN traffic flow.
23
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070024
25.. aafig::
26 :aspect: 60
27 :scale: 120
28
29 +----------------+ +-----------+
30 | "Applications" | | NetDevice |
31 +----------------+ +-----------+
32 ^ ^
33 .................|......................................|......................
34 . v v .
35 . +------------------+ +----------------------+ .
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070036 . | "Face" | | "Face" | .
37 . | "(AppFace)" | | "(NetDeviceFace)" | .
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070038 . +------------------+ +----------------------+ .
39 . ^ ^ .
40 . | | .
41 . v v .
42 . XXXXXXXXXXXXXXXXXXXXXXXXXXXXX .
43 . XX XX .
44 . XX Core NDN protocol XX .
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070045 . XX "(L3Protocol)" XX
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070046 . XX XX .
47 . XXXXXXXXXXXXXXXXXXXXXXXXXXXXX .
48 . ^ ^ ^ ^ .
49 . | | | | .
50 . +-------------------+ +---+ +---+ +------------+ .
51 . | | | | .
52 . v v v v .
53 . +-------------------+ +-------+ +-------+ +-------------+ .
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070054 . | "ContentStore" | | PIT | | FIB | | "Forwarding"| .
55 . +-------------------+ +-------+ +-------+ | "Strategy" | .
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070056 . +-------------+ .
57 . .
58 ...............................................................................
59
60
Alexander Afanasyev4d325162012-06-01 12:28:50 -070061The wire format of Interest and Data packets follows the format of the existing `CCNx Project's NDN implementation`_ (CCNx Binary Encoding), allowing reuse of the existing traffic analysis tools, as well as driving simulations using real NDN traffic traces.
62
63.. _CCNx Project's NDN implementation: http://www.ccnx.org/
64
Alexander Afanasyev4d325162012-06-01 12:28:50 -070065
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080066More documentation
67------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -070068
Alexander Afanasyev5b147e82012-06-22 10:39:46 -070069Overall structure of ndnSIM is described in our `technical report <http://lasr.cs.ucla.edu/afanasyev/data/files/Afanasyev/ndnSIM-TR.pdf>`_.
Alexander Afanasyev4d325162012-06-01 12:28:50 -070070
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070071`ndnSIM API documentation <doxygen/index.html>`_
Alexander Afanasyev4d325162012-06-01 12:28:50 -070072
Alexander Afanasyev9c0794a2012-12-10 01:02:33 -080073Also, you can `join our mailing list <http://www.lists.cs.ucla.edu/mailman/listinfo/ndnsim>`_ to see and participate in discussions about ndnSIM implementation and simulations in general.
74Do not forget to check mailling list `archives <http://www.lists.cs.ucla.edu/pipermail/ndnsim/>`_.
Alexander Afanasyev97fb44d2012-06-04 18:50:47 -070075
Alexander Afanasyev4d325162012-06-01 12:28:50 -070076
Alexander Afanasyev508269a2012-07-28 13:59:54 -070077Support
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -080078-------
Alexander Afanasyev508269a2012-07-28 13:59:54 -070079
80The code of ndnSIM is in active development. Bug reports (issues) as well as new feature implementation are always welcome.
81
82To file a bug report, please use `GitHub Issues <https://github.com/NDN-Routing/ndnSIM/issues>`_.
83
84To create new feature, please fork the code and submit Pull Request on GitHub.
85
Alexander Afanasyev4d325162012-06-01 12:28:50 -070086
87A very short guide to the code
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -070088------------------------------
Alexander Afanasyev4d325162012-06-01 12:28:50 -070089
Alexander Afanasyev6315ef72012-06-01 20:56:31 -070090All the NDN related code is in ``ns-3/src/ndnSIM``
Alexander Afanasyev4d325162012-06-01 12:28:50 -070091
92+-----------------+---------------------------------------------------------------------+
93| Folder | Description |
94+=================+=====================================================================+
Alexander Afanasyevf6807a52012-08-10 18:11:43 -070095| ``model/`` | implementation of NDN base: :ndnsim:`L3Protocol`, faces |
96| | (:ndnsim:`Face`, :ndnsim:`NetDeviceFace`, forwarding |
97| | :ndnsim:`AppFace`), |
98| | strategies (:ndnsim:`ForwardingStrategy`, |
Alexander Afanasyevb8d14ad2012-08-09 13:19:37 -070099| | :ndnsim:`Flooding`, :ndnsim:`SmartFlooding`, :ndnsim:`BestRoute`), |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700100| | etc. |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700101+-----------------+---------------------------------------------------------------------+
102| ``apps/`` | applications (in NS-3 sense) that can be installed on the nodes. |
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700103| | Right now we have one producer (:ndnsim:`Producer`) and a |
104| | collection of consumer (:ndnsim:`ConsumerCbr`, |
105| | :ndnsim:`ConsumerWindow`, |
106| | :ndnsim:`ConsumerBatches`). See doxygen documentation or |
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700107| | source code for details |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700108+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700109| ``helper/`` | a number of :doc:`useful helpers <helpers>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700110+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev6315ef72012-06-01 20:56:31 -0700111| ``examples/`` | contain :doc:`several example scenarios <examples>` |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700112+-----------------+---------------------------------------------------------------------+
Alexander Afanasyev508269a2012-07-28 13:59:54 -0700113| ``utils/`` | helper classes, including implementation of generalized data |
114| | structures |
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700115+-----------------+---------------------------------------------------------------------+
116| ``plugins/`` | a number of plugins that may be helpful to run simulation scenarios |
117+-----------------+---------------------------------------------------------------------+
118
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700119Logging
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800120-------
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700121
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800122Almost every component in ndnSIM exports logging interface, so in debug compilation it is possible to track many internal details.
123For example, logging of :ndnsim:`Face` and :ndnsim:`Consumer` shows everything what happens in :ndnsim:`Face` and :ndnsim:`Consumer` classes::
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700124
Alexander Afanasyevf6807a52012-08-10 18:11:43 -0700125 NS_LOG=ndn.Face:ndn.Consumer ./waf --run=ndn-simple
Alexander Afanasyevd4e97b32012-06-04 15:09:50 -0700126
127Refer to the source code and NS-3 documentation to see what logging interfaces are available and about details how enable one or more logging interfaces.
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700128
Alexander Afanasyeve095f0f2012-11-21 17:43:32 -0800129
Alexander Afanasyev4d325162012-06-01 12:28:50 -0700130.. Indices and tables
131.. ==================
132
133.. * :ref:`genindex`
134.. * :ref:`modindex`
135.. * :ref:`search`
136