# HG changeset patch
# User Florian Pose <fp@igh-essen.com>
# Date 1217244568 0
# Node ID 04d1c950cf9db080f0768b6ae8ffbf3ecc370b90
# Parent  ecaf2a896ea36cd15fb680844afe2152ff0932a9
Added --help for alias and position parameters.

diff -r ecaf2a896ea3 -r 04d1c950cf9d TODO
--- a/TODO	Mon Jul 28 09:12:21 2008 +0000
+++ b/TODO	Mon Jul 28 11:29:28 2008 +0000
@@ -14,13 +14,16 @@
 * Get original driver for r8169.
 * Race in jiffies frame timeout?
 * ethercat tool:
-    - Update help for --alias and --position.
     - Show Pdos in 'ethercat slave -v'.
     - Accept files from stdin.
     - Display attached device's MAC address instead of ff's.
     - Data type abbreviations.
     - Add a -n (numeric) switch.
     - Check for options, remove global variables.
+    - Remove MasterDevice::slaveCount().
+    - Alias index?
+    - Add 'etherlab version'.
+    - Remove 'all' parameter values.
 
 Future issues:
 
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/Command.cpp
--- a/tool/Command.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/Command.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -175,7 +175,6 @@
 Command::ConfigList Command::selectedConfigs(MasterDevice &m)
 {
     unsigned int i;
-    int effAlias;
     ec_ioctl_master_t master;
     ec_ioctl_config_t config;
     ConfigList list;
@@ -183,34 +182,35 @@
 
     m.getMaster(&master);
 
-    // Assume alias 0 if only position is given.
-    if (alias == -1 && position != -1) {
-        effAlias = 0;
-    } else {
-        effAlias = alias;
-    }
-
-    if (effAlias == -1) { // no alias given
+    if (alias == -1) { // no alias given
         if (position == -1) { // no alias and position given
             // all items
             for (i = 0; i < master.config_count; i++) {
                 m.getConfig(&config, i);
                 list.push_back(config);
             }
+        } else { // no alias, but position given
+            for (i = 0; i < master.config_count; i++) {
+                m.getConfig(&config, i);
+                if (!config.alias && config.position == position) {
+                    list.push_back(config);
+                    break; // there can be at most one matching
+                }
+            }
         }
     } else { // alias given
         if (position == -1) { // alias, but no position given
             // take all items with a given alias
             for (i = 0; i < master.config_count; i++) {
                 m.getConfig(&config, i);
-                if (config.alias == effAlias) {
+                if (config.alias == alias) {
                     list.push_back(config);
                 }
             }
         } else { // alias and position given
             for (i = 0; i < master.config_count; i++) {
                 m.getConfig(&config, i);
-                if (config.alias == effAlias && config.position == position) {
+                if (config.alias == alias && config.position == position) {
                     list.push_back(config);
                     break; // there can be at most one matching
                 }
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandAlias.cpp
--- a/tool/CommandAlias.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandAlias.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -33,15 +33,16 @@
         << "Arguments:" << endl
         << "  ALIAS must be an unsigned 16 bit number. Zero means" << endl
         << "        removing an alias address." << endl
-        << endl << endl
+        << endl
+        << "If multiple slaves are selected, the --force option" << endl
+        << "is required." << endl
+        << endl
         << "Command-specific options:" << endl
-        << "  --slave -s <index>  Positive numerical ring position, or 'all'"
-        << endl
-        << "                      for all slaves (default). The --force"
-        << endl
-        << "                      option is required in this case." << endl
-        << "  --force -f          Acknowledge writing aliases of all" << endl
-        << "                      slaves." << endl
+        << "  --alias    -a <alias>" << endl
+        << "  --position -p <pos>    Slave selection. See the help of" << endl
+        << "                         the 'slaves' command." << endl
+        << "  --force    -f          Acknowledge writing aliases of" << endl
+        << "                         multiple slaves." << endl
         << endl
         << numericInfo();
 
@@ -85,6 +86,10 @@
         throwCommandException(err);
     }
 
+    if (!slaves.size() && getVerbosity() != Quiet) {
+        cerr << "Warning: Selection matches no slaves!" << endl;
+    }
+
     for (si = slaves.begin(); si != slaves.end(); si++) {
         writeSlaveAlias(m, *si, alias);
     }
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandConfig.cpp
--- a/tool/CommandConfig.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandConfig.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -43,15 +43,33 @@
     	<< "|       |                         position of the attached" << endl
     	<< "|       |                         slave, or '-' if none" << endl
     	<< "|       |                         attached." << endl
-    	<< "|       \\- Vendor ID and product code (both" << endl
+    	<< "|       \\- Expected vendor ID and product code (both" << endl
     	<< "|          hexadecimal)." << endl
-    	<< "\\- Alias and relative position (both decimal)." << endl
+    	<< "\\- Alias address and relative position (both decimal)." << endl
     	<< endl
     	<< "With the --verbose option given, the configured Pdos and" << endl
     	<< "Sdos are output in addition." << endl
+        << endl
+        << "Configuration selection:" << endl
+        << "  Slave configurations can be selected with" << endl
+        << "  the --alias and --position parameters as follows:" << endl
+        << endl
+        << "  1) If neither the --alias nor the --position option" << endl
+        << "     is given, all slave configurations are selected." << endl
+        << "  2) If only the --position option is given, an alias" << endl
+        << "     of zero is assumed (see 4))." << endl
+        << "  3) If only the --alias option is given, all slave" << endl
+        << "     configurations with the given alias address" << endl
+        << "     match." << endl
+        << "  4) If both the --alias and the --position option are" << endl
+        << "     given, the specified configuration is matched." << endl
     	<< endl
     	<< "Command-specific options:" << endl
-    	<< "  --verbose -v  Show detailed configurations." << endl;
+        << "  --alias    -a <alias>  Configuration alias (see above)." << endl
+        << "  --position -p <pos>    Relative position (see above)." << endl
+    	<< "  --verbose  -v          Show detailed configurations." << endl
+        << endl
+        << numericInfo();
 
 	return str.str();
 }
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandDownload.cpp
--- a/tool/CommandDownload.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandDownload.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -28,6 +28,8 @@
     str << getName() << " [OPTIONS] <INDEX> <SUBINDEX> <VALUE>" << endl
     	<< endl
     	<< getBriefDescription() << endl
+        << endl
+        << "This command requires a single slave to be selected." << endl
     	<< endl
     	<< "The data type of the Sdo entry is taken from the Sdo" << endl
 		<< "dictionary by default. It can be overridden with the" << endl
@@ -47,9 +49,10 @@
 		<< "           to the Sdo entry datatype (see above)." << endl
     	<< endl
     	<< "Command-specific options:" << endl
-    	<< "  --slave -s <index>  Positive numerical ring position" << endl
-		<< "                      (mandatory)." << endl
-    	<< "  --type  -t <type>   Sdo entry data type (see above)." << endl
+        << "  --alias    -a <alias>" << endl
+        << "  --position -p <pos>    Slave selection. See the help of" << endl
+        << "                         the 'slaves' command." << endl
+    	<< "  --type     -t <type>   Sdo entry data type (see above)." << endl
     	<< endl
 		<< numericInfo();
 
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandPdos.cpp
--- a/tool/CommandPdos.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandPdos.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -55,8 +55,9 @@
 		<< "CoE communication area." << endl
     	<< endl
     	<< "Command-specific options:" << endl
-    	<< "  --slave -s <index>  Positive numerical ring position," << endl
-    	<< "                      or 'all' for all slaves (default)." << endl
+        << "  --alias    -a <alias>" << endl
+        << "  --position -p <pos>    Slave selection. See the help of" << endl
+        << "                         the 'slaves' command." << endl
     	<< endl
 		<< numericInfo();
 
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandSdos.cpp
--- a/tool/CommandSdos.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandSdos.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -44,10 +44,11 @@
     	<< "If the --quiet option is given, only the Sdos are output."
 		<< endl << endl
     	<< "Command-specific options:" << endl
-    	<< "  --slave -s <index>  Positive numerical ring position," << endl
-		<< "                      or 'all' for all slaves (default)." << endl
-    	<< "  --quiet -q          Only output Sdos (without the Sdo" << endl
-		<< "                      entries)." << endl
+        << "  --alias    -a <alias>" << endl
+        << "  --position -p <pos>    Slave selection. See the help of" << endl
+        << "                         the 'slaves' command." << endl
+    	<< "  --quiet    -q          Only output Sdos (without the" << endl
+		<< "                         Sdo entries)." << endl
     	<< endl
 		<< numericInfo();
 
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandSiiRead.cpp
--- a/tool/CommandSiiRead.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandSiiRead.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -28,6 +28,8 @@
     	<< endl
     	<< getBriefDescription() << endl
     	<< endl
+        << "This command requires a single slave to be selected." << endl
+    	<< endl
     	<< "Without the --verbose option, binary SII contents are" << endl
 		<< "output." << endl
     	<< endl
@@ -36,10 +38,11 @@
 		<< "names." << endl
     	<< endl
     	<< "Command-specific options:" << endl
-    	<< "  --slave   -s <index>  Positive numerical ring position" << endl
-		<< "                        (mandatory)." << endl
-    	<< "  --verbose -v          Output textual data with" << endl
-		<< "                        category names." << endl
+        << "  --alias    -a <alias>" << endl
+        << "  --position -p <pos>    Slave selection. See the help of" << endl
+        << "                         the 'slaves' command." << endl
+    	<< "  --verbose  -v          Output textual data with" << endl
+		<< "                         category names." << endl
     	<< endl
 		<< numericInfo();
 
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandSiiWrite.cpp
--- a/tool/CommandSiiWrite.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandSiiWrite.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -30,6 +30,8 @@
         << endl 
         << getBriefDescription() << endl
         << endl
+        << "This command requires a single slave to be selected." << endl
+    	<< endl
         << "The file contents are checked for validity and integrity." << endl
         << "These checks can be overridden with the --force option." << endl
         << endl
@@ -38,9 +40,10 @@
         << "           positive number of words." << endl
         << endl
         << "Command-specific options:" << endl
-        << "  --slave -s <index>  Positive numerical ring position" << endl
-        << "                      (mandatory)." << endl
-        << "  --force -f          Override validity checks." << endl
+        << "  --alias    -a <alias>" << endl
+        << "  --position -p <pos>    Slave selection. See the help of" << endl
+        << "                         the 'slaves' command." << endl
+        << "  --force    -f          Override validity checks." << endl
         << endl
         << numericInfo();
 
@@ -60,13 +63,6 @@
     uint16_t categoryType, categorySize;
     uint8_t crc;
 
-    slaves = selectedSlaves(m);
-
-    if (slaves.size() != 1) {
-        throwSingleSlaveRequired(slaves.size());
-    }
-    data.slave_position = slaves.front().position;
-
     if (args.size() != 1) {
         err << "'" << getName() << "' takes exactly one argument!";
         throwInvalidUsageException(err);
@@ -131,8 +127,14 @@
         }
     }
 
+    m.open(MasterDevice::ReadWrite);
+    slaves = selectedSlaves(m);
+    if (slaves.size() != 1) {
+        throwSingleSlaveRequired(slaves.size());
+    }
+    data.slave_position = slaves.front().position;
+
     // send data to master
-    m.open(MasterDevice::ReadWrite);
     data.offset = 0;
 	m.writeSii(&data);
 }
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandSlaves.cpp
--- a/tool/CommandSlaves.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandSlaves.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -40,21 +40,39 @@
         << "|  |    |  |         'E' means that scan or" << endl
         << "|  |    |  |         configuration failed." << endl
         << "|  |    |  \\- Current application-layer state." << endl
-        << "|  |    \\- Relative position (decimal) after the last" << endl
+        << "|  |    \\- Decimal relative position to the last" << endl
         << "|  |       slave with an alias address set." << endl
-        << "|  \\- Alias address of the slave (if set), or the alias" << endl
-        << "|     of the last slave with an alias, or zero if not" << endl
-        << "|     applicable" << endl
-        << "\\- Absolute ring position in the bus (use this with any" << endl
-        << "   --slave option)." << endl
+        << "|  \\- Decimal alias address of this slave (if set)," << endl
+        << "|     otherwise of the last slave with an alias set," << endl
+        << "|     or zero, if no alias was encountered up to this" << endl
+        << "|     position." << endl
+        << "\\- Absolute ring position in the bus." << endl
         << endl
         << "If the --verbose option is given, a detailed (multi-line)" << endl
         << "description is output for each slave." << endl
         << endl
+        << "Slave selection:" << endl
+        << "  Slaves for this and other commands can be selected with" << endl
+        << "  the --alias and --position parameters as follows:" << endl
+        << endl
+        << "  1) If neither the --alias nor the --position option" << endl
+        << "     is given, all slaves are selected." << endl
+        << "  2) If only the --position option is given, it is" << endl
+        << "     interpreted as an absolute ring position and" << endl
+        << "     a slave with this position is matched." << endl
+        << "  3) If only the --alias option is given, all slaves" << endl
+        << "     with the given alias address and subsequent" << endl
+        << "     slaves before a slave with a different alias" << endl
+        << "     address match (use -p0 if only the slaves" << endl
+        << "     with the given alias are desired, see 4))." << endl
+        << "  4) If both the --alias and the --position option are" << endl
+        << "     given, the latter is interpreted as relative" << endl
+        << "     position behind any slave with the given alias." << endl
+        << endl
         << "Command-specific options:" << endl
-        << "  --slave   -s <index>  Positive numerical ring position," << endl
-        << "                        or 'all' for all slaves (default)." << endl
-        << "  --verbose -v          Show detailed slave information." << endl
+        << "  --alias    -a <alias>  Slave alias (see above)." << endl
+        << "  --position -p <pos>    Slave position (see above)." << endl
+        << "  --verbose  -v          Show detailed slave information." << endl
         << endl
         << numericInfo();
 
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandStates.cpp
--- a/tool/CommandStates.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandStates.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -30,8 +30,9 @@
         << "  STATE can be 'INIT', 'PREOP', 'SAFEOP', or 'OP'." << endl
         << endl
         << "Command-specific options:" << endl
-        << "  --slave -s <index>  Positive numerical ring position," << endl
-        << "                      or 'all' for all slaves (default)." << endl
+        << "  --alias    -a <alias>" << endl
+        << "  --position -p <pos>    Slave selection. See the help of" << endl
+        << "                         the 'slaves' command." << endl
         << endl
         << numericInfo();
 
@@ -73,6 +74,10 @@
     m.open(MasterDevice::ReadWrite);
     slaves = selectedSlaves(m);
 
+    if (!slaves.size() && getVerbosity() != Quiet) {
+        cerr << "Warning: Selection matches no slaves!" << endl;
+    }
+
     for (si = slaves.begin(); si != slaves.end(); si++) {
         m.requestState(si->position, state);
     }
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandUpload.cpp
--- a/tool/CommandUpload.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandUpload.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -29,6 +29,8 @@
         << endl
         << getBriefDescription() << endl
         << endl
+        << "This command requires a single slave to be selected." << endl
+    	<< endl
         << "The data type of the Sdo entry is taken from the Sdo" << endl
         << "dictionary by default. It can be overridden with the" << endl
         << "--type option. If the slave does not support the Sdo" << endl
@@ -45,9 +47,10 @@
         << "           unsigned 8 bit number." << endl
         << endl
         << "Command-specific options:" << endl
-        << "  --slave -s <index>  Positive numerical ring position" << endl
-        << "                      (mandatory)." << endl
-        << "  --type  -t <type>   Sdo entry data type (see above)." << endl
+        << "  --alias    -a <alias>" << endl
+        << "  --position -p <pos>    Slave selection. See the help of" << endl
+        << "                         the 'slaves' command." << endl
+        << "  --type     -t <type>   Sdo entry data type (see above)." << endl
         << endl
         << numericInfo();
 
diff -r ecaf2a896ea3 -r 04d1c950cf9d tool/CommandXml.cpp
--- a/tool/CommandXml.cpp	Mon Jul 28 09:12:21 2008 +0000
+++ b/tool/CommandXml.cpp	Mon Jul 28 11:29:28 2008 +0000
@@ -33,8 +33,9 @@
         << "mapping, the output depends on the last configuration." << endl
         << endl
         << "Command-specific options:" << endl
-        << "  --slave -s <index>  Positive numerical ring position," << endl
-        << "                      or 'all' for all slaves (default)." << endl
+        << "  --alias    -a <alias>" << endl
+        << "  --position -p <pos>    Slave selection. See the help of" << endl
+        << "                         the 'slaves' command." << endl
         << endl
         << numericInfo();