Difference between revisions of "Sprints"

From Nsnam
Jump to: navigation, search
(How to build Doxygen for ns-3 and find the errors: formatting)
(Final report)
 
(67 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{TOC}}
 
{{TOC}}
  
= What is a sprint? =
+
== What is a sprint? ==
  
 
A sprint is a scheduled time for ns-3 contributors to gather and focus their undivided attention on improving the code, documentation, or tests.  
 
A sprint is a scheduled time for ns-3 contributors to gather and focus their undivided attention on improving the code, documentation, or tests.  
  
Sprints are open to anyone, and are conducted on IRC, and if needed, other virtual meeting technologies.
+
Sprints are open to anyone, and have been organized on Zulip and IRC, and if needed, other virtual meeting technologies.
* IRC channel is '''#ns-3''' at irc.freenode.net
+
* ns-3 Zulip channel is https://ns-3.zulipchat.com
  
 
The [https://code.djangoproject.com/wiki/Sprints Django project] has a good reference and links to some presentations all about coding sprints.
 
The [https://code.djangoproject.com/wiki/Sprints Django project] has a good reference and links to some presentations all about coding sprints.
  
A summary of the results of sprints will be shared with other developers on the ns-developers mailing list.
+
== Future sprints ==
  
= Upcoming sprints =
+
=== IETF 111 Hackathon, July 2021 ===
  
== Friday October 3, 14h00-20h00 UTC ==
+
To be scheduled.
('''note:'''  attendees are welcome to attend a subset of the 6-hour slot, if so desired)
+
 
 +
== Past sprints ==
 +
 
 +
We had several past sprints; details from the last few are listed below.  Details from older ones can be found in this wiki page history.
 +
 
 +
=== IETF 110 Hackathon, March 1-4, 2021 ===
 +
* '''Topic:''' L4S and traffic control models for ns-3
 +
* '''Time:'''  14:30-18:30 UTC, March 1-4 (Mon-Thurs.).
 +
* '''Chat:''' We used the Hackathon stream on [https://ns-3.zulipchat.com/#narrow/stream/249003-Hackathon ns-3's Zulip channel].
 +
* '''Video:''' We used [https://galene.org:8443/group/ns3 Galene], a browser-based open source tool, courtesy of [https://www.irif.fr/~jch/ Juliusz Chroboczek].  No password needed; just enter your name and Connect.
 +
 
 +
* '''Participating:''' Tom Henderson, Sachin Nayak
 +
* '''Contact:''' Tom Henderson <tomh at tomh.org>
 +
 
 +
We planned to focus on a few topics related to improved support of L4S and traffic controls in ns-3, along with experimentation with Linux on testbeds.  [https://datatracker.ietf.org/doc/draft-ietf-tsvwg-l4s-arch/ L4S] is an IETF research topic.
 +
 
 +
Several GSoC projects have pending merge requests, so adding them to the ns-3 mainline is a priority:
 +
 
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/362 !362 Add FqCobalt Queue Disc]
 +
** '''Progress:''' The merge request is updated; failing tests need to be debugged
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/377 !377 Add FqPIE with an L4S mode]
 +
** '''Progress:''' The merge request is updated; all tests pass
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/373 !373 TCP Prague model]
 +
** See below section on dual queue patch refresh
 +
* [https://gitlab.com/tomhenderson/ns-3-dev/-/tree/dual-queue Dual Queue Coupled AQM]
 +
** See below section on dual queue patch refresh
 +
 
 +
Some other related patches are in WIP form and could be updated if there is someone interested to work on them (no one volunteered for this):
 +
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/346 !346 ACK filtering] (for CAKE)
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/344 !344 BBRv1 congestion control]
 +
** Mohit is working on an example program
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/341 !341 ECN++ support]
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/342 !342 AccECN support]
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/34 !34 TCP FACK, DSACK, and RACK]
 +
 
 +
Testing and validation of Prague and L4S can be done with real implementations.  There is a [https://github.com/L4STeam/linux Linux kernel implementation of Prague] but it is for kernel 5.4.  Time permitting, we will also look at rebasing Prague to kernel 5.10 version for Google's BBRv2: https://github.com/google/bbr/tree/v2alpha
 +
* No one volunteered for this
 +
 
 +
The CloudLab-based experimentation framework prevoiusly worked on here:
 +
 
 +
* https://github.com/ffund/sce-l4s-bakeoff
 +
 
 +
may be useful for the Linux work, as well as a netns-based framework:
 +
 
 +
* https://github.com/L4STeam/l4steam.github.io/tree/master/rtt-independence/experiments
 +
 
 +
There are some bugs filed on our TCP model that could be looked at by anyone interested.
 +
 
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name=module%3A%3Ainternet%3Atcp TCP issues].  In particular, 59, 78, 125, 248.
 +
** Sachin Nayak worked on testing for issue #59
 +
 
 +
==== Final report ====
 +
 
 +
[https://www.nsnam.org/wp-content/uploads/2021/ietf-110-hackathon-presentation-ns-3.pdf Final presentation slides] from the IETF closing session.
 +
 
 +
Tom Henderson completed the final review and updating of the ns-3 models for FQ-PIE and FQ-COBALT, both with experimental support for L4S as well:
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/362 !362 Add FqCobalt Queue Disc]
 +
* [https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/377 !377 Add FqPIE with an L4S mode]
 +
 
 +
Tom Henderson created a new branch to is working on refreshing the dual queue AQM and TCP Prague models for L4S.  The dual queue model was originally written by Shravya KS in 2017 GSoC.  The TCP Prague model was originally written by Deepak K in 2020 GSoC.  This branch is at https://gitlab.com/tomhenderson/ns-3-dev/tree/hackathon-ietf-110.
 +
 
 +
* check if there are any technical differences between draft version -10 and -13 (current)
 +
** '''progress:''' There are small changes in the appendix to the default ramp thresholds, and the random variable for drop should be replaced by the recur() method, for the classic queue
 +
* rebase https://gitlab.com/tomhenderson/ns-3-dev/tree/dual-queue branch to ns-3-dev, to prepare a merge request
 +
** '''progress:''' This branch is now at https://gitlab.com/tomhenderson/ns-3-dev/-/tree/dual-queue-coupled-aqm.  It runs the example, and the test suite runs (with some failures)
 +
* test with the TCP Prague model developed by Deepak K in 2020 GSoC (https://gitlab.com/deepakkavoor/ns-3-dev/-/tree/prague-mr)
 +
** '''progress:'''  I have merged this Prague model with the dual-queue-coupled-aqm branch to create a 'hackathon-ietf-110' branch
 +
* test with the L4S evaluation suite (https://gitlab.com/tomhend/modules/l4s-evaluation)
 +
** '''progress:'''  The tcp-prague.cc example (examples/tcp/tcp-prague.cc) is based on this evaluation suite
 +
 
 +
The 'hackathon-ietf-110' branch is now delivering results similar to those published in [https://deepakkavoor.github.io/gsoc-2020-prague Deepak K's final report].  More testing/validation is needed to confirm this for all test cases.
 +
 
 +
The ultimate goal of all of the above is to have updated modules to experiment within the scenarios being used in the [https://datatracker.ietf.org/wg/tsvwg/about/ IETF tsvwg] to evaluate L4S, as described here:  https://l4s.cablelabs.com/
 +
 
 +
=== IETF 109 Hackathon, Nov 9-12, 2020 ===
 +
* '''Topic:''' TCP models for ns-3
 +
* '''Time:'''  15:00-19:00 UTC, Nov 9-12 (Mon-Thurs.).
 +
* '''Chat:''' We used the Hackathon stream on [https://ns-3.zulipchat.com/#narrow/stream/249003-Hackathon ns-3's Zulip channel].
 +
* '''Participating:''' Tom Henderson, Mohit Tahiliani, Aditya Chaudhary, Sayali Patil, Sushma Meena
 +
* '''Contact:''' Tom Henderson <tomh at tomh.org>
 +
 
 +
''Summary slides:'' https://www.nsnam.org/wp-content/uploads/2020/ietf-109-hackathon-presentation-ns-3.pdf
 +
 
 +
==== TCP Cubic ====
 +
 
 +
Finish off the testing and validation work described here:  https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/408
 +
 
 +
This [https://docs.google.com/document/d/1QiDqBo94wKr1eptTFe6xAB0RWWlwYOy8VLOWrpVAie8/edit Google Document] contains links to the latest status and steps to reproduce.
 +
 
 +
Accomplishments:
 +
* implement CWR state for ECN Echo handling
 +
* debug slow start window growth differences
 +
 
 +
==== BBRv1 ====
 +
 
 +
Accomplishments:  Further alignment against Linux BBRv1 results.
 +
 
 +
==== Flent ====
 +
 
 +
Harsha Sharma has been working on a flent application for ns-3 (to produce datasets similar to and compatible with the [https://flent.org flent tool].
 +
 
 +
Accomplishments:  Debug high latency of pings in RRUL test (due to hash collisions).  Debug TCP throughput differences for RRUL tests (due in part to socket buffer size differences).
 +
 
 +
=== IETF 108 Hackathon, July 20-23, 2020 ===
 +
* '''Topic:''' IETF L4S models for ns-3
 +
* '''Time:'''  14:00-18:00 UTC July 20-23 (Mon-Thurs.)
 +
* '''Chat:''' We will interact on the Hackathon stream on [https://ns-3.zulipchat.com/#narrow/stream/249003-Hackathon ns-3's Zulip channel].
 +
* '''Slides (closing IETF session):''' [https://www.nsnam.org/wp-content/uploads/2020/hackathon-presentation-l4s.pdf IETF presentation]
 +
** [https://www.nsnam.org/wp-content/uploads/2020/ns-3-l4s.pdf Supplemental slides]
 +
* '''Collaboration document:'''  https://docs.google.com/document/d/1rmE8m1j_AZvYIbeZRt25xHrPTSX7ihoXH5fCo3TGH_8/edit
 +
* '''Participating:''' Tom Henderson, Bhaskar Kataria, Harsha Sharma, Deepak Kumaraswamy, Ashutosh Srivastava, Fraida Fund
 +
 
 +
Our plan was to continue with testing, documenting, and preparing for the mainline, the various components that make up [https://www.ietf.org/id/draft-ietf-tsvwg-l4s-arch-06.txt L4S support for ns-3]
 +
 
 +
Integrated code was posted at the following two locations:
 +
* [https://gitlab.com/tomhenderson/ns-3-dev/tree/hackathon/master ns-3 (hackathon/master branch)]
 +
* [https://gitlab.com/tomhend/modules/l4s-evaluation/tree/hackathon/master l4s-evaluation module (hackathon/master branch)]
 +
 
 +
Some accomplishments for the week are listed below:
 +
 
 +
* Deepak added RTT independence feature to the Prague code, and helped with some integration issues regarding AccECN and ECN++ code
 +
* Bhaskar's Fq/CoDel code was added to the integrated code above, and he further worked on a Fq/Cobalt variant
 +
* Harsha worked on Flent application support, exploring C++ JSON serialization libraries and how to use Flent to plot ns-3 output data
 +
* Ashutosh and Fraida created [https://github.com/ffund/sce-l4s-bakeoff scripts and documentation] for using [https://cloudlab.us CloudLab] to test L4S kernel code
 +
* Tom performed overall ns-3 integration and testing.  AccECN and ECN++ support had to be backed out due to some failing mainline tests, but existing Prague does not yet need the full AccECN support.
 +
 
 +
Below are some links for those who may want to obtain, review, and run the ns-3 code:
 +
* Installation guide:  Please see the [https://www.nsnam.org/wp-content/uploads/2020/ns-3-l4s.pdf supplemental slides] for a quick start guide
 +
* TCP Prague project:  https://www.nsnam.org/wiki/GSOC2020Prague
 +
* L4S AQMs project: https://www.nsnam.org/wiki/GSOC2020AQM
 +
* Flent and L4S evaluation:  https://www.nsnam.org/wiki/NSOC2020L4SEvaluation
 +
 
 +
=== GSoC 2020 Code Sprint, May 16, 2020 ===
 +
* '''Topic:''' ns-3 issues and merge requests
 +
* '''Time:'''  10:00 through 18:00 CEST (UTC+2)
 +
* '''Place:''' Online only.  We will interact on [https://ns-3.zulipchat.com ns-3 Zulip] and on Jitsi.
 +
* '''Participating:''' Tommaso Pecorella, Ananthakrishnan Saji,  Deepak K.
 +
 
 +
=== IETF 107 Hackathon, March 21-22, 2020 ===
 +
* Unfortunately, this has been cancelled along with IETF 107.
 +
 
 +
=== IETF 106 Hackathon, November 16-17, 2019 ===
 +
* '''Topic:''' IETF L4S models for ns-3
 +
* '''Time:'''  8:30am Singapore (UTC+8), Saturday Nov. 16, through 16:00pm Sunday Nov. 17
 +
* '''Place:''' The physical location was IETF 106 in Singapore.  We will interact on [https://ns-3.zulipchat.com ns-3 Zulip] and on the L4S team's Slack channel.
 +
* '''Participating:''' Tom Henderson, Mohit Tahiliani, Vivek Jain, Joakim Misund
 +
 
 +
Our plan was to continue with testing, documenting, and preparing for the mainline, the various components that make up L4S:
 +
* AccECN and ECN++:  https://github.com/Vivek-anand-jain/ns-3-dev-git/tree/ecnpp
 +
* DualQ Coupled AQM and PI2:  https://gitlab.com/tomhenderson/ns-3-dev/tree/dual-queue
 +
* DCTCP:  https://github.com/Vivek-anand-jain/ns-3-dev-git/tree/dctcp-latest-rebase
 +
* TCP Prague
 +
 
 +
A new ns-3 extension module for L4S experiments has been posted [https://gitlab.com/tomhend/modules/l4s-evaluation here].
 +
 
 +
==== Accomplishments ====
 +
 
 +
'''1) Update DualQ implementation to latest IETF draft.'''
 +
 
 +
The latest IETF draft is here: https://www.ietf.org/id/draft-ietf-tsvwg-aqm-dualq-coupled-10.txt
 +
 
 +
We want the ns-3 implementation to align as closely as possible to Appendix A of the draft, Figures 2-6 (i.e. without overload code for the first phase).  This includes some variable naming updates, some arithmetic alignment, and reviewing the notes in Appendix A.
 +
 
 +
For example, the method recur(likelihood) was introduced in recent drafts.
 +
 
 +
'''Status:''' Tom Henderson completed this model port (still requiring tests and documentation update):
 +
 
 +
* https://gitlab.com/tomhenderson/ns-3-dev/tree/dual-queue
 +
 
 +
'''2) Create an initial TcpPrague model'''
 +
 
 +
Using the paced chirping code from Joakim Misund, take the current TcpDctcp model and create a TcpPrague model that initially is identical to TcpDctcp.  Then, add paced chirping as a first step.  This can be optionally enabled via an ns-3 attribute "EnablePacedChirping".
 +
 
 +
'''Status:''' Joakim continues to develop his branch:  https://gitlab.com/JoakimMisund/l4s-evaluation/tree/tcp-prague
 +
 
 +
'''3) TCP ECN refactoring.'''
 +
 
 +
We are reworking the TCP ECN configuration code so that we can more flexibly configure ECT(0) or ECT(1) and ECN mode (classic or DCTCP or AccECN mode) and trigger it from the selection of congestion control
 +
 
 +
'''Status:''' After much discussion during the hackathon, Vivek Jain completed two patches that should be readied for the mainline: 
 +
 
 +
* https://gitlab.com/Vivek-anand-jain/ns-3-dev/commits/dctcp
 +
 
 +
=== IETF 105 Hackathon, July 20, 2019 ===
 +
* '''Topic:''' IETF L4S models for ns-3
 +
* '''Participating:''' Ankit Deepak, Tom Henderson, Vivek Jain, Viyom Mittal, Mohit Tahiliani
 +
 
 +
A document describing the goals and plan was provided at [https://www.nsnam.org/wp-content/uploads/2019/ns-3-IETF-105-hackathon-plan.pdf this link].
 +
 
 +
* AccECN and ECN++:  https://github.com/Vivek-anand-jain/ns-3-dev-git/tree/ecnpp
 +
* DualQ Coupled AQM and PI2:  https://gitlab.com/tomhenderson/ns-3-dev/tree/dual-queue
 +
* DCTCP:  https://github.com/Vivek-anand-jain/ns-3-dev-git/tree/dctcp-latest-rebase
 +
 
 +
==== Accomplishments ====
 +
 
 +
In the July 2019 IETF 105 hackathon sprint, we focused on updating a number of previously submitted [https://riteproject.eu/dctth/ L4S] models.
 +
* Vivek Jain updated Wenying Dai's previous AccECN and ECN++ patch to the latest ns-3-dev
 +
** https://github.com/Vivek-anand-jain/ns-3-dev-git/tree/ecnpp
 +
* Ankit Deepak updated Shravya KS's previous Dual Queue queue disc, and also PI2 queue disc code
 +
** https://gitlab.com/tomhenderson/ns-3-dev/tree/dual-queue
 +
* Mohit Tahiliani and Viyom Mittal updated the ns-3 DCTCP code and performed some cleanup of previous patches
 +
** https://github.com/tomhenderson/ns-3-dev/tree/dctcp
 +
 
 +
=== Friday March 27, 2015, 13h00-19h00 UTC ===
 
* '''Etherpad:''' http://etherpad.osuosl.org/gMofL8fupm
 
* '''Etherpad:''' http://etherpad.osuosl.org/gMofL8fupm
* '''Topic:'''  Documentation improvement.  https://www.nsnam.org/bugzilla/show_bug.cgi?id=938.  In particular, we will work on reducing the number of doxygen warnings that are generated due to missing Doxygen.  This is a long-standing issue that just requires group effort to resolve.
+
* '''Topic:'''  Add Groups to TypeIds:  http://mailman.isi.edu/pipermail/ns-developers/2015-February/012515.html
 +
* '''Organizer:''' [mailto:tomhend@u.washington.edu Tom Henderson]
 +
* '''Preparation:'''
 +
*# Read the [[Sprints#General_preparation | general preparation]] below.
 +
*# Do you have mercurial installed?  Can you clone http://code.nsnam.org/ns-3-dev in some scratch directory to work on this?
 +
*# Can you run this program successfully?  Then you are ready for testing the work produced by this sprint:
 +
  <nowiki>./waf --run "third --PrintHelp"
 +
  Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
 +
  Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
 +
  'build' finished successfully (3.209s)
 +
  ns3-dev-third-debug [Program Arguments] [General Arguments]
 +
 
 +
  Program Arguments:
 +
    --nCsma:    Number of "extra" CSMA nodes/devices [3]
 +
    --nWifi:    Number of wifi STA devices [3]
 +
    --verbose:  Tell echo applications to log if true [true]
 +
 
 +
  General Arguments:
 +
    --PrintGlobals:              Print the list of globals.
 +
    --PrintGroups:              Print the list of groups.
 +
    --PrintGroup=[group]:        Print all TypeIds of group.
 +
    --PrintTypeIds:              Print all TypeIds.
 +
    --PrintAttributes=[typeid]:  Print all attributes of typeid.
 +
    --PrintHelp:                Print this help message.
 +
  </nowiki>
 +
This command should also work;
 +
  <nowiki>./waf --run "third --PrintGroups"
 +
  Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
 +
  Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
 +
  'build' finished successfully (3.231s)
 +
  Registered TypeId groups:
 +
   
 +
    Mobility</nowiki>
 +
 
 +
We then want to be able to list all of the relevant TypeIds:
 +
 
 +
<nowiki>./waf --run "third --PrintGroup=Mobility"
 +
Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
 +
Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
 +
'build' finished successfully (3.202s)
 +
TypeIds in group Mobility:
 +
    ns3::GaussMarkovMobilityModel
 +
    ns3::GridPositionAllocator
 +
    ns3::RandomBoxPositionAllocator
 +
    ns3::RandomDirection2dMobilityModel
 +
    ns3::RandomDiscPositionAllocator
 +
    ns3::RandomRectanglePositionAllocator
 +
    ns3::RandomWalk2dMobilityModel
 +
    ns3::RandomWaypointMobilityModel
 +
    ns3::SteadyStateRandomWaypointMobilityModel
 +
    ns3::UniformDiscPositionAllocator
 +
    ns3::WaypointMobilityModel</nowiki>
 +
 
 +
Then the attributes of a given class; this type of capability will be enabled across the codebase if we set the Group names consistently:
 +
 
 +
  <nowiki>./waf --run "third --PrintAttributes=ns3::RandomWalk2dMobilityModel"
 +
Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
 +
Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
 +
'build' finished successfully (3.187s)
 +
Attributes for TypeId ns3::RandomWalk2dMobilityModel
 +
    --ns3::RandomWalk2dMobilityModel::Bounds=[0|100|0|100]
 +
        Bounds of the area to cruise.
 +
    --ns3::RandomWalk2dMobilityModel::Direction=[ns3::UniformRandomVariable[Min=0.0|Max=6.283184]]
 +
        A random variable used to pick the direction (radians).
 +
    --ns3::RandomWalk2dMobilityModel::Distance=[1]
 +
        Change current direction and speed after moving for this distance.
 +
    --ns3::RandomWalk2dMobilityModel::Mode=[Distance]
 +
        The mode indicates the condition used to change the current speed and direction
 +
    --ns3::RandomWalk2dMobilityModel::Speed=[ns3::UniformRandomVariable[Min=2.0|Max=4.0]]
 +
        A random variable used to pick the speed (m/s).
 +
    --ns3::RandomWalk2dMobilityModel::Time=[+1000000000.0ns]
 +
        Change current direction and speed after moving for this delay.</nowiki>
 +
 
 +
* '''Tasks:'''  We will organize to group as many TypeIds as possible, across module lines.  For instance, someone will be assigned the src/applications module, someone will be assigned the src/propagation model, and so on.  When finished or having taken it as far as you can, submit a patch for the module.
 +
* '''Patches:''' We would like code to be sent in unified diff format.  An easy way to do this is to use the 'hg diff' command, and redirect the output into a file (and submit the file).  For instance, here is the output of 'hg diff' if one line of text is added:
 +
 
 +
<nowiki>hg diff
 +
diff -r 6ea11eb86c17 src/applications/model/application-packet-probe.cc
 +
--- a/src/applications/model/application-packet-probe.cc Thu Mar 19 21:13:16 2015 +0100
 +
+++ b/src/applications/model/application-packet-probe.cc Mon Mar 23 15:44:33 2015 -0700
 +
@@ -39,6 +39,7 @@
 +
{
 +
  static TypeId tid = TypeId ("ns3::ApplicationPacketProbe")
 +
    .SetParent<Probe> ()
 +
+    .SetGroupName ("Application")
 +
    .AddConstructor<ApplicationPacketProbe> ()
 +
    .AddTraceSource ( "Output",
 +
                      "The packet plus its socket address that serve "</nowiki>
 +
 
 +
If you type
 +
 
 +
  hg diff > application.patch
 +
 
 +
you will store the above in a patch file, which can be submitted.
 +
 
 +
Please remember that an implementation file (.cc) may contain multiple TypeId declarations, so please search through each file.
 +
 
 +
* '''Outcome:''' If successful, the PrintGroups command will have many groups defined (one for each module, perhaps more).  The tutorial and manual will also be extended to describe how to use this feature. 
 +
*  '''Coordination:'''  We will use IRC and [http://etherpad.org Etherpad] to coordinate the work (make sure multiple people do not work on the same file).
 +
 
 +
==== Accomplishments ====
 +
 
 +
In the March 2015 sprint, we were able to commit about half of the SetGroupName() methods across the codebase.  Following the sprint, the remainder of the codebase was handled, so by the ns-3.23 release, this item was completed
 +
 
 +
=== Friday December 12, 2014, 14h00-20h00 UTC ===
 +
* '''Etherpad:''' http://etherpad.osuosl.org/gMofL8fupm
 +
* '''Topic:'''  Documentation improvement.  https://www.nsnam.org/bugzilla/show_bug.cgi?id=938.  In particular, we worked on reducing the number of doxygen warnings that are generated due to missing Doxygen.  This is a long-standing issue that just requires group effort to resolve.
 
* '''Organizer:''' [mailto:tomhend@u.washington.edu Tom Henderson]
 
* '''Organizer:''' [mailto:tomhend@u.washington.edu Tom Henderson]
 
* '''Preparation:'''
 
* '''Preparation:'''
Line 26: Line 336:
 
*# Contact ns-3-users mailing list or the organizer for help if you have trouble with the above
 
*# Contact ns-3-users mailing list or the organizer for help if you have trouble with the above
 
* '''Tasks:'''   
 
* '''Tasks:'''   
: Fix as many of the doxygen warnings as we can.  A current count of warnings (by module) can be seen here:  http://mailman.isi.edu/pipermail/ns-commits/2014-September/015625.html.  There is a full log generated that can be used to identify what is the error, and then it can be fixed with a text editor.  How this is planned to work is that contributors who show up will choose a file or set of files (that they are comfortable with documenting) and will try to clear the errors in that file, producing a patch that can be merged to ns-3-dev.
+
: Fix as many of the doxygen warnings as we can.  A current count of warnings (by module) can be seen here:  http://mailman.isi.edu/pipermail/ns-commits/2014-November/015994.html.  There is a full log generated that can be used to identify what is the error, and then it can be fixed with a text editor.  How this is planned to work is that contributors who show up will choose a file or set of files (that they are comfortable with documenting) and will try to clear the errors in that file, producing a patch that can be merged to ns-3-dev.
 +
 
 +
: We may also work on [https://www.nsnam.org/bugzilla/show_bug.cgi?id=1832 reducing includes] in ns-3.
 +
 
 
*  '''Coordination:'''  We will use IRC and [http://etherpad.org Etherpad] to coordinate the work (make sure multiple people do not work on the same file).
 
*  '''Coordination:'''  We will use IRC and [http://etherpad.org Etherpad] to coordinate the work (make sure multiple people do not work on the same file).
  
 +
==== Accomplishments ====
  
=== How to build Doxygen for ns-3 and find the errors ===
+
In the December 2014 sprint, we were able to get to zero warnings on the LTE helper directory, and also the mobility model and helper directories.  December sprint warnings fixed (Peter, Piotr, Tom):
 +
* 176 src/mobility/model  (all eliminated)
 +
* 39 src/mobility/helper  (all eliminated)
 +
* 146 src/lte/helper  (all eliminated)
 +
* reduced src/core warnings to below 500 count
  
 +
=== October 2014 Doxygen sprint ===
 +
 +
This was a Doxygen-focused sprint with the following instructions.
  
 
*  Use mercurial to check out the current copy of ns-3 (see the tutorial if you don't know how to do this):
 
*  Use mercurial to check out the current copy of ns-3 (see the tutorial if you don't know how to do this):
Line 43: Line 364:
 
Then, run the script <tt>doc/doxygen.warnings.report.sh</tt> from the <tt>ns-3-dev</tt> directory:
 
Then, run the script <tt>doc/doxygen.warnings.report.sh</tt> from the <tt>ns-3-dev</tt> directory:
  
   $ ./doc/doxygen.warnings.report.sh
+
   $ ./doc/doxygen.warnings.report.sh -t -e
  
This will produce lots of summary statistics like:
+
(Note:  this excludes tests and examples; to include warnings for those files, rerun without the -t and -e options).  This will produce lots of summary statistics like:
 +
 
 +
  Warnings by module/directory:
 +
 
 +
  Count Directory
 +
  ----- ----------------------------------
 +
  3390 src/lte/model
 +
  1532 src/wimax/model
 +
    575 src/core/model
 +
    570 src/wifi/model
 +
    488 src/mesh/model
 +
    338 src/visualizer/visualizer
 +
    229 src/netanim/model
 +
    213 src/dsr/model
 +
    ...
  
  Warnings by module/directory:
 
 
 
  Count Directory
 
  ----- ----------------------------------
 
  3219 src/lte/model
 
  1173 src/wimax/model
 
  1066 src/core/model
 
    646 src/lte/test
 
    518 src/wifi/model
 
 
     ...  
 
     ...  
 +
 +
Do not worry if the output scrolls beyond the buffer in your terminal window; the full warnings log is written to doc/doxygen.warnings.log.
  
 
Once this is complete, you can use the <tt>doxygen.warnings.report.sh</tt> script to focus on one module or file.  To see just the errors from one module, for example <tt>wifi</tt>:
 
Once this is complete, you can use the <tt>doxygen.warnings.report.sh</tt> script to focus on one module or file.  To see just the errors from one module, for example <tt>wifi</tt>:
  
   $ ./doc/doxygen.warnings.report.sh -s -m wifi
+
   $ ./doc/doxygen.warnings.report.sh -t -e -s -m wifi
  
 
The <tt>-s</tt> option skips the doxygen run, and just reports results  
 
The <tt>-s</tt> option skips the doxygen run, and just reports results  
 
from the existing warnings log.  Obviously, if you want to see the results of your edits,  
 
from the existing warnings log.  Obviously, if you want to see the results of your edits,  
you would omit the <tt>-s</tt> option. The <tt>-m <module></tt> option only shows  
+
you would omit the <tt>-s</tt> option so you could regenerate the warnings log.  
 +
The <tt>-m <module></tt> option only shows  
 
results from the <tt>./src/<module></tt> module; after printing the
 
results from the <tt>./src/<module></tt> module; after printing the
 
warnings counts by file, it shows the actual errors from each file:
 
warnings counts by file, it shows the actual errors from each file:
Line 71: Line 400:
 
   Filtered Warnings
 
   Filtered Warnings
 
   ========================================
 
   ========================================
   src/wifi/examples/wifi-phy-test.cc:53: warning: Compound PsrExperiment::Output is not documented.
+
   src/wifi/helper/athstats-helper.h:49: warning: Member EnableAthstats(std::string filename, uint32_t nodeid,
 +
  uint32_t deviceid) (function) of class ns3::AthstatsHelper is not documented.
 
   ...
 
   ...
  
This means the type (probably a struct) <tt>PsrExperiment::Output</tt> has no documentation,
+
This means the method <tt>AthstatsHelper::EnableAthstats</tt> has no documentation,
and it's declared in <tt>src/wifi/examples/wifi-phy-test.cc</tt> around line 53.
+
and it's declared in <tt>src/wifi/helper/athstats-helper.h</tt> around line 49.
  
 
To see just the warnings from a single file (or a set of files matching a regular expression)
 
To see just the warnings from a single file (or a set of files matching a regular expression)
Line 81: Line 411:
  
 
   $ ./doc/doxygen.warnings.report.sh -s -F "block-ack.*"
 
   $ ./doc/doxygen.warnings.report.sh -s -F "block-ack.*"
 
=== How to add documentation during the sprint ===
 
  
  
Line 117: Line 445:
 
   $ firefox doc/html/index.html &
 
   $ firefox doc/html/index.html &
  
=== How to contribute your docs ===
 
  
 
Once you have fixed a file, you may create a patch such as follows:
 
Once you have fixed a file, you may create a patch such as follows:
Line 125: Line 452:
 
and upload it to [https://www.nsnam.org/bugzilla/show_bug.cgi?id=938 bug 938] or email it to one of the maintainers participating in the sprint (you can ask on IRC about it).
 
and upload it to [https://www.nsnam.org/bugzilla/show_bug.cgi?id=938 bug 938] or email it to one of the maintainers participating in the sprint (you can ask on IRC about it).
  
== General preparation ==
+
 
  
 
* Make sure that you can join the IRC channel in advance
 
* Make sure that you can join the IRC channel in advance
Line 131: Line 458:
 
* Familiarize yourself with how to [http://www.nsnam.org/developers/contributing-code/submit/ generate a patch] against ns-3-dev.  Patches you write can be uploaded to Bugzilla or sent to one of the maintainers.
 
* Familiarize yourself with how to [http://www.nsnam.org/developers/contributing-code/submit/ generate a patch] against ns-3-dev.  Patches you write can be uploaded to Bugzilla or sent to one of the maintainers.
  
== Once you're there ==
+
==== Accomplishments ====
  
* Check in on IRC by letting others know that you've joined and are ready to contribute, and a maintainer will go from there
+
In the October 2014 sprint, the following warnings were fixed (Budi, Tiago, Tommaso, Natale, Peter):
 +
* src/lte warnings count reduced by ~1500
 +
* src/mobility warnings count reduced by 20
 +
* all 160 propagation warnings eliminated
 +
* all 47 point-to-point warnings eliminated
 +
* all 55 internet warnings eliminated

Latest revision as of 18:31, 5 March 2021

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

What is a sprint?

A sprint is a scheduled time for ns-3 contributors to gather and focus their undivided attention on improving the code, documentation, or tests.

Sprints are open to anyone, and have been organized on Zulip and IRC, and if needed, other virtual meeting technologies.

The Django project has a good reference and links to some presentations all about coding sprints.

Future sprints

IETF 111 Hackathon, July 2021

To be scheduled.

Past sprints

We had several past sprints; details from the last few are listed below. Details from older ones can be found in this wiki page history.

IETF 110 Hackathon, March 1-4, 2021

  • Topic: L4S and traffic control models for ns-3
  • Time: 14:30-18:30 UTC, March 1-4 (Mon-Thurs.).
  • Chat: We used the Hackathon stream on ns-3's Zulip channel.
  • Video: We used Galene, a browser-based open source tool, courtesy of Juliusz Chroboczek. No password needed; just enter your name and Connect.
  • Participating: Tom Henderson, Sachin Nayak
  • Contact: Tom Henderson <tomh at tomh.org>

We planned to focus on a few topics related to improved support of L4S and traffic controls in ns-3, along with experimentation with Linux on testbeds. L4S is an IETF research topic.

Several GSoC projects have pending merge requests, so adding them to the ns-3 mainline is a priority:

Some other related patches are in WIP form and could be updated if there is someone interested to work on them (no one volunteered for this):

Testing and validation of Prague and L4S can be done with real implementations. There is a Linux kernel implementation of Prague but it is for kernel 5.4. Time permitting, we will also look at rebasing Prague to kernel 5.10 version for Google's BBRv2: https://github.com/google/bbr/tree/v2alpha

  • No one volunteered for this

The CloudLab-based experimentation framework prevoiusly worked on here:

may be useful for the Linux work, as well as a netns-based framework:

There are some bugs filed on our TCP model that could be looked at by anyone interested.

  • TCP issues. In particular, 59, 78, 125, 248.
    • Sachin Nayak worked on testing for issue #59

Final report

Final presentation slides from the IETF closing session.

Tom Henderson completed the final review and updating of the ns-3 models for FQ-PIE and FQ-COBALT, both with experimental support for L4S as well:

Tom Henderson created a new branch to is working on refreshing the dual queue AQM and TCP Prague models for L4S. The dual queue model was originally written by Shravya KS in 2017 GSoC. The TCP Prague model was originally written by Deepak K in 2020 GSoC. This branch is at https://gitlab.com/tomhenderson/ns-3-dev/tree/hackathon-ietf-110.

The 'hackathon-ietf-110' branch is now delivering results similar to those published in Deepak K's final report. More testing/validation is needed to confirm this for all test cases.

The ultimate goal of all of the above is to have updated modules to experiment within the scenarios being used in the IETF tsvwg to evaluate L4S, as described here: https://l4s.cablelabs.com/

IETF 109 Hackathon, Nov 9-12, 2020

  • Topic: TCP models for ns-3
  • Time: 15:00-19:00 UTC, Nov 9-12 (Mon-Thurs.).
  • Chat: We used the Hackathon stream on ns-3's Zulip channel.
  • Participating: Tom Henderson, Mohit Tahiliani, Aditya Chaudhary, Sayali Patil, Sushma Meena
  • Contact: Tom Henderson <tomh at tomh.org>

Summary slides: https://www.nsnam.org/wp-content/uploads/2020/ietf-109-hackathon-presentation-ns-3.pdf

TCP Cubic

Finish off the testing and validation work described here: https://gitlab.com/nsnam/ns-3-dev/-/merge_requests/408

This Google Document contains links to the latest status and steps to reproduce.

Accomplishments:

  • implement CWR state for ECN Echo handling
  • debug slow start window growth differences

BBRv1

Accomplishments: Further alignment against Linux BBRv1 results.

Flent

Harsha Sharma has been working on a flent application for ns-3 (to produce datasets similar to and compatible with the flent tool.

Accomplishments: Debug high latency of pings in RRUL test (due to hash collisions). Debug TCP throughput differences for RRUL tests (due in part to socket buffer size differences).

IETF 108 Hackathon, July 20-23, 2020

Our plan was to continue with testing, documenting, and preparing for the mainline, the various components that make up L4S support for ns-3

Integrated code was posted at the following two locations:

Some accomplishments for the week are listed below:

  • Deepak added RTT independence feature to the Prague code, and helped with some integration issues regarding AccECN and ECN++ code
  • Bhaskar's Fq/CoDel code was added to the integrated code above, and he further worked on a Fq/Cobalt variant
  • Harsha worked on Flent application support, exploring C++ JSON serialization libraries and how to use Flent to plot ns-3 output data
  • Ashutosh and Fraida created scripts and documentation for using CloudLab to test L4S kernel code
  • Tom performed overall ns-3 integration and testing. AccECN and ECN++ support had to be backed out due to some failing mainline tests, but existing Prague does not yet need the full AccECN support.

Below are some links for those who may want to obtain, review, and run the ns-3 code:

GSoC 2020 Code Sprint, May 16, 2020

  • Topic: ns-3 issues and merge requests
  • Time: 10:00 through 18:00 CEST (UTC+2)
  • Place: Online only. We will interact on ns-3 Zulip and on Jitsi.
  • Participating: Tommaso Pecorella, Ananthakrishnan Saji, Deepak K.

IETF 107 Hackathon, March 21-22, 2020

  • Unfortunately, this has been cancelled along with IETF 107.

IETF 106 Hackathon, November 16-17, 2019

  • Topic: IETF L4S models for ns-3
  • Time: 8:30am Singapore (UTC+8), Saturday Nov. 16, through 16:00pm Sunday Nov. 17
  • Place: The physical location was IETF 106 in Singapore. We will interact on ns-3 Zulip and on the L4S team's Slack channel.
  • Participating: Tom Henderson, Mohit Tahiliani, Vivek Jain, Joakim Misund

Our plan was to continue with testing, documenting, and preparing for the mainline, the various components that make up L4S:

A new ns-3 extension module for L4S experiments has been posted here.

Accomplishments

1) Update DualQ implementation to latest IETF draft.

The latest IETF draft is here: https://www.ietf.org/id/draft-ietf-tsvwg-aqm-dualq-coupled-10.txt

We want the ns-3 implementation to align as closely as possible to Appendix A of the draft, Figures 2-6 (i.e. without overload code for the first phase). This includes some variable naming updates, some arithmetic alignment, and reviewing the notes in Appendix A.

For example, the method recur(likelihood) was introduced in recent drafts.

Status: Tom Henderson completed this model port (still requiring tests and documentation update):

2) Create an initial TcpPrague model

Using the paced chirping code from Joakim Misund, take the current TcpDctcp model and create a TcpPrague model that initially is identical to TcpDctcp. Then, add paced chirping as a first step. This can be optionally enabled via an ns-3 attribute "EnablePacedChirping".

Status: Joakim continues to develop his branch: https://gitlab.com/JoakimMisund/l4s-evaluation/tree/tcp-prague

3) TCP ECN refactoring.

We are reworking the TCP ECN configuration code so that we can more flexibly configure ECT(0) or ECT(1) and ECN mode (classic or DCTCP or AccECN mode) and trigger it from the selection of congestion control

Status: After much discussion during the hackathon, Vivek Jain completed two patches that should be readied for the mainline:

IETF 105 Hackathon, July 20, 2019

  • Topic: IETF L4S models for ns-3
  • Participating: Ankit Deepak, Tom Henderson, Vivek Jain, Viyom Mittal, Mohit Tahiliani

A document describing the goals and plan was provided at this link.

Accomplishments

In the July 2019 IETF 105 hackathon sprint, we focused on updating a number of previously submitted L4S models.

Friday March 27, 2015, 13h00-19h00 UTC

 ./waf --run "third --PrintHelp"
  Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
  Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
  'build' finished successfully (3.209s)
  ns3-dev-third-debug [Program Arguments] [General Arguments]

  Program Arguments:
    --nCsma:    Number of "extra" CSMA nodes/devices [3]
    --nWifi:    Number of wifi STA devices [3]
    --verbose:  Tell echo applications to log if true [true]

  General Arguments:
    --PrintGlobals:              Print the list of globals.
    --PrintGroups:               Print the list of groups.
    --PrintGroup=[group]:        Print all TypeIds of group.
    --PrintTypeIds:              Print all TypeIds.
    --PrintAttributes=[typeid]:  Print all attributes of typeid.
    --PrintHelp:                 Print this help message.
  

This command should also work;

 ./waf --run "third --PrintGroups"
  Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
  Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
  'build' finished successfully (3.231s)
  Registered TypeId groups:
    
    Mobility

We then want to be able to list all of the relevant TypeIds:

./waf --run "third --PrintGroup=Mobility"
Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
'build' finished successfully (3.202s)
TypeIds in group Mobility:
    ns3::GaussMarkovMobilityModel
    ns3::GridPositionAllocator
    ns3::RandomBoxPositionAllocator
    ns3::RandomDirection2dMobilityModel
    ns3::RandomDiscPositionAllocator
    ns3::RandomRectanglePositionAllocator
    ns3::RandomWalk2dMobilityModel
    ns3::RandomWaypointMobilityModel
    ns3::SteadyStateRandomWaypointMobilityModel
    ns3::UniformDiscPositionAllocator
    ns3::WaypointMobilityModel

Then the attributes of a given class; this type of capability will be enabled across the codebase if we set the Group names consistently:

 ./waf --run "third --PrintAttributes=ns3::RandomWalk2dMobilityModel"
Waf: Entering directory `.../ns-3-allinone/ns-3-dev/build'
Waf: Leaving directory `.../ns-3-allinone/ns-3-dev/build'
'build' finished successfully (3.187s)
Attributes for TypeId ns3::RandomWalk2dMobilityModel
    --ns3::RandomWalk2dMobilityModel::Bounds=[0|100|0|100]
        Bounds of the area to cruise.
    --ns3::RandomWalk2dMobilityModel::Direction=[ns3::UniformRandomVariable[Min=0.0|Max=6.283184]]
        A random variable used to pick the direction (radians).
    --ns3::RandomWalk2dMobilityModel::Distance=[1]
        Change current direction and speed after moving for this distance.
    --ns3::RandomWalk2dMobilityModel::Mode=[Distance]
        The mode indicates the condition used to change the current speed and direction
    --ns3::RandomWalk2dMobilityModel::Speed=[ns3::UniformRandomVariable[Min=2.0|Max=4.0]]
        A random variable used to pick the speed (m/s).
    --ns3::RandomWalk2dMobilityModel::Time=[+1000000000.0ns]
        Change current direction and speed after moving for this delay.
  • Tasks: We will organize to group as many TypeIds as possible, across module lines. For instance, someone will be assigned the src/applications module, someone will be assigned the src/propagation model, and so on. When finished or having taken it as far as you can, submit a patch for the module.
  • Patches: We would like code to be sent in unified diff format. An easy way to do this is to use the 'hg diff' command, and redirect the output into a file (and submit the file). For instance, here is the output of 'hg diff' if one line of text is added:
hg diff
diff -r 6ea11eb86c17 src/applications/model/application-packet-probe.cc
--- a/src/applications/model/application-packet-probe.cc	Thu Mar 19 21:13:16 2015 +0100
+++ b/src/applications/model/application-packet-probe.cc	Mon Mar 23 15:44:33 2015 -0700
@@ -39,6 +39,7 @@
 {
   static TypeId tid = TypeId ("ns3::ApplicationPacketProbe")
     .SetParent<Probe> ()
+    .SetGroupName ("Application")
     .AddConstructor<ApplicationPacketProbe> ()
     .AddTraceSource ( "Output",
                       "The packet plus its socket address that serve "

If you type

 hg diff > application.patch

you will store the above in a patch file, which can be submitted.

Please remember that an implementation file (.cc) may contain multiple TypeId declarations, so please search through each file.

  • Outcome: If successful, the PrintGroups command will have many groups defined (one for each module, perhaps more). The tutorial and manual will also be extended to describe how to use this feature.
  • Coordination: We will use IRC and Etherpad to coordinate the work (make sure multiple people do not work on the same file).

Accomplishments

In the March 2015 sprint, we were able to commit about half of the SetGroupName() methods across the codebase. Following the sprint, the remainder of the codebase was handled, so by the ns-3.23 release, this item was completed

Friday December 12, 2014, 14h00-20h00 UTC

Fix as many of the doxygen warnings as we can. A current count of warnings (by module) can be seen here: http://mailman.isi.edu/pipermail/ns-commits/2014-November/015994.html. There is a full log generated that can be used to identify what is the error, and then it can be fixed with a text editor. How this is planned to work is that contributors who show up will choose a file or set of files (that they are comfortable with documenting) and will try to clear the errors in that file, producing a patch that can be merged to ns-3-dev.
We may also work on reducing includes in ns-3.
  • Coordination: We will use IRC and Etherpad to coordinate the work (make sure multiple people do not work on the same file).

Accomplishments

In the December 2014 sprint, we were able to get to zero warnings on the LTE helper directory, and also the mobility model and helper directories. December sprint warnings fixed (Peter, Piotr, Tom):

  • 176 src/mobility/model (all eliminated)
  • 39 src/mobility/helper (all eliminated)
  • 146 src/lte/helper (all eliminated)
  • reduced src/core warnings to below 500 count

October 2014 Doxygen sprint

This was a Doxygen-focused sprint with the following instructions.

  • Use mercurial to check out the current copy of ns-3 (see the tutorial if you don't know how to do this):
  • You must also have Doxygen installed on your machine.

Once you have an ns-3-dev/ directory, take these steps:

   $ ./waf configure --enable-examples --enable-tests
   $ ./waf build

Then, run the script doc/doxygen.warnings.report.sh from the ns-3-dev directory:

 $ ./doc/doxygen.warnings.report.sh -t -e

(Note: this excludes tests and examples; to include warnings for those files, rerun without the -t and -e options). This will produce lots of summary statistics like:

  Warnings by module/directory:
  Count Directory
  ----- ----------------------------------
  3390 src/lte/model
  1532 src/wimax/model
   575 src/core/model
   570 src/wifi/model
   488 src/mesh/model
   338 src/visualizer/visualizer
   229 src/netanim/model
   213 src/dsr/model
   ...
   ... 

Do not worry if the output scrolls beyond the buffer in your terminal window; the full warnings log is written to doc/doxygen.warnings.log.

Once this is complete, you can use the doxygen.warnings.report.sh script to focus on one module or file. To see just the errors from one module, for example wifi:

 $ ./doc/doxygen.warnings.report.sh -t -e -s -m wifi

The -s option skips the doxygen run, and just reports results from the existing warnings log. Obviously, if you want to see the results of your edits, you would omit the -s option so you could regenerate the warnings log. The -m <module> option only shows results from the ./src/<module> module; after printing the warnings counts by file, it shows the actual errors from each file:

 ...
 Filtered Warnings
 ========================================
 src/wifi/helper/athstats-helper.h:49: warning: Member EnableAthstats(std::string filename, uint32_t nodeid, 
 uint32_t deviceid) (function) of class ns3::AthstatsHelper is not documented.
 ...

This means the method AthstatsHelper::EnableAthstats has no documentation, and it's declared in src/wifi/helper/athstats-helper.h around line 49.

To see just the warnings from a single file (or a set of files matching a regular expression) use the -F <file-name-or-regex> option:

 $ ./doc/doxygen.warnings.report.sh -s -F "block-ack.*"


Once you find the list of files and look at the possible errors to fix, feel free to join the chat and request to take a module or file and fix it, and we will list it on the Etherpad as being taken. While all docs are valuable, we should probably focus on code in the model/ directories, then helpers/, examples/, and finally test/.

To add doxygen documentation, please follow the ns-3 Specifics guidelines.

Don't be surprised if you fix one warning and more appear! If a struct, class or function has no documentation, doxygen reports a single "is not documented" error. Once that object has documentation, then doxygen will examine it in detail and report additional warnings. For example, a function with no documentation will generate one warning. Adding documentation about the function itself will fix that warning, but then generate warnings for each of the function parameters and return value, until those are also documented.

Unfortunately, it's not enough just write documentation; you also have to test it. (Documentation has bugs too!) Just rerun the doxygen.warnings.report.sh script without the -s option:

 $ ./doc/doxygen.warnings.report.sh -m <module> # or -F <file-name-or-regex>

(BTW, without -s the script will always build all the doxygen; the -m and -F options only affect what it displays from the resulting doxygen.warnings.log)

Once the script completes, load up the docs in your browser and check that it looks as you intended/you didn't mistype some doxygen syntax:

 $ firefox doc/html/index.html &

As in all code development: wash, rinse, repeat, or, in this case:

 $ ./doc/doxygen.warnings.report.sh -m <module>
 [edit, edit, edit]
 $ firefox doc/html/index.html &


Once you have fixed a file, you may create a patch such as follows:

 $ hg diff file-you-have-fixed.h > file-you-have-fixed.h.patch

and upload it to bug 938 or email it to one of the maintainers participating in the sprint (you can ask on IRC about it).


  • Make sure that you can join the IRC channel in advance
  • Make sure you can checkout the development version of ns-3 (we will use ns-3-dev)
  • Familiarize yourself with how to generate a patch against ns-3-dev. Patches you write can be uploaded to Bugzilla or sent to one of the maintainers.

Accomplishments

In the October 2014 sprint, the following warnings were fixed (Budi, Tiago, Tommaso, Natale, Peter):

  • src/lte warnings count reduced by ~1500
  • src/mobility warnings count reduced by 20
  • all 160 propagation warnings eliminated
  • all 47 point-to-point warnings eliminated
  • all 55 internet warnings eliminated