Nsnam - User contributions [en]

GSOC2025Ntn

2025-07-25T09:49:59Z

Gabriel: /* Week 17 (August 24-30) */

{{TOC}}

Back to [[Summer_Projects#Google_Summer_of_Code_2025 | GSoC 2025 projects]]

= Project Overview =

* '''Project Name:''' NTN Helper and a LEO example for 5G NR
* '''Student:''' Thiago Miyazaki
* '''Mentors:''' Gabriel Ferreira, Biljana Bojovic, Amir Ashtari Gargari and Katerina Koutlia
* '''Google page:''' https://summerofcode.withgoogle.com/myprojects/details/Z1PZUHaC
* '''Project Goals:''' Create a simplified means for users to instantiate and set up GEO and LEO satellites through Helper models, providing a high-level interface for users interested in simulations using LEO and GEO satellites. Write a LEO example using implementations from the 5G NR Module for ground nodes and channel models.
* '''Repository:''' https://gitlab.com/thiagomiyazaki/nr-ntn-dev
* '''About Me:''' I am a Computer Science graduate student at UNESP/IGCE (Universidade Estadual Paulista - Instituto de Geociências e Ciências Exatas) and since September/2024 I have been part of a research group on Networks and Distributed Systems at IC/UNICAMP, where we have been working on a LEO simulator integrating OpenRAN on ns-3.

== Design Document ==

You can find the Design Document for this project at this link: https://docs.google.com/document/d/1LpZ83rH4adx3xcJoWsKJ30zSKwbJ2m6n-mE855yXeCQ/edit?usp=sharing

= Milestones (not final) =

* Orbital mobility model: week 9
** Models simple circular orbits, could be later extended to model elliptical orbits. This implies constant escape/orbital velocity. Model should support both fake velocity (with no position changes) and real velocity (with position changes, for when handover is fully supported).

* Orbital mobility helper: week 13
** Helper should set up the orbital planes with a given inclination and altitude (radius), for a given number of equally spaced satellites. Orbits in same orbital plane should be equally separated. Orbital plane assignment should start at ascending node (where orbital plane simultaneously intersects the equator plane and the prime meridian plane, e.g. greenwich)

* Example with orbital mobility and 3GPP NTN settings: week 16
** Example should reproduce deployments of LEO constellations such as Starlink and OneWeb.

= Weekly Reports =

== Community Bonding ==
=== Week 1 (May 4-10) ===
* Review on topics about 4G & 5G:
** 4G Architecture, components and Protocol Stack.
** 5G modes (NSA & SA), functions and Protocol Stack.

=== Week 2 (May 11-17) ===
* Requirement gathering with mentors and project discussion

=== Week 3 (May 18-24) ===
* Studied cttc-nr-demo example
* Studied NR Module documentation:
** Getting Started
** Manual: Introduction, Architecture, PHY Layer & Beamforming

=== Week 4 (May 25-31) ===
* Requirement gathering with mentors and project discussion

== GSoC officially starts ==
=== Week 5 (June 1-7) ===
* Study of important concepts for LEO Satellites, such as orbital planes and coordinate systems.
* Study case of existing LEO module: ns-3-leo
** Brief presentation on how the module sets up the initial position for satellite nodes.
** Presentation Link: https://docs.google.com/presentation/d/1EFlk-BCmONiPj0NMILidULXBKr6AY-3hsKmKUbVGHMI/edit?usp=sharing

=== Week 6 (June 8-14) ===
* Initial draft and commit for a LEO Position Allocator and Mobility Model
** Sets up resolution and define a discrete position for satellites within an orbit, setting their initial positions as evenly as possible, given a certain resolution.

=== Week 7 (June 15-21) ===
* Finished porting Mobility from ns-3-leo, including a trace example and utility to plot data for validation.
* The porting also included a new feature to precompute each node position.
* Presentation Link: https://docs.google.com/presentation/d/12uZ00mu8gW1Q0abqZW-l7rihcXTcDhp7l8E1cCy18Ks/edit?usp=sharing

=== Week 8 (June 22-28) ===
* Rebased fork to nr-4.0
* Created initial design document for the project.
* Precomputation feature: replace position queue with a deque to save computational resources.
* WIP: Envision how to share a single orbit deque with positions to multiple satellites in the orbit.
* Presentation Link: https://docs.google.com/presentation/d/19VjevJO2O1_R2cD9pE2XqFrgzoklJuk3GF4Cytt7C_E/edit?usp=sharing

=== Week 9 (June 29-July 5) ===
* A commit that aims to improve time and spatial complexity by using a progress vector to calculate each node offset within its orbit.
* Orbital plot validating the results produced by the commit.
* Overview of papers regarding delay models (doppler shift and propagation) and possible simulation implementations that already implement these delays.
* Presentation Link: https://docs.google.com/presentation/d/1JMrv2pCPvCljDxsHRJIS2D9WUEZXjQRanfaEA2GAYHU/edit?usp=sharing

=== Week 10 (July 6-12) ===
* Profiling development branch implementations with Heaptrack
* Continue researching papers on delay models
* Slides: https://docs.google.com/presentation/d/123lwegaOMN5B1hGzSSAwEKZRxDp2U_fmmNaafy_kayE/edit?usp=sharing

=== Week 11 (July 13-19) ===
* Presentation on reference scenarios for NTN Networks from TR 38.821
* Research on topics regarding antenna orientation
* Code implementation for a ns-3 and Python script to plot the satellite nodes and the antenna orientation.
* Discussion on delay models for the 3GPP NTN Channel.
* Presentation Link: https://docs.google.com/presentation/d/1lAk2F7AQ22G9PN6In5HQ2ytcFoE7MzFQxfnPsVu19RQ/edit?usp=sharing

=== Week 12 (July 20-26) ===
* Code for the Leo Antenna Orientation Example and Plot correction
* Initial code (draft) for the example
* Brief discussion on Coordinate Systems: ECEF, Geodetic/Geographic, Topocentric (ENU, AER).
* Presentation Link: https://docs.google.com/presentation/d/1rk-AQT76sv6T6AG5pgRjiSKLbLTO4-JUCVH1jVWR7Pk/edit?slide=id.p#slide=id.p

=== Week 13 (July 27-August 2) ===
* Expected: code commit for the NTN example

=== Week 14 (August 3-9) ===
* Expected: tests and validation for the NTN example

=== Week 15 (August 10-16) ===
* Project Delivery and Final Results discussion

=== Week 16 (August 17-23) ===

=== Week 17 (August 24-30) ===
Standard GSoC deadline

=== Week 18 (August 31- September 6) ===

GSOC2025Ntn

2025-06-13T09:34:12Z

Gabriel:

GSOC2025Ntn

2025-06-13T09:33:40Z

Gabriel:

GSOC2025Ntn

2025-06-13T07:47:33Z

Gabriel: Add weeks according to initial plan and current milestone planning.

Summer Projects

2024-10-06T13:49:24Z

Gabriel: /* Google Summer of Code 2024 */

{{TOC}}

The project coordinates a few summer coding programs in which student developers are paired with mentors to produce code over the summer.

= Google Summer of Code 2024 =

ns-3 is mentoring three projects for 2024:

* '''Joao Albuquerque''', [[GSOC2024Channels5G | 5G NR Module Benchmark and Analysis for Distinct Channel Models]], mentored by Biljana Bojovic, Amir Ashtari, and Gabriel Ferreira: '''''[[GSOC2024Channels5GFinalReport | Final report]]'''''
* '''Kavya Bhat''', [[GSOC2024DHCPv6 | DHCPv6]], mentored by Tommaso Pecorella, Alberto Gallegos Ramonet, and Manoj Kumar Rana: '''''[[GSOC2024DHCPv6FinalReport | Final report]]'''''
* '''Hyerin Kim''', [[GSOC2024RLUsability5G | Enhancement of RL Approach Accessibility in NR]], mentored by Katerina Koutlia, Amir Ashtari, Biljana Bojovic, and Gabriel Ferreira

* [[GSOC2024Projects | Project Ideas Page]]
* [[GSOC2024ContributorGuide | ns-3's GSoC Contributor Guide]]

= Google Summer of Code 2023 =

The organizational admins were Tommaso Pecorella, Mohit Tahiliani, and Tom Henderson.

We had three successful student projects for 2023; you can read their final reports below:

* '''Giovanni Grieco''', [[GSOC20235GUsability | IUNS-3 5G NR: Improving the Usability of ns-3's 5G NR Module]], mentored by Tom Henderson, Katerina Koutlia, and Biljana Bojovic: '''''[[GSOC20235GUsabilityFinalReport | Final report]]'''''
* '''Raghuram Kannan''', [[GSOC2023NetAnim | Dynamic device registration for NetAnim simulation animations]], mentored by Tommaso Pecorella and Manoj Kumar Rana: '''''[[GSOC2023NetAnimFinalReport | Final report]]'''''
* '''Muyuan Shen''', [[GSOC2023ns3-ai | ns3-ai enhancements]], mentored by Collin Brady and Hao Yin: '''''[[GSOC2023ns3-aiFinalReport | Final report]]'''''

We reviewed seven proposals, which were evaluated by a committee that includes most of the mentors listed on the Project Ideas page. For future reference, below is our ideas page and contributor's guide.

* [[GSOC2023Projects | Project Ideas Page]]
* [[GSOC2023ContributorGuide | ns-3's GSoC Contributor Guide]]

= Google Summer of Code 2022 =

The organizational admins were Tommaso Pecorella, Mohit Tahiliani, and Tom Henderson.

Two contributors completed projects with ns-3 in the 2022 Google Summer of Code.

* '''Matteo Pagin''', [[GSOC2022Channel | A simplified channel and beamforming model for ns-3]], mentored by Sandra Lagen, Biljana Bojovic, and Michele Polese '''''[https://pagmatt.github.io/blog/2022/gsoc2022 Final Report]'''''
* '''Zhiheng Dong''', [[GSOC2022PerfectArp | Perfect ARP and NDP]], mentored by Tommaso Pecorella, Ameya Deshpande,and Manoj Kumar Rana '''''[[GSOC2022NeighborCacheFinalReport | Final Report]]'''''

One additional project was started but did not progress past the midterm evaluation:

* '''Akash Mondal''', [[GSOC2022TCPMaximumSegmentSize | TCP maximum segment size (MSS) improvements]], mentored by Mohit Tahiliani, Bhaskar Kataria, and Vivek Jain

We received seven proposals, which were evaluated by a committee that includes most of the mentors listed on the Project Ideas page. For future reference, below is our ideas page and contributor's guide.

* [[GSOC2022Projects | Project Ideas Page]]
* [[GSOC2022ContributorGuide | ns-3's GSoC Contributor Guide]]

= ns-3 Summer of Code 2022 =

ns-3 Summer of Code (NSoC) is a program that runs in parallel to Google Summer of Code. Unlike GSoC, it is not funded, but we aim to operate it similarly to GSoC.

* '''Chandrakant Jena,''' ''Ping and Ping6 Enhancements for ns-3:'' '''''[[NSOC2022Ping | project wiki page ]]''''' mentored by Tommaso Pecorella and Tom Henderson

The project by Chandrakant was completed successfully in December 2022, with six commits made to ns-3-dev starting with [https://gitlab.com/nsnam/ns-3-dev/-/commit/da107e04eeb0c12631eadda6a30ad1a33b7f0931 commit da107e04]. The project added a '''[https://www.nsnam.org/docs/doxygen/d6/dbe/classns3_1_1_ping.html new Ping application]''', helper class, example program, unit test, and [https://www.nsnam.org/docs/models/html/internet-apps.html#ping documentation].

= Google Summer of Code 2021 =

Three students successfully completed projects in [https://summerofcode.withgoogle.com/organizations/4672908493848576/ Google Summer of Code 2021].

* '''Parth Pratim Chatterjee,''' ''Direct Code Execution Modernization:'' '''''[[GSOC2021DCE | project wiki page]]''''' '''--''' '''''[https://ns-3-dce-linux-upgrade.github.io/ Final report]'''''
* '''Ameya Deshpande,''' ''IPv6 Nix-Vector Routing:'' '''''[[GSOC2021NixVector | project wiki page]]''''' '''--''' '''''[https://www.nsnam.org/wiki/GSOC2021NixVectorFinalReport Final report]'''''
* '''Akshit Patel,''' ''Add logging support to Simulation Execution Manager (SEM):'' '''''[[GSOC2021SEM | project wiki page]]''''' '''--''' '''''[https://akshitpatel01.github.io/GSoC-2021-Report/ Final report]'''''

For reference, below were the 2021 project ideas and the 2021 student guide:

* [[GSOC2021StudentGuide | Student Guide]]
* [[GSOC2021Projects | Project Ideas Page]]

= ns-3 Summer of Code 2021 =

ns-3 Summer of Code (NSoC) is a program that runs in parallel to Google Summer of Code. Unlike GSoC, it is not funded, but we aim to operate it similarly to GSoC. The commitments are similar; students and mentors are expected to define and work towards a mergeable project goal by the end of the summer. The program is offered to 'honorable mention' GSoC proposals (i.e., proposals that we would have selected had we received more student slots from Google) and for other reasons such as a contributor's ineligibility for GSoC.

* '''Nitya Chandra,''' ''Enable IPv6 support for ad-hoc routing protocols in ns-3:'' '''''[[NSOC2021Ipv6 | project wiki page ]]''''' '''Note: project did not complete'''

= Google Summer of Code 2020 =

Four students successfully completed [https://summerofcode.withgoogle.com/ Google Summer of Code 2020] projects:

* '''Shivamani Patil,''' ''App Store Improvements:'' '''''[https://shivamanipatil.github.io/gsoc-2020-report/ final report], [[GSOC2020AppStore | project wiki page]]'''''
* '''Ananthakrishan S,''' ''NetDevice up/down consistency and event chain:'' '''''[https://ananthu-dev.github.io/net-device-consistency-gsoc-2020/ final report], [[GSOC2020NetDevice | project wiki page]]'''''
* '''Bhaskar Kataria,''' ''SCE AQMs and TCP along with CNQ-CodelAF and LFQ'' '''''[https://bhaskar792.github.io/GSoC-2020-Report/ final report], [[GSOC2020AQM | project wiki page]]'''''
* '''Deepak K,''' ''TCP Prague model for ns-3'', '''''[https://deepakkavoor.github.io/gsoc-2020-prague/ final report], [[GSOC2020Prague | project wiki page]]'''''

For reference, below were the 2020 project ideas and the 2020 student guide:

* [[GSOC2020StudentGuide | Student Guide]]
* [[GSOC2020Projects | Project Ideas Page]]

= ns-3 Summer of Code 2020 =

These projects are unfunded but are mentored in a manner similar to GSoC, at a lesser pace than the 12-week GSoC program.

* Muhammad Iqbal Rochman, [[NSOC2020WifiPHY | Wi-Fi PHY Restructure]] '''Note:''' This project successfully completed.
* Harsha Sharma, [[NSOC2020L4SEvaluation | L4S evaluation framework]] '''Note:''' This project continued through fall 2020 but did not yet merge.
* Rahul Bothra, [[NSOC2020Routing | Routing for community wireless networks]] '''Note:''' Project discontinued in August 2020.

= Google Summer of Code 2019 =

ns-3 participated in Google Summer of Code 2019 with four student projects:

* Apoorva Bhargava, [[GSOC2019TCPTestingAndAlignment | Testing and Alignment of ns-3 TCP with Linux TCP]]
* Mishal Shah, [[GSOC2019AppStore | Improving the ns-3 AppStore and linking with bake]]
* Tommaso Zugno, [[GSOC2019ThreeGPPChannel | Integration of the 3GPP TR 38.901 channel model in the ns-3 spectrum module]]
* Liangcheng Yu, [[GSOC2019DCN | Framework of Studying Flow Completion Time Minimization for Data Center Networks in ns-3]]

Below are project ideas and the 2019 student guide:

* [[GSOC2019StudentGuide | ns-3 GSoC student guide]]
* [[GSOC2019Projects | Project Ideas Page]]

= European Space Agency Summer of Code in Space (SOCIS) 2019 =

ns-3 ultimately was not selected for funding for SOCIS 2019. Below is an archive of our student guide, for future reference.

* [[SOCIS2019 | ns-3 SOCIS student guide]]

= Google Summer of Code 2018 =

ns-3 participated in the 2018 edition of Google Summer of Code, with five students:

* WenYing Dai, [[GSOC2018AccECN_ECN++ | Implementation of AccECN and ECN++ in ns-3]]
* Muhammad Iqbal CR, [[GSOC2018Coexistence | Merging and Improvement of LTE and Wi-Fi Coexistence Module]]
* Sourabh Jain, [[GSoC2018_DCE_Upgrade | Direct Code Execution upgrade]]
* Davide Magrin, [[GSoC2018:_A_Simulation_Execution_Manager_for_ns-3 | A simulation execution manager for ns-3]]
* Jude Niroshan, [[GSoC2018:Trust-based_routing_protocols_framework | Trust-based routing protocols framework]]

* [[GSOC2018Projects | Project Ideas Page]]
* [[GSOC2018StudentGuide | Student Application Guide]]

= European Space Agency Summer of Code in Space (SOCIS) 2017 =

ns-3 has been accepted to the 2017 ESA Summer of Code in Space, with student Pasquale Imputato (mentored by Tommaso Pecorella). The project successfully completed in October 2017 (details in the below wiki project page).

* [[SOCIS2017 | project page]]
* [https://codereview.appspot.com/330220043/ Final code review]

The original project ideas page is posted below.

* [[SOCIS2017Projects#Project_Ideas | Project Ideas page]]

= Google Summer of Code 2017 =

ns-3 was fortunate to mentor five outstanding students for the 2017 edition of [https://developers.google.com/open-source/gsoc/ Google Summer of Code].

* [[GSOC2017AcceptedProjects | Accepted Projects]]
== Final reports ==
* [http://mailman.isi.edu/pipermail/ns-developers/2017-August/013916.html ns-3 App Store] by Abhijith Anilkumar
* [https://www.nsnam.org/wiki/GSOC2017Lte#Project_summary Enabling LTE CA handover to secondary cell] by Alexander Krotov
* [http://mailman.isi.edu/pipermail/ns-developers/2017-September/013929.html TCP Prague] by Shravya Ks
* [http://mailman.isi.edu/pipermail/ns-developers/2017-September/013918.html LTE and IPv6 support] by Manoj Kumar Rana
* [http://mailman.isi.edu/pipermail/ns-developers/2017-September/013921.html TBF and HHF] by Surya Seetharaman

== Phase 2 reports ==
* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014038.html BCube and FatTree topology helpers (component of TCP Prague project)]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-August/014054.html Implementation of TBF and HHF]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014047.html Enabling LTE CA handover to secondary cell, Phase 2]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014042.html ns-3 App Store]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-July/014049.html Mobile IPv6 implementation with LTE support (report)]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-August/014058.html Mobile IPv6 implementation with LTE support (review request)]
== Phase 1 reports ==
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013980.html Data Center TCP (component of TCP Prague project)]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013982.html Implementation of TBF and HHF traffic control]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013983.html Enabling LTE CA handover to secondary cell, Phase 1]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013985.html ns-3 App Store]
* [http://mailman.isi.edu/pipermail/ns-developers/2017-June/013987.html Mobile IPv6 implementation with LTE support]
== Background ==
Below is some information that was used during the application phase.

* [[GSOC2017Projects | Project Ideas Page]]
* [[GSOC2017StudentGuide | Student Application Guide]]

= European Space Agency Summer of Code in Space (SOCIS) 2016 =

ns-3 had one student (Michael Di Perna) successfully complete the 2016 [http://sophia.estec.esa.int/socis/ ESA Summer of Code in Space].

* [[SOCIS2016 | Project page]] for Optical Satellite Systems project
* [[SOCIS2016Projects#Project_Ideas | Project Ideas page]]

= Mentored summer projects 2016 =

ns-3 maintainers will mentor additional summer projects (that students will work on using their own sources of funding) on a best-effort basis. Students interested in this option should review the GSoC or SOCIS ideas page, or propose their own.

* See [[MentoredProjects2016]]

= Google Summer of Code 2016 =

ns-3 was not selected for the 2016 [https://developers.google.com/open-source/gsoc/ Google Summer of Code]. We mentored two summer projects outside of GSoC. Below were our materials prepared for our GSoC organizational application.
* [[GSOC2016Projects | Project ideas page]]
* [[GSOCStudentGuide | Student guide]]

= Google Summer of Code 2015 =

ns-3 was selected to participate in the 2015 [http://www.google-melange.com/gsoc/homepage/google/gsoc2015 Google Summer of Code]. More information can be found on our Project Ideas page and our Student Guide.

* [[GSOC2015AcceptedProjects | Accepted projects]]
* [[GSOC2015Projects | Project ideas page]]
* [[GSOC2015StudentGuide | Student guide]]

This year's students were announced on April 27, and all four successfully completed the program:

* Melchiorre Danilo Abrignani, [[GSOC2015LTECA | Carrier Aggregation support for the LTE module]]
* Matthieu Coudron, [[GSOC2015MpTcpImplementation | Implementing multipath TCP (MPTCP) in ns3]]
* Natale Patriciello, [[GSOC2015TCPTest | TCP layer refactoring with automated test on RFC compliance and validation]]
* Vishwesh Rege, [[GSOC2015LrWpanMac | 802.15.4 realistic MAC and Energy Model]]

= European Space Agency Summer of Code in Space (SOCIS) 2015 =

ns-3 has been accepted to the 2015 [http://sophia.estec.esa.int/socis2015/ ESA Summer of Code in Space]. The ns-3 project had one student in SOCIS in each of 2013, 2014 and 2015. However, the satellite channel models project for 2015 [[SOCIS2015 | Satellite channel models]] did not successfully complete.

* [[SOCIS2015Projects | Project ideas page]] (for reference)

= Mentored summer projects =

ns-3 maintainers will mentor additional summer projects (that students will work on using their own sources of funding) on a best-effort basis. Students interested in this option should review the GSoC or SOCIS ideas page, or propose their own.

We have one such mentored project in 2015:

* Saswat Mishra, [[NeighborDiscoveryProject | Neighbor Discovery enhancements]]

= Past summer projects =

* [[GSOC2014AcceptedProjects | GSoC 2014 Accepted Projects]]
* [[SOCIS2014TCP | SOCIS 2014 Accepted Project]]
* [[MentoredProjects2014 | 2014 Mentored Projects]]
* [[SOCIS2013BundleProtocolProject | SOCIS 2013 Accepted Project]]
* [[GSOC2013AcceptedProjects | GSoC 2013 Accepted Projects]]
* [[GSOC2012AcceptedProjects |GSoC 2012 Accepted Projects]]
* [[NSOC2011AcceptedProjects |NSoC 2011 Accepted Projects]]
* [[GSOC2010AcceptedProjects |GSoC 2010 Accepted Projects]]
* [[GSOC2009AcceptedProjects |GSoC 2009 Accepted Projects]]
* [https://developers.google.com/open-source/soc/2008/?csw=1#ns3 GSoC 2008 Accepted Projects]

Ns-3.42 errata

2024-06-15T11:42:27Z

Gabriel: /* Minimum supported Apple Clang compiler should be 13.1.6 instead of 12 */

On May 29, 2024, ns-3.42 was published. This page lists some issues that have been fixed in the mainline since that time. If considered impactful enough, the maintainers may make an update to this release to cover some or all of these issues.

== examples/routing/manet-routing-compare.cc produces no output ==

The example program 'manet-routing-compare.cc' runs but produces no output. This is due to a bug preventing use of DSSS rates 5.5 and 11 Mbps. The workaround is to avoid these rates:

<pre>
diff --git a/examples/routing/manet-routing-compare.cc b/examples/routing/manet-routing-compare.cc
index a105ab0d2..e1dee99e0 100644
--- a/examples/routing/manet-routing-compare.cc
+++ b/examples/routing/manet-routing-compare.cc
@@ -247,7 +247,7 @@ RoutingExperiment::Run()

double TotalTime = 200.0;
std::string rate("2048bps");
- std::string phyMode("DsssRate11Mbps");
+ std::string phyMode("DsssRate2Mbps");
std::string tr_name("manet-routing-compare");
int nodeSpeed = 20; // in m/s
int nodePause = 0; // in s
</pre>

Another solution is to avoid use of 802.11b entirely and use another standard. There is an [https://gitlab.com/nsnam/ns-3-dev/-/issues/1095 open issue] to fix this in the mainline.

== Minimum supported Apple Clang compiler should be 13.1.6 instead of 11 ==

In 3.42 we replaced some code with the std::bind_front function. This causes the ns-3 build to fail under Apple Clang 11, as reported in [https://gitlab.com/nsnam/ns-3-dev/-/issues/1099 issue].

According to the Cppreference support page, [https://en.cppreference.com/w/cpp/compiler_support/20 Apple Clang 13.1.6 (shipped with Xcode 13.3)] is supported. We recommend updating Xcode.

Ns-3.42 errata

2024-06-15T11:41:39Z

Gabriel:

On May 29, 2024, ns-3.42 was published. This page lists some issues that have been fixed in the mainline since that time. If considered impactful enough, the maintainers may make an update to this release to cover some or all of these issues.

== examples/routing/manet-routing-compare.cc produces no output ==

The example program 'manet-routing-compare.cc' runs but produces no output. This is due to a bug preventing use of DSSS rates 5.5 and 11 Mbps. The workaround is to avoid these rates:

<pre>
diff --git a/examples/routing/manet-routing-compare.cc b/examples/routing/manet-routing-compare.cc
index a105ab0d2..e1dee99e0 100644
--- a/examples/routing/manet-routing-compare.cc
+++ b/examples/routing/manet-routing-compare.cc
@@ -247,7 +247,7 @@ RoutingExperiment::Run()

double TotalTime = 200.0;
std::string rate("2048bps");
- std::string phyMode("DsssRate11Mbps");
+ std::string phyMode("DsssRate2Mbps");
std::string tr_name("manet-routing-compare");
int nodeSpeed = 20; // in m/s
int nodePause = 0; // in s
</pre>

Another solution is to avoid use of 802.11b entirely and use another standard. There is an [https://gitlab.com/nsnam/ns-3-dev/-/issues/1095 open issue] to fix this in the mainline.

== Minimum supported Apple Clang compiler should be 13.1.6 instead of 12 ==

In 3.42 we replaced some code with the std::bind_front function. This causes the ns-3 build to fail under Apple Clang 12, as reported in [https://gitlab.com/nsnam/ns-3-dev/-/issues/1099 issue].

According to the Cppreference support page, [https://en.cppreference.com/w/cpp/compiler_support/20 Apple Clang 13.1.6 (shipped with Xcode 13.3)] is supported. We recommend updating Xcode.

MaintainersJune2024

2024-06-13T19:01:19Z

Gabriel: /* nr module plan */

{{TOC}}

This meeting is open to anyone interested.

== Date/Time/Venue ==

Thurs. June 6, 2024 10:00 AM Barcelona Time (08:00 UTC)

== Agenda ==

'''10:00-12:30 session:'''
* ns-3 NR module coordination (Tom Henderson and CTTC)
** possible use of nr namespace and removal of 'Nr' prefix on most symbols
** possible removal of service access point API objects
** new helpers for sidelink (and nr), and configuration management
** plan for migration of V2X out of ns-3-dev/lte and for merging v2x with main branch

'''14:00-15:30 session:'''
* How should ns-allinone-3.43 be organized? Docker? NetAnim? Bake? (Tom Henderson)
* Start/stop times for ns-3 logging [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/636 !636]

'''16:00-17:30 session:'''

* Project governance (Tom Henderson)
* Possible uses for remaining consortium funding (Tom Henderson)
** website work
** hosting contract
* strongly-typed units [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/1887 Merge Request !1887]

Lingering issues that we could discuss in one of the meeting sessions

* Next steps with C++ namespaces: [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/1906 Merge Request !1906]
* Random variable assignments to streams

== Minutes ==

Attendees: Tom Henderson, Sandra Lagen, Biljana Bojovic, Katerina Koutlia, Amir Ansari, Hamid, Erfan Mozaffari, Pasquale Imputato, Stefano Avallone, Felipe Gomez Cuba, Gabriel Ferreira, Vladimir Zelenkovski, Drew Spitzer, George Frangulea, Eduardo Almeida (remote), Peter Barnes (remote), Alberto Gallegos (remote).

=== next steps with namespaces ===

Tom relayed a concern raised by Peter that our namespaces work is incomplete because we are still duplicating module/namespace names in the symbol names, and the helpers are not include. He prefers to not see constructs like ``wifi::WifiHelper`` in the long run; it can become wifi::Helper and transition can be mitigated by using statements. Tom also supported this goal based on his recent experience with the nr module.

Tom identified an issue that string-based TypeIds have not yet been updated (e.g. ns3::BasicEnergySource should become ns3::energy::BasicEnergySource) and that transition is not supported by using statements.

Regarding the next steps for a heavily used module (wifi), Stefano indicated that this was not an urgent priority. Eduardo suggested that we wait a release cycle (until past ns-3.43) to evalute how lr-wpan and energy module transitions have gone, and that we merge any future namespace changes early in a release cycle.

=== Change of Lte EpsBearer type from enum to class enum ===

We discussed this at some length and LTE maintainers decided that in this specific case, because of the impact on LTE examples for this widely used enum, to leave it as a plain enum. If the issue is reopened in the future for some reason, the enum class should be moved outside of the class EpsBearer.

=== random variable stream assignment ===

The problem of automatic random variable stream assignments becoming perturbed by scenario changes continues to lead to unexpected results that lead to debugging efforts. The use of AssignStreams at the helper level is not foolproof, and further, the common practice of chaining the output of AssignStreams to the next invocation of AssignStreams is contributing to the problem.

Tom mentioned that two improvements that would solve most issues would be to be able to easily dump all of the stream assignments to a debug output file to search for missing assignments, and to avoid chaining AssignStreams() calls together.

Biljana asked about whether there could be some automatic stream assignments that localized the effect of perturbed changes, and suggested a possible approach that involved creating a pool of streams that could be assigned to each possible object type, and serially assign streams from those pools in an automatic way, thereby removing the burden of stream assignment from the simulation author. Tom replied that he did not think it was possible to do this in a completely failsafe way, unless simulation objects had logical names that persisted across different simulation instances, but things like Config paths can be perturbed across simulation runs. The meeting concluded that more work was needed on this point but there was no obvious answer yet.

=== nr module plan ===

Tom shared his future refactoring plans for nr module and v2x branch integration. First step will be to copy/rename LTE RLC and above, and also the EPC, to make nr module completely independent of lte module. Tom will wrap LTE moved code into an nr nested namespace, allowing EPC classes to be left with the same name (e.g., EpcPgw and nr::EpcPgw), and the "Lte" prefix will be dropped (e.g., LteUeRrc will become nr::UeRrc). This could pave the way for inclusion of the whole module into the nr nested namespace.

The next step will be to merge v2x-lte-dev and nr-v2x-dev into this new nr module. Separately, Tom plans to develop some new link-to-system mapping for error models for sidelink mode 2 fading channels, and to check/validate the current downlink error model.

Tom advocated for the removal of the Service Access Point (SAP) interface classes throughout the nr RAN layers, because they hinder cross-layer modifications to classes, and are dated (based on 4G Femto Forum specs) and not apparently adhered to in real implementations. Katerina expressed reservation about this step, stating that she thought it offered more clarity about the architectural separation of layers. Tom mentioned that we can use C++ inheritance (base class enforces the API) to accomplish similar clarity, but making it easier for users to modify the interfaces in their own implementation to do research, and also mentioned that our C++ attribute system requires Ptr access to all objects, and these cannot cross such boundaries (leading to unusal paths such as accessing the Mac scheduler through the BandwithPartManager instead of through the Mac). There was no agreement at this meeting to remove these classes, so they will remain for the time being.

Another problem to be addressed is the lengthy and verbose configuration of nr examples, especially in the V2X code. The meeting discussed the potential to do more with managing configuration via outside configuration files, such as the ConfigStore (text or XML, possibly JSON, file formats). However, scenarios can't be fully exported to configuration files because ns-3 lacks a high-level language like OMNeT++ NED to describe topology. Gabriel suggested the use of standardized YANG/NETCONF instead of custom solutions such as NED. Tom expressed the view that some people would prefer to run simulation campaigns by managing default and command-line values in external files, and that we could perhaps reduce the size of some of our example programs if we could refer to external files that illustrated key default values that could be changed. If the ConfigStore were extended to manage CommandLine arguments, then the system could be more extensible.

=== How should ns-allinone-3.43 be organized? ===

Tom mentioned that the current bundling of netanim, bake, and ns-3 is not really useful to many people-- most people surveyed are just git cloning from ns-3-dev and checking out the release that they want, or git cloning some fork of ns-3. However, he mentioned that he would prefer instead to start releasing bundles of tested contributed modules and declaring that as 'allinone' (e.g., waiting a month until the ns-3.xx release is made, and then publishing ns-allinone-3.xx that includes copies of all of the aligned contrib modules that can be drawn from the App Store). Tom plans to work on this in the current release cycle.

=== Start/stop times for ns-3 logging ===

The meeting agreed that this would be a useful feature, to limit the scope of log output to time ranges (see !636). Pasquale mentioned that limiting the scope of the context would also be useful. Katerina volunteered to try to push !636 along.

=== Strongly-typed units ===

Peter expressed his opinion that the project should not adopt a custom units library but instead adopt an externally maintained one. Stefano said that wifi maintainers were likely to adopt a custom solution (possibly Jiwoong Lee's solution) in the meantime if the project could not yet come to consensus.

Peter advocated mp-units because a number of contributors have banded together to try to get this solution into a future C++ standard library; in the meantime, it is distributed as a header-only library under MIT license. The options to actually include it, were we to adopt it, would be to include as a vendored-in header, to use CMake integration for git submodule or conan/vcp integration.

Stefano asked Peter what would happen to existing units support, and whether these strongly typed units could be used in the Attribute system. Peter replied that the Boost::length in the core would go away, DataRate would probably go away, but Time class may not be replaced, because we have some specific requirements on this class (integer representation, default nanosecond precision) so likely there would need to be some converter back and forth between mp-units time and ns-3 Time. Tom wondered whether this will expose us to more float-to-int time conversion portability issues. As for Attributes, Peter said that mp-units has some string-based representations that could be leveraged, but Value wrappers for the non-string types need to be explored. Tom also pointed out that non-linear conversions (dB to W) are not supported, and Peter acknowledged that mp-units would need to be extended in this regard.

Action items were that Peter urged everyone to read the [https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p3045r0.html mp-units paper], and Peter will explore some of the open questions above, and we will discuss again at a future maintainers meeting. Eduardo said that the support could be gradually rolled out; we could start to use it in a subset of our modules once enabled.

=== Governance ===

Tom shared that he was working on publishing a governance model that is adapted from several similar open source projects, and has shared an initial draft with a few longtime maintainers. Once he processes all of the comments, it will be posted for broader review. He shared that the guiding principles are:

* contributors to open source want to understand if the core team and the governance is aligned with their interests, and how conflict resolution or behavior issues may be handled
* the primary stakeholders are the maintainers working on the software day-to-day, and they should have the strongest voices in guiding the project, but there also needs to be room for people less connected to software maintenance to serve in prominent roles, such as community building, onboarding, outreach, etc.
* some maintainers do not want to get involved in things other than the code that they are managing, while others may want to maintain code and be active in other aspects
* as a result, a governance structure defining two overlapping groups of contributors (maintainers, steering council) is being developed.
* the governance should be as lightweight as possible and scale to smaller or larger groups of contributors than we presently have

== Recent maintainers meetings ==

* [[MaintainersApril2024]]
* [[MaintainersJan2024]]
* [[MaintainersOct2023]]
* [[MaintainersJune2023]]
* [[MaintainersApr2023]]
* [[MaintainersJan2023]]

HOWTO use gdb to debug program errors

2023-10-27T17:40:55Z

Gabriel:

{{TOC}}

[http://www.gnu.org/software/gdb/ The GNU Debugger (gdb)] can be used with ns-3 to debug program errors. There are several tutorials online (search for 'gdb tutorial' in a search engine) that explain how to use gdb in general.

One example of such tutorials is part of the [https://access.redhat.com/documentation/en-us/red_hat_developer_toolset/9/html/user_guide/chap-gdb Red Hat user guide].

This HOWTO is related to [[HOWTO understand and find cause of terminated with signal errors | another HOWTO]] that explains how to use the [https://www.sourceware.org/insight/ insight tool] (a graphical front-end for gdb) to debug segmentation faults.

This HOWTO is also related to [[HOWTO use Valgrind to debug memory problems | another HOWTO]] that describes how to invoke the [http://www.valgrind.org valgrind tool] to find memory leaks.

== running gdb directly ==

gdb can be invoked on a program executable in the normal way (''gdb <program-name>''), and to do this with ns-3, it is easiest to use the ns3 shell (to set the library paths correctly). We demonstrate with an example of the ''third'' tutorial example.

./ns3 shell
cd build/examples/tutorial
gdb ns3-dev-third-debug
Reading symbols from ns3-dev-third-debug...done.
(gdb)

At this point, one can set breakpoints in the ns-3 libraries, or run the program. We can run it with the ''--help'' argument to print out the program usage:

(gdb) r --help

Or we can deliberately cause a program error by running with an illegal argument

(gdb) r --nWifi=0
Program received signal SIGSEGV, Segmentation fault.
0x0000000000413ac9 in ns3::PeekPointer<ns3::Node> (p=...) at ./ns3/ptr.h:282
282 return p.m_ptr;
(gdb)

To run a test-suite through gdb, use the ''test-runner'' program, such as:

./ns3 shell
cd build/utils/
gdb ns3-dev-test-runner-debug
(gdb) r --suite=csma-system
(gdb) quit

== running gdb with ns3 script ==

ns3 supports a ''--gdb'' argument that allows users to launch gdb and run the programs from there.

./ns3 run --gdb <program-name>

An example using the ''third'' tutorial example, running it first to ask that the help message be printed out, and then running it with an illegal argument:

./ns3 run --gdb third
(gdb) r --help
(gdb) run --nWifi=0
...
Program received signal SIGSEGV, Segmentation fault.
ns3::NodeContainer::Get (this=this@entry=0x7fffffffd980, i=4294967295)
at ../src/network/helper/node-container.cc:95
95 return m_nodes[i];
(gdb)

The program execution is now stopped at the point of the segmentation fault. For a segmentation fault, this often means that the program is trying to access an object from a pointer, but the pointer is not valid. You can check here on the value of 'i' and 'm_nodes[i]' by using the gdb print (abbreviated as 'p'):

(gdb) p i
$1 = 4294967295

You can see how you got to this point by using the 'backtrace' (abbreviated as 'bt'), as follows:

(gdb) bt
#0 ns3::NodeContainer::Get(unsigned int) const
(this=this@entry=0x7fffffffd980, i=4294967295)
at ../src/network/helper/node-container.cc:95
#1 0x000055555555e13e in main(int, char**)
(argc=<optimized out>, argv=<optimized out>)
at ../examples/tutorial/third.cc:165

You can step back up through the call stack to inspect the program state, using the 'up' command:

(gdb) up
#1 0x000055555555e13e in main (argc=<optimized out>, argv=<optimized out>)
at ../examples/tutorial/third.cc:165
165 ApplicationContainer clientApps =

This tells me that line 165 of third.cc was the trigger. Let's look at that code:

ApplicationContainer clientApps =
echoClient.Install (wifiStaNodes.Get (nWifi - 1));

Now it should be obvious why the program segfaulted, and why the value of i above was invalid.

Notice that some of the values above say 'optimized out'. This is because I was debugging on a program that was compiled with some optimizations. To really see in detail what is going on, build ns-3 in 'debug' mode before running gdb.

To debug an individual test suite, use the ''test-runner'' program, such as the following example of the 'csma-system' test suite:

./ns3 run --gdb test-runner
(gdb) run --suite=csma-system

== running gdb with ns3, redirecting all output to a file ==

Sometimes a program will generate a lot of output to stdout and stderr, which may get in the way of interactively using the gdb prompt. It is possible to redirect program output to a file, while interacting with the gdb prompt. Here is a trivial example.

./ns3 run --gdb third
(gdb) run --help > output.txt 2>&1

An example of how to run an individual test suite this way, launching gdb from the command line:

./ns3 run test-runner --command-template="gdb -ex 'run --suite=csma-system > csma-output.txt 2>&1' --args %s"

== saving breakpoints across sessions ==

As of gdb 7.2, breakpoints can be saved to a file and reloaded for a separate session.

For example:

(gdb) info break
Num Type Disp Enb Address What
1 breakpoint keep y <PENDING> random-variable-stream.cc:175
2 breakpoint keep y <PENDING> random-variable-stream.cc:186

to save them to a file called 'breaks':

(gdb) save breakpoints breaks

Later, one can retrieve them as follows.

(gdb) source breaks

In ns-3 with shared libraries, one may get this error:

(gdb) source breaks
No source file named random-variable-stream.cc.
Make breakpoint pending on future shared library load? (y or [n]) [answered N; input not from terminal]
No source file named random-variable-stream.cc.
Make breakpoint pending on future shared library load? (y or [n]) [answered N; input not from terminal]

to work around this, use the command 'set breakpoints pending on' before sourcing the file:

(gdb) set breakpoint pending on
(gdb) source breaks
No source file named random-variable-stream.cc.
Breakpoint 1 (random-variable-stream.cc:175) pending.
No source file named random-variable-stream.cc.
Breakpoint 2 (random-variable-stream.cc:186) pending.
(gdb) info break
Num Type Disp Enb Address What
1 breakpoint keep y <PENDING> random-variable-stream.cc:175
2 breakpoint keep y <PENDING> random-variable-stream.cc:186

HOWTO use gdb to debug program errors

2023-10-27T17:40:40Z

Gabriel:

{{TOC}}

[http://www.gnu.org/software/gdb/ The GNU Debugger (gdb)] can be used with ns-3 to debug program errors. There are several tutorials online (search for 'gdb tutorial' in a search engine) that explain how to use gdb in general.

One example of such tutorials is part of the [https://access.redhat.com/documentation/en-us/red_hat_developer_toolset/9/html/user_guide/chap-gdb RedHat user guide].

This HOWTO is related to [[HOWTO understand and find cause of terminated with signal errors | another HOWTO]] that explains how to use the [https://www.sourceware.org/insight/ insight tool] (a graphical front-end for gdb) to debug segmentation faults.

This HOWTO is also related to [[HOWTO use Valgrind to debug memory problems | another HOWTO]] that describes how to invoke the [http://www.valgrind.org valgrind tool] to find memory leaks.

== running gdb directly ==

gdb can be invoked on a program executable in the normal way (''gdb <program-name>''), and to do this with ns-3, it is easiest to use the ns3 shell (to set the library paths correctly). We demonstrate with an example of the ''third'' tutorial example.

./ns3 shell
cd build/examples/tutorial
gdb ns3-dev-third-debug
Reading symbols from ns3-dev-third-debug...done.
(gdb)

At this point, one can set breakpoints in the ns-3 libraries, or run the program. We can run it with the ''--help'' argument to print out the program usage:

(gdb) r --help

Or we can deliberately cause a program error by running with an illegal argument

(gdb) r --nWifi=0
Program received signal SIGSEGV, Segmentation fault.
0x0000000000413ac9 in ns3::PeekPointer<ns3::Node> (p=...) at ./ns3/ptr.h:282
282 return p.m_ptr;
(gdb)

To run a test-suite through gdb, use the ''test-runner'' program, such as:

./ns3 shell
cd build/utils/
gdb ns3-dev-test-runner-debug
(gdb) r --suite=csma-system
(gdb) quit

== running gdb with ns3 script ==

ns3 supports a ''--gdb'' argument that allows users to launch gdb and run the programs from there.

./ns3 run --gdb <program-name>

An example using the ''third'' tutorial example, running it first to ask that the help message be printed out, and then running it with an illegal argument:

./ns3 run --gdb third
(gdb) r --help
(gdb) run --nWifi=0
...
Program received signal SIGSEGV, Segmentation fault.
ns3::NodeContainer::Get (this=this@entry=0x7fffffffd980, i=4294967295)
at ../src/network/helper/node-container.cc:95
95 return m_nodes[i];
(gdb)

The program execution is now stopped at the point of the segmentation fault. For a segmentation fault, this often means that the program is trying to access an object from a pointer, but the pointer is not valid. You can check here on the value of 'i' and 'm_nodes[i]' by using the gdb print (abbreviated as 'p'):

(gdb) p i
$1 = 4294967295

You can see how you got to this point by using the 'backtrace' (abbreviated as 'bt'), as follows:

(gdb) bt
#0 ns3::NodeContainer::Get(unsigned int) const
(this=this@entry=0x7fffffffd980, i=4294967295)
at ../src/network/helper/node-container.cc:95
#1 0x000055555555e13e in main(int, char**)
(argc=<optimized out>, argv=<optimized out>)
at ../examples/tutorial/third.cc:165

You can step back up through the call stack to inspect the program state, using the 'up' command:

(gdb) up
#1 0x000055555555e13e in main (argc=<optimized out>, argv=<optimized out>)
at ../examples/tutorial/third.cc:165
165 ApplicationContainer clientApps =

This tells me that line 165 of third.cc was the trigger. Let's look at that code:

ApplicationContainer clientApps =
echoClient.Install (wifiStaNodes.Get (nWifi - 1));

Now it should be obvious why the program segfaulted, and why the value of i above was invalid.

Notice that some of the values above say 'optimized out'. This is because I was debugging on a program that was compiled with some optimizations. To really see in detail what is going on, build ns-3 in 'debug' mode before running gdb.

To debug an individual test suite, use the ''test-runner'' program, such as the following example of the 'csma-system' test suite:

./ns3 run --gdb test-runner
(gdb) run --suite=csma-system

== running gdb with ns3, redirecting all output to a file ==

Sometimes a program will generate a lot of output to stdout and stderr, which may get in the way of interactively using the gdb prompt. It is possible to redirect program output to a file, while interacting with the gdb prompt. Here is a trivial example.

./ns3 run --gdb third
(gdb) run --help > output.txt 2>&1

An example of how to run an individual test suite this way, launching gdb from the command line:

./ns3 run test-runner --command-template="gdb -ex 'run --suite=csma-system > csma-output.txt 2>&1' --args %s"

== saving breakpoints across sessions ==

As of gdb 7.2, breakpoints can be saved to a file and reloaded for a separate session.

For example:

(gdb) info break
Num Type Disp Enb Address What
1 breakpoint keep y <PENDING> random-variable-stream.cc:175
2 breakpoint keep y <PENDING> random-variable-stream.cc:186

to save them to a file called 'breaks':

(gdb) save breakpoints breaks

Later, one can retrieve them as follows.

(gdb) source breaks

In ns-3 with shared libraries, one may get this error:

(gdb) source breaks
No source file named random-variable-stream.cc.
Make breakpoint pending on future shared library load? (y or [n]) [answered N; input not from terminal]
No source file named random-variable-stream.cc.
Make breakpoint pending on future shared library load? (y or [n]) [answered N; input not from terminal]

to work around this, use the command 'set breakpoints pending on' before sourcing the file:

(gdb) set breakpoint pending on
(gdb) source breaks
No source file named random-variable-stream.cc.
Breakpoint 1 (random-variable-stream.cc:175) pending.
No source file named random-variable-stream.cc.
Breakpoint 2 (random-variable-stream.cc:186) pending.
(gdb) info break
Num Type Disp Enb Address What
1 breakpoint keep y <PENDING> random-variable-stream.cc:175
2 breakpoint keep y <PENDING> random-variable-stream.cc:186

HOWTO use gdb to debug program errors

2023-10-27T17:39:45Z

Gabriel: Add link to RedHat GDB guide

{{TOC}}

[http://www.gnu.org/software/gdb/ The GNU Debugger (gdb)] can be used with ns-3 to debug program errors. There are several tutorials online (search for 'gdb tutorial' in a search engine) that explain how to use gdb in general.

One example of such tutorials is part of the [https://access.redhat.com/documentation/en-us/red_hat_developer_toolset/9/html/user_guide/chap-gdb RedHat user guides].

This HOWTO is related to [[HOWTO understand and find cause of terminated with signal errors | another HOWTO]] that explains how to use the [https://www.sourceware.org/insight/ insight tool] (a graphical front-end for gdb) to debug segmentation faults.

This HOWTO is also related to [[HOWTO use Valgrind to debug memory problems | another HOWTO]] that describes how to invoke the [http://www.valgrind.org valgrind tool] to find memory leaks.

== running gdb directly ==

gdb can be invoked on a program executable in the normal way (''gdb <program-name>''), and to do this with ns-3, it is easiest to use the ns3 shell (to set the library paths correctly). We demonstrate with an example of the ''third'' tutorial example.

./ns3 shell
cd build/examples/tutorial
gdb ns3-dev-third-debug
Reading symbols from ns3-dev-third-debug...done.
(gdb)

At this point, one can set breakpoints in the ns-3 libraries, or run the program. We can run it with the ''--help'' argument to print out the program usage:

(gdb) r --help

Or we can deliberately cause a program error by running with an illegal argument

(gdb) r --nWifi=0
Program received signal SIGSEGV, Segmentation fault.
0x0000000000413ac9 in ns3::PeekPointer<ns3::Node> (p=...) at ./ns3/ptr.h:282
282 return p.m_ptr;
(gdb)

To run a test-suite through gdb, use the ''test-runner'' program, such as:

./ns3 shell
cd build/utils/
gdb ns3-dev-test-runner-debug
(gdb) r --suite=csma-system
(gdb) quit

== running gdb with ns3 script ==

ns3 supports a ''--gdb'' argument that allows users to launch gdb and run the programs from there.

./ns3 run --gdb <program-name>

An example using the ''third'' tutorial example, running it first to ask that the help message be printed out, and then running it with an illegal argument:

./ns3 run --gdb third
(gdb) r --help
(gdb) run --nWifi=0
...
Program received signal SIGSEGV, Segmentation fault.
ns3::NodeContainer::Get (this=this@entry=0x7fffffffd980, i=4294967295)
at ../src/network/helper/node-container.cc:95
95 return m_nodes[i];
(gdb)

The program execution is now stopped at the point of the segmentation fault. For a segmentation fault, this often means that the program is trying to access an object from a pointer, but the pointer is not valid. You can check here on the value of 'i' and 'm_nodes[i]' by using the gdb print (abbreviated as 'p'):

(gdb) p i
$1 = 4294967295

You can see how you got to this point by using the 'backtrace' (abbreviated as 'bt'), as follows:

(gdb) bt
#0 ns3::NodeContainer::Get(unsigned int) const
(this=this@entry=0x7fffffffd980, i=4294967295)
at ../src/network/helper/node-container.cc:95
#1 0x000055555555e13e in main(int, char**)
(argc=<optimized out>, argv=<optimized out>)
at ../examples/tutorial/third.cc:165

You can step back up through the call stack to inspect the program state, using the 'up' command:

(gdb) up
#1 0x000055555555e13e in main (argc=<optimized out>, argv=<optimized out>)
at ../examples/tutorial/third.cc:165
165 ApplicationContainer clientApps =

This tells me that line 165 of third.cc was the trigger. Let's look at that code:

ApplicationContainer clientApps =
echoClient.Install (wifiStaNodes.Get (nWifi - 1));

Now it should be obvious why the program segfaulted, and why the value of i above was invalid.

Notice that some of the values above say 'optimized out'. This is because I was debugging on a program that was compiled with some optimizations. To really see in detail what is going on, build ns-3 in 'debug' mode before running gdb.

To debug an individual test suite, use the ''test-runner'' program, such as the following example of the 'csma-system' test suite:

./ns3 run --gdb test-runner
(gdb) run --suite=csma-system

== running gdb with ns3, redirecting all output to a file ==

Sometimes a program will generate a lot of output to stdout and stderr, which may get in the way of interactively using the gdb prompt. It is possible to redirect program output to a file, while interacting with the gdb prompt. Here is a trivial example.

./ns3 run --gdb third
(gdb) run --help > output.txt 2>&1

An example of how to run an individual test suite this way, launching gdb from the command line:

./ns3 run test-runner --command-template="gdb -ex 'run --suite=csma-system > csma-output.txt 2>&1' --args %s"

== saving breakpoints across sessions ==

As of gdb 7.2, breakpoints can be saved to a file and reloaded for a separate session.

For example:

(gdb) info break
Num Type Disp Enb Address What
1 breakpoint keep y <PENDING> random-variable-stream.cc:175
2 breakpoint keep y <PENDING> random-variable-stream.cc:186

to save them to a file called 'breaks':

(gdb) save breakpoints breaks

Later, one can retrieve them as follows.

(gdb) source breaks

In ns-3 with shared libraries, one may get this error:

(gdb) source breaks
No source file named random-variable-stream.cc.
Make breakpoint pending on future shared library load? (y or [n]) [answered N; input not from terminal]
No source file named random-variable-stream.cc.
Make breakpoint pending on future shared library load? (y or [n]) [answered N; input not from terminal]

to work around this, use the command 'set breakpoints pending on' before sourcing the file:

(gdb) set breakpoint pending on
(gdb) source breaks
No source file named random-variable-stream.cc.
Breakpoint 1 (random-variable-stream.cc:175) pending.
No source file named random-variable-stream.cc.
Breakpoint 2 (random-variable-stream.cc:186) pending.
(gdb) info break
Num Type Disp Enb Address What
1 breakpoint keep y <PENDING> random-variable-stream.cc:175
2 breakpoint keep y <PENDING> random-variable-stream.cc:186

Ns-3.37 errata

2022-12-01T14:04:15Z

Gabriel: /* Installation fails unless references to deprecated headers are removed */

On November 1, 2022, ns-3.37 was published. This page lists some issues that have been fixed in the mainline since that time. The maintainers may make an update to this release to cover some or all of these issues.

== Installation fails unless references to deprecated headers are removed ==

Installation may fail due to deprecated headers referenced in the build file. The following commit can be used as a patch to ns-3.37 release to fix the issue: https://gitlab.com/nsnam/ns-3-dev/-/commit/ffc4811cee5f4bc3ecc59ed660b56357346b5ecd