Browse Source

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>
tags/v0.4.0-rc2
David Brownell 12 years ago
parent
commit
1c5c57ec8e
8 changed files with 131 additions and 99 deletions
  1. +4
    -0
      TODO
  2. +2
    -2
      doc/openocd.texi
  3. +14
    -11
      src/flash/nor/at91sam3.c
  4. +16
    -15
      src/flash/nor/at91sam7.c
  5. +16
    -12
      src/flash/nor/lpc2900.c
  6. +22
    -13
      src/flash/nor/stm32x.c
  7. +4
    -3
      src/flash/nor/str9x.c
  8. +53
    -43
      src/flash/nor/tcl.c

+ 4
- 0
TODO View File

@@ -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)


+ 2
- 2
doc/openocd.texi View File

@@ -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).


+ 14
- 11
src/flash/nor/at91sam3.c View File

@@ -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) [<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
};


+ 16
- 15
src/flash/nor/at91sam7.c View File

@@ -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
};
@@ -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,
};

+ 16
- 12
src/flash/nor/lpc2900.c View File

@@ -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
};


+ 22
- 13
src/flash/nor/stm32x.c View File

@@ -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
};


+ 4
- 3
src/flash/nor/str9x.c View File

@@ -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
};


+ 53
- 43
src/flash/nor/tcl.c View File

@@ -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
};


Loading…
Cancel
Save