Anastasia Klimchuk has uploaded this change for review. ( https://review.coreboot.org/c/flashrom/+/74216 )
Change subject: [WAIT FOR CB:73822]doc: Convert README to sphinx ......................................................................
[WAIT FOR CB:73822]doc: Convert README to sphinx
This patch also includes small changes to README file that were agreed earlier:
changing all links to https re-ordering of sections as Build instructions, Installations, Packaging, Contact
Change-Id: I6e0debc0e15a9c4866f6d16fb010cd3f13171ff3 Signed-off-by: Anastasia Klimchuk aklm@chromium.org --- A doc/readme.rst 1 file changed, 261 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/flashrom refs/changes/16/74216/1
diff --git a/doc/readme.rst b/doc/readme.rst new file mode 100644 index 0000000..60ed628 --- /dev/null +++ b/doc/readme.rst @@ -0,0 +1,244 @@ +flashrom README +=============== + +flashrom is a utility for detecting, reading, writing, verifying and erasing +flash chips. It is often used to flash BIOS/EFI/coreboot/firmware images +in-system using a supported mainboard, but it also supports flashing of network +cards (NICs), SATA controller cards, and other external devices which can +program flash chips. + +It supports a wide range of flash chips (most commonly found in SOIC8, DIP8, +SOIC16, WSON8, PLCC32, DIP32, TSOP32, and TSOP40 packages), which use various +protocols such as LPC, FWH, parallel flash, or SPI. + +Do not use flashrom on laptops (yet)! The embedded controller (EC) present in +many laptops might interact badly with any attempts to communicate with the +flash chip and may brick your laptop. + +Please make a backup of your flash chip before writing to it. + +Please see the flashrom(8) manpage :doc:`classic_cli_manpage`. + + +Build Instructions +------------------ + +flashrom supports building with make and meson. + +Meson build system supports almost all the environments, although not exactly +all of them. Full meson support is on the roadmap in the nearest future. +To build flashrom with meson, follow the instruction and information in +:doc:`dev_guide/building_from_source` + +If you are unsure which build system to use, and/or don't know what's the +difference, use make for now. + +The rest of Build Instructions below refers to building flashrom with make. + +To build flashrom you need to install the following software: + + * C compiler (GCC / clang) + * pkg-config + + * pciutils+libpci (if you want support for mainboard or PCI device flashing) + * libusb (if you want FT2232, Dediprog or USB-Blaster support) + * libftdi (if you want FT2232 or USB-Blaster support) + * libjaylink (if you want support for SEGGER J-Link and compatible devices) + +Linux et al: + + * pciutils / libpci + * pciutils-devel / pciutils-dev / libpci-dev + * zlib-devel / zlib1g-dev (needed if libpci was compiled with libz support) + +On FreeBSD, you need the following ports: + + * devel/gmake + * devel/libpci + +On OpenBSD, you need the following ports: + + * devel/gmake + * sysutils/pciutils + +To compile on Linux, use: + +.. code-block:: + + make + +To compile on FreeBSD, OpenBSD or DragonFly BSD, use: + +.. code-block:: + + gmake + +To compile on Nexenta, use: + +.. code-block:: + + make + +To compile on Solaris, use: + +.. code-block:: + + gmake LDFLAGS="-L$pathtolibpci" CC="gcc -I$pathtopciheaders" CFLAGS=-O2 + +To compile on NetBSD (with pciutils, libftdi, libusb installed in /usr/pkg/), use: + +.. code-block:: + + gmake + +To compile and run on Darwin/Mac OS X: + +Install DirectHW from coresystems GmbH. +DirectHW is available at https://www.coreboot.org/DirectHW . + +To cross-compile on Linux for DOS: + +Get packages of the DJGPP cross compiler and install them: + + * djgpp-filesystem djgpp-gcc djgpp-cpp djgpp-runtime djgpp-binutils + +As an alternative, the DJGPP web site offers packages for download as well: + + * djcross-binutils-2.29.1-1ap.x86_64.rpm + * djcross-gcc-7.2.0-1ap.x86_64.rpm + * djcrx-2.05-5.x86_64.rpm + +The cross toolchain packages for your distribution may have slightly different +names (look for packages named *djgpp*). + +Alternatively, you could use a script to build it from scratch: +https://github.com/andrewwutw/build-djgpp + +You will need the libpci and libgetopt library source trees and +their compiled static libraries and header files installed in some +directory say libpci-libgetopt/, which will be later specified with +LIBS_BASE parameter during flashrom compilation. Easiest way to +handle it is to put pciutils, libgetopt and flashrom directories +in one subdirectory. There will be an extra subdirectory libpci-libgetopt +created, which will contain compiled libpci and libgetopt. + +Download pciutils 3.5.6 and apply https://flashrom.org/File:Pciutils-3.5.6.patch.gz +Compile pciutils, using following command line: + +.. code-block:: + + make ZLIB=no DNS=no HOST=i386-djgpp-djgpp CROSS_COMPILE=i586-pc-msdosdjgpp- \ + PREFIX=/ DESTDIR=$PWD/../libpci-libgetopt \ + STRIP="--strip-program=i586-pc-msdosdjgpp-strip -s" install install-lib + +Download and compile with 'make' https://flashrom.org/File:Libgetopt.tar.gz + +Copy the libgetopt.a to ../libpci-libgetopt/lib and +getopt.h to ../libpci-libgetopt/include + +Enter the flashrom directory. + +.. code-block:: + + make CC=i586-pc-msdosdjgpp-gcc STRIP=i586-pc-msdosdjgpp-strip LIBS_BASE=../libpci-libgetopt/ strip + +If you like, you can compress the resulting executable with UPX: + +.. code-block:: + + upx -9 flashrom.exe + +To run flashrom.exe, download https://flashrom.org/File:Csdpmi7b.zip and +unpack CWSDPMI.EXE into the current directory or one in PATH. + +To cross-compile on Linux for Windows: + +Get packages of the MinGW cross compiler and install them: + +.. code-block:: + + mingw32-filesystem mingw32-cross-cpp mingw32-cross-binutils mingw32-cross-gcc + mingw32-runtime mingw32-headers + +The cross toolchain packages for your distribution may have slightly different +names (look for packages named *mingw*). +PCI-based programmers (internal etc.) are not supported on Windows. +Run (change CC= and STRIP= settings where appropriate) + +.. code-block:: + + make CC=i686-w64-mingw32-gcc STRIP=i686-w64-mingw32-strip + +Processor architecture dependent features: + +On non-x86 architectures a few programmers don't work (yet) because they +use port-based I/O which is not directly available on non-x86. Those +programmers will be disabled automatically if you run "make". + +Compiler quirks: + +If you are using clang and if you want to enable only one driver, you may hit an +overzealous compiler warning from clang. Compile with "make WARNERROR=no" to +force it to continue and enjoy. + +Bindings: + +Foreign function interface bindings for the rust language are included in the +bindings folder. These are not compiled as part of the normal build process. +See the readme under bindings/rust for more information. + + +Installation +------------ + +In order to install flashrom and the manpage into /usr/local, type: + +.. code-block:: + + make install + +For installation in a different directory use DESTDIR, e.g. like this: + +.. code-block:: + + make DESTDIR=/usr install + +If you have insufficient permissions for the destination directory, use sudo +by adding sudo in front of the commands above. + + +Packaging +--------- + +To package flashrom and remove dependencies on Git, either use + +.. code-block:: + + make export + or + make tarball + +'make export' will export all flashrom files from the Git repository at +revision HEAD into a directory named "$EXPORTDIR/flashrom-$RELEASENAME" +and will additionally add a "versioninfo.inc" file in that directory to +contain the Git revision of the exported tree and a date for the manual +page. + +'make tarball' will simply tar up the result of make export and compress +it with bzip2. + +The snapshot tarballs are the result of 'make tarball' and require no +further processing. Some git files (for example the rust bindings) are omitted +from the tarball, as controlled by the .gitattributes files. + + +Contact +------- + +The official flashrom website is: + + https://www.flashrom.org/ + +Available contact methods are + + https://www.flashrom.org/Contact
-
Anastasia Klimchuk (Code Review)