NAND: help/usage/doc updates

Usage messages should use the same EBNF as the User's Guide;
no angle brackets.  Be more complete too ... some params were
missing.  Improve and correct various helptexts.

Make user's guide refer to the NAND "driver" name, not the
controller name; that's a bit more precise.

Don't use "&function"; its name is its address.  Line up struct
initializers properly.  Remove some blank lines.

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

doc/openocd.texi

@@ -4673,7 +4673,7 @@ NAND chips must be declared in configuration scripts,
 plus some additional configuration that's done after
 OpenOCD has initialized.
 
-@deffn {Config Command} {nand device} name controller target [configparams...]
+@deffn {Config Command} {nand device} name driver target [configparams...]
 Declares a NAND device, which can be read and written to
 after it has been configured through @command{nand probe}.
 In OpenOCD, devices are single chips; this is unlike some
@@ -4688,8 +4688,8 @@ configuration files, not interactively.
 
 @itemize @bullet
 @item @var{name} ... may be used to reference the NAND bank
-in other commands.
-@item @var{controller} ... identifies the controller driver
+in most other NAND commands.  A number is also available.
+@item @var{driver} ... identifies the NAND controller driver
 associated with the NAND device being declared.
 @xref{NAND Driver List}.
 @item @var{target} ... names the target used when issuing

src/flash/nand/at91sam9.c

@@ -697,28 +697,30 @@ static const struct command_registration at91sam9_sub_command_handlers[] = {
 		.handler = handle_at91sam9_cle_command,
 		.mode = COMMAND_CONFIG,
 		.help = "set command latch enable address line (default is 22)",
-		.usage = "<device_id> <address_line>",
+		.usage = "bank_id address_line",
 	},
 	{
 		.name = "ale",
 		.handler = handle_at91sam9_ale_command,
 		.mode = COMMAND_CONFIG,
 		.help = "set address latch enable address line (default is 21)",
-		.usage = "<device_id> <address_line>",
+		.usage = "bank_id address_line",
 	},
 	{
 		.name = "rdy_busy",
 		.handler = handle_at91sam9_rdy_busy_command,
 		.mode = COMMAND_CONFIG,
-		.help = "set the input pin connected to RDY/~BUSY signal (no default)",
-		.usage = "<device_id> <base_pioc> <pin_num>",
+		.help = "set the GPIO input pin connected to "
+			"the RDY/~BUSY signal (no default)",
+		.usage = "bank_id pio_base_addr pin_num",
 	},
 	{
 		.name = "ce",
 		.handler = handle_at91sam9_ce_command,
 		.mode = COMMAND_CONFIG,
-		.help = "set the output pin connected to chip enable signal (no default)",
-		.usage = "<device_id> <base_pioc> <pin_num>",
+		.help = "set the GPIO output pin connected to "
+			"the chip enable signal (no default)",
+		.usage = "bank_id pio_base_addr pin_num",
 	},
 	COMMAND_REGISTRATION_DONE
 };

src/flash/nand/lpc3180.c

@@ -878,10 +878,10 @@ COMMAND_HANDLER(handle_lpc3180_select_command)
 static const struct command_registration lpc3180_exec_command_handlers[] = {
 	{
 		.name = "select",
-		.handler = &handle_lpc3180_select_command,
+		.handler = handle_lpc3180_select_command,
 		.mode = COMMAND_EXEC,
-		.help = "select <'mlc'|'slc'> controller (default is mlc)",
-		.usage = "<device_id> (mlc|slc)",
+		.help = "select MLC or SLC controller (default is MLC)",
+		.usage = "bank_id ['mlc'|'slc']",
 	},
 	COMMAND_REGISTRATION_DONE
 };
@@ -896,17 +896,17 @@ static const struct command_registration lpc3180_command_handler[] = {
 };
 
 struct nand_flash_controller lpc3180_nand_controller = {
-		.name = "lpc3180",
-		.commands = lpc3180_command_handler,
-		.nand_device_command = lpc3180_nand_device_command,
-		.init = lpc3180_init,
-		.reset = lpc3180_reset,
-		.command = lpc3180_command,
-		.address = lpc3180_address,
-		.write_data = lpc3180_write_data,
-		.read_data = lpc3180_read_data,
-		.write_page = lpc3180_write_page,
-		.read_page = lpc3180_read_page,
-		.controller_ready = lpc3180_controller_ready,
-		.nand_ready = lpc3180_nand_ready,
-	};
+	.name = "lpc3180",
+	.commands = lpc3180_command_handler,
+	.nand_device_command = lpc3180_nand_device_command,
+	.init = lpc3180_init,
+	.reset = lpc3180_reset,
+	.command = lpc3180_command,
+	.address = lpc3180_address,
+	.write_data = lpc3180_write_data,
+	.read_data = lpc3180_read_data,
+	.write_page = lpc3180_write_page,
+	.read_page = lpc3180_read_page,
+	.controller_ready = lpc3180_controller_ready,
+	.nand_ready = lpc3180_nand_ready,
+};

src/flash/nand/tcl.c

@@ -446,68 +446,67 @@ COMMAND_HANDLER(handle_nand_raw_access_command)
 static const struct command_registration nand_exec_command_handlers[] = {
 	{
 		.name = "list",
-		.handler = &handle_nand_list_command,
+		.handler = handle_nand_list_command,
 		.mode = COMMAND_EXEC,
 		.help = "list configured NAND flash devices",
 	},
 	{
 		.name = "info",
-		.handler = &handle_nand_info_command,
+		.handler = handle_nand_info_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "print info about a NAND flash device",
+		.usage = "[banknum | first_bank_num last_bank_num]",
+		.help = "print info about one or more NAND flash devices",
 	},
 	{
 		.name = "probe",
-		.handler = &handle_nand_probe_command,
+		.handler = handle_nand_probe_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank>",
-		.help = "identify NAND flash device <num>",
-
+		.usage = "bank_id",
+		.help = "identify NAND flash device",
 	},
 	{
 		.name = "check_bad_blocks",
-		.handler = &handle_nand_check_bad_blocks_command,
+		.handler = handle_nand_check_bad_blocks_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> [<offset> <length>]",
-		.help = "check NAND flash device <num> for bad blocks",
+		.usage = "bank_id [offset length]",
+		.help = "check all or part of NAND flash device for bad blocks",
 	},
 	{
 		.name = "erase",
-		.handler = &handle_nand_erase_command,
+		.handler = handle_nand_erase_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> [<offset> <length>]",
-		.help = "erase blocks on NAND flash device",
+		.usage = "bank_id [offset length]",
+		.help = "erase all or subset of blocks on NAND flash device",
 	},
 	{
 		.name = "dump",
-		.handler = &handle_nand_dump_command,
+		.handler = handle_nand_dump_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <filename> <offset> <length> "
-			"[oob_raw | oob_only]",
+		.usage = "bank_id filename offset length "
+			"['oob_raw'|'oob_only']",
 		.help = "dump from NAND flash device",
 	},
 	{
 		.name = "verify",
-		.handler = &handle_nand_verify_command,
+		.handler = handle_nand_verify_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <filename> <offset> "
-			"[oob_raw | oob_only | oob_softecc | oob_softecc_kw]",
+		.usage = "bank_id filename offset "
+			"['oob_raw'|'oob_only'|'oob_softecc'|'oob_softecc_kw']",
 		.help = "verify NAND flash device",
 	},
 	{
 		.name = "write",
-		.handler = &handle_nand_write_command,
+		.handler = handle_nand_write_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<bank> <filename> <offset> "
-			"[oob_raw | oob_only | oob_softecc | oob_softecc_kw]",
+		.usage = "bank_id filename offset "
+			"['oob_raw'|'oob_only'|'oob_softecc'|'oob_softecc_kw']",
 		.help = "write to NAND flash device",
 	},
 	{
 		.name = "raw_access",
-		.handler = &handle_nand_raw_access_command,
+		.handler = handle_nand_raw_access_command,
 		.mode = COMMAND_EXEC,
-		.usage = "<num> ['enable'|'disable']",
+		.usage = "bank_id ['enable'|'disable']",
 		.help = "raw access to NAND flash device",
 	},
 	COMMAND_REGISTRATION_DONE
@@ -614,6 +613,7 @@ static const struct command_registration nand_config_command_handlers[] = {
 		.handler = &handle_nand_device_command,
 		.mode = COMMAND_CONFIG,
 		.help = "defines a new NAND bank",
+		.usage = "bank_id driver target [driver_options ...]",
 	},
 	{
 		.name = "drivers",