From 1c5c57ec8e3f285cc81d4ad101edccb82b721beb Mon Sep 17 00:00:00 2001 From: David Brownell Date: Sat, 9 Jan 2010 08:58:38 -0800 Subject: [PATCH] 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 --- TODO | 4 ++ doc/openocd.texi | 4 +- src/flash/nor/at91sam3.c | 25 ++++++----- src/flash/nor/at91sam7.c | 31 ++++++------- src/flash/nor/lpc2900.c | 28 +++++++----- src/flash/nor/stm32x.c | 35 +++++++++------ src/flash/nor/str9x.c | 7 +-- src/flash/nor/tcl.c | 96 ++++++++++++++++++++++------------------ 8 files changed, 131 insertions(+), 99 deletions(-) diff --git a/TODO b/TODO index 73e4aa7b..41d3457a 100644 --- a/TODO +++ b/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) diff --git a/doc/openocd.texi b/doc/openocd.texi index 47951c6d..f8956a31 100644 --- a/doc/openocd.texi +++ b/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). diff --git a/src/flash/nor/at91sam3.c b/src/flash/nor/at91sam3.c index 1194e25f..5dacf6fd 100644 --- a/src/flash/nor/at91sam3.c +++ b/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! @@ -2386,7 +2386,7 @@ COMMAND_HANDLER(sam3_handle_gpnvm_command) if (0 == strcmp("show", CMD_ARGV[0])) { if (who == -1) { - showall: +showall: r = ERROR_OK; for (x = 0 ; x < pChip->details.n_gpnvms ; x++) { r = FLASHD_GetGPNVM(&(pChip->details.bank[0]), x, &v); @@ -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) []]", - .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 = "", - .help = "set the slowclock frequency (default 32768hz)", + .usage = "[clock_hz]", + .help = "Display or set the slowclock frequency " + "(default 32768 Hz).", }, COMMAND_REGISTRATION_DONE }; diff --git a/src/flash/nor/at91sam7.c b/src/flash/nor/at91sam7.c index 97d6b568..cca0cf2c 100644 --- a/src/flash/nor/at91sam7.c +++ b/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 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 }; @@ -1200,15 +1201,15 @@ 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, - }; + .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, +}; diff --git a/src/flash/nor/lpc2900.c b/src/flash/nor/lpc2900.c index 13dd731c..d39b2ddf 100644 --- a/src/flash/nor/lpc2900.c +++ b/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 = "", - .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 = " ", - .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 = " ", - .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 = " []", - .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 = " ", - .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 = " ", - .help = "activate JTAG security", + .usage = "bank_id", + .help = "Disable the JTAG port. " + "It will be effective after a power cycle.", }, COMMAND_REGISTRATION_DONE }; diff --git a/src/flash/nor/stm32x.c b/src/flash/nor/stm32x.c index 9e085767..75dcf3b5 100644 --- a/src/flash/nor/stm32x.c +++ b/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 = "", - .help = "lock device", + .usage = "bank_id", + .help = "Lock entire flash device.", }, { .name = "unlock", .handler = &stm32x_handle_unlock_command, .mode = COMMAND_EXEC, - .usage = "", - .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 = "", - .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 = "", - .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 = " ", - .help = "write device option bytes", + .usage = "bank_id ('SWWDG'|'HWWDG') " + "('RSTSTNDBY'|'NORSTSTNDBY') " + "('RSTSTOP'|'NORSTSTOP')", + .help = "Replace bits in device option byte.", }, COMMAND_REGISTRATION_DONE }; diff --git a/src/flash/nor/str9x.c b/src/flash/nor/str9x.c index 9cddb506..bf3f750f 100644 --- a/src/flash/nor/str9x.c +++ b/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 = " ", + .help = "Configure str9x flash controller, prior to " + "programming the flash.", + .usage = "bank_id BBSR NBBSR BBADR NBBADR", }, COMMAND_REGISTRATION_DONE }; diff --git a/src/flash/nor/tcl.c b/src/flash/nor/tcl.c index ad2b8f11..65523fbe 100644 --- a/src/flash/nor/tcl.c +++ b/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 = "", - .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 = "", - .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 = "", - .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 = "", - .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 = " ", - .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 = "
", - .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 = "
", - .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 = "
", - .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 = "
", - .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 = " ", - .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] [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 = " ", - .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 = " " - " " + .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 }; -- 2.39.5