flashrom 

flashrom Svn Source Tree

Root/trunk/flashrom.8.tmpl

1.\" Load the www device when using groff; provide a fallback for groff's MTO macro that formats email addresses.
2.ie \n[.g] \
3. mso www.tmac
4.el \{
5. de MTO
6 \\$2 \(la\\$1 \(ra\\$3 \
7. .
8.\}
9.\" Create wrappers for .MTO and .URL that print only text on systems w/o groff or if not outputting to a HTML
10.\" device. To that end we need to distinguish HTML output on groff from other configurations first.
11.nr groffhtml 0
12.if \n[.g] \
13. if "\*[.T]"html" \
14. nr groffhtml 1
15.\" For code reuse it would be nice to have a single wrapper that gets its target macro as parameter.
16.\" However, this did not work out with NetBSD's and OpenBSD's groff...
17.de URLB
18. ie (\n[groffhtml]==1) \{\
19. URL \\$@
20. \}
21. el \{\
22. ie "\\$2"" \{\
23. BR "\\$1" "\\$3"
24. \}
25. el \{\
26. RB "\\$2 \(la" "\\$1" "\(ra\\$3"
27. \}
28. \}
29..
30.de MTOB
31. ie (\n[groffhtml]==1) \{\
32. MTO \\$@
33. \}
34. el \{\
35. ie "\\$2"" \{\
36. BR "\\$1" "\\$3"
37. \}
38. el \{\
39. RB "\\$2 \(la" "\\$1" "\(ra\\$3"
40. \}
41. \}
42..
43.TH FLASHROM 8 "" ""
44.SH NAME
45flashrom \- detect, read, write, verify and erase flash chips
46.SH SYNOPSIS
47.B flashrom \fR[\fB\-h\fR|\fB\-R\fR|\fB\-L\fR|\fB\-z\fR|\
48\fB\-p\fR <programmername>[:<parameters>]
49 [\fB\-E\fR|\fB\-r\fR <file>|\fB\-w\fR <file>|\fB\-v\fR <file>] \
50[\fB\-c\fR <chipname>]
51 [\fB\-l\fR <file> [\fB\-i\fR <image>]] [\fB\-n\fR] [\fB\-f\fR]]
52 [\fB\-V\fR[\fBV\fR[\fBV\fR]]] [\fB-o\fR <logfile>]
53.SH DESCRIPTION
54.B flashrom
55is a utility for detecting, reading, writing, verifying and erasing flash
56chips. It's often used to flash BIOS/EFI/coreboot/firmware images in-system
57using a supported mainboard. However, it also supports various external
58PCI/USB/parallel-port/serial-port based devices which can program flash chips,
59including some network cards (NICs), SATA/IDE controller cards, graphics cards,
60the Bus Pirate device, various FTDI FT2232/FT4232H/FT232H based USB devices, and more.
61.PP
62It supports a wide range of DIP32, PLCC32, DIP8, SO8/SOIC8, TSOP32, TSOP40,
63TSOP48, and BGA chips, which use various protocols such as LPC, FWH,
64parallel flash, or SPI.
65.SH OPTIONS
66.B IMPORTANT:
67Please note that the command line interface for flashrom will change before
68flashrom 1.0. Do not use flashrom in scripts or other automated tools without
69checking that your flashrom version won't interpret options in a different way.
70.PP
71You can specify one of
72.BR \-h ", " \-R ", " \-L ", " \-z ", " \-E ", " \-r ", " \-w ", " \-v
73or no operation.
74If no operation is specified, flashrom will only probe for flash chips. It is
75recommended that if you try flashrom the first time on a system, you run it
76in probe-only mode and check the output. Also you are advised to make a
77backup of your current ROM contents with
78.B \-r
79before you try to write a new image. All operations involving any chip access (probe/read/write/...) require the
80.B -p/--programmer
81option to be used (please see below).
82.TP
83.B "\-r, \-\-read <file>"
84Read flash ROM contents and save them into the given
85.BR <file> .
86If the file already exists, it will be overwritten.
87.TP
88.B "\-w, \-\-write <file>"
89Write
90.B <file>
91into flash ROM. This will first automatically
92.B erase
93the chip, then write to it.
94.sp
95In the process the chip is also read several times. First an in-memory backup
96is made for disaster recovery and to be able to skip regions that are
97already equal to the image file. This copy is updated along with the write
98operation. In case of erase errors it is even re-read completely. After
99writing has finished and if verification is enabled, the whole flash chip is
100read out and compared with the input image.
101.TP
102.B "\-n, \-\-noverify"
103Skip the automatic verification of flash ROM contents after writing. Using this
104option is
105.B not
106recommended, you should only use it if you know what you are doing and if you
107feel that the time for verification takes too long.
108.sp
109Typical usage is:
110.B "flashrom \-p prog \-n \-w <file>"
111.sp
112This option is only useful in combination with
113.BR \-\-write .
114.TP
115.B "\-v, \-\-verify <file>"
116Verify the flash ROM contents against the given
117.BR <file> .
118.TP
119.B "\-E, \-\-erase"
120Erase the flash ROM chip.
121.TP
122.B "\-V, \-\-verbose"
123More verbose output. This option can be supplied multiple times
124(max. 3 times, i.e.
125.BR \-VVV )
126for even more debug output.
127.TP
128.B "\-c, \-\-chip" <chipname>
129Probe only for the specified flash ROM chip. This option takes the chip name as
130printed by
131.B "flashrom \-L"
132without the vendor name as parameter. Please note that the chip name is
133case sensitive.
134.TP
135.B "\-f, \-\-force"
136Force one or more of the following actions:
137.sp
138* Force chip read and pretend the chip is there.
139.sp
140* Force chip access even if the chip is bigger than the maximum supported \
141size for the flash bus.
142.sp
143* Force erase even if erase is known bad.
144.sp
145* Force write even if write is known bad.
146.TP
147.B "\-l, \-\-layout <file>"
148Read ROM layout from
149.BR <file> .
150.sp
151flashrom supports ROM layouts. This allows you to flash certain parts of
152the flash chip only. A ROM layout file contains multiple lines with the
153following syntax:
154.sp
155.B " startaddr:endaddr imagename"
156.sp
157.BR "startaddr " "and " "endaddr "
158are hexadecimal addresses within the ROM file and do not refer to any
159physical address. Please note that using a 0x prefix for those hexadecimal
160numbers is not necessary, but you can't specify decimal/octal numbers.
161.BR "imagename " "is an arbitrary name for the region/image from"
162.BR " startaddr " "to " "endaddr " "(both addresses included)."
163.sp
164Example:
165.sp
166 00000000:00008fff gfxrom
167 00009000:0003ffff normal
168 00040000:0007ffff fallback
169.sp
170If you only want to update the image named
171.BR "normal " "in a ROM based on the layout above, run"
172.sp
173.B " flashrom \-p prog \-\-layout rom.layout \-\-image normal \-w some.rom"
174.sp
175To update only the images named
176.BR "normal " "and " "fallback" ", run:"
177.sp
178.B " flashrom \-p prog \-l rom.layout \-i normal -i fallback \-w some.rom"
179.sp
180Overlapping sections are not supported.
181.TP
182.B "\-i, \-\-image <imagename>"
183Only flash region/image
184.B <imagename>
185from flash layout.
186.TP
187.B "\-L, \-\-list\-supported"
188List the flash chips, chipsets, mainboards, and external programmers
189(including PCI, USB, parallel port, and serial port based devices)
190supported by flashrom.
191.sp
192There are many unlisted boards which will work out of the box, without
193special support in flashrom. Please let us know if you can verify that
194other boards work or do not work out of the box.
195.sp
196.B IMPORTANT:
197For verification you have
198to test an ERASE and/or WRITE operation, so make sure you only do that
199if you have proper means to recover from failure!
200.TP
201.B "\-z, \-\-list\-supported-wiki"
202Same as
203.BR \-\-list\-supported ,
204but outputs the supported hardware in MediaWiki syntax, so that it can be
205easily pasted into the
206.URLB https://flashrom.org/Supported_hardware "supported hardware wiki page" .
207Please note that MediaWiki output is not compiled in by default.
208.TP
209.B "\-p, \-\-programmer <name>[:parameter[,parameter[,parameter]]]"
210Specify the programmer device. This is mandatory for all operations
211involving any chip access (probe/read/write/...). Currently supported are:
212.sp
213.BR "* internal" " (for in-system flashing in the mainboard)"
214.sp
215.BR "* dummy" " (virtual programmer for testing flashrom)"
216.sp
217.BR "* nic3com" " (for flash ROMs on 3COM network cards)"
218.sp
219.BR "* nicrealtek" " (for flash ROMs on Realtek and SMC 1211 network cards)"
220.sp
221.BR "* nicnatsemi" " (for flash ROMs on National Semiconductor DP838* network \
222cards)"
223.sp
224.BR "* nicintel" " (for parallel flash ROMs on Intel 10/100Mbit network cards)
225.sp
226.BR "* gfxnvidia" " (for flash ROMs on NVIDIA graphics cards)"
227.sp
228.BR "* drkaiser" " (for flash ROMs on Dr. Kaiser PC-Waechter PCI cards)"
229.sp
230.BR "* satasii" " (for flash ROMs on Silicon Image SATA/IDE controllers)"
231.sp
232.BR "* satamv" " (for flash ROMs on Marvell SATA controllers)"
233.sp
234.BR "* atahpt" " (for flash ROMs on Highpoint ATA/RAID controllers)"
235.sp
236.BR "* atavia" " (for flash ROMs on VIA VT6421A SATA controllers)"
237.sp
238.BR "* atapromise" " (for flash ROMs on Promise PDC2026x ATA/RAID controllers)"
239.sp
240.BR "* it8212" " (for flash ROMs on ITE IT8212F ATA/RAID controller)"
241.sp
242.BR "* ft2232_spi" " (for SPI flash ROMs attached to an FT2232/FT4232H/FT232H family based USB SPI programmer).
243.sp
244.BR "* serprog" " (for flash ROMs attached to a programmer speaking serprog, \
245including some Arduino-based devices)."
246.sp
247.BR "* buspirate_spi" " (for SPI flash ROMs attached to a Bus Pirate)"
248.sp
249.BR "* dediprog" " (for SPI flash ROMs attached to a Dediprog SF100)"
250.sp
251.BR "* rayer_spi" " (for SPI flash ROMs attached to a parallel port by one of various cable types)"
252.sp
253.BR "* pony_spi" " (for SPI flash ROMs attached to a SI-Prog serial port "
254bitbanging adapter)
255.sp
256.BR "* nicintel_spi" " (for SPI flash ROMs on Intel Gigabit network cards)"
257.sp
258.BR "* ogp_spi" " (for SPI flash ROMs on Open Graphics Project graphics card)"
259.sp
260.BR "* linux_spi" " (for SPI flash ROMs accessible via /dev/spidevX.Y on Linux)"
261.sp
262.BR "* usbblaster_spi" " (for SPI flash ROMs attached to an Altera USB-Blaster compatible cable)"
263.sp
264.BR "* nicintel_eeprom" " (for SPI EEPROMs on Intel Gigabit network cards)"
265.sp
266.BR "* mstarddc_spi" " (for SPI flash ROMs accessible through DDC in MSTAR-equipped displays)"
267.sp
268.BR "* pickit2_spi" " (for SPI flash ROMs accessible via Microchip PICkit2)"
269.sp
270.BR "* ch341a_spi" " (for SPI flash ROMs attached to WCH CH341A)"
271.sp
272Some programmers have optional or mandatory parameters which are described
273in detail in the
274.B PROGRAMMER-SPECIFIC INFORMATION
275section. Support for some programmers can be disabled at compile time.
276.B "flashrom \-h"
277lists all supported programmers.
278.TP
279.B "\-h, \-\-help"
280Show a help text and exit.
281.TP
282.B "\-o, \-\-output <logfile>"
283Save the full debug log to
284.BR <logfile> .
285If the file already exists, it will be overwritten. This is the recommended
286way to gather logs from flashrom because they will be verbose even if the
287on-screen messages are not verbose and don't require output redirection.
288.TP
289.B "\-R, \-\-version"
290Show version information and exit.
291.SH PROGRAMMER-SPECIFIC INFORMATION
292Some programmer drivers accept further parameters to set programmer-specific
293parameters. These parameters are separated from the programmer name by a
294colon. While some programmers take arguments at fixed positions, other
295programmers use a key/value interface in which the key and value is separated
296by an equal sign and different pairs are separated by a comma or a colon.
297.SS
298.BR "internal " programmer
299.TP
300.B Board Enables
301.sp
302Some mainboards require to run mainboard specific code to enable flash erase
303and write support (and probe support on old systems with parallel flash).
304The mainboard brand and model (if it requires specific code) is usually
305autodetected using one of the following mechanisms: If your system is
306running coreboot, the mainboard type is determined from the coreboot table.
307Otherwise, the mainboard is detected by examining the onboard PCI devices
308and possibly DMI info. If PCI and DMI do not contain information to uniquely
309identify the mainboard (which is the exception), or if you want to override
310the detected mainboard model, you can specify the mainboard using the
311.sp
312.B " flashrom \-p internal:mainboard=<vendor>:<board>"
313syntax.
314.sp
315See the 'Known boards' or 'Known laptops' section in the output
316of 'flashrom \-L' for a list of boards which require the specification of
317the board name, if no coreboot table is found.
318.sp
319Some of these board-specific flash enabling functions (called
320.BR "board enables" )
321in flashrom have not yet been tested. If your mainboard is detected needing
322an untested board enable function, a warning message is printed and the
323board enable is not executed, because a wrong board enable function might
324cause the system to behave erratically, as board enable functions touch the
325low-level internals of a mainboard. Not executing a board enable function
326(if one is needed) might cause detection or erasing failure. If your board
327protects only part of the flash (commonly the top end, called boot block),
328flashrom might encounter an error only after erasing the unprotected part,
329so running without the board-enable function might be dangerous for erase
330and write (which includes erase).
331.sp
332The suggested procedure for a mainboard with untested board specific code is
333to first try to probe the ROM (just invoke flashrom and check that it
334detects your flash chip type) without running the board enable code (i.e.
335without any parameters). If it finds your chip, fine. Otherwise, retry
336probing your chip with the board-enable code running, using
337.sp
338.B " flashrom \-p internal:boardenable=force"
339.sp
340If your chip is still not detected, the board enable code seems to be broken
341or the flash chip unsupported. Otherwise, make a backup of your current ROM
342contents (using
343.BR \-r )
344and store it to a medium outside of your computer, like
345a USB drive or a network share. If you needed to run the board enable code
346already for probing, use it for reading too.
347If reading succeeds and the contens of the read file look legit you can try to write the new image.
348You should enable the board enable code in any case now, as it
349has been written because it is known that writing/erasing without the board
350enable is going to fail. In any case (success or failure), please report to
351the flashrom mailing list, see below.
352.sp
353.TP
354.B Coreboot
355.sp
356On systems running coreboot, flashrom checks whether the desired image matches
357your mainboard. This needs some special board ID to be present in the image.
358If flashrom detects that the image you want to write and the current board
359do not match, it will refuse to write the image unless you specify
360.sp
361.B " flashrom \-p internal:boardmismatch=force"
362.TP
363.B ITE IT87 Super I/O
364.sp
365If your mainboard is manufactured by GIGABYTE and supports DualBIOS it is very likely that it uses an
366ITE IT87 series Super I/O to switch between the two flash chips. Only one of them can be accessed at a time
367and you can manually select which one to use with the
368.sp
369.B " flashrom \-p internal:dualbiosindex=chip"
370.sp
371syntax where
372.B chip
373is the index of the chip to use (0 = main, 1 = backup). You can check which one is currently selected by
374leaving out the
375.B chip
376parameter.
377.sp
378If your mainboard uses an ITE IT87 series Super I/O for LPC<->SPI flash bus
379translation, flashrom should autodetect that configuration. If you want to
380set the I/O base port of the IT87 series SPI controller manually instead of
381using the value provided by the BIOS, use the
382.sp
383.B " flashrom \-p internal:it87spiport=portnum"
384.sp
385syntax where
386.B portnum
387is the I/O port number (must be a multiple of 8). In the unlikely case
388flashrom doesn't detect an active IT87 LPC<->SPI bridge, please send a bug
389report so we can diagnose the problem.
390.sp
391.TP
392.B AMD chipsets
393.sp
394Beginning with the SB700 chipset there is an integrated microcontroller (IMC) based on the 8051 embedded in
395every AMD southbridge. Its firmware resides in the same flash chip as the host's which makes writing to the
396flash risky if the IMC is active. Flashrom tries to temporarily disable the IMC but even then changing the
397contents of the flash can have unwanted effects: when the IMC continues (at the latest after a reboot) it will
398continue executing code from the flash. If the code was removed or changed in an unfortunate way it is
399unpredictable what the IMC will do. Therefore, if flashrom detects an active IMC it will disable write support
400unless the user forces it with the
401.sp
402.B " flashrom \-p internal:amd_imc_force=yes"
403.sp
404syntax. The user is responsible for supplying a suitable image or leaving out the IMC region with the help of
405a layout file. This limitation might be removed in the future when we understand the details better and have
406received enough feedback from users. Please report the outcome if you had to use this option to write a chip.
407.sp
408An optional
409.B spispeed
410parameter specifies the frequency of the SPI bus where applicable (i.e.\& SB600 or later with an SPI flash chip
411directly attached to the chipset).
412Syntax is
413.sp
414.B " flashrom \-p internal:spispeed=frequency"
415.sp
416where
417.B frequency
418can be
419.BR "'16.5\ MHz'" ", " "'22\ MHz'" ", " "'33\ MHz'" ", " "'66\ MHz'" ", " "'100\ MHZ'" ", or " "'800\ kHz'" "."
420Support of individual frequencies depends on the generation of the chipset:
421.sp
422* SB6xx, SB7xx, SP5xxx: from 16.5 MHz up to and including 33 MHz
423.sp
424* SB8xx, SB9xx, Hudson: from 16.5 MHz up to and including 66 MHz
425.sp
426* Yangtze (with SPI 100 engine as found in Kabini and Tamesh): all of them
427.sp
428The default is to use 16.5 MHz and disable Fast Reads.
429.TP
430.B Intel chipsets
431.sp
432If you have an Intel chipset with an ICH8 or later southbridge with SPI flash
433attached, and if a valid descriptor was written to it (e.g.\& by the vendor), the
434chipset provides an alternative way to access the flash chip(s) named
435.BR "Hardware Sequencing" .
436It is much simpler than the normal access method (called
437.BR "Software Sequencing" "),"
438but does not allow the software to choose the SPI commands to be sent.
439You can use the
440.sp
441.B " flashrom \-p internal:ich_spi_mode=value"
442.sp
443syntax where
444.BR "value " "can be"
445.BR auto ", " swseq " or " hwseq .
446By default
447.RB "(or when setting " ich_spi_mode=auto )
448the module tries to use swseq and only activates hwseq if need be (e.g.\& if
449important opcodes are inaccessible due to lockdown; or if more than one flash
450chip is attached). The other options (swseq, hwseq) select the respective mode
451(if possible).
452.sp
453ICH8 and later southbridges may also have locked address ranges of different
454kinds if a valid descriptor was written to it. The flash address space is then
455partitioned in multiple so called "Flash Regions" containing the host firmware,
456the ME firmware and so on respectively. The flash descriptor can also specify up
457to 5 so called "Protected Regions", which are freely chosen address ranges
458independent from the aforementioned "Flash Regions". All of them can be write
459and/or read protected individually. If flashrom detects such a lock it will
460disable write support unless the user forces it with the
461.sp
462.B " flashrom \-p internal:ich_spi_force=yes"
463.sp
464syntax. If this leads to erase or write accesses to the flash it would most
465probably bring it into an inconsistent and unbootable state and we will not
466provide any support in such a case.
467.sp
468If you have an Intel chipset with an ICH2 or later southbridge and if you want
469to set specific IDSEL values for a non-default flash chip or an embedded
470controller (EC), you can use the
471.sp
472.B " flashrom \-p internal:fwh_idsel=value"
473.sp
474syntax where
475.B value
476is the 48-bit hexadecimal raw value to be written in the
477IDSEL registers of the Intel southbridge. The upper 32 bits use one hex digit
478each per 512 kB range between 0xffc00000 and 0xffffffff, and the lower 16 bits
479use one hex digit each per 1024 kB range between 0xff400000 and 0xff7fffff.
480The rightmost hex digit corresponds with the lowest address range. All address
481ranges have a corresponding sister range 4 MB below with identical IDSEL
482settings. The default value for ICH7 is given in the example below.
483.sp
484Example:
485.B "flashrom \-p internal:fwh_idsel=0x001122334567"
486.TP
487.B Laptops
488.sp
489Using flashrom on laptops is dangerous and may easily make your hardware
490unusable (see also the
491.B BUGS
492section). The embedded controller (EC) in these
493machines often interacts badly with flashing.
494More information is
495.URLB https://flashrom.org/Laptops "in the wiki" .
496For example the EC firmware sometimes resides on the same
497flash chip as the host firmware. While flashrom tries to change the contents of
498that memory the EC might need to fetch new instructions or data from it and
499could stop working correctly. Probing for and reading from the chip may also
500irritate your EC and cause fan failure, backlight failure, sudden poweroff, and
501other nasty effects. flashrom will attempt to detect if it is running on a
502laptop and abort immediately for safety reasons if it clearly identifies the
503host computer as one. If you want to proceed anyway at your own risk, use
504.sp
505.B " flashrom \-p internal:laptop=force_I_want_a_brick"
506.sp
507We will not help you if you force flashing on a laptop because this is a really
508dumb idea.
509.sp
510You have been warned.
511.sp
512Currently we rely on the chassis type encoded in the DMI/SMBIOS data to detect
513laptops. Some vendors did not implement those bits correctly or set them to
514generic and/or dummy values. flashrom will then issue a warning and bail out
515like above. In this case you can use
516.sp
517.B " flashrom \-p internal:laptop=this_is_not_a_laptop"
518.sp
519to tell flashrom (at your own risk) that it is not running on a laptop.
520.SS
521.BR "dummy " programmer
522.IP
523The dummy programmer operates on a buffer in memory only. It provides a safe and fast way to test various
524aspects of flashrom and is mainly used in development and while debugging.
525It is able to emulate some chips to a certain degree (basic
526identify/read/erase/write operations work).
527.sp
528An optional parameter specifies the bus types it
529should support. For that you have to use the
530.sp
531.B " flashrom \-p dummy:bus=[type[+type[+type]]]"
532.sp
533syntax where
534.B type
535can be
536.BR parallel ", " lpc ", " fwh ", " spi
537in any order. If you specify bus without type, all buses will be disabled.
538If you do not specify bus, all buses will be enabled.
539.sp
540Example:
541.B "flashrom \-p dummy:bus=lpc+fwh"
542.sp
543The dummy programmer supports flash chip emulation for automated self-tests
544without hardware access. If you want to emulate a flash chip, use the
545.sp
546.B " flashrom \-p dummy:emulate=chip"
547.sp
548syntax where
549.B chip
550is one of the following chips (please specify only the chip name, not the
551vendor):
552.sp
553.RB "* ST " M25P10.RES " SPI flash chip (128 kB, RES, page write)"
554.sp
555.RB "* SST " SST25VF040.REMS " SPI flash chip (512 kB, REMS, byte write)"
556.sp
557.RB "* SST " SST25VF032B " SPI flash chip (4096 kB, RDID, AAI write)"
558.sp
559.RB "* Macronix " MX25L6436 " SPI flash chip (8192 kB, RDID, SFDP)"
560.sp
561Example:
562.B "flashrom -p dummy:emulate=SST25VF040.REMS"
563.TP
564.B Persistent images
565.sp
566If you use flash chip emulation, flash image persistence is available as well
567by using the
568.sp
569.B " flashrom \-p dummy:emulate=chip,image=image.rom"
570.sp
571syntax where
572.B image.rom
573is the file where the simulated chip contents are read on flashrom startup and
574where the chip contents on flashrom shutdown are written to.
575.sp
576Example:
577.B "flashrom -p dummy:emulate=M25P10.RES,image=dummy.bin"
578.TP
579.B SPI write chunk size
580.sp
581If you use SPI flash chip emulation for a chip which supports SPI page write
582with the default opcode, you can set the maximum allowed write chunk size with
583the
584.sp
585.B " flashrom \-p dummy:emulate=chip,spi_write_256_chunksize=size"
586.sp
587syntax where
588.B size
589is the number of bytes (min.\& 1, max.\& 256).
590.sp
591Example:
592.sp
593.B " flashrom -p dummy:emulate=M25P10.RES,spi_write_256_chunksize=5"
594.TP
595.B SPI blacklist
596.sp
597To simulate a programmer which refuses to send certain SPI commands to the
598flash chip, you can specify a blacklist of SPI commands with the
599.sp
600.B " flashrom -p dummy:spi_blacklist=commandlist"
601.sp
602syntax where
603.B commandlist
604is a list of two-digit hexadecimal representations of
605SPI commands. If commandlist is e.g.\& 0302, flashrom will behave as if the SPI
606controller refuses to run command 0x03 (READ) and command 0x02 (WRITE).
607commandlist may be up to 512 characters (256 commands) long.
608Implementation note: flashrom will detect an error during command execution.
609.sp
610.TP
611.B SPI ignorelist
612.sp
613To simulate a flash chip which ignores (doesn't support) certain SPI commands,
614you can specify an ignorelist of SPI commands with the
615.sp
616.B " flashrom -p dummy:spi_ignorelist=commandlist"
617.sp
618syntax where
619.B commandlist
620is a list of two-digit hexadecimal representations of
621SPI commands. If commandlist is e.g.\& 0302, the emulated flash chip will ignore
622command 0x03 (READ) and command 0x02 (WRITE). commandlist may be up to 512
623characters (256 commands) long.
624Implementation note: flashrom won't detect an error during command execution.
625.sp
626.TP
627.B SPI status register
628.sp
629You can specify the initial content of the chip's status register with the
630.sp
631.B " flashrom -p dummy:spi_status=content"
632.sp
633syntax where
634.B content
635is an 8-bit hexadecimal value.
636.SS
637.BR "nic3com" , " nicrealtek" , " nicnatsemi" , " nicintel", " nicintel_eeprom"\
638, " nicintel_spi" , " gfxnvidia" , " ogp_spi" , " drkaiser" , " satasii"\
639, " satamv" , " atahpt", " atavia ", " atapromise " and " it8212 " programmers
640.IP
641These programmers have an option to specify the PCI address of the card
642your want to use, which must be specified if more than one card supported
643by the selected programmer is installed in your system. The syntax is
644.sp
645.BR " flashrom \-p xxxx:pci=bb:dd.f" ,
646.sp
647where
648.B xxxx
649is the name of the programmer,
650.B bb
651is the PCI bus number,
652.B dd
653is the PCI device number, and
654.B f
655is the PCI function number of the desired device.
656.sp
657Example:
658.B "flashrom \-p nic3com:pci=05:04.0"
659.SS
660.BR "atavia " programmer
661.IP
662Due to the mysterious address handling of the VIA VT6421A controller the user can specify an offset with the
663.sp
664.B " flashrom \-p atavia:offset=addr"
665.sp
666syntax where
667.B addr
668will be interpreted as usual (leading 0x (0) for hexadecimal (octal) values, or else decimal).
669For more information please see
670.URLB https://flashrom.org/VT6421A "its wiki page" .
671.SS
672.BR "atapromise " programmer
673.IP
674This programmer is currently limited to 32 kB, regardless of the actual size of the flash chip. This stems
675from the fact that, on the tested device (a Promise Ultra100), not all of the chip's address lines were
676actually connected. You may use this programmer to flash firmware updates, since these are only 16 kB in
677size (padding to 32 kB is required).
678.SS
679.BR "nicintel_eeprom " programmer
680.IP
681This is the first programmer module in flashrom that does not provide access to NOR flash chips but EEPROMs
682mounted on gigabit Ethernet cards based on Intel's 82580 NIC. Because EEPROMs normally do not announce their
683size nor allow themselves to be identified, the controller relies on correct size values written to predefined
684addresses within the chip. Flashrom follows this scheme but assumes the minimum size of 16 kB (128 kb) if an
685unprogrammed EEPROM/card is detected. Intel specifies following EEPROMs to be compatible:
686Atmel AT25128, AT25256, Micron (ST) M95128, M95256 and OnSemi (Catalyst) CAT25CS128.
687.SS
688.BR "ft2232_spi " programmer
689.IP
690This module supports various programmers based on FTDI FT2232/FT4232H/FT232H chips including the DLP Design
691DLP-USB1232H, openbiosprog-spi, Amontec JTAGkey/JTAGkey-tiny/JTAGkey-2, Dangerous Prototypes Bus Blaster,
692Olimex ARM-USB-TINY/-H, Olimex ARM-USB-OCD/-H, OpenMoko Neo1973 Debug board (V2+), TIAO/DIYGADGET USB
693Multi-Protocol Adapter (TUMPA), TUMPA Lite, GOEPEL PicoTAP and Google Servo v1/v2.
694.sp
695An optional parameter specifies the controller
696type and channel/interface/port it should support. For that you have to use the
697.sp
698.B " flashrom \-p ft2232_spi:type=model,port=interface"
699.sp
700syntax where
701.B model
702can be
703.BR 2232H ", " 4232H ", " 232H ", " jtagkey ", " busblaster ", " openmoko ", " \
704arm-usb-tiny ", " arm-usb-tiny-h ", " arm-usb-ocd ", " arm-usb-ocd-h \
705", " tumpa ", " tumpalite ", " picotap ", " google-servo ", " google-servo-v2 \
706" or " google-servo-v2-legacy
707and
708.B interface
709can be
710.BR A ", " B ", " C ", or " D .
711The default model is
712.B 4232H
713and the default interface is
714.BR A .
715.sp
716If there is more than one ft2232_spi-compatible device connected, you can select which one should be used by
717specifying its serial number with the
718.sp
719.B " flashrom \-p ft2232_spi:serial=number"
720.sp
721syntax where
722.B number
723is the serial number of the device (which can be found for example in the output of lsusb -v).
724.sp
725All models supported by the ft2232_spi driver can configure the SPI clock rate by setting a divisor. The
726expressible divisors are all
727.B even
728numbers between 2 and 2^17 (=131072) resulting in SPI clock frequencies of
7296 MHz down to about 92 Hz for 12 MHz inputs. The default divisor is set to 2, but you can use another one by
730specifying the optional
731.B divisor
732parameter with the
733.sp
734.B " flashrom \-p ft2232_spi:divisor=div"
735.sp
736syntax.
737.SS
738.BR "serprog " programmer
739.IP
740This module supports all programmers speaking the serprog protocol. This includes some Arduino-based devices
741as well as various programmers by Urja Rannikko, Juhana Helovuo, Stefan Tauner, Chi Zhang and many others.
742.sp
743A mandatory parameter specifies either a serial device (and baud rate) or an IP/port combination for
744communicating with the programmer.
745The device/baud combination has to start with
746.B dev=
747and separate the optional baud rate with a colon.
748For example
749.sp
750.B " flashrom \-p serprog:dev=/dev/ttyS0:115200"
751.sp
752If no baud rate is given the default values by the operating system/hardware will be used.
753For IP connections you have to use the
754.sp
755.B " flashrom \-p serprog:ip=ipaddr:port"
756.sp
757syntax.
758In case the device supports it, you can set the SPI clock frequency with the optional
759.B spispeed
760parameter. The frequency is parsed as hertz, unless an
761.BR M ", or " k
762suffix is given, then megahertz or kilohertz are used respectively.
763Example that sets the frequency to 2 MHz:
764.sp
765.B " flashrom \-p serprog:dev=/dev/device:baud,spispeed=2M"
766.sp
767More information about serprog is available in
768.B serprog-protocol.txt
769in the source distribution.
770.SS
771.BR "buspirate_spi " programmer
772.IP
773A required
774.B dev
775parameter specifies the Bus Pirate device node and an optional
776.B spispeed
777parameter specifies the frequency of the SPI bus. The parameter
778delimiter is a comma. Syntax is
779.sp
780.B " flashrom \-p buspirate_spi:dev=/dev/device,spispeed=frequency"
781.sp
782where
783.B frequency
784can be
785.BR 30k ", " 125k ", " 250k ", " 1M ", " 2M ", " 2.6M ", " 4M " or " 8M
786(in Hz). The default is the maximum frequency of 8 MHz.
787.sp
788An optional pullups parameter specifies the use of the Bus Pirate internal pull-up resistors. This may be
789needed if you are working with a flash ROM chip that you have physically removed from the board. Syntax is
790.sp
791.B " flashrom -p buspirate_spi:pullups=state"
792.sp
793where
794.B state
795can be
796.BR on " or " off .
797More information about the Bus Pirate pull-up resistors and their purpose is available
798.URLB "http://dangerousprototypes.com/docs/Practical_guide_to_Bus_Pirate_pull-up_resistors" \
799"in a guide by dangerousprototypes" .
800Only the external supply voltage (Vpu) is supported as of this writing.
801.SS
802.BR "pickit2_spi " programmer
803.IP
804An optional
805.B voltage
806parameter specifies the voltage the PICkit2 should use. The default unit is Volt if no unit is specified.
807You can use
808.BR mV ", " millivolt ", " V " or " Volt
809as unit specifier. Syntax is
810.sp
811.B " flashrom \-p pickit2_spi:voltage=value"
812.sp
813where
814.B value
815can be
816.BR 0V ", " 1.8V ", " 2.5V ", " 3.5V
817or the equivalent in mV.
818.sp
819An optional
820.B spispeed
821parameter specifies the frequency of the SPI bus. Syntax is
822.sp
823.B " flashrom \-p pickit2_spi:spispeed=frequency"
824.sp
825where
826.B frequency
827can be
828.BR 250k ", " 333k ", " 500k " or " 1M "
829(in Hz). The default is a frequency of 1 MHz.
830.SS
831.BR "dediprog " programmer
832.IP
833An optional
834.B voltage
835parameter specifies the voltage the Dediprog should use. The default unit is
836Volt if no unit is specified. You can use
837.BR mV ", " milliVolt ", " V " or " Volt
838as unit specifier. Syntax is
839.sp
840.B " flashrom \-p dediprog:voltage=value"
841.sp
842where
843.B value
844can be
845.BR 0V ", " 1.8V ", " 2.5V ", " 3.5V
846or the equivalent in mV.
847.sp
848An optional
849.B device
850parameter specifies which of multiple connected Dediprog devices should be used.
851Please be aware that the order depends on libusb's usb_get_busses() function and that the numbering starts
852at 0.
853Usage example to select the second device:
854.sp
855.B " flashrom \-p dediprog:device=1"
856.sp
857An optional
858.B spispeed
859parameter specifies the frequency of the SPI bus. The firmware on the device needs to be 5.0.0 or newer.
860Syntax is
861.sp
862.B " flashrom \-p dediprog:spispeed=frequency"
863.sp
864where
865.B frequency
866can be
867.BR 375k ", " 750k ", " 1.5M ", " 2.18M ", " 3M ", " 8M ", " 12M " or " 24M
868(in Hz). The default is a frequency of 12 MHz.
869.sp
870An optional
871.B target
872parameter specifies which target chip should be used. Syntax is
873.sp
874.B " flashrom \-p dediprog:target=value"
875.sp
876where
877.B value
878can be
879.BR 1 " or " 2
880to select target chip 1 or 2 respectively. The default is target chip 1.
881.SS
882.BR "rayer_spi " programmer
883.IP
884The default I/O base address used for the parallel port is 0x378 and you can use
885the optional
886.B iobase
887parameter to specify an alternate base I/O address with the
888.sp
889.B " flashrom \-p rayer_spi:iobase=baseaddr"
890.sp
891syntax where
892.B baseaddr
893is base I/O port address of the parallel port, which must be a multiple of
894four. Make sure to not forget the "0x" prefix for hexadecimal port addresses.
895.sp
896The default cable type is the RayeR cable. You can use the optional
897.B type
898parameter to specify the cable type with the
899.sp
900.B " flashrom \-p rayer_spi:type=model"
901.sp
902syntax where
903.B model
904can be
905.BR rayer " for the RayeR cable, " byteblastermv " for the Altera ByteBlasterMV, " stk200 " for the Atmel \
906STK200/300, " wiggler " for the Macraigor Wiggler, " xilinx " for the Xilinx Parallel Cable III (DLC 5), or" \
907" spi_tt" " for SPI Tiny Tools-compatible hardware.
908.sp
909More information about the RayeR hardware is available at
910.nh
911.URLB "http://rayer.g6.cz/elektro/spipgm.htm" "RayeR's website" .
912The Altera ByteBlasterMV datasheet can be obtained from
913.URLB "http://www.altera.co.jp/literature/ds/dsbytemv.pdf" Altera .
914For more information about the Macraigor Wiggler see
915.URLB "http://www.macraigor.com/wiggler.htm" "their company homepage" .
916The schematic of the Xilinx DLC 5 was published in
917.URLB "http://www.xilinx.com/support/documentation/user_guides/xtp029.pdf" "a Xilinx user guide" .
918.SS
919.BR "pony_spi " programmer
920.IP
921The serial port (like /dev/ttyS0, /dev/ttyUSB0 on Linux or COM3 on windows) is
922specified using the mandatory
923.B dev
924parameter. The adapter type is selectable between SI-Prog (used for
925SPI devices with PonyProg 2000) or a custom made serial bitbanging programmer
926named "serbang". The optional
927.B type
928parameter accepts the values "si_prog" (default) or "serbang".
929.sp
930Information about the SI-Prog adapter can be found at
931.URLB "http://www.lancos.com/siprogsch.html" "its website" .
932.sp
933An example call to flashrom is
934.sp
935.B " flashrom \-p pony_spi:dev=/dev/ttyS0,type=serbang"
936.sp
937Please note that while USB-to-serial adapters work under certain circumstances,
938this slows down operation considerably.
939.SS
940.BR "ogp_spi " programmer
941.IP
942The flash ROM chip to access must be specified with the
943.B rom
944parameter.
945.sp
946.B " flashrom \-p ogp_spi:rom=name"
947.sp
948Where
949.B name
950is either
951.B cprom
952or
953.B s3
954for the configuration ROM and
955.B bprom
956or
957.B bios
958for the BIOS ROM. If more than one card supported by the ogp_spi programmer
959is installed in your system, you have to specify the PCI address of the card
960you want to use with the
961.B pci=
962parameter as explained in the
963.B nic3com et al.\&
964section above.
965.SS
966.BR "linux_spi " programmer
967.IP
968You have to specify the SPI controller to use with the
969.sp
970.B " flashrom \-p linux_spi:dev=/dev/spidevX.Y"
971.sp
972syntax where
973.B /dev/spidevX.Y
974is the Linux device node for your SPI controller.
975.sp
976In case the device supports it, you can set the SPI clock frequency with the optional
977.B spispeed
978parameter. The frequency is parsed as kilohertz.
979Example that sets the frequency to 8 MHz:
980.sp
981.B " flashrom \-p linux_spi:dev=/dev/spidevX.Y,spispeed=8000"
982.sp
983Please note that the linux_spi driver only works on Linux.
984.SS
985.BR "mstarddc_spi " programmer
986.IP
987The Display Data Channel (DDC) is an I2C bus present on VGA and DVI connectors, that allows exchanging
988information between a computer and attached displays. Its most common uses are getting display capabilities
989through EDID (at I2C address 0x50) and sending commands to the display using the DDC/CI protocol (at address
9900x37). On displays driven by MSTAR SoCs, it is also possible to access the SoC firmware flash (connected to
991the Soc through another SPI bus) using an In-System Programming (ISP) port, usually at address 0x49.
992This flashrom module allows the latter via Linux's I2C driver.
993.sp
994.B IMPORTANT:
995Before using this programmer, the display
996.B MUST
997be in standby mode, and only connected to the computer that will run flashrom using a VGA cable, to an
998inactive VGA output. It absolutely
999.B MUST NOT
1000be used as a display during the procedure!
1001.sp
1002You have to specify the DDC/I2C controller and I2C address to use with the
1003.sp
1004.B " flashrom \-p mstarddc_spi:dev=/dev/i2c-X:YY"
1005.sp
1006syntax where
1007.B /dev/i2c-X
1008is the Linux device node for your I2C controller connected to the display's DDC channel, and
1009.B YY
1010is the (hexadecimal) address of the MSTAR ISP port (address 0x49 is usually used).
1011Example that uses I2C controller /dev/i2c-1 and address 0x49:
1012.sp
1013.B " flashrom \-p mstarddc_spi:dev=/dev/i2c-1:49
1014.sp
1015It is also possible to inhibit the reset command that is normally sent to the display once the flashrom
1016operation is completed using the optional
1017.B noreset
1018parameter. A value of 1 prevents flashrom from sending the reset command.
1019Example that does not reset the display at the end of the operation:
1020.sp
1021.B " flashrom \-p mstarddc_spi:dev=/dev/i2c-1:49,noreset=1
1022.sp
1023Please note that sending the reset command is also inhibited if an error occurred during the operation.
1024To send the reset command afterwards, you can simply run flashrom once more, in chip probe mode (not specifying
1025an operation), without the
1026.B noreset
1027parameter, once the flash read/write operation you intended to perform has completed successfully.
1028.sp
1029Please also note that the mstarddc_spi driver only works on Linux.
1030.SS
1031.BR "ch341a_spi " programmer
1032The WCH CH341A programmer does not support any parameters currently. SPI frequency is fixed at 2 MHz, and CS0 is
1033used as per the device.
1034.SH EXAMPLES
1035To back up and update your BIOS, run
1036.sp
1037.B flashrom -p internal -r backup.rom -o backuplog.txt
1038.br
1039.B flashrom -p internal -w newbios.rom -o writelog.txt
1040.sp
1041Please make sure to copy backup.rom to some external media before you try
1042to write. That makes offline recovery easier.
1043.br
1044If writing fails and flashrom complains about the chip being in an unknown
1045state, you can try to restore the backup by running
1046.sp
1047.B flashrom -p internal -w backup.rom -o restorelog.txt
1048.sp
1049If you encounter any problems, please contact us and supply
1050backuplog.txt, writelog.txt and restorelog.txt. See section
1051.B BUGS
1052for contact info.
1053.SH EXIT STATUS
1054flashrom exits with 0 on success, 1 on most failures but with 3 if a call to mmap() fails.
1055.SH REQUIREMENTS
1056flashrom needs different access permissions for different programmers.
1057.sp
1058.B internal
1059needs raw memory access, PCI configuration space access, raw I/O port
1060access (x86) and MSR access (x86).
1061.sp
1062.B atavia
1063needs PCI configuration space access.
1064.sp
1065.BR nic3com ", " nicrealtek " and " nicnatsemi "
1066need PCI configuration space read access and raw I/O port access.
1067.sp
1068.B atahpt
1069needs PCI configuration space access and raw I/O port access.
1070.sp
1071.BR gfxnvidia ", " drkaiser " and " it8212
1072need PCI configuration space access and raw memory access.
1073.sp
1074.B rayer_spi
1075needs raw I/O port access.
1076.sp
1077.BR satasii ", " nicintel ", " nicintel_eeprom " and " nicintel_spi
1078need PCI configuration space read access and raw memory access.
1079.sp
1080.BR satamv " and " atapromise
1081need PCI configuration space read access, raw I/O port access and raw memory
1082access.
1083.sp
1084.B serprog
1085needs TCP access to the network or userspace access to a serial port.
1086.sp
1087.B buspirate_spi
1088needs userspace access to a serial port.
1089.sp
1090.BR ft2232_spi ", " usbblaster_spi " and " pickit2_spi
1091need access to the respective USB device via libusb API version 0.1.
1092.sp
1093.BR ch341a_spi " and " dediprog
1094need access to the respective USB device via libusb API version 1.0.
1095.sp
1096.B dummy
1097needs no access permissions at all.
1098.sp
1099.BR internal ", " nic3com ", " nicrealtek ", " nicnatsemi ", "
1100.BR gfxnvidia ", " drkaiser ", " satasii ", " satamv ", " atahpt ", " atavia " and " atapromise
1101have to be run as superuser/root, and need additional raw access permission.
1102.sp
1103.BR serprog ", " buspirate_spi ", " dediprog ", " usbblaster_spi ", " ft2232_spi ", " pickit2_spi " and " \
1104ch341a_spi
1105can be run as normal user on most operating systems if appropriate device
1106permissions are set.
1107.sp
1108.B ogp
1109needs PCI configuration space read access and raw memory access.
1110.sp
1111On OpenBSD, you can obtain raw access permission by setting
1112.B "securelevel=-1"
1113in
1114.B "/etc/rc.securelevel"
1115and rebooting, or rebooting into single user mode.
1116.SH BUGS
1117Please report any bugs to the
1118.MTOB "flashrom@flashrom.org" "flashrom mailing list" .
1119.sp
1120We recommend to subscribe first at
1121.URLB "https://flashrom.org/mailman/listinfo/flashrom" "" .
1122.sp
1123Many of the developers communicate via the
1124.B "#flashrom"
1125IRC channel on
1126.BR chat.freenode.net .
1127If you don't have an IRC client, you can use the
1128.URLB http://webchat.freenode.net/?channels=flashrom "freenode webchat" .
1129You are welcome to join and ask questions, send us bug and success reports there
1130too. Please provide a way to contact you later (e.g.\& a mail address) and be
1131patient if there is no immediate reaction. Also, we provide a
1132.URLB https://paste.flashrom.org "pastebin service"
1133that is very useful when you want to share logs etc.\& without spamming the
1134channel.
1135.SS
1136.B Laptops
1137.sp
1138Using flashrom on laptops is dangerous and may easily make your hardware
1139unusable. flashrom will attempt to detect if it is running on a laptop and abort
1140immediately for safety reasons. Please see the detailed discussion of this topic
1141and associated flashrom options in the
1142.B Laptops
1143paragraph in the
1144.B internal programmer
1145subsection of the
1146.B PROGRAMMER-SPECIFIC INFORMATION
1147section and the information
1148.URLB "https://flashrom.org/Laptops" "in our wiki" .
1149.SS
1150One-time programmable (OTP) memory and unique IDs
1151.sp
1152Some flash chips contain OTP memory often denoted as "security registers".
1153They usually have a capacity in the range of some bytes to a few hundred
1154bytes and can be used to give devices unique IDs etc. flashrom is not able
1155to read or write these memories and may therefore not be able to duplicate a
1156chip completely. For chip types known to include OTP memories a warning is
1157printed when they are detected.
1158.sp
1159Similar to OTP memories are unique, factory programmed, unforgeable IDs.
1160They are not modifiable by the user at all.
1161.SH LICENSE
1162.B flashrom
1163is covered by the GNU General Public License (GPL), version 2. Some files are
1164additionally available under any later version of the GPL.
1165.SH COPYRIGHT
1166.br
1167Please see the individual files.
1168.SH AUTHORS
1169Andrew Morgan
1170.br
1171Carl-Daniel Hailfinger
1172.br
1173Claus Gindhart
1174.br
1175David Borg
1176.br
1177David Hendricks
1178.br
1179Dominik Geyer
1180.br
1181Eric Biederman
1182.br
1183Giampiero Giancipoli
1184.br
1185Helge Wagner
1186.br
1187Idwer Vollering
1188.br
1189Joe Bao
1190.br
1191Joerg Fischer
1192.br
1193Joshua Roys
1194.br
1195Ky\[:o]sti M\[:a]lkki
1196.br
1197Luc Verhaegen
1198.br
1199Li-Ta Lo
1200.br
1201Mark Marshall
1202.br
1203Markus Boas
1204.br
1205Mattias Mattsson
1206.br
1207Michael Karcher
1208.br
1209Nikolay Petukhov
1210.br
1211Patrick Georgi
1212.br
1213Peter Lemenkov
1214.br
1215Peter Stuge
1216.br
1217Reinder E.N. de Haan
1218.br
1219Ronald G. Minnich
1220.br
1221Ronald Hoogenboom
1222.br
1223Sean Nelson
1224.br
1225Stefan Reinauer
1226.br
1227Stefan Tauner
1228.br
1229Stefan Wildemann
1230.br
1231Stephan Guilloux
1232.br
1233Steven James
1234.br
1235Urja Rannikko
1236.br
1237Uwe Hermann
1238.br
1239Wang Qingpei
1240.br
1241Yinghai Lu
1242.br
1243some others, please see the flashrom svn changelog for details.
1244.br
1245All still active authors can be reached via
1246.MTOB "flashrom@flashrom.org" "the mailing list" .
1247.PP
1248This manual page was written by
1249.MTOB "uwe@hermann-uwe.de" "Uwe Hermann" ,
1250Carl-Daniel Hailfinger, Stefan Tauner and others.
1251It is licensed under the terms of the GNU GPL (version 2 or later).

Archive Download this file

Revision: HEAD