From b6a5ee8151d63ffbe03f338a7e408cc556eb7330 Mon Sep 17 00:00:00 2001 From: Tom Henderson Date: Sun, 5 Jun 2022 21:01:11 -0700 Subject: [PATCH] Run utils/trim-trailing-whitespace.py on codebase --- CHANGES.md | 2 +- build-support/empty-main.cc | 2 +- build-support/pybindings-LP64-to-ILP32.py | 2 +- doc/build.txt | 2 +- doc/contributing.txt | 4 +- doc/contributing/pickle-to-xml.py | 8 +- doc/contributing/source/coding-style.rst | 6 +- doc/contributing/source/enhancements.rst | 18 +- doc/contributing/source/external.rst | 12 +- doc/contributing/source/general.rst | 32 +- doc/contributing/source/introduction.rst | 12 +- doc/contributing/source/models.rst | 22 +- doc/main.h | 22 +- doc/manual/Makefile | 6 +- doc/manual/source/attributes.rst | 4 +- doc/manual/source/callbacks.rst | 100 +- doc/manual/source/conf.py | 4 +- doc/manual/source/documentation.rst | 32 +- doc/manual/source/enable-modules.rst | 20 +- doc/manual/source/enable-tests.rst | 28 +- doc/manual/source/events.rst | 82 +- doc/manual/source/gnuplot.rst | 38 +- doc/manual/source/hash-functions.rst | 4 +- doc/manual/source/how-to-write-tests.rst | 12 +- doc/manual/source/logging.rst | 32 +- doc/manual/source/new-models.rst | 54 +- doc/manual/source/new-modules.rst | 46 +- doc/manual/source/object-model.rst | 30 +- doc/manual/source/organization.rst | 20 +- doc/manual/source/profiling.rst | 266 +-- doc/manual/source/python.rst | 76 +- doc/manual/source/random-variables.rst | 56 +- doc/manual/source/realtime.rst | 8 +- doc/manual/source/test-background.rst | 146 +- doc/manual/source/test-overview.rst | 6 +- doc/manual/source/tracing.rst | 70 +- doc/manual/source/troubleshoot.rst | 14 +- doc/manual/source/utilities.rst | 16 +- doc/manual/source/working-with-git.rst | 18 +- .../source/working-with-gitlab-ci-local.rst | 82 +- doc/models/Makefile | 16 +- doc/models/source/conf.py | 4 +- doc/models/source/emulation-overview.rst | 4 +- doc/models/source/index.rst | 4 +- doc/models/source/organization.rst | 18 +- doc/ns3_html_theme/get_version.sh | 12 +- doc/ns3_html_theme/layout.html | 28 +- doc/ns3_html_theme/ns3_doxy_header.html | 14 +- doc/ns3_html_theme/static/drop-down-menu.js | 24 +- doc/ns3_html_theme/static/ns3_stylesheet.css | 6 +- doc/release_steps.txt | 18 +- doc/tutorial/pickle-to-xml.py | 8 +- doc/tutorial/source/building-topologies.rst | 398 ++-- doc/tutorial/source/conceptual-overview.rst | 402 ++-- doc/tutorial/source/conclusion.rst | 6 +- doc/tutorial/source/conf.py | 4 +- doc/tutorial/source/data-collection.rst | 88 +- doc/tutorial/source/getting-started.rst | 198 +- doc/tutorial/source/introduction.rst | 72 +- doc/tutorial/source/quick-start.rst | 12 +- doc/tutorial/source/resources.rst | 54 +- doc/tutorial/source/tracing.rst | 124 +- doc/tutorial/source/tweaking.rst | 358 ++-- .../three-gpp-v2v-channel-example.sh | 6 +- examples/energy/energy-model-example.cc | 2 +- .../energy-model-with-harvesting-example.cc | 2 +- examples/error-model/simple-error-model.cc | 14 +- examples/ipv6/examples-to-run.py | 2 +- examples/ipv6/fragmentation-ipv6-two-MTU.cc | 2 +- examples/ipv6/fragmentation-ipv6.cc | 2 +- examples/ipv6/icmpv6-redirect.cc | 2 +- examples/ipv6/ping6.cc | 4 +- examples/ipv6/radvd-two-prefix.cc | 2 +- examples/ipv6/radvd.cc | 2 +- examples/ipv6/test-ipv6.cc | 2 +- examples/ipv6/wsn-ping6.cc | 2 +- examples/matrix-topology/adjacency_matrix.txt | 2 +- examples/matrix-topology/matrix-topology.cc | 6 +- examples/matrix-topology/node_coordinates.txt | 2 +- examples/naming/object-names.cc | 24 +- examples/realtime/realtime-udp-echo.cc | 6 +- examples/realtime/realtime-udp-echo.py | 2 +- examples/routing/dynamic-global-routing.cc | 10 +- examples/routing/global-injection-slash32.cc | 6 +- ...global-routing-multi-switch-plus-router.cc | 2 +- examples/routing/global-routing-slash32.cc | 6 +- examples/routing/manet-routing-compare.cc | 2 +- examples/routing/mixed-global-routing.cc | 4 +- examples/routing/simple-alternate-routing.cc | 20 +- examples/routing/simple-global-routing.cc | 12 +- examples/routing/simple-multicast-flooding.cc | 8 +- examples/routing/simple-routing-ping6.cc | 4 +- examples/routing/simple-routing-ping6.py | 8 +- examples/routing/static-routing-slash32.cc | 6 +- .../socket/socket-bound-static-routing.cc | 12 +- .../socket/socket-bound-tcp-static-routing.cc | 10 +- examples/socket/socket-options-ipv4.cc | 10 +- examples/socket/socket-options-ipv6.cc | 10 +- examples/stats/wifi-example-apps.cc | 14 +- examples/stats/wifi-example-apps.h | 4 +- examples/stats/wifi-example-sim.cc | 4 +- examples/tcp/star.cc | 4 +- examples/tcp/tcp-large-transfer.cc | 12 +- examples/tcp/tcp-star-server.cc | 4 +- examples/tcp/tcp-validation.cc | 4 +- examples/tcp/tcp-variants-comparison.cc | 2 +- examples/traffic-control/cobalt-vs-codel.cc | 2 +- examples/traffic-control/traffic-control.cc | 2 +- examples/tutorial/fifth.cc | 16 +- examples/tutorial/first.cc | 4 +- examples/tutorial/second.cc | 2 +- examples/tutorial/sixth.cc | 2 +- examples/tutorial/third.cc | 4 +- examples/tutorial/third.py | 8 +- examples/udp/udp-echo.cc | 4 +- examples/wireless/mixed-wired-wireless.py | 198 +- examples/wireless/wifi-adhoc.cc | 4 +- examples/wireless/wifi-aggregation.cc | 4 +- examples/wireless/wifi-clear-channel-cmu.cc | 4 +- .../wireless/wifi-error-models-comparison.cc | 2 +- examples/wireless/wifi-multirate.cc | 36 +- .../wifi-power-adaptation-distance.cc | 24 +- .../wifi-power-adaptation-interference.cc | 36 +- examples/wireless/wifi-simple-infra.cc | 4 +- examples/wireless/wifi-txop-aggregation.cc | 4 +- scratch/scratch-simulator.cc | 2 +- scratch/subdir/scratch-simulator-subdir.cc | 2 +- src/antenna/doc/Makefile | 6 +- src/antenna/doc/source/antenna-design.rst | 2 +- src/antenna/doc/source/antenna-testing.rst | 6 +- src/antenna/model/angles.h | 62 +- src/antenna/model/antenna-model.h | 14 +- src/antenna/model/cosine-antenna-model.cc | 2 +- src/antenna/model/cosine-antenna-model.h | 2 +- src/antenna/model/isotropic-antenna-model.cc | 4 +- src/antenna/model/isotropic-antenna-model.h | 8 +- src/antenna/model/parabolic-antenna-model.cc | 10 +- src/antenna/model/parabolic-antenna-model.h | 2 +- src/antenna/test/test-cosine-antenna.cc | 10 +- src/antenna/test/test-degrees-radians.cc | 2 +- src/antenna/test/test-parabolic-antenna.cc | 8 +- src/aodv/doc/aodv.h | 4 +- src/aodv/doc/aodv.rst | 70 +- src/aodv/examples/aodv.cc | 14 +- src/aodv/helper/aodv-helper.cc | 12 +- src/aodv/model/aodv-id-cache.h | 2 +- src/aodv/model/aodv-neighbor.h | 2 +- src/aodv/model/aodv-routing-protocol.h | 6 +- src/aodv/model/aodv-rqueue.h | 4 +- src/applications/doc/applications.rst | 68 +- src/applications/helper/bulk-send-helper.h | 2 +- src/applications/helper/on-off-helper.cc | 4 +- src/applications/helper/on-off-helper.h | 12 +- src/applications/helper/packet-sink-helper.cc | 2 +- src/applications/helper/packet-sink-helper.h | 4 +- src/applications/helper/udp-echo-helper.cc | 8 +- src/applications/helper/udp-echo-helper.h | 18 +- .../model/bulk-send-application.cc | 2 +- .../model/bulk-send-application.h | 20 +- src/applications/model/onoff-application.cc | 6 +- src/applications/model/onoff-application.h | 10 +- src/applications/model/packet-sink.cc | 8 +- src/applications/model/packet-sink.h | 16 +- src/applications/model/seq-ts-echo-header.h | 2 +- src/applications/model/seq-ts-header.h | 2 +- .../model/three-gpp-http-variables.cc | 2 +- .../model/three-gpp-http-variables.h | 2 +- src/applications/model/udp-echo-client.cc | 38 +- src/applications/model/udp-echo-client.h | 22 +- src/applications/model/udp-echo-server.cc | 12 +- src/applications/model/udp-echo-server.h | 6 +- .../test/bulk-send-application-test-suite.cc | 4 +- src/bridge/doc/bridge.rst | 2 +- src/bridge/examples/csma-bridge-one-hop.cc | 22 +- src/bridge/examples/csma-bridge.cc | 16 +- src/bridge/examples/csma-bridge.py | 16 +- src/bridge/helper/bridge-helper.cc | 2 +- src/bridge/model/bridge-channel.cc | 2 +- src/bridge/model/bridge-channel.h | 2 +- src/bridge/model/bridge-net-device.cc | 46 +- src/bridge/model/bridge-net-device.h | 6 +- src/brite/doc/brite.rst | 88 +- src/brite/examples/conf_files/ASBarabasi.conf | 4 +- src/brite/examples/conf_files/ASWaxman.conf | 4 +- src/brite/examples/conf_files/RTBarabasi.conf | 4 +- .../examples/conf_files/RTBarabasi10.conf | 4 +- .../examples/conf_files/RTBarabasi20.conf | 4 +- .../examples/conf_files/RTBarabasi5.conf | 4 +- src/brite/examples/conf_files/RTWaxman.conf | 4 +- src/brite/examples/conf_files/RTWaxman10.conf | 4 +- src/brite/examples/conf_files/RTWaxman20.conf | 4 +- src/brite/examples/conf_files/RTWaxman5.conf | 4 +- .../conf_files/TD_ASBarabasi_RTWaxman.conf | 4 +- src/brite/test/brite-test-topology.cc | 6 +- src/brite/test/test.conf | 4 +- src/buildings/doc/Makefile | 8 +- src/buildings/doc/source/buildings-design.rst | 44 +- src/buildings/doc/source/buildings-user.rst | 8 +- src/buildings/doc/source/conf.py | 2 +- .../examples/buildings-pathloss-profiler.cc | 30 +- .../outdoor-group-mobility-animate.sh | 6 +- .../outdoor-group-mobility-example.cc | 16 +- .../outdoor-random-walk-example-animate.sh | 4 +- .../examples/outdoor-random-walk-example.cc | 4 +- src/buildings/helper/building-allocator.cc | 10 +- src/buildings/helper/building-allocator.h | 14 +- src/buildings/helper/building-container.cc | 18 +- src/buildings/helper/building-container.h | 18 +- .../helper/building-position-allocator.cc | 10 +- .../helper/building-position-allocator.h | 34 +- src/buildings/model/building-list.cc | 12 +- src/buildings/model/building.cc | 40 +- src/buildings/model/building.h | 62 +- .../buildings-channel-condition-model.cc | 6 +- .../model/buildings-propagation-loss-model.cc | 14 +- .../model/buildings-propagation-loss-model.h | 12 +- ...hybrid-buildings-propagation-loss-model.cc | 14 +- .../hybrid-buildings-propagation-loss-model.h | 34 +- .../itu-r-1238-propagation-loss-model.cc | 4 +- .../model/itu-r-1238-propagation-loss-model.h | 14 +- src/buildings/model/mobility-building-info.cc | 6 +- src/buildings/model/mobility-building-info.h | 26 +- .../oh-buildings-propagation-loss-model.cc | 8 +- .../oh-buildings-propagation-loss-model.h | 6 +- .../random-walk-2d-outdoor-mobility-model.cc | 2 +- .../random-walk-2d-outdoor-mobility-model.h | 2 +- .../test/building-position-allocator-test.cc | 18 +- .../buildings-channel-condition-model-test.cc | 2 +- src/buildings/test/buildings-helper-test.cc | 28 +- src/buildings/test/buildings-pathloss-test.cc | 12 +- src/buildings/test/buildings-pathloss-test.h | 2 +- .../test/buildings-shadowing-test.cc | 20 +- src/buildings/test/buildings-shadowing-test.h | 8 +- .../test/outdoor-random-walk-test.cc | 4 +- .../test/reference/buildings_pathloss.m | 2 +- src/buildings/test/reference/loss_ITU1238.m | 4 +- ...ee-gpp-v2v-channel-condition-model-test.cc | 4 +- src/click/doc/click.rst | 14 +- src/click/examples/nsclick-defines.cc | 2 +- .../nsclick-lan-single-interface.click | 8 +- .../examples/nsclick-routing-node0.click | 8 +- .../examples/nsclick-routing-node2.click | 8 +- ...sclick-wifi-single-interface-promisc.click | 8 +- .../nsclick-wifi-single-interface.click | 8 +- src/click/model/ipv4-click-routing.cc | 4 +- .../examples/config-store-save.cc | 12 +- .../model/attribute-default-iterator.cc | 14 +- .../model/attribute-default-iterator.h | 4 +- src/config-store/model/attribute-iterator.cc | 42 +- src/config-store/model/attribute-iterator.h | 12 +- src/config-store/model/config-store.cc | 20 +- src/config-store/model/config-store.h | 4 +- src/config-store/model/display-functions.h | 18 +- src/config-store/model/file-config.cc | 6 +- src/config-store/model/gtk-config-store.cc | 10 +- src/config-store/model/gtk-config-store.h | 4 +- src/config-store/model/model-node-creator.cc | 22 +- src/config-store/model/model-node-creator.h | 2 +- .../model/model-typeid-creator.cc | 8 +- src/config-store/model/model-typeid-creator.h | 2 +- src/config-store/model/raw-text-config.cc | 6 +- src/config-store/model/raw-text-config.h | 4 +- src/config-store/model/xml-config.cc | 26 +- src/core/doc/core.h | 10 +- src/core/doc/deprecated-example.h | 2 +- .../empirical-random-variable-example.cc | 18 +- src/core/examples/fatal-example.cc | 6 +- src/core/examples/sample-rng-plot.py | 2 +- src/core/examples/sample-simulator.cc | 2 +- src/core/examples/sample-simulator.py | 4 +- src/core/helper/csv-reader.h | 2 +- src/core/helper/event-garbage-collector.h | 4 +- .../helper/random-variable-stream-helper.h | 2 +- src/core/model/command-line.cc | 8 +- src/core/model/config.h | 8 +- src/core/model/default-simulator-impl.cc | 2 +- src/core/model/deprecated.h | 6 +- src/core/model/event-id.h | 2 +- src/core/model/example-as-test.h | 8 +- src/core/model/hash-fnv.cc | 6 +- src/core/model/hash-murmur3.cc | 8 +- src/core/model/int64x64-128.h | 2 +- src/core/model/int64x64-cairo.h | 2 +- src/core/model/int64x64-double.h | 4 +- src/core/model/names.cc | 2 +- src/core/model/nstime.h | 20 +- src/core/model/object-base.cc | 10 +- src/core/model/pair.h | 20 +- src/core/model/priority-queue-scheduler.h | 2 +- src/core/model/random-variable-stream.cc | 12 +- src/core/model/random-variable-stream.h | 2 +- src/core/model/realtime-simulator-impl.cc | 4 +- src/core/model/rng-stream.cc | 4 +- src/core/model/show-progress.cc | 6 +- src/core/model/show-progress.h | 6 +- src/core/model/simulator-impl.h | 2 +- src/core/model/system-wall-clock-timestamp.cc | 6 +- src/core/model/system-wall-clock-timestamp.h | 8 +- src/core/model/time.cc | 6 +- src/core/model/timer.cc | 2 +- src/core/model/tuple.h | 6 +- src/core/model/valgrind.h | 56 +- src/core/model/version.cc | 4 +- src/core/model/version.h | 24 +- src/core/test/attribute-test-suite.cc | 36 +- src/core/test/callback-test-suite.cc | 20 +- src/core/test/command-line-test-suite.cc | 4 +- src/core/test/examples-as-tests-test-suite.cc | 6 +- src/core/test/int64x64-test-suite.cc | 46 +- src/core/test/pair-value-test-suite.cc | 10 +- .../test/random-variable-stream-test-suite.cc | 60 +- src/core/test/rng-test-suite.cc | 14 +- src/core/test/simulator-test-suite.cc | 14 +- src/core/test/threaded-test-suite.cc | 10 +- src/core/test/time-test-suite.cc | 74 +- src/core/test/timer-test-suite.cc | 6 +- src/core/test/traced-callback-test-suite.cc | 4 +- src/core/test/type-id-test-suite.cc | 16 +- src/csma-layout/examples/csma-star.cc | 14 +- src/csma-layout/model/csma-star-helper.cc | 10 +- src/csma-layout/model/csma-star-helper.h | 18 +- src/csma/doc/csma.rst | 10 +- src/csma/examples/csma-broadcast.cc | 14 +- src/csma/examples/csma-multicast.cc | 22 +- src/csma/examples/csma-one-subnet.cc | 16 +- src/csma/examples/csma-packet-socket.cc | 8 +- src/csma/examples/csma-ping.cc | 2 +- src/csma/examples/csma-raw-ip-socket.cc | 6 +- src/csma/helper/csma-helper.cc | 34 +- src/csma/helper/csma-helper.h | 32 +- src/csma/model/backoff.cc | 12 +- src/csma/model/backoff.h | 4 +- src/csma/model/csma-channel.cc | 42 +- src/csma/model/csma-channel.h | 8 +- src/csma/model/csma-net-device.cc | 124 +- src/csma/model/csma-net-device.h | 70 +- src/dsdv/doc/dsdv.h | 2 +- src/dsdv/doc/dsdv.rst | 4 +- src/dsdv/model/dsdv-packet-queue.h | 2 +- src/dsr/doc/dsr.rst | 98 +- src/dsr/helper/dsr-helper.h | 2 +- src/dsr/model/dsr-errorbuff.h | 4 +- src/dsr/model/dsr-rreq-table.cc | 2 +- src/energy/doc/energy.rst | 10 +- src/energy/examples/li-ion-energy-source.cc | 2 +- src/energy/examples/rv-battery-model-test.cc | 4 +- .../helper/basic-energy-harvester-helper.cc | 4 +- .../helper/basic-energy-harvester-helper.h | 4 +- .../helper/energy-harvester-container.h | 4 +- src/energy/helper/energy-harvester-helper.cc | 4 +- src/energy/helper/energy-harvester-helper.h | 2 +- .../helper/li-ion-energy-source-helper.cc | 4 +- src/energy/model/basic-energy-harvester.cc | 2 +- src/energy/model/energy-harvester.cc | 2 +- src/energy/model/energy-harvester.h | 6 +- src/energy/model/energy-source.cc | 12 +- src/energy/model/energy-source.h | 10 +- src/energy/model/li-ion-energy-source.cc | 6 +- src/energy/model/li-ion-energy-source.h | 2 +- src/energy/model/rv-battery-model.h | 2 +- src/fd-net-device/doc/dpdk-net-device.rst | 2 +- src/fd-net-device/doc/fd-net-device.rst | 160 +- src/fd-net-device/doc/netmap-net-device.rst | 30 +- src/fd-net-device/examples/dummy-network.cc | 2 +- src/fd-net-device/examples/fd-emu-send.cc | 4 +- src/fd-net-device/examples/fd-emu-tc.cc | 6 +- src/fd-net-device/examples/fd-emu-udp-echo.cc | 18 +- src/fd-net-device/examples/fd-tap-ping6.cc | 16 +- src/fd-net-device/examples/fd2fd-onoff.cc | 20 +- .../examples/realtime-fd2fd-onoff.cc | 20 +- .../helper/tap-device-creator.cc | 24 +- src/fd-net-device/model/fd-net-device.h | 2 +- .../examples/flowmon-parse-results.py | 18 +- .../examples/wifi-olsr-flowmon.py | 10 +- .../helper/flow-monitor-helper.cc | 2 +- src/flow-monitor/model/flow-monitor.cc | 6 +- src/flow-monitor/model/flow-probe.cc | 4 +- src/flow-monitor/model/flow-probe.h | 4 +- src/flow-monitor/model/ipv4-flow-probe.cc | 22 +- src/flow-monitor/model/ipv4-flow-probe.h | 4 +- src/flow-monitor/model/ipv6-flow-probe.cc | 24 +- src/flow-monitor/model/ipv6-flow-probe.h | 2 +- src/internet-apps/doc/internet-apps.rst | 20 +- src/internet-apps/helper/v4ping-helper.cc | 2 +- src/internet-apps/helper/v4ping-helper.h | 2 +- src/internet-apps/model/ping6.cc | 18 +- src/internet-apps/model/radvd-interface.cc | 2 +- src/internet-apps/model/radvd-interface.h | 8 +- src/internet-apps/model/radvd-prefix.cc | 2 +- src/internet-apps/model/radvd-prefix.h | 4 +- src/internet-apps/model/radvd.cc | 6 +- src/internet-apps/model/v4ping.cc | 12 +- src/internet-apps/model/v4ping.h | 4 +- src/internet/doc/internet-stack.rst | 28 +- src/internet/doc/ipv4.rst | 20 +- src/internet/doc/ipv6.rst | 92 +- src/internet/doc/routing-overview.rst | 86 +- src/internet/doc/tcp.rst | 104 +- src/internet/doc/udp.rst | 6 +- src/internet/examples/main-simple.cc | 2 +- src/internet/helper/internet-stack-helper.cc | 184 +- src/internet/helper/internet-stack-helper.h | 48 +- src/internet/helper/internet-trace-helper.cc | 100 +- src/internet/helper/internet-trace-helper.h | 108 +- src/internet/helper/ipv4-address-helper.cc | 10 +- src/internet/helper/ipv4-address-helper.h | 6 +- .../helper/ipv4-global-routing-helper.cc | 4 +- .../helper/ipv4-global-routing-helper.h | 4 +- .../helper/ipv4-interface-container.cc | 6 +- .../helper/ipv4-interface-container.h | 28 +- .../helper/ipv4-list-routing-helper.cc | 10 +- .../helper/ipv4-list-routing-helper.h | 8 +- src/internet/helper/ipv4-routing-helper.h | 28 +- .../helper/ipv4-static-routing-helper.cc | 32 +- .../helper/ipv4-static-routing-helper.h | 22 +- src/internet/helper/ipv6-address-helper.cc | 6 +- src/internet/helper/ipv6-address-helper.h | 22 +- .../helper/ipv6-interface-container.h | 10 +- .../helper/ipv6-list-routing-helper.cc | 10 +- .../helper/ipv6-list-routing-helper.h | 8 +- src/internet/helper/ipv6-routing-helper.h | 14 +- .../helper/ipv6-static-routing-helper.cc | 38 +- .../helper/ipv6-static-routing-helper.h | 12 +- src/internet/model/arp-cache.h | 8 +- src/internet/model/arp-header.h | 2 +- src/internet/model/arp-l3-protocol.cc | 62 +- src/internet/model/candidate-queue.cc | 10 +- src/internet/model/candidate-queue.h | 26 +- .../model/global-route-manager-impl.cc | 354 ++-- .../model/global-route-manager-impl.h | 128 +- src/internet/model/global-route-manager.cc | 4 +- src/internet/model/global-route-manager.h | 6 +- src/internet/model/global-router-interface.cc | 172 +- src/internet/model/global-router-interface.h | 86 +- src/internet/model/global-routing.h | 22 +- src/internet/model/icmpv4-l4-protocol.cc | 22 +- src/internet/model/icmpv4-l4-protocol.h | 2 +- src/internet/model/icmpv4.cc | 74 +- src/internet/model/icmpv6-header.cc | 28 +- src/internet/model/icmpv6-header.h | 2 +- src/internet/model/icmpv6-l4-protocol.cc | 4 +- src/internet/model/ip-l4-protocol.cc | 2 +- src/internet/model/ipv4-address-generator.cc | 36 +- src/internet/model/ipv4-address-generator.h | 2 +- src/internet/model/ipv4-end-point-demux.cc | 46 +- src/internet/model/ipv4-end-point-demux.h | 12 +- src/internet/model/ipv4-end-point.cc | 30 +- src/internet/model/ipv4-end-point.h | 6 +- src/internet/model/ipv4-global-routing.cc | 116 +- src/internet/model/ipv4-global-routing.h | 26 +- src/internet/model/ipv4-header.cc | 64 +- src/internet/model/ipv4-header.h | 4 +- src/internet/model/ipv4-interface-address.cc | 28 +- src/internet/model/ipv4-interface-address.h | 8 +- src/internet/model/ipv4-interface.cc | 34 +- src/internet/model/ipv4-interface.h | 20 +- src/internet/model/ipv4-l3-protocol.cc | 122 +- src/internet/model/ipv4-l3-protocol.h | 16 +- src/internet/model/ipv4-list-routing.cc | 36 +- src/internet/model/ipv4-list-routing.h | 12 +- src/internet/model/ipv4-packet-filter.cc | 2 +- src/internet/model/ipv4-packet-info-tag.cc | 18 +- src/internet/model/ipv4-packet-info-tag.h | 6 +- .../model/ipv4-raw-socket-factory-impl.cc | 2 +- src/internet/model/ipv4-raw-socket-factory.h | 4 +- src/internet/model/ipv4-raw-socket-impl.cc | 52 +- src/internet/model/ipv4-raw-socket-impl.h | 4 +- src/internet/model/ipv4-route.cc | 14 +- src/internet/model/ipv4-route.h | 14 +- src/internet/model/ipv4-routing-protocol.h | 22 +- .../model/ipv4-routing-table-entry.cc | 50 +- src/internet/model/ipv4-routing-table-entry.h | 32 +- src/internet/model/ipv4-static-routing.cc | 140 +- src/internet/model/ipv4-static-routing.h | 52 +- src/internet/model/ipv4.cc | 8 +- src/internet/model/ipv4.h | 70 +- .../model/ipv6-autoconfigured-prefix.cc | 4 +- .../model/ipv6-autoconfigured-prefix.h | 6 +- src/internet/model/ipv6-end-point.cc | 2 +- src/internet/model/ipv6-extension-header.cc | 30 +- src/internet/model/ipv6-extension-header.h | 4 +- src/internet/model/ipv6-interface-address.cc | 4 +- src/internet/model/ipv6-interface-address.h | 2 +- src/internet/model/ipv6-interface.cc | 4 +- src/internet/model/ipv6-interface.h | 6 +- src/internet/model/ipv6-l3-protocol.cc | 14 +- src/internet/model/ipv6-l3-protocol.h | 24 +- src/internet/model/ipv6-option-header.cc | 16 +- src/internet/model/ipv6-option-header.h | 2 +- src/internet/model/ipv6-option.h | 2 +- src/internet/model/ipv6-packet-filter.cc | 2 +- src/internet/model/ipv6-packet-info-tag.cc | 26 +- src/internet/model/ipv6-packet-info-tag.h | 6 +- src/internet/model/ipv6-queue-disc-item.h | 2 +- src/internet/model/ipv6-raw-socket-factory.h | 8 +- src/internet/model/ipv6-raw-socket-impl.cc | 8 +- src/internet/model/ipv6-raw-socket-impl.h | 2 +- src/internet/model/ipv6-routing-protocol.cc | 2 +- src/internet/model/ipv6-routing-protocol.h | 20 +- .../model/ipv6-routing-table-entry.cc | 4 +- src/internet/model/ipv6-routing-table-entry.h | 6 +- src/internet/model/ipv6.cc | 6 +- src/internet/model/ipv6.h | 48 +- src/internet/model/loopback-net-device.cc | 50 +- src/internet/model/loopback-net-device.h | 2 +- src/internet/model/ndisc-cache.cc | 4 +- src/internet/model/ndisc-cache.h | 2 +- src/internet/model/pending-data.cc | 6 +- src/internet/model/pending-data.h | 16 +- src/internet/model/rtt-estimator.cc | 28 +- src/internet/model/rtt-estimator.h | 10 +- src/internet/model/tcp-bbr.cc | 18 +- src/internet/model/tcp-bbr.h | 4 +- src/internet/model/tcp-htcp.h | 4 +- src/internet/model/tcp-l4-protocol.h | 2 +- src/internet/model/tcp-linux-reno.cc | 2 +- src/internet/model/tcp-linux-reno.h | 2 +- src/internet/model/tcp-prr-recovery.cc | 2 +- src/internet/model/tcp-recovery-ops.cc | 2 +- src/internet/model/tcp-socket-base.cc | 6 +- src/internet/model/tcp-socket-factory-impl.cc | 2 +- src/internet/model/tcp-socket-factory.h | 6 +- src/internet/model/tcp-socket.h | 2 +- src/internet/model/tcp-westwood.cc | 2 +- src/internet/model/tcp-westwood.h | 14 +- src/internet/model/udp-header.cc | 26 +- src/internet/model/udp-header.h | 10 +- src/internet/model/udp-l4-protocol.cc | 38 +- src/internet/model/udp-l4-protocol.h | 8 +- src/internet/model/udp-socket-factory-impl.cc | 2 +- src/internet/model/udp-socket-factory-impl.h | 2 +- src/internet/model/udp-socket-factory.h | 4 +- src/internet/model/udp-socket-impl.cc | 74 +- src/internet/model/udp-socket-impl.h | 6 +- src/internet/model/udp-socket.h | 4 +- .../global-route-manager-impl-test-suite.cc | 10 +- .../test/ipv4-address-generator-test-suite.cc | 8 +- .../test/ipv4-address-helper-test-suite.cc | 4 +- src/internet/test/ipv4-deduplication-test.cc | 28 +- src/internet/test/ipv4-fragmentation-test.cc | 4 +- .../test/ipv4-global-routing-test-suite.cc | 80 +- src/internet/test/ipv4-raw-test.cc | 4 +- src/internet/test/ipv4-rip-test.cc | 2 +- .../test/ipv4-static-routing-test-suite.cc | 2 +- src/internet/test/ipv4-test.cc | 6 +- .../test/ipv6-address-duplication-test.cc | 2 +- .../test/ipv6-address-helper-test-suite.cc | 8 +- src/internet/test/ipv6-forwarding-test.cc | 2 +- src/internet/test/ipv6-raw-test.cc | 4 +- src/internet/test/ipv6-ripng-test.cc | 2 +- src/internet/test/ipv6-test.cc | 12 +- src/internet/test/rtt-test.cc | 2 +- .../test/tcp-advertised-window-test.cc | 8 +- src/internet/test/tcp-close-test.cc | 2 +- src/internet/test/tcp-general-test.h | 4 +- src/internet/test/tcp-htcp-test.cc | 8 +- src/internet/test/tcp-loss-test.cc | 8 +- src/internet/test/udp-test.cc | 10 +- src/lr-wpan/doc/lr-wpan.rst | 58 +- src/lr-wpan/examples/lr-wpan-phy-test.cc | 2 +- src/lr-wpan/helper/lr-wpan-helper.h | 4 +- src/lr-wpan/model/lr-wpan-lqi-tag.h | 6 +- src/lte/doc/Makefile | 12 +- src/lte/doc/source/conf.py | 2 +- .../source/figures/ca-downlink-bsr.seqdiag | 4 +- .../figures/ca-setup-radio-bearer.seqdiag | 4 +- .../doc/source/figures/ca-uplink-bsr.seqdiag | 6 +- src/lte/doc/source/figures/helpers.seqdiag | 2 +- .../doc/source/figures/lte-enb-rrc-states.dot | 12 +- .../figures/lte-phy-interference.seqdiag | 2 +- .../mac-random-access-contention.seqdiag | 26 +- .../mac-random-access-noncontention.seqdiag | 24 +- src/lte/doc/source/figures/nas-attach.seqdiag | 4 +- .../rrc-connection-establishment.seqdiag | 4 +- ...onnection-reconfiguration-handover.seqdiag | 30 +- .../rrc-connection-reconfiguration.seqdiag | 8 +- src/lte/doc/source/index.rst | 4 +- src/lte/doc/source/lte-design.rst | 1370 ++++++------ src/lte/doc/source/lte-profiling.rst | 20 +- src/lte/doc/source/lte-references.rst | 26 +- src/lte/doc/source/lte-testing.rst | 414 ++-- src/lte/doc/source/lte-user.rst | 452 ++-- .../rlc_buffer_status_report_downlink.seqdiag | 16 +- .../rlc_buffer_status_report_uplink.seqdiag | 16 +- src/lte/examples/lena-cc-helper.cc | 12 +- src/lte/examples/lena-cqi-threshold.cc | 18 +- src/lte/examples/lena-dual-stripe.cc | 50 +- src/lte/examples/lena-fading.cc | 14 +- .../examples/lena-intercell-interference.cc | 2 +- src/lte/examples/lena-pathloss-traces.cc | 12 +- src/lte/examples/lena-rem.cc | 6 +- src/lte/examples/lena-rlc-traces.cc | 2 +- src/lte/examples/lena-simple-epc-emu.cc | 14 +- src/lte/examples/lena-uplink-power-control.cc | 4 +- src/lte/helper/cc-helper.cc | 6 +- src/lte/helper/cc-helper.h | 8 +- src/lte/helper/emu-epc-helper.cc | 8 +- src/lte/helper/emu-epc-helper.h | 6 +- src/lte/helper/epc-helper.cc | 2 +- src/lte/helper/epc-helper.h | 50 +- .../helper/lte-global-pathloss-database.cc | 8 +- src/lte/helper/lte-global-pathloss-database.h | 22 +- src/lte/helper/lte-helper.cc | 56 +- src/lte/helper/lte-helper.h | 74 +- .../lte-hex-grid-enb-topology-helper.cc | 26 +- .../helper/lte-hex-grid-enb-topology-helper.h | 6 +- src/lte/helper/mac-stats-calculator.h | 30 +- src/lte/helper/no-backhaul-epc-helper.cc | 32 +- src/lte/helper/no-backhaul-epc-helper.h | 2 +- src/lte/helper/phy-rx-stats-calculator.h | 22 +- src/lte/helper/phy-stats-calculator.h | 42 +- src/lte/helper/phy-tx-stats-calculator.h | 24 +- src/lte/helper/point-to-point-epc-helper.h | 4 +- .../helper/radio-bearer-stats-calculator.h | 20 +- .../helper/radio-environment-map-helper.cc | 50 +- src/lte/helper/radio-environment-map-helper.h | 20 +- src/lte/model/component-carrier-enb.cc | 6 +- src/lte/model/component-carrier-enb.h | 2 +- src/lte/model/component-carrier-ue.cc | 2 +- src/lte/model/component-carrier-ue.h | 6 +- src/lte/model/component-carrier.h | 2 +- src/lte/model/cqa-ff-mac-scheduler.cc | 14 +- src/lte/model/cqa-ff-mac-scheduler.h | 4 +- src/lte/model/epc-enb-application.cc | 44 +- src/lte/model/epc-enb-application.h | 82 +- src/lte/model/epc-enb-s1-sap.h | 54 +- src/lte/model/epc-gtpc-header.cc | 2 +- src/lte/model/epc-gtpc-header.h | 40 +- src/lte/model/epc-pgw-application.cc | 10 +- src/lte/model/epc-pgw-application.h | 6 +- src/lte/model/epc-s11-sap.h | 56 +- src/lte/model/epc-s1ap-sap.h | 44 +- src/lte/model/epc-sgw-application.cc | 4 +- src/lte/model/epc-sgw-application.h | 2 +- src/lte/model/epc-tft-classifier.cc | 6 +- src/lte/model/epc-tft-classifier.h | 28 +- src/lte/model/epc-tft.cc | 20 +- src/lte/model/epc-tft.h | 118 +- src/lte/model/epc-ue-nas.cc | 20 +- src/lte/model/epc-ue-nas.h | 38 +- src/lte/model/epc-x2-header.cc | 20 +- src/lte/model/epc-x2-header.h | 8 +- src/lte/model/epc-x2-sap.h | 18 +- src/lte/model/epc-x2.cc | 12 +- src/lte/model/epc-x2.h | 18 +- src/lte/model/eps-bearer-tag.h | 4 +- src/lte/model/eps-bearer.h | 6 +- .../fading-traces/fading_trace_generator.m | 26 +- src/lte/model/fdbet-ff-mac-scheduler.cc | 10 +- src/lte/model/fdbet-ff-mac-scheduler.h | 4 +- src/lte/model/fdmt-ff-mac-scheduler.cc | 26 +- src/lte/model/fdmt-ff-mac-scheduler.h | 2 +- src/lte/model/ff-mac-common.cc | 6 +- src/lte/model/ff-mac-common.h | 8 +- src/lte/model/ff-mac-csched-sap.h | 2 +- src/lte/model/ff-mac-scheduler.h | 6 +- src/lte/model/lte-amc.cc | 12 +- src/lte/model/lte-amc.h | 10 +- src/lte/model/lte-anr.h | 2 +- src/lte/model/lte-as-sap.h | 44 +- src/lte/model/lte-asn1-header.h | 2 +- src/lte/model/lte-ccm-mac-sap.h | 16 +- src/lte/model/lte-ccm-rrc-sap.h | 32 +- src/lte/model/lte-chunk-processor.h | 20 +- src/lte/model/lte-common.cc | 18 +- src/lte/model/lte-common.h | 58 +- src/lte/model/lte-control-messages.cc | 10 +- src/lte/model/lte-control-messages.h | 38 +- src/lte/model/lte-enb-cmac-sap.h | 46 +- .../lte-enb-component-carrier-manager.cc | 12 +- .../model/lte-enb-component-carrier-manager.h | 4 +- src/lte/model/lte-enb-cphy-sap.h | 52 +- src/lte/model/lte-enb-mac.cc | 46 +- src/lte/model/lte-enb-mac.h | 24 +- src/lte/model/lte-enb-net-device.cc | 30 +- src/lte/model/lte-enb-net-device.h | 30 +- src/lte/model/lte-enb-phy-sap.h | 10 +- src/lte/model/lte-enb-phy.h | 4 +- src/lte/model/lte-enb-rrc.cc | 122 +- src/lte/model/lte-enb-rrc.h | 292 +-- src/lte/model/lte-ffr-enhanced-algorithm.h | 4 +- src/lte/model/lte-ffr-rrc-sap.h | 2 +- src/lte/model/lte-ffr-sap.h | 2 +- src/lte/model/lte-ffr-soft-algorithm.h | 4 +- src/lte/model/lte-fr-soft-algorithm.cc | 2 +- src/lte/model/lte-fr-soft-algorithm.h | 2 +- src/lte/model/lte-handover-management-sap.h | 2 +- src/lte/model/lte-harq-phy.cc | 10 +- src/lte/model/lte-harq-phy.h | 10 +- src/lte/model/lte-interference.cc | 20 +- src/lte/model/lte-mi-error-model.cc | 80 +- src/lte/model/lte-mi-error-model.h | 18 +- src/lte/model/lte-net-device.h | 12 +- src/lte/model/lte-pdcp-header.h | 2 +- src/lte/model/lte-pdcp-sap.h | 6 +- src/lte/model/lte-pdcp.cc | 4 +- src/lte/model/lte-pdcp.h | 12 +- src/lte/model/lte-phy-tag.h | 2 +- src/lte/model/lte-phy.cc | 4 +- src/lte/model/lte-phy.h | 42 +- src/lte/model/lte-radio-bearer-info.cc | 12 +- src/lte/model/lte-radio-bearer-info.h | 8 +- src/lte/model/lte-radio-bearer-tag.h | 4 +- src/lte/model/lte-rlc-am-header.h | 30 +- src/lte/model/lte-rlc-am.cc | 66 +- src/lte/model/lte-rlc-am.h | 32 +- src/lte/model/lte-rlc-sequence-number.h | 8 +- src/lte/model/lte-rlc-tag.h | 2 +- src/lte/model/lte-rlc-tm.cc | 4 +- src/lte/model/lte-rlc-tm.h | 4 +- src/lte/model/lte-rlc-um.cc | 2 +- src/lte/model/lte-rlc.h | 12 +- src/lte/model/lte-rrc-header.cc | 184 +- src/lte/model/lte-rrc-header.h | 60 +- src/lte/model/lte-rrc-protocol-ideal.cc | 168 +- src/lte/model/lte-rrc-protocol-ideal.h | 40 +- src/lte/model/lte-rrc-protocol-real.cc | 82 +- src/lte/model/lte-rrc-protocol-real.h | 32 +- src/lte/model/lte-rrc-sap.h | 8 +- src/lte/model/lte-spectrum-phy.h | 126 +- .../model/lte-spectrum-signal-parameters.h | 30 +- src/lte/model/lte-spectrum-value-helper.cc | 20 +- src/lte/model/lte-ue-ccm-rrc-sap.h | 22 +- src/lte/model/lte-ue-cmac-sap.h | 52 +- .../model/lte-ue-component-carrier-manager.cc | 4 +- .../model/lte-ue-component-carrier-manager.h | 4 +- src/lte/model/lte-ue-cphy-sap.h | 36 +- src/lte/model/lte-ue-mac.cc | 60 +- src/lte/model/lte-ue-mac.h | 14 +- src/lte/model/lte-ue-net-device.cc | 4 +- src/lte/model/lte-ue-net-device.h | 2 +- src/lte/model/lte-ue-phy-sap.h | 4 +- src/lte/model/lte-ue-phy.h | 16 +- .../model/lte-vendor-specific-parameters.cc | 6 +- .../model/lte-vendor-specific-parameters.h | 10 +- .../model/no-op-component-carrier-manager.cc | 4 +- .../model/no-op-component-carrier-manager.h | 2 +- src/lte/model/pf-ff-mac-scheduler.cc | 6 +- src/lte/model/pf-ff-mac-scheduler.h | 2 +- src/lte/model/pss-ff-mac-scheduler.cc | 124 +- src/lte/model/pss-ff-mac-scheduler.h | 2 +- src/lte/model/rem-spectrum-phy.h | 24 +- src/lte/model/rr-ff-mac-scheduler.cc | 20 +- src/lte/model/rr-ff-mac-scheduler.h | 2 +- .../simple-ue-component-carrier-manager.cc | 18 +- .../simple-ue-component-carrier-manager.h | 6 +- src/lte/model/tdbet-ff-mac-scheduler.cc | 26 +- src/lte/model/tdmt-ff-mac-scheduler.cc | 32 +- src/lte/model/tdtbfq-ff-mac-scheduler.cc | 34 +- src/lte/model/tdtbfq-ff-mac-scheduler.h | 2 +- src/lte/model/tta-ff-mac-scheduler.cc | 28 +- src/lte/model/tta-ff-mac-scheduler.h | 4 +- src/lte/test/epc-test-s1u-downlink.cc | 62 +- src/lte/test/examples-to-run.py | 4 +- src/lte/test/lte-simple-helper.h | 6 +- src/lte/test/lte-simple-net-device.h | 4 +- ...-test-carrier-aggregation-configuration.cc | 2 +- src/lte/test/lte-test-carrier-aggregation.cc | 8 +- src/lte/test/lte-test-carrier-aggregation.h | 10 +- src/lte/test/lte-test-cqa-ff-mac-scheduler.cc | 30 +- src/lte/test/lte-test-cqa-ff-mac-scheduler.h | 2 +- src/lte/test/lte-test-cqi-generation.h | 4 +- .../test/lte-test-downlink-power-control.h | 10 +- src/lte/test/lte-test-downlink-sinr.cc | 58 +- src/lte/test/lte-test-downlink-sinr.h | 18 +- src/lte/test/lte-test-earfcn.cc | 14 +- src/lte/test/lte-test-entities.cc | 24 +- src/lte/test/lte-test-entities.h | 18 +- .../test/lte-test-fdbet-ff-mac-scheduler.cc | 20 +- .../test/lte-test-fdbet-ff-mac-scheduler.h | 14 +- .../test/lte-test-fdmt-ff-mac-scheduler.cc | 12 +- src/lte/test/lte-test-fdmt-ff-mac-scheduler.h | 10 +- .../test/lte-test-fdtbfq-ff-mac-scheduler.cc | 32 +- .../test/lte-test-fdtbfq-ff-mac-scheduler.h | 16 +- src/lte/test/lte-test-frequency-reuse.h | 14 +- src/lte/test/lte-test-harq.cc | 4 +- src/lte/test/lte-test-interference-fr.h | 6 +- src/lte/test/lte-test-interference.cc | 4 +- src/lte/test/lte-test-interference.h | 2 +- src/lte/test/lte-test-link-adaptation.cc | 2 +- src/lte/test/lte-test-mimo.cc | 34 +- src/lte/test/lte-test-mimo.h | 12 +- src/lte/test/lte-test-pathloss-model.cc | 40 +- src/lte/test/lte-test-pathloss-model.h | 10 +- src/lte/test/lte-test-pf-ff-mac-scheduler.cc | 28 +- src/lte/test/lte-test-pf-ff-mac-scheduler.h | 14 +- src/lte/test/lte-test-phy-error-model.cc | 52 +- src/lte/test/lte-test-phy-error-model.h | 8 +- src/lte/test/lte-test-pss-ff-mac-scheduler.cc | 30 +- src/lte/test/lte-test-pss-ff-mac-scheduler.h | 14 +- src/lte/test/lte-test-rlc-am-e2e.h | 2 +- src/lte/test/lte-test-rlc-am-transmitter.h | 12 +- src/lte/test/lte-test-rlc-um-transmitter.h | 6 +- src/lte/test/lte-test-rr-ff-mac-scheduler.cc | 10 +- src/lte/test/lte-test-rr-ff-mac-scheduler.h | 14 +- .../test/lte-test-spectrum-value-helper.cc | 16 +- .../test/lte-test-tdbet-ff-mac-scheduler.cc | 24 +- .../test/lte-test-tdbet-ff-mac-scheduler.h | 10 +- .../test/lte-test-tdmt-ff-mac-scheduler.cc | 14 +- src/lte/test/lte-test-tdmt-ff-mac-scheduler.h | 10 +- .../test/lte-test-tdtbfq-ff-mac-scheduler.cc | 28 +- .../test/lte-test-tdtbfq-ff-mac-scheduler.h | 12 +- src/lte/test/lte-test-tta-ff-mac-scheduler.cc | 12 +- src/lte/test/lte-test-tta-ff-mac-scheduler.h | 10 +- src/lte/test/lte-test-ue-measurements.h | 56 +- src/lte/test/lte-test-ue-phy.cc | 4 +- src/lte/test/lte-test-ue-phy.h | 2 +- src/lte/test/lte-test-uplink-sinr.cc | 64 +- src/lte/test/lte-test-uplink-sinr.h | 24 +- src/lte/test/reference/gain_freespace.m | 8 +- .../generate_test_data_lte_spectrum_model.m | 14 +- ...erate_test_data_lte_spectrum_value_noise.m | 14 +- ...erate_test_data_lte_spectrum_value_txpsd.m | 16 +- src/lte/test/reference/lte_amc.m | 2 +- src/lte/test/reference/lte_cqi_generation.m | 10 +- src/lte/test/reference/lte_frequency_reuse.m | 14 +- src/lte/test/reference/lte_link_budget.m | 2 +- .../reference/lte_link_budget_interference.m | 14 +- .../lte_link_budget_interference_fr.m | 14 +- .../lte_link_budget_x2_handover_measures.m | 2 +- src/lte/test/reference/lte_pathloss.m | 2 +- src/lte/test/reference/lte_ue_measurements.m | 6 +- .../test/reference/lte_uplink_power_control.m | 24 +- src/lte/test/reference/path_loss.m | 8 +- src/lte/test/reference/print_C_vector.m | 6 +- src/lte/test/test-asn1-encoding.cc | 2 +- src/lte/test/test-epc-tft-classifier.cc | 4 +- src/lte/test/test-lte-antenna.cc | 30 +- src/lte/test/test-lte-epc-e2e-data.cc | 120 +- src/lte/test/test-lte-rlc-header.cc | 22 +- src/lte/test/test-lte-rrc.cc | 12 +- src/lte/test/test-lte-x2-handover.cc | 2 +- src/mesh/doc/Makefile | 8 +- src/mesh/doc/mesh.h | 76 +- src/mesh/doc/source/conf.py | 2 +- src/mesh/doc/source/mesh-design.rst | 26 +- src/mesh/examples/mesh.cc | 16 +- src/mesh/helper/dot11s/dot11s-installer.cc | 4 +- src/mesh/helper/dot11s/dot11s-installer.h | 4 +- src/mesh/helper/flame/flame-installer.cc | 2 +- src/mesh/helper/mesh-helper.cc | 6 +- src/mesh/helper/mesh-helper.h | 20 +- src/mesh/helper/mesh-stack-installer.cc | 2 +- src/mesh/helper/mesh-stack-installer.h | 2 +- src/mesh/model/dot11s/airtime-metric.cc | 2 +- src/mesh/model/dot11s/airtime-metric.h | 2 +- src/mesh/model/dot11s/dot11s-mac-header.cc | 4 +- src/mesh/model/dot11s/dot11s-mac-header.h | 4 +- src/mesh/model/dot11s/dot11s.h | 26 +- src/mesh/model/dot11s/hwmp-protocol-mac.cc | 6 +- src/mesh/model/dot11s/hwmp-protocol-mac.h | 12 +- src/mesh/model/dot11s/hwmp-protocol.cc | 6 +- src/mesh/model/dot11s/hwmp-protocol.h | 6 +- src/mesh/model/dot11s/hwmp-rtable.cc | 4 +- src/mesh/model/dot11s/hwmp-tag.cc | 2 +- src/mesh/model/dot11s/hwmp-tag.h | 6 +- .../model/dot11s/ie-dot11s-beacon-timing.h | 6 +- .../model/dot11s/ie-dot11s-configuration.cc | 8 +- .../model/dot11s/ie-dot11s-configuration.h | 26 +- src/mesh/model/dot11s/ie-dot11s-id.h | 2 +- .../model/dot11s/ie-dot11s-peer-management.h | 8 +- src/mesh/model/dot11s/ie-dot11s-prep.h | 4 +- src/mesh/model/dot11s/ie-dot11s-preq.h | 6 +- src/mesh/model/dot11s/ie-dot11s-rann.h | 2 +- src/mesh/model/dot11s/peer-link-frame.cc | 20 +- src/mesh/model/dot11s/peer-link-frame.h | 8 +- src/mesh/model/dot11s/peer-link.cc | 2 +- src/mesh/model/dot11s/peer-link.h | 4 +- .../dot11s/peer-management-protocol-mac.cc | 22 +- .../dot11s/peer-management-protocol-mac.h | 4 +- .../model/dot11s/peer-management-protocol.cc | 8 +- .../model/dot11s/peer-management-protocol.h | 10 +- src/mesh/model/flame/flame-protocol-mac.cc | 8 +- src/mesh/model/flame/flame-protocol-mac.h | 8 +- src/mesh/model/flame/flame-protocol.cc | 4 +- src/mesh/model/flame/flame-protocol.h | 2 +- src/mesh/model/flame/flame-rtable.cc | 2 +- src/mesh/model/mesh-point-device.cc | 6 +- src/mesh/model/mesh-point-device.h | 4 +- .../model/mesh-wifi-interface-mac-plugin.h | 16 +- src/mesh/model/mesh-wifi-interface-mac.h | 8 +- src/mesh/test/dot11s/dot11s-test-suite.cc | 10 +- .../test/dot11s/hwmp-proactive-regression.cc | 2 +- .../test/dot11s/hwmp-reactive-regression.h | 4 +- .../test/dot11s/hwmp-simplest-regression.h | 2 +- src/mesh/test/dot11s/pmp-regression.cc | 2 +- src/mesh/test/dot11s/pmp-regression.h | 6 +- src/mesh/test/dot11s/regression.cc | 4 +- src/mesh/test/flame/flame-regression.cc | 2 +- src/mesh/test/flame/flame-test-suite.cc | 10 +- src/mesh/test/flame/regression.cc | 4 +- src/mobility/doc/mobility.rst | 46 +- .../examples/bonnmotion-ns2-example.cc | 2 +- src/mobility/examples/main-grid-topology.cc | 6 +- src/mobility/examples/main-random-topology.cc | 4 +- src/mobility/examples/main-random-walk.cc | 4 +- .../examples/mobility-trace-example.cc | 2 +- src/mobility/examples/ns2-mobility-trace.cc | 2 +- .../reference-point-group-mobility-animate.sh | 6 +- .../reference-point-group-mobility-example.cc | 12 +- src/mobility/helper/group-mobility-helper.cc | 6 +- src/mobility/helper/group-mobility-helper.h | 14 +- src/mobility/helper/mobility-helper.cc | 28 +- src/mobility/helper/mobility-helper.h | 32 +- src/mobility/helper/ns2-mobility-helper.cc | 18 +- src/mobility/helper/ns2-mobility-helper.h | 8 +- src/mobility/model/box.cc | 2 +- src/mobility/model/box.h | 2 +- .../constant-acceleration-mobility-model.cc | 4 +- .../constant-acceleration-mobility-model.h | 2 +- .../model/constant-position-mobility-model.h | 2 +- .../model/constant-velocity-helper.cc | 8 +- src/mobility/model/constant-velocity-helper.h | 8 +- .../model/constant-velocity-mobility-model.cc | 2 +- .../model/constant-velocity-mobility-model.h | 2 +- .../model/gauss-markov-mobility-model.cc | 8 +- .../model/gauss-markov-mobility-model.h | 18 +- src/mobility/model/geographic-positions.cc | 58 +- src/mobility/model/geographic-positions.h | 54 +- .../model/hierarchical-mobility-model.cc | 14 +- .../model/hierarchical-mobility-model.h | 4 +- src/mobility/model/mobility-model.cc | 8 +- src/mobility/model/mobility-model.h | 8 +- src/mobility/model/mobility.h | 4 +- .../random-direction-2d-mobility-model.cc | 2 +- .../random-direction-2d-mobility-model.h | 6 +- .../model/random-walk-2d-mobility-model.cc | 2 +- .../model/random-walk-2d-mobility-model.h | 4 +- .../model/random-waypoint-mobility-model.cc | 2 +- .../model/random-waypoint-mobility-model.h | 12 +- src/mobility/model/rectangle.cc | 2 +- ...dy-state-random-waypoint-mobility-model.cc | 8 +- ...ady-state-random-waypoint-mobility-model.h | 16 +- src/mobility/model/waypoint-mobility-model.h | 20 +- src/mobility/model/waypoint.h | 2 +- src/mobility/test/geo-to-cartesian-test.cc | 956 ++++----- .../test/rand-cart-around-geo-test.cc | 76 +- ...ate-random-waypoint-mobility-model-test.cc | 2 +- .../test/waypoint-mobility-model-test.cc | 2 +- src/mpi/doc/distributed.rst | 42 +- src/mpi/examples/mpi-test-fixtures.cc | 8 +- src/mpi/examples/mpi-test-fixtures.h | 18 +- src/mpi/examples/nms-p2p-nix-distributed.cc | 6 +- .../examples/simple-distributed-empty-node.cc | 18 +- .../examples/simple-distributed-mpi-comm.cc | 44 +- src/mpi/examples/simple-distributed.cc | 10 +- src/mpi/examples/third-distributed.cc | 28 +- src/mpi/model/distributed-simulator-impl.cc | 6 +- src/mpi/model/distributed-simulator-impl.h | 12 +- .../granted-time-window-mpi-interface.cc | 14 +- .../model/granted-time-window-mpi-interface.h | 4 +- src/mpi/model/mpi-interface.cc | 2 +- src/mpi/model/mpi-interface.h | 4 +- src/mpi/model/null-message-mpi-interface.cc | 20 +- src/mpi/model/null-message-mpi-interface.h | 6 +- src/mpi/model/null-message-simulator-impl.cc | 6 +- .../model/remote-channel-bundle-manager.cc | 2 +- src/mpi/model/remote-channel-bundle-manager.h | 4 +- src/mpi/model/remote-channel-bundle.cc | 6 +- src/mpi/model/remote-channel-bundle.h | 4 +- src/mpi/test/mpi-test-suite.cc | 6 +- src/netanim/doc/animation.rst | 22 +- .../examples/colors-link-description.cc | 12 +- src/netanim/examples/dumbbell-animation.cc | 2 +- src/netanim/examples/resources-counters.cc | 16 +- src/netanim/examples/star-animation.cc | 4 +- src/netanim/examples/uan-animation.cc | 10 +- src/netanim/examples/uan-animation.h | 2 +- src/netanim/examples/wireless-animation.cc | 8 +- src/netanim/model/animation-interface.cc | 26 +- src/network/doc/error-model.rst | 34 +- src/network/doc/network-overview.rst | 2 +- src/network/doc/packets.rst | 54 +- src/network/doc/queue.rst | 16 +- src/network/doc/sockets-api.rst | 30 +- src/network/examples/main-packet-header.cc | 8 +- src/network/examples/main-packet-tag.cc | 16 +- src/network/helper/application-container.cc | 20 +- src/network/helper/application-container.h | 18 +- src/network/helper/delay-jitter-estimation.cc | 6 +- src/network/helper/net-device-container.cc | 14 +- src/network/helper/net-device-container.h | 22 +- src/network/helper/node-container.cc | 26 +- src/network/helper/node-container.h | 50 +- src/network/helper/packet-socket-helper.h | 2 +- .../helper/simple-net-device-helper.cc | 6 +- src/network/helper/trace-helper.cc | 76 +- src/network/helper/trace-helper.h | 146 +- src/network/model/address.cc | 20 +- src/network/model/address.h | 14 +- src/network/model/application.cc | 4 +- src/network/model/application.h | 4 +- src/network/model/buffer.cc | 124 +- src/network/model/buffer.h | 58 +- src/network/model/byte-tag-list.cc | 24 +- src/network/model/byte-tag-list.h | 32 +- src/network/model/channel-list.cc | 16 +- src/network/model/channel.cc | 4 +- src/network/model/channel.h | 4 +- src/network/model/chunk.cc | 2 +- src/network/model/chunk.h | 2 +- src/network/model/header.h | 16 +- src/network/model/net-device.h | 50 +- src/network/model/nix-vector.cc | 24 +- src/network/model/nix-vector.h | 40 +- src/network/model/node-list.cc | 18 +- src/network/model/node-list.h | 2 +- src/network/model/node.cc | 38 +- src/network/model/node.h | 12 +- src/network/model/packet-metadata.cc | 148 +- src/network/model/packet-metadata.h | 46 +- src/network/model/packet-tag-list.h | 14 +- src/network/model/packet.cc | 106 +- src/network/model/packet.h | 86 +- src/network/model/socket-factory.h | 8 +- src/network/model/socket.h | 172 +- src/network/model/tag-buffer.cc | 18 +- src/network/model/tag-buffer.h | 16 +- src/network/model/tag.cc | 2 +- src/network/model/trailer.h | 28 +- src/network/test/error-model-test-suite.cc | 10 +- .../test/packet-socket-apps-test-suite.cc | 2 +- src/network/test/packetbb-test-suite.cc | 6 +- src/network/test/pcap-file-test-suite.cc | 104 +- .../test/sequence-number-test-suite.cc | 4 +- src/network/test/test-data-rate.cc | 6 +- src/network/utils/crc32.cc | 4 +- src/network/utils/data-rate.h | 62 +- src/network/utils/error-model.cc | 134 +- src/network/utils/error-model.h | 64 +- src/network/utils/ethernet-header.cc | 18 +- src/network/utils/ethernet-header.h | 2 +- src/network/utils/ethernet-trailer.cc | 8 +- src/network/utils/ethernet-trailer.h | 8 +- src/network/utils/flow-id-tag.cc | 16 +- src/network/utils/flow-id-tag.h | 2 +- src/network/utils/inet-socket-address.cc | 8 +- src/network/utils/ipv4-address.cc | 46 +- src/network/utils/ipv4-address.h | 30 +- src/network/utils/ipv6-address.cc | 8 +- src/network/utils/ipv6-address.h | 2 +- src/network/utils/llc-snap-header.cc | 8 +- src/network/utils/llc-snap-header.h | 4 +- src/network/utils/mac48-address.cc | 40 +- src/network/utils/mac48-address.h | 6 +- src/network/utils/mac64-address.cc | 20 +- src/network/utils/mac64-address.h | 4 +- src/network/utils/output-stream-wrapper.h | 22 +- src/network/utils/packet-burst.h | 2 +- src/network/utils/packet-data-calculators.h | 10 +- src/network/utils/packet-socket-factory.cc | 4 +- src/network/utils/packet-socket-factory.h | 4 +- src/network/utils/packet-socket.cc | 18 +- src/network/utils/packet-socket.h | 20 +- src/network/utils/packetbb.cc | 18 +- src/network/utils/packetbb.h | 18 +- src/network/utils/pcap-file-wrapper.cc | 16 +- src/network/utils/pcap-file-wrapper.h | 38 +- src/network/utils/pcap-file.h | 82 +- src/network/utils/sequence-number.h | 18 +- src/network/utils/simple-channel.cc | 2 +- src/network/utils/simple-channel.h | 6 +- src/network/utils/simple-net-device.cc | 50 +- src/network/utils/simple-net-device.h | 12 +- .../doc/nix-vector-routing.rst | 30 +- .../examples/nix-simple-multi-address.cc | 2 +- src/nix-vector-routing/examples/nix-simple.cc | 8 +- .../examples/nms-p2p-nix.cc | 58 +- .../helper/ipv4-nix-vector-helper.h | 2 +- .../helper/nix-vector-helper.cc | 4 +- .../helper/nix-vector-helper.h | 10 +- .../model/ipv4-nix-vector-routing.h | 2 +- .../model/nix-vector-routing.cc | 44 +- .../model/nix-vector-routing.h | 12 +- src/nix-vector-routing/test/nix-test.cc | 2 +- src/olsr/doc/olsr.rst | 8 +- src/openflow/doc/openflow-switch.rst | 70 +- src/openflow/model/openflow-interface.cc | 6 +- src/openflow/model/openflow-interface.h | 4 +- .../model/openflow-switch-net-device.cc | 2 +- .../model/openflow-switch-net-device.h | 4 +- .../doc/point-to-point-dumbbell.rst | 2 +- .../model/point-to-point-dumbbell.cc | 12 +- .../model/point-to-point-dumbbell.h | 16 +- .../model/point-to-point-grid.cc | 54 +- .../model/point-to-point-grid.h | 48 +- .../model/point-to-point-star.cc | 8 +- .../model/point-to-point-star.h | 16 +- src/point-to-point/doc/point-to-point.rst | 12 +- .../examples/main-attribute-value.cc | 26 +- .../helper/point-to-point-helper.cc | 46 +- .../helper/point-to-point-helper.h | 12 +- .../model/point-to-point-channel.cc | 4 +- .../model/point-to-point-channel.h | 18 +- .../model/point-to-point-net-device.cc | 72 +- .../model/point-to-point-net-device.h | 46 +- .../model/point-to-point-remote-channel.h | 6 +- src/point-to-point/model/ppp-header.cc | 4 +- src/point-to-point/model/ppp-header.h | 2 +- .../test/point-to-point-test.cc | 12 +- src/propagation/doc/propagation.rst | 212 +- .../jakes-propagation-model-example.cc | 4 +- .../examples/main-propagation-loss.cc | 2 +- .../model/channel-condition-model.h | 48 +- .../itu-r-1411-los-propagation-loss-model.cc | 4 +- .../itu-r-1411-los-propagation-loss-model.h | 18 +- ...los-over-rooftop-propagation-loss-model.cc | 6 +- ...nlos-over-rooftop-propagation-loss-model.h | 20 +- src/propagation/model/jakes-process.cc | 6 +- .../model/jakes-propagation-loss-model.cc | 2 +- .../kun-2600-mhz-propagation-loss-model.cc | 6 +- .../kun-2600-mhz-propagation-loss-model.h | 10 +- .../okumura-hata-propagation-loss-model.cc | 8 +- .../okumura-hata-propagation-loss-model.h | 10 +- ...robabilistic-v2v-channel-condition-model.h | 26 +- src/propagation/model/propagation-cache.h | 2 +- .../model/propagation-delay-model.cc | 4 +- .../model/propagation-delay-model.h | 6 +- .../model/propagation-environment.h | 6 +- .../model/propagation-loss-model.cc | 36 +- .../model/propagation-loss-model.h | 66 +- .../model/three-gpp-propagation-loss-model.cc | 26 +- .../model/three-gpp-propagation-loss-model.h | 12 +- .../three-gpp-v2v-propagation-loss-model.h | 8 +- .../test/itu-r-1411-los-test-suite.cc | 10 +- ...itu-r-1411-nlos-over-rooftop-test-suite.cc | 10 +- .../test/kun-2600-mhz-test-suite.cc | 12 +- .../test/okumura-hata-test-suite.cc | 8 +- ...listic-v2v-channel-condition-model-test.cc | 6 +- .../test/propagation-loss-model-test-suite.cc | 48 +- .../loss_COST231_large_cities_urban.m | 8 +- .../loss_COST231_small_cities_urban.m | 8 +- .../test/reference/loss_ITU1411_LOS.m | 4 +- .../loss_ITU1411_NLOS_over_rooftop.m | 8 +- .../test/reference/loss_Kun_2_6GHz.m | 4 +- .../reference/loss_OH_large_cities_urban.m | 8 +- .../test/reference/loss_OH_openareas.m | 4 +- .../reference/loss_OH_small_cities_urban.m | 8 +- .../test/reference/loss_OH_suburban.m | 4 +- ...e-gpp-propagation-loss-model-test-suite.cc | 20 +- src/sixlowpan/doc/sixlowpan.rst | 6 +- .../examples/example-ping-lr-wpan.cc | 12 +- src/sixlowpan/model/sixlowpan-net-device.cc | 2 +- src/sixlowpan/test/mock-net-device.h | 2 +- src/spectrum/doc/Makefile | 2 +- .../spectrum-channel-phy-interface.seqdiag | 10 +- src/spectrum/doc/spectrum.rst | 76 +- ...ideal-phy-matrix-propagation-loss-model.cc | 30 +- ...hoc-aloha-ideal-phy-with-microwave-oven.cc | 4 +- .../examples/three-gpp-channel-example.cc | 2 +- src/spectrum/examples/tv-trans-example.cc | 10 +- .../examples/tv-trans-regional-example.cc | 20 +- .../helper/spectrum-analyzer-helper.h | 6 +- src/spectrum/helper/spectrum-helper.cc | 4 +- src/spectrum/helper/spectrum-helper.h | 8 +- .../helper/tv-spectrum-transmitter-helper.cc | 174 +- .../helper/tv-spectrum-transmitter-helper.h | 204 +- src/spectrum/model/half-duplex-ideal-phy.h | 6 +- .../model/matrix-based-channel-model.h | 4 +- .../model/multi-model-spectrum-channel.cc | 8 +- .../model/multi-model-spectrum-channel.h | 2 +- .../model/single-model-spectrum-channel.cc | 4 +- src/spectrum/model/spectrum-analyzer.h | 6 +- src/spectrum/model/spectrum-interference.h | 2 +- .../model/spectrum-model-300kHz-300GHz-log.cc | 4 +- .../spectrum-model-ism2400MHz-res1MHz.cc | 4 +- src/spectrum/model/three-gpp-channel-model.cc | 14 +- src/spectrum/model/three-gpp-channel-model.h | 4 +- ...ree-gpp-spectrum-propagation-loss-model.cc | 2 +- src/spectrum/model/trace-fading-loss-model.cc | 18 +- src/spectrum/model/trace-fading-loss-model.h | 24 +- src/spectrum/model/tv-spectrum-transmitter.cc | 76 +- src/spectrum/model/tv-spectrum-transmitter.h | 32 +- .../model/wifi-spectrum-value-helper.cc | 2 +- src/spectrum/test/spectrum-ideal-phy-test.cc | 28 +- src/spectrum/test/spectrum-test.h | 2 +- .../test/spectrum-waveform-generator-test.cc | 4 +- .../test/three-gpp-channel-test-suite.cc | 6 +- .../test/tv-helper-distribution-test.cc | 46 +- .../test/tv-spectrum-transmitter-test.cc | 78 +- src/stats/doc/adaptor.rst | 2 +- src/stats/doc/aggregator.rst | 52 +- src/stats/doc/collector.rst | 4 +- src/stats/doc/data-collection-helpers.rst | 142 +- src/stats/doc/data-collection-overview.rst | 20 +- src/stats/doc/data-collection.rst | 6 +- src/stats/doc/probe.rst | 100 +- src/stats/doc/scope-and-limitations.rst | 2 +- src/stats/doc/statistics.rst | 38 +- src/stats/examples/gnuplot-example.cc | 12 +- src/stats/examples/gnuplot-helper-example.cc | 2 +- src/stats/examples/time-probe-example.cc | 4 +- src/stats/helper/file-helper.h | 4 +- src/stats/helper/gnuplot-helper.cc | 2 +- src/stats/helper/gnuplot-helper.h | 4 +- src/stats/model/average.h | 16 +- src/stats/model/basic-data-calculators.h | 8 +- src/stats/model/data-calculator.cc | 2 +- src/stats/model/data-calculator.h | 4 +- src/stats/model/data-collector.cc | 2 +- src/stats/model/data-collector.h | 4 +- src/stats/model/data-output-interface.cc | 2 +- src/stats/model/data-output-interface.h | 2 +- src/stats/model/gnuplot.cc | 14 +- src/stats/model/gnuplot.h | 16 +- src/stats/model/histogram.cc | 18 +- src/stats/model/omnet-data-output.cc | 2 +- src/stats/model/omnet-data-output.h | 2 +- src/stats/model/time-data-calculators.cc | 2 +- src/stats/model/time-data-calculators.h | 2 +- src/stats/model/time-probe.h | 10 +- src/stats/model/time-series-adaptor.h | 2 +- src/stats/test/histogram-test-suite.cc | 2 +- src/tap-bridge/doc/tap.rst | 176 +- .../examples/tap-csma-virtual-machine.cc | 20 +- .../examples/tap-csma-virtual-machine.py | 8 +- src/tap-bridge/examples/tap-csma.cc | 2 +- src/tap-bridge/examples/tap-wifi-dumbbell.cc | 14 +- .../examples/tap-wifi-virtual-machine.cc | 16 +- .../examples/tap-wifi-virtual-machine.py | 8 +- src/tap-bridge/helper/tap-bridge-helper.cc | 2 +- src/tap-bridge/helper/tap-bridge-helper.h | 30 +- src/tap-bridge/model/tap-bridge.cc | 190 +- src/tap-bridge/model/tap-creator.cc | 56 +- src/test/csma-system-test-suite.cc | 128 +- src/test/doc/tests.h | 20 +- .../ns3tc/fq-cobalt-queue-disc-test-suite.cc | 58 +- .../ns3tc/fq-codel-queue-disc-test-suite.cc | 26 +- .../ns3tc/fq-pie-queue-disc-test-suite.cc | 28 +- .../ns3tc/pfifo-fast-queue-disc-test-suite.cc | 16 +- src/test/ns3tcp/ns3tcp-loss-test-suite.cc | 14 +- src/test/ns3tcp/ns3tcp-no-delay-test-suite.cc | 12 +- src/test/ns3tcp/ns3tcp-socket-test-suite.cc | 14 +- src/test/ns3tcp/ns3tcp-socket-writer.cc | 2 +- src/test/ns3tcp/ns3tcp-socket-writer.h | 4 +- src/test/ns3tcp/ns3tcp-state-test-suite.cc | 12 +- src/test/ns3tcp/plot.gp | 22 +- src/test/ns3tcp/trTidy.pl | 4 +- .../traced-callback-typedef-test-suite.cc | 30 +- ...raced-value-callback-typedef-test-suite.cc | 38 +- src/topology-read/doc/topology.rst | 22 +- src/traffic-control/doc/cobalt.rst | 8 +- src/traffic-control/doc/codel.rst | 38 +- src/traffic-control/doc/fq-codel.rst | 26 +- src/traffic-control/doc/fq-pie.rst | 6 +- src/traffic-control/doc/pie.rst | 18 +- src/traffic-control/doc/queue-discs.rst | 8 +- src/traffic-control/doc/red.rst | 4 +- .../examples/adaptive-red-tests.cc | 2 +- .../examples/codel-vs-pfifo-asymmetric.cc | 2 +- src/traffic-control/examples/pfifo-vs-red.cc | 16 +- src/traffic-control/examples/red-tests.cc | 28 +- .../helper/traffic-control-helper.cc | 2 +- src/traffic-control/model/packet-filter.cc | 2 +- .../model/pfifo-fast-queue-disc.cc | 2 +- src/traffic-control/model/pie-queue-disc.cc | 10 +- src/traffic-control/model/prio-queue-disc.cc | 2 +- src/traffic-control/model/red-queue-disc.cc | 32 +- src/traffic-control/model/red-queue-disc.h | 4 +- .../test/codel-queue-disc-test-suite.cc | 12 +- .../test/fifo-queue-disc-test-suite.cc | 2 +- .../test/pie-queue-disc-test-suite.cc | 6 +- .../test/queue-disc-traces-test-suite.cc | 4 +- .../test/red-queue-disc-test-suite.cc | 4 +- .../test/tc-flow-control-test-suite.cc | 6 +- src/uan/doc/uan.rst | 24 +- src/uan/examples/uan-cw-example.cc | 10 +- src/uan/examples/uan-cw-example.h | 6 +- src/uan/examples/uan-rc-example.cc | 14 +- src/uan/examples/uan-rc-example.h | 2 +- .../acoustic-modem-energy-model-helper.h | 2 +- src/uan/helper/uan-helper.cc | 4 +- src/uan/helper/uan-helper.h | 4 +- src/uan/model/acoustic-modem-energy-model.cc | 2 +- src/uan/model/acoustic-modem-energy-model.h | 10 +- src/uan/model/uan-header-rc.h | 6 +- src/uan/model/uan-mac-aloha.cc | 4 +- src/uan/model/uan-mac-aloha.h | 2 +- src/uan/model/uan-mac-rc-gw.cc | 12 +- src/uan/model/uan-mac-rc-gw.h | 4 +- src/uan/model/uan-mac-rc.cc | 48 +- src/uan/model/uan-mac-rc.h | 8 +- src/uan/model/uan-mac.h | 2 +- src/uan/model/uan-net-device.cc | 6 +- src/uan/model/uan-net-device.h | 8 +- src/uan/model/uan-noise-model.cc | 4 +- src/uan/model/uan-phy-dual.h | 12 +- src/uan/model/uan-prop-model.h | 14 +- src/uan/model/uan-transducer-hd.cc | 2 +- src/uan/model/uan-transducer-hd.h | 2 +- src/uan/model/uan-transducer.h | 8 +- src/uan/model/uan-tx-mode.cc | 2 +- src/uan/model/uan-tx-mode.h | 4 +- src/uan/test/uan-energy-model-test.cc | 4 +- src/uan/test/uan-test.cc | 8 +- .../examples/virtual-net-device.cc | 14 +- .../model/virtual-net-device.cc | 16 +- src/visualizer/model/pyviz.cc | 146 +- src/visualizer/model/pyviz.h | 2 +- src/visualizer/model/visual-simulator-impl.cc | 14 +- src/visualizer/visualizer/core.py | 2 +- src/visualizer/visualizer/ipython_view.py | 78 +- src/visualizer/visualizer/svgitem.py | 2 +- src/wave/doc/wave.rst | 524 ++--- .../low99-ct-unterstrass-1day.filt.7.adj.mob | 1886 ++++++++--------- src/wave/examples/vanet-routing-compare.cc | 6 +- src/wave/examples/wave-simple-device.cc | 2 +- src/wave/helper/wave-bsm-stats.cc | 2 +- src/wave/helper/wave-bsm-stats.h | 4 +- src/wave/model/wave-net-device.h | 4 +- src/wifi/doc/Makefile | 8 +- src/wifi/doc/source/conf.py | 2 +- src/wifi/doc/source/wifi-references.rst | 6 +- src/wifi/doc/source/wifi-testing.rst | 32 +- src/wifi/examples/reference/Bianchi11a.m | 12 +- src/wifi/examples/reference/Bianchi11b.m | 16 +- src/wifi/examples/reference/Bianchi11g.m | 14 +- src/wifi/examples/reference/bianchi11ax.py | 58 +- .../examples/reference/generate_bianchi.m | 12 +- src/wifi/model/interference-helper.cc | 4 +- src/wifi/model/interference-helper.h | 2 +- .../model/originator-block-ack-agreement.h | 2 +- .../model/recipient-block-ack-agreement.cc | 4 +- .../threshold-preamble-detection-model.cc | 2 +- .../model/wifi-information-element-vector.h | 2 +- src/wifi/model/wifi-tx-current-model.cc | 6 +- src/wifi/model/wifi-tx-parameters.cc | 8 +- src/wifi/test/inter-bss-test-suite.cc | 2 +- src/wifi/test/spectrum-wifi-phy-test.cc | 4 +- src/wifi/test/wifi-phy-reception-test.cc | 22 +- src/wimax/doc/wimax.rst | 44 +- src/wimax/helper/wimax-helper.h | 2 +- src/wimax/model/bandwidth-manager.h | 2 +- src/wimax/model/bs-link-manager.h | 2 +- src/wimax/model/bs-net-device.h | 2 +- src/wimax/model/bs-scheduler-simple.h | 2 +- src/wimax/model/bs-scheduler.cc | 2 +- src/wimax/model/bs-scheduler.h | 2 +- src/wimax/model/bs-service-flow-manager.h | 4 +- src/wimax/model/bs-uplink-scheduler-mbqos.h | 4 +- src/wimax/model/bs-uplink-scheduler-rtps.cc | 4 +- src/wimax/model/bs-uplink-scheduler-rtps.h | 2 +- src/wimax/model/bs-uplink-scheduler-simple.cc | 2 +- src/wimax/model/bs-uplink-scheduler-simple.h | 2 +- src/wimax/model/bs-uplink-scheduler.h | 14 +- src/wimax/model/burst-profile-manager.h | 2 +- src/wimax/model/cid-factory.h | 2 +- src/wimax/model/ipcs-classifier-record.h | 4 +- src/wimax/model/ipcs-classifier.h | 2 +- src/wimax/model/mac-messages.h | 2 +- src/wimax/model/ofdm-downlink-frame-prefix.cc | 2 +- src/wimax/model/ofdm-downlink-frame-prefix.h | 2 +- src/wimax/model/service-flow-manager.h | 2 +- src/wimax/model/service-flow.h | 2 +- src/wimax/model/simple-ofdm-send-param.h | 4 +- src/wimax/model/simple-ofdm-wimax-channel.cc | 2 +- src/wimax/model/simple-ofdm-wimax-channel.h | 6 +- src/wimax/model/simple-ofdm-wimax-phy.cc | 2 +- src/wimax/model/simple-ofdm-wimax-phy.h | 4 +- .../model/snr-to-block-error-rate-manager.h | 2 +- src/wimax/model/ss-link-manager.h | 8 +- src/wimax/model/ss-manager.cc | 2 +- src/wimax/model/ss-manager.h | 2 +- src/wimax/model/ss-net-device.h | 4 +- src/wimax/model/ss-record.h | 2 +- src/wimax/model/ss-scheduler.cc | 2 +- src/wimax/model/ss-service-flow-manager.h | 4 +- src/wimax/model/ul-job.h | 6 +- src/wimax/model/ul-mac-messages.h | 4 +- src/wimax/model/wimax-connection.h | 2 +- src/wimax/model/wimax-net-device.h | 6 +- src/wimax/model/wimax-phy.h | 4 +- src/wimax/model/wimax-tlv.cc | 4 +- src/wimax/model/wimax-tlv.h | 26 +- utils/bench-packets.cc | 24 +- utils/bench-simulator.cc | 2 +- utils/coverity-report.sh | 2 +- utils/create-module.py | 70 +- utils/perf/perf-io.cc | 10 +- utils/print-introspected-doxygen.cc | 92 +- utils/python-unit-tests.py | 10 +- utils/tests/TestBase.py | 4 +- utils/tests/gitlab-ci-clang.yml | 2 +- utils/tests/test-test.py | 6 +- utils/utils.h | 20 +- 1385 files changed, 16008 insertions(+), 16008 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 5dc1dce0e..931aea495 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -23,7 +23,7 @@ Changes from ns-3.36 to ns-3.37 ### Changes to existing API * Adds support for channel paging to the **LrWpanPhy** (only placeholder, a single modulation/band is currently supported). - + ### Changes to build system ### Changed behavior diff --git a/build-support/empty-main.cc b/build-support/empty-main.cc index dbbd85ecc..979a1cd78 100644 --- a/build-support/empty-main.cc +++ b/build-support/empty-main.cc @@ -1 +1 @@ -int main(){} \ No newline at end of file +int main(){} diff --git a/build-support/pybindings-LP64-to-ILP32.py b/build-support/pybindings-LP64-to-ILP32.py index 60ff0719c..5526ed2c9 100644 --- a/build-support/pybindings-LP64-to-ILP32.py +++ b/build-support/pybindings-LP64-to-ILP32.py @@ -13,4 +13,4 @@ def lp64_to_ilp32(lp64path, ilp32path): if __name__ == "__main__": import sys print(sys.argv) - exit(lp64_to_ilp32(sys.argv[1], sys.argv[2])) \ No newline at end of file + exit(lp64_to_ilp32(sys.argv[1], sys.argv[2])) diff --git a/doc/build.txt b/doc/build.txt index 2d3b1dd6d..c6386c85a 100644 --- a/doc/build.txt +++ b/doc/build.txt @@ -30,7 +30,7 @@ option is -d . Valid debug levels (which are listed in ns3 --help) are: "debug" or "optimized", with debug being default. It is also possible to change the flags used for compilation with (e.g.): CXXFLAGS="-O3" ./ns3 configure. By default, ns-3 is built as debug code, -with examples and tests disabled, and with python bindings enabled. +with examples and tests disabled, and with python bindings enabled. [ Note: Unlike some other build tools, to change the build target, the option must be supplied during the configure stage rather than diff --git a/doc/contributing.txt b/doc/contributing.txt index efd9fc62a..b8e4b1f68 100644 --- a/doc/contributing.txt +++ b/doc/contributing.txt @@ -2,6 +2,6 @@ Contributing to the ns-3 project -------------------------------- ns-3 is a free, open source software project that welcomes contributions -from users worldwide. Please see the following web page for how to -contribute: +from users worldwide. Please see the following web page for how to +contribute: http://www.nsnam.org/developers/contributing-code/ diff --git a/doc/contributing/pickle-to-xml.py b/doc/contributing/pickle-to-xml.py index be3126cf6..1f557370f 100755 --- a/doc/contributing/pickle-to-xml.py +++ b/doc/contributing/pickle-to-xml.py @@ -20,12 +20,12 @@ def dump_pickles(out, dirname, filename, path): out.write(' \n' % path) out.write(' %s.frag\n' % data['current_page_name']) if data['prev'] is not None: - out.write(' %s\n' % - (os.path.normpath(os.path.join(path, data['prev']['link'])), + out.write(' %s\n' % + (os.path.normpath(os.path.join(path, data['prev']['link'])), data['prev']['title'])) if data['next'] is not None: - out.write(' %s\n' % - (os.path.normpath(os.path.join(path, data['next']['link'])), + out.write(' %s\n' % + (os.path.normpath(os.path.join(path, data['next']['link'])), data['next']['title'])) out.write(' \n') f.close() diff --git a/doc/contributing/source/coding-style.rst b/doc/contributing/source/coding-style.rst index 13cff3185..e28a544a3 100644 --- a/doc/contributing/source/coding-style.rst +++ b/doc/contributing/source/coding-style.rst @@ -300,7 +300,7 @@ is described in the `Doxygen website `_. /** * Private method doxygen is also recommended */ - void MyPrivateMethod (void); + void MyPrivateMethod (void); int m_myPrivateMemberVariable; ///< Brief description of member variable }; @@ -415,7 +415,7 @@ Miscellaneous items - ``NS_LOG_COMPONENT_DEFINE("log-component-name");`` statements should be placed within namespace ns3 (for module code) and after the - ``using namespace ns3;``. In examples. + ``using namespace ns3;``. In examples. ``NS_OBJECT_ENSURE_REGISTERED()`` should also be placed within namespace ns3. - Const reference syntax: @@ -455,7 +455,7 @@ Miscellaneous items This guidance does not apply to the use of references to implement operators. - Expose class members through access functions, rather than direct access - to a public object. The access functions are typically named Get" and + to a public object. The access functions are typically named Get" and "Set". For example, a member m_delayTime might have accessor functions ``GetDelayTime ()`` and ``SetDelayTime ()``. diff --git a/doc/contributing/source/enhancements.rst b/doc/contributing/source/enhancements.rst index d27d63cb2..dbb50d8d0 100644 --- a/doc/contributing/source/enhancements.rst +++ b/doc/contributing/source/enhancements.rst @@ -35,7 +35,7 @@ the `issue tracker `_ for something that may be similar, and if nothing is found, please report the new issue. -If a user wants to submit proposed new code for |ns3|, please +If a user wants to submit proposed new code for |ns3|, please submit on the `merge request tracker `_. More details for each are provided below. Similarly, users who want to @@ -54,7 +54,7 @@ determined which module your bug is related to, if it is inside the official distribution (mainline), then create an issue, label it with the name of the module, and provide as much information as possible. -First, perform a cursory search on the +First, perform a cursory search on the `open issue list `_ to see if the problem has already been reported. If it has and the issue is still open, add a comment to the existing issue instead of opening a new one. @@ -89,12 +89,12 @@ Here are some additional guidelines: block formatting. 4. Describe the behavior you observed after following the steps and point out - what exactly is the problem with that behavior. Explain which behavior you + what exactly is the problem with that behavior. Explain which behavior you expected to see instead and why. 5. If you're reporting that ns-3 crashed, include a crash report with a stack trace from the operating system. On macOS, the crash report will - be available in Console.app under + be available in Console.app under `"Diagnostic and usage information" > "User diagnostic reports"`. Include the crash report in the issue in a code block, or a file attachment. @@ -117,7 +117,7 @@ If you are new to public Git repositories, you may want to read pull requests, the GitLab.com merge requests are very similar. In brief, you will want to fork ns-3-dev into your own namespace (i.e., -fork the repository into your personal GitLab.com account, via the user +fork the repository into your personal GitLab.com account, via the user interface on GitLab.com), clone your fork of ns-3-dev to your local machine, create a new feature branch that is based on the current tip of ns-3-dev, push that new feature branch up to your fork, @@ -129,7 +129,7 @@ Remember the documentation ========================== If you add or change API to the simulator, please include `Doxygen `_ changes as appropriate. Please scan the module documentation -(written in `Restructured Text `_ in the `docs` directory) to check if an update is needed to align with the patch proposal. +(written in `Restructured Text `_ in the `docs` directory) to check if an update is needed to align with the patch proposal. Commit message format ===================== @@ -155,11 +155,11 @@ more detail, you can add subsequent message lines below the first one, separated Date: Wed May 19 16:34:01 2021 +0200 lte: Assign default values - + Fixes crashing optimized/release builds with 'may be used uninitialized' error -3. The first line of the commit message should include the relevant module name or names, separated by a colon. Example: +3. The first line of the commit message should include the relevant module name or names, separated by a colon. Example: .. code-block:: text @@ -186,7 +186,7 @@ more detail, you can add subsequent message lines below the first one, separated 5. If the commit is from a merge request, that may also be added in a similar way the same by saying 'merges !NNN'. The exclamation point differentiates - merge requests from issues (which use the number sign '#') on GitLab.com. + merge requests from issues (which use the number sign '#') on GitLab.com. Example: .. code-block:: text diff --git a/doc/contributing/source/external.rst b/doc/contributing/source/external.rst index 80cd589ad..1c3fc2976 100644 --- a/doc/contributing/source/external.rst +++ b/doc/contributing/source/external.rst @@ -13,7 +13,7 @@ Submitting externally maintained code This chapter mainly pertains to code that will be maintained in external repositories (such as a personal or university research group repository, possibly hosted on GitHub or GitLab.com), -but for which the contributor wishes to keep consistent and compatible +but for which the contributor wishes to keep consistent and compatible with the |ns3| mainline. If the contributor does not want to maintain the external code @@ -226,7 +226,7 @@ Links to related projects ************************* Some projects choose to maintain their own version of |ns3|, or maintain models outside of the main tree of the code. In this case, the way to find out -about these is to look at the Related Projects page on the |ns3| +about these is to look at the Related Projects page on the |ns3| `wiki `_. If you know of externally maintained code that the project does not know about, @@ -241,15 +241,15 @@ app store so that there is a single place to discover them. Unmaintained, contributed code ****************************** -Anyone who wants to provide access to code that has been developed to +Anyone who wants to provide access to code that has been developed to extend |ns3| but that will not be further maintained may list its availability on our website. Furthermore, we can provide, in some circumstances, storage of a compressed archive on a web server if needed. -This type of code contribution will +This type of code contribution will not be listed in the app store, although popular extensions might be adopted by a future contributor. -We ask anyone who wishes to do this to provide at least this information +We ask anyone who wishes to do this to provide at least this information on our wiki: * Authors, @@ -259,6 +259,6 @@ on our wiki: * Status (how it is maintained) Please also make clear in your code the applicable software license. -The contribution will be stored on our `wiki `_. If you need web server +The contribution will be stored on our `wiki `_. If you need web server space for your archive, please contact ``webmaster@nsnam.org``. diff --git a/doc/contributing/source/general.rst b/doc/contributing/source/general.rst index e123baecd..d21c0996a 100644 --- a/doc/contributing/source/general.rst +++ b/doc/contributing/source/general.rst @@ -38,7 +38,7 @@ original. The Software Freedom Law Center has published `guidance `_ on handling this case. Note that it is incumbent upon the submitter to make sure that the -licensing attribution is correct and that the code is suitable for |ns3| +licensing attribution is correct and that the code is suitable for |ns3| inclusion. Do not include code (even snippets) from sources that have incompatible licenses. Even if the code licenses are compatible, do not copy someone else's code without attribution. @@ -171,7 +171,7 @@ these guidelines: main body of the code, for attribution purposes An example of a substantial modification that led to extension of -the authors section of the header can be found in +the authors section of the header can be found in ``src/lte/model/lte-ue-phy.h``:: * Author: Giuseppe Piro @@ -188,14 +188,14 @@ obtaining proper attribution and avoiding long headers. Coding style ************ -We ask that all contributors make their code conform to the +We ask that all contributors make their code conform to the coding standard which is outlined in :ref:`Coding style`. The project maintains a Python program called ``check-style.py`` found in the ``utils/`` directory. This is a wrapper around the ``uncrustify`` utility with configuration set to the conventions used by |ns3|, and can be used to quickly format new source code files proposed for the -mainline. +mainline. Additionally, the project also maintains a Python program called ``trim_trailing_whitespace.py``, found in the ``utils/`` directory. @@ -209,21 +209,21 @@ Patches are preferably submitted as a GitLab.com Short patches can be attached to an issue report or sent to the mailing-lists, but a Merge Request is the best way to submit. -The UNIX diff tool is the most common way of producing a patch: a patch is -a text-based representation of the difference between two text files or two -directories with text files in them. If you have two files, -``original.cc``, and, ``modified.cc``, you can generate a patch with the -command ``diff -u original.cc modified.cc``. If you wish to produce a patch +The UNIX diff tool is the most common way of producing a patch: a patch is +a text-based representation of the difference between two text files or two +directories with text files in them. If you have two files, +``original.cc``, and, ``modified.cc``, you can generate a patch with the +command ``diff -u original.cc modified.cc``. If you wish to produce a patch between two directories, use the command ``diff -uprN original modified``. -Make sure you specify to the reviewer where the original files came from -and make sure that the resulting patch file does not contain unexpected +Make sure you specify to the reviewer where the original files came from +and make sure that the resulting patch file does not contain unexpected content by performing a final inspection of the patch file yourself. -Patches such as this are sufficient for simple bug fixes or very simple +Patches such as this are sufficient for simple bug fixes or very simple small features. -Git can be used to create a patch of what parts differ from the last +Git can be used to create a patch of what parts differ from the last committed code; try:: $ git diff @@ -247,7 +247,7 @@ Maintainers Maintainers are the set of people who make decisions on code and documentation changes. Maintainers are contributors who have demonstrated, over time, knowledge and good judgment as pertains to contributions to |ns3|, and who -have expressed willingness to maintain some code. |ns3| is like other +have expressed willingness to maintain some code. |ns3| is like other open source projects in terms of how people gradually become maintainers as their involvement with the project deepens; maintainers are not newcomers to the project. @@ -255,14 +255,14 @@ to the project. The list of maintainers for each module is found here: https://www.nsnam.org/developers/maintainers/ -Maintainers review code (bug fixes, new models) within scope of their +Maintainers review code (bug fixes, new models) within scope of their maintenance responsibility. A maintainer of a module should "sign off" (or approve of) changes to an |ns3| module before it is committed to the main codebase. Note that we typically do not formalize the signing off using Git's sign off feature, but instead, maintainers will indicate their approval of the merge request using GitLab.com. -Note that some modules do not have active maintainers; these types of +Note that some modules do not have active maintainers; these types of modules typically receive less maintenance attention than those with active maintainers (and bugs may linger unattended). diff --git a/doc/contributing/source/introduction.rst b/doc/contributing/source/introduction.rst index 9313e81f3..7e4b405fa 100644 --- a/doc/contributing/source/introduction.rst +++ b/doc/contributing/source/introduction.rst @@ -22,12 +22,12 @@ End users are encouraged to report issues and bugs, or to propose software or documentation modifications, to be reviewed by and handled by maintainers. End users can also help by reviewing code proposals made by others. Some end users who contribute high quality -patches or code reviews over time may ask or be invited to become +patches or code reviews over time may ask or be invited to become a maintainer of software within their areas of expertise. Finally, some end users wish to disseminate their |ns3| work to the community, through the addition of new features or modules to |ns3|. -A question often asked by newcomers is "How can I contribute to |ns3|?" +A question often asked by newcomers is "How can I contribute to |ns3|?" or "How do I get started?". This document summarizes the various ways and processes used to contribute to |ns3|. Contribution by users is essential for a project maintained @@ -37,8 +37,8 @@ contributors to please become familiar with conventions and processes used by |ns3| so as to smooth the contribution process. The very first step is to become familiar with |ns3| by reading the tutorial, -running some example programs, and then reading some of the code and -documentation to get a feel for things. From that point, there are a +running some example programs, and then reading some of the code and +documentation to get a feel for things. From that point, there are a number of options to contribute: * Contributing a small documentation correction @@ -54,7 +54,7 @@ number of options to contribute: how to contribute |ns3| code specifically, but the overall open source project maintains various related codebases written in several other languages, so if you are interested in contributing outside of |ns3| -C++ code, there are several possibilities: +C++ code, there are several possibilities: * |ns3| provides Python bindings to most of its API, and maintains an automated API scanning process that relies on other tools. We can use @@ -64,7 +64,7 @@ C++ code, there are several possibilities: * The `NetAnim `_ animator is written in `Qt `_ and has lacked a maintainer for several years. * If you are interested in Linux kernel hacking, or use of applications in |ns3| such as open source routing daemons, we maintain the `Direct Code Execution project `_. -* If you are familiar with `Django `_, we have work to do on `our app store infrastructure `_. +* If you are familiar with `Django `_, we have work to do on `our app store infrastructure `_. * Our `website `_ is written in `Jekyll `_ and is in need of more work. The remainder of this document is organized as follows. diff --git a/doc/contributing/source/models.rst b/doc/contributing/source/models.rst index 14a3f11d2..995c915be 100644 --- a/doc/contributing/source/models.rst +++ b/doc/contributing/source/models.rst @@ -10,12 +10,12 @@ Submitting new models --------------------- -We actively encourage submission of new features to |ns3|. +We actively encourage submission of new features to |ns3|. Independent submissions are essential for open source projects, and if accepted into the mainline, you will also be credited as an author of -future versions of |ns3|. However, +future versions of |ns3|. However, please keep in mind that there is already a large burden on the |ns3| -maintainers to manage the flow of incoming contributions and maintain new +maintainers to manage the flow of incoming contributions and maintain new and existing code. The goal of this chapter is to outline the options for new models in |ns3|, and how you can help to minimize the burden on maintainers and thus minimize the average time-to-merge of your code. @@ -43,7 +43,7 @@ The options for publishing new models are: 1. Propose a Merge Request for the |ns3| mainline and follow the guidelines below. -2. Organize your code as a "contributed module" or modules and maintain them in +2. Organize your code as a "contributed module" or modules and maintain them in your own public Git repository. A page on the App Store can be made to advertise this to users, and other tooling can be used to ensure that the module stays compatible with the mainline. @@ -59,7 +59,7 @@ The options for publishing new models are: changes so that public forks can be avoided. 4. Archive your code somewhere, or publish in a Git repository, and link to - it from the |ns3| `Contributed Code `_ + it from the |ns3| `Contributed Code `_ wiki page. This option requires the least amount of work from the contributor, but visibility of the code to new |ns3| users will likely be reduced. To follow this route, obtain a wiki account from the webmaster, @@ -70,13 +70,13 @@ other options are described in the next chapter (:ref:`External`). Upstreaming new models ********************** -The term "upstreaming" refers to the process whereby new code is +The term "upstreaming" refers to the process whereby new code is contributed back to an upstream source (the main open source project) whereby that project takes responsibility for further enhancement and maintenance. -Making sure that each code submission fulfills as many items -as possible in the following checklist is the best way to ensure quick +Making sure that each code submission fulfills as many items +as possible in the following checklist is the best way to ensure quick merging of your code. In brief, we can summarize the guidelines as follows: @@ -87,12 +87,12 @@ In brief, we can summarize the guidelines as follows: engineering and consistency feedback that maintainers may provide 4. Write associated documentation, tests, and example programs -If you do not have the time to follow through the process to include your +If you do not have the time to follow through the process to include your code in the main tree, please see the next chapter (:ref:`External`) about contributing ns-3 code that is not maintained in the main tree. The process can take a long time when submissions are large or when -contributors skip some of these steps. Therefore, best results are found +contributors skip some of these steps. Therefore, best results are found when the following guidelines are followed: * Ask for review of small chunks of code, rather than large patches. Split @@ -215,7 +215,7 @@ documentation, test code, and example scripts. Note that you may want to go through multiple phases of code reviews, and all of this supporting material may not be needed at the first stage (e.g. -when you want some feedback on public API header declarations only, before +when you want some feedback on public API header declarations only, before starting the implementation). However, when it times come to merge your code, you should be prepared to provide these things, as fits your contribution (maintainers will provide some guidance here). diff --git a/doc/main.h b/doc/main.h index d4bde1b67..bd7b84fc0 100644 --- a/doc/main.h +++ b/doc/main.h @@ -6,28 +6,28 @@ * \mainpage ns-3 Documentation * * \section intro-sec Introduction - * ns-3 documentation is maintained using + * ns-3 documentation is maintained using * Doxygen. - * Doxygen is typically used for + * Doxygen is typically used for * API documentation, and organizes such documentation across different * modules. This project uses Doxygen for building the definitive - * maintained API documentation. Additional ns-3 project documentation + * maintained API documentation. Additional ns-3 project documentation * can be found at the * project web site. * * \section install-sec Building the Documentation - * + * * Building ns-3 Doxygen requires Doxygen version 1.8 at a minimum, but version 1.9 is recommended to minimize warnings. - * + * * Type "./ns3 docs doxygen" or "./ns3 docs doxygen-no-build" to build the * documentation. The doc/ directory contains - * configuration for Doxygen (doxygen.conf) and main.h. The Doxygen - * build process puts html files into the doc/html/ directory, and latex + * configuration for Doxygen (doxygen.conf) and main.h. The Doxygen + * build process puts html files into the doc/html/ directory, and latex * filex into the doc/latex/ directory. - * + * * \section module-sec Module overview * - * The ns-3 library is split across many modules organized under the + * The ns-3 library is split across many modules organized under the * Modules tab. * - aodv * - applications @@ -78,10 +78,10 @@ /** * \name Macros defined by the build system. - * + * * These have to be visible for doxygen to document them, * so we put them here in a file only seen by doxygen, not the compiler. - * + * * @{ */ /** diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 69e86cd0f..1c6bd19bf 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -58,9 +58,9 @@ SOURCES = \ ${SRC}/stats/doc/adaptor.rst \ ${SRC}/stats/doc/scope-and-limitations.rst \ -# list all manual figure files that need to be copied to +# list all manual figure files that need to be copied to # $SOURCETEMP/figures. For each figure to be included in all -# documentation formats (html, latex...) the following formats are supported: +# documentation formats (html, latex...) the following formats are supported: # 1) a single .dia file (preferred option, because it can be edited) # 2) a single .eps file # 3) both a .pdf and .png file @@ -170,7 +170,7 @@ help: copy-sources: $(SOURCES) @rm -rf $(SOURCETEMP) - @mkdir -p $(SOURCETEMP) + @mkdir -p $(SOURCETEMP) @mkdir -p $(FIGURES) @cp -r $(SOURCES) $(SOURCETEMP) @cp -r $(SOURCEFIGS) $(FIGURES) diff --git a/doc/manual/source/attributes.rst b/doc/manual/source/attributes.rst index 1608aa879..f55a57fba 100644 --- a/doc/manual/source/attributes.rst +++ b/doc/manual/source/attributes.rst @@ -1261,7 +1261,7 @@ The typical use-cases are: As a matter of fact, some Objects might be created when the simulation starts. Hence, ConfigStore will not "report" their attributes if invoked earlier in the code. -A typical workflow might involve running the simulation, calling ConfigStore +A typical workflow might involve running the simulation, calling ConfigStore at the end of the simulation (after ``Simulator::Run ()`` and before ``Simulator::Destroy ()``) This will show all the attributes in the Objects, both those with default values, and those with values changed during the simulation execution. @@ -1277,7 +1277,7 @@ ConfigStore GUI There is a GTK-based front end for the ConfigStore. This allows users to use a GUI to access and change variables. -Some screenshots are presented here. They are the result of using GtkConfig on +Some screenshots are presented here. They are the result of using GtkConfig on ``src/lte/examples/lena-dual-stripe.cc`` after ``Simulator::Run ()``. .. _GtkConfig: diff --git a/doc/manual/source/callbacks.rst b/doc/manual/source/callbacks.rst index 70ef94567..2c353e54f 100644 --- a/doc/manual/source/callbacks.rst +++ b/doc/manual/source/callbacks.rst @@ -48,7 +48,7 @@ independent compilation units in the simulator) and is not generalized; if in a later usage scenario, B needs to talk to a completely different C object, the source code for B needs to be changed to add a ``c_instance`` and so forth. It is easy to see that this is a brute force mechanism of communication that can -lead to programming cruft in the models. +lead to programming cruft in the models. This is not to say that objects should not know about one another if there is a hard dependency between them, but that often the model can be made more flexible @@ -182,14 +182,14 @@ calling function from the called class completely. This requirement led to the development of the *Functor*. A functor is the outgrowth of something invented in the 1960s called a closure. -It is basically just a packaged-up function call, possibly with some state. +It is basically just a packaged-up function call, possibly with some state. A functor has two parts, a specific part and a generic part, related through inheritance. The calling code (the code that executes the callback) will execute a generic overloaded ``operator ()`` of a generic functor to cause the callback to be called. The called code (the code that wants to be called back) will have to provide a specialized implementation of the ``operator ()`` that performs the -class-specific work that caused the close-coupling problem above. +class-specific work that caused the close-coupling problem above. With the specific functor and its overloaded ``operator ()`` created, the called code then gives the specialized code to the module that will execute the @@ -201,7 +201,7 @@ functor. This means that the calling module just needs to understand the generic functor type. It is decoupled from the calling code completely. The information one needs to make a specific functor is the object pointer and -the pointer-to-method address. +the pointer-to-method address. The essence of what needs to happen is that the system declares a generic part of the functor:: @@ -213,7 +213,7 @@ of the functor:: virtual int operator() (T arg) = 0; }; -The caller defines a specific part of the functor that really is just there to +The caller defines a specific part of the functor that really is just there to implement the specific ``operator()`` method:: template @@ -256,11 +256,11 @@ Here is an example of the usage:: } .. note:: The previous code is not real ns-3 code. It is simplistic example - code used only to illustrate the concepts involved and to help you understand + code used only to illustrate the concepts involved and to help you understand the system more. Do not expect to find this code anywhere in the ns-3 tree. -Notice that there are two variables defined in the class above. The m_p -variable is the object pointer and m_pmi is the variable containing the +Notice that there are two variables defined in the class above. The m_p +variable is the object pointer and m_pmi is the variable containing the address of the function to execute. Notice that when ``operator()`` is called, it in turn calls the method provided @@ -271,16 +271,16 @@ as a parameter:: void LibraryFunction (Functor functor); -The code that will talk to the model would build a specific functor and pass it to ``LibraryFunction``:: +The code that will talk to the model would build a specific functor and pass it to ``LibraryFunction``:: MyClass myClass; SpecificFunctor functor (&myclass, MyClass::MyMethod); -When ``LibraryFunction`` is done, it executes the callback using the +When ``LibraryFunction`` is done, it executes the callback using the ``operator()`` on the generic functor it was passed, and in this particular case, provides the integer argument:: - void + void LibraryFunction (Functor functor) { // Execute the library function @@ -291,11 +291,11 @@ Notice that ``LibraryFunction`` is completely decoupled from the specific type of the client. The connection is made through the Functor polymorphism. The Callback API in |ns3| implements object-oriented callbacks using -the functor mechanism. This callback API, being based on C++ templates, is +the functor mechanism. This callback API, being based on C++ templates, is type-safe; that is, it performs static type checks to enforce proper signature -compatibility between callers and callees. It is therefore more type-safe to -use than traditional function pointers, but the syntax may look imposing at -first. This section is designed to walk you through the Callback system so +compatibility between callers and callees. It is therefore more type-safe to +use than traditional function pointers, but the syntax may look imposing at +first. This section is designed to walk you through the Callback system so that you can be comfortable using it in |ns3|. Using the Callback API @@ -340,39 +340,39 @@ a ``this`` pointer. The function template ``Callback`` is essentially the declaration of the variable containing the pointer-to-function. In the example above, we explicitly showed a pointer to a function that returned an integer and took a single integer as a parameter, The ``Callback`` template function is -a generic version of that -- it is used to declare the type of a callback. +a generic version of that -- it is used to declare the type of a callback. .. note:: Readers unfamiliar with C++ templates may consult ``_. -The ``Callback`` template requires one mandatory argument (the return type -of the function to be assigned to this callback) and up to five optional +The ``Callback`` template requires one mandatory argument (the return type +of the function to be assigned to this callback) and up to five optional arguments, which each specify the type of the arguments (if your particular callback function has more than five arguments, then this can be handled by extending the callback implementation). So in the above example, we have a declared a callback named "one" that will eventually hold a function pointer. The signature of the function that it will -hold must return double and must support two double arguments. If one tries -to pass a function whose signature does not match the declared callback, +hold must return double and must support two double arguments. If one tries +to pass a function whose signature does not match the declared callback, a compilation error will occur. Also, if one tries to assign to a callback -an incompatible one, compilation will succeed but a run-time -NS_FATAL_ERROR will be raised. The sample program +an incompatible one, compilation will succeed but a run-time +NS_FATAL_ERROR will be raised. The sample program ``src/core/examples/main-callback.cc`` demonstrates both of these error cases at the end of the ``main()`` program. Now, we need to tie together this callback instance and the actual target function -(CbOne). Notice above that CbOne has the same function signature types as the -callback-- this is important. We can pass in any such properly-typed function +(CbOne). Notice above that CbOne has the same function signature types as the +callback-- this is important. We can pass in any such properly-typed function to this callback. Let's look at this more closely:: static double CbOne (double a, double b) {} ^ ^ ^ | | | - | | | + | | | Callback one; You can only bind a function to a callback if they have the matching signature. -The first template argument is the return type, and the additional template +The first template argument is the return type, and the additional template arguments are the types of the arguments of the function signature. Now, let's bind our callback "one" to the function that matches its signature:: @@ -381,9 +381,9 @@ Now, let's bind our callback "one" to the function that matches its signature:: one = MakeCallback (&CbOne); This call to ``MakeCallback`` is, in essence, creating one of the specialized -functors mentioned above. The variable declared using the ``Callback`` +functors mentioned above. The variable declared using the ``Callback`` template function is going to be playing the part of the generic functor. The -assignment ``one = MakeCallback (&CbOne)`` is the cast that converts the +assignment ``one = MakeCallback (&CbOne)`` is the cast that converts the specialized functor known to the callee to a generic functor known to the caller. Then, later in the program, if the callback is needed, it can be used as follows:: @@ -394,18 +394,18 @@ Then, later in the program, if the callback is needed, it can be used as follows double retOne; retOne = one (10.0, 20.0); -The check for ``IsNull()`` ensures that the callback is not null -- that there +The check for ``IsNull()`` ensures that the callback is not null -- that there is a function to call behind this callback. Then, ``one()`` executes the generic ``operator()`` which is really overloaded with a specific implementation -of ``operator()`` and returns the same result as if ``CbOne()`` had been +of ``operator()`` and returns the same result as if ``CbOne()`` had been called directly. Using the Callback API with member functions ++++++++++++++++++++++++++++++++++++++++++++ -Generally, you will not be calling static functions but instead public member -functions of an object. In this case, an extra argument is needed to the -MakeCallback function, to tell the system on which object the function should be +Generally, you will not be calling static functions but instead public member +functions of an object. In this case, an extra argument is needed to the +MakeCallback function, to tell the system on which object the function should be invoked. Consider this example, also from main-callback.cc:: class MyCb { @@ -429,7 +429,7 @@ invoked. Consider this example, also from main-callback.cc:: } Here, we pass an additional object pointer to the ``MakeCallback<>`` function. -Recall from the background section above that ``Operator()`` will use the pointer to +Recall from the background section above that ``Operator()`` will use the pointer to member syntax when it executes on an object:: virtual int operator() (ARG arg) @@ -446,8 +446,8 @@ does precisely that. In this case, when ``two ()`` is invoked:: int result = two (1.0); -will result in a call to the ``CbTwo`` member function (method) on the object -pointed to by ``&cb``. +will result in a call to the ``CbTwo`` member function (method) on the object +pointed to by ``&cb``. Building Null Callbacks +++++++++++++++++++++++ @@ -466,21 +466,21 @@ crash at runtime. Bound Callbacks *************** -A very useful extension to the functor concept is that of a Bound Callback. -Previously it was mentioned that closures were originally function calls -packaged up for later execution. Notice that in all of the Callback -descriptions above, there is no way to package up any parameters for use -later -- when the ``Callback`` is called via ``operator()``. All of -the parameters are provided by the calling function. +A very useful extension to the functor concept is that of a Bound Callback. +Previously it was mentioned that closures were originally function calls +packaged up for later execution. Notice that in all of the Callback +descriptions above, there is no way to package up any parameters for use +later -- when the ``Callback`` is called via ``operator()``. All of +the parameters are provided by the calling function. What if it is desired to allow the client function (the one that provides the callback) to provide some of the parameters? `Alexandrescu `_ calls the process of -allowing a client to specify one of the parameters *"binding"*. One of the +allowing a client to specify one of the parameters *"binding"*. One of the parameters of ``operator()`` has been bound (fixed) by the client. Some of our pcap tracing code provides a nice example of this. There is a function that needs to be called whenever a packet is received. This function -calls an object that actually writes the packet to disk in the pcap file +calls an object that actually writes the packet to disk in the pcap file format. The signature of one of these functions will be:: static void DefaultSink (Ptr file, Ptr p); @@ -492,8 +492,8 @@ the calling code is just a call that looks like:: m_promiscSnifferTrace (m_currentPkt); -What we want to do is to *bind* the ``Ptr file`` to the -specific callback implementation when it is created and arrange for the +What we want to do is to *bind* the ``Ptr file`` to the +specific callback implementation when it is created and arrange for the ``operator()`` of the Callback to provide that parameter for free. We provide the ``MakeBoundCallback`` template function for that purpose. It @@ -585,9 +585,9 @@ itself. The actual Callback code is quite complicated and very template-intense a deep understanding of the code is not required. If interested, expert users may find the following useful. -The code was originally written based on the techniques described in +The code was originally written based on the techniques described in ``_. -It was subsequently rewritten to follow the architecture outlined in +It was subsequently rewritten to follow the architecture outlined in `Modern C++ Design, Generic Programming and Design Patterns Applied, Alexandrescu, chapter 5, Generalized Functors `_. This code uses: @@ -605,6 +605,6 @@ This code uses: value semantics. This code most notably departs from the Alexandrescu implementation in that it -does not use type lists to specify and pass around the types of the callback -arguments. Of course, it also does not use copy-destruction semantics and +does not use type lists to specify and pass around the types of the callback +arguments. Of course, it also does not use copy-destruction semantics and relies on a reference list rather than autoPtr to hold the pointer. diff --git a/doc/manual/source/conf.py b/doc/manual/source/conf.py index bedb37bcc..46a0f3ba6 100644 --- a/doc/manual/source/conf.py +++ b/doc/manual/source/conf.py @@ -24,7 +24,7 @@ import sys, os # To change default code-block format in Latex to footnotesize (8pt) # Tip from https://stackoverflow.com/questions/9899283/how-do-you-change-the-code-example-font-size-in-latex-pdf-output-with-sphinx/9955928 -# Note: sizes are \footnotesize (8pt), \small (9pt), and \normalsize (10pt). +# Note: sizes are \footnotesize (8pt), \small (9pt), and \normalsize (10pt). #from sphinx.highlighting import PygmentsBridge #from pygments.formatters.latex import LatexFormatter @@ -273,7 +273,7 @@ latex_elements = { # (double backquotes) to either \footnotesize (8pt) or \small (9pt) # # See above to change the font size of verbatim code blocks - # + # # 'preamble': '', 'preamble': u'''\\usepackage{amssymb} \\definecolor{VerbatimBorderColor}{rgb}{1,1,1} diff --git a/doc/manual/source/documentation.rst b/doc/manual/source/documentation.rst index c63e84085..46d59d49d 100644 --- a/doc/manual/source/documentation.rst +++ b/doc/manual/source/documentation.rst @@ -14,7 +14,7 @@ The API documentation is generated from the source code itself, using Doxygen_, to generate cross-linked web pages. Both of these are important: the Sphinx chapters explain the *why* and overview of using a model; the API documentation explains the -*how* details. +*how* details. This chapter gives a quick overview of these tools, emphasizing preferred usage and customizations for |ns3|. @@ -64,7 +64,7 @@ all go in the ``src/foo/doc/`` directory. The docs are actually built by a Sphinx Makefile. For especially involved documentation, it may be helpful to have a local ``Makefile`` in the ``src/foo/doc/`` directory to -simplify building the documentation for this module +simplify building the documentation for this module (`Antenna`_ is an example). Setting this up is not particularly hard, but is beyond the scope of this chapter. @@ -87,7 +87,7 @@ To add your chapter there, edit ``doc/models/source/index.rst`` .. toctree:: :maxdepth: 1 - + organization animation antenna @@ -127,7 +127,7 @@ your image files. Again, please keep these in alphabetical order. Building Sphinx Docs ==================== -Building the Sphinx documentation is pretty simple. +Building the Sphinx documentation is pretty simple. To build all the Sphinx documentation: .. sourcecode:: bash @@ -175,12 +175,12 @@ the basics here, instead focusing on preferred usage for |ns3|. * Start documents with these two lines: - + .. sourcecode:: rest - + .. include:: replace.txt .. highlight:: cpp - + The first line enables some simple replacements. For example, typing ``|ns3|`` renders as |ns3|. The second sets the default source code highlighting language explicitly @@ -189,12 +189,12 @@ the basics here, instead focusing on preferred usage for |ns3|. see below.) * Sections: - + Sphinx is pretty liberal about marking section headings. By convention, we prefer this hierarchy: - + .. sourcecode:: rest - + .. heading hierarchy: ------------- Chapter ************* Section (#.#) @@ -202,7 +202,7 @@ the basics here, instead focusing on preferred usage for |ns3|. ############# Sub-subsection * Syntax Highlighting: - + To use the default syntax highlighter, simply start a sourcecode block: +--------------------------------------+------------------------------------+ @@ -227,7 +227,7 @@ the basics here, instead focusing on preferred usage for |ns3|. | | | | $ ls | $ ls | +--------------------------------------+------------------------------------+ - + * Shorthand Notations: These shorthands are defined: @@ -390,7 +390,7 @@ script: .. sourcecode:: bash $ doc/doxygen.warnings.report.sh - + doxygen.warnings.report.sh: Building and running print-introspected-doxygen...done. Rebuilding doxygen (v1.8.10) docs with full errors...done. @@ -545,7 +545,7 @@ usage for |ns3|. */ or in the corresponding ``.cc`` file:: - + /** * \file * \ingroup foo @@ -570,7 +570,7 @@ usage for |ns3|. * \param ale The size of a pint of ale, in Imperial ounces. */ typedef void (* BarCallback)(const int ale); - + * Copy the ``Attribute`` help strings from the ``GetTypeId`` method to use as the brief descriptions of associated members. @@ -586,7 +586,7 @@ usage for |ns3|. The allowed values of the direction token are ``[in]``, ``[out]``, and ``[in,out]`` (note the explicit square brackets), as discussed in the Doxygen docs for ``\param``. - + * Document template arguments with ``\tparam``, just as you use ``\param`` for function arguments. diff --git a/doc/manual/source/enable-modules.rst b/doc/manual/source/enable-modules.rst index 39b4a758d..24790c6d5 100644 --- a/doc/manual/source/enable-modules.rst +++ b/doc/manual/source/enable-modules.rst @@ -4,7 +4,7 @@ Enabling Subsets of |ns3| Modules --------------------------------- -As with most software projects, |ns3| is ever growing larger in terms of number of modules, lines of code, and memory footprint. Users, however, may only use a few of those modules at a time. For this reason, users may want to explicitly enable only the subset of the possible |ns3| modules that they actually need for their research. +As with most software projects, |ns3| is ever growing larger in terms of number of modules, lines of code, and memory footprint. Users, however, may only use a few of those modules at a time. For this reason, users may want to explicitly enable only the subset of the possible |ns3| modules that they actually need for their research. This chapter discusses how to enable only the |ns3| modules that you are interested in using. @@ -23,7 +23,7 @@ If the module has a test library and test libraries are being built, then libns3-modulename-test.so -will be built, too. Other modules that the module depends on and their test libraries will also be built. +will be built, too. Other modules that the module depends on and their test libraries will also be built. By default, all modules are built in |ns3|. There are two ways to enable a subset of these modules: @@ -52,7 +52,7 @@ and the following libraries should be present: Note the ``./ns3 clean`` step is done here only to make it more obvious which module libraries were built. You don't have to do ``./ns3 clean`` in order to enable subsets of modules. Running test.py will cause only those tests that depend on module core to be run: - + .. sourcecode:: text 24 of 24 tests passed (24 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) @@ -94,16 +94,16 @@ The .ns3rc file should now be in your top level |ns3| directory, and it contains .. sourcecode:: python #! /usr/bin/env python - + # A list of the modules that will be enabled when ns-3 is run. # Modules that depend on the listed modules will be enabled also. # # All modules can be enabled by choosing 'all_modules'. modules_enabled = ['all_modules'] - + # Set this equal to true if you want examples to be run. examples_enabled = False - + # Set this equal to true if you want tests to be run. tests_enabled = False @@ -112,16 +112,16 @@ Use your favorite editor to modify the .ns3rc file to only enable the core modul .. sourcecode:: python #! /usr/bin/env python - + # A list of the modules that will be enabled when ns-3 is run. # Modules that depend on the listed modules will be enabled also. # # All modules can be enabled by choosing 'all_modules'. modules_enabled = ['core'] - + # Set this equal to true if you want examples to be run. examples_enabled = True - + # Set this equal to true if you want tests to be run. tests_enabled = True @@ -143,7 +143,7 @@ and the following libraries should be present: Note the ``./ns3 clean`` step is done here only to make it more obvious which module libraries were built. You don't have to do ``./ns3 clean`` in order to enable subsets of modules. Running test.py will cause only those tests that depend on module core to be run: - + .. sourcecode:: text 24 of 24 tests passed (24 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) diff --git a/doc/manual/source/enable-tests.rst b/doc/manual/source/enable-tests.rst index b17661c0e..6bc44ec5d 100644 --- a/doc/manual/source/enable-tests.rst +++ b/doc/manual/source/enable-tests.rst @@ -23,7 +23,7 @@ Enable/disable examples and tests using build.py You can use build.py to enable/disable examples and tests when |ns3| is built for the first time. -By default, examples and tests are not built in |ns3|. +By default, examples and tests are not built in |ns3|. From the ns-3-allinone directory, you can build |ns3| without any examples or tests simply by doing: :: @@ -31,7 +31,7 @@ examples or tests simply by doing: :: $ ./build.py Running test.py in the top level |ns3| directory now will cause no examples or tests to be run: - + .. sourcecode:: text 0 of 0 tests passed (0 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) @@ -41,7 +41,7 @@ If you would like build |ns3| with examples and tests, then do the following fro $ ./build.py --enable-examples --enable-tests Running test.py in the top level |ns3| directory will cause all of the examples and tests to be run: - + .. sourcecode:: text 170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) @@ -51,7 +51,7 @@ Enable/disable examples and tests using ns3 You can use ns3 to enable/disable examples and tests once |ns3| has been built. -By default, examples and tests are not built in |ns3|. +By default, examples and tests are not built in |ns3|. From the top level |ns3| directory, you can build |ns3| without any examples or tests simply by doing: :: @@ -60,7 +60,7 @@ examples or tests simply by doing: :: $ ./ns3 build Running test.py now will cause no examples or tests to be run: - + .. sourcecode:: text 0 of 0 tests passed (0 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) @@ -71,7 +71,7 @@ If you would like build |ns3| with examples and tests, then do the following fro $ ./ns3 build Running test.py will cause all of the examples and tests to be run: - + .. sourcecode:: text 170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) @@ -101,16 +101,16 @@ The .ns3rc file should now be in your top level |ns3| directory, and it contains .. sourcecode:: python #! /usr/bin/env python - + # A list of the modules that will be enabled when ns-3 is run. # Modules that depend on the listed modules will be enabled also. # # All modules can be enabled by choosing 'all_modules'. modules_enabled = ['all_modules'] - + # Set this equal to true if you want examples to be run. examples_enabled = False - + # Set this equal to true if you want tests to be run. tests_enabled = False @@ -121,7 +121,7 @@ examples or tests simply by doing: :: $ ./ns3 build Running test.py now will cause no examples or tests to be run: - + .. sourcecode:: text 0 of 0 tests passed (0 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) @@ -133,16 +133,16 @@ examples_enabled and tests_enabled file to be True: .. sourcecode:: python #! /usr/bin/env python - + # A list of the modules that will be enabled when ns-3 is run. # Modules that depend on the listed modules will be enabled also. # # All modules can be enabled by choosing 'all_modules'. modules_enabled = ['all_modules'] - + # Set this equal to true if you want examples to be run. examples_enabled = True - + # Set this equal to true if you want tests to be run. tests_enabled = True @@ -153,7 +153,7 @@ and tests simply by doing: :: $ ./ns3 build Running test.py will cause all of the examples and tests to be run: - + .. sourcecode:: text 170 of 170 tests passed (170 passed, 0 skipped, 0 failed, 0 crashed, 0 valgrind errors) diff --git a/doc/manual/source/events.rst b/doc/manual/source/events.rst index 5c1fd28b8..6db0a280e 100644 --- a/doc/manual/source/events.rst +++ b/doc/manual/source/events.rst @@ -18,19 +18,19 @@ events in sequential time order. Once the completion of an event occurs, the simulator will move to the next event (or will exit if there are no more events in the event queue). If, for example, an event scheduled for simulation time "100 seconds" is executed, and the next event is not -scheduled until "200 seconds", the simulator will immediately jump from +scheduled until "200 seconds", the simulator will immediately jump from 100 seconds to 200 seconds (of simulation time) to execute the next event. This is what is meant by "discrete-event" simulator. To make this all happen, the simulator needs a few things: -1) a simulator object that can access an event queue where events are +1) a simulator object that can access an event queue where events are stored and that can manage the execution of events 2) a scheduler responsible for inserting and removing events from the queue 3) a way to represent simulation time 4) the events themselves -This chapter of the manual describes these fundamental objects +This chapter of the manual describes these fundamental objects (simulator, scheduler, time, event) and how they are used. Event @@ -88,7 +88,7 @@ Notes: support more arguments, please, file a bug report. * Readers familiar with the term 'fully-bound functors' will recognize the Simulator::Schedule methods as a way to automatically construct such - objects. + objects. 2) Common scheduling operations @@ -139,7 +139,7 @@ node, its 'context' is set to 0xffffffff. To associate a context to each event, the Schedule, and ScheduleNow methods automatically reuse the context of the currently-executing event -as the context of the event scheduled for execution later. +as the context of the event scheduled for execution later. In some cases, most notably when simulating the transmission of a packet from a node to another, this behavior is undesirable since the expected @@ -190,14 +190,14 @@ context. Available Simulator Engines =========================== -|ns3| supplies two different types of basic simulator engine to manage +|ns3| supplies two different types of basic simulator engine to manage event execution. These are derived from the abstract base class `SimulatorImpl`: -* `DefaultSimulatorImpl` This is a classic sequential discrete event - simulator engine which uses a single thread of execution. This engine +* `DefaultSimulatorImpl` This is a classic sequential discrete event + simulator engine which uses a single thread of execution. This engine executes events as fast as possible. -* `DistributedSimulatorImpl` This is a classic YAWNS distributed ("parallel") - simulator engine. By labeling and instantiating your model components +* `DistributedSimulatorImpl` This is a classic YAWNS distributed ("parallel") + simulator engine. By labeling and instantiating your model components appropriately this engine will execute the model in parallel across many compute processes, yet in a time-synchronized way, as if the model had executed sequentially. The two advantages are to execute models faster @@ -209,7 +209,7 @@ event execution. These are derived from the abstract base class `SimulatorImpl` instantiation of model components. This engine attempts to execute events as fast as possible. -You can choose which simulator engine to use by setting a global variable, +You can choose which simulator engine to use by setting a global variable, for example:: GlobalValue::Bind ("SimulatorImplementationType", @@ -222,28 +222,28 @@ or by using a command line argument:: $ ./ns3 run "... -–SimulatorImplementationType=ns3::DistributedSimulatorImpl" In addition to the basic simulator engines there is a general facility used -to build "adapters" which provide small behavior modifications to one of -the core `SimulatorImpl` engines. The adapter base class is +to build "adapters" which provide small behavior modifications to one of +the core `SimulatorImpl` engines. The adapter base class is `SimulatorAdapter`, itself derived from `SimulatorImpl`. `SimluatorAdapter` uses the `PIMPL (pointer to implementation) `_ -idiom to forward all calls to the configured base simulator engine. +idiom to forward all calls to the configured base simulator engine. This makes it easy to provide small customizations -just by overriding the specific Simulator calls needed, and allowing -`SimulatorAdapter` to handle the rest. +just by overriding the specific Simulator calls needed, and allowing +`SimulatorAdapter` to handle the rest. There are few places where adapters are used currently: -* `ReadltimeSimulatorImpl` This adapter attempts to execute in real time - by pacing the wall clock evolution. This pacing is "best effort", +* `ReadltimeSimulatorImpl` This adapter attempts to execute in real time + by pacing the wall clock evolution. This pacing is "best effort", meaning actual event execution may not occur exactly in sync, but - close to it. This engine is normally only used with the + close to it. This engine is normally only used with the `DefaultSimulatorImpl`, but it can be used to keep a distributed simulation synchronized with real time. See the :doc:`realtime` chapter. -* `VisualSimulatorImpl` This adapter starts a live visualization of the +* `VisualSimulatorImpl` This adapter starts a live visualization of the running simulation, showing the network graph and each packet traversing the links. * `LocalTimeSimulatorImpl` This adapter enables attaching noisy local clocks - to `Nodes`, then scheduling events with respect to the local noisy clock, + to `Nodes`, then scheduling events with respect to the local noisy clock, instead of relative to the true simulator time. In addition to the PIMPL idiom of `SimulatorAdapter` there is a special @@ -253,22 +253,22 @@ per-event customization hook:: One can use this to perform any housekeeping actions before the next event actually executes. - -The distinction between a core engine and an adapter is the following: there + +The distinction between a core engine and an adapter is the following: there can only ever be one core engine running, while there can be several adapters -chained up each providing a variation on the base engine execution. +chained up each providing a variation on the base engine execution. For example one can use noisy local clocks with the real time adapter. A single adapter can be added on top of the `DefaultSimulatorImpl` by the same two methods above: binding the `"SimulatorImplementationType"` global value or -using the command line argument. To chain multipe adapters a different +using the command line argument. To chain multipe adapters a different approach must be used; see the `SimulatorAdapter::AddAdapter()` API documentation. The simulator engine type can be set once, but must be set before the first call to the `Simulator()` API. In practice, since some models have to schedule their start up events when they are constructed, this means -generally you should set the engine type before instantiating any other +generally you should set the engine type before instantiating any other model components. The engine type can be changed after `Simulator::Destroy()` but before @@ -279,22 +279,22 @@ multiple runs in a single |ns3| invocation. Time **** -|ns3| internally represents simulation times and durations as -64-bit signed integers (with the sign bit used for negative durations). +|ns3| internally represents simulation times and durations as +64-bit signed integers (with the sign bit used for negative durations). The time values are interpreted with respect to a "resolution" unit in the -customary SI units: fs, ps, ns, us, ms, s, min, h, d, y. -The unit defines the minimum Time value. +customary SI units: fs, ps, ns, us, ms, s, min, h, d, y. +The unit defines the minimum Time value. It can be changed once before any calls to `Simulator::Run()`. It is not stored with the 64-bit time value itself. -Times can be constructed from all standard numeric types -(using the configured default unit) +Times can be constructed from all standard numeric types +(using the configured default unit) or with explicit units (as in `Time MicroSeconds (uint64_t value)`). -Times can be compared, tested for sign or equality to zero, rounded to -a given unit, converted to standard numeric types in specific units. -All basic arithmetic operations are supported +Times can be compared, tested for sign or equality to zero, rounded to +a given unit, converted to standard numeric types in specific units. +All basic arithmetic operations are supported (addition, subtraction, multiplication or division -by a scalar (numeric value)). Times can be written to/read from IO streams. +by a scalar (numeric value)). Times can be written to/read from IO streams. In the case of writing it is easy to choose the output unit, different from the resolution unit. @@ -306,24 +306,24 @@ The main job of the `Scheduler` classes is to maintain the priority queue of future events. The scheduler can be set with a global variable, similar to choosing the `SimulatorImpl`:: - GlobalValue::Bind ("SchedulerType", + GlobalValue::Bind ("SchedulerType", StringValue ("ns3::DistributedSimulatorImpl")); The scheduler can be changed at any time via `Simulator::SetScheduler()`. -The default scheduler is `MapScheduler` which uses a `std::map<>` to +The default scheduler is `MapScheduler` which uses a `std::map<>` to store events in time order. Because event distributions vary by model there is no one best strategy for the priority queue, so |ns3| has several options with -differing tradeoffs. The example `utils/bench-simulator.c` can be used -to test the performance for a user-supplied event distribution. +differing tradeoffs. The example `utils/bench-simulator.c` can be used +to test the performance for a user-supplied event distribution. For modest execution times (less than an hour, say) the choice of priority queue is usually not significant; configuring the build type to optimized is much more important in reducing execution times. The available scheduler types, and a summary of their time and space complexity on `Insert()` and `RemoveNext()`, are listed in the -following table. See the individual Scheduler API pages for details on the +following table. See the individual Scheduler API pages for details on the complexity of the other API calls. +-----------------------+-------------------------------------+-------------+--------------+----------+--------------+ diff --git a/doc/manual/source/gnuplot.rst b/doc/manual/source/gnuplot.rst index fcff8af26..7e885bb31 100644 --- a/doc/manual/source/gnuplot.rst +++ b/doc/manual/source/gnuplot.rst @@ -1,6 +1,6 @@ .. include:: replace.txt .. highlight:: cpp - + Making Plots using the Gnuplot Class ------------------------------------ @@ -16,7 +16,7 @@ Creating Plots Using the Gnuplot Class The following steps must be taken in order to create a plot using |ns3|'s Gnuplot class: -#. Modify your code so that is uses the Gnuplot class and its functions. +#. Modify your code so that is uses the Gnuplot class and its functions. #. Run your code so that it creates a gnuplot control file. #. Call gnuplot with the name of the gnuplot control file. #. View the graphics file that was produced in your favorite graphics viewer. @@ -42,38 +42,38 @@ This should produce the following gnuplot control files: .. sourcecode:: text - plot-2d.plt + plot-2d.plt plot-2d-with-error-bars.plt - plot-3d.plt + plot-3d.plt In order to process these gnuplot control files, do the following: .. sourcecode:: bash - $ gnuplot plot-2d.plt + $ gnuplot plot-2d.plt $ gnuplot plot-2d-with-error-bars.plt - $ gnuplot plot-3d.plt + $ gnuplot plot-3d.plt This should produce the following graphics files: .. sourcecode:: text - plot-2d.png + plot-2d.png plot-2d-with-error-bars.png - plot-3d.png + plot-3d.png You can view these graphics files in your favorite graphics viewer. If you have gimp installed on your machine, for example, you can do this: .. sourcecode:: bash - $ gimp plot-2d.png + $ gimp plot-2d.png $ gimp plot-2d-with-error-bars.png - $ gimp plot-3d.png + $ gimp plot-3d.png An Example 2-Dimensional Plot ***************************** -The following 2-Dimensional plot +The following 2-Dimensional plot .. _plot-2d: @@ -114,10 +114,10 @@ was created using the following code from gnuplot-example.cc: :: for (x = -5.0; x <= +5.0; x += 1.0) { // Calculate the 2-D curve - // + // // 2 // y = x . - // + // y = x * x; // Add this point. @@ -135,7 +135,7 @@ was created using the following code from gnuplot-example.cc: :: // Close the plot file. plotFile.close (); - + An Example 2-Dimensional Plot with Error Bars ********************************************* @@ -185,10 +185,10 @@ was created using the following code from gnuplot-example.cc: :: for (x = -5.0; x <= +5.0; x += 1.0) { // Calculate the 2-D curve - // + // // 2 // y = x . - // + // y = x * x; // Make the uncertainty in the x direction be constant and make @@ -217,7 +217,7 @@ was created using the following code from gnuplot-example.cc: :: An Example 3-Dimensional Plot ***************************** -The following 3-Dimensional plot +The following 3-Dimensional plot .. _plot-3d: @@ -271,10 +271,10 @@ was created using the following code from gnuplot-example.cc: :: for (y = -5.0; y <= +5.0; y += 1.0) { // Calculate the 3-D surface - // + // // 2 2 // z = x * y . - // + // z = x * x * y * y; // Add this point. diff --git a/doc/manual/source/hash-functions.rst b/doc/manual/source/hash-functions.rst index b311bea7e..6990930da 100644 --- a/doc/manual/source/hash-functions.rst +++ b/doc/manual/source/hash-functions.rst @@ -27,7 +27,7 @@ The simplest way to get a hash value of a data buffer or string is just:: char * buffer = ... size_t buffer_size = ... - + uint32_t buffer_hash = Hash32 ( buffer, buffer_size); std::string s; @@ -92,7 +92,7 @@ To add the hash function ``foo``, follow the ``hash-murmur3.h``/``.cc`` pattern: ``hash-murmur3.h`` is included. * In your own code, instantiate a ``Hasher`` object via the constructor ``Hasher (Ptr ())`` - + If your hash function is a single function, e.g. ``hashf``, you don't even need to create a new class derived from HashImplementation:: diff --git a/doc/manual/source/how-to-write-tests.rst b/doc/manual/source/how-to-write-tests.rst index 091add68e..6fa9f7485 100644 --- a/doc/manual/source/how-to-write-tests.rst +++ b/doc/manual/source/how-to-write-tests.rst @@ -4,7 +4,7 @@ How to write tests ------------------ -A primary goal of the ns-3 project is to help users to improve the +A primary goal of the ns-3 project is to help users to improve the validity and credibility of their results. There are many elements to obtaining valid models and simulations, and testing is a major component. If you contribute models or examples to ns-3, you may @@ -26,7 +26,7 @@ Sample TestSuite skeleton When starting from scratch (i.e. not adding a TestCase to an existing TestSuite), these things need to be decided up front: -* What the test suite will be called +* What the test suite will be called * What type of test it will be (Build Verification Test, Unit Test, System Test, or Performance Test) * Where the test code will live (either in an existing ns-3 module or @@ -36,13 +36,13 @@ TestSuite), these things need to be decided up front: A program called ``utils/create-module.py`` is a good starting point. This program can be invoked such as ``create-module.py router`` for a hypothetical new module called ``router``. Once you do this, you -will see a ``router`` directory, and a ``test/router-test-suite.cc`` +will see a ``router`` directory, and a ``test/router-test-suite.cc`` test suite. This file can be a starting point for your initial test. This is a working test suite, although the actual tests performed are trivial. Copy it over to your module's test directory, and do a global substitution of "Router" in that file for something pertaining to the model that you want to test. You can also edit things such as a -more descriptive test case name. +more descriptive test case name. You also need to add a block into your wscript to get this test to compile: @@ -82,7 +82,7 @@ Test macros *********** There are a number of macros available for checking test program -output with expected output. These macros are defined in +output with expected output. These macros are defined in ``src/core/model/test.h``. The main set of macros that are used include the following: @@ -93,7 +93,7 @@ The main set of macros that are used include the following: NS_TEST_ASSERT_MSG_NE(actual, limit, msg) NS_TEST_ASSERT_MSG_LT(actual, limit, msg) NS_TEST_ASSERT_MSG_GT(actual, limit, msg) - NS_TEST_ASSERT_MSG_EQ_TOL(actual, limit, tol, msg) + NS_TEST_ASSERT_MSG_EQ_TOL(actual, limit, tol, msg) The first argument ``actual`` is the value under test, the second value ``limit`` is the expected value (or the value to test against), and the diff --git a/doc/manual/source/logging.rst b/doc/manual/source/logging.rst index 53f10404a..6cd54ef45 100644 --- a/doc/manual/source/logging.rst +++ b/doc/manual/source/logging.rst @@ -17,10 +17,10 @@ in your ``main()`` program or by the use of the ``NS_LOG`` environment variable. Logging statements are not compiled into optimized builds of |ns3|. To use logging, one must build the (default) debug build of |ns3|. -The project makes no guarantee about whether logging output will remain +The project makes no guarantee about whether logging output will remain the same over time. Users are cautioned against building simulation output frameworks on top of logging code, as the output and the way the output -is enabled may change over time. +is enabled may change over time. Overview ******** @@ -61,10 +61,10 @@ This can be made more granular by selecting individual components: $ NS_LOG="Ipv4L3Protocol" ./ns3 run first The output can be further tailored with prefix options. - + The second way to enable logging is to use explicit statements in your program, such as in the ``first`` tutorial program:: - + int main (int argc, char *argv[]) { @@ -107,7 +107,7 @@ in a module, spanning different compilation units, but logically grouped together, such as the |ns3| wifi code:: WifiHelper wifiHelper; - wifiHelper.EnableLogComponents (); + wifiHelper.EnableLogComponents (); The ``NS_LOG`` log component wildcard \`*' will enable all components. @@ -306,10 +306,10 @@ for all log components. These are all equivalent: .. sourcecode:: bash - $ NS_LOG="***" ... $ NS_LOG="*=all|*" ... $ NS_LOG="*=*|all" ... + $ NS_LOG="***" ... $ NS_LOG="*=all|*" ... $ NS_LOG="*=*|all" ... $ NS_LOG="*=**" ... $ NS_LOG="*=level_all|*" ... $ NS_LOG="*=*|prefix_all" ... $ NS_LOG="*=*|*" ... - + Be advised: even the trivial ``scratch-simulator`` produces over 46K lines of output with ``NS_LOG="***"``! @@ -329,7 +329,7 @@ Adding logging to your code is very simple: :: namespace ns3 { - + NS_LOG_COMPONENT_DEFINE ("Ipv4L3Protocol"); ... @@ -400,8 +400,8 @@ Controlling timestamp precision ******************************* Timestamps are printed out in units of seconds. When used with the default -|ns3| time resolution of nanoseconds, the default timestamp precision is 9 -digits, with fixed format, to allow for 9 digits to be consistently printed +|ns3| time resolution of nanoseconds, the default timestamp precision is 9 +digits, with fixed format, to allow for 9 digits to be consistently printed to the right of the decimal point. Example: :: @@ -417,11 +417,11 @@ or femtoseconds, the precision is expanded accordingly; e.g. for picosecond: When the |ns3| simulation uses a time resolution lower than microseconds, the default C++ precision is used. - + An example program at ``src\core\examples\sample-log-time-format.cc`` demonstrates how to change the timestamp formatting. -The maximum useful precision is 20 decimal digits, since Time is signed 64 +The maximum useful precision is 20 decimal digits, since Time is signed 64 bits. Logging Macros @@ -476,7 +476,7 @@ Guidelines * Start every class method with ``NS_LOG_FUNCTION (this << args...);`` This enables easy function call tracing. - * Except: don't log operators or explicit copy constructors, + * Except: don't log operators or explicit copy constructors, since these will cause infinite recursion and stack overflow. * For methods without arguments use the same form: @@ -502,11 +502,11 @@ Guidelines * Use ``NS_LOG_LOGIC`` to trace important logic branches within a function. -* Test that your logging changes do not break the code. - Run some example programs with all log components turned on (e.g. +* Test that your logging changes do not break the code. + Run some example programs with all log components turned on (e.g. ``NS_LOG="***"``). -* Use an explicit cast for any variable of type uint8_t or int8_t, +* Use an explicit cast for any variable of type uint8_t or int8_t, e.g., ``NS_LOG_LOGIC ("Variable i is " << static_cast (i));``. Without the cast, the integer is interpreted as a char, and the result will be most likely not in line with the expectations. diff --git a/doc/manual/source/new-models.rst b/doc/manual/source/new-models.rst index bff411a9b..bb6850c99 100644 --- a/doc/manual/source/new-models.rst +++ b/doc/manual/source/new-models.rst @@ -78,7 +78,7 @@ ListErrorModel, etc, such as is done in |ns2|. You may be thinking at this point, "Why not make IsCorrupt() a virtual method?". That is one approach; the other is to make the public non-virtual function indirect through a private virtual function (this in C++ is known as the non -virtual interface idiom and is adopted in the |ns3| ErrorModel class). +virtual interface idiom and is adopted in the |ns3| ErrorModel class). Next, should this device have any dependencies on IP or other protocols? We do not want to create dependencies on Internet protocols (the error model should be @@ -106,7 +106,7 @@ NetDevice level. After some thinking and looking at existing |ns2| code, here is a sample API of a base class and first subclass that could be posted for initial review:: - class ErrorModel + class ErrorModel { public: ErrorModel (); @@ -153,14 +153,14 @@ Let's say that you are ready to start implementing; you have a fairly clear picture of what you want to build, and you may have solicited some initial review or suggestions from the list. One way to approach the next step (implementation) is to create scaffolding and fill in the details as the design -matures. +matures. This section walks through many of the steps you should consider to define scaffolding, or a non-functional skeleton of what your model will eventually implement. It is usually good practice to not wait to get these details integrated at the end, but instead to plumb a skeleton of your model into the system early and then add functions later once the API and integration seems -about right. +about right. Note that you will want to modify a few things in the below presentation for your model since if you follow the error model verbatim, the code you produce @@ -185,7 +185,7 @@ particularly for ease of integrating with the build system. In the case of the error model, it is very related to the packet class, so it makes sense to implement this in the ``src/network/`` module where |ns3| -packets are implemented. +packets are implemented. `cmake` and `CMakeLists.txt` ++++++++++++++++++++++++++++ @@ -197,7 +197,7 @@ add your files to the ``CMakeLists.txt`` file found in each directory. Let's start with empty files error-model.h and error-model.cc, and add this to ``src/network/CMakeLists.txt``. It is really just a matter of adding the .cc file to the -rest of the source files, and the .h file to the list of the header files. +rest of the source files, and the .h file to the list of the header files. Now, pop up to the top level directory and type "./test.py". You shouldn't have broken anything by this operation. @@ -290,7 +290,7 @@ from class Object.:: #include "ns3/object.h" namespace ns3 { - + class ErrorModel : public Object { public: @@ -304,7 +304,7 @@ from class Object.:: { public: static TypeId GetTypeId (void); - + RateErrorModel (); virtual ~RateErrorModel (); }; @@ -317,18 +317,18 @@ included without any path prefix. Therefore, if we were implementing ErrorModel in ``src/core/model`` directory, we could have just said "``#include "object.h"``". But we are in ``src/network/model``, so we must include it as "``#include "ns3/object.h"``". Note also that this goes outside the namespace declaration. - + Second, each class must implement a static public member function called -``GetTypeId (void)``. +``GetTypeId (void)``. Third, it is a good idea to implement constructors and destructors rather than to let the compiler generate them, and to make the destructor virtual. In C++, note also that copy assignment operator and copy constructors are auto-generated if they are not defined, so if you do not want those, you should implement those as private members. This aspect of C++ is discussed in Scott Meyers' Effective -C++ book. item 45. +C++ book. item 45. -Let's now look at some corresponding skeletal implementation code in the .cc +Let's now look at some corresponding skeletal implementation code in the .cc file.:: #include "error-model.h" @@ -347,11 +347,11 @@ file.:: } ErrorModel::ErrorModel () - { + { } ErrorModel::~ErrorModel () - { + { } NS_OBJECT_ENSURE_REGISTERED (RateErrorModel); @@ -368,7 +368,7 @@ file.:: RateErrorModel::RateErrorModel () { - } + } RateErrorModel::~RateErrorModel () { @@ -378,7 +378,7 @@ What is the ``GetTypeId (void)`` function? This function does a few things. It registers a unique string into the TypeId system. It establishes the hierarchy of objects in the attribute system (via ``SetParent``). It also declares that certain objects can be created via the object creation framework -(``AddConstructor``). +(``AddConstructor``). The macro ``NS_OBJECT_ENSURE_REGISTERED (classname)`` is needed also once for every class that defines a new GetTypeId method, and it does the actual @@ -422,12 +422,12 @@ Add Basic Support in the Class /* point-to-point-net-device.h */ class ErrorModel; - + /** * Error model for receive packet events */ Ptr m_receiveErrorModel; - + Add Accessor ++++++++++++ @@ -438,7 +438,7 @@ Add Accessor { NS_LOG_FUNCTION (this << em); m_receiveErrorModel = em; - } + } .AddAttribute ("ReceiveErrorModel", "The receiver error model used to simulate packet loss", @@ -455,26 +455,26 @@ Plumb Into the System { NS_LOG_FUNCTION (this << packet); uint16_t protocol = 0; - + if (m_receiveErrorModel && m_receiveErrorModel->IsCorrupt (packet) ) { - // + // // If we have an error model and it indicates that it is time to lose a - // corrupted packet, don't forward this packet up, let it go. - // + // corrupted packet, don't forward this packet up, let it go. + // m_dropTrace (packet); - } + } else { - // + // // Hit the receive trace hook, strip off the point-to-point protocol header // and forward this packet up the protocol stack. - // + // m_rxTrace (packet); ProcessHeader(packet, protocol); m_rxCallback (this, packet, protocol, GetRemote ()); if (!m_promiscCallback.IsNull ()) - { m_promiscCallback (this, packet, protocol, GetRemote (), + { m_promiscCallback (this, packet, protocol, GetRemote (), GetAddress (), NetDevice::PACKET_HOST); } } diff --git a/doc/manual/source/new-modules.rst b/doc/manual/source/new-modules.rst index 8eb2b76b2..8ec4a75ee 100644 --- a/doc/manual/source/new-modules.rst +++ b/doc/manual/source/new-modules.rst @@ -62,7 +62,7 @@ By default ``create-module.py`` creates the module skeleton in the .. sourcecode:: bash $ ./utils/create-module.py contrib/new-contrib - + Let's assume we've created our new module in ``src``. ``cd`` into ``src/new-module``; you will find this directory layout: @@ -113,10 +113,10 @@ like this (before editing): .. sourcecode:: cmake build_lib( - LIBNAME new-module - SOURCE_FILES helper/new-module-helper.cc + LIBNAME new-module + SOURCE_FILES helper/new-module-helper.cc model/new-module.cc - HEADER_FILES helper/new-module-helper.h + HEADER_FILES helper/new-module-helper.h model/new-module.h LIBRARIES_TO_LINK ${libcore} TEST_SOURCES test/new-module-test-suite.cc @@ -129,12 +129,12 @@ should look like: .. sourcecode:: cmake build_lib( - LIBNAME new-module - SOURCE_FILES helper/new-module-helper.cc + LIBNAME new-module + SOURCE_FILES helper/new-module-helper.cc model/new-module.cc - HEADER_FILES helper/new-module-helper.h + HEADER_FILES helper/new-module-helper.h model/new-module.h - LIBRARIES_TO_LINK + LIBRARIES_TO_LINK ${libinternet} ${libmobility} ${libaodv} @@ -147,7 +147,7 @@ is why we removed ``core``; the ``internet`` module in turn depends on Your module will most likely have model source files. Initial skeletons (which will compile successfully) are created in ``model/new-module.cc`` -and ``model/new-module.h``. +and ``model/new-module.h``. If your module will have helper source files, then they will go into the ``helper/`` directory; again, initial skeletons are created @@ -213,7 +213,7 @@ with the following: Note: the ``source_files`` and ``header_files`` lists are not necessary. They are used keep the ``build_lib`` macro readable for modules with many -source files. +source files. The objects resulting from compiling these sources will be assembled into a link library, which will be linked to any programs relying on this @@ -257,7 +257,7 @@ If the list of headers is short, use the following instead: build_lib( LIBNAME spectrum ... - HEADER_FILES + HEADER_FILES helper/adhoc-aloha-noack-ideal-phy-helper.h helper/spectrum-analyzer-helper.h ... @@ -266,7 +266,7 @@ If the list of headers is short, use the following instead: model/wifi-spectrum-value-helper.h ... ) - + Headers made public in this way will be accessible to users of your model with include statements like @@ -274,7 +274,7 @@ with include statements like .. sourcecode:: cpp #include "ns3/spectrum-model.h" - + Headers used strictly internally in your implementation should not be included here. They are still accessible to your implementation by include statements like @@ -307,7 +307,7 @@ The ``spectrum`` model tests are specified with the following stanza: test/tv-spectrum-transmitter-test.cc ) -See :doc:`Tests ` for more information on how to write test cases. +See :doc:`Tests ` for more information on how to write test cases. Step 6 - Declare Examples ************************* @@ -325,7 +325,7 @@ The ``spectrum`` model defines it's first example in build_lib_example( NAME adhoc-aloha-ideal-phy SOURCE_FILES adhoc-aloha-ideal-phy.cc - LIBRARIES_TO_LINK + LIBRARIES_TO_LINK ${libspectrum} ${libmobility} ${libinternet} @@ -335,7 +335,7 @@ The ``spectrum`` model defines it's first example in Note that the variable ``libraries_to_link`` is the list of modules that the program being created depends on; again, don't forget to include -``new-module`` in the list. It's best practice to list only the direct +``new-module`` in the list. It's best practice to list only the direct module dependencies, and let ``CMake`` deduce the full dependency tree. Occasionally, for clarity, you may want to split the implementation @@ -343,13 +343,13 @@ for your example among several source files. In this case, just include those files as additional explicit sources of the example: .. sourcecode:: cmake - + build_lib_example( NAME new-module-example SOURCE_FILES new-module-example.cc - LIBRARIES_TO_LINK - ${libspectrum} - ${libmobility} + LIBRARIES_TO_LINK + ${libspectrum} + ${libmobility} ${libinternet} ${libapplications} ) @@ -380,7 +380,7 @@ two lists of C++ and Python examples: ("adhoc-aloha-ideal-phy-with-microwave-oven", "True", "True"), ("adhoc-aloha-ideal-phy-matrix-propagation-loss-model", "True", "True"), ] - + # A list of Python examples to run in order to ensure that they remain # runnable over time. Each tuple in the list contains # @@ -447,6 +447,6 @@ Adding Python bindings to your module is optional. If you want to include Python bindings (needed only if you want to write Python ns-3 programs instead of C++ ns-3 programs), you -should scan your module to generate new bindings for the Python -API (covered elsewhere in this manual), and they will be used +should scan your module to generate new bindings for the Python +API (covered elsewhere in this manual), and they will be used if NS3_PYTHON_BINDINGS is set to ON. diff --git a/doc/manual/source/object-model.rst b/doc/manual/source/object-model.rst index 51ace3ad7..ae79e28a6 100644 --- a/doc/manual/source/object-model.rst +++ b/doc/manual/source/object-model.rst @@ -24,9 +24,9 @@ not strictly in accordance with either. Object-oriented behavior ************************ -C++ objects, in general, provide common object-oriented capabilities -(abstraction, encapsulation, inheritance, and polymorphism) that are part -of classic object-oriented design. |ns3| objects make use of these +C++ objects, in general, provide common object-oriented capabilities +(abstraction, encapsulation, inheritance, and polymorphism) that are part +of classic object-oriented design. |ns3| objects make use of these properties; for instance:: class Address @@ -54,8 +54,8 @@ These base classes are: * class :cpp:class:`ObjectBase` * class :cpp:class:`SimpleRefCount` -It is not required that |ns3| objects inherit from these class, but -those that do get special properties. Classes deriving from +It is not required that |ns3| objects inherit from these class, but +those that do get special properties. Classes deriving from class :cpp:class:`Object` get the following properties. * the |ns3| type and attribute system (see :ref:`Attributes`) @@ -87,14 +87,14 @@ obtained to an interface, the object's reference count is incremented by calling object is deleted. * When the client code obtains a pointer from the object itself through object - creation, or via GetObject, it does not have to increment the reference count. + creation, or via GetObject, it does not have to increment the reference count. * When client code obtains a pointer from another source (e.g., copying a pointer) it must call ``Ref()`` to increment the reference count. * All users of the object pointer must call ``Unref()`` to release the reference. The burden for calling :cpp:func:`Unref()` is somewhat relieved by the use of -the reference counting smart pointer class described below. +the reference counting smart pointer class described below. Users using a low-level API who wish to explicitly allocate non-reference-counted objects on the heap, using operator new, are responsible @@ -108,7 +108,7 @@ provides a smart pointer class :cpp:class:`Ptr` similar to :cpp:class:`Boost::intrusive_ptr`. This smart-pointer class assumes that the underlying type provides a pair of ``Ref`` and ``Unref`` methods that are expected to increment and decrement the internal refcount of the object -instance. +instance. This implementation allows you to manipulate the smart pointer as if it was a normal pointer: you can compare it with zero, compare it against other pointers, @@ -157,7 +157,7 @@ The |ns3| object aggregation system is motivated in strong part by a recognition that a common use case for |ns2| has been the use of inheritance and polymorphism to extend protocol models. For instance, specialized versions of TCP such as RenoTcpAgent derive from (and override functions from) class -TcpAgent. +TcpAgent. However, two problems that have arisen in the |ns2| model are downcasts and "weak base class." Downcasting refers to the procedure of using a base class @@ -174,7 +174,7 @@ problems. This design is based on elements of the `Component Object Model `_ and `GNOME Bonobo `_ although full binary-level compatibility of replaceable components is not supported and we -have tried to simplify the syntax and impact on model developers. +have tried to simplify the syntax and impact on model developers. Examples ******** @@ -212,7 +212,7 @@ GetObject example +++++++++++++++++ GetObject is a type-safe way to achieve a safe downcasting and to allow -interfaces to be found on an object. +interfaces to be found on an object. Consider a node pointer ``m_node`` that points to a Node object that has an implementation of IPv4 previously aggregated to it. The client code wishes to @@ -243,7 +243,7 @@ Object factories A common use case is to create lots of similarly configured objects. One can repeatedly call :cpp:func:`CreateObject` but there is also a factory design -pattern in use in the |ns3| system. It is heavily used in the "helper" API. +pattern in use in the |ns3| system. It is heavily used in the "helper" API. Class :cpp:class:`ObjectFactory` can be used to instantiate objects and to configure the attributes on those objects:: @@ -254,7 +254,7 @@ configure the attributes on those objects:: The first method allows one to use the |ns3| TypeId system to specify the type of objects created. The second allows one to set attributes on the objects to be -created, and the third allows one to create the objects themselves. +created, and the third allows one to create the objects themselves. For example: :: @@ -265,10 +265,10 @@ For example: :: // subsequently created objects factory.Set ("SystemLoss", DoubleValue (2.0)); // Create one such object - Ptr object = factory.Create (); + Ptr object = factory.Create (); factory.Set ("SystemLoss", DoubleValue (3.0)); // Create another object with a different SystemLoss - Ptr object = factory.Create (); + Ptr object = factory.Create (); Downcasting *********** diff --git a/doc/manual/source/organization.rst b/doc/manual/source/organization.rst index 01c650a67..f6aa5be6a 100644 --- a/doc/manual/source/organization.rst +++ b/doc/manual/source/organization.rst @@ -13,12 +13,12 @@ and models are implemented in C++. |ns3| is built as a library which may be statically or dynamically linked to a C++ main program that defines the simulation topology and starts the simulator. |ns3| also exports nearly all of its API to Python, allowing Python programs to import an "ns3" module in -much the same way as the |ns3| library is linked by executables in C++. +much the same way as the |ns3| library is linked by executables in C++. .. _software-organization: .. figure:: figures/software-organization.* - + Software organization of |ns3| The source code for |ns3| is mostly organized in the ``src`` directory and @@ -26,9 +26,9 @@ can be described by the diagram in :ref:`software-organization`. We will work our way from the bottom up; in general, modules only have dependencies on modules beneath them in the figure. -We first describe the core of the simulator; those components that are -common across all protocol, hardware, and environmental models. -The simulation core is implemented in ``src/core``. Packets are +We first describe the core of the simulator; those components that are +common across all protocol, hardware, and environmental models. +The simulation core is implemented in ``src/core``. Packets are fundamental objects in a network simulator and are implemented in ``src/network``. These two simulation modules by themselves are intended to comprise a generic simulation core that can be @@ -36,8 +36,8 @@ used by different kinds of networks, not just Internet-based networks. The above modules of |ns3| are independent of specific network and device models, which are covered in subsequent parts of this manual. -In addition to the above |ns3| core, we introduce, also in the initial -portion of the manual, two other modules that supplement the core C++-based +In addition to the above |ns3| core, we introduce, also in the initial +portion of the manual, two other modules that supplement the core C++-based API. |ns3| programs may access all of the API directly or may make use of a so-called *helper API* that provides convenient wrappers or encapsulation of low-level API calls. The @@ -50,10 +50,10 @@ The remainder of the manual is focused on documenting the models and supporting capabilities. The next part focuses on two fundamental objects in |ns3|: the ``Node`` and ``NetDevice``. Two special NetDevice types are designed to support network emulation use cases, and emulation is described -next. The following chapter is devoted to Internet-related models, +next. The following chapter is devoted to Internet-related models, including the -sockets API used by Internet applications. The next chapter covers -applications, and the following chapter describes additional support for +sockets API used by Internet applications. The next chapter covers +applications, and the following chapter describes additional support for simulation, such as animators and statistics. The project maintains a separate manual devoted to testing and validation diff --git a/doc/manual/source/profiling.rst b/doc/manual/source/profiling.rst index c98cfabea..f6700a766 100644 --- a/doc/manual/source/profiling.rst +++ b/doc/manual/source/profiling.rst @@ -5,28 +5,28 @@ Profiling --------- Memory profiling is essential to identify issues that -may cause memory corruption, which may lead to all sorts of +may cause memory corruption, which may lead to all sorts of side-effects, such as crashing after many hours of simulation and producing wrong results that invalidate the entire simulation. -It also can help tracking sources of excessive memory allocations, -the size of these allocations and memory usage during simulation. -These can affect simulation performance, or limit the complexity +It also can help tracking sources of excessive memory allocations, +the size of these allocations and memory usage during simulation. +These can affect simulation performance, or limit the complexity and the number of concurrent simulations. -Performance profiling on the other hand is essential for +Performance profiling on the other hand is essential for high-performance applications, as it allows for the identification of bottlenecks and their mitigation. Another type of profiling is related to system calls. They -can be used to debug issues and identify hotspots that +can be used to debug issues and identify hotspots that may cause performance issues in specific conditions. Excessive -calls results in more context switches, which interrupt the -simulations, ultimately slowing them down. +calls results in more context switches, which interrupt the +simulations, ultimately slowing them down. Other than profiling the simulations, which can highlight bottlenecks -in the simulator, we can also profile the compilation process. -This allows us to identify and fix bottlenecks, which speed up +in the simulator, we can also profile the compilation process. +This allows us to identify and fix bottlenecks, which speed up build times. @@ -40,22 +40,22 @@ Memory Profilers .. _Bytehound : https://github.com/koute/bytehound .. _gperftools : https://github.com/gperftools/gperftools -Memory profilers are tools that help identifying memory related +Memory profilers are tools that help identifying memory related issues. There are two well known tools for finding bugs such as uninitialized memory usage, out-of-bound accesses, dereferencing null pointers and other memory-related bugs: * `Valgrind`_ - + * Pros: very rich tooling, no need to recompile programs to profile the program. * Cons: very slow and limited to Linux and MacOS. * `Sanitizers`_ - + * Pros: sanitizers are distributed along with compilers, such as GCC, Clang and MSVC. They are widely available, cross platform and faster than Valgrind. - * Cons: false positives, high memory usage, memory sanitizer is incompatible - with other sanitizers (e.g. address sanitizer), requiring two instrumented + * Cons: false positives, high memory usage, memory sanitizer is incompatible + with other sanitizers (e.g. address sanitizer), requiring two instrumented compilations and two test runs. The memory sanitizer requires Clang. There are also tools to count memory allocations, track memory usage and memory leaks, @@ -92,11 +92,11 @@ used to profile programs at runtime and find issues related to undefined behavio memory corruption (out-of-bound access, uninitialized memory use), leaks, race conditions and others. -Sanitizers are shipped with most modern compilers and can be used by instructing the +Sanitizers are shipped with most modern compilers and can be used by instructing the compiler to link the required libraries and instrument the code. To build ns-3 with sanitizers, enable the ``NS3_SANITIZE`` option. This can be done -directly via CMake: +directly via CMake: .. sourcecode:: console @@ -158,27 +158,27 @@ Sanitizers were used to find issues in multiple occasions: =>0x0ffd7197db70: 00 00 04 f9 f9 f9 f9[f9]00 00 00 00 00 00 00 00 Shadow byte legend (one shadow byte represents 8 application bytes): Addressable: 00 - Partially addressable: 01 02 03 04 05 06 07 + Partially addressable: 01 02 03 04 05 06 07 Global redzone: f9 ==51636==ABORTING - * The output above shows the type of error (``global-buffer-overflow``), - the stack-trace of where the bug happened (``LteAmc::GetDlTbSizeFromMcs``), - affected variables (``McsToItbsUl`` and ``TransportBlockSizeTable``), + * The output above shows the type of error (``global-buffer-overflow``), + the stack-trace of where the bug happened (``LteAmc::GetDlTbSizeFromMcs``), + affected variables (``McsToItbsUl`` and ``TransportBlockSizeTable``), and a shadow bytes map, showing the wrong access between square brackets. - * The the global redzone (f9) shadow bytes are empty memory allocated between global variables (00s and 04s), + * The the global redzone (f9) shadow bytes are empty memory allocated between global variables (00s and 04s), which are left there to be corrupted by the bugged program. Any eventual corruption is then traced back to the source, without affecting the program execution. * The adopted solution in merge request `MR703`_ was to fix one of the schedulers that could produce the index value of -1, and updating the asserts to catch the illegal index value. * A wrong downcast in the Wimax module: - + * The pointer was casted incorrectly to U16TlvValue instead of U8TvlValue, which could have different sizes in memory - leading to the program reading the wrong memory address. - Reading the wrong memory address can result in unexpected or invalid values being read, which could change the - program flow and corrupt memory, producing wrong simulation results or crashing the program. - + leading to the program reading the wrong memory address. + Reading the wrong memory address can result in unexpected or invalid values being read, which could change the + program flow and corrupt memory, producing wrong simulation results or crashing the program. + .. sourcecode:: console ~/ns-3-dev/src/wimax/model/service-flow.cc:159:86: runtime error: downcast of address 0x6020000148b0 which does not point to an object of type 'U16TlvValue' @@ -210,8 +210,8 @@ along with stack traces, allowing developers to identify code responsible for possible memory leaks and unnecessary allocations. For the examples below we used the default configuration of ns-3, -with the output going to the ``build`` directory. The actual executable -for the ``wifi-he-network`` example is ``./build/examples/wireless/ns3-dev-wifi-he-network``, which is what is +with the output going to the ``build`` directory. The actual executable +for the ``wifi-he-network`` example is ``./build/examples/wireless/ns3-dev-wifi-he-network``, which is what is executed by ``./ns3 run wifi-he-network``. To collect information of a program (in this case the ``wifi-he-network`` @@ -225,13 +225,13 @@ If you prefer to use the ``ns3`` wrapper, try: .. sourcecode:: console - ~ns-3-dev/$ ./ns3 run "wifi-he-network --simulationTime=0.3 --frequency=5 --useRts=1 --minExpectedThroughput=6 --maxExpectedThroughput=745" --command-template "heaptrack %s" --no-build + ~ns-3-dev/$ ./ns3 run "wifi-he-network --simulationTime=0.3 --frequency=5 --useRts=1 --minExpectedThroughput=6 --maxExpectedThroughput=745" --command-template "heaptrack %s" --no-build In both cases, heaptrack will print to the terminal the output file: .. sourcecode:: console - ~ns-3-dev/$ ./ns3 run "wifi-he-network --simulationTime=0.3 --frequency=5 --useRts=1 --minExpectedThroughput=6 --maxExpectedThroughput=745" --command-template "heaptrack %s" --no-build + ~ns-3-dev/$ ./ns3 run "wifi-he-network --simulationTime=0.3 --frequency=5 --useRts=1 --minExpectedThroughput=6 --maxExpectedThroughput=745" --command-template "heaptrack %s" --no-build heaptrack output will be written to "~ns-3-dev/heaptrack.ns3-dev-wifi-he-network.210305.zst" starting application, this might take some time... MCS value Channel width GI Throughput @@ -248,10 +248,10 @@ In both cases, heaptrack will print to the terminal the output file: heaptrack --analyze "~/ns-3-dev/heaptrack.ns3-dev-wifi-he-network.210305.zst" -The output above shows a summary of the stats collected: ~149 million allocations, +The output above shows a summary of the stats collected: ~149 million allocations, ~21 million temporary allocations and ~10 thousand possible leaked allocations. -If ``heaptrack-gui`` is installed, running ``heaptrack`` will launch it. If it is not installed, +If ``heaptrack-gui`` is installed, running ``heaptrack`` will launch it. If it is not installed, the command line interface will be used. .. sourcecode:: console @@ -364,7 +364,7 @@ Here is a short description of what each line of the last block of the output me * Total memory leak refers to memory allocated but never freed. This includes static initialization, so it is not uncommon to be different than 0KB. However this does not mean the program does not have memory leaks. Other memory profilers such as Valgrind and memory sanitizers are better - suited to track down memory leaks. + suited to track down memory leaks. Based on the stack trace, it is fairly easy to locate the corresponding code and act on it to reduce the number of allocations. @@ -383,7 +383,7 @@ but in a more interactive way. .. image:: figures/heaptrack.png Heaptrack was used in merge request `MR830`_ to track and reduce the number of allocations -in the ``wifi-he-network`` example mentioned above. About 29 million unnecessary allocations +in the ``wifi-he-network`` example mentioned above. About 29 million unnecessary allocations were removed, which translates to a 20% reduction. This resulted in a 1.07x speedup of the test suite with Valgrind (``./test.py -d -g``) and 1.02x speedup without it. @@ -402,16 +402,16 @@ Performance Profilers Performance profilers are programs that collect runtime information and help to identify performance bottlenecks. In some cases, they can point out hotspots -and suggest solutions. +and suggest solutions. -There are many tools to profile your program, including: +There are many tools to profile your program, including: * profilers from CPU manufacturers, such as `AMD uProf`_ and `Intel VTune`_ * profilers from the operating systems, such as Linux's `Perf`_ and `Windows Performance Toolkit`_ - + * `Perf`_ also has a few graphical user interfaces available, being `Hotspot`_ one of them * instrumented compilation and auxiliary tools provided by compilers, such as `Gprof`_ -* third-party tools, such as `Sysprof`_ and `Oprofile`_ +* third-party tools, such as `Sysprof`_ and `Oprofile`_ An overview on how to use `Perf`_ with `Hotspot`_, `AMD uProf`_ and `Intel VTune`_ is provided in the following sections. @@ -422,29 +422,29 @@ Linux Perf and Hotspot GUI ++++++++++++++++++++++++++ `Perf`_ is the kernel tool to measure performance of the Linux kernel, -drivers and user-space applications. +drivers and user-space applications. Perf tracks some performance events, being some of the most important for performance: * cycles - + * Clocks (time) spent running. * cache-misses - - * When either data or instructions were not in the L1/L2 caches, requiring + + * When either data or instructions were not in the L1/L2 caches, requiring a L3 or memory access. * branch-misses - + * How many branch instructions were mispredicted. - Mispredictions causes the CPU to stall and clean the pipeline, + Mispredictions causes the CPU to stall and clean the pipeline, slowing down the program. * stalled-cycles-frontend - + * Cycles wasted by the processor waiting for the next instruction, usually due to instruction cache miss or mispredictions. Starves the CPU pipeline of instructions and slows down the program. * stalled-cycles-backend - + * Cycles wasted waiting for pipeline resources to finish their work. Usually waiting for memory read/write, or executing long-latency instructions. @@ -459,12 +459,12 @@ to the ``perf.data`` output file. ~/ns-3-dev$ ./ns3 run "wifi-he-network --simulationTime=0.3 --frequency=5 --useRts=1 --minExpectedThroughput=6 --maxExpectedThroughput=745" --command-template "perf record -o ./perf.data --call-graph dwarf --event cycles,cache-misses,branch-misses --sample-cpu %s" --no-build -`Hotspot`_ is a GUI for Perf, that makes performance profiling more -enjoyable and productive. It can parse the ``perf.data`` and show in +`Hotspot`_ is a GUI for Perf, that makes performance profiling more +enjoyable and productive. It can parse the ``perf.data`` and show in a more friendly way. To record the same perf.data from Hotspot directly, fill the fields -for working directory, path to the executable, arguments, perf +for working directory, path to the executable, arguments, perf events to track and output directory for the ``perf.data``. Then run to start recording. @@ -475,7 +475,7 @@ image. .. image:: figures/hotspot-cycles.png -The data is also presented in a tabular format in the bottom-up, +The data is also presented in a tabular format in the bottom-up, top-down and caller/callee tabs (top left of the screen). .. image:: figures/hotspot-top-down.png @@ -490,14 +490,14 @@ Hotspot was used to identify performance bottlenecks in multiple occasions: #. ``wifi-primary-channels`` test suite was extremely slow due to unnecessary RF processing. The adopted solution was to replace the filtering step of the entire channel to just the desired sub-band, and assuming sub-bands are uniformly sized, saving multiplications in the integral - used to compute the power of each sub-band. This resulted in a 6x speedup with - ``./ns3 run "test-runner --fullness=TAKES_FOREVER --test-name=wifi-primary-channels"``. + used to compute the power of each sub-band. This resulted in a 6x speedup with + ``./ns3 run "test-runner --fullness=TAKES_FOREVER --test-name=wifi-primary-channels"``. Hotspot was used along with AMD uProf to track this and other bottlenecks in `issue 426`_. #. ``WifiMacQueue::TtlExceeded`` dereferenced data out of cache when calling Simulator::Now(). The adopted solution was to move Simulator::Now() out of TtlExceeded and reuse the value and inlining TtlExceeded. This resulted in a ~1.20x speedup with the test suite (``./test.py -d``). - Hotspot was used along with AMD uProf to track this and other bottlenecks in `issue 280`_ + Hotspot was used along with AMD uProf to track this and other bottlenecks in `issue 280`_ and merge request `MR681`_. #. MpduAggregator and MsduAggregator required an expensive attribute lookup to get the maximum sizes @@ -510,9 +510,9 @@ Hotspot was used to identify performance bottlenecks in multiple occasions: AMD uProf +++++++++ -`AMD uProf`_ works much like `Linux Perf and Hotspot GUI`_, but +`AMD uProf`_ works much like `Linux Perf and Hotspot GUI`_, but is available in more platforms (Linux, Windows and BSD) using AMD -processors. Differently from Perf, it provides more performance +processors. Differently from Perf, it provides more performance trackers for finer analysis. To use it, open uProf then click to profile an application. If you @@ -522,11 +522,11 @@ Configurations`` section. .. image:: figures/uprof-start.png -Fill the fields with the application path, the arguments and -the working directory. +Fill the fields with the application path, the arguments and +the working directory. -You may need to add the LD_LIBRARY_PATH environment variable -(or PATH on Windows), pointing it to the library output +You may need to add the LD_LIBRARY_PATH environment variable +(or PATH on Windows), pointing it to the library output directory (e.g. ``ns-3-dev/build/lib``). Then click next: @@ -537,29 +537,29 @@ Now select custom events and pick the events you want. The recommended ones for performance profiling are: * CYCLES_NOT_IN_HALT - + * Clocks (time) spent running. * RETIRED_INST - + * How many instructions were completed. * These do not count mispredictions, stalls, etc. * Instructions per clock (IPC) = RETIRED_INST / CYCLES_NOT_IN_HALT * RETIRED_BR_INST_MISP - + * How many branch instructions were mispredicted. - * Mispredictions causes the CPU to stall and clean the pipeline, + * Mispredictions causes the CPU to stall and clean the pipeline, slowing down the program. - * L2_CACHE_MISS.FROM_L1_IC_MISS - - * L2 cache misses caused by instruction L1 cache misses. + * L2_CACHE_MISS.FROM_L1_IC_MISS + + * L2 cache misses caused by instruction L1 cache misses. * Results in L3/memory accesses due to missing instructions in L1/L2. - * L2_CACHE_MISS.FROM_L1_DC_MISS - - * L2 cache misses caused by data L1 cache misses. + * L2_CACHE_MISS.FROM_L1_DC_MISS + + * L2 cache misses caused by data L1 cache misses. * Results in L3/memory accesses due to missing instructions in L1/L2 * MISALIGNED_LOADS - - * Loads not aligned with processor words. + + * Loads not aligned with processor words. * Might result in additional cache and memory accesses. .. image:: figures/uprof-select-events.png @@ -569,14 +569,14 @@ Now click in advanced options to enable collection of the call stack. .. image:: figures/uprof-collect-callstack.png Then click ``Start Profile`` and wait for the program to end. -After it finishes you will be greeted with a hotspot summary screen, -but the ``Analyze`` tab (top of the screen) has sub-tabs with more +After it finishes you will be greeted with a hotspot summary screen, +but the ``Analyze`` tab (top of the screen) has sub-tabs with more relevant information. -In the following image the metrics are shown per module, including the +In the following image the metrics are shown per module, including the C library (libc.so.6) which provides the ``malloc`` and ``free`` functions. Values can be shown in terms of samples or percentages for easier reading -and to decide where to optimize. +and to decide where to optimize. .. image:: figures/uprof-stats.png @@ -597,23 +597,23 @@ Here are a few cases where AMD uProf was used to identify performance bottleneck #. ``wifi-primary-channels`` test suite was extremely slow due to unnecessary RF processing. The adopted solution was to replace the filtering step of the entire channel to just the desired sub-band, and assuming sub-bands are uniformly sized, saving multiplications in the integral - used to compute the power of each sub-band. This resulted in a 6x speedup with - ``./ns3 run "test-runner --fullness=TAKES_FOREVER --test-name=wifi-primary-channels"``. + used to compute the power of each sub-band. This resulted in a 6x speedup with + ``./ns3 run "test-runner --fullness=TAKES_FOREVER --test-name=wifi-primary-channels"``. More details on: `issue 426`_ and merge request `MR677`_. #. Continuing the work on ``wifi-primary-channels`` test suite, profiling showed an excessive - number of cache misses in ``InterferenceHelper::GetNextPosition``. + number of cache misses in ``InterferenceHelper::GetNextPosition``. This function searches for an iterator on a map, which is very fast if the map is small and fits in the cache, which was not the case. After reviewing the code, it was noticed in most cases this call was unnecessary as the iterator was already known. - The adopted solution was to reuse the iterator whenever possible. - This resulted in a 1.78x speedup on top of the previous 6x with + The adopted solution was to reuse the iterator whenever possible. + This resulted in a 1.78x speedup on top of the previous 6x with ``./ns3 run "test-runner --fullness=TAKES_FOREVER --test-name=wifi-primary-channels"``. More details on: `issue 426`_ and merge requests `MR677`_ and `MR680`_. -#. Position-Independent Code libraries (``-fPIC``) have an additional layer of indirection that increases +#. Position-Independent Code libraries (``-fPIC``) have an additional layer of indirection that increases instruction cache misses. The adopted solution was to disable `semantic interposition`_ with flag - ``-fno-semantic-interposition`` on GCC. This is the default setting on Clang. This results in + ``-fno-semantic-interposition`` on GCC. This is the default setting on Clang. This results in approximately 1.14x speedup with ``./test.py -d``. More details on: `MR777`_. Note: all speedups above were measured on the same machine. Results may differ based on clock speeds, @@ -622,39 +622,39 @@ cache sizes, number of cores, memory bandwidth and latency, storage throughput a Intel VTune +++++++++++ -`Intel VTune`_ works much like `Linux Perf and Hotspot GUI`_, but +`Intel VTune`_ works much like `Linux Perf and Hotspot GUI`_, but is available in more platforms (Linux, Windows and Mac) using Intel -processors. Differently from Perf, it provides more performance +processors. Differently from Perf, it provides more performance trackers for finer analysis. -When you open the program, you will be greeted by the landing page +When you open the program, you will be greeted by the landing page shown in the following image. To start a new profiling project, click -in the ``Configure Analysis`` button. If you already have a project, -right-click the entry and click to configure analysis to reuse the +in the ``Configure Analysis`` button. If you already have a project, +right-click the entry and click to configure analysis to reuse the settings. .. image:: figures/vtune-landing.png A configuration page will open, where you can fill the fields with -the path to the program, arguments, and set working directory and -environment variables. +the path to the program, arguments, and set working directory and +environment variables. Note: in this example on Windows using MinGW, -we need to define the ``PATH`` environment variable with the paths -to both ``~/ns-3-dev/build/lib`` and the MinGW binaries folder +we need to define the ``PATH`` environment variable with the paths +to both ``~/ns-3-dev/build/lib`` and the MinGW binaries folder (``~/msys64/mingw64/bin``), which contains essential libraries. -On Linux-like systems you will need to define the +On Linux-like systems you will need to define the ``LD_LIBRARY_PATH`` environment variable instead of ``PATH``. Clicking on the ``Performance Snapshot`` shows the different profiling -options. +options. .. image:: figures/vtune-configure.png -If executed as is, a quicker profiling will be executed to +If executed as is, a quicker profiling will be executed to determine what areas should be profiled with more details. -For the specific example, it is indicated that there are -microarchitectural bottlenecks and low parallelism +For the specific example, it is indicated that there are +microarchitectural bottlenecks and low parallelism (not a surprise since ns-3 is single-threaded). .. image:: figures/vtune-perf-snapshot.png @@ -678,7 +678,7 @@ mispredictions), bad speculation, cache misses, unused load ports, and more. The stats for the wifi module are shown below. The retiring -metric indicates about 40% of dispatched instructions are +metric indicates about 40% of dispatched instructions are executed. The diagram on the right shows the bottleneck is in the front-end of the pipeline (red), due to high instruction cache misses, translation lookaside buffer (TLB) @@ -686,10 +686,10 @@ overhead and unknown branches (most likely callbacks). .. image:: figures/vtune-uarch-wifi-stats.png -The stats for the core module are shown below. +The stats for the core module are shown below. More specifically for the ns3::Object::DoGetObject function. Metrics indicates about 63% of bad speculations. -The diagram on the right shows that there are bottlenecks +The diagram on the right shows that there are bottlenecks both in the front-end and due to bad speculation (red). .. image:: figures/vtune-uarch-core-stats.png @@ -703,7 +703,7 @@ System calls profilers .. _procmon : https://docs.microsoft.com/en-us/sysinternals/downloads/procmon System call profilers collect information on which system -calls were made by a program, how long they took to be +calls were made by a program, how long they took to be fulfilled and how many of them resulted in errors. There are many system call profilers, including `dtrace`_, `strace`_ and `procmon`_. @@ -714,8 +714,8 @@ Strace ++++++ -The `strace`_ is a system calls (syscalls) profiler for Linux. It can filter -specific syscalls, or gather stats during the execution. +The `strace`_ is a system calls (syscalls) profiler for Linux. It can filter +specific syscalls, or gather stats during the execution. To collect statistics, use ``strace -c``: @@ -734,10 +734,10 @@ To collect statistics, use ``strace -c``: ------ ----------- ----------- --------- --------- ---------------- 100.00 0.011515 8 1378 251 total -In the example above, the syscalls are listed in the right, after +In the example above, the syscalls are listed in the right, after the time spent on each syscall, number of calls and errors. -The errors can be caused due to multiple reasons and may not +The errors can be caused due to multiple reasons and may not be a problem. To check if they were problems, strace can log the syscalls with ``strace -o calls.log``: @@ -750,7 +750,7 @@ syscalls with ``strace -o calls.log``: 11 160 MHz 800 ns 524.459 Mbit/s -Looking at the ``calls.log`` file, we can see different sections. In the +Looking at the ``calls.log`` file, we can see different sections. In the following section, the example is executed (``execve``), architecture is checked (``arch_prctl``), memory is mapped for execution (``mmap``) and LD_PRELOAD use is checked. @@ -772,14 +772,14 @@ Then the program searches for the wifi module library and fails multiple times ( openat(AT_FDCWD, "~/ns-3-dev/build/lib/x86_64/libns3-dev-wifi.so", O_RDONLY|O_CLOEXEC) = -1 ENOENT (No such file or directory) newfstatat(AT_FDCWD, "~/ns-3-dev/build/lib/x86_64", 0x7ffff8d62c80, 0) = -1 ENOENT (No such file or directory) -The library is finally found and its header is read: +The library is finally found and its header is read: .. sourcecode:: console openat(AT_FDCWD, "~/ns-3-dev/build/lib/libns3-dev-wifi.so", O_RDONLY|O_CLOEXEC) = 3 read(3, "\177ELF\2\1\1\3\0\0\0\0\0\0\0\0\3\0>\0\1\0\0\0py\30\0\0\0\0\0"..., 832) = 832 -Then other modules that wifi depends on are loaded, then execution of the program continues to the main +Then other modules that wifi depends on are loaded, then execution of the program continues to the main function of the simulation. Strace was used to track down issues found while running the ``lena-radio-link-failure`` example. @@ -802,8 +802,8 @@ Its ``strace -c`` table was the following: 100,00 0,781554 1 411681 951 total Notice the number of ``openat``, ``write``, ``close`` and ``lseek`` calls -are much more frequent than the other calls. These mean -``lena-radio-link-failure`` is opening, then seeking, then writing, +are much more frequent than the other calls. These mean +``lena-radio-link-failure`` is opening, then seeking, then writing, then closing at least one file handler. Using ``strace``, we can easily find the most frequently used file handlers. @@ -835,21 +835,21 @@ Using ``strace``, we can easily find the most frequently used file handlers. With the name of the files, we can look at the code that manipulates them. -The issue above was found in `MR777`_, were performance for some LTE examples -regressed for no apparent reason. The flame graph below, produced by `AMD uProf`_, -contains four large columns/"flames" in red, which +The issue above was found in `MR777`_, were performance for some LTE examples +regressed for no apparent reason. The flame graph below, produced by `AMD uProf`_, +contains four large columns/"flames" in red, which correspond to the ``write``, ``openat``, ``close`` and ``lseek`` syscalls. .. image:: figures/uprof-strace-lte.png -Upon closer inspection, these syscalls take a long time to complete due to +Upon closer inspection, these syscalls take a long time to complete due to the underlying filesystem of the machine running the example (NTFS mount -using the ntfs-3g FUSE filesystem). In other words, the bottleneck only -exists when running the example in slow file systems -(e.g. FUSE and network file systems). +using the ntfs-3g FUSE filesystem). In other words, the bottleneck only +exists when running the example in slow file systems +(e.g. FUSE and network file systems). The merge request `MR814`_ addressed the issue by keeping the files open -throughout the simulation. That alone resulted in a 1.75x speedup. +throughout the simulation. That alone resulted in a 1.75x speedup. Compilation Profilers @@ -859,7 +859,7 @@ Compilation profilers can help identifying which steps of the compilation are slowing it down. These profilers are built into the compilers themselves, only requiring third-party tools to consolidate the results. -The GCC feature is mentioned and exemplified, but is not the recommended +The GCC feature is mentioned and exemplified, but is not the recommended compilation profiling method. For that, Clang is recommended. GCC @@ -899,14 +899,14 @@ output for a file is shown below. The line of ``---`` was inserted for clarity. TOTAL : 0.67 0.20 0.88 78612 kB In the table above, the first few lines show the five main compilations steps: ``setup``, -``parsing``, ``lang. deferred`` (C++ specific transformations), -``opt(imize) and generate (code)``, ``last asm`` (produce binary code). +``parsing``, ``lang. deferred`` (C++ specific transformations), +``opt(imize) and generate (code)``, ``last asm`` (produce binary code). The lines below the ``---`` line show sub-steps of the five main compilation steps. -For this specific case, parsing global definitions (21%) and structures (16%), +For this specific case, parsing global definitions (21%) and structures (16%), ``template instantiation`` (16%) and generating the code in ``symout`` (10%). -Aggregating the data into a meaningful output to help focus where to improve is not that easy +Aggregating the data into a meaningful output to help focus where to improve is not that easy and it is `not a priority`_ for GCC developers. It is recommended to use the Clang alternative. @@ -920,8 +920,8 @@ Clang can output very similar results with the ``-ftime-trace`` flag, but can al it in a more meaningful way. With the help of the third-party tool `ClangBuildAnalyzer`_, we can have really good insights on where to spend time trying to speed up the compilation. -Support for building with ``-ftime-trace``, compiling `ClangBuildAnalyzer`_ and producing a -report for the project have been baked into the CMake project of ns-3, and can be enabled +Support for building with ``-ftime-trace``, compiling `ClangBuildAnalyzer`_ and producing a +report for the project have been baked into the CMake project of ns-3, and can be enabled with ``-DNS3_CLANG_TIMETRACE=ON``. .. sourcecode:: console @@ -1019,13 +1019,13 @@ The entire procedure looks like the following: lte-test-rlc-um-transmitter.cc.o simulator.h event-id.h (560 ms) ... - + done in 2.8s. -The output printed out contain a summary of time spent on parsing and on code generation, along +The output printed out contain a summary of time spent on parsing and on code generation, along with multiple lists for different tracked categories. From the summary, it is clear that parsing times are very high when compared to the optimization time (``-O3``). Skipping the others categories and going straight -to the expensive headers section, we can better understand why parsing times are so high, with some headers +to the expensive headers section, we can better understand why parsing times are so high, with some headers adding as much as 5 minutes of CPU time to the parsing time. .. _drastically speed up parsing times : https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/731#note_687176503 @@ -1038,7 +1038,7 @@ compilation at the cost of increasing recompilation times. CMake Profiler ************** -CMake has a built-in tracer that permits tracking hotspots in the CMake files slowing down the +CMake has a built-in tracer that permits tracking hotspots in the CMake files slowing down the project configuration. To use the tracer, call cmake directly from a clean CMake cache directory: .. sourcecode:: console @@ -1055,14 +1055,14 @@ Or using the ns3 wrapper: .. _Perfetto UI: https://ui.perfetto.dev/ -A ``cmake_performance_trace.log`` file will be generated in the ns-3-dev directory. +A ``cmake_performance_trace.log`` file will be generated in the ns-3-dev directory. The tracing results can be visualized using the ``about:tracing`` panel available in Chromium-based browsers or a compatible trace viewer such as `Perfetto UI`_. After opening the trace file, select the traced process and click on any of the blocks to inspect the different stacks and find hotspots. -An auxiliary panel containing the function/macro name, arguments -and location can be shown, providing enough information to trace +An auxiliary panel containing the function/macro name, arguments +and location can be shown, providing enough information to trace back the location of each specific call. Just like in performance profilers, visual inspection makes it easier @@ -1083,7 +1083,7 @@ up-to-date copies of headers in the output directory. In `MR911`_, alternatives such as stub headers that include the original header files, keeping them in their respective modules, and symlinking headers to the -output directory were used to reduce the configuration overhead. +output directory were used to reduce the configuration overhead. Note: when testing I/O bottlenecks, you may want to drop filesystem caches, otherwise the cache may hide the issues. In Linux, the caches can be cleared diff --git a/doc/manual/source/python.rst b/doc/manual/source/python.rst index 5e7ffb642..1a1b9b6d1 100644 --- a/doc/manual/source/python.rst +++ b/doc/manual/source/python.rst @@ -35,11 +35,11 @@ regenerated by an automated scanning process. If a user is not interested in Python, no action is needed; by default, Python bindings are disabled (and must be explicitly enabled at CMake configure time). In this case, changes to the C++ -API of a provided module will not cause the module to fail to compile. +API of a provided module will not cause the module to fail to compile. The process for automatically generating Python bindings relies on a toolchain involving a development installation of the Clang compiler, a program called -CastXML (https://github.com/CastXML/CastXML), and a program called +CastXML (https://github.com/CastXML/CastXML), and a program called pygccxml (https://github.com/gccxml/pygccxml). The toolchain can be installed using the ns-3 ``bake`` build tool. @@ -67,42 +67,42 @@ Here is some example code that is written in Python and that runs |ns3|, which i import ns.internet import ns.network import ns.point_to_point - + ns.core.LogComponentEnable("UdpEchoClientApplication", ns.core.LOG_LEVEL_INFO) ns.core.LogComponentEnable("UdpEchoServerApplication", ns.core.LOG_LEVEL_INFO) - + nodes = ns.network.NodeContainer() nodes.Create(2) - + pointToPoint = ns.point_to_point.PointToPointHelper() pointToPoint.SetDeviceAttribute("DataRate", ns.core.StringValue("5Mbps")) pointToPoint.SetChannelAttribute("Delay", ns.core.StringValue("2ms")) - + devices = pointToPoint.Install(nodes) - + stack = ns.internet.InternetStackHelper() stack.Install(nodes) - + address = ns.internet.Ipv4AddressHelper() address.SetBase(ns.network.Ipv4Address("10.1.1.0"), ns.network.Ipv4Mask("255.255.255.0")) - + interfaces = address.Assign (devices); - + echoServer = ns.applications.UdpEchoServerHelper(9) - + serverApps = echoServer.Install(nodes.Get(1)) serverApps.Start(ns.core.Seconds(1.0)) serverApps.Stop(ns.core.Seconds(10.0)) - + echoClient = ns.applications.UdpEchoClientHelper(interfaces.GetAddress(1), 9) echoClient.SetAttribute("MaxPackets", ns.core.UintegerValue(1)) echoClient.SetAttribute("Interval", ns.core.TimeValue(ns.core.Seconds (1.0))) echoClient.SetAttribute("PacketSize", ns.core.UintegerValue(1024)) - + clientApps = echoClient.Install(nodes.Get(0)) clientApps.Start(ns.core.Seconds(2.0)) clientApps.Stop(ns.core.Seconds(10.0)) - + ns.core.Simulator.Run() ns.core.Simulator.Destroy() @@ -164,7 +164,7 @@ First of all, keep in mind that not 100% of the API is supported in Python. Som #. some of the APIs involve pointers, which require knowledge of what kind of memory passing semantics (who owns what memory). Such knowledge is not part of the function signatures, and is either documented or sometimes not even documented. Annotations are needed to bind those functions; #. Sometimes a unusual fundamental data type or C++ construct is used which is not yet supported by PyBindGen; -#. CastXML does not report template based classes unless they are instantiated. +#. CastXML does not report template based classes unless they are instantiated. Most of the missing APIs can be wrapped, given enough time, patience, and expertise, and will likely be wrapped if bug reports are submitted. However, don't file a bug report saying "bindings are incomplete", because the project does not have maintainers to maintain every API. @@ -232,7 +232,7 @@ There is one caveat: you must not allow the file object to be garbage collected Working with Python Bindings **************************** -Python bindings are built on a module-by-module basis, and can be found in each module's ``bindings`` directory. +Python bindings are built on a module-by-module basis, and can be found in each module's ``bindings`` directory. Overview ======== @@ -283,7 +283,7 @@ Process Overview |ns3| has an automated process to regenerate Python bindings from the C++ header files. The process is only supported for Linux at the moment because the project has not found a contributor yet to test and -document the capability on macOS. In short, the process currently +document the capability on macOS. In short, the process currently requires the following steps on a Linux machine. 1. Prepare the system for scanning by installing the prerequisites, @@ -332,7 +332,7 @@ Perform a configuration at the bake level: $ ./bake.py configure -e ns-3-dev -e pygccxml -The output of ``./bake.py show`` should show something like this: +The output of ``./bake.py show`` should show something like this: .. sourcecode:: bash @@ -363,7 +363,7 @@ report as Missing. For Python bindings, the important prerequisites are clang-dev, cmake, cxxfilt, llvm-dev, python3-dev, and python3-setuptools. In the following process, the following programs and libraries will be locally installed: castxml, pybindgen, pygccxml, -and |ns3|. +and |ns3|. Note also that the `ns-3-allinone` target for bake will also include the `pygccxml` and `ns-3-dev` targets (among other libraries) and can be @@ -386,38 +386,38 @@ is present or missing on your system. >> Searching for system dependency clang-dev - OK >> Searching for system dependency qt - Problem > Problem: Optional dependency, module "qt" not available - This may reduce the functionality of the final build. + This may reduce the functionality of the final build. However, bake will continue since "qt" is not an essential dependency. For more information call bake with -v or -vvv, for full verbose mode. - + >> Searching for system dependency g++ - OK >> Searching for system dependency cxxfilt - OK >> Searching for system dependency setuptools - OK >> Searching for system dependency python3-setuptools - OK >> Searching for system dependency gi-cairo - Problem > Problem: Optional dependency, module "gi-cairo" not available - This may reduce the functionality of the final build. + This may reduce the functionality of the final build. However, bake will continue since "gi-cairo" is not an essential dependency. For more information call bake with -v or -vvv, for full verbose mode. - + >> Searching for system dependency gir-bindings - Problem > Problem: Optional dependency, module "gir-bindings" not available - This may reduce the functionality of the final build. + This may reduce the functionality of the final build. However, bake will continue since "gir-bindings" is not an essential dependency. For more information call bake with -v or -vvv, for full verbose mode. - + >> Searching for system dependency pygobject - Problem > Problem: Optional dependency, module "pygobject" not available - This may reduce the functionality of the final build. + This may reduce the functionality of the final build. However, bake will continue since "pygobject" is not an essential dependency. For more information call bake with -v or -vvv, for full verbose mode. - + >> Searching for system dependency pygraphviz - Problem > Problem: Optional dependency, module "pygraphviz" not available - This may reduce the functionality of the final build. + This may reduce the functionality of the final build. However, bake will continue since "pygraphviz" is not an essential dependency. For more information call bake with -v or -vvv, for full verbose mode. - + >> Searching for system dependency python3-dev - OK >> Searching for system dependency cmake - OK >> Downloading castxml - OK @@ -425,7 +425,7 @@ is present or missing on your system. >> Downloading pybindgen - OK >> Downloading pygccxml - OK >> Downloading ns-3-dev - OK - + Build ##### @@ -451,7 +451,7 @@ C++ code), it will report a failure instead: :: >> Building ns-3-dev - Problem - > Error: Critical dependency, module "ns-3-dev" failed + > Error: Critical dependency, module "ns-3-dev" failed For more information call Bake with --debug and/or -v, -vvv, for full verbose mode (bake --help) At this point, it is recommended to change into the ns-3-dev directory and @@ -483,15 +483,15 @@ data models, as explained here: https://www.ibm.com/support/knowledgecenter/en/ Linux uses the LP64 model, and MacOS (as well as 32-bit Linux) use the ILP32 model. Users will note that there are two versions of bindings files in -each ns-3 module directory; one with an ILP32.py suffix and one with +each ns-3 module directory; one with an ILP32.py suffix and one with an LP64.py suffix. Only one is used on any given platform. The main difference is in the representation of the 64 bit integer type as either -a 'long' (LP64) or 'long long' (ILP32). +a 'long' (LP64) or 'long long' (ILP32). The process (only supported on Linux at present) generates the LP64 bindings using the toolchain and then copies the LP64 bindings to the ILP32 bindings with some type substitutions automated by CMake scripts. - + Rescanning a module ################### @@ -532,7 +532,7 @@ Generating bindings on MacOS In principle, this should work (and should generate the 32-bit bindings). However, maintainers have not been available to complete this port to date. -We would welcome suggestions on how to enable scanning for MacOS. +We would welcome suggestions on how to enable scanning for MacOS. Regenerating the Python bindings using gitlab-ci-local ====================================================== @@ -570,10 +570,10 @@ To allow an unprivileged user to use Docker, perform the following: $ sudo chmod 666 /var/run/docker.sock -The following command will obtain a raw shell for an Ubuntu 20.04 image: +The following command will obtain a raw shell for an Ubuntu 20.04 image: .. sourcecode:: bash - + $ docker run -it ubuntu:20.04 However, if you prefer to work on your current directory from the container @@ -620,7 +620,7 @@ The ``src//bindings`` directory may contain the following files, some of * ``modulegen_customizations.py``: you may optionally add this file in order to customize the pybindgen code generation * ``scan-header.h``: you may optionally add this file to customize what header file is scanned for the module. Basically this file is scanned instead of ns3/-module.h. Typically, the first statement is #include "ns3/-module.h", plus some other stuff to force template instantiations; * ``module_helpers.cc``: you may add additional files, such as this, to be linked to python extension module. They will be automatically scanned; -* ``.py``: if this file exists, it becomes the "frontend" python module for the ns3 module, and the extension module (.so file) becomes _.so instead of .so. The .py file has to import all symbols from the module _ (this is more tricky than it sounds, see src/core/bindings/core.py for an example), and then can add some additional pure-python definitions. +* ``.py``: if this file exists, it becomes the "frontend" python module for the ns3 module, and the extension module (.so file) becomes _.so instead of .so. The .py file has to import all symbols from the module _ (this is more tricky than it sounds, see src/core/bindings/core.py for an example), and then can add some additional pure-python definitions. Historical Information ********************** diff --git a/doc/manual/source/random-variables.rst b/doc/manual/source/random-variables.rst index 3ae8f6695..457974692 100644 --- a/doc/manual/source/random-variables.rst +++ b/doc/manual/source/random-variables.rst @@ -7,7 +7,7 @@ Random Variables |ns3| contains a built-in pseudo-random number generator (PRNG). It is important for serious users of the simulator to understand the functionality, configuration, and usage of this PRNG, and to decide whether it is sufficient -for his or her research use. +for his or her research use. Quick Overview ************** @@ -17,7 +17,7 @@ Quick Overview * by default, |ns3| simulations use a fixed seed; if there is any randomness in the simulation, each run of the program will yield identical results unless - the seed and/or run number is changed. + the seed and/or run number is changed. * in *ns-3.3* and earlier, |ns3| simulations used a random seed by default; this marks a change in policy starting with *ns-3.4*. @@ -46,24 +46,24 @@ Read further for more explanation about the random number facility for |ns3|. Background ********** -Simulations use a lot of random numbers; one study -found that most network simulations spend as much as 50% +Simulations use a lot of random numbers; one study +found that most network simulations spend as much as 50% of the CPU generating random numbers. Simulation users need to be concerned with the quality of the (pseudo) random numbers and -the independence between different streams of random numbers. +the independence between different streams of random numbers. Users need to be concerned with a few issues, such as: -* the seeding of the random number generator and whether a +* the seeding of the random number generator and whether a simulation outcome is deterministic or not, -* how to acquire different streams of random numbers that are - independent from one another, and +* how to acquire different streams of random numbers that are + independent from one another, and * how long it takes for streams to cycle We will introduce a few terms here: a RNG provides a long sequence of (pseudo) random numbers. The length of this sequence is called the *cycle length* -or *period*, after which the RNG will repeat itself. +or *period*, after which the RNG will repeat itself. This sequence can be partitioned into disjoint *streams*. A stream of a RNG is a contiguous subset or block of the RNG sequence. @@ -73,10 +73,10 @@ RNG, then the first stream might use the first N/2 values and the second stream might produce the second N/2 values. An important property here is that the two streams are uncorrelated. Likewise, each -stream can be partitioned disjointedly to a number of +stream can be partitioned disjointedly to a number of uncorrelated *substreams*. The underlying RNG hopefully produces a pseudo-random sequence of numbers with a very long -cycle length, and partitions this into streams and substreams in an +cycle length, and partitions this into streams and substreams in an efficient manner. |ns3| uses the same underlying random number generator as does |ns2|: the @@ -85,7 +85,7 @@ http://www.iro.umontreal.ca/~lecuyer/myftp/papers/streams00.pdf. The MRG32k3a generator provides :math:`1.8x10^{19}` independent streams of random numbers, each of which consists of :math:`2.3x10^{15}` substreams. Each substream has a period (*i.e.*, the number of random numbers before overlap) of -:math:`7.6x10^{22}`. The period of the entire generator is :math:`3.1x10^{57}`. +:math:`7.6x10^{22}`. The period of the entire generator is :math:`3.1x10^{57}`. Class :cpp:class:`ns3::RandomVariableStream` is the public interface to this @@ -109,10 +109,10 @@ Creating random variables ************************* |ns3| supports a number of random variable objects from the base class -:cpp:class:`RandomVariableStream`. These objects derive from +:cpp:class:`RandomVariableStream`. These objects derive from :cpp:class:`ns3::Object` and are handled by smart pointers. -The correct way to create these objects is to use the templated +The correct way to create these objects is to use the templated `CreateObject<>` method, such as: :: @@ -124,7 +124,7 @@ then you can access values by calling methods on the object such as: :: myRandomNo = x->GetInteger (); - + If you try to instead do something like this: @@ -175,7 +175,7 @@ substream capability to produce multiple independent runs of the same simulation.* In other words, the more statistically rigorous way to configure multiple independent replications is to use a fixed seed and to advance the run number. This implementation allows for a maximum of :math:`2.3x10^{15}` -independent replications using the substreams. +independent replications using the substreams. For ease of use, it is not necessary to control the seed and run number from within the program; the user can set the ``NS_GLOBAL_VALUE`` environment @@ -209,7 +209,7 @@ base class provides a few methods for globally configuring the behavior of the random number generator. Derived classes provide API for drawing random variates from the particular distribution being supported. -Each RandomVariableStream created in the simulation is given a generator that is a +Each RandomVariableStream created in the simulation is given a generator that is a new RNGStream from the underlying PRNG. Used in this manner, the L'Ecuyer implementation allows for a maximum of :math:`1.8x10^19` random variables. Each random variable in a single replication can produce up to :math:`7.6x10^22` @@ -228,7 +228,7 @@ that access the next value in the substream. * \return A floating point random value */ double GetValue (void) const; - + /** * \brief Returns a random integer from the underlying distribution * \return Integer cast of ::GetValue() @@ -242,7 +242,7 @@ Types of RandomVariables ************************ The following types of random variables are provided, and are documented in the -|ns3| Doxygen or by reading ``src/core/model/random-variable-stream.h``. Users +|ns3| Doxygen or by reading ``src/core/model/random-variable-stream.h``. Users can also create their own custom random variables by deriving from class :cpp:class:`RandomVariableStream`. @@ -274,7 +274,7 @@ An example is in the propagation models for WifiNetDevice:: TypeId RandomPropagationDelayModel::GetTypeId (void) - { + { static TypeId tid = TypeId ("ns3::RandomPropagationDelayModel") .SetParent () .SetGroupName ("Propagation") @@ -303,7 +303,7 @@ Setting the stream number ************************* The underlying MRG32k3a generator provides 2^64 independent streams. -In ns-3, these are assigned sequentially starting from the first stream as +In ns-3, these are assigned sequentially starting from the first stream as new RandomVariableStream instances make their first call to GetValue(). As a result of how these RandomVariableStream objects are assigned to @@ -314,12 +314,12 @@ streams may (or may not) change. As a concrete example, a user running a comparative study between routing protocols may find that the act of changing one routing protocol for another -will notice that the underlying mobility pattern also changed. +will notice that the underlying mobility pattern also changed. Starting with ns-3.15, some control has been provided to users to allow -users to optionally fix the assignment of selected RandomVariableStream +users to optionally fix the assignment of selected RandomVariableStream objects to underlying streams. This is the ``Stream`` attribute, part -of the base class RandomVariableStream. +of the base class RandomVariableStream. By partitioning the existing sequence of streams from before: @@ -332,7 +332,7 @@ into two equal-sized sets: .. sourcecode:: text - <--------------------------------------------------------------------------> + <--------------------------------------------------------------------------> ^ ^^ ^ | || | stream 0 stream (2^63 - 1) stream 2^63 stream (2^64 - 1) @@ -353,7 +353,7 @@ of -1 means that a value will be automatically allocated). Publishing your results *********************** -When you publish simulation results, a key piece of configuration +When you publish simulation results, a key piece of configuration information that you should always state is how you used the random number generator. @@ -374,8 +374,8 @@ Summary Let's review what things you should do when creating a simulation. * Decide whether you are running with a fixed seed or random seed; a fixed seed - is the default, -* Decide how you are going to manage independent replications, if applicable, + is the default, +* Decide how you are going to manage independent replications, if applicable, * Convince yourself that you are not drawing more random values than the cycle length, if you are running a very long simulation, and * When you publish, follow the guidelines above about documenting your use of diff --git a/doc/manual/source/realtime.rst b/doc/manual/source/realtime.rst index df9d44123..d0c3db463 100644 --- a/doc/manual/source/realtime.rst +++ b/doc/manual/source/realtime.rst @@ -7,7 +7,7 @@ RealTime |ns3| has been designed for integration into testbed and virtual machine environments. To integrate with real network stacks and emit/consume packets, a real-time scheduler is needed to try to lock the simulation clock with the -hardware clock. We describe here a component of this: the RealTime scheduler. +hardware clock. We describe here a component of this: the RealTime scheduler. The purpose of the realtime scheduler is to cause the progression of the simulation clock to occur synchronously with respect to some external time base. @@ -41,7 +41,7 @@ executing events until it reaches a point where the next event is in the possible for the simulation to consume more time than the wall clock time. The other option "HardLimit" will cause the simulation to abort if the tolerance threshold is exceeded. This attribute is -``ns3::RealTimeSimulatorImpl::HardLimit`` and the default is 0.1 seconds. +``ns3::RealTimeSimulatorImpl::HardLimit`` and the default is 0.1 seconds. A different mode of operation is one in which simulated time is **not** frozen during an event execution. This mode of realtime simulation was implemented but @@ -55,7 +55,7 @@ Usage ***** The usage of the realtime simulator is straightforward, from a scripting -perspective. Users just need to set the attribute +perspective. Users just need to set the attribute ``SimulatorImplementationType`` to the Realtime simulator, such as follows: :: GlobalValue::Bind ("SimulatorImplementationType", @@ -93,4 +93,4 @@ smaller than the minimum sleep time, so we busy-wait for the remainder of the time. This means that the thread just sits in a for loop consuming cycles until the desired time arrives. After the combination of sleep- and busy-waits, the elapsed realtime (wall) clock should agree with the simulation time of the next -event and the simulation proceeds. +event and the simulation proceeds. diff --git a/doc/manual/source/test-background.rst b/doc/manual/source/test-background.rst index 1c4685c40..3d3ddea76 100644 --- a/doc/manual/source/test-background.rst +++ b/doc/manual/source/test-background.rst @@ -7,33 +7,33 @@ Background software testing.** Writing defect-free software is a difficult proposition. There are many -dimensions to the problem and there is much confusion regarding what is +dimensions to the problem and there is much confusion regarding what is meant by different terms in different contexts. We have found it worthwhile to spend a little time reviewing the subject and defining some terms. Software testing may be loosely defined as the process of executing a program -with the intent of finding errors. When one enters a discussion regarding -software testing, it quickly becomes apparent that there are many distinct +with the intent of finding errors. When one enters a discussion regarding +software testing, it quickly becomes apparent that there are many distinct mind-sets with which one can approach the subject. -For example, one could break the process into broad functional categories +For example, one could break the process into broad functional categories like ''correctness testing,'' ''performance testing,'' ''robustness testing'' and ''security testing.'' Another way to look at the problem is by life-cycle: -''requirements testing,'' ''design testing,'' ''acceptance testing,'' and +''requirements testing,'' ''design testing,'' ''acceptance testing,'' and ''maintenance testing.'' Yet another view is by the scope of the tested system. -In this case one may speak of ''unit testing,'' ''component testing,'' +In this case one may speak of ''unit testing,'' ''component testing,'' ''integration testing,'' and ''system testing.'' These terms are also not standardized in any way, and so ''maintenance testing'' and ''regression testing'' may be heard interchangeably. Additionally, these terms are often misused. -There are also a number of different philosophical approaches to software +There are also a number of different philosophical approaches to software testing. For example, some organizations advocate writing test programs -before actually implementing the desired software, yielding ''test-driven +before actually implementing the desired software, yielding ''test-driven development.'' Some organizations advocate testing from a customer perspective as soon as possible, following a parallel with the agile development process: ''test early and test often.'' This is sometimes called ''agile testing.'' It -seems that there is at least one approach to testing for every development +seems that there is at least one approach to testing for every development methodology. The |ns3| project is not in the business of advocating for any one of @@ -42,7 +42,7 @@ the test process. Like all major software products, |ns3| has a number of qualities that must be present for the product to succeed. From a testing perspective, some -of these qualities that must be addressed are that |ns3| must be +of these qualities that must be addressed are that |ns3| must be ''correct,'' ''robust,'' ''performant'' and ''maintainable.'' Ideally there should be metrics for each of these dimensions that are checked by the tests to identify when the product fails to meet its expectations / requirements. @@ -50,70 +50,70 @@ to identify when the product fails to meet its expectations / requirements. Correctness *********** -The essential purpose of testing is to determine that a piece of software -behaves ''correctly.'' For |ns3| this means that if we simulate -something, the simulation should faithfully represent some physical entity or +The essential purpose of testing is to determine that a piece of software +behaves ''correctly.'' For |ns3| this means that if we simulate +something, the simulation should faithfully represent some physical entity or process to a specified accuracy and precision. -It turns out that there are two perspectives from which one can view -correctness. Verifying that a particular model is implemented according -to its specification is generically called *verification*. The process of -deciding that the model is correct for its intended use is generically called +It turns out that there are two perspectives from which one can view +correctness. Verifying that a particular model is implemented according +to its specification is generically called *verification*. The process of +deciding that the model is correct for its intended use is generically called *validation*. Validation and Verification *************************** -A computer model is a mathematical or logical representation of something. It -can represent a vehicle, an elephant (see +A computer model is a mathematical or logical representation of something. It +can represent a vehicle, an elephant (see `David Harel's talk about modeling an elephant at SIMUTools 2009 `_, or a networking card. Models can also represent -processes such as global warming, freeway traffic flow or a specification of a -networking protocol. Models can be completely faithful representations of a -logical process specification, but they necessarily can never completely -simulate a physical object or process. In most cases, a number of -simplifications are made to the model to make simulation computationally -tractable. +processes such as global warming, freeway traffic flow or a specification of a +networking protocol. Models can be completely faithful representations of a +logical process specification, but they necessarily can never completely +simulate a physical object or process. In most cases, a number of +simplifications are made to the model to make simulation computationally +tractable. -Every model has a *target system* that it is attempting to simulate. The +Every model has a *target system* that it is attempting to simulate. The first step in creating a simulation model is to identify this target system and -the level of detail and accuracy that the simulation is desired to reproduce. -In the case of a logical process, the target system may be identified as ''TCP +the level of detail and accuracy that the simulation is desired to reproduce. +In the case of a logical process, the target system may be identified as ''TCP as defined by RFC 793.'' In this case, it will probably be desirable to create -a model that completely and faithfully reproduces RFC 793. In the case of a -physical process this will not be possible. If, for example, you would like to -simulate a wireless networking card, you may determine that you need, ''an -accurate MAC-level implementation of the 802.11 specification and [...] a -not-so-slow PHY-level model of the 802.11a specification.'' +a model that completely and faithfully reproduces RFC 793. In the case of a +physical process this will not be possible. If, for example, you would like to +simulate a wireless networking card, you may determine that you need, ''an +accurate MAC-level implementation of the 802.11 specification and [...] a +not-so-slow PHY-level model of the 802.11a specification.'' Once this is done, one can develop an abstract model of the target system. This is typically an exercise in managing the tradeoffs between complexity, resource requirements and accuracy. The process of developing an abstract model has been -called *model qualification* in the literature. In the case of a TCP -protocol, this process results in a design for a collection of objects, +called *model qualification* in the literature. In the case of a TCP +protocol, this process results in a design for a collection of objects, interactions and behaviors that will fully implement RFC 793 in |ns3|. In the case of the wireless card, this process results in a number of tradeoffs -to allow the physical layer to be simulated and the design of a network device -and channel for ns-3, along with the desired objects, interactions and behaviors. +to allow the physical layer to be simulated and the design of a network device +and channel for ns-3, along with the desired objects, interactions and behaviors. -This abstract model is then developed into an |ns3| model that +This abstract model is then developed into an |ns3| model that implements the abstract model as a computer program. The process of getting the -implementation to agree with the abstract model is called *model -verification* in the literature. +implementation to agree with the abstract model is called *model +verification* in the literature. The process so far is open loop. What remains is to make a determination that a -given ns-3 model has some connection to some reality -- that a model is an +given ns-3 model has some connection to some reality -- that a model is an accurate representation of a real system, whether a logical process or a physical -entity. +entity. -If one is going to use a simulation model to try and predict how some real -system is going to behave, there must be some reason to believe your results -- -i.e., can one trust that an inference made from the model translates into a +If one is going to use a simulation model to try and predict how some real +system is going to behave, there must be some reason to believe your results -- +i.e., can one trust that an inference made from the model translates into a correct prediction for the real system. The process of getting the ns-3 model behavior to agree with the desired target system behavior as defined by the model qualification process is called *model validation* in the literature. In the -case of a TCP implementation, you may want to compare the behavior of your ns-3 -TCP model to some reference implementation in order to validate your model. In -the case of a wireless physical layer simulation, you may want to compare the +case of a TCP implementation, you may want to compare the behavior of your ns-3 +TCP model to some reference implementation in order to validate your model. In +the case of a wireless physical layer simulation, you may want to compare the behavior of your model to that of real hardware in a controlled setting, The |ns3| testing environment provides tools to allow for both model @@ -122,58 +122,58 @@ validation and testing, and encourages the publication of validation results. Robustness ********** -Robustness is the quality of being able to withstand stresses, or changes in +Robustness is the quality of being able to withstand stresses, or changes in environments, inputs or calculations, etc. A system or design is ''robust'' if it can deal with such changes with minimal loss of functionality. -This kind of testing is usually done with a particular focus. For example, the -system as a whole can be run on many different system configurations to +This kind of testing is usually done with a particular focus. For example, the +system as a whole can be run on many different system configurations to demonstrate that it can perform correctly in a large number of environments. -The system can be also be stressed by operating close to or beyond capacity by +The system can be also be stressed by operating close to or beyond capacity by generating or simulating resource exhaustion of various kinds. This genre of testing is called ''stress testing.'' The system and its components may be exposed to so-called ''clean tests'' that -demonstrate a positive result -- that is that the system operates correctly in -response to a large variation of expected configurations. +demonstrate a positive result -- that is that the system operates correctly in +response to a large variation of expected configurations. -The system and its components may also be exposed to ''dirty tests'' which -provide inputs outside the expected range. For example, if a module expects a +The system and its components may also be exposed to ''dirty tests'' which +provide inputs outside the expected range. For example, if a module expects a zero-terminated string representation of an integer, a dirty test might provide an unterminated string of random characters to verify that the system does not -crash as a result of this unexpected input. Unfortunately, detecting such +crash as a result of this unexpected input. Unfortunately, detecting such ''dirty'' input and taking preventive measures to ensure the system does not fail catastrophically can require a huge amount of development overhead. In order to reduce development time, a decision was taken early on in the project -to minimize the amount of parameter validation and error handling in the +to minimize the amount of parameter validation and error handling in the |ns3| codebase. For this reason, we do not spend much time on dirty testing -- it would just uncover the results of the design decision we know we took. We do want to demonstrate that |ns3| software does work across some set -of conditions. We borrow a couple of definitions to narrow this down a bit. +of conditions. We borrow a couple of definitions to narrow this down a bit. The *domain of applicability* is a set of prescribed conditions for which -the model has been tested, compared against reality to the extent possible, and -judged suitable for use. The *range of accuracy* is an agreement between -the computerized model and reality within a domain of applicability. +the model has been tested, compared against reality to the extent possible, and +judged suitable for use. The *range of accuracy* is an agreement between +the computerized model and reality within a domain of applicability. -The |ns3| testing environment provides tools to allow for setting up -and running test environments over multiple systems (buildbot) and provides +The |ns3| testing environment provides tools to allow for setting up +and running test environments over multiple systems (buildbot) and provides classes to encourage clean tests to verify the operation of the system over the expected ''domain of applicability'' and ''range of accuracy.'' Performant ********** -Okay, ''performant'' isn't a real English word. It is, however, a very concise -neologism that is quite often used to describe what we want |ns3| to +Okay, ''performant'' isn't a real English word. It is, however, a very concise +neologism that is quite often used to describe what we want |ns3| to be: powerful and fast enough to get the job done. This is really about the broad subject of software performance testing. One of -the key things that is done is to compare two systems to find which performs -better (cf benchmarks). This is used to demonstrate that, for example, -|ns3| can perform a basic kind of simulation at least as fast as a +the key things that is done is to compare two systems to find which performs +better (cf benchmarks). This is used to demonstrate that, for example, +|ns3| can perform a basic kind of simulation at least as fast as a competing tool, or can be used to identify parts of the system that perform badly. @@ -183,15 +183,15 @@ of tests. Maintainability *************** -A software product must be maintainable. This is, again, a very broad +A software product must be maintainable. This is, again, a very broad statement, but a testing framework can help with the task. Once a model has been developed, validated and verified, we can repeatedly execute the suite of tests for the entire system to ensure that it remains valid and verified over its lifetime. When a feature stops functioning as intended after some kind of change to the -system is integrated, it is called generically a *regression*. -Originally the +system is integrated, it is called generically a *regression*. +Originally the term regression referred to a change that caused a previously fixed bug to reappear, but the term has evolved to describe any kind of change that breaks existing functionality. There are many kinds of regressions that may occur @@ -210,7 +210,7 @@ existing bug that had no affect is suddenly exposed in the system. This may be as simple as exercising a code path for the first time. A *performance regression* is one that causes the performance requirements -of the system to be violated. For example, doing some work in a low level +of the system to be violated. For example, doing some work in a low level function that may be repeated large numbers of times may suddenly render the system unusable from certain perspectives. diff --git a/doc/manual/source/test-overview.rst b/doc/manual/source/test-overview.rst index 1e4edefd6..e2666d0da 100644 --- a/doc/manual/source/test-overview.rst +++ b/doc/manual/source/test-overview.rst @@ -7,7 +7,7 @@ This chapter is concerned with the testing and validation of |ns3| software. This chapter provides -* background about terminology and software testing -* a description of the ns-3 testing framework -* a guide to model developers or new model contributors for how to write tests +* background about terminology and software testing +* a description of the ns-3 testing framework +* a guide to model developers or new model contributors for how to write tests diff --git a/doc/manual/source/tracing.rst b/doc/manual/source/tracing.rst index 225bb753f..c27069816 100644 --- a/doc/manual/source/tracing.rst +++ b/doc/manual/source/tracing.rst @@ -29,7 +29,7 @@ output, as in, :: ... std::cout << "The value of x is " << x << std::endl; ... - } + } This is workable in small environments, but as your simulations get more and more complicated, you end up with more and more prints and the task of parsing @@ -76,20 +76,20 @@ congestion window of a TCP model is a prime candidate for a trace source. Trace sources are not useful by themselves; they must be connected to other pieces of code that actually do something useful with the information provided by the source. The entities that consume trace information are called trace -sinks. Trace sources are generators of events and trace sinks are consumers. +sinks. Trace sources are generators of events and trace sinks are consumers. This explicit division allows for large numbers of trace sources to be scattered around the system in places which model authors believe might be useful. Unless a user connects a trace sink to one of these sources, nothing is output. This arrangement allows relatively unsophisticated users to attach new types of sinks to existing tracing sources, without requiring editing and recompiling the core -or models of the simulator. +or models of the simulator. There can be zero or more consumers of trace events generated by a trace source. One can think of a trace source as a kind of point-to-multipoint information -link. +link. -The "transport protocol" for this conceptual point-to-multipoint link is an +The "transport protocol" for this conceptual point-to-multipoint link is an |ns3| ``Callback``. Recall from the Callback Section that callback facility is a way to allow two @@ -110,21 +110,21 @@ The Simplest Example It will be useful to go walk a quick example just to reinforce what we've said.:: - + #include "ns3/object.h" #include "ns3/uinteger.h" #include "ns3/traced-value.h"" #include "ns3/trace-source-accessor.h" - + #include - + using namespace ns3; The first thing to do is include the required files. As mentioned above, the trace system makes heavy use of the Object and Attribute systems. The first two includes bring in the declarations for those systems. The file, ``traced-value.h`` brings in the required declarations for tracing data that -obeys value semantics. +obeys value semantics. In general, value semantics just means that you can pass the object around, not an address. In order to use value semantics at all you have to have an object @@ -150,7 +150,7 @@ made using those operators.:: ; return tid; } - + MyObject () {} TracedValue m_myInt; }; @@ -179,7 +179,7 @@ function. This function will be called whenever one of the operators of the main (int argc, char *argv[]) { Ptr myObject = CreateObject (); - + myObject->TraceConnectWithoutContext ("MyInteger", MakeCallback(&IntTrace)); myObject->m_myInt = 1234; @@ -233,7 +233,7 @@ system (taken from ``examples/tcp-large-transfer.cc``):: ... Config::ConnectWithoutContext ( - "/NodeList/0/$ns3::TcpL4Protocol/SocketList/0/CongestionWindow", + "/NodeList/0/$ns3::TcpL4Protocol/SocketList/0/CongestionWindow", MakeCallback (&CwndTracer)); This should look very familiar. It is the same thing as the previous example, @@ -260,10 +260,10 @@ happens. The leading "/" character in the path refers to a so-called namespace. One of the predefined namespaces in the config system is "NodeList" which is a list of all of -the nodes in the simulation. Items in the list are referred to by indices into the +the nodes in the simulation. Items in the list are referred to by indices into the list, so "/NodeList/0" refers to the zeroth node in the list of nodes created by the simulation. This node is actually a ``Ptr`` and so is a subclass of -an :cpp:class:`ns3::Object`. +an :cpp:class:`ns3::Object`. As described in the :ref:`Object-model` section, |ns3| supports an object aggregation model. The next path segment begins with the "$" character which @@ -311,7 +311,7 @@ There are three levels of interaction with the tracing system: generated or use existing trace sources in different ways, without modifying the core of the simulator; * Advanced users can modify the simulator core to add new tracing sources and - sinks. + sinks. Using Trace Helpers ******************* @@ -339,7 +339,7 @@ example, you may want to specify that pcap tracing should be enabled on a particular device on a specific node. This follows from the |ns3| device conceptual model, and also the conceptual models of the various device helpers. Following naturally from this, the files created follow a --- naming convention. +-- naming convention. Protocol helpers look at the problem of specifying which traces should be enabled through a protocol and interface pair. This follows from the |ns3| @@ -363,7 +363,7 @@ possible there are analogs for all methods in all classes. We use an approach called a ``mixin`` to add tracing functionality to our helper classes. A ``mixin`` is a class that provides functionality to that is inherited by a subclass. Inheriting from a mixin is not considered a form of -specialization but is really a way to collect functionality. +specialization but is really a way to collect functionality. Let's take a quick look at all four of these cases and their respective ``mixins``. @@ -512,7 +512,7 @@ Finally, two of the methods shown above,:: have a default parameter called ``explicitFilename``. When set to true, this parameter disables the automatic filename completion mechanism and allows you to create an explicit filename. This option is only available in the methods which -enable pcap tracing on a single device. +enable pcap tracing on a single device. For example, in order to arrange for a device helper to create a single promiscuous pcap capture file of a specific name (``my-pcap-file.pcap``) on a @@ -528,8 +528,8 @@ tells the helper to interpret the ``prefix`` parameter as a complete filename. Ascii Tracing Device Helpers ++++++++++++++++++++++++++++ -The behavior of the ASCII trace helper ``mixin`` is substantially similar to -the pcap version. Take a look at ``src/network/helper/trace-helper.h`` if you want to +The behavior of the ASCII trace helper ``mixin`` is substantially similar to +the pcap version. Take a look at ``src/network/helper/trace-helper.h`` if you want to follow the discussion while looking at real code. The class ``AsciiTraceHelperForDevice`` adds the high level functionality for @@ -550,11 +550,11 @@ methods,:: void EnableAscii (Ptr stream, Ptr nd); will call the device implementation of ``EnableAsciiInternal`` directly, -providing either a valid prefix or stream. All other public ASCII tracing +providing either a valid prefix or stream. All other public ASCII tracing methods will build on these low-level functions to provide additional user-level -functionality. What this means to the user is that all device helpers in the +functionality. What this means to the user is that all device helpers in the system will have all of the ASCII trace methods available; and these methods -will all work in the same way across devices if the devices implement +will all work in the same way across devices if the devices implement ``EnablAsciiInternal`` correctly. Ascii Tracing Device Helper Methods @@ -623,9 +623,9 @@ user is completely specifying the file name, the string should include the ".tr" for consistency. You can enable ASCII tracing on a particular node/net-device pair by providing a -``std::string`` representing an object name service string to an +``std::string`` representing an object name service string to an ``EnablePcap`` method. The ``Ptr`` is looked up from the name -string. Again, the ```` is implicit since the named net device must +string. Again, the ```` is implicit since the named net device must belong to exactly one ``Node``. For example,:: Names::Add ("client" ...); @@ -811,7 +811,7 @@ corresponding interface. For example,:: NodeContainer nodes; ... NetDeviceContainer devices = deviceHelper.Install (nodes); - ... + ... Ipv4AddressHelper ipv4; ipv4.SetBase ("10.1.1.0", "255.255.255.0"); Ipv4InterfaceContainer interfaces = ipv4.Assign (devices); @@ -865,7 +865,7 @@ would be "prefix-n21-i1.pcap". You can always use the |ns3| object name service to make this more clear. For example, if you use the object name service to assign the name "serverIpv4" -to the Ptr on node 21, the resulting pcap trace file name will +to the Ptr on node 21, the resulting pcap trace file name will automatically become, "prefix-nserverIpv4-i1.pcap". Ascii Tracing Protocol Helpers @@ -884,7 +884,7 @@ The class ``AsciiTraceHelperForIpv4`` adds the high level functionality for using ASCII tracing to a protocol helper. Each protocol that enables these methods must implement a single virtual method inherited from this class.:: - virtual void EnableAsciiIpv4Internal (Ptr stream, std::string prefix, + virtual void EnableAsciiIpv4Internal (Ptr stream, std::string prefix, Ptr ipv4, uint32_t interface) = 0; The signature of this method reflects the protocol- and interface-centric view @@ -936,7 +936,7 @@ pcap tracing. This is because, in addition to the pcap-style model where traces from each unique protocol/interface pair are written to a unique file, we support a model in which trace information for many protocol/interface pairs is written to a common file. This means that the -n- -file name generation mechanism is replaced by a mechanism to refer to a common +file name generation mechanism is replaced by a mechanism to refer to a common file; and the number of API methods is doubled to allow all combinations. Just as in pcap tracing, you can enable ASCII tracing on a particular @@ -982,9 +982,9 @@ between protocol instances and nodes, For example,:: helper.EnableAsciiIpv4 ("prefix", "node1Ipv4", 1); helper.EnableAsciiIpv4 ("prefix", "node2Ipv4", 1); -This would result in two files named "prefix-nnode1Ipv4-i1.tr" and -"prefix-nnode2Ipv4-i1.tr" with traces for each interface in the respective -trace file. Since all of the EnableAscii functions are overloaded to take a +This would result in two files named "prefix-nnode1Ipv4-i1.tr" and +"prefix-nnode2Ipv4-i1.tr" with traces for each interface in the respective +trace file. Since all of the EnableAscii functions are overloaded to take a stream wrapper, you can use that form as well:: Names::Add ("node1Ipv4" ...); @@ -1008,7 +1008,7 @@ one-to-one correspondence between each protocol and its node. For example,:: NodeContainer nodes; ... NetDeviceContainer devices = deviceHelper.Install (nodes); - ... + ... Ipv4AddressHelper ipv4; ipv4.SetBase ("10.1.1.0", "255.255.255.0"); Ipv4InterfaceContainer interfaces = ipv4.Assign (devices); @@ -1023,7 +1023,7 @@ traces into a single file is accomplished similarly to the examples above:: NodeContainer nodes; ... NetDeviceContainer devices = deviceHelper.Install (nodes); - ... + ... Ipv4AddressHelper ipv4; ipv4.SetBase ("10.1.1.0", "255.255.255.0"); Ipv4InterfaceContainer interfaces = ipv4.Assign (devices); @@ -1062,7 +1062,7 @@ associated protocol being the same type as that managed by the device helper.:: This would result in a number of ASCII trace files being created, one for every interface in the system related to a protocol of the type managed by the helper. All of these files will follow the -n-iBind (); The culprit here is that the return value of GetObject is not being checked and -may be null. +may be null. Sometimes you may need to use the `valgrind memory checker `_ for more subtle errors. Again, you invoke the use of diff --git a/doc/manual/source/utilities.rst b/doc/manual/source/utilities.rst index a371b2f03..1129c4efc 100644 --- a/doc/manual/source/utilities.rst +++ b/doc/manual/source/utilities.rst @@ -69,7 +69,7 @@ This will output the following:: * HelloInterval: HELLO messages emission interval. - + Bench-simulator *************** @@ -95,18 +95,18 @@ Command-line Arguments --prec: printed output precision [6] You can change the Scheduler being benchmarked by passing -the appropriate flags, for example if you want to +the appropriate flags, for example if you want to benchmark the CalendarScheduler pass `--cal` to the program. The default total number of events, runs or population size -can be overridden by passing `--total=value`, `--runs=value` -and `--pop=value` respectively. +can be overridden by passing `--total=value`, `--runs=value` +and `--pop=value` respectively. If you want to use event distribution which is stored in a file, -you can pass the file option by `--file=FILE_NAME`. +you can pass the file option by `--file=FILE_NAME`. `--prec` can be used to change the output precision value and -`--debug` as the name suggests enables debugging. +`--debug` as the name suggests enables debugging. Invocation ++++++++++ @@ -116,7 +116,7 @@ To run it, simply open the terminal and type .. sourcecode:: bash $ ./ns3 run bench-simulator - + It will show something like this depending upon the scheduler being benchmarked:: ns3-dev-bench-simulator-debug: @@ -138,7 +138,7 @@ Suppose we had to benchmark `CalendarScheduler` instead, we would have written .. sourcecode:: bash $ ./ns3 run "bench-simulator --cal" - + And the output would look something like this:: ns3-dev-bench-simulator-debug: diff --git a/doc/manual/source/working-with-git.rst b/doc/manual/source/working-with-git.rst index ae45ebf24..2653f0fe5 100644 --- a/doc/manual/source/working-with-git.rst +++ b/doc/manual/source/working-with-git.rst @@ -179,7 +179,7 @@ and we can see the edits with git diff: @@ -1439,6 +1439,10 @@ TcpSocketBase::ReceivedAck (Ptr packet, const TcpHeader& tcpHeader) // There is a DupAck ++m_dupAckCount; - + + // I'm introducing a subtle bug! + + m_tcb->m_cWnd = m_tcb->m_ssThresh; @@ -250,7 +250,7 @@ Submit work for review ********************** After you push your branch to origin, you can follow the instructions here https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html -to create a merge request. +to create a merge request. GitLab CI (Continous Integration) +++++++++++++++++++++++++++++++++ @@ -380,7 +380,7 @@ Make a commit of these files: Next, make the following change to RELEASE_NOTES and commit it: :: - + Availability ------------ -This release is not yet available. @@ -390,7 +390,7 @@ Next, make the following change to RELEASE_NOTES and commit it: $ git commit -m"Update availability in RELEASE_NOTES" RELEASE_NOTES Finally, add a git annotated tag: - + :: $ git tag -a 'ns-3.34' -m"ns-3.34 release" @@ -466,7 +466,7 @@ are committed to ``master`` on ``nsnam/ns-3-dev.git`` as usual:: ... (now fix a really important bug) $ echo 'abc' >> a $ git commit -m"Fix missing abc bug on file a" a - + Now the tree looks like this:: @@ -543,10 +543,10 @@ We can next hand-edit these files to restore them to original state, so that:: The new log should show something like the below, with parallel git history paths until the merge back again:: - + $ git log --graph --decorate --oneline --all * 815ce6e (HEAD -> master) Merge branch 'ns-3.34.1-release' - |\ + |\ | * 12a29ca (tag: ns-3.34.1) Update VERSION to 3.34.1 | * 21ebdbf Fix missing abc bug on file a * | ee37d41 Fix missing abc bug on file a @@ -554,8 +554,8 @@ history paths until the merge back again:: * | ba28d6d Add new feature * | e50015a make some changes * | fd075f6 Merge ns-3.34-release branch - |\ \ - | |/ + |\ \ + | |/ | * 3fab3cf (tag: ns-3.34) Update availability in RELEASE_NOTES | * c50aaf7 Update VERSION and documentation tags for ns-3.34 release |/ diff --git a/doc/manual/source/working-with-gitlab-ci-local.rst b/doc/manual/source/working-with-gitlab-ci-local.rst index 30617edfd..aba990b50 100644 --- a/doc/manual/source/working-with-gitlab-ci-local.rst +++ b/doc/manual/source/working-with-gitlab-ci-local.rst @@ -15,25 +15,25 @@ Working with gitlab-ci-local .. _rootless mode : https://docs.docker.com/engine/security/rootless/ The ns-3 project repository is currently hosted in GitLab, which includes -`continuos integration (CI)`_ tools to automate build, tests, packaging and -distribution of software. The CI works based on jobs, that are defined -on YAML files. +`continuos integration (CI)`_ tools to automate build, tests, packaging and +distribution of software. The CI works based on jobs, that are defined +on YAML files. -The ns-3 GitLab CI files are located in ``ns-3-dev/utils/tests/``. +The ns-3 GitLab CI files are located in ``ns-3-dev/utils/tests/``. The main GitLab CI file is ``gitlab-ci.yml``. The different jobs are used to check if a multitude of compilers and package versions -are compatible with the current ns-3 build, which is why a build is -usually followed by a test run. Other CI jobs build and warn about -missing the documentation. +are compatible with the current ns-3 build, which is why a build is +usually followed by a test run. Other CI jobs build and warn about +missing the documentation. -The GitLab CI jobs are executed based on `pipelines`_ containing a +The GitLab CI jobs are executed based on `pipelines`_ containing a sequence of job batches. Jobs within a batch can be executed in parallel. -These `pipelines`_ can be triggered manually, or scheduled to run automatically -per commit and/or based on a time period -(ns-3 has `daily and weekly pipelines`_ scheduled). +These `pipelines`_ can be triggered manually, or scheduled to run automatically +per commit and/or based on a time period +(ns-3 has `daily and weekly pipelines`_ scheduled). The GitLab CI free tier is very slow, taking a lot of time to identify -issues during active merge request development. +issues during active merge request development. Note: the free tier now requires a credit card due to `crypto miners abuse`_. @@ -42,18 +42,18 @@ now requires a credit card due to `crypto miners abuse`_. configuration files locally, allowing for the debugging of CI settings and pipelines without requiring pushes to test repositories or main repositories that fill up the CI job queues with failed jobs due to -script errors. +script errors. GitLab-CI-local relies on `Docker`_ to setup the environment to execute -the jobs. +the jobs. -Note: Docker is usually setup in root mode, requiring +Note: Docker is usually setup in root mode, requiring frequent use of administrative permissions/sudo. However, -this is highly discouraged. You can configure Docker to run -in `rootless mode`_. From this point onwards, we assume Docker is configured +this is highly discouraged. You can configure Docker to run +in `rootless mode`_. From this point onwards, we assume Docker is configured in `rootless mode`_. -After installing both `Docker`_ in `rootless mode`_ and `GitLab-CI-local`_, +After installing both `Docker`_ in `rootless mode`_ and `GitLab-CI-local`_, the ns-3 jobs can be listed using the following command: .. sourcecode:: bash @@ -61,30 +61,30 @@ the ns-3 jobs can be listed using the following command: ~/ns-3-dev$ gitlab-ci-local --file ./utils/tests/gitlab-ci.yml --list parsing and downloads finished in 226 ms name description stage when allow_failure needs - weekly-build-ubuntu-18.04-debug build on_success false - - ... + weekly-build-ubuntu-18.04-debug build on_success false - weekly-build-clang-11-optimized build on_success false - pybindgen build on_success false - per-commit-compile-debug build on_success false - per-commit-compile-release build on_success false - per-commit-compile-optimized build on_success false - daily-test-debug test on_success false - daily-test-release test on_success false - daily-test-optimized test on_success false - daily-test-optimized-valgrind test on_success false - weekly-test-debug-valgrind test on_success false - weekly-test-release-valgrind test on_success false - weekly-test-optimized-valgrind test on_success false - weekly-test-takes-forever-optimized test on_success false - doxygen documentation on_success false - manual documentation on_success false - tutorial documentation on_success false - models documentation on_success false + ... -To execute the ``per-commit-compile-release`` job, or any of the others listed above, use -the following command. + weekly-build-clang-11-optimized build on_success false + pybindgen build on_success false + per-commit-compile-debug build on_success false + per-commit-compile-release build on_success false + per-commit-compile-optimized build on_success false + daily-test-debug test on_success false + daily-test-release test on_success false + daily-test-optimized test on_success false + daily-test-optimized-valgrind test on_success false + weekly-test-debug-valgrind test on_success false + weekly-test-release-valgrind test on_success false + weekly-test-optimized-valgrind test on_success false + weekly-test-takes-forever-optimized test on_success false + doxygen documentation on_success false + manual documentation on_success false + tutorial documentation on_success false + models documentation on_success false + +To execute the ``per-commit-compile-release`` job, or any of the others listed above, use +the following command. .. sourcecode:: console @@ -161,6 +161,6 @@ Then run the doxygen job again: PASS doxygen Artifacts built by the CI jobs will be stored in separate subfolders -based on the job name. +based on the job name. ``~/ns-3-dev/.gitlab-ci-local/artifacts/jobname`` diff --git a/doc/models/Makefile b/doc/models/Makefile index 1908f0aa4..04719c003 100644 --- a/doc/models/Makefile +++ b/doc/models/Makefile @@ -102,9 +102,9 @@ SOURCES = \ $(SRC)/sixlowpan/doc/sixlowpan.rst \ $(SRC)/lr-wpan/doc/lr-wpan.rst \ -# list all model library figure files that need to be copied to +# list all model library figure files that need to be copied to # $SOURCETEMP/figures. For each figure to be included in all -# documentation formats (html, latex...) the following formats are supported: +# documentation formats (html, latex...) the following formats are supported: # 1) a single .dia file (preferred option, because it can be edited) # 2) a single .eps file # 3) both a .pdf and .png file @@ -472,7 +472,7 @@ IMAGES_EPS = \ # rescale pdf figures as necessary $(FIGURES)/testbed.pdf_width = 5in $(FIGURES)/emulated-channel.pdf_width = 6in -$(FIGURES)/antenna-coordinate-system.pdf_width = 7cm +$(FIGURES)/antenna-coordinate-system.pdf_width = 7cm $(FIGURES)/node.pdf_width = 5in $(FIGURES)/packet.pdf_width = 4in $(FIGURES)/buffer.pdf_width = 15cm @@ -501,7 +501,7 @@ $(FIGURES)/fr-soft-frequency-reuse-scheme-v1.pdf_width = 8cm $(FIGURES)/fr-soft-frequency-reuse-scheme-v2.pdf_width = 8cm $(FIGURES)/fr-strict-frequency-reuse-scheme.pdf_width = 8cm $(FIGURES)/ffr-distributed-scheme.pdf_width = 8cm -$(FIGURES)/lte-arch-enb-data.pdf_width = 6cm +$(FIGURES)/lte-arch-enb-data.pdf_width = 6cm $(FIGURES)/lte-arch-enb-ctrl.pdf_width = 10cm $(FIGURES)/lte-arch-ue-data.pdf_width = 6cm $(FIGURES)/lte-arch-ue-ctrl.pdf_width = 10cm @@ -561,7 +561,7 @@ BUILDDIR = build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCETEMP) +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCETEMP) .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest @@ -587,8 +587,8 @@ help: @echo " doctest to run all doctests embedded in the documentation (if enabled)" copy-sources: $(SOURCES) - @mkdir -p $(SOURCETEMP) - @mkdir -p $(FIGURES) + @mkdir -p $(SOURCETEMP) + @mkdir -p $(FIGURES) @cp -r -p $(SOURCES) $(SOURCETEMP) @cp -r -p $(SOURCEFIGS) $(FIGURES) @@ -601,7 +601,7 @@ frag: pickle pushd $(BUILDDIR)/frag && ../../pickle-to-xml.py ../pickle/index.fpickle > navigation.xml && popd cp -r $(BUILDDIR)/pickle/_images $(BUILDDIR)/frag -html: copy-sources $(IMAGES) +html: copy-sources $(IMAGES) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/doc/models/source/conf.py b/doc/models/source/conf.py index 0e1dd66c6..63294ce75 100644 --- a/doc/models/source/conf.py +++ b/doc/models/source/conf.py @@ -24,7 +24,7 @@ import sys, os # To change default code-block format in Latex to footnotesize (8pt) # Tip from https://stackoverflow.com/questions/9899283/how-do-you-change-the-code-example-font-size-in-latex-pdf-output-with-sphinx/9955928 -# Note: sizes are \footnotesize (8pt), \small (9pt), and \normalsize (10pt). +# Note: sizes are \footnotesize (8pt), \small (9pt), and \normalsize (10pt). #from sphinx.highlighting import PygmentsBridge #from pygments.formatters.latex import LatexFormatter @@ -274,7 +274,7 @@ latex_elements = { # (double backquotes) to either \footnotesize (8pt) or \small (9pt) # # See above to change the font size of verbatim code blocks - # + # # 'preamble': '', 'preamble': u'''\\usepackage{amssymb} \\definecolor{VerbatimBorderColor}{rgb}{1,1,1} diff --git a/doc/models/source/emulation-overview.rst b/doc/models/source/emulation-overview.rst index a47ac8604..071b7411e 100644 --- a/doc/models/source/emulation-overview.rst +++ b/doc/models/source/emulation-overview.rst @@ -24,7 +24,7 @@ One of the use-cases we want to support is that of a testbed. A concrete example of an environment of this kind is the ORBIT testbed. ORBIT is a laboratory emulator/field trial network arranged as a two dimensional grid of 400 802.11 radio nodes. We integrate with ORBIT by using their "imaging" process to load -and run |ns3| simulations on the ORBIT array. We can use our +and run |ns3| simulations on the ORBIT array. We can use our ``EmuFdNetDevice`` to drive the hardware in the testbed and we can accumulate results either using the |ns3| tracing and logging functions, or the native ORBIT data gathering @@ -36,7 +36,7 @@ A simulation of this kind is shown in the following figure: .. _testbed: .. figure:: figures/testbed.* - + Example Implementation of Testbed Emulation. You can see that there are separate hosts, each running a subset of a "global" diff --git a/doc/models/source/index.rst b/doc/models/source/index.rst index e3f089764..d21172a42 100644 --- a/doc/models/source/index.rst +++ b/doc/models/source/index.rst @@ -3,12 +3,12 @@ ns-3 Model Library ================== -This is the *ns-3 Model Library* documentation. Primary documentation for the ns-3 project is +This is the *ns-3 Model Library* documentation. Primary documentation for the ns-3 project is available in five forms: * `ns-3 Doxygen `_: Documentation of the public APIs of the simulator * Tutorial, Manual, and Model Library *(this document)* for the `latest release `_ and `development tree `_ -* `ns-3 wiki `_ +* `ns-3 wiki `_ This document is written in `reStructuredText `_ for `Sphinx `_ and is maintained in the ``doc/models`` directory of ns-3's source code. diff --git a/doc/models/source/organization.rst b/doc/models/source/organization.rst index 95ee91045..2e858e089 100644 --- a/doc/models/source/organization.rst +++ b/doc/models/source/organization.rst @@ -12,22 +12,22 @@ It is important to distinguish between **modules** and **models**: the modules (libraries) they need to conduct their simulation. * |ns3| *models* are abstract representations of real-world objects, - protocols, devices, etc. + protocols, devices, etc. An |ns3| module may consist of more than one model (for instance, the :mod:`internet` module contains models for both TCP and UDP). In general, -ns-3 models do not span multiple software modules, however. +ns-3 models do not span multiple software modules, however. -This manual provides documentation about the models of |ns3|. It +This manual provides documentation about the models of |ns3|. It complements two other sources of documentation concerning models: * the model APIs are documented, from a programming perspective, using `Doxygen `_. Doxygen for ns-3 models is available - `on the project web server `_. + `on the project web server `_. * the |ns3| core is documented in the developer's manual. |ns3| models make - use of the facilities of the core, such as attributes, default values, - random numbers, test frameworks, etc. Consult the + use of the facilities of the core, such as attributes, default values, + random numbers, test frameworks, etc. Consult the `main web site `_ to find copies of the manual. Finally, additional documentation about various aspects of |ns3| may @@ -35,7 +35,7 @@ exist on the `project wiki `_. A sample outline of how to write model library documentation can be found by executing the ``create-module.py`` program and looking at the -template created in the file ``new-module/doc/new-module.rst``. +template created in the file ``new-module/doc/new-module.rst``. .. sourcecode:: bash @@ -46,8 +46,8 @@ The remainder of this document is organized alphabetically by module name. If you are new to |ns3|, you might first want to read below about the network module, which contains some fundamental models for the simulator. -The packet model, models for different address formats, and abstract -base classes for objects such as nodes, net devices, channels, sockets, and +The packet model, models for different address formats, and abstract +base classes for objects such as nodes, net devices, channels, sockets, and applications are discussed there. diff --git a/doc/ns3_html_theme/get_version.sh b/doc/ns3_html_theme/get_version.sh index eae7c45e6..a2c00630c 100755 --- a/doc/ns3_html_theme/get_version.sh +++ b/doc/ns3_html_theme/get_version.sh @@ -29,7 +29,7 @@ # If both a and b are true, we're building for public urls. # (The newer update-docs script (through ns3) sets # NS3_WWW_URLS=public explicitly.) -# +# # The repo version is either a tag name or a commit (short) id. # # If we're building for nsnam.org, and at a tag, we use just @@ -64,7 +64,7 @@ function usage -n pretend we are on nsnam.org -d pretend we are in the automated build directory -t pretend we are at a repo tag - + EOF exit 1 } @@ -172,24 +172,24 @@ if [ $PUBLIC -eq 1 ]; then echo "// public urls" >> $outf # Generate URL relative to server root echo "var ns3_host = \"/\";" >> $outf - + if [ $distance -eq 1 ]; then # Like "http://www.nsnam.org/ns-3-14" vers_href="https://www.nsnam.org/ns-3-${version#ns-3.}" vers_href="$version$dirty" - + echo "var ns3_version = \"Release $vers_href\";" >> $outf echo "var ns3_release = \"docs/release/${version#ns-}/\";" >> $outf else vers_href="https://gitlab.com/nsnam/ns-3-dev/commits/$version" version="$version$dirty" - + echo "var ns3_version = \"ns-3-dev @ $version\";" >> $outf echo "var ns3_release = \"docs/\";" >> $outf fi echo "var ns3_local = \"\";" >> $outf echo "var ns3_doxy = \"doxygen/\";" >> $outf - + else repo=`basename $PWD` echo "// ns3_version.js: automatically generated" > $outf diff --git a/doc/ns3_html_theme/layout.html b/doc/ns3_html_theme/layout.html index ca54c5215..f167dda17 100644 --- a/doc/ns3_html_theme/layout.html +++ b/doc/ns3_html_theme/layout.html @@ -11,15 +11,15 @@ {% set reldelim1 = ' ' %} {# set reldelim1 = ' @' #} - + {%- block extrahead %} {%- if theme_customstylesheet %} {%- endif %} - + {%- if theme_favicon %} - {%- endif %} @@ -27,9 +27,9 @@ - + {% endblock %} - + {% block header %}
@@ -56,11 +56,11 @@ >  Home
  • Tutorials  ▼ -
  • Documentation  ▼
  • Development  ▼ {% endblock %} - + {% block rootrellink %}
  • {{ theme_projectname }} 
    • {{ super() }} {% endblock %} - + {% if theme_collapsiblesidebar|tobool %} {% set script_files = script_files + ['_static/sidebar.js'] %} {% endif %} diff --git a/doc/ns3_html_theme/ns3_doxy_header.html b/doc/ns3_html_theme/ns3_doxy_header.html index 17fd79c37..fe5c1849d 100644 --- a/doc/ns3_html_theme/ns3_doxy_header.html +++ b/doc/ns3_html_theme/ns3_doxy_header.html @@ -52,11 +52,11 @@ $extrastylesheet >  Home
  • Tutorials  ▼ -
  • Documentation  ▼
  • Development  ▼