From 7f0c3ec56b794313b8d23346f8b75bee711c739d Mon Sep 17 00:00:00 2001 From: Michael Karcher Date: Sun, 7 Mar 2010 22:29:28 +0000 Subject: [PATCH] Move untested board enable documentation to manpage This also checks the testedness of boards in all cases, not just for PCI/DMI detection. Corresponding to flashrom svn r926. Signed-off-by: Michael Karcher Acked-by: Carl-Daniel Hailfinger --- board_enable.c | 41 +++++++++++++++++------------------------ flashrom.8 | 41 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 24 deletions(-) diff --git a/board_enable.c b/board_enable.c index 7a34eb1f2..4107411e7 100644 --- a/board_enable.c +++ b/board_enable.c @@ -1425,30 +1425,6 @@ static struct board_pciid_enable *board_match_pci_card_ids(void) } } - if (board->status == NT) { - if (!force_boardenable) - { - printf("WARNING: Your mainboard is %s %s, but the mainboard-specific\n" - "code has not been marked as working. To help flashrom development, please\n" - "test flashrom on your board. As the code to support your board is untested,\n" - "we strongly recommend that as an additional safety measure you make\n" - "store backup of your current ROM contents (obtained by flashrom -r) on\n" - "a medium that can be accessed from a different computer (like an USB\n" - "drive or a network share of another system) before you try to erase or\n" - "write.\n" - "The untested code does not run unless you specify the\n" - " \"-p internal:boardenable=force\" command line option. Depending on your\n" - "hardware environment, erasing, writing or even probing can fail without\n" - "running the board specific code. Running the board-specific code might\n" - "cause your computer to behave erratically if it is wrong.\n" - "Please report the results of running the board enable code to\n" - "flashrom@flashrom.org.\n", - board->vendor_name, board->board_name); - continue; - } - printf("NOTE: Running an untested board enable procedure.\n" - "Please report success/failure to flashrom@flashrom.org\n"); - } return board; } @@ -1466,6 +1442,23 @@ int board_flash_enable(const char *vendor, const char *part) if (!board) board = board_match_pci_card_ids(); + if (board->status == NT) { + if (!force_boardenable) + { + printf("WARNING: Your mainboard is %s %s, but the mainboard-specific\n" + "code has not been tested, and thus will not not be executed by default.\n" + "Depending on your hardware environment, erasing, writing or even probing\n" + "can fail without running the board specific code.\n\n" + "Please see the man page (section PROGRAMMER SPECIFIC INFO, subsection\n" + "\"internal programmer\") for details\n", + board->vendor_name, board->board_name); + board = NULL; + } + else + printf("NOTE: Running an untested board enable procedure.\n" + "Please report success/failure to flashrom@flashrom.org\n"); + } + if (board) { if (board->max_rom_decode_parallel) max_rom_decode.parallel = diff --git a/flashrom.8 b/flashrom.8 index 696aba2f1..9c212783f 100644 --- a/flashrom.8 +++ b/flashrom.8 @@ -175,6 +175,47 @@ colon. While some programmers take arguments at fixed positions, other programmers use a key/value interface in which the key and value is separated by an equal sign and different pairs are separated by a comma or a colon. .TP +.BR "internal " programmer +Some mainboards require to run mainboard specific code to enable flash erase +and write support (and probe support on old systems with parallel flash). +The mainboard brand and model (if it requires specific code) is usually +autodetected using one of the following mechanisms: If your system is +running coreboot, the mainboard type is determined from the coreboot table, +otherwise, the mainboard is detected by examining the onboard PCI devices +and possibly DMI info. If PCI and DMI do not contain information to uniquely +identify the mainboard (which is the exception), it might be necessary to +specify the mainboard using the \-m switch (see above). +.sp +Some of these board-specific flash enabling functions (called board enables) +in flashrom have not yet been tested. If your mainboard is detected needing +an untested board enable function, a warning message is printed and the +board enable is not executed, because a wrong board enable function might +cause the system to behave erratically, as board enable functions touch the +low-level internals of a mainboard. Not executing a board enable function +(if one is needed) might cause detection or erasing failure. If your board +protects only part of the flash (commonly the top end, called boot block), +flashrom might encounter an error only after erasing the unprotected part, +so running without the board-enable function might be dangerous for erase +and write (which includes erase). +.sp +The suggested procedure for a mainboard with untested board specific code is +to first try to probe the ROM (just invoke flashrom and check that it +detects your flash chip type) without running the board enable code (i.e. +without any parameters). If it finds your chip, fine, otherwise, retry +probing your chip with the board-enable code running, using +.sp +.B "flashrom -p internal:boardenable=force" +.sp +If your chip is still not detected, the board enable code seems to be broken +or the flash chip unsupported. Otherwise, make a backup of your current ROM +contents (using \-r) and store it to a medium outside of your computer, like +an USB drive or a network share. If you needed to run the board enable code +already for probing, use it for reading too. Now you can try to write the +new image. You should enable the board enable code in any case now, as it +has been written because it is known that writing/erasing without the board +enable is going to fail. In any case (success or failure), please report to +the flashrom mailing list, see below. +.sp .BR "dummy " programmer An optional parameter specifies the bus types it should support. For that you have to use the