Man page fixes: - Add dummy programmer flash chip emulation - Add satamv programmer - Merge it87spi programmer into internal section - Correct formatting of pci= parameter
Signed-off-by: Carl-Daniel Hailfinger c-d.hailfinger.devel.2006@gmx.net
Index: flashrom-manpage_dummy_satamv_it87spi/flashrom.8 =================================================================== --- flashrom-manpage_dummy_satamv_it87spi/flashrom.8 (Revision 1380) +++ flashrom-manpage_dummy_satamv_it87spi/flashrom.8 (Arbeitskopie) @@ -168,7 +168,7 @@ .sp .BR "* internal" " (default, for in-system flashing in the mainboard)" .sp -.BR "* dummy" " (just prints all operations and accesses)" +.BR "* dummy" " (prints all operations and accesses, can emulate flash chips)" .sp .BR "* nic3com" " (for flash ROMs on 3COM network cards)" .sp @@ -192,9 +192,6 @@ .sp .BR "* atahpt" " (for flash ROMs on Highpoint ATA/RAID controllers)" .sp -.BR "* it87spi" " (for flash ROMs behind an ITE IT87xx Super I/O LPC/SPI \ -translation unit)" -.sp .BR "* ft2232_spi" " (for SPI flash ROMs attached to an FT2232/FT4232H family \ based USB SPI programmer)" .sp @@ -286,17 +283,17 @@ .B " flashrom -p internal:boardmismatch=force" .sp If your mainboard uses an ITE IT87 series Super I/O for LPC<->SPI flash bus -translation, flashrom should autodetect that configuration. You can use the +translation, flashrom should autodetect that configuration. If you want to +set the I/O base port of the IT87 series SPI controller manually instead of +using the value provided by the BIOS, use the .sp .B " flashrom -p internal:it87spiport=portnum" .sp -syntax as explained in the -.B it87spi -programmer section to use a non-default port for controlling the IT87 series -Super I/O. In the unlikely case flashrom doesn't detect an active -IT87 LPC<->SPI bridge, you can try to force recognition by using the -.B it87spi -programmer. +syntax where +.B portnum +is the I/O port number (must be a multiple of 8). In the unlikely case +flashrom doesn't detect an active IT87 LPC<->SPI bridge, please send a bug +report so we can diagnose the problem. .sp Using flashrom on laptops is dangerous and may easily make your hardware unusable (see also the @@ -322,7 +319,9 @@ .BR "dummy " programmer An optional parameter specifies the bus types it should support. For that you have to use the -.B "flashrom -p dummy:bus=[type[+type[+type]]]" +.sp +.B " flashrom -p dummy:bus=[type[+type[+type]]]" +.sp syntax where .B type can be @@ -332,6 +331,51 @@ .sp Example: .B "flashrom -p dummy:bus=lpc+fwh" +.sp +The dummy programmer supports flash chip emulation for automated self-tests +without hardware access. If you want to emulate a flash chip, use the +.sp +.B " flashrom -p dummy:emulate=chip" +.sp +syntax where +.B chip +is one of the following chips (please specify only the chip name, not the +vendor): +.sp +.RB "* ST " M25P10.RES " SPI flash chip (RES, page write)" +.sp +.RB "* SST " SST25VF040.REMS " SPI flash chip (REMS, byte write)" +.sp +.RB "* SST " SST25VF032B " SPI flash chip (RDID, AAI write)" +.sp +Example: +.B "flashrom -p dummy:emulate=SST25VF040.REMS" +.sp +If you use flash chip emulation, flash image persistence is available as well +by using the +.sp +.B " flashrom -p dummy:emulate=chip,image=image.rom" +.sp +syntax where +.B image.rom +is the file where the simulated chip contents are read on flashrom startup and +where the chip contents on flashrom shutdown are written to. +.sp +Example: +.B "flashrom -p dummy:emulate=M25P10.RES,image=dummy.bin" +.sp +If you use SPI flash chip emulation for a chip which supports SPI page write +with the default opcode, you can set the maximum allowed write chunk size with +the +.sp +.B " flashrom -p dummy:emulate=chip,spi_write_256_chunksize=size" +.sp +syntax where +.B size +is the number of bytes (min. 1, max. 256). +.sp +Example: +.B "flashrom -p dummy:emulate=M25P10.RES,spi_write_256_chunksize=5" .TP .BR "nic3com" , " nicrealtek" , " nicsmc1211" , " nicnatsemi" , " nicintel\ " , " nicintel_spi" , " gfxnvidia" , " ogp_spi" , " drkaiser" , " satasii\ @@ -339,7 +383,9 @@ These programmers have an option to specify the PCI address of the card your want to use, which must be specified if more than one card supported by the selected programmer is installed in your system. The syntax is -.BR "flashrom -p xxxx:pci=bb:dd.f" , +.sp +.BR " flashrom -p xxxx:pci=bb:dd.f" , +.sp where .B xxxx is the name of the programmer @@ -353,19 +399,6 @@ Example: .B "flashrom -p nic3com:pci=05:04.0" .TP -.BR "it87spi " programmer -An optional -.B it87spiport -parameter sets the I/O base port of the IT87 series SPI controller -interface to the port specified in the parameter instead of using the port -address set by the BIOS. For that you have to use the -.sp -.B " flashrom -p it87spi:it87spiport=portnum" -.sp -syntax where -.B portnum -is an I/O port number which must be a multiple of 8. -.TP .BR "ft2232_spi " programmer An optional parameter specifies the controller type and interface/port it should support. For that you have to use the @@ -487,9 +520,6 @@ needs raw memory access, PCI configuration space access, raw I/O port access (x86) and MSR access (x86). .sp -.B it87spi -needs raw I/O port access (x86). -.sp .BR nic3com ", " nicrealtek ", " nicsmc1211 " and " nicnatsemi " need PCI configuration space read access and raw I/O port access. .sp @@ -505,6 +535,10 @@ .B satasii needs PCI configuration space read access and raw memory access. .sp +.B satamv +needs PCI configuration space read access, raw I/O port access and raw memory +access. +.sp .B serprog needs TCP access to the network or userspace access to a serial port. .sp @@ -517,8 +551,8 @@ .B dummy needs no access permissions at all. .sp -.BR internal ", " it87spi ", " nic3com ", " nicrealtek ", " nicsmc1211 ", " -.BR nicnatsemi ", " "gfxnvidia" ", " drkaiser ", " satasii " and " atahpt +.BR internal ", " nic3com ", " nicrealtek ", " nicsmc1211 ", " nicnatsemi ", " +.BR gfxnvidia" ", " drkaiser ", " satasii ", " satamv " and " atahpt have to be run as superuser/root, and need additional raw access permission. .sp .BR serprog ", " buspirate_spi ", " dediprog " and " ft2232_spi
On Sat, 23 Jul 2011 00:58:03 +0200 Carl-Daniel Hailfinger c-d.hailfinger.devel.2006@gmx.net wrote:
Man page fixes:
- Add dummy programmer flash chip emulation
- Add satamv programmer
- Merge it87spi programmer into internal section
- Correct formatting of pci= parameter
i have started working on a similar patch yesterday that has become almost obsolete by yours (mine describes my -p dummy:content=pattern too). maybe you find some phrases or ideas useful and want to incorporate them. what i miss a bit in the programmers section in the manpage is a general description of the programmers. a sentence at the start of each of flashrom's programmers should be added to give a short overview imho.
i will merge the content=pattern part of my patch below with the corresponding implementation.
flashrom.8: improve dummy programmer documentation
describe emulate and content parameters
Signed-off-by: Stefan Tauner stefan.tauner@student.tuwien.ac.at --- flashrom.8 | 25 ++++++++++++++++++++++++- 1 files changed, 24 insertions(+), 1 deletions(-)
diff --git a/flashrom.8 b/flashrom.8 index 941a424..ccf3670 100644 --- a/flashrom.8 +++ b/flashrom.8 @@ -168,7 +168,7 @@ Specify the programmer device. Currently supported are: .sp .BR "* internal" " (default, for in-system flashing in the mainboard)" .sp -.BR "* dummy" " (just prints all operations and accesses)" +.BR "* dummy" " (a virtual programmer that can be used for testing flashrom)" .sp .BR "* nic3com" " (for flash ROMs on 3COM network cards)" .sp @@ -320,6 +320,29 @@ We will not help you if you force flashing on a laptop because this is a really dumb idea. .TP .BR "dummy " programmer +The dummy programmer operates on a buffer in memory only. It provides a safe and +fast way to test various aspects of flashrom and is mainly used in development +and while debugging. +.sp +It is able to emulate some chips to a certain degree (e.g. timing variations +are not considered). The syntax to tell flashrom the chip to emulate is: +.sp +.B " flashrom -p dummy:emulate=chipname" +.sp +where chipname can be +.BR M25P10.RES ", " SST25VF040.REMS " or " SST25VF032B "." +.sp +Its buffer is initialized with random data by default. This behavior is +configurable using the +.sp +.B " flashrom -p dummy:content=pattern" +.sp +syntax where pattern can be +.BR "random" " (the default), " "ones" " (all 0xff; this was the behavior in \ +previous versions), " "zeros" " (all 0x00) or " "increment" " (First byte \ +0x00, second byte 0x01, ..., 255th byte 0xff, 256th byte 0x00, ...)." + +.sp An optional parameter specifies the bus types it should support. For that you have to use the .B "flashrom -p dummy:bus=[type[+type[+type]]]"
Am 23.07.2011 15:45 schrieb Stefan Tauner:
On Sat, 23 Jul 2011 00:58:03 +0200 Carl-Daniel Hailfinger c-d.hailfinger.devel.2006@gmx.net wrote:
Man page fixes:
- Add dummy programmer flash chip emulation
- Add satamv programmer
- Merge it87spi programmer into internal section
- Correct formatting of pci= parameter
i have started working on a similar patch yesterday that has become almost obsolete by yours (mine describes my -p dummy:content=pattern too). maybe you find some phrases or ideas useful and want to incorporate them. what i miss a bit in the programmers section in the manpage is a general description of the programmers. a sentence at the start of each of flashrom's programmers should be added to give a short overview imho.
i will merge the content=pattern part of my patch below with the corresponding implementation.
flashrom.8: improve dummy programmer documentation
describe emulate and content parameters
Signed-off-by: Stefan Tauner stefan.tauner@student.tuwien.ac.at
Thanks, I have merged this with small modifications:
Man page fixes: - Finish dummy programmer description - Add satamv programmer - Merge it87spi programmer into internal section - Correct formatting of pci= parameter
Signed-off-by: Carl-Daniel Hailfinger c-d.hailfinger.devel.2006@gmx.net
Index: flashrom-manpage_dummy_satamv_it87spi/flashrom.8 =================================================================== --- flashrom-manpage_dummy_satamv_it87spi/flashrom.8 (Revision 1380) +++ flashrom-manpage_dummy_satamv_it87spi/flashrom.8 (Arbeitskopie) @@ -168,7 +168,7 @@ .sp .BR "* internal" " (default, for in-system flashing in the mainboard)" .sp -.BR "* dummy" " (just prints all operations and accesses)" +.BR "* dummy" " (virtual programmer for testing flashrom)" .sp .BR "* nic3com" " (for flash ROMs on 3COM network cards)" .sp @@ -192,9 +192,6 @@ .sp .BR "* atahpt" " (for flash ROMs on Highpoint ATA/RAID controllers)" .sp -.BR "* it87spi" " (for flash ROMs behind an ITE IT87xx Super I/O LPC/SPI \ -translation unit)" -.sp .BR "* ft2232_spi" " (for SPI flash ROMs attached to an FT2232/FT4232H family \ based USB SPI programmer)" .sp @@ -286,17 +283,17 @@ .B " flashrom -p internal:boardmismatch=force" .sp If your mainboard uses an ITE IT87 series Super I/O for LPC<->SPI flash bus -translation, flashrom should autodetect that configuration. You can use the +translation, flashrom should autodetect that configuration. If you want to +set the I/O base port of the IT87 series SPI controller manually instead of +using the value provided by the BIOS, use the .sp .B " flashrom -p internal:it87spiport=portnum" .sp -syntax as explained in the -.B it87spi -programmer section to use a non-default port for controlling the IT87 series -Super I/O. In the unlikely case flashrom doesn't detect an active -IT87 LPC<->SPI bridge, you can try to force recognition by using the -.B it87spi -programmer. +syntax where +.B portnum +is the I/O port number (must be a multiple of 8). In the unlikely case +flashrom doesn't detect an active IT87 LPC<->SPI bridge, please send a bug +report so we can diagnose the problem. .sp Using flashrom on laptops is dangerous and may easily make your hardware unusable (see also the @@ -320,9 +317,18 @@ dumb idea. .TP .BR "dummy " programmer +The dummy programmer operates on a buffer in memory only. It provides a safe and +fast way to test various aspects of flashrom and is mainly used in development +and while debugging. +.sp +It is able to emulate some chips to a certain degree (basic identify/read/write +operations work). +.sp An optional parameter specifies the bus types it should support. For that you have to use the -.B "flashrom -p dummy:bus=[type[+type[+type]]]" +.sp +.B " flashrom -p dummy:bus=[type[+type[+type]]]" +.sp syntax where .B type can be @@ -332,6 +338,51 @@ .sp Example: .B "flashrom -p dummy:bus=lpc+fwh" +.sp +The dummy programmer supports flash chip emulation for automated self-tests +without hardware access. If you want to emulate a flash chip, use the +.sp +.B " flashrom -p dummy:emulate=chip" +.sp +syntax where +.B chip +is one of the following chips (please specify only the chip name, not the +vendor): +.sp +.RB "* ST " M25P10.RES " SPI flash chip (RES, page write)" +.sp +.RB "* SST " SST25VF040.REMS " SPI flash chip (REMS, byte write)" +.sp +.RB "* SST " SST25VF032B " SPI flash chip (RDID, AAI write)" +.sp +Example: +.B "flashrom -p dummy:emulate=SST25VF040.REMS" +.sp +If you use flash chip emulation, flash image persistence is available as well +by using the +.sp +.B " flashrom -p dummy:emulate=chip,image=image.rom" +.sp +syntax where +.B image.rom +is the file where the simulated chip contents are read on flashrom startup and +where the chip contents on flashrom shutdown are written to. +.sp +Example: +.B "flashrom -p dummy:emulate=M25P10.RES,image=dummy.bin" +.sp +If you use SPI flash chip emulation for a chip which supports SPI page write +with the default opcode, you can set the maximum allowed write chunk size with +the +.sp +.B " flashrom -p dummy:emulate=chip,spi_write_256_chunksize=size" +.sp +syntax where +.B size +is the number of bytes (min. 1, max. 256). +.sp +Example: +.B "flashrom -p dummy:emulate=M25P10.RES,spi_write_256_chunksize=5" .TP .BR "nic3com" , " nicrealtek" , " nicsmc1211" , " nicnatsemi" , " nicintel\ " , " nicintel_spi" , " gfxnvidia" , " ogp_spi" , " drkaiser" , " satasii\ @@ -339,7 +390,9 @@ These programmers have an option to specify the PCI address of the card your want to use, which must be specified if more than one card supported by the selected programmer is installed in your system. The syntax is -.BR "flashrom -p xxxx:pci=bb:dd.f" , +.sp +.BR " flashrom -p xxxx:pci=bb:dd.f" , +.sp where .B xxxx is the name of the programmer @@ -353,19 +406,6 @@ Example: .B "flashrom -p nic3com:pci=05:04.0" .TP -.BR "it87spi " programmer -An optional -.B it87spiport -parameter sets the I/O base port of the IT87 series SPI controller -interface to the port specified in the parameter instead of using the port -address set by the BIOS. For that you have to use the -.sp -.B " flashrom -p it87spi:it87spiport=portnum" -.sp -syntax where -.B portnum -is an I/O port number which must be a multiple of 8. -.TP .BR "ft2232_spi " programmer An optional parameter specifies the controller type and interface/port it should support. For that you have to use the @@ -487,9 +527,6 @@ needs raw memory access, PCI configuration space access, raw I/O port access (x86) and MSR access (x86). .sp -.B it87spi -needs raw I/O port access (x86). -.sp .BR nic3com ", " nicrealtek ", " nicsmc1211 " and " nicnatsemi " need PCI configuration space read access and raw I/O port access. .sp @@ -505,6 +542,10 @@ .B satasii needs PCI configuration space read access and raw memory access. .sp +.B satamv +needs PCI configuration space read access, raw I/O port access and raw memory +access. +.sp .B serprog needs TCP access to the network or userspace access to a serial port. .sp @@ -517,8 +558,8 @@ .B dummy needs no access permissions at all. .sp -.BR internal ", " it87spi ", " nic3com ", " nicrealtek ", " nicsmc1211 ", " -.BR nicnatsemi ", " "gfxnvidia" ", " drkaiser ", " satasii " and " atahpt +.BR internal ", " nic3com ", " nicrealtek ", " nicsmc1211 ", " nicnatsemi ", " +.BR gfxnvidia" ", " drkaiser ", " satasii ", " satamv " and " atahpt have to be run as superuser/root, and need additional raw access permission. .sp .BR serprog ", " buspirate_spi ", " dediprog " and " ft2232_spi
On Sun, Jul 24, 2011 at 01:21:42AM +0200, Carl-Daniel Hailfinger wrote:
+The dummy programmer operates on a buffer in memory only. It provides a safe and +fast way to test various aspects of flashrom and is mainly used in development +and while debugging.
Minor issue, but the "and" could be in the next line, it ends exactly on column 80, which makes the line look a bit "crowded" IMHO (the "development" has to go into the next line too, then).
+.sp +It is able to emulate some chips to a certain degree (basic identify/read/write +operations work).
Erase does not work? If so, we should probably implement that too.
+If you use SPI flash chip emulation for a chip which supports SPI page write +with the default opcode, you can set the maximum allowed write chunk size with +the +.sp +.B " flashrom -p dummy:emulate=chip,spi_write_256_chunksize=size" +.sp +syntax where +.B size +is the number of bytes (min. 1, max. 256). +.sp +Example: +.B "flashrom -p dummy:emulate=M25P10.RES,spi_write_256_chunksize=5"
Please add an ".sp" after the "Example:" line, and indent the CLI invocation by 2 spaces as above, otherwise the line is too long when viewed using "man flashrom" and is wrapped automatically in a very ugly way. Using the ".sp" and two spaces it looks OK.
+.BR internal ", " nic3com ", " nicrealtek ", " nicsmc1211 ", " nicnatsemi ", " +.BR gfxnvidia" ", " drkaiser ", " satasii ", " satamv " and " atahpt
^ This character has to be killed, looks incorrect in the output otherwise.
With the above changes: Acked-by: Uwe Hermann uwe@hermann-uwe.de
Uwe.
On Sun, 24 Jul 2011 14:45:34 +0200 Uwe Hermann uwe@hermann-uwe.de wrote:
On Sun, Jul 24, 2011 at 01:21:42AM +0200, Carl-Daniel Hailfinger wrote:
+The dummy programmer operates on a buffer in memory only. It provides a safe and +fast way to test various aspects of flashrom and is mainly used in development +and while debugging.
Minor issue, but the "and" could be in the next line, it ends exactly on column 80, which makes the line look a bit "crowded" IMHO (the "development" has to go into the next line too, then).
isnt that how it is supposed to be? we have a line limit of 80 columns not 79. :) and its irrelevant for the man output anyway.
+.sp +It is able to emulate some chips to a certain degree (basic identify/read/write +operations work).
Erase does not work? If so, we should probably implement that too.
afaics erase is emulated correctly... so i agree, this should be changed.
Am 24.07.2011 14:45 schrieb Uwe Hermann:
On Sun, Jul 24, 2011 at 01:21:42AM +0200, Carl-Daniel Hailfinger wrote:
+The dummy programmer operates on a buffer in memory only. It provides a safe and +fast way to test various aspects of flashrom and is mainly used in development +and while debugging.
Minor issue, but the "and" could be in the next line, it ends exactly on column 80, which makes the line look a bit "crowded" IMHO (the "development" has to go into the next line too, then).
It is reformatted before being displayed in the man page anyway, but sure, I can use an 79 column limit.
+.sp +It is able to emulate some chips to a certain degree (basic identify/read/write +operations work).
Erase does not work? If so, we should probably implement that too.
Erase works, I just thought that was implied in write (the man page is end-user documentation after all). Will change.
+If you use SPI flash chip emulation for a chip which supports SPI page write +with the default opcode, you can set the maximum allowed write chunk size with +the +.sp +.B " flashrom -p dummy:emulate=chip,spi_write_256_chunksize=size" +.sp +syntax where +.B size +is the number of bytes (min. 1, max. 256). +.sp +Example: +.B "flashrom -p dummy:emulate=M25P10.RES,spi_write_256_chunksize=5"
Please add an ".sp" after the "Example:" line, and indent the CLI invocation by 2 spaces as above, otherwise the line is too long when viewed using "man flashrom" and is wrapped automatically in a very ugly way. Using the ".sp" and two spaces it looks OK.
I had that, but the look was inconsistent. That said, the linebreak is worse, so I'll change it.
Should we move all examples to an example section in the man page?
+.BR internal ", " nic3com ", " nicrealtek ", " nicsmc1211 ", " nicnatsemi ", " +.BR gfxnvidia" ", " drkaiser ", " satasii ", " satamv " and " atahpt
^This character has to be killed, looks incorrect in the output otherwise.
Thanks, I didn't spot that one.
With the above changes: Acked-by: Uwe Hermann uwe@hermann-uwe.de
Thanks, committed with changes in r1383.
Regards, Carl-Daniel
On Sun, 24 Jul 2011 20:42:11 +0200 Carl-Daniel Hailfinger c-d.hailfinger.devel.2006@gmx.net wrote:
Should we move all examples to an example section in the man page?
no. they are not useful alone but belong to the description of the feature and merely exists to demonstrate the syntax (imho :).
On Sun, Jul 24, 2011 at 08:47:50PM +0200, Stefan Tauner wrote:
On Sun, 24 Jul 2011 20:42:11 +0200 Carl-Daniel Hailfinger c-d.hailfinger.devel.2006@gmx.net wrote:
Should we move all examples to an example section in the man page?
no. they are not useful alone but belong to the description of the feature and merely exists to demonstrate the syntax (imho :).
I agree, moving is not desirable. However, an _additional_ EXAMPLES section with some common use-cases might be nice to have.
Uwe.
-
Carl-Daniel Hailfinger -
Stefan Tauner -
Uwe Hermann