Thomas Heijligen submitted this change.
11 is the latest approved patch-set.
No files were changed between the latest approved patch-set and the submitted one.
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(-)
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-information
+
+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-configuration
+
+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-html-output
+
+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_resistors" \
-"in a guide by dangerousprototypes" .
-.sp
-The state of the Bus Pirate power supply pins is controllable through an optional
-.B psus
-parameter. Syntax is
-.sp
-.B " 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/docs/servo_v4.md" "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')
To view, visit change 72619. To unsubscribe, or for help writing mail filters, visit settings.