Thomas Heijligen has uploaded this change for review.
[WIP] 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.
So it's also readable in source form. Meson is not yet integrated. To
test run `sphinx-build -M man docs out` from the flashrom top-level
directory. Use `man ./out/man/flashrom.1` to view the result.
A web version can be build with `sphinx-build -M html docs out` and then
be found in `out/html/index.html`.
This is just a proof of concept and I liked it.
Note: This was me just throwing time on a non important subject because
I needed to see some nice results fast.
Change-Id: Iee9f1164c5913e47385e6f7d51dc7775a58b5a67
Signed-off-by: Thomas Heijligen <thomas.heijligen@secunet.com>
---
A docs/conf.py
A docs/index.rst
A docs/man-page.rst
A docs/meson.build
4 files changed, 1,069 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/flashrom refs/changes/19/72619/1
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..9518f25
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,36 @@
+# 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
+
+# -- 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 = '1.4-dev'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+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_pages = [
+ ('man-page', 'flashrom', u'flashrom Dokumentation', [u'FLashrom Contributors'], 1)
+]
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..577a245
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,14 @@
+.. 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::
+
+ man-page
+
+
+The **flashrom** documentation
+==============================
+
+foooooo
diff --git a/docs/man-page.rst b/docs/man-page.rst
new file mode 100644
index 0000000..a1676a1
--- /dev/null
+++ b/docs/man-page.rst
@@ -0,0 +1,960 @@
+FLASHROM MANPAGE
+================
+
+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)"
+ * **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)"
+ 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 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.
+
+ **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 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).
+
+ 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)'**
+ * **'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** or **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 **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.
+
+ **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** and **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 **f** 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>_`.
+
+ **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 one of:
+ * 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
+ * kt-link
+ and **interface** can be one of:
+ * A
+ * B
+ * C
+ * 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=**
+ 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** - 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 dangerprototypes
+ <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 one of:
+ * 375k
+ * 750k
+ * 1.5M
+ * 2.18M
+ * 3M
+ * 8M
+ * 12M
+ * 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))
+ * **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 user 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 the `servo 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.
+
+ **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 **VTref** 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 \fBbus\fP 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) and MSR access (x86)
+ * **atavia** needs PCI configuration space access
+ * **nic3com, nicrealtek, nicnatsemi** need PCI configuration space read access and raw I/O port access
+ * **atahpt** needs PCI configuration space access and raw I/O port access
+ * **gfxnvidia, drkaiser, it8212** need PCI configuration space access and raw memory access.
+ * **rayer_spi** needs raw I/O port access.
+ * **raiden_debug_spi** need access to the respective USB device via libusb API version 1.0.
+ * **satasii, nicintel, nicintel_eeprom, nicintel_spi** need PCI configuration space read access and raw memory access.
+ * **satamv, atapromise** need PCI configuration space read access, raw I/O port access and 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** have to be run as superuser/root, and need additional 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:
+ `<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/docs/meson.build b/docs/meson.build
new file mode 100644
index 0000000..d8b8730
--- /dev/null
+++ b/docs/meson.build
@@ -0,0 +1,34 @@
+
+
+sphinx-build = find_program('sphinx-build', native : true, required : get_option('man-pages'))
+if sphinx.found() and get_option('man-pages').allowed()
+ custom_target(
+ 'man-pages',
+ command : [sphinx-build, '-M', 'man', <src_dir>, <build_dir>],
+ )
+
+
+
+
+
+
+
+# Minimal makefile for Sphinx documentation
+#
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+# SPHINXOPTS ?=
+# SPHINXBUILD ?= sphinx-build
+# SOURCEDIR = source
+# BUILDDIR = build
+#
+# Put it first so that "make" without argument is like "make help".
+# help:
+# @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+#
+# .PHONY: help Makefile
+#
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
+# %: Makefile
+# @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
To view, visit change 72619. To unsubscribe, or for help writing mail filters, visit settings.