src/flash/nor: usage/help/doc updates

Make "usage" messages use the same EBNF as the User's Guide;
no angle brackets.  Improve and correct various helptexts.

Don't use "&function"; a function's name is its address.
Remove a couple instances of pointless whitespace; shrink a
few overlong lines; fix some bad indents.

Add TODO list entry re full support for NAND/NOR bank names.

Signed-off-by: David Brownell <dbrownell@users.sourceforge.net>

TODO

@@ -215,6 +215,10 @@ https://lists.berlios.de/pipermail/openocd-development/2009-October/011506.html
   - NOR flash_write_unlock() does that between sectors
   - there may be other cases too
 
+- Make sure all commands accept either a bank name or a bank number,
+  and be sure both identifiers show up in "flash banks" and "nand list".
+  Right now the user-friendly names are pretty much hidden...
+
 @subsection thelistflashcfi CFI
 
 - finish implementing bus width/chip width handling (suggested by NC)

doc/openocd.texi

@@ -3737,7 +3737,7 @@ see the driver-specific documentation.
 
 @itemize @bullet
 @item @var{name} ... may be used to reference the flash bank
-in other flash commands.
+in other flash commands.  A number is also available.
 @item @var{driver} ... identifies the controller driver
 associated with the flash bank being declared.
 This is usually @code{cfi} for external flash, or else
@@ -4103,7 +4103,7 @@ plane (of up to 256KB), and it will be used automatically when you issue
 @command{flash erase_sector} or @command{flash erase_address} commands.
 
 @deffn Command {at91sam7 gpnvm} bitnum (@option{set}|@option{clear})
-Set or clear a ``General Purpose Non-Volatle Memory'' (GPNVM)
+Set or clear a ``General Purpose Non-Volatile Memory'' (GPNVM)
 bit for the processor.   Each processor has a number of such bits,
 used for controlling features such as brownout detection (so they
 are not truly general purpose).

src/flash/nor/at91sam3.c

@@ -2288,7 +2288,7 @@ COMMAND_HANDLER(sam3_handle_info_command)
 			return ERROR_FAIL;
 		}
 	}
-	// above garentees the "chip details" structure is valid
+	// above guarantees the "chip details" structure is valid
 	// and thus, bank private areas are valid
 	// and we have a SAM3 chip, what a concept!
 
@@ -2466,24 +2466,27 @@ COMMAND_HANDLER(sam3_handle_slowclk_command)
 static const struct command_registration at91sam3_exec_command_handlers[] = {
 	{
 		.name = "gpnvm",
-		.handler = &sam3_handle_gpnvm_command,
+		.handler = sam3_handle_gpnvm_command,
 		.mode = COMMAND_EXEC,
-		.usage = "[(set|clear) [<bit_id>]]",
-		.help = "Without arguments, shows the gpnvm register; "
-			"otherwise, sets or clear the specified bit.",
+		.usage = "[('clr'|'set'|'show') bitnum]",
+		.help = "Without arguments, shows all bits in the gpnvm "
+			"register.  Otherwise, clears, sets, or shows one "
+			"General Purpose Non-Volatile Memory (gpnvm) bit.",
 	},
 	{
 		.name = "info",
-		.handler = &sam3_handle_info_command,
+		.handler = sam3_handle_info_command,
 		.mode = COMMAND_EXEC,
-		.help = "print information about the current sam3 chip",
+		.help = "Print information about the current at91sam3 chip"
+			"and its flash configuration.",
 	},
 	{
 		.name = "slowclk",
-		.handler = &sam3_handle_slowclk_command,
+		.handler = sam3_handle_slowclk_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<value>",
-		.help = "set the slowclock frequency (default 32768hz)",
+		.usage = "[clock_hz]",
+		.help = "Display or set the slowclock frequency "
+			"(default 32768 Hz).",
 	},
 	COMMAND_REGISTRATION_DONE
 };

src/flash/nor/at91sam7.c

@@ -1182,10 +1182,11 @@ COMMAND_HANDLER(at91sam7_handle_gpnvm_command)
 static const struct command_registration at91sam7_exec_command_handlers[] = {
 	{
 		.name = "gpnvm",
-		.handler = &at91sam7_handle_gpnvm_command,
+		.handler = at91sam7_handle_gpnvm_command,
 		.mode = COMMAND_EXEC,
-		.usage = "gpnvm <bit> set | clear, "
-			"set or clear one gpnvm bit",
+		.help = "set or clear one General Purpose Non-Volatile Memory "
+			"(gpnvm) bit",
+		.usage = "bitnum ('set'|'clear')",
 	},
 	COMMAND_REGISTRATION_DONE
 };
@@ -1202,13 +1203,13 @@ static const struct command_registration at91sam7_command_handlers[] = {
 struct flash_driver at91sam7_flash = {
 	.name = "at91sam7",
 	.commands = at91sam7_command_handlers,
-		.flash_bank_command = &at91sam7_flash_bank_command,
-		.erase = &at91sam7_erase,
-		.protect = &at91sam7_protect,
-		.write = &at91sam7_write,
-		.probe = &at91sam7_probe,
-		.auto_probe = &at91sam7_probe,
-		.erase_check = &at91sam7_erase_check,
-		.protect_check = &at91sam7_protect_check,
-		.info = &at91sam7_info,
+	.flash_bank_command = at91sam7_flash_bank_command,
+	.erase = at91sam7_erase,
+	.protect = at91sam7_protect,
+	.write = at91sam7_write,
+	.probe = at91sam7_probe,
+	.auto_probe = at91sam7_probe,
+	.erase_check = at91sam7_erase_check,
+	.protect_check = at91sam7_protect_check,
+	.info = at91sam7_info,
 };

src/flash/nor/lpc2900.c

@@ -953,43 +953,47 @@ static const struct command_registration lpc2900_exec_command_handlers[] = {
 		.name = "signature",
 		.handler = &lpc2900_handle_signature_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "print device signature of flash bank",
+		.usage = "bank_id",
+		.help = "Calculate and display signature of flash bank.",
 	},
 	{
 		.name = "read_custom",
 		.handler = &lpc2900_handle_read_custom_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <filename>",
-		.help = "read customer information from index sector to file",
+		.usage = "bank_id filename",
+		.help = "Copies 912 bytes of customer information "
+			"from index sector into file.",
 	},
 	{
 		.name = "password",
 		.handler = &lpc2900_handle_password_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <password>",
-		.help = "enter password to enable 'dangerous' options",
+		.usage = "bank_id password",
+		.help = "Enter fixed password to enable 'dangerous' options.",
 	},
 	{
 		.name = "write_custom",
 		.handler = &lpc2900_handle_write_custom_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <filename> [<type>]",
-		.help = "write customer info from file to index sector",
+		.usage = "bank_id filename ('bin'|'ihex'|'elf'|'s19')",
+		.help = "Copies 912 bytes of customer info from file "
+			"to index sector.",
 	},
 	{
 		.name = "secure_sector",
 		.handler = &lpc2900_handle_secure_sector_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <first> <last>",
-		.help = "activate sector security for a range of sectors",
+		.usage = "bank_id first_sector last_sector",
+		.help = "Activate sector security for a range of sectors.  "
+			"It will be effective after a power cycle.",
 	},
 	{
 		.name = "secure_jtag",
 		.handler = &lpc2900_handle_secure_jtag_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <level>",
-		.help = "activate JTAG security",
+		.usage = "bank_id",
+		.help = "Disable the JTAG port.  "
+			"It will be effective after a power cycle.",
 	},
 	COMMAND_REGISTRATION_DONE
 };

src/flash/nor/stm32x.c

@@ -1066,29 +1066,36 @@ COMMAND_HANDLER(stm32x_handle_options_write_command)
 		return ERROR_TARGET_NOT_HALTED;
 	}
 
+	/* REVISIT: ignores some options which we will display...
+	 * and doesn't insist on the specified syntax.
+	 */
+
+	/* OPT_RDWDGSW */
 	if (strcmp(CMD_ARGV[1], "SWWDG") == 0)
 	{
 		optionbyte |= (1 << 0);
 	}
-	else
+	else	/* REVISIT must be "HWWDG" then ... */
 	{
 		optionbyte &= ~(1 << 0);
 	}
 
+	/* OPT_RDRSTSTDBY */
 	if (strcmp(CMD_ARGV[2], "NORSTSTNDBY") == 0)
 	{
 		optionbyte |= (1 << 1);
 	}
-	else
+	else	/* REVISIT must be "RSTSTNDBY" then ... */
 	{
 		optionbyte &= ~(1 << 1);
 	}
 
+	/* OPT_RDRSTSTOP */
 	if (strcmp(CMD_ARGV[3], "NORSTSTOP") == 0)
 	{
 		optionbyte |= (1 << 2);
 	}
-	else
+	else	/* REVISIT must be "RSTSTOP" then ... */
 	{
 		optionbyte &= ~(1 << 2);
 	}
@@ -1188,36 +1195,38 @@ static const struct command_registration stm32x_exec_command_handlers[] = {
 		.name = "lock",
 		.handler = &stm32x_handle_lock_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "lock device",
+		.usage = "bank_id",
+		.help = "Lock entire flash device.",
 	},
 	{
 		.name = "unlock",
 		.handler = &stm32x_handle_unlock_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "unlock protected device",
+		.usage = "bank_id",
+		.help = "Unlock entire protected flash device.",
 	},
 	{
 		.name = "mass_erase",
 		.handler = &stm32x_handle_mass_erase_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "mass erase device",
+		.usage = "bank_id",
+		.help = "Erase entire flash device.",
 	},
 	{
 		.name = "options_read",
 		.handler = &stm32x_handle_options_read_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "read device option bytes",
+		.usage = "bank_id",
+		.help = "Read and display device option byte.",
 	},
 	{
 		.name = "options_write",
 		.handler = &stm32x_handle_options_write_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <SWWDG | HWWDG> <RSTSTNDBY | NORSTSTNDBY> <RSTSTOP | NORSTSTOP>",
-		.help = "write device option bytes",
+		.usage = "bank_id ('SWWDG'|'HWWDG') "
+			"('RSTSTNDBY'|'NORSTSTNDBY') "
+			"('RSTSTOP'|'NORSTSTOP')",
+		.help = "Replace bits in device option byte.",
 	},
 	COMMAND_REGISTRATION_DONE
 };

src/flash/nor/str9x.c

@@ -679,11 +679,12 @@ COMMAND_HANDLER(str9x_handle_flash_config_command)
 
 static const struct command_registration str9x_config_command_handlers[] = {
 	{
-		.name = "disable_jtag",
+		.name = "flash_config",
 		.handler = &str9x_handle_flash_config_command,
 		.mode = COMMAND_EXEC,
-		.help = "configure str9x flash controller",
-		.usage = "<bank_id> <BBSR> <NBBSR> <BBADR> <NBBADR>",
+		.help = "Configure str9x flash controller, prior to "
+			"programming the flash.",
+		.usage = "bank_id BBSR NBBSR BBADR NBBADR",
 	},
 	COMMAND_REGISTRATION_DONE
 };

src/flash/nor/tcl.c

@@ -654,89 +654,99 @@ void flash_set_dirty(void)
 static const struct command_registration flash_exec_command_handlers[] = {
 	{
 		.name = "probe",
-		.handler = &handle_flash_probe_command,
+		.handler = handle_flash_probe_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "identify flash bank",
+		.usage = "bank_id",
+		.help = "Identify a flash bank.",
 	},
 	{
 		.name = "info",
-		.handler = &handle_flash_info_command,
+		.handler = handle_flash_info_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "print bank information",
+		.usage = "bank_id",
+		.help = "Print information about a flash bank.",
 	},
 	{
 		.name = "erase_check",
-		.handler = &handle_flash_erase_check_command,
+		.handler = handle_flash_erase_check_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "check erase state of sectors",
+		.usage = "bank_id",
+		.help = "Check erase state of all blocks in a "
+			"flash bank.",
 	},
 	{
 		.name = "protect_check",
-		.handler = &handle_flash_protect_check_command,
+		.handler = handle_flash_protect_check_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "check protection state of sectors",
+		.usage = "bank_id",
+		.help = "Check protection state of all blocks in a "
+			"flash bank.",
 	},
 	{
 		.name = "erase_sector",
-		.handler = &handle_flash_erase_command,
+		.handler = handle_flash_erase_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <first> <last>",
-		.help = "erase sectors",
+		.usage = "bank_id first_sector_num last_sector_num",
+		.help = "Erase a range of sectors in a flash bank.",
 	},
 	{
 		.name = "erase_address",
-		.handler = &handle_flash_erase_address_command,
+		.handler = handle_flash_erase_address_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<address> <length>",
-		.help = "erase address range",
-
+		.usage = "address length",
+		.help = "Erase flash blocks starting at address "
+			"and continuing for length bytes.",
 	},
 	{
 		.name = "fillw",
-		.handler = &handle_flash_fill_command,
+		.handler = handle_flash_fill_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<address> <word_pattern> <count>",
-		.help = "fill with pattern (no autoerase)",
+		.usage = "address value n",
+		.help = "Fill n words with 32-bit value, starting at "
+			"word address.  (No autoerase.)",
 	},
 	{
 		.name = "fillh",
-		.handler = &handle_flash_fill_command,
+		.handler = handle_flash_fill_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<address> <halfword_pattern> <count>",
-		.help = "fill with pattern",
+		.usage = "address value n",
+		.help = "Fill n halfwords with 16-bit value, starting at "
+			"word address.  (No autoerase.)",
 	},
 	{
 		.name = "fillb",
-		.handler = &handle_flash_fill_command,
+		.handler = handle_flash_fill_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<address> <byte_pattern> <count>",
-		.help = "fill with pattern",
-
+		.usage = "address value n",
+		.help = "Fill n bytes with 8-bit value, starting at "
+			"word address.  (No autoerase.)",
 	},
 	{
 		.name = "write_bank",
-		.handler = &handle_flash_write_bank_command,
+		.handler = handle_flash_write_bank_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <file> <offset>",
-		.help = "write binary data",
+		.usage = "bank_id filename offset",
+		.help = "Write binary data from file to flash bank, "
+			"starting at specified byte offset from the "
+			"beginning of the bank.",
 	},
 	{
 		.name = "write_image",
-		.handler = &handle_flash_write_image_command,
+		.handler = handle_flash_write_image_command,
 		.mode = COMMAND_EXEC,
-		.usage = "[erase] [unlock] <file> [offset] [type]",
-		.help = "write an image to flash"
+		.usage = "[erase] [unlock] filename [offset [file_type]]",
+		.help = "Write an image to flash.  Optionally first unprotect "
+			"and/or erase the region to be used.  Allow optional "
+			"offset from beginning of bank (defaults to zero)",
 	},
 	{
 		.name = "protect",
-		.handler = &handle_flash_protect_command,
+		.handler = handle_flash_protect_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <first> <last> <on | off>",
-		.help = "set protection of sectors",
+		.usage = "bank_id first_sector [last_sector|'last'] "
+			"('on'|'off')",
+		.help = "Turn protection on or off for a range of sectors "
+			"in a given flash bank.",
 	},
 	COMMAND_REGISTRATION_DONE
 };
@@ -893,8 +903,8 @@ static const struct command_registration flash_config_command_handlers[] = {
 		.name = "bank",
 		.handler = &handle_flash_bank_command,
 		.mode = COMMAND_CONFIG,
-		.usage = "<name> <driver> <base> <size> "
-			"<chip_width> <bus_width> <target> "
+		.usage = "bank_id driver_name base_address size_bytes "
+			"chip_width_bytes bus_width_bytes target "
 			"[driver_options ...]",
 		.help = "Define a new bank with the given name, "
 			"using the specified NOR flash driver.",
@@ -903,19 +913,19 @@ static const struct command_registration flash_config_command_handlers[] = {
 		.name = "init",
 		.mode = COMMAND_CONFIG,
 		.handler = &handle_flash_init_command,
-		.help = "initialize flash devices",
+		.help = "Initialize flash devices.",
 	},
 	{
 		.name = "banks",
 		.mode = COMMAND_ANY,
 		.handler = &handle_flash_banks_command,
-		.help = "return readable information about the flash banks",
+		.help = "Display table with information about flash banks.",
 	},
 	{
 		.name = "list",
 		.mode = COMMAND_ANY,
 		.jim_handler = &jim_flash_list,
-		.help = "returns a list of details about the flash banks",
+		.help = "Returns a list of details about the flash banks.",
 	},
 	COMMAND_REGISTRATION_DONE
 };