1.1 --- a/doc/manual/attributes.texi Fri Jul 03 08:26:52 2009 -0700
1.2 +++ b/doc/manual/attributes.texi Fri Aug 07 15:34:45 2009 -0700
1.3 @@ -645,11 +645,11 @@
1.4 found in @code{src/contrib} and not in the main tree. If you like this feature
1.5 and would like to provide feedback on it, please email us.
1.6
1.7 -Values for ns-3 attributes can be stored in an ascii text file and
1.8 +Values for ns-3 attributes can be stored in an ascii or XML text file and
1.9 loaded into a future simulation. This feature is known as the
1.10 ns-3 ConfigStore.
1.11 The ConfigStore code is in @code{src/contrib/}. It is not yet main-tree
1.12 -code, because we are seeking some user feedback.
1.13 +code, because we are seeking some user feedback and experience with this.
1.14
1.15 We can explore this system by using an example. Copy the @code{csma-bridge.cc}
1.16 file to the scratch directory:
1.17 @@ -658,8 +658,8 @@
1.18 ./waf
1.19 @end verbatim
1.20
1.21 -Let's edit it to add the ConfigStore feature. First, add an include statement,
1.22 -and then add these lines:
1.23 +Let's edit it to add the ConfigStore feature. First, add an include statement
1.24 +to include the contrib module, and then add these lines:
1.25
1.26 @verbatim
1.27 #include "contrib-module.h"
1.28 @@ -670,20 +670,43 @@
1.29
1.30 // Invoke just before entering Simulator::Run ()
1.31 ConfigStore config;
1.32 - config.Configure ();
1.33 + config.ConfigureDefaults ();
1.34 + config.ConfigureAttributes ();
1.35
1.36 Simulator::Run ();
1.37 }
1.38 @end verbatim
1.39
1.40 -There is an attribute that governs whether the Configure() call either
1.41 -stores a simulation configuration in a file and exits, or whether
1.42 -it loads a simulation configuration file annd proceeds. First,
1.43 -the @code{LoadFilename} attribute is checked, and if non-empty,
1.44 -the program loads the configuration from the filename provided.
1.45 -If LoadFilename is empty, and if the @code{StoreFilename} attribute is
1.46 -populated, the configuration will be written to the output filename
1.47 -specified.
1.48 +There are three attributes that govern the behavior of the ConfigStore:
1.49 +"Mode", "Filename", and "FileFormat". The Mode (default "None") configures
1.50 +whether ns-3 should load configuration from a previously saved file
1.51 +(specify "Mode=Load") or save it to a file (specify "Mode=Save").
1.52 +The Filename (default "") is where the ConfigStore should store its
1.53 +output data. The FileFormat (default "RawText") governs whether
1.54 +the ConfigStore format is Xml or RawText format.
1.55 +
1.56 +So, using the above modified program, try executing the following
1.57 +waf command and
1.58 +@verbatim
1.59 +./waf --command-template="%s --ns3::ConfigStore::Filename=csma-bridge-config.xml --ns3::ConfigStore::Mode=Save --ns3::ConfigStore::FileFormat=Xml" --run scratch/csma-bridge
1.60 +@end verbatim
1.61 +After running, you can open the csma-bridge-config.xml file and it will
1.62 +display the configuration that was applied to your simulation; e.g.
1.63 +@verbatim
1.64 +<?xml version="1.0" encoding="UTF-8"?>
1.65 +<ns3>
1.66 + <default name="ns3::V4Ping::Remote" value="102.102.102.102"/>
1.67 + <default name="ns3::MsduStandardAggregator::MaxAmsduSize" value="7935"/>
1.68 + <default name="ns3::EdcaTxopN::MinCw" value="31"/>
1.69 + <default name="ns3::EdcaTxopN::MaxCw" value="1023"/>
1.70 + <default name="ns3::EdcaTxopN::Aifsn" value="3"/>
1.71 + <default name="ns3::QstaWifiMac::ProbeRequestTimeout" value="50000000ns"/>
1.72 + <default name="ns3::QstaWifiMac::AssocRequestTimeout" value="500000000ns"/>
1.73 + <default name="ns3::QstaWifiMac::MaxMissedBeacons" value="10"/>
1.74 + <default name="ns3::QstaWifiMac::ActiveProbing" value="false"/>
1.75 +...
1.76 +@end verbatim
1.77 +This file can be archived with your simulation script and output data.
1.78
1.79 While it is possible to generate a sample config file and lightly
1.80 edit it to change a couple of values, there are cases where this
1.81 @@ -697,55 +720,46 @@
1.82 elements to a new configuration file which can then safely
1.83 be edited and loaded in a subsequent simulation run.
1.84
1.85 -So, let's do that as an example. We'lll run the program once
1.86 -to create a configure file, and look at it.
1.87 -If you are running bash shell, the below command should work (which illustrates
1.88 -how to set an attribute from the command line):
1.89 +When the ConfigStore object is instantiated, its attributes Filename,
1.90 +Mode, and FileFormat must be set, either via command-line or via
1.91 +program statements.
1.92 +
1.93 +As a more complicated example, let's assume that we want to
1.94 +read in a configuration of defaults from an input file named
1.95 +"input-defaults.xml", and write out the resulting attributes to a
1.96 +separate file called "output-attributes.xml". (Note-- to get this
1.97 +input xml file to begin with, it is sometimes helpful to run the
1.98 +program to generate an output xml file first, then hand-edit that
1.99 +file and re-input it for the next simulation run).
1.100 @verbatim
1.101 -./build/debug/scratch/csma-bridge --ns3::ConfigStore::StoreFilename=test.config
1.102 -@end verbatim
1.103 -or, if the above does not work (the above requires rpath support), try this:
1.104 -@verbatim
1.105 -./waf --command-template="%s --ns3::ConfigStore::StoreFilename=test.config" --run scratch/csma-bridge
1.106 -@end verbatim
1.107 +#include "contrib-module.h"
1.108 +...
1.109 +int main (...)
1.110 +{
1.111
1.112 -Running the program should yield a "test.config" output configuration file
1.113 -that looks like this:
1.114 -@verbatim
1.115 -/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Addre
1.116 -ss 00:00:00:00:00:01
1.117 -/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Frame
1.118 -Size 1518
1.119 -/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/SendE
1.120 -nable true
1.121 -/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Recei
1.122 -veEnable true
1.123 -/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/TxQue
1.124 -ue/$ns3::DropTailQueue/MaxPackets 100
1.125 -/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Mtu 1
1.126 -500
1.127 -...
1.128 -@end verbatim
1.129 + Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("input-defaults.xml"));
1.130 + Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Load"));
1.131 + Config::SetDefault ("ns3::ConfigStore::FileFormat", StringValue ("Xml"));
1.132 + ConfigStore inputConfig;
1.133 + inputConfig.ConfigureDefaults ();
1.134 +
1.135 + //
1.136 + // Allow the user to override any of the defaults and the above Bind() at
1.137 + // run-time, via command-line arguments
1.138 + //
1.139 + CommandLine cmd;
1.140 + cmd.Parse (argc, argv);
1.141
1.142 -The above lists, for each object in the script topology, the value of each
1.143 -registered attribute. The syntax of this file is that the unique name
1.144 -of the attribute (in the attribute namespace) is specified on each line,
1.145 -followed by a value.
1.146 + // setup topology
1.147 + ...
1.148
1.149 -This file is intended to be a convenient record of the parameters that were
1.150 -used in a given simulation run, and can be stored with simulation
1.151 -output files. Additionally,
1.152 -this file can also be used to parameterize a simulation, instead of
1.153 -editing the script or passing in command line arguments. For instance,
1.154 -a person wanting to run the simulation can examine and tweak the values
1.155 -in a pre-existing configuration file, and pass the file to the
1.156 -program. In this case, the relevant commands are:
1.157 -@verbatim
1.158 -./build/debug/scratch/csma-bridge --ns3::ConfigStore::LoadFilename=test.config
1.159 -@end verbatim
1.160 -or, if the above does not work (the above requires rpath support), try this:
1.161 -@verbatim
1.162 -./waf --command-template="%s --ns3::ConfigStore::LoadFilename=test.config" --run scratch/csma-bridge
1.163 + // Invoke just before entering Simulator::Run ()
1.164 + Config::SetDefault ("ns3::ConfigStore::Filename", StringValue ("output-attributes.xml"));
1.165 + Config::SetDefault ("ns3::ConfigStore::Mode", StringValue ("Save"));
1.166 + ConfigStore outputConfig;
1.167 + outputConfig.ConfigureAttributes ();
1.168 + Simulator::Run ();
1.169 +}
1.170 @end verbatim
1.171
1.172 @subsection GTK-based ConfigStore
1.173 @@ -772,11 +786,13 @@
1.174 In the above example, it was not enabled, so it cannot be used until a
1.175 suitable version is installed and ./waf configure; ./waf is rerun.
1.176
1.177 -Usage is almost the same as the non-GTK-based version:
1.178 +Usage is almost the same as the non-GTK-based version, but there
1.179 +are no ConfigStore attributes involved:
1.180 @verbatim
1.181 // Invoke just before entering Simulator::Run ()
1.182 GtkConfigStore config;
1.183 - config.Configure ();
1.184 + config.ConfigureDefaults ();
1.185 + config.ConfigureAttributes ();
1.186 @end verbatim
1.187
1.188 Now, when you run the script, a GUI should pop up, allowing you to open