Thomas Heijligen has submitted this change. ( https://review.coreboot.org/c/flashrom/+/72619 )
(
11 is the latest approved patch-set. No files were changed between the latest approved patch-set and the submitted one. )Change subject: move manpage to sphinx ......................................................................
move manpage to sphinx
Use sphinx (sphinx-doc.org) to generate the UNIX man page from an reStructuredText file instead of dealing with plain groff.
Use `meson setup -Dman-pages=enabled` to build the man page, and `meson setup -Ddocumentation=enabled` to build the web documentation explicitly. Both are enabled automatically if sphinx-build is found.
The man page will be installed as `<meson_mandir>/man8/flashrom.8` and The html documentation in <meson_datadir>/doc/flashrom/html`.
The Makefile builds only the man-page format.
Increase the minimum version of meson from 0.53.0 to 0.57.0 to be able to pass environment variables to the custom_target() command. That is needed to pass the FLASHROM_VERSION to the documentation.
Change-Id: Iee9f1164c5913e47385e6f7d51dc7775a58b5a67 Signed-off-by: Thomas Heijligen thomas.heijligen@secunet.com Reviewed-on: https://review.coreboot.org/c/flashrom/+/72619 Tested-by: build bot (Jenkins) no-reply@coreboot.org Reviewed-by: Anastasia Klimchuk aklm@chromium.org Reviewed-by: Alexander Goncharov chat@joursoir.net --- M .gitignore M Makefile A doc/classic_cli_manpage.rst A doc/conf.py A doc/index.rst A doc/meson.build D flashrom.8.tmpl M meson.build M meson_options.txt 9 files changed, 1,498 insertions(+), 1,870 deletions(-)
Approvals: build bot (Jenkins): Verified Anastasia Klimchuk: Looks good to me, approved Alexander Goncharov: Looks good to me, but someone else must approve
diff --git a/.gitignore b/.gitignore index 1aa73d2..4e38739 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ *.d !Makefile.d/ *.o +/.doctrees /.features /.dependencies /.libdeps @@ -12,6 +13,7 @@ /flashrom.bash /libflashrom.a /libflashrom-doc/ +/man8
/util/ich_descriptors_tool/ich_descriptors_tool /util/ich_descriptors_tool/ich_descriptors_tool.exe diff --git a/Makefile b/Makefile index 5283fea..6038faf 100644 --- a/Makefile +++ b/Makefile @@ -404,7 +404,6 @@ # be obtained using util/getrevision.sh, which is the common case during development. -include versioninfo.inc VERSION ?= $(shell ./util/getrevision.sh --revision) -MAN_DATE ?= $(shell ./util/getrevision.sh --date $(PROGRAM).8.tmpl 2>/dev/null)
SCMDEF := -D'FLASHROM_VERSION="$(VERSION)"'
@@ -960,7 +959,7 @@ OBJS = $(CHIP_OBJS) $(PROGRAMMER_OBJS) $(LIB_OBJS)
-all: $(PROGRAM)$(EXEC_SUFFIX) $(PROGRAM).8 +all: $(PROGRAM)$(EXEC_SUFFIX) man8/$(PROGRAM).8 ifeq ($(ARCH), x86) @+$(MAKE) -C util/ich_descriptors_tool/ HOST_OS=$(HOST_OS) TARGET_OS=$(TARGET_OS) endif @@ -1033,12 +1032,9 @@ $(AR) rcs $@ $^ $(RANLIB) $@
-$(PROGRAM).8.html: $(PROGRAM).8 - @groff -mandoc -Thtml $< >$@ - -$(PROGRAM).8: $(PROGRAM).8.tmpl - @# Add the man page change date and version to the man page - @sed -e 's#.TH FLASHROM 8 .*#.TH FLASHROM 8 "$(MAN_DATE)" "$(VERSION)" "$(MAN_DATE)"#' <$< >$@ +SPHINXBUILD ?= sphinx-build +man8/$(PROGRAM).8: doc/* + @FLASHROM_VERSION=$(VERSION) $(SPHINXBUILD) -b man doc .
$(PROGRAM).bash: util/$(PROGRAM).bash-completion.tmpl @# Add to the bash completion file a list of enabled programmers. @@ -1051,16 +1047,16 @@ # This includes all frontends and libflashrom. # We don't use EXEC_SUFFIX here because we want to clean everything. clean: - rm -f $(PROGRAM) $(PROGRAM).exe libflashrom.a $(filter-out Makefile.d, $(wildcard *.d *.o platform/*.d platform/*.o)) \ - $(PROGRAM).8 $(PROGRAM).8.html $(PROGRAM).bash $(BUILD_DETAILS_FILE) + rm -rf $(PROGRAM) $(PROGRAM).exe libflashrom.a $(filter-out Makefile.d, $(wildcard *.d *.o platform/*.d platform/*.o)) \ + man8 .doctrees $(PROGRAM).bash $(BUILD_DETAILS_FILE) @+$(MAKE) -C util/ich_descriptors_tool/ clean
-install: $(PROGRAM)$(EXEC_SUFFIX) $(PROGRAM).8 $(PROGRAM).bash +install: $(PROGRAM)$(EXEC_SUFFIX) man8/$(PROGRAM).8 $(PROGRAM).bash mkdir -p $(DESTDIR)$(PREFIX)/sbin mkdir -p $(DESTDIR)$(MANDIR)/man8 mkdir -p $(DESTDIR)$(BASHCOMPDIR) $(INSTALL) -m 0755 $(PROGRAM)$(EXEC_SUFFIX) $(DESTDIR)$(PREFIX)/sbin - $(INSTALL) -m 0644 $(PROGRAM).8 $(DESTDIR)$(MANDIR)/man8 + $(INSTALL) -m 0644 man8/$(PROGRAM).8 $(DESTDIR)$(MANDIR)/man8 $(INSTALL) -m 0644 $(PROGRAM).bash $(DESTDIR)$(BASHCOMPDIR)
libinstall: libflashrom.a include/libflashrom.h @@ -1069,13 +1065,12 @@ mkdir -p $(DESTDIR)$(PREFIX)/include $(INSTALL) -m 0644 include/libflashrom.h $(DESTDIR)$(PREFIX)/include
-_export: $(PROGRAM).8 +_export: man8/$(PROGRAM).8 @rm -rf "$(EXPORTDIR)/flashrom-$(RELEASENAME)" @mkdir -p "$(EXPORTDIR)/flashrom-$(RELEASENAME)" @git archive HEAD | tar -x -C "$(EXPORTDIR)/flashrom-$(RELEASENAME)" # Generate versioninfo.inc containing metadata that would not be available in exported sources otherwise. @echo "VERSION = $(VERSION)" > "$(EXPORTDIR)/flashrom-$(RELEASENAME)/versioninfo.inc" - @echo "MAN_DATE = $(MAN_DATE)" >> "$(EXPORTDIR)/flashrom-$(RELEASENAME)/versioninfo.inc" # Restore modification date of all tracked files not marked 'export-ignore' in .gitattributes. # sed is required to filter out file names having the attribute set. # The sed program saves the file name in the hold buffer and then checks if the respective value is 'set'. diff --git a/doc/classic_cli_manpage.rst b/doc/classic_cli_manpage.rst new file mode 100644 index 0000000..fc0ae14 --- /dev/null +++ b/doc/classic_cli_manpage.rst @@ -0,0 +1,1362 @@ +Manual page +=========== + + +NAME +---- + +**flashrom** - detect, read, write, verify and erase flash chips + + +SYNOPSIS +-------- + +| **flashrom** [-h|-R|-L|-z| +| -p <programmername>[:<parameters>] [-c <chipname>] +| (--flash-name|--flash-size| +| [-E|-x|-r <file>|-w <file>|-v <file>] +| [(-l <file>|--ifd|--fmap|--fmap-file <file>) +| [-i <include>[:<file>]]] +| [--wp-status] [--wp-list] [--wp-enable|--wp-disable] +| [--wp-range <start>,<length>|--wp-region <region>] +| [-n] [-N] [-f])] +| [-V[V[V]]] [-o <logfile>] [--progress] + + +DESCRIPTION +----------- + +**flashrom** 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. + +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. + + +OPTIONS +------- + +You can specify one of ``-h``, ``-R``, ``-L``, ``-z``, ``-E``, ``-r``, ``-w``, ``-v`` or no operation. +If no operation is specified, **flashrom** will only probe for flash chips. It is recommended that if you try **flashrom** 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 ``-r`` before you try to write a new image. +All operations involving any chip access (probe/read/write/...) require the ``-p/--programmer`` option to be used (please see below). + + +**-r, --read <file>** + Read flash ROM contents and save them into the given **<file>**. + If the file already exists, it will be overwritten. + + +**-w, --write (<file>|-)** + Write **<file>** into flash ROM. If **-** is provided instead, contents will be read from stdin. + This will first automatically erase the chip, then write to it. + + 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. + + +**-n, --noverify** + Skip the automatic verification of flash ROM contents after writing. Using this option is **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. + + Typical usage is:: + + flashrom -p prog -n -w <file> + + This option is only useful in combination with ``--write``. + + +**-N, --noverify-all** + Skip not included regions during automatic verification after writing (cf. ``-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 **internal** programmer). + Even if **flashrom** is instructed not to touch parts of the flash chip, their contents could be damaged + (e.g. due to misunderstood erase commands). + + This option is required to flash an Intel system with locked ME flash region using the **internal** programmer. + It may be enabled by default in this case in the future. + + +**-v, --verify (<file>|-)** + Verify the flash ROM contents against the given **<file>**. + If **-** is provided instead, contents will be written to the stdout. + + +**-E, --erase** + Erase the flash ROM chip. + + +**-x, --extract** + Extract every region defined on the layout from flash ROM chip to a file with the same name as the extracted region + (replacing spaces with underscores). + + +**-V, --verbose** + More verbose output. This option can be supplied multiple times (max. 3 times, i.e. ``-VVV`` ) for even more debug output. + + +**-c, --chip <chipname>** + Probe only for the specified flash ROM chip. This option takes the chip name as printed by ``flashrom -L`` without the + vendor name as parameter. Please note that the chip name is case sensitive. + + +**-f, --force** + Force one or more of the following actions: + + * Force chip read and pretend the chip is there. + * Force chip access even if the chip is bigger than the maximum supported size for the flash bus. + * Force erase even if erase is known bad. + * Force write even if write is known bad. + + +**-l, --layout <file>** + Read ROM layout from **<file>**. + + **flashrom** 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:: + + startaddr:endaddr imagename + + ``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. + ``imagename`` is an arbitrary name for the region/image from ``startaddr`` to ``endaddr`` (both addresses included). + + Example:: + + 00000000:00008fff gfxrom + 00009000:0003ffff normal + 00040000:0007ffff fallback + + If you only want to update the image named **normal** in a ROM based on the layout above, run:: + + flashrom -p prog --layout rom.layout --image normal -w some.rom + + To update only the images named **normal** and **fallback**, run:: + + flashrom -p prog -l rom.layout -i normal -i fallback -w some.rom + + Overlapping sections are not supported. + + +**--fmap** + Read layout from fmap in flash chip. + + **flashrom** 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. + + If you only want to update the **COREBOOT** region defined in the fmap, run:: + + flashrom -p prog --fmap --image COREBOOT -w some.rom + + +**--fmap-file <file>** + Read layout from a **<file>** containing binary fmap (e.g. coreboot roms). + + **flashrom** 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. + + If you only want to update the **COREBOOT** region defined in the binary fmap file, run:: + + flashrom -p prog --fmap-file some.rom --image COREBOOT -w some.rom + + +**--ifd** + Read ROM layout from Intel Firmware Descriptor. + + **flashrom** 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. + + The following ROM images may be present in an IFD: + + | ``fd`` - the IFD itself + | ``bios`` - the host firmware aka. BIOS + | ``me`` - Intel Management Engine firmware + | ``gbe`` - gigabit ethernet firmware + | ``pd`` - platform specific data + + +**-i, --include <region>[:<file>]** + Read or write only **<region>** to or from ROM. + The **-i** option may be used multiple times if the user wishes to read or write multiple regions using a single command. + + The user may optionally specify a corresponding **<file>** for any region they wish to read or write. + A read operation will read the corresponding regions from ROM and write individual files for each one. + A write option will read file(s) and write to the corresponding region(s) in ROM. + + For write operations, files specified using ``-i`` take precedence over content from the argument to ``-w``. + + Examples: + To read regions named **foo** and **bar** in layout file **<layout>** into region-sized files **foo.bin** and **bar.bin**, run:: + + flashrom -p prog -l <layout> -i foo:foo.bin -i bar:bar.bin -r rom.bin + + To write files **foo.bin** and **bar.bin** into regions named **foo** and **bar** in layout file **<layout>** to the ROM, run:: + + flashrom -p prog -l <layout> -i foo:foo.bin -i bar:bar.bin -w rom.bin + + +**--wp-status** + Prints the flash's current status register protection mode and write protection range. + + +**--wp-list** + Prints a list of all protection ranges that the flash supports. + + +**--wp-enable** + Enables hardware status register protection (SRP) if the flash supports it. + Once SRP is enabled, operations that change the flash's status registers (including ``--wp-disable`` and ``--wp-range``) + can only be performed if the flash's #WP pin is at an inactive logic level. + + +**--wp-disable** + Disables status register protection if the flash allows it. + + +**--wp-range <start>,<length>** + Configures the flash to protect a range of addresses from <start> to (<start> + <length> - 1), bounds inclusive. + The range must be supported by the flash, see ``--wp-list``. + + +**--wp-region <region>** + Same as ``--wp-range`` but protects the range occupied by an image region. + This option requires a image layout to be specified, see ``--layout``. + The region must be supported by the flash, see ``--wp-list``. + + +**--flash-name** + Prints out the detected flash chip's name. + + +**--flash-size** + Prints out the detected flash chip's size. + + +**--flash-contents <ref-file>** + The file contents of **<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. + + +**-L, --list-supported** + List the flash chips, chipsets, mainboards, and external programmers (including PCI, USB, parallel port, and serial port based devices) + supported by **flashrom**. + + There are many unlisted boards which will work out of the box, without special support in **flashrom**. + Please let us know if you can verify that other boards work or do not work out of the box. + + **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! + + +**-z, --list-supported-wiki** + Same as ``--list-supported``, but outputs the supported hardware in MediaWiki syntax, + so that it can be easily pasted into the `supported hardware wiki page https://flashrom.org/Supported_hardware`_. + Please note that MediaWiki output is not compiled in by default. + + +**-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: + + * ``internal`` (for in-system flashing in the mainboard) + * ``dummy`` (virtual programmer for testing **flashrom**) + * ``nic3com`` (for flash ROMs on 3COM network cards) + * ``nicrealtek`` (for flash ROMs on Realtek and SMC 1211 network cards) + * ``nicnatsemi`` (for flash ROMs on National Semiconductor DP838* network cards) + * ``nicintel`` (for parallel flash ROMs on Intel 10/100Mbit network cards) + * ``gfxnvidia`` (for flash ROMs on NVIDIA graphics cards) + * ``drkaiser`` (for flash ROMs on Dr. Kaiser PC-Waechter PCI cards) + * ``satasii`` (for flash ROMs on Silicon Image SATA/IDE controllers) + * ``satamv`` (for flash ROMs on Marvell SATA controllers) + * ``atahpt`` (for flash ROMs on Highpoint ATA/RAID controllers) + * ``atavia`` (for flash ROMs on VIA VT6421A SATA controllers) + * ``atapromise`` (for flash ROMs on Promise PDC2026x ATA/RAID controllers) + * ``it8212`` (for flash ROMs on ITE IT8212F ATA/RAID controller) + * ``ft2232_spi`` (for SPI flash ROMs attached to an FT2232/FT4232H/FT232H family based USB SPI programmer) + * ``serprog`` (for flash ROMs attached to a programmer speaking serprog, including some Arduino-based devices) + * ``buspirate_spi`` (for SPI flash ROMs attached to a Bus Pirate) + * ``dediprog`` (for SPI flash ROMs attached to a Dediprog SF100) + * ``rayer_spi`` (for SPI flash ROMs attached to a parallel port by one of various cable types) + * ``raiden_debug_spi`` (For Chrome EC based debug tools - SuzyQable, Servo V4, C2D2 & uServo) + * ``pony_spi`` (for SPI flash ROMs attached to a SI-Prog serial port bitbanging adapter) + * ``nicintel_spi`` (for SPI flash ROMs on Intel Gigabit network cards) + * ``ogp_spi`` (for SPI flash ROMs on Open Graphics Project graphics card) + * ``linux_mtd`` (for SPI flash ROMs accessible via /dev/mtdX on Linux) + * ``linux_spi`` (for SPI flash ROMs accessible via /dev/spidevX.Y on Linux) + * ``usbblaster_spi`` (for SPI flash ROMs attached to an Altera USB-Blaster compatible cable) + * ``nicintel_eeprom`` (for SPI EEPROMs on Intel Gigabit network cards) + * ``mstarddc_spi`` (for SPI flash ROMs accessible through DDC in MSTAR-equipped displays) + * ``pickit2_spi`` (for SPI flash ROMs accessible via Microchip PICkit2) + * ``ch341a_spi`` (for SPI flash ROMs attached to WCH CH341A) + * ``ch347_api`` (for SPI flash ROMs attached to WHC CH347) + * ``digilent_spi`` (for SPI flash ROMs attached to iCEblink40 development boards) + * ``jlink_spi`` (for SPI flash ROMs attached to SEGGER J-Link and compatible devices) + * ``ni845x_spi`` (for SPI flash ROMs attached to National Instruments USB-8451 or USB-8452) + * ``stlinkv3_spi`` (for SPI flash ROMs attached to STMicroelectronics STLINK V3 devices) + * ``realtek_mst_i2c_spi`` (for SPI flash ROMs attached to Realtek DisplayPort hubs accessible through I2C) + * ``parade_lspcon`` (for SPI flash ROMs attached to Parade Technologies LSPCONs (PS175)) + * ``mediatek_i2c_spi`` (for SPI flash ROMs attached to some Mediatek display devices accessible over I2C) + * ``dirtyjtag_spi`` (for SPI flash ROMs attached to DirtyJTAG-compatible devices) + * ``asm106x`` (for SPI flash ROMs attached to asm106x PCI SATA controllers) + + Some programmers have optional or mandatory parameters which are described in detail in the + **PROGRAMMER-SPECIFIC INFORMATION** section. Support for some programmers can be disabled at compile time. + ``flashrom -h`` lists all supported programmers. + + +**-h, --help** + Show a help text and exit. + + +**-o, --output <logfile>** + Save the full debug log to **<logfile>**. + If the file already exists, it will be overwritten. This is the recommended way to gather logs from **flashrom** + because they will be verbose even if the on-screen messages are not verbose and don't require output redirection. + + +**--progress** + Show progress percentage of operations on the standard output. + + +**-R, --version** + Show version information and exit. + + +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 atfixed 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. + + +internal programmer +^^^^^^^^^^^^^^^^^^^ + + +**Board Enables** + 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:: + + flashrom -p internal:mainboard=<vendor>:<board> + + syntax. + + See the **Known boards** or **Known laptops** section in the output of ``flashrom -L`` for a list of boards + which require the specification of the board name, if no coreboot table is found. + + Some of these board-specific flash enabling functions (called **board enables** ) in **flashrom** have not yet been tested. + If your mainboard is detected needing an untested board enable function, a warning message is printed and the board enableis not executed, + because a wrong board enable function might cause the system to behave erratically, as board enable functions touch the + low-level internals of a mainboard. + Not executing a board enable function (if one is needed) might cause detection or erasing failure. + If your board protects only part of the flash (commonly the top end, called boot block), + **flashrom** might encounter an error only after erasing the unprotected part, so running without the board-enable function + might be dangerous for erase and write (which includes erase). + + The suggested procedure for a mainboard with untested board specific code is to first try to probe the ROM + (just invoke **flashrom** and check that it detects your flash chip type) without running the board enable code + (i.e. without any parameters). If it finds your chip, fine. Otherwise, retry probing your chip with the board-enable code running, using:: + + flashrom -p internal:boardenable=force + + If your chip is still not detected, the board enable code seems to be broken or the flash chip unsupported. + Otherwise, make a backup of your current ROM contents (using ``-r``) and store it to a medium outside of your computer, + like 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 **flashrom** mailing list, see below. + +**Coreboot** + On systems running coreboot, **flashrom** checks whether the desired image matches your mainboard. + This needs some special board ID to be present in the image. + If **flashrom** 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:: + + flashrom -p internal:boardmismatch=force + + +**ITE IT87 Super I/O** + 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:: + + flashrom -p internal:dualbiosindex=chip + + syntax where ``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 ``chip`` parameter. + + If your mainboard uses an ITE IT87 series Super I/O for LPC<->SPI flash bus translation, **flashrom** should autodetect that configuration. + If you want to set the I/O base port of the IT87 series SPI controller manually instead of using the value provided by the BIOS, + use the:: + + flashrom -p internal:it87spiport=portnum + + syntax where ``portnum`` is the I/O port number (must be a multiple of 8). + In the unlikely case **flashrom** doesn't detect an active IT87 LPC<->SPI bridge, please send a bug report so we can diagnose the problem. + + +**AMD chipsets** + 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. + Flashrom 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 **flashrom** detects an active IMC it will disable write support unless the user forces it with the:: + + flashrom -p internal:amd_imc_force=yes + + 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. + + An optional ``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:: + + flashrom -p internal:spispeed=frequency + + where ``frequency`` can be ``'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: + + * SB6xx, SB7xx, SP5xxx: from 16.5 MHz up to and including 33 MHz. + The default is to use 16.5 MHz and disable Fast Reads. + * SB8xx, SB9xx, Hudson: from 16.5 MHz up to and including 66 MHz. + The default is to use 16.5 MHz and disable Fast Reads. + * Yangtze (with SPI 100 engine as found in Kabini and Tamesh): all of them. + The default is to use the frequency that is currently configured. + + An optional ``spireadmode`` parameter specifies the read mode of the SPI bus where applicable (Bolton or later). + Syntax is:: + + flashrom -p internal:spireadmode=mode + + where ``mode`` can be ``'Normal (up to 33 MHz)'``, ``'Normal (up to 66 MHz)'``, ``'Dual IO (1-1-2)'``, ``'Quad IO (1-1-4)'``, + ``'Dual IO (1-2-2)'``, ``'Quad IO (1-4-4)'``, or ``'Fast Read'``. + + The default is to use the read mode that is currently configured. + + +**Intel chipsets** + 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 **Hardware Sequencing**. + It is much simpler than the normal access method (called **Software Sequencing**), but does not allow the software to + choose the SPI commands to be sent. You can use the:: + + flashrom -p internal:ich_spi_mode=value + + syntax where ``value`` can be ``auto``, ``swseq`` or ``hwseq``. By default (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). + + 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. + + 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:: + + flashrom -p internal:fwh_idsel=value + + syntax where ``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. + + Example:: + + flashrom -p internal:fwh_idsel=0x001122334567 + + +**Laptops** + Using **flashrom** on older laptops that don't boot from the SPI bus is dangerous and may easily make your hardware unusable + (see also the **BUGS** section). The embedded controller (EC) in some machines may interact badly with flashing. + More information is `in the wiki https://flashrom.org/Laptops`_. + Problems occur when the flash chip is shared between BIOS and EC firmware, and the latter does not expect **flashrom** + to access the chip. While **flashrom** 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. **flashrom** 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:: + + flashrom -p internal:laptop=force_I_want_a_brick + + We will not help you if you force flashing on a laptop because this is a really dumb idea. + + You have been warned. + + 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. **flashrom** will then issue a warning and restrict buses like above. + In this case you can use:: + + flashrom -p internal:laptop=this_is_not_a_laptop + + to tell **flashrom** (at your own risk) that it is not running on a laptop. + + +dummy programmer +^^^^^^^^^^^^^^^^ + +The dummy programmer operates on a buffer in memory only. It provides a safe and fast way to test various aspects of +**flashrom** and is mainly used in development and while debugging. +It is able to emulate some chips to a certain degree (basic identify/read/erase/write operations work). + +An optional parameter specifies the bus types it should support. For that you have to use the:: + + flashrom -p dummy:bus=[type[+type[+type]]] + +syntax where ``type`` can be ``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. + +Example:: + + flashrom -p dummy:bus=lpc+fwh + +The dummy programmer supports flash chip emulation for automated self-tests without hardware access. +If you want to emulate a flash chip, use the:: + + flashrom -p dummy:emulate=chip + +syntax where ``chip`` is one of the following chips (please specify only the chip name, not the vendor): + +* ST ``M25P10.RES`` SPI flash chip (128 kB, RES, page write) +* SST ``SST25VF040.REMS`` SPI flash chip (512 kB, REMS, byte write) +* SST ``SST25VF032B`` SPI flash chip (4096 kB, RDID, AAI write) +* Macronix ``MX25L6436`` SPI flash chip (8192 kB, RDID, SFDP) +* Winbond ``W25Q128FV`` SPI flash chip (16384 kB, RDID) +* Spansion ``S25FL128L`` SPI flash chip (16384 kB, RDID) +* Dummy vendor ``VARIABLE_SIZE`` SPI flash chip (configurable size, page write) + +Example:: + + flashrom -p dummy:emulate=SST25VF040.REMS + +To use ``VARIABLE_SIZE`` chip, ``size`` must be specified to configure the size of the flash chip as a power of two. + +Example:: + + flashrom -p dummy:emulate=VARIABLE_SIZE,size=16777216,image=dummy.bin + + +**Persistent images** + If you use flash chip emulation, flash image persistence is available as well by using the:: + + flashrom -p dummy:emulate=chip,image=image.rom + + syntax where ``image.rom`` is the file where the simulated chip contents are read on **flashrom** startup and where the + chip contents on **flashrom** shutdown are written to. + + Example:: + + flashrom -p dummy:emulate=M25P10.RES,image=dummy.bin + + +**SPI write chunk size** + 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:: + + flashrom -p dummy:emulate=chip,spi_write_256_chunksize=size + + syntax where ``size`` is the number of bytes (min.& 1, max.& 256). + Example:: + + flashrom -p dummy:emulate=M25P10.RES,spi_write_256_chunksize=5 + + +**SPI blacklist** + 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:: + + flashrom -p dummy:spi_blacklist=commandlist + + syntax where ``ommandlist`` is a list of two-digit hexadecimal representations of SPI commands. + If commandlist is e.g. 0302, **flashrom** 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: **flashrom** will detect an error during command execution. + + +**SPI ignorelist** + To simulate a flash chip which ignores (doesn't support) certain SPI commands, you can specify an ignorelist of SPI commands with the:: + + flashrom -p dummy:spi_ignorelist=commandlist + + syntax where ``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: **flashrom** won't detect an error during command execution. + + +**SPI status register** + You can specify the initial content of the chip's status register with the:: + + flashrom -p dummy:spi_status=content" + + syntax where ``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. + + +**Write protection** + Chips with emulated WP: **W25Q128FV**, **S25FL128L**. + + You can simulate state of hardware protection pin (WP) with the:: + + flashrom -p dummy:hwwp=state + + syntax where ``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). + + +nic3com, nicrealtek, nicnatsemi, nicintel, nicintel_eeprom, nicintel_spi, gfxnvidia, ogp_spi, drkaiser, satasii, satamv, atahpt, atavia, atapromise, it8212 programmers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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:: + + flashrom -p xxxx:pci=bb:dd.f + +where ``xxxx`` is the name of the programmer, ``bb`` is the PCI bus number, ``dd`` is the PCI device number, and ``b`` +is the PCI function number of the desired device. Example:: + + flashrom -p nic3com:pci=05:04.0 + + +atavia programmer +^^^^^^^^^^^^^^^^^ + +Due to the mysterious address handling of the VIA VT6421A controller the user can specify an offset with the:: + + flashrom -p atavia:offset=addr + +syntax where ``addr`` will be interpreted as usual (leading 0x (0) for hexadecimal (octal) values, or else decimal). +For more information please see `its wiki page <https://flashrom.org/VT6421A "its wiki page>`_. + + +atapromise programmer +^^^^^^^^^^^^^^^^^^^^^ + +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). + + +nicintel_eeprom programmer +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is the first programmer module in **flashrom** 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. +**Flashrom** 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. + + +ft2232_spi programmer +^^^^^^^^^^^^^^^^^^^^^ + +This module supports various programmers based on FTDI FT2232/FT4232H/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. + +An optional parameter specifies the controller type, channel/interface/port it should support. For that you have to use the:: + + flashrom -p ft2232_spi:type=model,port=interface + +syntax where ``model`` can be ``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``. +``interface`` can be ``A``, ``B``, ``C``, or ``D``. The default model is ``4232H``, the default interface is ``A`` and +GPIO is not used by default. + +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:: + + flashrom -p ft2232_spi:serial=number + +syntax where ``number`` is the serial number of the device (which can be found for example in the output of lsusb -v). + +All models supported by the **ft2232_spi** driver can configure the SPI clock rate by setting a divisor. The expressible +divisors are all **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 ``divisor`` parameter with the:: + + flashrom -p ft2232_spi:divisor=div + +syntax. Using the parameter ``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:: + + flashrom -p ft2232_spi:csgpiol=3 + +The parameter ``gpiolX=[HLC]`` allows use of the GPIOL pins either as generic gpios with a fixed value during flashing +or as additional CS# signal, where ``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 ``H``, ``L`` and ``C``: + +* ``H`` - Set GPIOL output high +* ``L`` - Set GPIOL output low +* ``C`` - Use GPIOL as additional CS# output + +Example:: + + flashrom -p ft2232_spi:gpiol0=H + +**Note** that not all GPIOL pins are freely usable with all programmers as some have special functionality. + + +serprog programmer +^^^^^^^^^^^^^^^^^^ + +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. + +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 ``dev=`` and separate the optional baud rate with a colon. +For example:: + + flashrom -p serprog:dev=/dev/ttyS0:115200 + +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:: + + flashrom -p serprog:ip=ipaddr:port + +syntax. In case the device supports it, you can set the SPI clock frequency with the optional ``spispeed`` parameter. +The frequency is parsed as hertz, unless an ``M``, or ``k`` suffix is given, then megahertz or kilohertz are used respectively. +Example that sets the frequency to 2 MHz:: + + flashrom -p serprog:dev=/dev/device:baud,spispeed=2M + +More information about serprog is available in **serprog-protocol.txt** in the source distribution. + + +buspirate_spi programmer +^^^^^^^^^^^^^^^^^^^^^^^^ + +A required ``dev`` parameter specifies the Bus Pirate device node and an optional ``spispeed`` parameter specifies the +frequency of the SPI bus. The parameter delimiter is a comma. Syntax is:: + + flashrom -p buspirate_spi:dev=/dev/device,spispeed=frequency + +where ``frequency`` can be ``30k``, ``125k``, ``250k``, ``1M``, ``2M``, ``2.6M``, ``4M`` or ``8M`` (in Hz). +The default is the maximum frequency of 8 MHz. + +The baud rate for communication between the host and the Bus Pirate can be specified with the optional ``serialspeed`` +parameter. Syntax is:: + + flashrom -p buspirate_spi:serialspeed=baud + +where ``baud`` can be ``115200``, ``230400``, ``250000`` or ``2000000`` (``2M``). +The default is ``2M`` baud for Bus Pirate hardware version 3.0 and greater, and 115200 otherwise. + +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:: + + flashrom -p buspirate_spi:pullups=state + +where ``state`` can be ``on`` or ``off``. +More information about the Bus Pirate pull-up resistors and their purpose is available +`in a guide by dangerousprototypes http://dangerousprototypes.com/docs/Practical_guide_to_Bus_Pirate_pull-up_resistors`_. + +The state of the Bus Pirate power supply pins is controllable through an optional ``psus`` parameter. Syntax is:: + + flashrom -p buspirate_spi:psus=state + +where ``state`` can be ``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 **pullups** option), by connecting the Bus Pirate's Vpu input to the appropriate Vcc pin. + + +pickit2_spi programmer +^^^^^^^^^^^^^^^^^^^^^^ + +An optional ``voltage`` parameter specifies the voltage the PICkit2 should use. The default unit is Volt if no unit is specified. +You can use ``mV``, ``millivolt``, ``V`` or ``Volt`` as unit specifier. Syntax is:: + + flashrom -p pickit2_spi:voltage=value + +where ``value`` can be ``0V``, ``1.8V``, ``2.5V``, ``3.5V`` or the equivalent in mV. + +An optional ``spispeed`` parameter specifies the frequency of the SPI bus. Syntax is:: + + flashrom -p pickit2_spi:spispeed=frequency + +where ``frequency`` can be ``250k``, ``333k``, ``500k`` or ``1M`` (in Hz). The default is a frequency of 1 MHz. + + +dediprog programmer +^^^^^^^^^^^^^^^^^^^ + +An optional ``voltage`` parameter specifies the voltage the Dediprog should use. The default unit is Volt if no unit is specified. +You can use ``mV``, ``milliVolt``, ``V`` or ``Volt`` as unit specifier. Syntax is:: + + flashrom -p dediprog:voltage=value + +where ``value`` can be ``0V``, ``1.8V``, ``2.5V``, ``3.5V`` or the equivalent in mV. + +An optional ``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:: + + flashrom -p dediprog:device=1 + +An optional ``spispeed`` parameter specifies the frequency of the SPI bus. The firmware on the device needs to be 5.0.0 or newer. +Syntax is:: + + flashrom -p dediprog:spispeed=frequency + +where ``frequency`` can be ``375k``, ``750k``, ``1.5M``, ``2.18M``, ``3M``, ``8M``, ``12M`` or ``24M`` (in Hz). +The default is a frequency of 12 MHz. + +An optional ``target`` parameter specifies which target chip should be used. Syntax is:: + + flashrom -p dediprog:target=value + +where ``value`` can be ``1`` or ``2`` to select target chip 1 or 2 respectively. The default is target chip 1. + + +rayer_spi programmer +^^^^^^^^^^^^^^^^^^^^ + +The default I/O base address used for the parallel port is 0x378 and you can use the optional ``iobase`` parameter to +specify an alternate base I/O address with the:: + + flashrom -p rayer_spi:iobase=baseaddr + +syntax where ``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. + +The default cable type is the RayeR cable. You can use the optional ``type`` parameter to specify the cable type with the:: + + flashrom -p rayer_spi:type=model + +syntax where ``model`` can be ``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. + +More information about the RayeR hardware is available at `RayeR's website http://rayer.g6.cz/elektro/spipgm.htm`_. +The Altera ByteBlasterMV datasheet can be obtained from `Altera http://www.altera.co.jp/literature/ds/dsbytemv.pdf`_. +For more information about the Macraigor Wiggler see `their company homepage http://www.macraigor.com/wiggler.htm`_. +The schematic of the Xilinx DLC 5 was published in `a Xilinx guide http://www.xilinx.com/support/documentation/user_guides/xtp029.pdf`_. + + +raiden_debug_spi programmer +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The target of the SPI flashing mux must be specified with the ``target`` parameter with the:: + + flashrom -p raiden_debug_spi:target=chip + +syntax, where ``chip`` is either the ``ap`` or ``ec`` to flash, otherwise a unspecified target terminates at the end-point. + +The default is to use the first available servo. You can use the optional ``serial`` parameter to specify the servo +USB device serial number to use specifically with:: + + flashrom -p raiden_debug_spi:serial=XXX + +The servo device serial number can be found via ``lsusb``. +Raiden will poll the ``ap`` target waiting for the system power to settle on the AP and EC flash devices. + +The optional ``custom_rst=true`` parameter changes the timeout value from 3ms to 10ms:: + + flashrom -p raiden_debug_spi:custom_rst=<true|false> + +syntax, where ``custom_rst=false`` is the implicit default timeout of 3ms. More information about the ChromiumOS servo +hardware is available at `servos website https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/HEAD/docs/servo_v4.md`_. + + +pony_spi programmer +^^^^^^^^^^^^^^^^^^^ + +The serial port (like /dev/ttyS0, /dev/ttyUSB0 on Linux or COM3 on windows) is specified using the mandatory ``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 ``type`` parameter accepts the values ``si_prog`` (default) +or ``serbang``. + +Information about the SI-Prog adapter can be found at `its website http://www.lancos.com/siprogsch.html`_. + +An example call to **flashrom** is:: + + flashrom -p pony_spi:dev=/dev/ttyS0,type=serbang + +Please note that while USB-to-serial adapters work under certain circumstances, this slows down operation considerably. + + +ogp_spi programmer +^^^^^^^^^^^^^^^^^^ + +The flash ROM chip to access must be specified with the ``rom`` parameter:: + + flashrom -p ogp_spi:rom=name + +Where ``name`` is either ``cprom`` or ``s3`` for the configuration ROM and ``bprom`` or ``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 ``pci=`` parameter as explained in the **nic3com** et al. section above. + + +linux_mtd programmer +^^^^^^^^^^^^^^^^^^^^ + +You may specify the MTD device to use with the:: + + flashrom -p linux_mtd:dev=/dev/mtdX + +syntax where ``/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. + +Please note that the linux_mtd driver only works on Linux. + + +linux_spi programmer +^^^^^^^^^^^^^^^^^^^^ + +You have to specify the SPI controller to use with the:: + + flashrom -p linux_spi:dev=/dev/spidevX.Y + +syntax where ``/dev/spidevX.Y`` is the Linux device node for your SPI controller. + +In case the device supports it, you can set the SPI clock frequency with the optional ``spispeed`` parameter. +The frequency is parsed as kilohertz. Example that sets the frequency to 8 MHz:: + + flashrom -p linux_spi:dev=/dev/spidevX.Y,spispeed=8000 + +Please note that the linux_spi driver only works on Linux. + + +mstarddc_spi programmer +^^^^^^^^^^^^^^^^^^^^^^^ + +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 **flashrom** module allows the latter via Linux's I2C driver. + +**IMPORTANT:** +Before using this programmer, the display **MUST** be in standby mode, and only connected to the computer that will run +**flashrom** using a VGA cable, to an inactive VGA output. It absolutely **MUST NOT** be used as a display during the procedure! + +You have to specify the DDC/I2C controller and I2C address to use with the:: + + flashrom -p mstarddc_spi:dev=/dev/i2c-X:YY + +syntax where ``/dev/i2c-X`` is the Linux device node for your I2C controller connected to the display's DDC channel, and +``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:: + + flashrom -p mstarddc_spi:dev=/dev/i2c-1:49 + +It is also possible to inhibit the reset command that is normally sent to the display once the **flashrom** operation is +completed using the optional ``noreset`` parameter. A value of 1 prevents **flashrom** from sending the reset command. +Example that does not reset the display at the end of the operation:: + + flashrom -p mstarddc_spi:dev=/dev/i2c-1:49,noreset=1 + +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 **flashrom** once more, in chip probe mode (not specifying an operation), +without the ``noreset`` parameter, once the flash read/write operation you intended to perform has completed successfully. + +Please also note that the mstarddc_spi driver only works on Linux. + + +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. + + +ch347_spi programmer +^^^^^^^^^^^^^^^^^^^^ + +The WCH CH347 programmer does not currently support any parameters. SPI frequency is fixed at 2 MHz, and CS0 is used +as per the device. + +ni845x_spi programmer +^^^^^^^^^^^^^^^^^^^^^ + +An optional ``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 ``mV``, ``milliVolt``, ``V`` or ``Volt`` as unit specifier. +Syntax is:: + + flashrom -p ni845x_spi:voltage=value + +where ``value`` can be ``1.2V``, ``1.5V``, ``1.8V``, ``2.5V``, ``3.3V`` or the equivalent in mV. + +In the case if none of the programmer's supported IO voltage is within the supported voltage range of the detected flash +chip the **flashrom** will abort the operation (to prevent damaging the flash chip). +You can override this behaviour by passing ``yes`` to the ``ignore_io_voltage_limits`` parameter +(for e.g. if you are using an external voltage translator circuit). Syntax is:: + + flashrom -p ni845x_spi:ignore_io_voltage_limits=yes + +You can use the ``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:: + + flashrom -p ni845x_spi:serial=1230A12 + +An optional ``spispeed`` parameter specifies the frequency of the SPI bus. Syntax is:: + + flashrom -p ni845x_spi:spispeed=frequency + +where ``frequency`` should a number corresponding to the desired frequency in kHz. +The maximum ``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). + +An optional ``cs`` parameter specifies which target chip select line should be used. Syntax is:: + + flashrom -p ni845x_spi:csnumber=value + +where ``value`` should be between ``0`` and ``7``. By default the CS0 is used. + + +digilent_spi programmer +^^^^^^^^^^^^^^^^^^^^^^^ + +An optional ``spispeed`` parameter specifies the frequency of the SPI bus. Syntax is:: + + flashrom -p digilent_spi:spispeed=frequency + +where ``frequency`` can be ``62.5k``, ``125k``, ``250k``, ``500k``, ``1M``, ``2M`` or ``4M`` (in Hz). +The default is a frequency of 4 MHz. + + +dirtyjtag_spi programmer +^^^^^^^^^^^^^^^^^^^^^^^^ + +An optional ``freq`` parameter specifies the frequency of the SPI bus. Syntax is:: + + flashrom -p dirtyjtag_spi:spispeed=frequency + +where ``spispeed`` can be any value in hertz, kilohertz or megahertz supported by the programmer. +The default is a frequency of 100 KHz. + + +jlink_spi programmer +^^^^^^^^^^^^^^^^^^^^ + +This module supports SEGGER J-Link and compatible devices. + +The **MOSI** signal of the flash chip must be attached to **TDI** pin of the programmer, **MISO** to **TDO** and +**SCK** to **TCK**. The chip select (**CS**) signal of the flash chip can be attached to different pins of the +programmer which can be selected with the:: + + flashrom -p jlink_spi:cs=pin + +syntax where ``pin`` can be either ``TRST`` or ``RESET``. The default pin for chip select is ``RESET``. +Note that, when using ``RESET``, it is normal that the indicator LED blinks orange or red. + +Additionally, the ``Tref`` 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. + +Pinout for devices with 20-pin JTAG connector:: + + +-------+ + | 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: + +-------+ + +If there is more than one compatible device connected, you can select which one should be used by specifying its serial +number with the:: + + flashrom -p jlink_spi:serial=number + +syntax where ``number`` is the serial number of the device (which can be found for example in the output of ``lsusb -v``). + +The SPI speed can be selected by using the:: + + flashrom -p jlink_spi:spispeed=frequency + +syntax where ``frequency`` is the SPI clock frequency in kHz. The maximum speed depends on the device in use. + +The ``power=on`` option can be used to activate the 5 V power supply (PWR_5V) of the J-Link during a flash operation. + + +stlinkv3_spi programmer +^^^^^^^^^^^^^^^^^^^^^^^ + +This module supports SPI flash programming through the STMicroelectronics STLINK V3 programmer/debugger's SPI bridge interface:: + + flashrom -p stlinkv3_spi + +If there is more than one compatible device connected, you can select which one should be used by specifying its +serial number with the:: + + flashrom -p stlinkv3_spi:serial=number + +syntax where ``number`` is the serial number of the device (which can be found for example in the output of ``lsusb -v``). + +The SPI speed can be selected by using the:: + + flashrom -p stlinkv3_spi:spispeed=frequency + +syntax where ``frequency`` 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. + + +realtek_mst_i2c_spi, parade_lspcon and mediatek_i2c_spi programmers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These programmers tunnel SPI commands through I2C-connected devices. The I2C bus over which communication occurs must be +specified either by device path with the ``devpath`` option:: + + flashrom -p realtek_mst_i2c_spi:devpath=/dev/i2c-8 + +or by a bus number with the ``bus`` option, which implies a device path like ``/dev/i2c-N`` where ``N`` is the specified +bus number:: + + flashrom -p parade_lspcon:bus=8 + + +realtek_mst_i2c_spi programmer +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This programmer supports SPI flash programming for chips attached to Realtek DisplayPort MST hubs, themselves accessed +through I2C (tunneling SPI flash commands through the MST hub's I2C connection with the host). + + +In-system programming (ISP) mode +"""""""""""""""""""""""""""""""" + +The ``reset_mcu`` and ``enter_isp`` options provide control over device mode changes, where each can be set to ``0`` +or ``1`` to enable or disable the corresponding mode transition. + +``enter_isp`` defaults to ``1``, and if enabled will issue commands to the MST hub when beginning operation to put it +into ISP mode. + +``reset_mcu`` defaults to ``0``, and if enabled will issue a reset command to the MST hub on programming completion, +causing it to exit ISP mode and to reload its own firmware from flash. + +``allow_brick`` defaults to ``no``, however must be set explicitly to ``yes`` to allow the driver to run if you are sure +you have a MST chip. + +The hub must be in ISP mode for SPI flash access to be possible, so it is usually only useful to disable ``enter_isp`` +if an earlier invocation avoided resetting it on completion. For instance, to erase the flash and rewrite it with the +contents of a file without resetting in between (which could render it nonfunctional if attempting to load firmware +from a blank flash):: + + flashrom -p realtek_mst_i2c_spi:bus=0,enter_isp=1,reset_mcu=0 -E + + flashrom -p realtek_mst_i2c_spi:bus=0,enter_isp=0,reset_mcu=1 -w new.bin + + +parade_lspcon programmer +^^^^^^^^^^^^^^^^^^^^^^^^ + +This programmer supports SPI flash programming for chips attached to Parade Technologies DisplayPort-to-HDMI level +shifter/protocol converters (LSPCONs), e.g. the PS175. Communication to the SPI flash is tunneled through the LSPCON +over I2C. + + +mediatek_i2c_spi programmer +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This programmer supports SPI flash programming for chips attached to some Mediatek display controllers, themselves +accessed through I2C (tunneling SPI flash commands through an I2C connection with the host). + +The programmer is designed to support the TSUMOP82JUQ integrated display driver and scaler as used in the Google Meet +Series One Desk 27 (which runs a version of ChromeOS and uses **flashrom** in its ``tsum-scaler-updater`` scripts that ship +with the OS). Other chips may use compatible protocols but have not been tested with this programmer, and external chip +IOs may need to be controlled through other non- **flashrom** means to configure the chip in order for it to operate as expected. + +``devpath`` and ``bus`` options select the I2C bus to use, as described previously. ``allow_brick`` defaults to ``no``, +and must explicitly be set to ``yes`` in order for the programmer to operate. This is required because there is no +mechanism in the driver to positively identify that a given I2C bus is actually connected to a supported device. + + +EXAMPLES +-------- + +To back up and update your BIOS, run:: + + flashrom -p internal -r backup.rom -o backuplog.txt + flashrom -p internal -w newbios.rom -o writelog.txt + +Please make sure to copy backup.rom to some external media before you try to write. That makes offline recovery easier. + +If writing fails and **flashrom** complains about the chip being in an unknown state, you can try to restore the backup by running:: + + flashrom -p internal -w backup.rom -o restorelog.txt + +If you encounter any problems, please contact us and supply backuplog.txt, writelog.txt and restorelog.txt. +See section **BUGS** for contact info. + + +EXIT STATUS +----------- + +**flashrom** exits with 0 on success, 1 on most failures but with 3 if a call to mmap() fails. + + +REQUIREMENTS +------------ + +**flashrom** needs different access permissions for different programmers. + +* internal + + * needs raw memory access + * PCI configuration space access + * raw I/O port access (x86) + * MSR access (x86) + +* atavia + + * needs PCI configuration space access + +* nic3com, nicrealtek, nicnatsemi + + * need PCI configuration space read access + * raw I/O port access + +* atahpt + + * needs PCI configuration space access + * raw I/O port access + +* gfxnvidia, drkaiser, it8212 + + * need PCI configuration space access + * raw memory access + +* rayer_spi + + * needs raw I/O port access + +* raiden_debug_spi + + * needs access to the respective USB device via libusb API version 1.0 + +* satasii, nicintel, nicintel_eeprom, nicintel_spi + + * need PCI configuration space read access + * raw memory access + +* satamv, atapromise + + * need PCI configuration space read access + * raw I/O port access + * raw memory access + +* serprog + + * needs TCP access to the network or userspace access to a serial port + +* buspirate_spi + + * needs userspace access to a serial port + +* ft2232_spi, usbblaster_spi, pickit2_spi + + * need access to the respective USB device via libusb API version 1.0 + +* ch341a_spi, dediprog + + * need access to the respective USB device via libusb API version 1.0 + +* dummy + + * needs no access permissions at all + +* internal, nic3com, nicrealtek, nicnatsemi, gfxnvidia, drkaiser, satasii, satamv, atahpt, atavia, atapromise, asm106x + + * have to be run as superuser/root + * need raw access permission + +* serprog, buspirate_spi, dediprog, usbblaster_spi, ft2232_spi, pickit2_spi, ch341a_spi, digilent_spi, dirtyjtag_spi + + * can be run as normal user on most operating systems if appropriate device permissions are set + +* ogp + + * needs PCI configuration space read access and raw memory access + +* realtek_mst_i2c_spi, parade_lspcon + + * need userspace access to the selected I2C bus + +On OpenBSD, you can obtain raw access permission by setting:: + + securelevel=-1 + +in **/etc/rc.securelevel** and rebooting, or rebooting into single user mode. + + +BUGS +---- + +You can report bugs, ask us questions or send success reports via our communication channels listed here: +`Contact https://www.flashrom.org/Contact`_ + +Also, we provide a `pastebin service https://paste.flashrom.org`_ that is very useful to share logs without spamming +the communication channels. + + +Laptops +------- + +Using **flashrom** on older laptops is dangerous and may easily make your hardware unusable. **flashrom** 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 **flashrom** options in the **Laptops** paragraph in the **internal programmer** +subsection of the **PROGRAMMER-SPECIFIC INFORMATION** section and the information `in our wiki https://flashrom.org/Laptops`_. + +One-time programmable (OTP) memory and unique IDs + +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. **flashrom** 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. + +Similar to OTP memories are unique, factory programmed, unforgeable IDs. They are not modifiable by the user at all. + + +LICENSE +------- + +**flashrom** is covered by the GNU General Public License (GPL), version 2. Some files are additionally available +under any later version of the GPL. + + +COPYRIGHT +--------- +Please see the individual files. + + +AUTHORS +------- + +Andrew Morgan, Anastasia Klimchuk, Carl-Daniel Hailfinger, Claus Gindhart, David Borg, David Hendricks, Dominik Geyer, +Edward O'Callaghan, Eric Biederman, Giampiero Giancipoli, Helge Wagner, Idwer Vollering, Joe Bao, Joerg Fischer, +Joshua Roys, Kyösti Mälkki, Luc Verhaegen, Li-Ta Lo, Mark Marshall, Markus Boas, Mattias Mattsson, Michael Karcher, +Nikolay Petukhov, Patrick Georgi, Peter Lemenkov, Peter Stuge, Reinder E.N. de Haan, Ronald G. Minnich, Ronald Hoogenboom, +Sean Nelson, Stefan Reinauer, Stefan Tauner, Stefan Wildemann, Stephan Guilloux, Steven James, Urja Rannikko, Uwe Hermann, +Wang Qingpei, Yinghai Lu and others, please see the **flashrom** git history for details. + +All still active authors can be reached via `the mailing list <flashrom@flashrom.org>`_. + +This manual page was written by `Uwe Hermann <uwe@hermann-uwe.de>`_, Carl-Daniel Hailfinger, Stefan Tauner and others. +It is licensed under the terms of the GNU GPL (version 2 or later). diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..d06f538 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,41 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +import os + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-inform... + +project = 'flashrom' +# copyright = '2023, The flashrom authors' +author = 'The flashrom authors' +release = os.getenv('FLASHROM_VERSION') + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-config... + +master_doc = 'index' # this is needed for old versions + +extensions = [] + +#templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-ht... + +html_theme = 'alabaster' +#html_static_path = ['_static'] + + + +# -- Options for manual page output -------------------------------------------- +man_make_section_directory = True +man_show_urls = True +man_pages = [ + ('classic_cli_manpage', project, '', [], 8), +] diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..d309a03 --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,11 @@ +.. flashrom documentation master file, created by + sphinx-quickstart on Mon Jan 30 17:34:19 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. toctree:: + :hidden: + + classic_cli_manpage + +.. include:: ../README diff --git a/doc/meson.build b/doc/meson.build new file mode 100644 index 0000000..bdf4493 --- /dev/null +++ b/doc/meson.build @@ -0,0 +1,38 @@ + +sphinx = find_program('sphinx-build', native : true, required : get_option('man-pages').enabled() or get_option('documentation').enabled()) + +man_pages = [ + 'flashrom.8' +] + +if sphinx.found() + if get_option('man-pages').auto() or get_option('man-pages').enabled() + man_outputs = [] + foreach page : man_pages + man_outputs += 'man' + page.substring(-1) + endforeach + + custom_target( + 'man-pages', + command : [sphinx, '-b', 'man', '-q', '-d', '@PRIVATE_DIR@', '@CURRENT_SOURCE_DIR@', '@OUTDIR@'], + env : {'FLASHROM_VERSION' : meson.project_version() }, + build_always_stale : true, # sphinx handles rebuilds + output : man_outputs, + install : true, + install_dir : get_option('mandir'), + ) + endif + + if get_option('documentation').auto() or get_option('documtation').enabled() + custom_target( + 'documentation', + command : [sphinx, '-b', 'html', '-q', '-d', '@PRIVATE_DIR@', '@CURRENT_SOURCE_DIR@', '@OUTDIR@/html'], + env : {'FLASHROM_VERSION' : meson.project_version() }, + build_always_stale : true, # sphinx handles rebuilds + output : 'html', + install : true, + install_dir : get_option('datadir') + '/doc/flashrom' + ) + endif + +endif diff --git a/flashrom.8.tmpl b/flashrom.8.tmpl deleted file mode 100644 index d740db8..0000000 --- a/flashrom.8.tmpl +++ /dev/null @@ -1,1844 +0,0 @@ -." 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 FLASHROM 8 "@MAN_DATE@" "@VERSION@" "@MAN_DATE@" -.SH NAME -flashrom - detect, read, write, verify and erase flash chips -.SH SYNOPSIS -.B flashrom \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-x\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>[:<file>]]] - [\fB--wp-status\fR] [\fB--wp-list\fR] [\fB--wp-enable\fR|\fB--wp-disable\fR] - [\fB--wp-range\fR <start>,<length>|\fB--wp-region\fR <region>] - [\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 flashrom -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, flashrom will only probe for flash chips. It is -recommended that if you try flashrom 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 "flashrom -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 flashrom 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 written to the stdout. -.TP -.B "-E, --erase" -Erase the flash ROM chip. -.TP -.B "-x, --extract" -Extract every region defined on the layout from flash ROM chip to a -file with the same name as the extracted region (replacing spaces with -underscores). -.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 "flashrom -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 -flashrom 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 " flashrom -p prog --layout rom.layout --image normal -w some.rom" -.sp -To update only the images named -.BR "normal " "and " "fallback" ", run:" -.sp -.B " flashrom -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 -flashrom 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 " flashrom -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 -flashrom 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 " flashrom -p prog --fmap-file some.rom --image COREBOOT -w some.rom" -.TP -.B "--ifd" -Read ROM layout from Intel Firmware Descriptor. -.sp -flashrom 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, --include <region>[:<file>]" -Read or write only -.B <region> -to or from ROM. -The -.B "-i" -option may be used multiple times if the user wishes to read or write -multiple regions using a single command. -.sp -The user may optionally specify a corresponding -.B <file> -for any region they wish to read or write. A read operation will read the -corresponding regions from ROM and write individual files for each one. A write -option will read file(s) and write to the corresponding region(s) in ROM. -.sp -For write operations, files specified using -.B "-i" -take precedence over content from the argument to -.B "-w." -.sp -Examples: -.sp - To read regions named -.BR "foo " and " bar" -in layout file -.B <layout> -into region-sized files -.BR "foo.bin " and " bar.bin" ", run: -.sp -.B " flashrom -p prog -l <layout> -i foo:foo.bin -i bar:bar.bin -r rom.bin -.sp - To write files -.BR "foo.bin " and " bar.bin" -into regions named -.BR "foo " and " bar" " in layout file -.BR <layout> -to the ROM, run: -.sp -.B " flashrom -p prog -l <layout> -i foo:foo.bin -i bar:bar.bin -w rom.bin -.TP -.B "--wp-status" -Prints the flash's current status register protection mode and write protection -range. -.TP -.B "--wp-list" -Prints a list of all protection ranges that the flash supports. -.TP -.B "--wp-enable" -Enables hardware status register protection (SRP) if the flash supports it. -Once SRP is enabled, operations that change the flash's status registers -(including \fB--wp-disable\fR and \fB--wp-range\fR) can only be performed -if the flash's #WP pin is at an inactive logic level. -.TP -.B "--wp-disable" -Disables status register protection if the flash allows it. -.TP -.B "--wp-range <start>,<length>" -Configures the flash to protect a range of addresses from <start> to (<start> + -<length> - 1), bounds inclusive. The range must be supported by the flash, see -\fB--wp-list\fR. -.TP -.B "--wp-region <region>" -Same as \fB--wp-range\fR but protects the range occupied by an image region. -This option requires a image layout to be specified, see \fB--layout\fR. The -region must be supported by the flash, see -\fB--wp-list\fR. -.TP -.B "--flash-name" -Prints out the detected flash chip's name. -.TP -.B "--flash-size" -Prints out the detected flash chip's 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 flashrom. -.sp -There are many unlisted boards which will work out of the box, without -special support in flashrom. 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://flashrom.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 flashrom)" -.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 "* 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)" -.sp -.BR "* rayer_spi" " (for SPI flash ROMs attached to a parallel port by one of various cable types)" -.sp -.BR "* raiden_debug_spi" " (For Chrome EC based debug tools - SuzyQable, Servo V4, C2D2 & uServo)" -.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_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 "* realtek_mst_i2c_spi" " (for SPI flash ROMs attached to Realtek DisplayPort hubs accessible through I2C)" -.sp -.BR "* parade_lspcon" " (for SPI flash ROMs attached to Parade Technologies LSPCONs (PS175))" -.sp -.BR "* mediatek_i2c_spi" " (for SPI flash ROMs attached to some Mediatek display devices accessible over I2C)" -.sp -.BR "* dirtyjtag_spi" " (for SPI flash ROMs attached to DirtyJTAG-compatible devices)" -.sp -.BR "* asm106x" " (for SPI flash ROMs attached to ASM106x PCIe SATA controllers)" -.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 "flashrom -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 flashrom 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 " flashrom -p internal:mainboard=<vendor>:<board>" -syntax. -.sp -See the 'Known boards' or 'Known laptops' section in the output -of 'flashrom -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 flashrom have not yet been tested. If your mainboard is detected needing -an untested board enable function, a warning message is printed and the -board enable is not executed, because a wrong board enable function might -cause the system to behave erratically, as board enable functions touch the -low-level internals of a mainboard. Not executing a board enable function -(if one is needed) might cause detection or erasing failure. If your board -protects only part of the flash (commonly the top end, called boot block), -flashrom might encounter an error only after erasing the unprotected part, -so running without the board-enable function might be dangerous for erase -and write (which includes erase). -.sp -The suggested procedure for a mainboard with untested board specific code is -to first try to probe the ROM (just invoke flashrom and check that it -detects your flash chip type) without running the board enable code (i.e. -without any parameters). If it finds your chip, fine. Otherwise, retry -probing your chip with the board-enable code running, using -.sp -.B " flashrom -p internal:boardenable=force" -.sp -If your chip is still not detected, the board enable code seems to be broken -or the flash chip unsupported. Otherwise, make a backup of your current ROM -contents (using -.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 flashrom mailing list, see below. -.sp -.TP -.B Coreboot -.sp -On systems running coreboot, flashrom checks whether the desired image matches -your mainboard. This needs some special board ID to be present in the image. -If flashrom 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 " flashrom -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 " flashrom -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, flashrom should autodetect that configuration. If you want to -set the I/O base port of the IT87 series SPI controller manually instead of -using the value provided by the BIOS, use the -.sp -.B " flashrom -p internal:it87spiport=portnum" -.sp -syntax where -.B portnum -is the I/O port number (must be a multiple of 8). In the unlikely case -flashrom doesn't detect an active IT87 LPC<->SPI bridge, please send a bug -report so we can diagnose the problem. -.sp -.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. Flashrom 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 flashrom detects an active IMC it will disable write support -unless the user forces it with the -.sp -.B " flashrom -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 " flashrom -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 --The default is to use 16.5 MHz and disable Fast Reads. -.sp -* SB8xx, SB9xx, Hudson: from 16.5 MHz up to and including 66 MHz -.sp --The default is to use 16.5 MHz and disable Fast Reads. -.sp -* Yangtze (with SPI 100 engine as found in Kabini and Tamesh): all of them -.sp --The default is to use the frequency that is currently configured. -.sp -An optional -.B spireadmode -parameter specifies the read mode of the SPI bus where applicable (Bolton or later). -Syntax is -.sp -.B " flashrom -p internal:spireadmode=mode" -.sp -where -.B mode -can be -.BR "'Normal\ (up\ to\ 33 MHz)'" ", " "'Normal\ (up\ to\ 66 MHz)'" ", " "'Dual\ IO\ (1-1-2)'" ", " "'Quad\ IO\ (1-1-4)'" ", " "'Dual\ IO\ (1-2-2)'" ", " "'Quad\ IO\ (1-4-4)'" ", or " "'Fast\ Read'" "." -.sp -The default is to use the read mode that is currently configured. -.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 " flashrom -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 " flashrom -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 "flashrom -p internal:fwh_idsel=0x001122334567" -.TP -.B Laptops -.sp -Using flashrom 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://flashrom.org/Laptops "in the wiki" . -Problems occur when the flash chip is shared between BIOS -and EC firmware, and the latter does not expect flashrom -to access the chip. While flashrom 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. flashrom 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 " flashrom -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. flashrom will then issue a warning and restrict -buses like above. In this case you can use -.sp -.B " flashrom -p internal:laptop=this_is_not_a_laptop" -.sp -to tell flashrom (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 flashrom 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 " flashrom -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 "flashrom -p dummy:bus=lpc+fwh" -.sp -The dummy programmer supports flash chip emulation for automated self-tests -without hardware access. If you want to emulate a flash chip, use the -.sp -.B " flashrom -p dummy:emulate=chip" -.sp -syntax where -.B chip -is one of the following chips (please specify only the chip name, not the -vendor): -.sp -.RB "* ST " M25P10.RES " SPI flash chip (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 -.RB "* Dummy vendor " VARIABLE_SIZE " SPI flash chip (configurable size, page write)" -.sp -Example: -.B "flashrom -p dummy:emulate=SST25VF040.REMS" -.sp -To use -.B VARIABLE_SIZE -chip, -.B size -must be specified to configure the size of the flash chip as a power of two. -.sp -Example: -.B "flashrom -p dummy:emulate=VARIABLE_SIZE,size=16777216,image=dummy.bin" -.TP -.B Persistent images -.sp -If you use flash chip emulation, flash image persistence is available as well -by using the -.sp -.B " flashrom -p dummy:emulate=chip,image=image.rom" -.sp -syntax where -.B image.rom -is the file where the simulated chip contents are read on flashrom startup and -where the chip contents on flashrom shutdown are written to. -.sp -Example: -.B "flashrom -p dummy:emulate=M25P10.RES,image=dummy.bin" -.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 " flashrom -p dummy:emulate=chip,spi_write_256_chunksize=size" -.sp -syntax where -.B size -is the number of bytes (min.& 1, max.& 256). -.sp -Example: -.sp -.B " flashrom -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 " flashrom -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, flashrom 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: flashrom 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 " flashrom -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: flashrom 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 " flashrom -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 " flashrom -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 " flashrom -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 "flashrom -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 " flashrom -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://flashrom.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 flashrom 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. Flashrom 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/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 " flashrom -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 " flashrom -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 " flashrom -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 " flashrom -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 " flashrom -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 "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 " flashrom -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 " flashrom -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 " flashrom -p serprog:dev=/dev/device:baud,spispeed=2M" -.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 " flashrom -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 " flashrom -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 " flashrom -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_re..." \ -"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 " flashrom -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 " flashrom -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 " flashrom -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 " flashrom -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 " flashrom -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 " flashrom -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 " flashrom -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. -.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 " flashrom -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 " flashrom -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 "raiden_debug_spi " programmer -.IP -The target of the SPI flashing mux must be specified with the -.B target -parameter with the -.sp -.B " flashrom -p raiden_debug_spi:target=chip" -.sp -syntax, where -.B chip -is either the -.B ap -or -.B ec -to flash, otherwise a unspecified target terminates at the end-point. -.sp -The default is to use the first available servo. You can use the optional -.B serial -parameter to specify the servo USB device serial number to use specifically with -.sp -.B " flashrom -p raiden_debug_spi:serial=XXX" -.sp -The servo device serial number can be found via -.B lsusb. -.sp -Raiden will poll the -.B -ap -target waiting for the system power to settle on the AP and EC flash devices. -.sp -The optional -.B custom_rst=true -parameter changes the timeout value from 3ms to 10ms. -.sp -.B " flashrom -p raiden_debug_spi:custom_rst=<true|false>" -.sp -syntax, where -.B custom_rst=false -is the implicit default timeout of 3ms. -.sp -More information about the ChromiumOS servo hardware is available at -.nh -.URLB "https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/HEAD/doc..." "servo website" . -.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 flashrom is -.sp -.B " flashrom -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 " flashrom -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_mtd " programmer -.IP -You may specify the MTD device to use with the -.sp -.B " flashrom -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 " flashrom -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 " flashrom -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 flashrom 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 flashrom 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 " flashrom -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 " flashrom -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 flashrom -operation is completed using the optional -.B noreset -parameter. A value of 1 prevents flashrom from sending the reset command. -Example that does not reset the display at the end of the operation: -.sp -.B " flashrom -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 flashrom 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 -The WCH CH347 programmer does not currently support any parameters. SPI frequency is fixed at 2 MHz, and CS0 is -used as per the device. -.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 " flashrom -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 flashrom 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 " flashrom -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 " flashrom -p ni845x_spi:serial=1230A12" -.sp -An optional -.B spispeed -parameter specifies the frequency of the SPI bus. -Syntax is -.sp -.B " flashrom -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 " flashrom -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 " flashrom -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. -.sp -.BR "dirtyjtag_spi " programmer -.IP -An optional -.B freq -parameter specifies the frequency of the SPI bus. -Syntax is -.sp -.B " flashrom -p dirtyjtag_spi:spispeed=frequency" -.sp -where -.B spispeed -can be -.BR any value in hertz, kilohertz or megahertz supported by the -programmer. The default is a frequency of 100 KHz. -.sp -.SS -.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 " flashrom -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 " flashrom -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 " flashrom -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 " flashrom -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 " flashrom -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 " flashrom -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 -.BR "realtek_mst_i2c_spi ", " parade_lspcon ", and " mediatek_i2c_spi " programmers -.IP -These programmers tunnel SPI commands through I2C-connected devices. The I2C -bus over which communication occurs must be specified either by device path -with the \fBdevpath\fP option: -.sp -.B " flashrom -p realtek_mst_i2c_spi:devpath=/dev/i2c-8" -.sp -or by a bus number with the \fBbus\fP option, which implies a device path like -/dev/i2c-N where N is the specified bus number: -.sp -.B " flashrom -p parade_lspcon:bus=8" - -.SS -.BR "realtek_mst_i2c_spi " programmer -.IP -This programmer supports SPI flash programming for chips attached to Realtek -DisplayPort MST hubs, themselves accessed through I2C (tunneling SPI flash -commands through the MST hub's I2C connection with the host). -.TP -.B In-system programming (ISP) mode -.sp -The \fBreset_mcu\fP and \fBenter_isp\fP options provide control over device -mode changes, where each can be set to 0 or 1 to enable or disable the -corresponding mode transition. - -\fBenter_isp\fP defaults to 1, and if enabled will issue commands to the MST -hub when beginning operation to put it into ISP mode. - -\fBreset_mcu\fP defaults to 0, and if enabled will issue a reset command to -the MST hub on programming completion, causing it to exit ISP mode and to -reload its own firmware from flash. - -\fBallow_brick\fP defaults to no, however must be set explicitly to "yes" -to allow the driver to run if you are sure you have a MST chip. - -The hub must be in ISP mode for SPI flash access to be possible, so it is -usually only useful to disable \fBenter_isp\fP if an earlier invocation avoided -resetting it on completion. For instance, to erase the flash and -rewrite it with the contents of a file without resetting in between (which -could render it nonfunctional if attempting to load firmware from a blank -flash): -.sp -.B " flashrom -p realtek_mst_i2c_spi:bus=0,enter_isp=1,reset_mcu=0 -E" -.br -.B " flashrom -p realtek_mst_i2c_spi:bus=0,enter_isp=0,reset_mcu=1 -w new.bin" -.SS -.BR "parade_lspcon " programmer -.IP -This programmer supports SPI flash programming for chips attached to Parade -Technologies DisplayPort-to-HDMI level shifter/protocol converters (LSPCONs), -e.g. the PS175. Communication to the SPI flash is tunneled through the LSPCON -over I2C. - -.SS -.BR "mediatek_i2c_spi " programmer -.IP -This programmer supports SPI flash programming for chips attached to some -Mediatek display controllers, themselves accessed through I2C (tunneling -SPI flash commands through an I2C connection with the host). -.sp -The programmer is designed to support the TSUMOP82JUQ integrated display driver -and scaler as used in the Google Meet Series One Desk 27 (which runs a version -of ChromeOS and uses flashrom in its \fBtsum-scaler-updater\fP scripts that -ship with the OS). Other chips may use compatible protocols but have not been -tested with this programmer, and external chip IOs may need to be controlled -through other non-flashrom means to configure the chip in order for it to -operate as expected. -.sp -\fBdevpath\fP and \fBbus\fP options select the I2C bus to use, as described -previously. \fBallow_brick\fP defaults to no, and must explicitly be set to -"yes" in order for the programmer to operate. This is required because there is -no mechanism in the driver to positively identify that a given I2C bus is -actually connected to a supported device. - -.SH EXAMPLES -To back up and update your BIOS, run -.sp -.B flashrom -p internal -r backup.rom -o backuplog.txt -.br -.B flashrom -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 flashrom complains about the chip being in an unknown -state, you can try to restore the backup by running -.sp -.B flashrom -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 -flashrom exits with 0 on success, 1 on most failures but with 3 if a call to mmap() fails. -.SH REQUIREMENTS -flashrom 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 -.B raiden_debug_spi -need access to the respective USB device via libusb API version 1.0. -.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 ", " asm106x ", " -.BR 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 -.BR realtek_mst_i2c_spi " and " parade_lspcon -need userspace access to the selected I2C bus. -.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.flashrom.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 flashrom on older laptops is dangerous and may easily make your hardware -unusable. flashrom 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 flashrom options in the -.B Laptops -paragraph in the -.B internal programmer -subsection of the -.B PROGRAMMER-SPECIFIC INFORMATION -section and the information -.URLB "https://flashrom.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. flashrom 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 flashrom -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 -Anastasia Klimchuk -.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 -Steven James -.br -Urja Rannikko -.br -Uwe Hermann -.br -Wang Qingpei -.br -Yinghai Lu -.br -some others, please see the flashrom git history for details. -.br -All still active authors can be reached via -.MTOB "flashrom@flashrom.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). diff --git a/meson.build b/meson.build index d20f24c..caeea6e 100644 --- a/meson.build +++ b/meson.build @@ -1,7 +1,7 @@ project('flashromutils', 'c', version : run_command('util/getversion.sh', '--version', check : true).stdout().strip(), license : 'GPL-2.0', - meson_version : '>=0.53.0', + meson_version : '>=0.57.0', default_options : [ 'warning_level=2', 'c_std=c99', @@ -11,6 +11,8 @@ ], )
+subdir('doc') + # libtool versioning lt_current = '1' lt_revision = '0' @@ -621,17 +623,6 @@ description : 'library to interact with flashrom', )
-config_manfile = configuration_data() -config_manfile.set('VERSION', version) -config_manfile.set('MAN_DATE', run_command('util/getversion.sh', '--man-date', check : true).stdout().strip()) -configure_file( - input : 'flashrom.8.tmpl', - output : 'flashrom.8', - configuration : config_manfile, - install: true, - install_dir: join_paths(get_option('mandir'), 'man8'), -) - if get_option('classic_cli').auto() or get_option('classic_cli').enabled() classic_cli = executable( 'flashrom', diff --git a/meson_options.txt b/meson_options.txt index 307b551..91d3045 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -18,3 +18,5 @@ 'rayer_spi', 'realtek_mst_i2c_spi', 'satamv', 'satasii', 'serprog', 'stlinkv3_spi', 'usbblaster_spi', ], description: 'Active programmers') option('llvm_cov', type : 'feature', value : 'disabled', description : 'build for llvm code coverage') +option('man-pages', type : 'feature', value : 'auto', description : 'build the man-page for classic_cli') +option('documentation', type : 'feature', value : 'auto', description : 'build the html documentation')
-
Thomas Heijligen (Code Review)