Added command-line help for every ethercat command.
authorFlorian Pose <fp@igh-essen.com>
Wed, 23 Jul 2008 16:16:30 +0000
changeset 1137 a73c0f54be42
parent 1136 a0982873d655
child 1138 4149af40c0e2
Added command-line help for every ethercat command.
TODO
tool/cmd_alias.cpp
tool/cmd_data.cpp
tool/cmd_debug.cpp
tool/cmd_domain.cpp
tool/cmd_download.cpp
tool/cmd_master.cpp
tool/cmd_pdos.cpp
tool/cmd_sdos.cpp
tool/cmd_sii_read.cpp
tool/cmd_sii_write.cpp
tool/cmd_slaves.cpp
tool/cmd_states.cpp
tool/cmd_upload.cpp
tool/cmd_xml.cpp
tool/main.cpp
--- a/TODO	Wed Jul 23 08:06:10 2008 +0000
+++ b/TODO	Wed Jul 23 16:16:30 2008 +0000
@@ -14,7 +14,6 @@
 * Get original driver for r8169.
 * Race in jiffies frame timeout?
 * ethercat tool:
-    - Add help pages for each command.
     - Add -a and -p switches for config command.
     - Show attached slave position.
     - Show Pdos in 'ethercat slave -v'.
--- a/tool/cmd_alias.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_alias.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -21,16 +21,16 @@
     "one or for multiple slaves.\n"
     "\n"
     "Arguments:\n"
-    "  ALIAS must be a 16 bit unsigned integer, specified\n"
-    "        either in decimal (no prefix), octal (prefix '0')\n"
-    "        or hexadecimal (prefix '0x').\n"
+    "  ALIAS must be an unsigned 16 bit number. Zero means no alias.\n"
     "\n"
     "Command-specific options:\n"
-    "  -s <SLAVE>  Write the alias of the slave with the given\n"
-    "              ring position. If this option is not\n"
-    "              specified, the alias of all slaves is set.\n"
-    "              The --force option is required in this\n"
-    "              case.\n";
+    "  --slave -s <index>  Positive numerical ring position, or 'all' for\n"
+    "                      all slaves (default). The --force option is\n"
+    "                      required in this case.\n"
+    "  --force             Acknowledge writing aliases of all slaves.\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /*****************************************************************************/
 
--- a/tool/cmd_data.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_data.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -19,7 +19,10 @@
     "Command-specific options:\n"
     "  --domain -d <index> Positive numerical domain index, or 'all' for\n"
     "                      all domains (default). In this case, data of all\n"
-    "                      domains are concatenated.\n";
+    "                      domains are concatenated.\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 
--- a/tool/cmd_debug.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_debug.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -20,12 +20,13 @@
     "Debug messages are printed to syslog.\n"
     "\n"
     "Arguments:\n"
-    "  LEVEL must be an unsigned integer, specified\n"
-    "        either in decimal (no prefix), octal (prefix '0')\n"
-    "        or hexadecimal (prefix '0x').\n"
-    "        0 stands for no debugging output,\n"
-    "        1 means some debug messages, and\n"
-    "        2 outputs all frame data (use with caution!).\n";
+    "  LEVEL can have one of the following values:\n"
+    "        0 for no debugging output,\n"
+    "        1 for some debug messages, or\n"
+    "        2 for printing all frame contents (use with caution!).\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 
--- a/tool/cmd_domain.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_domain.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -17,7 +17,7 @@
     "\n"
     "Show information about the application's configured domains.\n"
     "\n"
-    "Without the --verbose option, one domain is displayed per line.\n"
+    "Without the --verbose option, the domains are displayed one-per-line.\n"
     "Example:\n"
     "\n"
     "Domain0: LogBaseAddr 0x00000000, Size   6, WorkingCounter 0/1\n"
@@ -36,12 +36,15 @@
     "  SlaveConfig 1001:0, SM3 ( Input), LogAddr 0x00000006, Size 6\n"
     "    00 00 00 00 00 00\n"
     "\n"
-    "The process data are displayed as raw hexadecimal bytes.\n"
+    "The process data are displayed as hexadecimal bytes.\n"
     "\n"
     "Command-specific options:\n"
     "  --domain   -d <index> Positive numerical domain index, or 'all'\n"
     "                        for all domains (default).\n"
-    "  --verbose  -v         Show FMMUs and process data additionally.\n";
+    "  --verbose  -v         Show FMMUs and process data additionally.\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 
--- a/tool/cmd_download.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_download.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -13,12 +13,33 @@
 
 /****************************************************************************/
 
-// FIXME
 const char *help_download =
-    "[OPTIONS]\n"
-    "\n"
-    "\n"
-    "Command-specific options:\n";
+    "[OPTIONS] <INDEX> <SUBINDEX> <VALUE>\n"
+    "\n"
+    "Download an Sdo entry to a slave.\n"
+    "\n"
+    "The data type of the Sdo entry is taken from the Sdo dictionary by\n"
+    "default. It can be overridden with the --type option. If the slave\n"
+    "does not support the Sdo information service or the Sdo is not in the\n"
+    "dictionary, the --type option is mandatory.\n"
+    "\n"
+    "These are the valid Sdo entry data types:\n"
+    "  int8, int16, int32, uint8, uint16, uint32, string.\n"
+    "\n"
+    "Arguments:\n"
+    "  INDEX    is the Sdo index and must be an unsigned 16 bit number.\n"
+    "  SUBINDEX is the Sdo entry subindex and must be an unsigned 8 bit\n"
+    "           number.\n"
+    "  VALUE    is the value to download and must correspond to the Sdo\n"
+    "           entry datatype (see above).\n"
+    "\n"
+    "Command-specific options:\n"
+    "  --slave -s <index>  Positive numerical ring position (mandatory).\n"
+    "  --type  -t <type>   Forced Sdo entry data type (see above).\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
+
 
 /****************************************************************************/
 
--- a/tool/cmd_master.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_master.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -18,7 +18,10 @@
     "Show master and Ethernet device information.\n"
     "\n"
     "Command-specific options:\n"
-    "  --master  -m <master>  Index of the master to use. Default: 0\n";
+    "  --master -m <index>  Index of the master to use. Default: 0.\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 
--- a/tool/cmd_pdos.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_pdos.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -12,12 +12,40 @@
 
 /****************************************************************************/
 
-// FIXME
 const char *help_pdos =
     "[OPTIONS]\n"
     "\n"
+    "Displays sync managers, assigned Pdos and mapped Pdo entries.\n"
     "\n"
-    "Command-specific options:\n";
+    "The information is displayed in three layers, which are indented\n"
+    "accordingly:\n"
+    "\n"
+    "1) Sync managers - Contains the sync manager information from the\n"
+    "   SII: Index, physical start address, default size (raw value from\n"
+    "   the SII), control register and enable word. Example:\n"
+    "\n"
+    "   SM3: PhysAddr 0x1100, DefaultSize 0, ControlRegister 0x20, Enable 1\n"
+    "\n"
+    "2) Assigned Pdos - Pdo direction, hexadecimal index and -if available-\n"
+    "   the Pdo name. Example:\n"
+    "\n"
+    "   TxPdo 0x1a00 \"Channel1\"\n"
+    "\n"
+    "3) Mapped Pdo entries - Pdo entry index and subindex (both\n"
+    "   hexadecimal), the length in bit and -if available- the\n"
+    "   description. Example:\n"
+    "\n"
+    "   Pdo entry 0x3101:01, 8 bit, \"Status\"\n"
+    "\n"
+    "Note, that the displayed Pdo assignment and Pdo mapping information\n"
+    "can either originate from the SII or from the CoE communication area.\n"
+    "\n"
+    "Command-specific options:\n"
+    "  --slave -s <index>  Positive numerical ring position, or 'all' for\n"
+    "                      all slaves (default).\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 	
--- a/tool/cmd_sdos.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_sdos.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -13,12 +13,33 @@
 
 /****************************************************************************/
 
-// FIXME
 const char *help_sdos =
     "[OPTIONS]\n"
     "\n"
+    "Displays the Sdo dictionary with Sdos and Sdo entries.\n"
     "\n"
-    "Command-specific options:\n";
+    "Sdo dictionary information is displayed in two layers, with are\n"
+    "indented accordingly:\n"
+    "\n"
+    "1) Sdos - Hexadecimal Sdo index and the name. Example:\n"
+    "\n"
+    "   Sdo 0x1018, \"Identity object\"\n"
+    "\n"
+    "2) Sdo entries - Sdo index and Sdo entry subindex (both hexadecimal)\n"
+    "   followed by the data type, the length in bit, and the description.\n"
+    "   Example:\n"
+    "\n"
+    "   0x1018:01, uint32, 32 bit, \"Vendor id\"\n"
+    "\n"
+    "If the --quiet option is given, only the Sdos are printed.\n"
+    "\n"
+    "Command-specific options:\n"
+    "  --slave -s <index>  Positive numerical ring position, or 'all' for\n"
+    "                      all slaves (default).\n"
+    "  --quiet -q          Print only Sdos (without Sdo entries).\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 
--- a/tool/cmd_sii_read.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_sii_read.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -12,12 +12,25 @@
 
 /****************************************************************************/
 
-// FIXME
 const char *help_sii_read =
     "[OPTIONS]\n"
     "\n"
+    "Outputs the SII (EEPROM) contents of a slave.\n"
     "\n"
-    "Command-specific options:\n";
+    "Without the --verbose option, binary SII contents are output. They can\n"
+    "be piped to a tool like hexdump, for example:\n"
+    "\n"
+    "  ethercat sii_read -s2 | hexdump -C\n"
+    "\n"
+    "With the --verbose option given, a textual representation of the data\n"
+    "is output, that is separated by SII category names.\n"
+    "\n"
+    "Command-specific options:\n"
+    "  --slave   -s <index>  Positive numerical ring position (mandatory).\n"
+    "  --verbose -v          Output textual data with category names.\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 
--- a/tool/cmd_sii_write.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_sii_write.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -14,12 +14,24 @@
 
 /****************************************************************************/
 
-// FIXME
 const char *help_sii_write =
-    "[OPTIONS]\n"
+    "[OPTIONS] <FILENAME>\n"
     "\n"
+    "Writes SII contents from a local file to a slave.\n"
     "\n"
-    "Command-specific options:\n";
+    "The file contents are checked for validity and integrity. These checks\n"
+    "can be overridden with the --force option.\n"
+    "\n"
+    "Arguments:\n"
+    "  FILENAME must be a path to a file that contains a positive number\n"
+    "           of words.\n"
+    "\n"
+    "Command-specific options:\n"
+    "  --slave -s <index>  Positive numerical ring position (mandatory).\n"
+    "  --force             Override validity checks.\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 
--- a/tool/cmd_slaves.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_slaves.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -13,12 +13,40 @@
 
 /****************************************************************************/
 
-// FIXME
 const char *help_slaves =
     "[OPTIONS]\n"
     "\n"
-    "\n"
-    "Command-specific options:\n";
+    "Display slaves on the bus.\n"
+    "\n"
+    "If the --verbose option is not given, the slaves are displayed\n"
+    "one-per-line. Example:\n"
+    "\n"
+    "1  5555:0  PREOP  +  EL3162 2C. Ana. Input 0-10V\n"
+    "|  |    |  |      |  |\n"
+    "|  |    |  |      |  \\- Name from SII if avaliable, otherwise\n"
+    "|  |    |  |      |     hexadecimal vendor ID and product code\n"
+    "|  |    |  |      |     separated by a colon.\n"
+    "|  |    |  |      \\- Error flag. '+' means no error, 'E' means,\n"
+    "|  |    |  |         that scanning or configuration failed.\n"
+    "|  |    |  \\- Current slave state.\n"
+    "|  |    \\- Relative position (decimal) after the last slave with an\n"
+    "|  |       alias address set.\n"
+    "|  \\- Alias address of the slave (if set to non-zero), or the alias\n"
+    "|     of the last slave with an alias set, or zero if there is none.\n"
+    "\\- Ring position (use this with any --slave option).\n"
+    "\n"
+    "If the --verbose option is given, a detailed (multi-line) description\n"
+    "is output for each slave.\n"
+    "\n"
+    "Command-specific options:\n"
+    "  --slave   -s <index>  Positive numerical ring position, or 'all' for\n"
+    "                        all slaves (default).\n"
+    "  --verbose -v          Show detailed slave information.\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
+
+/****************************************************************************/
 
 void listSlaves(int);
 void showSlave(uint16_t);
--- a/tool/cmd_states.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_states.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -11,12 +11,20 @@
 
 /****************************************************************************/
 
-// FIXME
 const char *help_states =
-    "[OPTIONS]\n"
+    "[OPTIONS] <STATE>\n"
     "\n"
+    "Request an application-layer state change for the specified slaves.\n"
     "\n"
-    "Command-specific options:\n";
+    "Arguments:\n"
+    "  STATE can be 'INIT', 'PREOP', 'SAFEOP', or 'OP'\n"
+    "\n"
+    "Command-specific options:\n"
+    "  --slave -s <index>  Positive numerical ring position, or 'all' for\n"
+    "                      all slaves (default).\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 
--- a/tool/cmd_upload.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_upload.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -13,12 +13,30 @@
 
 /****************************************************************************/
 
-// FIXME
 const char *help_upload =
-    "[OPTIONS]\n"
+    "[OPTIONS] <INDEX> <SUBINDEX>\n"
     "\n"
+    "Upload an Sdo entry from a slave.\n"
     "\n"
-    "Command-specific options:\n";
+    "The data type of the Sdo entry is taken from the Sdo dictionary by\n"
+    "default. It can be overridden with the --type option. If the slave\n"
+    "does not support the Sdo information service or the Sdo is not in the\n"
+    "dictionary, the --type option is mandatory.\n"
+    "\n"
+    "These are the valid Sdo entry data types:\n"
+    "  int8, int16, int32, uint8, uint16, uint32, string.\n"
+    "\n"
+    "Arguments:\n"
+    "  INDEX    is the Sdo index and must be an unsigned 16 bit number.\n"
+    "  SUBINDEX is the Sdo entry subindex and must be an unsigned 8 bit\n"
+    "           number.\n"
+    "\n"
+    "Command-specific options:\n"
+    "  --slave -s <index>  Positive numerical ring position (mandatory).\n"
+    "  --type  -t <type>   Forced Sdo entry data type (see above).\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 
--- a/tool/cmd_xml.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/cmd_xml.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -12,12 +12,21 @@
 
 /****************************************************************************/
 
-// FIXME
 const char *help_xml =
     "[OPTIONS]\n"
     "\n"
+    "Generate slave description XMLs from the master's slave information.\n"
     "\n"
-    "Command-specific options:\n";
+    "Note that the Pdo information can either originate from the SII or\n"
+    "from the CoE communication area. For some slaves, this is dependant on\n"
+    "the last slave configuration.\n"
+    "\n"
+    "Command-specific options:\n"
+    "  --slave -s <index>  Positive numerical ring position, or 'all' for\n"
+    "                      all slaves (default).\n"
+    "\n"
+    "Numerical values can be specified either with decimal (no prefix),\n"
+    "octal (prefix '0') or hexadecimal (prefix '0x') base.\n";
 
 /****************************************************************************/
 
--- a/tool/main.cpp	Wed Jul 23 08:06:10 2008 +0000
+++ b/tool/main.cpp	Wed Jul 23 16:16:30 2008 +0000
@@ -103,8 +103,9 @@
     }
 
     cerr
-        << "Usage: " << binaryBaseName << " <COMMAND> [OPTIONS]" << endl
-		<< "Commands:" << endl;
+        << "Usage: " << binaryBaseName << " <COMMAND> [OPTIONS] [ARGUMENTS]"
+        << endl << endl
+		<< "Commands (can be abbreviated):" << endl;
 
     cerr << left;
     for (cmd = commands; cmd < cmdEnd; cmd++) {
@@ -113,21 +114,22 @@
     }
 
     cerr
-        << "Commands can be abbreviated." << endl
+        << endl
 		<< "Global options:" << endl
-        << "  --master  -m <master>  Index of the master to use. Default: 0"
+        << "  --master  -m <master>  Index of the master to use. Default: 0."
 		<< endl
-        << "  --slave   -s <index>   Positive numerical ring position,"
-        << endl
-        << "                         or 'all' for all slaves (default)."
-        << endl
-        << "  --type    -t <type>    Forced Sdo data type." << endl
-        << "  --force   -f           Force action." << endl
+        << "  --force   -f           Force a command." << endl
         << "  --quiet   -q           Output less information." << endl
         << "  --verbose -v           Output more information." << endl
         << "  --help    -h           Show this help." << endl
+        << endl
+        << "Numerical values can be specified either with decimal "
+        << "(no prefix)," << endl
+        << "octal (prefix '0') or hexadecimal (prefix '0x') base." << endl
+        << endl
         << "Call '" << binaryBaseName
         << " <COMMAND> --help' for command-specific help." << endl
+        << endl
         << "Send bug reports to " << PACKAGE_BUGREPORT << "." << endl;
 }