| .\" Load the www device when using groff; provide a fallback for groff's MTO macro that formats email addresses. |
| .ie \n[.g] \ |
| . mso www.tmac |
| .el \{ |
| . de MTO |
| \\$2 \(la\\$1 \(ra\\$3 \ |
| . . |
| .\} |
| .\" Create wrappers for .MTO and .URL that print only text on systems w/o groff or if not outputting to a HTML |
| .\" device. To that end we need to distinguish HTML output on groff from other configurations first. |
| .nr groffhtml 0 |
| .if \n[.g] \ |
| . if "\*[.T]"html" \ |
| . nr groffhtml 1 |
| .\" For code reuse it would be nice to have a single wrapper that gets its target macro as parameter. |
| .\" However, this did not work out with NetBSD's and OpenBSD's groff... |
| .de URLB |
| . ie (\n[groffhtml]==1) \{\ |
| . URL \\$@ |
| . \} |
| . el \{\ |
| . ie "\\$2"" \{\ |
| . BR "\\$1" "\\$3" |
| . \} |
| . el \{\ |
| . RB "\\$2 \(la" "\\$1" "\(ra\\$3" |
| . \} |
| . \} |
| .. |
| .de MTOB |
| . ie (\n[groffhtml]==1) \{\ |
| . MTO \\$@ |
| . \} |
| . el \{\ |
| . ie "\\$2"" \{\ |
| . BR "\\$1" "\\$3" |
| . \} |
| . el \{\ |
| . RB "\\$2 \(la" "\\$1" "\(ra\\$3" |
| . \} |
| . \} |
| .. |
| .TH FLASHPROG 8 "@MAN_DATE@" "flashprog-@VERSION@" "@MAN_DATE@" |
| .SH NAME |
| flashprog \- detect, read, write, verify and erase flash chips |
| .SH SYNOPSIS |
| Flashprog supports multiple command modes: |
| .sp |
| .BR flashprog " ([" prog ]| config | cfg | write-protect | wp ) |
| .sp |
| With |
| .B prog |
| being the default and described in this manual. For the other commands, see |
| .MR flashprog-config 8 ", and" |
| .MR flashprog-write-protect 8 . |
| .sp |
| .B flashprog \fR[\fB\-h\fR|\fB\-R\fR|\fB\-L\fR|\fB\-z\fR| |
| \fB\-p\fR <programmername>[:<parameters>] [\fB\-c\fR <chipname>] |
| (\fB\-\-flash\-name\fR|\fB\-\-flash\-size\fR| |
| [\fB\-E\fR|\fB\-r\fR <file>|\fB\-w\fR <file>|\fB\-v\fR <file>] |
| [(\fB\-l\fR <file>|\fB\-\-ifd\fR|\fB\-\-fmap\fR|\fB\-\-fmap-file\fR <file>) |
| [\fB\-i\fR <include>]...] |
| [\fB\-n\fR] [\fB\-N\fR] [\fB\-f\fR])] |
| [\fB\-V\fR[\fBV\fR[\fBV\fR]]] [\fB-o\fR <logfile>] [\fB\-\-progress\fR] |
| |
| .SH DESCRIPTION |
| .B flashprog |
| is a utility for detecting, reading, writing, verifying and erasing flash |
| chips. It's often used to flash BIOS/EFI/coreboot/firmware images in-system |
| using a supported mainboard. However, it also supports various external |
| PCI/USB/parallel-port/serial-port based devices which can program flash chips, |
| including some network cards (NICs), SATA/IDE controller cards, graphics cards, |
| the Bus Pirate device, various FTDI FT2232/FT4232H/FT232H based USB devices, and more. |
| .PP |
| It supports a wide range of DIP32, PLCC32, DIP8, SO8/SOIC8, TSOP32, TSOP40, |
| TSOP48, and BGA chips, which use various protocols such as LPC, FWH, |
| parallel flash, or SPI. |
| .SH OPTIONS |
| You can specify one of |
| .BR \-h ", " \-R ", " \-L ", " \-z ", " \-E ", " \-r ", " \-w ", " \-v |
| or no operation. |
| If no operation is specified, flashprog will only probe for flash chips. It is |
| recommended that if you try flashprog the first time on a system, you run it |
| in probe-only mode and check the output. Also you are advised to make a |
| backup of your current ROM contents with |
| .B \-r |
| before you try to write a new image. All operations involving any chip access (probe/read/write/...) require the |
| .B -p/--programmer |
| option to be used (please see below). |
| .TP |
| .B "\-r, \-\-read <file>" |
| Read flash ROM contents and save them into the given |
| .BR <file> . |
| If the file already exists, it will be overwritten. |
| .TP |
| .B "\-w, \-\-write (<file>|-)" |
| Write |
| .B <file> |
| into flash ROM. If |
| .B - |
| is provided instead, contents will be read from stdin. This will first automatically |
| .B erase |
| the chip, then write to it. |
| .sp |
| In the process the chip is also read several times. First an in-memory backup |
| is made for disaster recovery and to be able to skip regions that are |
| already equal to the image file. This copy is updated along with the write |
| operation. In case of erase errors it is even re-read completely. After |
| writing has finished and if verification is enabled, the whole flash chip is |
| read out and compared with the input image. |
| .TP |
| .B "\-n, \-\-noverify" |
| Skip the automatic verification of flash ROM contents after writing. Using this |
| option is |
| .B not |
| recommended, you should only use it if you know what you are doing and if you |
| feel that the time for verification takes too long. |
| .sp |
| Typical usage is: |
| .B "flashprog \-p prog \-n \-w <file>" |
| .sp |
| This option is only useful in combination with |
| .BR \-\-write . |
| .TP |
| .B "\-N, \-\-noverify-all" |
| Skip not included regions during automatic verification after writing (cf. |
| .BR "\-l " "and " "\-i" ). |
| You should only use this option if you are sure that communication with |
| the flash chip is reliable (e.g. when using the |
| .BR internal |
| programmer). Even if flashprog is instructed not to touch parts of the |
| flash chip, their contents could be damaged (e.g. due to misunderstood |
| erase commands). |
| .sp |
| This option is required to flash an Intel system with locked ME flash |
| region using the |
| .BR internal |
| programmer. It may be enabled by default in this case in the future. |
| .TP |
| .B "\-v, \-\-verify (<file>|-)" |
| Verify the flash ROM contents against the given |
| .BR <file> . |
| If |
| .BR - |
| is provided instead, contents will be read from stdin. |
| .TP |
| .B "\-E, \-\-erase" |
| Erase the flash ROM chip. |
| .TP |
| .B "\-V, \-\-verbose" |
| More verbose output. This option can be supplied multiple times |
| (max. 3 times, i.e. |
| .BR \-VVV ) |
| for even more debug output. |
| .TP |
| .B "\-c, \-\-chip" <chipname> |
| Probe only for the specified flash ROM chip. This option takes the chip name as |
| printed by |
| .B "flashprog \-L" |
| without the vendor name as parameter. Please note that the chip name is |
| case sensitive. |
| .TP |
| .B "\-f, \-\-force" |
| Force one or more of the following actions: |
| .sp |
| * Force chip read and pretend the chip is there. |
| .sp |
| * Force chip access even if the chip is bigger than the maximum supported \ |
| size for the flash bus. |
| .sp |
| * Force erase even if erase is known bad. |
| .sp |
| * Force write even if write is known bad. |
| .TP |
| .B "\-l, \-\-layout <file>" |
| Read ROM layout from |
| .BR <file> . |
| .sp |
| flashprog supports ROM layouts. This allows you to flash certain parts of |
| the flash chip only. A ROM layout file contains multiple lines with the |
| following syntax: |
| .sp |
| .B " startaddr:endaddr imagename" |
| .sp |
| .BR "startaddr " "and " "endaddr " |
| are hexadecimal addresses within the ROM file and do not refer to any |
| physical address. Please note that using a 0x prefix for those hexadecimal |
| numbers is not necessary, but you can't specify decimal/octal numbers. |
| .BR "imagename " "is an arbitrary name for the region/image from" |
| .BR " startaddr " "to " "endaddr " "(both addresses included)." |
| .sp |
| Example: |
| .sp |
| 00000000:00008fff gfxrom |
| 00009000:0003ffff normal |
| 00040000:0007ffff fallback |
| .sp |
| If you only want to update the image named |
| .BR "normal " "in a ROM based on the layout above, run" |
| .sp |
| .B " flashprog \-p prog \-\-layout rom.layout \-\-image normal \-w some.rom" |
| .sp |
| To update only the images named |
| .BR "normal " "and " "fallback" ", run:" |
| .sp |
| .B " flashprog \-p prog \-l rom.layout \-i normal -i fallback \-w some.rom" |
| .sp |
| Overlapping sections are not supported. |
| .TP |
| .B "\-\-fmap" |
| Read layout from fmap in flash chip. |
| .sp |
| flashprog supports the fmap binary format which is commonly used by coreboot |
| for partitioning a flash chip. The on-chip fmap will be read and used to generate |
| the layout. |
| .sp |
| If you only want to update the |
| .BR "COREBOOT" |
| region defined in the fmap, run |
| .sp |
| .B " flashprog -p prog \-\-fmap \-\-image COREBOOT \-w some.rom" |
| .TP |
| .B "\-\-fmap-file <file>" |
| Read layout from a |
| .BR <file> |
| containing binary fmap (e.g. coreboot roms). |
| .sp |
| flashprog supports the fmap binary format which is commonly used by coreboot |
| for partitioning a flash chip. The fmap in the specified file will be read and |
| used to generate the layout. |
| .sp |
| If you only want to update the |
| .BR "COREBOOT" |
| region defined in the binary fmap file, run |
| .sp |
| .B " flashprog \-p prog \-\-fmap-file some.rom \-\-image COREBOOT \-w some.rom" |
| .TP |
| .B "\-\-ifd" |
| Read ROM layout from Intel Firmware Descriptor. |
| .sp |
| flashprog supports ROM layouts given by an Intel Firmware Descriptor |
| (IFD). The on-chip descriptor will be read and used to generate the |
| layout. If you need to change the layout, you have to update the IFD |
| only first. |
| .sp |
| The following ROM images may be present in an IFD: |
| .sp |
| fd the IFD itself |
| bios the host firmware aka. BIOS |
| me Intel Management Engine firmware |
| gbe gigabit ethernet firmware |
| pd platform specific data |
| .TP |
| .B "\-i, \-\-image <imagename>" |
| Only flash region/image |
| .B <imagename> |
| from flash layout. |
| .TP |
| .B "\-\-flash\-name" |
| Prints out the detected flash chips name. |
| .TP |
| .B "\-\-flash\-size" |
| Prints out the detected flash chips size. |
| .TP |
| .B "\-\-flash\-contents <ref\-file>" |
| The file contents of |
| .BR <ref\-file> |
| will be used to decide which parts of the flash need to be written. Providing |
| this saves an initial read of the full flash chip. Be careful, if the provided |
| data doesn't actually match the flash contents, results are undefined. |
| .TP |
| .B "\-L, \-\-list\-supported" |
| List the flash chips, chipsets, mainboards, and external programmers |
| (including PCI, USB, parallel port, and serial port based devices) |
| supported by flashprog. |
| .sp |
| There are many unlisted boards which will work out of the box, without |
| special support in flashprog. Please let us know if you can verify that |
| other boards work or do not work out of the box. |
| .sp |
| .B IMPORTANT: |
| For verification you have |
| to test an ERASE and/or WRITE operation, so make sure you only do that |
| if you have proper means to recover from failure! |
| .TP |
| .B "\-z, \-\-list\-supported-wiki" |
| Same as |
| .BR \-\-list\-supported , |
| but outputs the supported hardware in MediaWiki syntax, so that it can be |
| easily pasted into the |
| .URLB https://flashprog.org/Supported_hardware "supported hardware wiki page" . |
| Please note that MediaWiki output is not compiled in by default. |
| .TP |
| .B "\-p, \-\-programmer <name>[:parameter[,parameter[,parameter]]]" |
| Specify the programmer device. This is mandatory for all operations |
| involving any chip access (probe/read/write/...). Currently supported are: |
| .sp |
| .BR "* internal" " (for in-system flashing in the mainboard)" |
| .sp |
| .BR "* dummy" " (virtual programmer for testing flashprog)" |
| .sp |
| .BR "* nic3com" " (for flash ROMs on 3COM network cards)" |
| .sp |
| .BR "* nicrealtek" " (for flash ROMs on Realtek and SMC 1211 network cards)" |
| .sp |
| .BR "* nicnatsemi" " (for flash ROMs on National Semiconductor DP838* network \ |
| cards)" |
| .sp |
| .BR "* nicintel" " (for parallel flash ROMs on Intel 10/100Mbit network cards) |
| .sp |
| .BR "* gfxnvidia" " (for flash ROMs on NVIDIA graphics cards)" |
| .sp |
| .BR "* drkaiser" " (for flash ROMs on Dr. Kaiser PC-Waechter PCI cards)" |
| .sp |
| .BR "* satasii" " (for flash ROMs on Silicon Image SATA/IDE controllers)" |
| .sp |
| .BR "* satamv" " (for flash ROMs on Marvell SATA controllers)" |
| .sp |
| .BR "* atahpt" " (for flash ROMs on Highpoint ATA/RAID controllers)" |
| .sp |
| .BR "* atavia" " (for flash ROMs on VIA VT6421A SATA controllers)" |
| .sp |
| .BR "* atapromise" " (for flash ROMs on Promise PDC2026x ATA/RAID controllers)" |
| .sp |
| .BR "* it8212" " (for flash ROMs on ITE IT8212F ATA/RAID controller)" |
| .sp |
| .BR "* ft2232_spi" " (for SPI flash ROMs attached to an FT2232/FT4232H/FT232H family based USB SPI programmer). |
| .sp |
| .BR "* ft4222_spi" " (for SPI and QPI flash ROMs attached to an FT4222H based USB programmer). |
| .sp |
| .BR "* serprog" " (for flash ROMs attached to a programmer speaking serprog, \ |
| including some Arduino-based devices)." |
| .sp |
| .BR "* buspirate_spi" " (for SPI flash ROMs attached to a Bus Pirate)" |
| .sp |
| .BR "* dediprog" " (for SPI flash ROMs attached to a Dediprog SF100/SF200/SF600/SF700)" |
| .sp |
| .BR "* rayer_spi" " (for SPI flash ROMs attached to a parallel port by one of various cable types)" |
| .sp |
| .BR "* pony_spi" " (for SPI flash ROMs attached to a SI-Prog serial port " |
| bitbanging adapter) |
| .sp |
| .BR "* nicintel_spi" " (for SPI flash ROMs on Intel Gigabit network cards)" |
| .sp |
| .BR "* ogp_spi" " (for SPI flash ROMs on Open Graphics Project graphics card)" |
| .sp |
| .BR "* linux_gpio_spi" " (for SPI flash ROMs attached to a GPIO chip device accessible via /dev/gpiochipX on Linux)" |
| .sp |
| .BR "* linux_mtd" " (for SPI flash ROMs accessible via /dev/mtdX on Linux)" |
| .sp |
| .BR "* linux_spi" " (for SPI flash ROMs accessible via /dev/spidevX.Y on Linux)" |
| .sp |
| .BR "* usbblaster_spi" " (for SPI flash ROMs attached to an Altera USB-Blaster compatible cable)" |
| .sp |
| .BR "* nicintel_eeprom" " (for SPI EEPROMs on Intel Gigabit network cards)" |
| .sp |
| .BR "* mstarddc_spi" " (for SPI flash ROMs accessible through DDC in MSTAR-equipped displays)" |
| .sp |
| .BR "* pickit2_spi" " (for SPI flash ROMs accessible via Microchip PICkit2)" |
| .sp |
| .BR "* ch341a_spi" " (for SPI flash ROMs attached to WCH CH341A)" |
| .sp |
| .BR "* ch347_spi" " (for SPI flash ROMs attached to WCH CH347)" |
| .sp |
| .BR "* digilent_spi" " (for SPI flash ROMs attached to iCEblink40 development boards)" |
| .sp |
| .BR "* jlink_spi" " (for SPI flash ROMs attached to SEGGER J-Link and compatible devices)" |
| .sp |
| .BR "* ni845x_spi" " (for SPI flash ROMs attached to National Instruments USB-8451 or USB-8452)" |
| .sp |
| .BR "* stlinkv3_spi" " (for SPI flash ROMs attached to STMicroelectronics STLINK V3 devices)" |
| .sp |
| .BR "* dirtyjtag_spi" " (for SPI flash ROMs attached to DirtyJTAG-compatible devices)" |
| .sp |
| Some programmers have optional or mandatory parameters which are described |
| in detail in the |
| .B PROGRAMMER-SPECIFIC INFORMATION |
| section. Support for some programmers can be disabled at compile time. |
| .B "flashprog \-h" |
| lists all supported programmers. |
| .TP |
| .B "\-h, \-\-help" |
| Show a help text and exit. |
| .TP |
| .B "\-o, \-\-output <logfile>" |
| Save the full debug log to |
| .BR <logfile> . |
| If the file already exists, it will be overwritten. This is the recommended |
| way to gather logs from flashprog because they will be verbose even if the |
| on-screen messages are not verbose and don't require output redirection. |
| .TP |
| .B "\-\-progress" |
| Show progress percentage of operations on the standard output. |
| .TP |
| .B "\-R, \-\-version" |
| Show version information and exit. |
| .SH PROGRAMMER-SPECIFIC INFORMATION |
| Some programmer drivers accept further parameters to set programmer-specific |
| parameters. These parameters are separated from the programmer name by a |
| 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. |
| .SS |
| .BR "internal " programmer |
| .TP |
| .B Board Enables |
| .sp |
| 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), or if you want to override |
| the detected mainboard model, you can specify the mainboard using the |
| .sp |
| .B " flashprog \-p internal:mainboard=<vendor>:<board>" |
| syntax. |
| .sp |
| See the 'Known boards' or 'Known laptops' section in the output |
| of 'flashprog \-L' for a list of boards which require the specification of |
| the board name, if no coreboot table is found. |
| .sp |
| Some of these board-specific flash enabling functions (called |
| .BR "board enables" ) |
| in flashprog 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), |
| flashprog 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 flashprog 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 " flashprog \-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 |
| .BR \-r ) |
| and store it to a medium outside of your computer, like |
| a USB drive or a network share. If you needed to run the board enable code |
| already for probing, use it for reading too. |
| If reading succeeds and the contents of the read file look legit 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 flashprog mailing list, see below. |
| .sp |
| .TP |
| .B Coreboot |
| .sp |
| On systems running coreboot, flashprog checks whether the desired image matches |
| your mainboard. This needs some special board ID to be present in the image. |
| If flashprog detects that the image you want to write and the current board |
| do not match, it will refuse to write the image unless you specify |
| .sp |
| .B " flashprog \-p internal:boardmismatch=force" |
| .TP |
| .B ITE IT87 Super I/O |
| .sp |
| If your mainboard is manufactured by GIGABYTE and supports DualBIOS it is very likely that it uses an |
| ITE IT87 series Super I/O to switch between the two flash chips. Only one of them can be accessed at a time |
| and you can manually select which one to use with the |
| .sp |
| .B " flashprog \-p internal:dualbiosindex=chip" |
| .sp |
| syntax where |
| .B chip |
| is the index of the chip to use (0 = main, 1 = backup). You can check which one is currently selected by |
| leaving out the |
| .B chip |
| parameter. |
| .sp |
| If your mainboard uses an ITE IT87 series Super I/O for LPC<->SPI flash bus |
| translation, flashprog 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 " flashprog \-p internal:it87spiport=portnum" |
| .sp |
| syntax where |
| .B portnum |
| is the I/O port number (must be a multiple of 8). In the unlikely case |
| flashprog doesn't detect an active IT87 LPC<->SPI bridge, please send a bug |
| report so we can diagnose the problem. |
| .sp |
| .TP |
| .B AMD chipsets |
| .sp |
| Beginning with the SB700 chipset there is an integrated microcontroller (IMC) based on the 8051 embedded in |
| every AMD southbridge. Its firmware resides in the same flash chip as the host's which makes writing to the |
| flash risky if the IMC is active. Flashprog tries to temporarily disable the IMC but even then changing the |
| contents of the flash can have unwanted effects: when the IMC continues (at the latest after a reboot) it will |
| continue executing code from the flash. If the code was removed or changed in an unfortunate way it is |
| unpredictable what the IMC will do. Therefore, if flashprog detects an active IMC it will disable write support |
| unless the user forces it with the |
| .sp |
| .B " flashprog \-p internal:amd_imc_force=yes" |
| .sp |
| syntax. The user is responsible for supplying a suitable image or leaving out the IMC region with the help of |
| a layout file. This limitation might be removed in the future when we understand the details better and have |
| received enough feedback from users. Please report the outcome if you had to use this option to write a chip. |
| .sp |
| An optional |
| .B spispeed |
| parameter specifies the frequency of the SPI bus where applicable (i.e.\& SB600 or later with an SPI flash chip |
| directly attached to the chipset). |
| Syntax is |
| .sp |
| .B " flashprog \-p internal:spispeed=frequency" |
| .sp |
| where |
| .B frequency |
| can be |
| .BR "'16.5\ MHz'" ", " "'22\ MHz'" ", " "'33\ MHz'" ", " "'66\ MHz'" ", " "'100\ MHZ'" ", or " "'800\ kHz'" "." |
| Support of individual frequencies depends on the generation of the chipset: |
| .sp |
| * SB6xx, SB7xx, SP5xxx: from 16.5 MHz up to and including 33 MHz |
| .sp |
| * SB8xx, SB9xx, Hudson: from 16.5 MHz up to and including 66 MHz |
| .sp |
| * Yangtze (with SPI 100 engine as found in Kabini and Tamesh): all of them |
| .sp |
| The default is to use 16.5 MHz and disable Fast Reads. |
| .TP |
| .B Intel chipsets |
| .sp |
| If you have an Intel chipset with an ICH8 or later southbridge with SPI flash |
| attached, and if a valid descriptor was written to it (e.g.\& by the vendor), the |
| chipset provides an alternative way to access the flash chip(s) named |
| .BR "Hardware Sequencing" . |
| It is much simpler than the normal access method (called |
| .BR "Software Sequencing" ")," |
| but does not allow the software to choose the SPI commands to be sent. |
| You can use the |
| .sp |
| .B " flashprog \-p internal:ich_spi_mode=value" |
| .sp |
| syntax where |
| .BR "value " "can be" |
| .BR auto ", " swseq " or " hwseq . |
| By default |
| .RB "(or when setting " ich_spi_mode=auto ) |
| the module tries to use swseq and only activates hwseq if need be (e.g.\& if |
| important opcodes are inaccessible due to lockdown; or if more than one flash |
| chip is attached). The other options (swseq, hwseq) select the respective mode |
| (if possible). |
| .sp |
| ICH8 and later southbridges may also have locked address ranges of different |
| kinds if a valid descriptor was written to it. The flash address space is then |
| partitioned in multiple so called "Flash Regions" containing the host firmware, |
| the ME firmware and so on respectively. The flash descriptor can also specify up |
| to 5 so called "Protected Regions", which are freely chosen address ranges |
| independent from the aforementioned "Flash Regions". All of them can be write |
| and/or read protected individually. |
| .sp |
| If you have an Intel chipset with an ICH2 or later southbridge and if you want |
| to set specific IDSEL values for a non-default flash chip or an embedded |
| controller (EC), you can use the |
| .sp |
| .B " flashprog \-p internal:fwh_idsel=value" |
| .sp |
| syntax where |
| .B value |
| is the 48-bit hexadecimal raw value to be written in the |
| IDSEL registers of the Intel southbridge. The upper 32 bits use one hex digit |
| each per 512 kB range between 0xffc00000 and 0xffffffff, and the lower 16 bits |
| use one hex digit each per 1024 kB range between 0xff400000 and 0xff7fffff. |
| The rightmost hex digit corresponds with the lowest address range. All address |
| ranges have a corresponding sister range 4 MB below with identical IDSEL |
| settings. The default value for ICH7 is given in the example below. |
| .sp |
| Example: |
| .B "flashprog \-p internal:fwh_idsel=0x001122334567" |
| .TP |
| .B Laptops |
| .sp |
| Using flashprog on older laptops that don't boot from the SPI bus is |
| dangerous and may easily make your hardware unusable (see also the |
| .B BUGS |
| section). The embedded controller (EC) in some |
| machines may interact badly with flashing. |
| More information is |
| .URLB https://flashprog.org/Laptops "in the wiki" . |
| Problems occur when the flash chip is shared between BIOS |
| and EC firmware, and the latter does not expect flashprog |
| to access the chip. While flashprog tries to change the contents of |
| that memory the EC might need to fetch new instructions or data from it and |
| could stop working correctly. Probing for and reading from the chip may also |
| irritate your EC and cause fan failure, backlight failure, sudden poweroff, and |
| other nasty effects. flashprog will attempt to detect if it is running on such a |
| laptop and limit probing to SPI buses. If you want to probe the LPC bus |
| anyway at your own risk, use |
| .sp |
| .B " flashprog \-p internal:laptop=force_I_want_a_brick" |
| .sp |
| We will not help you if you force flashing on a laptop because this is a really |
| dumb idea. |
| .sp |
| You have been warned. |
| .sp |
| Currently we rely on the chassis type encoded in the DMI/SMBIOS data to detect |
| laptops. Some vendors did not implement those bits correctly or set them to |
| generic and/or dummy values. flashprog will then issue a warning and restrict |
| buses like above. In this case you can use |
| .sp |
| .B " flashprog \-p internal:laptop=this_is_not_a_laptop" |
| .sp |
| to tell flashprog (at your own risk) that it is not running on a laptop. |
| .SS |
| .BR "dummy " programmer |
| .IP |
| The dummy programmer operates on a buffer in memory only. It provides a safe and fast way to test various |
| aspects of flashprog and is mainly used in development and while debugging. |
| It is able to emulate some chips to a certain degree (basic |
| identify/read/erase/write operations work). |
| .sp |
| An optional parameter specifies the bus types it |
| should support. For that you have to use the |
| .sp |
| .B " flashprog \-p dummy:bus=[type[+type[+type]]]" |
| .sp |
| syntax where |
| .B type |
| can be |
| .BR parallel ", " lpc ", " fwh ", " spi |
| in any order. If you specify bus without type, all buses will be disabled. |
| If you do not specify bus, all buses will be enabled. |
| .sp |
| Example: |
| .B "flashprog \-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 " flashprog \-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 (128 kB, RES, page write)" |
| .sp |
| .RB "* SST " SST25VF040.REMS " SPI flash chip (512 kB, REMS, byte write)" |
| .sp |
| .RB "* SST " SST25VF032B " SPI flash chip (4096 kB, RDID, AAI write)" |
| .sp |
| .RB "* Macronix " MX25L6436 " SPI flash chip (8192 kB, RDID, SFDP)" |
| .sp |
| .RB "* Winbond " W25Q128FV " SPI flash chip (16384 kB, RDID)" |
| .sp |
| .RB "* Spansion " S25FL128L " SPI flash chip (16384 kB, RDID)" |
| .sp |
| Example: |
| .B "flashprog -p dummy:emulate=SST25VF040.REMS" |
| .TP |
| .B Persistent images |
| .sp |
| If you use flash chip emulation, flash image persistence is available as well |
| by using the |
| .sp |
| .B " flashprog \-p dummy:emulate=chip,image=image.rom" |
| .sp |
| syntax where |
| .B image.rom |
| is the file where the simulated chip contents are read on flashprog startup and |
| where the chip contents on flashprog shutdown are written to. |
| .sp |
| Example: |
| .B "flashprog -p dummy:emulate=M25P10.RES,image=dummy.bin" |
| .TP |
| .B SPI write chunk size |
| .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 " flashprog \-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: |
| .sp |
| .B " flashprog -p dummy:emulate=M25P10.RES,spi_write_256_chunksize=5" |
| .TP |
| .B SPI blacklist |
| .sp |
| To simulate a programmer which refuses to send certain SPI commands to the |
| flash chip, you can specify a blacklist of SPI commands with the |
| .sp |
| .B " flashprog -p dummy:spi_blacklist=commandlist" |
| .sp |
| syntax where |
| .B commandlist |
| is a list of two-digit hexadecimal representations of |
| SPI commands. If commandlist is e.g.\& 0302, flashprog will behave as if the SPI |
| controller refuses to run command 0x03 (READ) and command 0x02 (WRITE). |
| commandlist may be up to 512 characters (256 commands) long. |
| Implementation note: flashprog will detect an error during command execution. |
| .sp |
| .TP |
| .B SPI ignorelist |
| .sp |
| To simulate a flash chip which ignores (doesn't support) certain SPI commands, |
| you can specify an ignorelist of SPI commands with the |
| .sp |
| .B " flashprog -p dummy:spi_ignorelist=commandlist" |
| .sp |
| syntax where |
| .B commandlist |
| is a list of two-digit hexadecimal representations of |
| SPI commands. If commandlist is e.g.\& 0302, the emulated flash chip will ignore |
| command 0x03 (READ) and command 0x02 (WRITE). commandlist may be up to 512 |
| characters (256 commands) long. |
| Implementation note: flashprog won't detect an error during command execution. |
| .sp |
| .TP |
| .B SPI status register |
| .sp |
| You can specify the initial content of the chip's status register with the |
| .sp |
| .B " flashprog -p dummy:spi_status=content" |
| .sp |
| syntax where |
| .B content |
| is a hexadecimal value of up to 24 bits. For example, 0x332211 assigns 0x11 to |
| SR1, 0x22 to SR2 and 0x33 to SR3. Shorter value is padded to 24 bits with |
| zeroes on the left. See datasheet for chosen chip for details about the |
| registers content. |
| .sp |
| .TP |
| .B Write protection |
| .sp |
| Chips with emulated WP: W25Q128FV, S25FL128L. |
| .sp |
| You can simulate state of hardware protection pin (WP) with the |
| .sp |
| .B " flashprog -p dummy:hwwp=state" |
| .sp |
| syntax where |
| .B state |
| is "yes" or "no" (default value). "yes" means active state of the pin implies |
| that chip is write-protected (on real hardware the pin is usually negated, but |
| not here). |
| .SS |
| .BR "nic3com" , " nicrealtek" , " nicnatsemi" , " nicintel", " nicintel_eeprom"\ |
| , " nicintel_spi" , " gfxnvidia" , " ogp_spi" , " drkaiser" , " satasii"\ |
| , " satamv" , " atahpt", " atavia ", " atapromise " and " it8212 " programmers |
| .IP |
| 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 |
| .sp |
| .BR " flashprog \-p xxxx:pci=bb:dd.f" , |
| .sp |
| where |
| .B xxxx |
| is the name of the programmer, |
| .B bb |
| is the PCI bus number, |
| .B dd |
| is the PCI device number, and |
| .B f |
| is the PCI function number of the desired device. |
| .sp |
| Example: |
| .B "flashprog \-p nic3com:pci=05:04.0" |
| .SS |
| .BR "atavia " programmer |
| .IP |
| Due to the mysterious address handling of the VIA VT6421A controller the user can specify an offset with the |
| .sp |
| .B " flashprog \-p atavia:offset=addr" |
| .sp |
| syntax where |
| .B addr |
| will be interpreted as usual (leading 0x (0) for hexadecimal (octal) values, or else decimal). |
| For more information please see |
| .URLB https://flashprog.org/VT6421A "its wiki page" . |
| .SS |
| .BR "atapromise " programmer |
| .IP |
| This programmer is currently limited to 32 kB, regardless of the actual size of the flash chip. This stems |
| from the fact that, on the tested device (a Promise Ultra100), not all of the chip's address lines were |
| actually connected. You may use this programmer to flash firmware updates, since these are only 16 kB in |
| size (padding to 32 kB is required). |
| .SS |
| .BR "nicintel_eeprom " programmer |
| .IP |
| This is the first programmer module in flashprog that does not provide access to NOR flash chips but EEPROMs |
| mounted on gigabit Ethernet cards based on Intel's 82580 NIC. Because EEPROMs normally do not announce their |
| size nor allow themselves to be identified, the controller relies on correct size values written to predefined |
| addresses within the chip. Flashprog follows this scheme but assumes the minimum size of 16 kB (128 kb) if an |
| unprogrammed EEPROM/card is detected. Intel specifies following EEPROMs to be compatible: |
| Atmel AT25128, AT25256, Micron (ST) M95128, M95256 and OnSemi (Catalyst) CAT25CS128. |
| .SS |
| .BR "ft2232_spi " programmer |
| .IP |
| This module supports various programmers based on FTDI FT2232/FT4232H/FT4233H/FT232H chips including the DLP Design |
| DLP-USB1232H, openbiosprog-spi, Amontec JTAGkey/JTAGkey-tiny/JTAGkey-2, Dangerous Prototypes Bus Blaster, |
| Olimex ARM-USB-TINY/-H, Olimex ARM-USB-OCD/-H, OpenMoko Neo1973 Debug board (V2+), TIAO/DIYGADGET USB |
| Multi-Protocol Adapter (TUMPA), TUMPA Lite, GOEPEL PicoTAP, Google Servo v1/v2, Tin Can Tools |
| Flyswatter/Flyswatter 2 and Kristech KT-LINK. |
| .sp |
| An optional parameter specifies the controller |
| type, channel/interface/port it should support. For that you have to use the |
| .sp |
| .B " flashprog \-p ft2232_spi:type=model,port=interface" |
| .sp |
| syntax where |
| .B model |
| can be |
| .BR 2232H ", " 4232H ", " 232H ", " jtagkey ", " busblaster ", " openmoko ", " \ |
| arm-usb-tiny ", " arm-usb-tiny-h ", " arm-usb-ocd ", " arm-usb-ocd-h \ |
| ", " tumpa ", " tumpalite ", " picotap ", " google-servo ", " google-servo-v2 \ |
| ", " google-servo-v2-legacy " or " kt-link |
| .B interface |
| can be |
| .BR A ", " B ", " C ", or " D . |
| The default model is |
| .B 4232H |
| the default interface is |
| .BR A |
| and GPIO is not used by default. |
| .sp |
| If there is more than one ft2232_spi-compatible device connected, you can select which one should be used by |
| specifying its serial number with the |
| .sp |
| .B " flashprog \-p ft2232_spi:serial=number" |
| .sp |
| syntax where |
| .B number |
| is the serial number of the device (which can be found for example in the output of lsusb -v). |
| .sp |
| All models supported by the ft2232_spi driver can configure the SPI clock rate by setting a divisor. The |
| expressible divisors are all |
| .B even |
| numbers between 2 and 2^17 (=131072) resulting in SPI clock frequencies of |
| 6 MHz down to about 92 Hz for 12 MHz inputs (non-H chips) and 30 MHz down to about 458 Hz for 60 MHz inputs ('H' chips). The default |
| divisor is set to 2, but you can use another one by specifying the optional |
| .B divisor |
| parameter with the |
| .sp |
| .B " flashprog \-p ft2232_spi:divisor=div" |
| .sp |
| syntax. |
| .sp |
| Using the parameter |
| .B csgpiol (DEPRECATED - use gpiol instead) |
| an additional CS# pin can be chosen, where the value can be a number between 0 and 3, denoting GPIOL0-GPIOL3 |
| correspondingly. Example: |
| .sp |
| .B " flashprog \-p ft2232_spi:csgpiol=3" |
| .sp |
| The parameter |
| .B gpiolX=[HLC] |
| allows use of the GPIOL pins either as generic gpios with a fixed value during flashing or as additional CS# |
| signal, where |
| .B X |
| can be a number between 0 and 3, denoting GPIOL0-GPIOL3 correspondingly. The parameter may be specified |
| multiple times, one time per GPIOL pin. |
| Valid values are |
| .B H |
| , |
| .B L |
| and |
| .B C |
| : |
| .br |
| .B " H " |
| - Set GPIOL output high |
| .br |
| .B " L " |
| - Set GPIOL output low |
| .br |
| .B " C " |
| - Use GPIOL as additional CS# output |
| .sp |
| .B Example: |
| .sp |
| .B " flashprog \-p ft2232_spi:gpiol0=H" |
| .sp |
| .B Note |
| that not all GPIOL pins are freely usable with all programmers as some have special functionality. |
| .SS |
| .BR "ft4222_spi " programmer |
| .IP |
| This driver supports programmers based on the FTDI FT4222H chip. |
| .sp |
| An optional |
| .B cs |
| parameter can be used to select the USB interface and respective CS# |
| output |
| .BR 0 .. 3 ", e.g." |
| .sp |
| .B " flashprog \-p ft4222_spi:cs=3" |
| .sp |
| The ft4222_spi driver supports setting the SPI clock rate in kHz with |
| the |
| .B spispeed |
| parameter. The actual clock rate will be rounded down to a supported |
| value (power-of-2 fractions of 80MHz, 60MHz and 48MHz base clocks). |
| Hence the highest supported SPI clock rates are 40MHz, 30MHz, 24Mhz, |
| 20MHz, 15MHz, 12MHz, and so forth. As this also affects the base clock |
| of the controller and thereby the overall bandwidth, there is a wrinkle: |
| Quad-i/o reads can actually be faster at 20MHz (80MHz base clock) than |
| they are at 30MHz or 24MHz with a lower base clock. |
| .sp |
| .B " flashprog \-p ft4222_spi:spispeed=20000" |
| .sp |
| The default is 10MHz. |
| .sp |
| As the FT4222H supports dual and quad i/o, there is an additional |
| .B iomode |
| parameter to specify how many lines can be used for bidirectional i/o. |
| Valid values are |
| .BR single ", " dual ", or " quad . |
| The default is |
| .B dual |
| as at least two lines are always connected (MOSI and MISO). Quad i/o |
| is most useful to get high transfer rates when the hardware setup is |
| not reliable enough for high clock rates, e.g. |
| .sp |
| .B " flashprog \-p ft4222_spi:spispeed=15000,iomode=quad" |
| .sp |
| Note that the overall bandwidth of the FT4222H is limited to |
| 52.8Mb/s (with the 80MHz base clock). This is almost saturated |
| at 20MHz x4. |
| .SS |
| .BR "serprog " programmer |
| .IP |
| This module supports all programmers speaking the serprog protocol. This includes some Arduino-based devices |
| as well as various programmers by Urja Rannikko, Juhana Helovuo, Stefan Tauner, Chi Zhang and many others. |
| .sp |
| A mandatory parameter specifies either a serial device (and baud rate) or an IP/port combination for |
| communicating with the programmer. |
| The device/baud combination has to start with |
| .B dev= |
| and separate the optional baud rate with a colon. |
| For example |
| .sp |
| .B " flashprog \-p serprog:dev=/dev/ttyS0:115200" |
| .sp |
| If no baud rate is given the default values by the operating system/hardware will be used. |
| For IP connections you have to use the |
| .sp |
| .B " flashprog \-p serprog:ip=ipaddr:port" |
| .sp |
| syntax. |
| In case the device supports it, you can set the SPI clock frequency with the optional |
| .B spispeed |
| parameter. The frequency is parsed as hertz, unless an |
| .BR M ", or " k |
| suffix is given, then megahertz or kilohertz are used respectively. |
| Example that sets the frequency to 2 MHz: |
| .sp |
| .B " flashprog \-p serprog:dev=/dev/ttyACM0,spispeed=2M" |
| .sp |
| In case the device supports it, you can set which SPI Chip Select to use with the optional |
| .B cs |
| parameter. Example that tells the programmer to use chip select number 0: |
| .sp |
| .B " flashprog \-p serprog:dev=/dev/ttyACM0:cs=0" |
| .sp |
| More information about serprog is available in |
| .B serprog-protocol.txt |
| in the source distribution. |
| .SS |
| .BR "buspirate_spi " programmer |
| .IP |
| A required |
| .B dev |
| parameter specifies the Bus Pirate device node and an optional |
| .B spispeed |
| parameter specifies the frequency of the SPI bus. The parameter |
| delimiter is a comma. Syntax is |
| .sp |
| .B " flashprog \-p buspirate_spi:dev=/dev/device,spispeed=frequency" |
| .sp |
| where |
| .B frequency |
| can be |
| .BR 30k ", " 125k ", " 250k ", " 1M ", " 2M ", " 2.6M ", " 4M " or " 8M |
| (in Hz). The default is the maximum frequency of 8 MHz. |
| .sp |
| The baud rate for communication between the host and the Bus Pirate can be specified with the optional |
| .B serialspeed |
| parameter. Syntax is |
| .sp |
| .B " flashprog -p buspirate_spi:serialspeed=baud |
| .sp |
| where |
| .B baud |
| can be |
| .BR 115200 ", " 230400 ", " 250000 " or " 2000000 " (" 2M ")." |
| The default is 2M baud for Bus Pirate hardware version 3.0 and greater, and 115200 otherwise. |
| .sp |
| An optional pullups parameter specifies the use of the Bus Pirate internal pull-up resistors. This may be |
| needed if you are working with a flash ROM chip that you have physically removed from the board. Syntax is |
| .sp |
| .B " flashprog -p buspirate_spi:pullups=state" |
| .sp |
| where |
| .B state |
| can be |
| .BR on " or " off . |
| More information about the Bus Pirate pull-up resistors and their purpose is available |
| .URLB "http://dangerousprototypes.com/docs/Practical_guide_to_Bus_Pirate_pull-up_resistors" \ |
| "in a guide by dangerousprototypes" . |
| .sp |
| The state of the Bus Pirate power supply pins is controllable through an optional |
| .B psus |
| parameter. Syntax is |
| .sp |
| .B " flashprog -p buspirate_spi:psus=state" |
| .sp |
| where |
| .B state |
| can be |
| .BR on " or " off . |
| This allows the bus pirate to power the ROM chip directly. This may also be used to provide the |
| required pullup voltage (when using the |
| .B pullups |
| option), by connecting the Bus Pirate's Vpu input to the appropriate Vcc pin. |
| .SS |
| .BR "pickit2_spi " programmer |
| .IP |
| An optional |
| .B voltage |
| parameter specifies the voltage the PICkit2 should use. The default unit is Volt if no unit is specified. |
| You can use |
| .BR mV ", " millivolt ", " V " or " Volt |
| as unit specifier. Syntax is |
| .sp |
| .B " flashprog \-p pickit2_spi:voltage=value" |
| .sp |
| where |
| .B value |
| can be |
| .BR 0V ", " 1.8V ", " 2.5V ", " 3.5V |
| or the equivalent in mV. |
| .sp |
| An optional |
| .B spispeed |
| parameter specifies the frequency of the SPI bus. Syntax is |
| .sp |
| .B " flashprog \-p pickit2_spi:spispeed=frequency" |
| .sp |
| where |
| .B frequency |
| can be |
| .BR 250k ", " 333k ", " 500k " or " 1M " |
| (in Hz). The default is a frequency of 1 MHz. |
| .SS |
| .BR "dediprog " programmer |
| .IP |
| An optional |
| .B voltage |
| parameter specifies the voltage the Dediprog should use. The default unit is |
| Volt if no unit is specified. You can use |
| .BR mV ", " milliVolt ", " V " or " Volt |
| as unit specifier. Syntax is |
| .sp |
| .B " flashprog \-p dediprog:voltage=value" |
| .sp |
| where |
| .B value |
| can be |
| .BR 0V ", " 1.8V ", " 2.5V ", " 3.5V |
| or the equivalent in mV. |
| .sp |
| An optional |
| .B device |
| parameter specifies which of multiple connected Dediprog devices should be used. |
| Please be aware that the order depends on libusb's usb_get_busses() function and that the numbering starts |
| at 0. |
| Usage example to select the second device: |
| .sp |
| .B " flashprog \-p dediprog:device=1" |
| .sp |
| An optional |
| .B spispeed |
| parameter specifies the frequency of the SPI bus. The firmware on the device needs to be 5.0.0 or newer. |
| Syntax is |
| .sp |
| .B " flashprog \-p dediprog:spispeed=frequency" |
| .sp |
| where |
| .B frequency |
| can be |
| .BR 375k ", " 750k ", " 1.5M ", " 2.18M ", " 3M ", " 8M ", " 12M " or " 24M |
| (in Hz). The default is a frequency of 12 MHz. |
| .sp |
| An optional |
| .B target |
| parameter specifies which target chip should be used. Syntax is |
| .sp |
| .B " flashprog \-p dediprog:target=value" |
| .sp |
| where |
| .B value |
| can be |
| .BR 1 " or " 2 |
| to select target chip 1 or 2 respectively. The default is target chip 1. |
| .sp |
| Dediprog SF600 and SF700 programmer models support dual and quad i/o. |
| The default is dual i/o on newer models with protocol v3 and single i/o |
| otherwise. The mode can be set with the |
| .B iomode |
| parameter. Valid values are |
| .BR single ", " dual ", or " quad . |
| For instance, to enable quad i/o |
| .sp |
| .B " flashprog \-p dediprog:iomode=quad" |
| .SS |
| .BR "rayer_spi " programmer |
| .IP |
| The default I/O base address used for the parallel port is 0x378 and you can use |
| the optional |
| .B iobase |
| parameter to specify an alternate base I/O address with the |
| .sp |
| .B " flashprog \-p rayer_spi:iobase=baseaddr" |
| .sp |
| syntax where |
| .B baseaddr |
| is base I/O port address of the parallel port, which must be a multiple of |
| four. Make sure to not forget the "0x" prefix for hexadecimal port addresses. |
| .sp |
| The default cable type is the RayeR cable. You can use the optional |
| .B type |
| parameter to specify the cable type with the |
| .sp |
| .B " flashprog \-p rayer_spi:type=model" |
| .sp |
| syntax where |
| .B model |
| can be |
| .BR rayer " for the RayeR cable, " byteblastermv " for the Altera ByteBlasterMV, " stk200 " for the Atmel \ |
| STK200/300, " wiggler " for the Macraigor Wiggler, " xilinx " for the Xilinx Parallel Cable III (DLC 5), or" \ |
| " spi_tt" " for SPI Tiny Tools-compatible hardware. |
| .sp |
| More information about the RayeR hardware is available at |
| .nh |
| .URLB "http://rayer.g6.cz/elektro/spipgm.htm" "RayeR's website" . |
| The Altera ByteBlasterMV datasheet can be obtained from |
| .URLB "http://www.altera.co.jp/literature/ds/dsbytemv.pdf" Altera . |
| For more information about the Macraigor Wiggler see |
| .URLB "http://www.macraigor.com/wiggler.htm" "their company homepage" . |
| The schematic of the Xilinx DLC 5 was published in |
| .URLB "http://www.xilinx.com/support/documentation/user_guides/xtp029.pdf" "a Xilinx user guide" . |
| .SS |
| .BR "pony_spi " programmer |
| .IP |
| The serial port (like /dev/ttyS0, /dev/ttyUSB0 on Linux or COM3 on windows) is |
| specified using the mandatory |
| .B dev |
| parameter. The adapter type is selectable between SI-Prog (used for |
| SPI devices with PonyProg 2000) or a custom made serial bitbanging programmer |
| named "serbang". The optional |
| .B type |
| parameter accepts the values "si_prog" (default) or "serbang". |
| .sp |
| Information about the SI-Prog adapter can be found at |
| .URLB "http://www.lancos.com/siprogsch.html" "its website" . |
| .sp |
| An example call to flashprog is |
| .sp |
| .B " flashprog \-p pony_spi:dev=/dev/ttyS0,type=serbang" |
| .sp |
| Please note that while USB-to-serial adapters work under certain circumstances, |
| this slows down operation considerably. |
| .SS |
| .BR "ogp_spi " programmer |
| .IP |
| The flash ROM chip to access must be specified with the |
| .B rom |
| parameter. |
| .sp |
| .B " flashprog \-p ogp_spi:rom=name" |
| .sp |
| Where |
| .B name |
| is either |
| .B cprom |
| or |
| .B s3 |
| for the configuration ROM and |
| .B bprom |
| or |
| .B bios |
| for the BIOS ROM. If more than one card supported by the ogp_spi programmer |
| is installed in your system, you have to specify the PCI address of the card |
| you want to use with the |
| .B pci= |
| parameter as explained in the |
| .B nic3com et al.\& |
| section above. |
| .SS |
| .BR "linux_gpio_spi " programmer |
| .IP |
| Either the GPIO device node or the chip number as well as the GPIO numbers |
| of the SPI lines must be specified like in the following examples: |
| .sp |
| .B " flashprog \-p linux_gpio_spi:dev=/dev/gpiochip0,cs=8,sck=11,mosi=10,miso=9" |
| .sp |
| or |
| .sp |
| .B " flashprog \-p linux_gpio_spi:gpiochip=0,cs=8,sck=11,mosi=10,miso=9" |
| .sp |
| Here, |
| .B gpiochip=0 |
| selects the GPIO chip 0, accessible through Linux device node /dev/gpiochip0, and the |
| .B cs, sck, mosi, miso |
| arguments select the GPIO numbers used as SPI lines connected to the flash ROM chip. |
| If libgpiod 2.0 or later is available, dual-i/o is enabled by default with bidirectional |
| MOSI and MISO lines, and if a quad-i/o capable chip is connect with four lines, the |
| additional GPIOs can be specified via |
| .BR io2 " and " io3 |
| parameters. |
| |
| In the example above, the GPIO numbers of the hardware SPI lines of a Raspberry Pi |
| single board computer are specified. The first four GPIO parameters are mandatory. |
| Note that this is a bitbanged driver, and if your device has a hardware SPI |
| controller, use the |
| .B linux_spi |
| programmer driver instead for better performance. |
| .sp |
| Refer to the output of the |
| .B gpioinfo |
| utility to make sure the GPIO numbers are correct and unused. |
| .sp |
| Please note that the linux_gpio_spi driver only works on Linux, and depends on libgpiod. |
| .SS |
| .BR "linux_mtd " programmer |
| .IP |
| You may specify the MTD device to use with the |
| .sp |
| .B " flashprog \-p linux_mtd:dev=/dev/mtdX" |
| .sp |
| syntax where |
| .B /dev/mtdX |
| is the Linux device node for your MTD device. If left unspecified the first MTD |
| device found (e.g. /dev/mtd0) will be used by default. |
| .sp |
| Please note that the linux_mtd driver only works on Linux. |
| .SS |
| .BR "linux_spi " programmer |
| .IP |
| You have to specify the SPI controller to use with the |
| .sp |
| .B " flashprog \-p linux_spi:dev=/dev/spidevX.Y" |
| .sp |
| syntax where |
| .B /dev/spidevX.Y |
| is the Linux device node for your SPI controller. |
| .sp |
| In case the device supports it, you can set the SPI clock frequency with the optional |
| .B spispeed |
| parameter. The frequency is parsed as kilohertz. |
| Example that sets the frequency to 8 MHz: |
| .sp |
| .B " flashprog \-p linux_spi:dev=/dev/spidevX.Y,spispeed=8000" |
| .sp |
| Please note that the linux_spi driver only works on Linux. |
| .SS |
| .BR "mstarddc_spi " programmer |
| .IP |
| The Display Data Channel (DDC) is an I2C bus present on VGA and DVI connectors, that allows exchanging |
| information between a computer and attached displays. Its most common uses are getting display capabilities |
| through EDID (at I2C address 0x50) and sending commands to the display using the DDC/CI protocol (at address |
| 0x37). On displays driven by MSTAR SoCs, it is also possible to access the SoC firmware flash (connected to |
| the Soc through another SPI bus) using an In-System Programming (ISP) port, usually at address 0x49. |
| This flashprog module allows the latter via Linux's I2C driver. |
| .sp |
| .B IMPORTANT: |
| Before using this programmer, the display |
| .B MUST |
| be in standby mode, and only connected to the computer that will run flashprog using a VGA cable, to an |
| inactive VGA output. It absolutely |
| .B MUST NOT |
| be used as a display during the procedure! |
| .sp |
| You have to specify the DDC/I2C controller and I2C address to use with the |
| .sp |
| .B " flashprog \-p mstarddc_spi:dev=/dev/i2c-X:YY" |
| .sp |
| syntax where |
| .B /dev/i2c-X |
| is the Linux device node for your I2C controller connected to the display's DDC channel, and |
| .B YY |
| is the (hexadecimal) address of the MSTAR ISP port (address 0x49 is usually used). |
| Example that uses I2C controller /dev/i2c-1 and address 0x49: |
| .sp |
| .B " flashprog \-p mstarddc_spi:dev=/dev/i2c-1:49 |
| .sp |
| It is also possible to inhibit the reset command that is normally sent to the display once the flashprog |
| operation is completed using the optional |
| .B noreset |
| parameter. A value of 1 prevents flashprog from sending the reset command. |
| Example that does not reset the display at the end of the operation: |
| .sp |
| .B " flashprog \-p mstarddc_spi:dev=/dev/i2c-1:49,noreset=1 |
| .sp |
| Please note that sending the reset command is also inhibited if an error occurred during the operation. |
| To send the reset command afterwards, you can simply run flashprog once more, in chip probe mode (not specifying |
| an operation), without the |
| .B noreset |
| parameter, once the flash read/write operation you intended to perform has completed successfully. |
| .sp |
| Please also note that the mstarddc_spi driver only works on Linux. |
| .SS |
| .BR "ch341a_spi " programmer |
| The WCH CH341A programmer does not support any parameters currently. SPI frequency is fixed at 2 MHz, and CS0 is |
| used as per the device. |
| .SS |
| .BR "ch347_spi " programmer |
| .IP |
| The driver is currently hard-coded to use |
| .BR CS0 . |
| An optional |
| .B spispeed |
| parameter specifies the frequency of the SPI bus. |
| Syntax is |
| .sp |
| .B " flashprog \-p ch347_spi:spispeed=frequency" |
| .sp |
| where |
| .B frequency |
| is given in |
| .B kHz |
| and can be in the range 468 .. 60000. The frequency will be rounded down to |
| a supported value (60 MHz divided by a power of 2). The default is a frequency |
| of 7.5 MHz. |
| The SPI mode can also be set using the spimode parameter: |
| .sp |
| .B " flashprog \-p ch347_spi:spimode=mode" |
| .sp |
| where |
| .B mode |
| is in the range 0 to 3. The default is mode 0. |
| .SS |
| .BR "ni845x_spi " programmer |
| .IP |
| An optional |
| .B voltage |
| parameter could be used to specify the IO voltage. This parameter is available for the NI USB-8452 device. |
| The default unit is Volt if no unit is specified. You can use |
| .BR mV ", " milliVolt ", " V " or " Volt |
| as unit specifier. |
| Syntax is |
| .sp |
| .B " flashprog \-p ni845x_spi:voltage=value" |
| .sp |
| where |
| .B value |
| can be |
| .BR 1.2V ", " 1.5V ", " 1.8V ", " 2.5V ", " 3.3V |
| or the equivalent in mV. |
| .sp |
| In the case if none of the programmer's supported IO voltage is within the supported voltage range of |
| the detected flash chip the flashprog will abort the operation (to prevent damaging the flash chip). |
| You can override this behaviour by passing "yes" to the |
| .B ignore_io_voltage_limits |
| parameter (for e.g. if you are using an external voltage translator circuit). |
| Syntax is |
| .sp |
| .B " flashprog \-p ni845x_spi:ignore_io_voltage_limits=yes" |
| .sp |
| You can use the |
| .B serial |
| parameter to explicitly specify which connected NI USB-845x device should be used. |
| You should use your device's 7 digit hexadecimal serial number. |
| Usage example to select the device with 1230A12 serial number: |
| .sp |
| .B " flashprog \-p ni845x_spi:serial=1230A12" |
| .sp |
| An optional |
| .B spispeed |
| parameter specifies the frequency of the SPI bus. |
| Syntax is |
| .sp |
| .B " flashprog \-p ni845x_spi:spispeed=frequency" |
| .sp |
| where |
| .B frequency |
| should a number corresponding to the desired frequency in kHz. |
| The maximum |
| .B frequency |
| is 12 MHz (12000 kHz) for the USB-8451 and 50 MHz (50000 kHz) for the USB-8452. |
| The default is a frequency of 1 MHz (1000 kHz). |
| .sp |
| An optional |
| .B cs |
| parameter specifies which target chip select line should be used. Syntax is |
| .sp |
| .B " flashprog \-p ni845x_spi:csnumber=value" |
| .sp |
| where |
| .B value |
| should be between |
| .BR 0 " and " 7 |
| By default the CS0 is used. |
| .SS |
| .BR "digilent_spi " programmer |
| .IP |
| An optional |
| .B spispeed |
| parameter specifies the frequency of the SPI bus. |
| Syntax is |
| .sp |
| .B " flashprog \-p digilent_spi:spispeed=frequency" |
| .sp |
| where |
| .B frequency |
| can be |
| .BR 62.5k ", " 125k ", " 250k ", " 500k ", " 1M ", " 2M " or " 4M |
| (in Hz). The default is a frequency of 4 MHz. |
| .SS |
| .BR "dirtyjtag_spi " programmer |
| .IP |
| An optional |
| .B spispeed |
| parameter specifies the frequency of the SPI bus. |
| Syntax is |
| .sp |
| .B " flashprog \-p dirtyjtag_spi:spispeed=frequency" |
| .sp |
| where |
| .B frequency |
| can be any value in hertz, kilohertz or megahertz supported by the programmer. |
| The default is a frequency of 100 kHz. |
| .SS |
| .BR "jlink_spi " programmer |
| .IP |
| This module supports SEGGER J-Link and compatible devices. |
| |
| The \fBMOSI\fP signal of the flash chip must be attached to \fBTDI\fP pin of |
| the programmer, \fBMISO\fP to \fBTDO\fP and \fBSCK\fP to \fBTCK\fP. |
| The chip select (\fBCS\fP) signal of the flash chip can be attached to |
| different pins of the programmer which can be selected with the |
| .sp |
| .B " flashprog \-p jlink_spi:cs=pin" |
| .sp |
| syntax where \fBpin\fP can be either \fBTRST\fP or \fBRESET\fP. |
| The default pin for chip select is \fBRESET\fP. |
| Note that, when using \fBRESET\fP, it is normal that the indicator LED blinks |
| orange or red. |
| .br |
| Additionally, the \fBVTref\fP pin of the programmer must be attached to the |
| logic level of the flash chip. |
| The programmer measures the voltage on this pin and generates the reference |
| voltage for its input comparators and adapts its output voltages to it. |
| .sp |
| Pinout for devices with 20-pin JTAG connector: |
| .sp |
| +-------+ |
| | 1 2 | 1: VTref 2: |
| | 3 4 | 3: TRST 4: GND |
| | 5 6 | 5: TDI 6: GND |
| +-+ 7 8 | 7: 8: GND |
| | 9 10 | 9: TCK 10: GND |
| | 11 12 | 11: 12: GND |
| +-+ 13 14 | 13: TDO 14: |
| | 15 16 | 15: RESET 16: |
| | 17 18 | 17: 18: |
| | 19 20 | 19: PWR_5V 20: |
| +-------+ |
| .sp |
| If there is more than one compatible device connected, you can select which one |
| should be used by specifying its serial number with the |
| .sp |
| .B " flashprog \-p jlink_spi:serial=number" |
| .sp |
| syntax where |
| .B number |
| is the serial number of the device (which can be found for example in the |
| output of lsusb -v). |
| .sp |
| The SPI speed can be selected by using the |
| .sp |
| .B " flashprog \-p jlink_spi:spispeed=frequency" |
| .sp |
| syntax where \fBfrequency\fP is the SPI clock frequency in kHz. |
| The maximum speed depends on the device in use. |
| .sp |
| The \fBpower=on\fP option can be used to activate the 5 V power supply (PWR_5V) |
| of the J-Link during a flash operation. |
| .SS |
| .BR "stlinkv3_spi " programmer |
| .IP |
| This module supports SPI flash programming through the STMicroelectronics |
| STLINK V3 programmer/debugger's SPI bridge interface |
| .sp |
| .B " flashprog \-p stlinkv3_spi" |
| .sp |
| If there is more than one compatible device connected, you can select which one |
| should be used by specifying its serial number with the |
| .sp |
| .B " flashprog \-p stlinkv3_spi:serial=number" |
| .sp |
| syntax where |
| .B number |
| is the serial number of the device (which can be found for example in the |
| output of lsusb -v). |
| .sp |
| The SPI speed can be selected by using the |
| .sp |
| .B " flashprog \-p stlinkv3_spi:spispeed=frequency" |
| .sp |
| syntax where \fBfrequency\fP is the SPI clock frequency in kHz. |
| If the passed frequency is not supported by the adapter the nearest lower |
| supported frequency will be used. |
| .SS |
| |
| .SH EXAMPLES |
| To back up and update your BIOS, run |
| .sp |
| .B flashprog -p internal -r backup.rom -o backuplog.txt |
| .br |
| .B flashprog -p internal -w newbios.rom -o writelog.txt |
| .sp |
| Please make sure to copy backup.rom to some external media before you try |
| to write. That makes offline recovery easier. |
| .br |
| If writing fails and flashprog complains about the chip being in an unknown |
| state, you can try to restore the backup by running |
| .sp |
| .B flashprog -p internal -w backup.rom -o restorelog.txt |
| .sp |
| If you encounter any problems, please contact us and supply |
| backuplog.txt, writelog.txt and restorelog.txt. See section |
| .B BUGS |
| for contact info. |
| .SH EXIT STATUS |
| flashprog exits with 0 on success, 1 on most failures but with 3 if a call to mmap() fails. |
| .SH REQUIREMENTS |
| flashprog needs different access permissions for different programmers. |
| .sp |
| .B internal |
| needs raw memory access, PCI configuration space access, raw I/O port |
| access (x86) and MSR access (x86). |
| .sp |
| .B atavia |
| needs PCI configuration space access. |
| .sp |
| .BR nic3com ", " nicrealtek " and " nicnatsemi " |
| need PCI configuration space read access and raw I/O port access. |
| .sp |
| .B atahpt |
| needs PCI configuration space access and raw I/O port access. |
| .sp |
| .BR gfxnvidia ", " drkaiser " and " it8212 |
| need PCI configuration space access and raw memory access. |
| .sp |
| .B rayer_spi |
| needs raw I/O port access. |
| .sp |
| .BR satasii ", " nicintel ", " nicintel_eeprom " and " nicintel_spi |
| need PCI configuration space read access and raw memory access. |
| .sp |
| .BR satamv " and " atapromise |
| need 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 |
| .B buspirate_spi |
| needs userspace access to a serial port. |
| .sp |
| .BR ft2232_spi ", " usbblaster_spi " and " pickit2_spi |
| need access to the respective USB device via libusb API version 0.1. |
| .sp |
| .BR ch341a_spi " and " dediprog |
| need access to the respective USB device via libusb API version 1.0. |
| .sp |
| .B dummy |
| needs no access permissions at all. |
| .sp |
| .BR internal ", " nic3com ", " nicrealtek ", " nicnatsemi ", " |
| .BR gfxnvidia ", " drkaiser ", " satasii ", " satamv ", " atahpt ", " atavia " and " atapromise |
| have to be run as superuser/root, and need additional raw access permission. |
| .sp |
| .BR serprog ", " buspirate_spi ", " dediprog ", " usbblaster_spi ", " ft2232_spi ", " pickit2_spi ", " \ |
| ch341a_spi ", " digilent_spi " and " dirtyjtag_spi |
| can be run as normal user on most operating systems if appropriate device |
| permissions are set. |
| .sp |
| .B ogp |
| needs PCI configuration space read access and raw memory access. |
| .sp |
| On OpenBSD, you can obtain raw access permission by setting |
| .B "securelevel=-1" |
| in |
| .B "/etc/rc.securelevel" |
| and rebooting, or rebooting into single user mode. |
| .SH BUGS |
| You can report bugs, ask us questions or send success reports |
| via our communication channels listed here: |
| .URLB "https://www.flashprog.org/Contact" "" . |
| .sp |
| Also, we provide a |
| .URLB https://paste.flashrom.org "pastebin service" |
| that is very useful to share logs without spamming the communication channels. |
| .SS |
| .B Laptops |
| .sp |
| Using flashprog on older laptops is dangerous and may easily make your hardware |
| unusable. flashprog will attempt to detect if it is running on a susceptible |
| laptop and restrict flash-chip probing for safety reasons. Please see the |
| detailed discussion of this topic and associated flashprog options in the |
| .B Laptops |
| paragraph in the |
| .B internal programmer |
| subsection of the |
| .B PROGRAMMER-SPECIFIC INFORMATION |
| section and the information |
| .URLB "https://flashprog.org/Laptops" "in our wiki" . |
| .SS |
| One-time programmable (OTP) memory and unique IDs |
| .sp |
| Some flash chips contain OTP memory often denoted as "security registers". |
| They usually have a capacity in the range of some bytes to a few hundred |
| bytes and can be used to give devices unique IDs etc. flashprog is not able |
| to read or write these memories and may therefore not be able to duplicate a |
| chip completely. For chip types known to include OTP memories a warning is |
| printed when they are detected. |
| .sp |
| Similar to OTP memories are unique, factory programmed, unforgeable IDs. |
| They are not modifiable by the user at all. |
| .SH LICENSE |
| .B flashprog |
| is covered by the GNU General Public License (GPL), version 2. Some files are |
| additionally available under any later version of the GPL. |
| .SH COPYRIGHT |
| .br |
| Please see the individual files. |
| .SH AUTHORS |
| Andrew Morgan |
| .br |
| Carl-Daniel Hailfinger |
| .br |
| Claus Gindhart |
| .br |
| David Borg |
| .br |
| David Hendricks |
| .br |
| Dominik Geyer |
| .br |
| Edward O'Callaghan |
| .br |
| Eric Biederman |
| .br |
| Giampiero Giancipoli |
| .br |
| Helge Wagner |
| .br |
| Idwer Vollering |
| .br |
| Joe Bao |
| .br |
| Joerg Fischer |
| .br |
| Joshua Roys |
| .br |
| Ky\[:o]sti M\[:a]lkki |
| .br |
| Luc Verhaegen |
| .br |
| Li-Ta Lo |
| .br |
| Mark Marshall |
| .br |
| Markus Boas |
| .br |
| Mattias Mattsson |
| .br |
| Michael Karcher |
| .br |
| Nikolay Petukhov |
| .br |
| Patrick Georgi |
| .br |
| Peter Lemenkov |
| .br |
| Peter Stuge |
| .br |
| Reinder E.N. de Haan |
| .br |
| Ronald G. Minnich |
| .br |
| Ronald Hoogenboom |
| .br |
| Sean Nelson |
| .br |
| Stefan Reinauer |
| .br |
| Stefan Tauner |
| .br |
| Stefan Wildemann |
| .br |
| Stephan Guilloux |
| .br |
| Steve Markgraf |
| .br |
| Steven James |
| .br |
| Urja Rannikko |
| .br |
| Uwe Hermann |
| .br |
| Wang Qingpei |
| .br |
| Yinghai Lu |
| .br |
| some others, please see the flashprog git history for details. |
| .br |
| Active maintainers can be reached via |
| .MTOB "flashprog@flashprog.org" "the mailing list" . |
| .PP |
| This manual page was written by |
| .MTOB "uwe@hermann-uwe.de" "Uwe Hermann" , |
| Carl-Daniel Hailfinger, Stefan Tauner and others. |
| It is licensed under the terms of the GNU GPL (version 2 or later). |
| |
| .SH SEE ALSO |
| .MR flashprog-config 8 , |
| .MR flashprog-write-protect 8 |