firmware/coreboot: Initial import via subtree merge

Signed-off-by: David Hendricks <dhendricks@fb.com>

firmware/coreboot/.checkpatch.conf

@@ -0,0 +1,31 @@
+# Not Linux, so don't expect a Linux tree.
+--no-tree
+
+# Ignore aspects we don't follow here.
+--ignore C99_COMMENTS
+--ignore GLOBAL_INITIALISERS
+--ignore INITIALISED_STATIC
+--ignore LINE_SPACING
+--ignore NEW_TYPEDEFS
+--ignore PREFER_ALIGNED
+--ignore PREFER_PACKED
+--ignore PREFER_PRINTF
+--ignore SPLIT_STRING
+--ignore BLOCK_COMMENT_STYLE
+--ignore AVOID_EXTERNS
+--ignore VOLATILE
+--ignore CONFIG_DESCRIPTION
+--ignore MISSING_SPACE
+--ignore CORRUPTED_PATCH
+
+# FILE_PATH_CHANGES seems to not be working correctly. It will
+# choke on added / deleted files even if the MAINTAINERS file
+# is touched.
+--ignore FILE_PATH_CHANGES
+
+# This one has a linux path hard coded, so it would choke on
+# some commits unnecessarily.
+--ignore EXECUTE_PERMISSIONS
+
+# Exclude the vendorcode directory
+--exclude src/vendorcode

firmware/coreboot/.clang-format

@@ -0,0 +1,10 @@
+BasedOnStyle:                              LLVM
+Language:                                  Cpp
+IndentWidth:                               8
+UseTab:                                    Always
+BreakBeforeBraces:                         Linux
+AllowShortIfStatementsOnASingleLine:       false
+IndentCaseLabels:                          false
+SortIncludes:                              false
+ContinuationIndentWidth:                   8
+ColumnLimit:                               80

firmware/coreboot/.gitignore

@@ -0,0 +1,137 @@
+payloads/libpayload/install/
+payloads/nvramcui/build
+payloads/nvramcui/libpayload
+junit.xml
+abuild*.xml
+.config
+.config.old
+defconfig
+.coreboot-version
+.xcompile
+.ccwrap
+build/
+coreboot-builds/
+payloads/coreinfo/lpbuild/
+payloads/coreinfo/lp.config*
+payloads/external/depthcharge/depthcharge/
+payloads/external/FILO/filo/
+payloads/external/GRUB2/grub2/
+payloads/external/SeaBIOS/seabios/
+payloads/external/tianocore/tianocore/
+payloads/external/tint/tint/
+payloads/external/U-Boot/u-boot/
+payloads/external/Memtest86Plus/memtest86plus/
+payloads/external/iPXE/ipxe/
+util/crossgcc/acpica-unix-*/
+util/crossgcc/binutils-*/
+util/crossgcc/build-*BINUTILS/
+util/crossgcc/build-*EXPAT/
+util/crossgcc/build-*GCC/
+util/crossgcc/build-*GDB/
+util/crossgcc/build-*GMP/
+util/crossgcc/build-*LIBELF/
+util/crossgcc/build-*MPC/
+util/crossgcc/build-*MPFR/
+util/crossgcc/build-*PYTHON/
+util/crossgcc/build-*LVM/
+util/crossgcc/build-*IASL/
+util/crossgcc/expat-*/
+util/crossgcc/gcc-*/
+util/crossgcc/gdb-*/
+util/crossgcc/gmp-*/
+util/crossgcc/libelf-*/
+util/crossgcc/mingwrt-*/
+util/crossgcc/mpc-*/
+util/crossgcc/mpfr-*/
+util/crossgcc/Python-*/
+util/crossgcc/*.src/
+util/crossgcc/tarballs/
+util/crossgcc/w32api-*/
+util/crossgcc/xgcc/
+util/crossgcc/xgcc-*/
+util/crossgcc/xgcc
+site-local
+
+*.\#
+*.bin
+*.debug
+*.elf
+*.o
+*.out
+*.pyc
+*.sw[po]
+/*.rom
+coreboot-builds*/
+
+# Development friendly files
+tags
+.clang_complete
+
+# Cross-compile toolkits
+xgcc/
+tarballs/
+
+#
+# KDE editors create lots of backup files whenever
+# a file is edited, so just ignore them
+*~
+*.kate-swp
+# Ignore Kdevelop project file
+*.kdev4
+
+util/*/.dependencies
+util/*/.test
+util/amdfwtool/amdfwtool
+util/archive/archive
+util/bimgtool/bimgtool
+util/bincfg/bincfg
+util/board_status/board-status
+util/cbfstool/cbfs-compression-tool
+util/cbfstool/cbfstool
+util/cbfstool/fmaptool
+util/cbfstool/ifwitool
+util/cbfstool/rmodtool
+util/cbmem/.dependencies
+util/cbmem/cbmem
+util/dumpmmcr/dumpmmcr
+util/ectool/ectool
+util/futility/futility
+util/genprof/genprof
+util/getpir/getpir
+util/ifdtool/ifdtool
+util/ifdfake/ifdfake
+util/intelmetool/intelmetool
+util/inteltool/.dependencies
+util/inteltool/inteltool
+util/intelvbttool/intelvbttool
+util/k8resdump/k8resdump
+util/lbtdump/lbtdump
+util/mptable/mptable
+util/msrtool/Makefile
+util/msrtool/Makefile.deps
+util/msrtool/msrtool
+util/nvramtool/.dependencies
+util/nvramtool/nvramtool
+util/optionlist/Options.wiki
+util/romcc/build
+util/runfw/googlesnow
+util/superiotool/superiotool
+util/vgabios/testbios
+util/viatool/viatool
+util/autoport/autoport
+util/kbc1126/kbc1126_ec_dump
+util/kbc1126/kbc1126_ec_insert
+
+documentation/*.aux
+documentation/*.idx
+documentation/*.log
+documentation/*.toc
+documentation/*.out
+documentation/*.pdf
+documentation/cpukconfig.tex
+documentation/mainboardkconfig.tex
+documentation/skconfig.tex
+documentation/socketfkconfig.tex
+Documentation/_build
+
+doxygen/*

firmware/coreboot/.gitmodules

@@ -0,0 +1,23 @@
+[submodule "3rdparty/blobs"]
+	path = 3rdparty/blobs
+	url = ../blobs.git
+	update = none
+	ignore = dirty
+[submodule "util/nvidia-cbootimage"]
+	path = util/nvidia/cbootimage
+	url = ../nvidia-cbootimage.git
+[submodule "vboot"]
+	path = 3rdparty/vboot
+	url = ../vboot.git
+[submodule "arm-trusted-firmware"]
+	path = 3rdparty/arm-trusted-firmware
+	url = ../arm-trusted-firmware.git
+[submodule "3rdparty/chromeec"]
+	path = 3rdparty/chromeec
+	url = ../chrome-ec.git
+[submodule "libhwbase"]
+	path = 3rdparty/libhwbase
+	url = ../libhwbase.git
+[submodule "libgfxinit"]
+	path = 3rdparty/libgfxinit
+	url = ../libgfxinit.git

firmware/coreboot/.gitreview

@@ -0,0 +1,5 @@
+[gerrit]
+host=review.coreboot.org
+port=29418
+project=coreboot
+defaultbranch=master

firmware/coreboot/COPYING

@@ -0,0 +1,339 @@
+		    GNU GENERAL PUBLIC LICENSE
+		       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+			    Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+		    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+			    NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+		     END OF TERMS AND CONDITIONS
+
+	    How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, write to the Free Software Foundation, Inc.,
+    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Ty Coon>, 1 April 1989
+  Ty Coon, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.

firmware/coreboot/Documentation/AMD-S3.txt

@@ -0,0 +1,153 @@
+   _____ ____  _____  ______ ____   ____   ____ _______
+  / ____/ __ \|  __ \|  ____|  _ \ / __ \ / __ \__   __|
+ | |   | |  | | |__) | |__  | |_) | |  | | |  | | | |
+ | |   | |  | |  _  /|  __| |  _ <| |  | | |  | | | |
+ | |___| |__| | | \ \| |____| |_) | |__| | |__| | | |
+  \_____\____/|_|  \_\______|____/ \____/ \____/  |_|
+
+           __  __ _____     _____   ____
+     /\   |  \/  |  __ \   / ____| |___ \
+    /  \  | \  / | |  | | | (___     __) |
+   / /\ \ | |\/| | |  | |  \___ \   |__ <
+  / ____ \| |  | | |__| |  ____) |  ___) |
+ /_/    \_\_|  |_|_____/  |_____/  |____/
+
+
+               S3 in coreboot (V 1.2)
+----------------------------------------
+                Zheng Bao
+            <zheng.bao@amd.com>
+            <fishbaozi@gmail.com>
+
+Introduction
+============
+This document is about how the feature S3 is implemented on coreboot,
+specifically on AMD platform. This topic deals with ACPI spec, hardware,
+BIOS, OS. We try to help coreboot users to realize their own S3.
+
+S3 in a nutshell
+================
+The S3 sleeping state is a low wake latency sleeping state where all
+system context is lost except system memory. [1]. S3 is a ACPI
+definition.
+To enter S3, write 3 in SLP_TYPx and set the SLP_EN bit (See ACPI
+registers). But if you do that, board can not resume at where it
+sleeps, because you don't save the context. More often than not, we
+make the board go into S3 by the tools which OSes provide. For
+windows, click Start->sleep. For linux, some distribution provide a
+tools called pm-suspend, which can make the system goto S3. If
+pm-suspend is not available, we can run "echo mem > /sys/power/state",
+but this way may not save all the needed context.
+In S3 state, the power is off. So when the power button is pressed,
+BIOS runs as it does in cold boot. If BIOS didn't detect whether
+board boots or resumes, it would go the same way as boot. It is not
+what we expect. BIOS detects the SLP_TYPx. If it is 3, it means BIOS
+are waking up.
+BIOS is responsible for restore the machine state as it is before
+sleep. It needs restore the memory controller, not overwriting memory
+which is not marked as reserved. For the peripheral which loses its
+registers, BIOS needs to write the original value.
+When everything is done, BIOS needs to find out the wakeup vector
+provided by OSes and jump there. OSes also have work to do. We can go
+to linux kernel or some other open source projects to find out how they
+handle S3 resume.
+
+ACPI registers
+==============
+ACPI specification defines a group of registers. OSes handle all these
+registers to read and write status to all the platform.
+On AMD platform, these registers are provided by southbridge. For
+example, Hudson uses PMIO 60:6F to define ACPI registers.
+OSes don't have any specific driver to know where these registers
+are. BIOS has the responsibility to allocated the IO resources and
+write all these address to FADT, a ACPI defined table.
+
+Memory Layout
+=============
+Restoring memory is the most important job done by BIOS. When the
+power is off, the memory is maintained by standby power. BIOS need to
+make sure that when flow goes to OS, everything in memory should be
+the same as it was.
+
+The chip vendor will provide a way, or code, to wake up the memory
+from sleeping. In AGESA 2008 arch, it is called AmdInitResume.
+
+The BIOS itself needs some memory to run. Either, BIOS marks the erea
+as reserved in e820, or BIOS saves the content into reserved space.
+
+Here is the address Map for S3 Resume. Assumingly the total memory is 1GB.
+00000000 --- 00100000      BIOS Reserved area.
+00100000 --- 00200000      Free
+00200000 --- 01000000      coreboot ramstage area.
+01000000 --- 2e160000      Free
+2e160000 --- 2e170000      ACPI table
+2e170000 --- 2ef70000      OSRAM
+2ef70000 --- 2efe0000      Stack in highmem
+2efe0000 --- 2f000000      heap in highmem
+2f000000                   TOM
+
+AMD requirements in S3
+======================
+Chip vendor like AMD will provide bunch of routines to restore the
+board.[2]
+ * AmdS3Save: It is called in cold boot, save required register into
+ non-volatile storage. Currently, we use SPI flash to store the data.
+ * AmdInitResume: Restore the memory controller.
+ * AmdS3LateRestore: Called after AmdInitResume, restore other
+ register that memory.
+ * (SouthBridge)InitS3EarlyRestore, (SouthBridge)InitS3LateRestore:
+ Provided by Southbridge vendor code. Early is called before PCI
+ enumeration, and Late is called after that.
+
+Lifecycle of booting, sleeping and waking coreboot and Ubuntu
+=============================================================
+1. Cold boot.
+For a system with S3 feature, the BIOS needs to save some data to
+non-volatile storage at cold boot stage. What data need to be save are
+provided by AmdS3Save. After the wrapper calls the AmdS3Save, it gets
+the VolatileStorage and NvStorage, which are where the data are
+located. It is the wrappers's responsibility to save the data.[3][4]
+Currently, the wrappers allocate a CBFS modules in BIOS image. To do
+that, the wrapper needs to have the ability to write flash chips. It
+is not as comprehensive as flashrom. But for the SST chip on Parmer,
+MX chip on Thather, coreboot works well.[5]
+
+2. OS goes in S3.
+For Linux, besides the kernel needs to do some saving, most distributions
+run some scripts. For Ubuntu, scripts are located at /usr/lib/pm-utils/sleep.d.
+  # ls /usr/lib/pm-utils/sleep.d
+   000kernel-change  49bluetooth        90clock       95led
+   00logging         55NetworkManager   94cpufreq     98video-quirk-db-handler
+   00powersave       60_wpa_supplicant  95anacron     99video
+   01PulseAudio      75modules          95hdparm-apm
+The script with lower prefix runs before the one with higher prefix.
+99video is the last one.
+Those scripts have hooks called hibernate, suspend, thaw, resume. For
+each script, suspend is called when system sleeps and wakeup is called
+when system wakeups.
+
+3. Firmware detects S3 wakeup
+As we mentioned, Firmware detects the SLP_TYPx to find out if the board
+wakes up. In romstage.c, AmdInitReset and AmdInitEarly are called
+as they are during cold boot. AmdInitResume and AmdS3LateRestore are
+called only during resume. For whole ramstage, coreboot goes through
+almost the same way as cold boot, other than not calling the AmdInitMid,
+AmdInitLate and AmdS3Save, and restoring all the MTRRs.
+At last step of coreboot stage, coreboot finds out the wakeup vector in FADT,
+written by OS, and jump.
+
+4. OS resumes.
+When Linux resumes, all the sleeping scripts call their resume
+hooks. If we are more lucky, all the scripts can go through. More
+chances that the 99video hangs or fails to get the display
+back. Sometimes it can fixed if CONFIG_S3_VGA_ROM_RUN is unset in
+coreboot/Kconfig. That needs more troubleshooting.
+
+
+Reference
+=========
+[1]   ACPI40a, http://www.acpi.info/spec40a.htm
+[2]   coreboot Vendorcode, {top}/src/vendorcode/amd/agesa/{family}/Proc/Common/
+[3]   coreboot AGESA wrapper, {top}/src/mainboard/amd/parmer/agesawrapper.c
+[4]   coreboot AGESA wrapper, {top}/src/cpu/amd/agesa/s3_resume.c
+[5]   coreboot Southbridge, {top}/src/southbridge/amd/agesa/hudson/spi.c

firmware/coreboot/Documentation/Binary_Extraction.md

@@ -0,0 +1,68 @@
+# Intel IFD Binary Extraction Tutorial
+
+## Part 1: Extracting Binaries
+
+To begin extracting the binaries, first create a directory labeled "binaries"
+in the coreboot directory (i.e. /path/to/coreboot/binaries/).
+
+Now, execute the following commands to extract the binaries from a ROM image.
+**Note:** Make sure you are in the root coreboot directory.
+
+    cd /path/to/coreboot/util/ifdtool
+    ./ifdtool COREBOOT_IMAGE
+    ./ifdtool -d COREBOOT_IMAGE
+    ./ifdtool -x COREBOOT_IMAGE
+
+In the above steps, COREBOOT_IMAGE is the name of the ROM image to extract the
+binaries from, including the file path (ex. /build/coreboot.rom).
+
+Copy the extracted .bin files to the binaries directory you created previously.
+**Note:** You may want to rename your various .bin files to more clearly
+indicate what they are and their purpose.
+
+To extract the mrc.bin, move to the /coreboot/build directory and run the
+following command:
+
+    cd /path/to/coreboot/build/
+    ./cbfstool COREBOOT_IMAGE extract -n mrc.bin -f /path/to/destination/filename
+
+where COREBOOT_IMAGE is the filepath to the ROM image (same image as above),
+/path/to/destination is the filepath to the destination directory and filename
+is the output filename. An example command is given below:
+
+    ./cbfstool coreboot.rom extract -n mrc.bin -f /path/to/coreboot/binaries/mrc.bin
+
+## Part 2: Using extract_blobs.sh
+
+To simplify some of the steps above, there is a script in the
+/path/to/coreboot/util/chromeos/ directory called extract_blobs.sh what will
+extract the flashdescriptor.bin and intel_me.bin files.
+
+To run this script, switch to the /path/to/coreboot/util/chromeos/ directory
+and execute the script providing a coreboot image as an argument.
+
+    cd /path/to/coreboot/util/chromeos/
+    ./extract_blobs.sh COREBOOT_IMAGE
+
+Executing those commands will result in two binary blobs to appear in the
+/path/to/coreboot/util/chromeos/ directory under the names
+'flashdescriptor.bin' and 'me.bin'.
+
+## Part 3: Changing the coreboot configuration settings
+
+To begin using the binaries extracted above, enable the use of binary
+repositories in the menuconfig. From the main coreboot directory, run
+'make menuconfig'. Select "General Setup", then select "Allow use of
+binary-only repository", then exit to the main menu.
+
+To configure the ROM image for a specific board, select "Mainboard". Select
+"Mainboard vendor" and scroll to the correct vendor. Then select "Mainboard
+model" and select the name of the board model. Exit back to the main menu.
+
+To add the binaries you extracted, select "Chipset". Scroll and select "Add a
+System Agent Binary" and set the filepath to your mrc.bin file's filepath.
+Scroll and select "Add Intel descriptor.bin file" and type the filepath for
+your descriptor.bin file. Scroll down and select "Add Intel ME/TXE firmware
+file" and type the filepath for your ME file. Exit to the main menu.
+
+Select "Exit", and select "Yes" when prompted to save your configuration.

firmware/coreboot/Documentation/COPYING

@@ -0,0 +1,401 @@
+Files under Documentation/ are licensed under CC-BY 4.0 terms, printed below.
+As an exception, files under Documentation/ with a history older than 2017-05-24
+might be under different licenses (but should be cleared up ASAP).
+
+------
+Attribution 4.0 International
+
+=======================================================================
+
+Creative Commons Corporation ("Creative Commons") is not a law firm and
+does not provide legal services or legal advice. Distribution of
+Creative Commons public licenses does not create a lawyer-client or
+other relationship. Creative Commons makes its licenses and related
+information available on an "as-is" basis. Creative Commons gives no
+warranties regarding its licenses, any material licensed under their
+terms and conditions, or any related information. Creative Commons
+disclaims all liability for damages resulting from their use to the
+fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and
+conditions that creators and other rights holders may use to share
+original works of authorship and other material subject to copyright
+and certain other rights specified in the public license below. The
+following considerations are for informational purposes only, are not
+exhaustive, and do not form part of our licenses.
+
+     Considerations for licensors: Our public licenses are
+     intended for use by those authorized to give the public
+     permission to use material in ways otherwise restricted by
+     copyright and certain other rights. Our licenses are
+     irrevocable. Licensors should read and understand the terms
+     and conditions of the license they choose before applying it.
+     Licensors should also secure all rights necessary before
+     applying our licenses so that the public can reuse the
+     material as expected. Licensors should clearly mark any
+     material not subject to the license. This includes other CC-
+     licensed material, or material used under an exception or
+     limitation to copyright. More considerations for licensors:
+	wiki.creativecommons.org/Considerations_for_licensors
+
+     Considerations for the public: By using one of our public
+     licenses, a licensor grants the public permission to use the
+     licensed material under specified terms and conditions. If
+     the licensor's permission is not necessary for any reason--for
+     example, because of any applicable exception or limitation to
+     copyright--then that use is not regulated by the license. Our
+     licenses grant only permissions under copyright and certain
+     other rights that a licensor has authority to grant. Use of
+     the licensed material may still be restricted for other
+     reasons, including because others have copyright or other
+     rights in the material. A licensor may make special requests,
+     such as asking that all changes be marked or described.
+     Although not required by our licenses, you are encouraged to
+     respect those requests where reasonable. More_considerations
+     for the public:
+	wiki.creativecommons.org/Considerations_for_licensees
+
+=======================================================================
+
+Creative Commons Attribution 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution 4.0 International Public License ("Public License"). To the
+extent this Public License may be interpreted as a contract, You are
+granted the Licensed Rights in consideration of Your acceptance of
+these terms and conditions, and the Licensor grants You such rights in
+consideration of benefits the Licensor receives from making the
+Licensed Material available under these terms and conditions.
+
+
+Section 1 -- Definitions.
+
+  a. Adapted Material means material subject to Copyright and Similar
+     Rights that is derived from or based upon the Licensed Material
+     and in which the Licensed Material is translated, altered,
+     arranged, transformed, or otherwise modified in a manner requiring
+     permission under the Copyright and Similar Rights held by the
+     Licensor. For purposes of this Public License, where the Licensed
+     Material is a musical work, performance, or sound recording,
+     Adapted Material is always produced where the Licensed Material is
+     synched in timed relation with a moving image.
+
+  b. Adapter's License means the license You apply to Your Copyright
+     and Similar Rights in Your contributions to Adapted Material in
+     accordance with the terms and conditions of this Public License.
+
+  c. Copyright and Similar Rights means copyright and/or similar rights
+     closely related to copyright including, without limitation,
+     performance, broadcast, sound recording, and Sui Generis Database
+     Rights, without regard to how the rights are labeled or
+     categorized. For purposes of this Public License, the rights
+     specified in Section 2(b)(1)-(2) are not Copyright and Similar
+     Rights.
+
+  d. Effective Technological Measures means those measures that, in the
+     absence of proper authority, may not be circumvented under laws
+     fulfilling obligations under Article 11 of the WIPO Copyright
+     Treaty adopted on December 20, 1996, and/or similar international
+     agreements.
+
+  e. Exceptions and Limitations means fair use, fair dealing, and/or
+     any other exception or limitation to Copyright and Similar Rights
+     that applies to Your use of the Licensed Material.
+
+  f. Licensed Material means the artistic or literary work, database,
+     or other material to which the Licensor applied this Public
+     License.
+
+  g. Licensed Rights means the rights granted to You subject to the
+     terms and conditions of this Public License, which are limited to
+     all Copyright and Similar Rights that apply to Your use of the
+     Licensed Material and that the Licensor has authority to license.
+
+  h. Licensor means the individual(s) or entity(ies) granting rights
+     under this Public License.
+
+  i. Share means to provide material to the public by any means or
+     process that requires permission under the Licensed Rights, such
+     as reproduction, public display, public performance, distribution,
+     dissemination, communication, or importation, and to make material
+     available to the public including in ways that members of the
+     public may access the material from a place and at a time
+     individually chosen by them.
+
+  j. Sui Generis Database Rights means rights other than copyright
+     resulting from Directive 96/9/EC of the European Parliament and of
+     the Council of 11 March 1996 on the legal protection of databases,
+     as amended and/or succeeded, as well as other essentially
+     equivalent rights anywhere in the world.
+
+  k. You means the individual or entity exercising the Licensed Rights
+     under this Public License. Your has a corresponding meaning.
+
+
+Section 2 -- Scope.
+
+  a. License grant.
+
+       1. Subject to the terms and conditions of this Public License,
+          the Licensor hereby grants You a worldwide, royalty-free,
+          non-sublicensable, non-exclusive, irrevocable license to
+          exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part; and
+
+            b. produce, reproduce, and Share Adapted Material.
+
+       2. Exceptions and Limitations. For the avoidance of doubt, where
+          Exceptions and Limitations apply to Your use, this Public
+          License does not apply, and You do not need to comply with
+          its terms and conditions.
+
+       3. Term. The term of this Public License is specified in Section
+          6(a).
+
+       4. Media and formats; technical modifications allowed. The
+          Licensor authorizes You to exercise the Licensed Rights in
+          all media and formats whether now known or hereafter created,
+          and to make technical modifications necessary to do so. The
+          Licensor waives and/or agrees not to assert any right or
+          authority to forbid You from making technical modifications
+          necessary to exercise the Licensed Rights, including
+          technical modifications necessary to circumvent Effective
+          Technological Measures. For purposes of this Public License,
+          simply making modifications authorized by this Section 2(a)
+          (4) never produces Adapted Material.
+
+       5. Downstream recipients.
+
+            a. Offer from the Licensor -- Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. No downstream restrictions. You may not offer or impose
+               any additional or different terms or conditions on, or
+               apply any Effective Technological Measures to, the
+               Licensed Material if doing so restricts exercise of the
+               Licensed Rights by any recipient of the Licensed
+               Material.
+
+       6. No endorsement. Nothing in this Public License constitutes or
+          may be construed as permission to assert or imply that You
+          are, or that Your use of the Licensed Material is, connected
+          with, or sponsored, endorsed, or granted official status by,
+          the Licensor or others designated to receive attribution as
+          provided in Section 3(a)(1)(A)(i).
+
+  b. Other rights.
+
+       1. Moral rights, such as the right of integrity, are not
+          licensed under this Public License, nor are publicity,
+          privacy, and/or other similar personality rights; however, to
+          the extent possible, the Licensor waives and/or agrees not to
+          assert any such rights held by the Licensor to the limited
+          extent necessary to allow You to exercise the Licensed
+          Rights, but not otherwise.
+
+       2. Patent and trademark rights are not licensed under this
+          Public License.
+
+       3. To the extent possible, the Licensor waives any right to
+          collect royalties from You for the exercise of the Licensed
+          Rights, whether directly or through a collecting society
+          under any voluntary or waivable statutory or compulsory
+          licensing scheme. In all other cases the Licensor expressly
+          reserves any right to collect such royalties.
+
+
+Section 3 -- License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the
+following conditions.
+
+  a. Attribution.
+
+       1. If You Share the Licensed Material (including in modified
+          form), You must:
+
+            a. retain the following if it is supplied by the Licensor
+               with the Licensed Material:
+
+                 i. identification of the creator(s) of the Licensed
+                    Material and any others designated to receive
+                    attribution, in any reasonable manner requested by
+                    the Licensor (including by pseudonym if
+                    designated);
+
+                ii. a copyright notice;
+
+               iii. a notice that refers to this Public License;
+
+                iv. a notice that refers to the disclaimer of
+                    warranties;
+
+                 v. a URI or hyperlink to the Licensed Material to the
+                    extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI or
+               hyperlink to, this Public License.
+
+       2. You may satisfy the conditions in Section 3(a)(1) in any
+          reasonable manner based on the medium, means, and context in
+          which You Share the Licensed Material. For example, it may be
+          reasonable to satisfy the conditions by providing a URI or
+          hyperlink to a resource that includes the required
+          information.
+
+       3. If requested by the Licensor, You must remove any of the
+          information required by Section 3(a)(1)(A) to the extent
+          reasonably practicable.
+
+       4. If You Share Adapted Material You produce, the Adapter's
+          License You apply must not prevent recipients of the Adapted
+          Material from complying with this Public License.
+
+
+Section 4 -- Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use of the Licensed Material:
+
+  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+     to extract, reuse, reproduce, and Share all or a substantial
+     portion of the contents of the database;
+
+  b. if You include all or a substantial portion of the database
+     contents in a database in which You have Sui Generis Database
+     Rights, then the database in which You have Sui Generis Database
+     Rights (but not its individual contents) is Adapted Material; and
+
+  c. You must comply with the conditions in Section 3(a) if You Share
+     all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+
+Section 5 -- Disclaimer of Warranties and Limitation of Liability.
+
+  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
+     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
+     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
+     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
+     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
+     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
+     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
+     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
+     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
+     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
+     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
+     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
+     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
+     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
+     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
+     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
+
+  c. The disclaimer of warranties and limitation of liability provided
+     above shall be interpreted in a manner that, to the extent
+     possible, most closely approximates an absolute disclaimer and
+     waiver of all liability.
+
+
+Section 6 -- Term and Termination.
+
+  a. This Public License applies for the term of the Copyright and
+     Similar Rights licensed here. However, if You fail to comply with
+     this Public License, then Your rights under this Public License
+     terminate automatically.
+
+  b. Where Your right to use the Licensed Material has terminated under
+     Section 6(a), it reinstates:
+
+       1. automatically as of the date the violation is cured, provided
+          it is cured within 30 days of Your discovery of the
+          violation; or
+
+       2. upon express reinstatement by the Licensor.
+
+     For the avoidance of doubt, this Section 6(b) does not affect any
+     right the Licensor may have to seek remedies for Your violations
+     of this Public License.
+
+  c. For the avoidance of doubt, the Licensor may also offer the
+     Licensed Material under separate terms or conditions or stop
+     distributing the Licensed Material at any time; however, doing so
+     will not terminate this Public License.
+
+  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+     License.
+
+
+Section 7 -- Other Terms and Conditions.
+
+  a. The Licensor shall not be bound by any additional or different
+     terms or conditions communicated by You unless expressly agreed.
+
+  b. Any arrangements, understandings, or agreements regarding the
+     Licensed Material not stated herein are separate from and
+     independent of the terms and conditions of this Public License.
+
+
+Section 8 -- Interpretation.
+
+  a. For the avoidance of doubt, this Public License does not, and
+     shall not be interpreted to, reduce, limit, restrict, or impose
+     conditions on any use of the Licensed Material that could lawfully
+     be made without permission under this Public License.
+
+  b. To the extent possible, if any provision of this Public License is
+     deemed unenforceable, it shall be automatically reformed to the
+     minimum extent necessary to make it enforceable. If the provision
+     cannot be reformed, it shall be severed from this Public License
+     without affecting the enforceability of the remaining terms and
+     conditions.
+
+  c. No term or condition of this Public License will be waived and no
+     failure to comply consented to unless expressly agreed to by the
+     Licensor.
+
+  d. Nothing in this Public License constitutes or may be interpreted
+     as a limitation upon, or waiver of, any privileges and immunities
+     that apply to the Licensor or You, including from the legal
+     processes of any jurisdiction or authority.
+
+
+=======================================================================
+
+Creative Commons is not a party to its public
+licenses. Notwithstanding, Creative Commons may elect to apply one of
+its public licenses to material it publishes and in those instances
+will be considered the “Licensor.” The text of the Creative Commons
+public licenses is dedicated to the public domain under the CC0 Public
+Domain Dedication. Except for the limited purpose of indicating that
+material is shared under a Creative Commons public license or as
+otherwise permitted by the Creative Commons policies published at
+creativecommons.org/policies, Creative Commons does not authorize the
+use of the trademark "Creative Commons" or any other trademark or logo
+of Creative Commons without its prior written consent including,
+without limitation, in connection with any unauthorized modifications
+to any of its public licenses or any other arrangements,
+understandings, or agreements concerning use of licensed material. For
+the avoidance of doubt, this paragraph does not form part of the
+public licenses.
+
+Creative Commons may be contacted at creativecommons.org.
+

firmware/coreboot/Documentation/Intel/Board/Galileo_checklist.html

@@ -0,0 +1,162 @@
+<html>
+<head>
+<title>Galileo Implementation Status</title>
+</title>
+<body>
+<h1>Galileo Implementation Status<br>2016/07/08 06:51:34 PDT</h1>
+<table>
+  <tr><td colspan=2><b>Legend</b></td></tr>
+  <tr><td bgcolor="#ffc0c0">Red</td><td>Required - To-be-implemented</td></tr>
+  <tr><td bgcolor="#ffffc0">Yellow</td><td>Optional</td></tr>
+  <tr><td bgcolor="#c0ffc0">Green</td><td>Implemented</td></tr>
+</table>
+<table>
+  <tr valign="top">
+    <td>
+<table border=1>
+<tr><th colspan=2>bootblock: 100% Done</th></tr>
+<tr><th>Type</th><th>Routine</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>bootblock_c_entry</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>bootblock_main_with_timestamp</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>bootblock_mainboard_early_init</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>bootblock_mainboard_init</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>bootblock_pre_c_entry</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>bootblock_protected_mode_entry</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>bootblock_soc_early_init</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>bootblock_soc_init</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>tsc_freq_mhz</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>uart_init</td></tr>
+</table>
+    </td>
+    <td width=5>&nbsp;</td>
+    <td>
+<table border=1>
+<tr><th colspan=2>romstage: 67% Done</th></tr>
+<tr><th>Type</th><th>Routine</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>arch_segment_loaded</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>backup_top_of_ram</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>boot_device_init</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>car_mainboard_post_console_init</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>car_mainboard_pre_console_init</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>car_soc_post_console_init</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>car_soc_pre_console_init</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>car_stage_entry</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>cbfs_master_header_locator</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>cbmem_fail_resume</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>clear_recovery_mode_switch</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>cpu_smi_handler</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>fill_power_state</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>get_sw_write_protect_state</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>get_top_of_ram</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>gpio_acpi_path</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>init_timer</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_add_dimm_info</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_check_ec_image</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>mainboard_fill_spd_data</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_io_trap_handler</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>mainboard_memory_init_params</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_post</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>mainboard_romstage_entry</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_save_dimm_info</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_apmc</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_gpi</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_sleep</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>map_oprom_vendev</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>migrate_power_state</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>mrc_cache_get_current_with_version</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>mrc_cache_stash_data_with_version</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>platform_prog_run</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>platform_segment_loaded</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>print_fsp_info</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>raminit</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>ramstage_cache_invalid</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>report_memory_config</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>romstage_common</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>save_chromeos_gpios</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>set_max_freq</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>setup_stack_and_mtrrs</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>smm_region</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>smm_region_size</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>soc_after_ram_init</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>soc_display_memory_init_params</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>soc_display_mtrrs</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>soc_get_variable_mtrr_count</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>soc_memory_init_params</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>soc_pre_ram_init</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>southbridge_smi_handler</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>stage_cache_add</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>stage_cache_load_stage</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>timestamp_get</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>tsc_freq_mhz</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_extend</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_finalize</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_init</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>vboot_platform_prepare_reboot</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>verstage_mainboard_init</td></tr>
+</table>
+    </td>
+    <td width=5>&nbsp;</td>
+    <td>
+<table border=1>
+<tr><th colspan=2>ramstage: 60% Done</th></tr>
+<tr><th>Type</th><th>Routine</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>acpi_create_serialio_ssdt</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>arch_segment_loaded</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>backup_top_of_ram</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>boot_device_init</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>cbfs_master_header_locator</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>cbmem_fail_resume</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>clear_recovery_mode_switch</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>cpu_smi_handler</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>fw_cfg_acpi_tables</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>get_sw_write_protect_state</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>get_top_of_ram</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>gpio_acpi_path</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>init_timer</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>lb_board</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>lb_framebuffer</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_add_dimm_info</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_io_trap_handler</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_post</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_silicon_init_params</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_apmc</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_gpi</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_smi_sleep</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mainboard_suspend_resume</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>map_oprom_vendev</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>mirror_payload</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>northbridge_smi_handler</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>nvm_mmio_to_flash_offset</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>platform_prog_run</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>platform_segment_loaded</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>save_chromeos_gpios</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>smbios_mainboard_bios_version</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>smbios_mainboard_manufacturer</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>smbios_mainboard_product_name</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>smbios_mainboard_serial_number</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>smbios_mainboard_set_uuid</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>smbios_mainboard_version</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>smm_disable_busmaster</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>soc_after_silicon_init</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>soc_display_silicon_init_params</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>soc_fill_acpi_wake</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>soc_silicon_init_params</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>soc_skip_ucode_update</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>southbridge_smi_handler</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>stage_cache_add</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>stage_cache_load_stage</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>timestamp_get</td></tr>
+<tr bgcolor=#ffc0c0><td>Required</td><td>timestamp_tick_freq_mhz</td></tr>
+<tr bgcolor=#c0ffc0><td>Required</td><td>tsc_freq_mhz</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_extend</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_finalize</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>vb2ex_hwcrypto_digest_init</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>wifi_regulatory_domain</td></tr>
+<tr bgcolor=#ffffc0><td>Optional</td><td>write_smp_table</td></tr>
+</table>
+    </td>
+    <td width=5>&nbsp;</td>
+  </tr>
+</table>
+</body>
+</html>

firmware/coreboot/Documentation/Intel/Board/board.html

@@ -0,0 +1,239 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Board</title>
+  </head>
+  <body>
+
+<h1>x86 Board Development</h1>
+<p>
+  Board development requires System-on-a-Chip (SoC) support.
+  The combined steps are listed
+  <a target="_blank" href="../development.html">here</a>.
+  The development steps for the board are listed below:
+</p>
+<ol>
+  <li><a href="#RequiredFiles">Required Files</a></li>
+  <li>Enable <a href="#SerialOutput">Serial Output</a></li>
+  <li>Load the <a href="#SpdData">Memory Timing Data</a></li>
+  <li><a href="#DisablePciDevices">Disable</a> the PCI devices</li>
+  <li><a href="#AcpiTables">ACPI Tables</a></li>
+</ol>
+
+
+<hr>
+<h2><a name="RequiredFiles">Required Files</a></h2>
+<p>
+  Create the board directory as src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;.
+</p>
+
+<p>
+  The following files are required to build a new board:
+</p>
+<ol>
+  <li>Kconfig.name - Defines the Kconfig value for the board</li>
+  <li>Kconfig
+    <ol type="A">
+      <li>Selects the SoC for the board and specifies the SPI flash size
+        <ol type="I">
+          <li>BOARD_ROMSIZE_KB_&lt;Size&gt;</li>
+          <li>SOC_&lt;Vendor&gt;_&lt;Chip Family&gt;</li>
+        </ol>
+      </li>
+      <li>Declare the Kconfig values for:
+        <ol type="I">
+          <li>MAINBOARD_DIR</li>
+          <li>MAINBOARD_PART_NUMBER</li>
+          <li>MAINBOARD_VENDOR</li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+  <li>devicetree.cb - Enable root bridge and serial port
+    <ol type="A">
+      <li>The first line must be "chip soc/Intel/&lt;soc family&gt;";
+        this path is used by the generated static.c to include the chip.h
+        header file
+      </li>
+    </ol>
+  </li>
+  <li>romstage.c
+    <ol type="A">
+      <li>Add routine mainboard_romstage_entry which calls romstage_common</li>
+    </ol>
+  </li>
+  <li>Configure coreboot build:
+    <ol type="A">
+      <li>Set LOCALVERSION</li>
+      <li>Select vendor for the board</li>
+      <li>Select the board</li>
+      <li>CBFS_SIZE = 0x00100000</li>
+      <li>Set the CPU_MICROCODE_CBFS_LEN</li>
+      <li>Set the CPU_MICROCODE_CBFS_LOC</li>
+      <li>Set the FSP_IMAGE_ID_STRING</li>
+      <li>Set the FSP_LOC</li>
+      <li>No payload</li>
+      <li>Choose the default value for all other options</li>
+    </ol>
+  </li>
+</ol>
+
+
+<hr>
+<h2><a name="SerialOutput">Enable Serial Output</a></h2>
+<p>
+  Use the following steps to enable serial output:
+</p>
+<ol>
+  <li>Implement the car_mainboard_pre_console_init routine in the com_init.c
+    file:
+    <ol type="A">
+      <li>Power on and enable the UART controller</li>
+      <li>Connect the UART receive and transmit data lines to the
+        appropriate SoC pins
+      </li>
+    </ol>
+  </li>
+  <li>Add Makefile.inc
+    <ol type="A">
+      <li>Add com_init.c to romstage</li>
+    </ol>
+  </li>
+</ol>
+
+
+<hr>
+<h2><a name="SpdData">Memory Timing Data</a></h2>
+<p>
+  Memory timing data is located in the flash.  This data is in the format of
+  <a target="_blank" href="https://en.wikipedia.org/wiki/Serial_presence_detect">serial presence detect</a>
+  (SPD) data.
+  Use the following steps to load the SPD data:
+</p>
+<ol>
+  <li>Edit Kconfig to add the DISPLAY_SPD_DATA" value which enables the
+    display of the SPD data being passed to MemoryInit
+  </li>
+  <li>Create an "spd" subdirectory</li>
+  <li>Create an spd/spd.c file for the SPD implementation
+    <ol type="A">
+      <li>Implement the mainboard_fill_spd_data routine
+        <ol type="i">
+          <li>Read the SPD data either from the spd.bin file or using I2C or SMBUS</li>
+          <li>Fill in the pei_data structure with SPD data for each of the DIMMs</li>
+          <li>Set the DIMM channel configuration</li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+  <li>Add an .spd.hex file containing the memory timing data to the spd subdirectory</li>
+  <li>Create spd/Makefile.inc
+    <ol type="A">
+      <li>Add spd.c to romstage</li>
+      <li>Add the .spd.hex file to SPD_SOURCES</li>
+    </ol>
+  </li>
+  <li>Edit Makefile.inc to add the spd subdirectory</li>
+  <li>Edit romstage.c
+    <ol type="A">
+      <li>Call mainboard_fill_spd_data</li>
+      <li>Add mainboard_memory_init_params to copy the SPD and DRAM
+        configuration data from the pei_data structure into the UPDs
+        for MemoryInit
+      </li>
+    </ol>
+  </li>
+  <li>Edit devicetree.cb
+    <ol type="A">
+      <li>Include the UPD parameters for MemoryInit except for:
+        <ul>
+          <li>Address of SPD data</li>
+          <li>DRAM configuration set above</li>
+        </ul>
+      </li>
+    </ol>
+  </li>
+  <li>A working FSP
+    <a target="_blank" href="../fsp1_1.html#MemoryInit">MemoryInit</a>
+    routine is required to complete debugging</li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x34:
+        - Just after entering
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l67">raminit</a>
+      </li>
+      <li>0x36:
+        - Just before displaying the
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l106">UPD parameters</a>
+        for FSP MemoryInit
+      </li>
+      <li>0x92: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l219">POST_FSP_MEMORY_INIT</a>
+        - Just before calling FSP
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l125">MemoryInit</a>
+      </li>
+      <li>0x37:
+        - Just after returning from FSP
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l127">MemoryInit</a>
+      </li>
+    </ol>
+  </li>
+  <li>Continue debugging with CONFIG_DISPLAY_HOBS enabled until TempRamExit is called</li>
+</ol>
+
+
+
+<hr>
+<h2><a name="DisablePciDevices">Disable PCI Devices</a></h2>
+<p>
+  Ramstage's BS_DEV_ENUMERATE state displays the PCI vendor and device IDs for all
+  of the devices in the system.  Edit the devicetree.cb file:
+</p>
+<ol>
+  <li>Edit the devicetree.cb file:
+    <ol type="A">
+      <li>Add an entry for a PCI device.function and turn it off.  The entry
+        should look similar to:
+<pre><code>device pci 14.0 off end</code></pre>
+      </li>
+      <li>Turn on the devices for:
+        <ul>
+          <li>Memory Controller</li>
+          <li>Debug serial device</li>
+        </ul>
+      </li>
+    </ol>
+  </li>
+  <li>Debug until the BS_DEV_ENUMERATE state shows the proper state for all of the devices</li>
+</ol>
+
+
+
+<hr>
+<h2><a name="AcpiTables">ACPI Tables</a></h2>
+<ol>
+  <li>Edit Kconfig
+    <ol type="A">
+      <li>Add "select HAVE_ACPI_TABLES"</li>
+    </ol>
+  </li>
+  <li>Add the acpi_tables.c module:
+    <ol type="A">
+      <li>Include soc/acpi.h</li>
+      <li>Add the acpi_create_fadt routine
+        <ol type="I">
+          <li>fill in the ACPI header</li>
+          <li>Call the acpi_fill_in_fadt routine</li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+  <li>Add the dsdt.asl module:
+  </li>
+</ol>
+
+
+
+<hr>
+<p>Modified: 20 February 2016</p>
+  </body>
+</html>

firmware/coreboot/Documentation/Intel/Board/galileo.html

@@ -0,0 +1,114 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Galileo</title>
+  </head>
+  <body>
+
+<h1>Intel&reg; Galileo Development Board</h1>
+<table>
+  <tr>
+    <td><a target="_blank" href="http://www.mouser.com/images/microsites/Intel_Galileo2_lrg.jpg"><img alt="Galileo Gen 2" src="http://www.mouser.com/images/microsites/Intel_Galileo2_lrg.jpg" width=500></a></td>
+    <td>
+      The Intel&reg; Galileo Gen 2 mainboard code was developed along with the Intel&reg;
+      <a target="_blank" href="../SoC/quark.html">Quark&trade;</a> SoC:
+      <ul>
+        <li><a target="_blank" href="../development.html">Overall</a> development</li>
+        <li><a target="_blank" href="../SoC/soc.html">SoC</a> support</li>
+        <li><a target="_blank" href="../fsp1_1.html">FSP 1.1</a> integration</li>
+        <li><a target="_blank" href="board.html">Board</a> support</li>
+        <li><a target="_blank" href="Galileo_checklist.html">Implementation Checklist</a></li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+
+<hr>
+<h2>Galileo Board Documentation</h2>
+<ul>
+  <li>Common Components
+    <ul>
+      <li>A/D: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/adc108s102.pdf">ADC108S102</a></li>
+      <li>Analog Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/ts5a23159.pdf">TS5A23159</a></li>
+      <li>Ethernet (10/100 MB/S): Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/dp83848-ep.pdf">DP83848</a></li>
+      <li>Load Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps22920.pdf">TPS22920x</a></li>
+      <li>Memory (256 MiB): Micron <a target="_blank" href="https://www.micron.com/~/media/Documents/Products/Data%20Sheet/DRAM/DDR3/1Gb_1_35V_DDR3L.pdf">MT41K128M8</a></li>
+      <li>SoC: Intel&reg; Quark&trade; <a target="_blank" href="../SoC/quark.html">X-1000</a></li>
+      <li>Serial EEPROM (1 KiB): ON Semiconductor&reg; <a target="_blank" href="http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF">CAT24C08</a></li>
+      <li>SPI Flash (8 MiB): Winbond&trade; <a target="_blank" href="http://www.winbond-usa.com/resource-files/w25q64fv_revl1_100713.pdf">W25Q64FV</a></li>
+      <li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf">TPS62130</a></li>
+      <li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ug/slvu570/slvu570.pdf">TPS652510</a></li>
+      <li>Termination Regulator: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps51200.pdf">TPS51200</a></li>
+    </ul>
+  </li>
+  <li>Make a bootable <a target="_blank" href="https://software.intel.com/en-us/get-started-galileo-linux-step1">micro SD card</a></li>
+</ul>
+
+<h3>Galileo Gen 2 Board Documentation</h3>
+<ul>
+  <li><a target="_blank" href="http://files.linuxgizmos.com/intel_galileo_gen2_blockdiagram.jpg">Block Diagram</a></li>
+  <li><a target="_blank" href="https://software.intel.com/en-us/iot/library/galileo-getting-started">Getting Started</a></li>
+  <li><a target="_blank" href="http://www.intel.com/content/www/us/en/embedded/products/galileo/galileo-overview.html">Overview</a></li>
+  <li><a target="_blank" href="http://files.linuxgizmos.com/intel_galileo_gen2_ports.jpg">Port Diagram</a></li>
+  <li><a target="_blank" href="http://download.intel.com/support/galileo/sb/intelgalileogen2prodbrief_330736_003.pdf">Product Brief</a></li>
+  <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/galileo-g2-schematic.pdf">Schematic</a></li>
+  <li><a target="_blank" href="http://download.intel.com/support/galileo/sb/galileo_boarduserguide_330237_001.pdf">User Guide</a></li>
+  <li>Components
+    <ul>
+      <li>A/D: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/adc108s102.pdf">ADC108S102</a></li>
+      <li>I2C 16-channel, 12-bit PWM: NXP Semiconductors <a target="_blank" href="http://cache.nxp.com/documents/data_sheet/PCA9685.pdf">PCA9685</a></li>
+      <li>I2C I/O Ports: NXP Semiconductors <a target="_blank" href="http://www.nxp.com/documents/data_sheet/PCAL9535A.pdf">PCAL9535A</a></li>
+      <li>Octal Buffer/Driver: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lv541at.pdf">SN74LV541AT</a></li>
+      <li>Quadruple Bus Buffer: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lv125a.pdf">SN74LV125A</a></li>
+      <li>Quadruple Bus Buffer with 3-State Outputs: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lvc126a.pdf">SN74LVC126A</a></li>
+      <li>Serial EEPROM (1 KiB): ON Semiconductor&reg; <a target="_blank" href="http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF">CAT24C08</a></li>
+      <li>Single 2-input multiplexer: NXP Semiconductors <a target="_blank" href="http://www.nxp.com/documents/data_sheet/74LVC1G157.pdf">74LVC1G157</a></li>
+      <li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf">TPS62130</a></li>
+    </ul>
+  </li>
+</ul>
+
+<h3>Galileo Gen 1 Board Documentation</h3>
+<ul>
+  <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/datasheets/galileo-g1-datasheet.pdf">Datasheet</a></li>
+  <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/galileo-g1-schematic.pdf">Schematic</a></li>
+  <li>Components
+    <ul>
+      <li>A/D: Analog Devices <a target="_blank" href="http://www.analog.com/media/en/technical-documentation/data-sheets/AD7298-1.pdf">AD7298</a></li>
+      <li>Analog Switch, 2 channel: Texas Instruments <a target="_blank" href="http://www.ti.com.cn/cn/lit/ds/symlink/ts5a23159.pdf">TS5A23159</a></li>
+      <li>EEPROM & GPIO: Cypress <a target="_blank" href="http://www.cypress.com/file/37971/download">CY8C9540A</a></li>
+      <li>Power Distribution Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps2044b.pdf">TPS2051BDBVR</a></li>
+      <li>RS232 Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/max3232.pdf">MAX3232</a></li>
+      <li>Voltage-Level Translator: Texas Instruments<a target="_blank" href="http://www.ti.com/lit/ds/symlink/txs0108e.pdf">TXS0108E</a></li>
+    </ul>
+  </li>
+</ul>
+
+
+
+<hr>
+<h2>Debug Tools</h2>
+<ul>
+  <li>Flash Programmer:
+    <ul>
+      <li>Dediprog <a target="_blank" href="http://www.dediprog.com/pd/spi-flash-solution/SF100">SF100</a> ISP IC Programmer</li>
+    </ul>
+  </li>
+  <li>JTAG Connector: <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=Olimex+ARM-JTAG-20-10">Olimex ARM-JTAG-20-10</a></li>
+  <li>JTAG Debugger:
+    <ul>
+      <li>Olimex LTD <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=Olimex+ARM-USB-OCD-H">ARM-USB-OCD-H</a></li>
+      <li>Tincan Tools <a target="_blank" href="https://www.tincantools.com/wiki/Flyswatter2">Flyswatter2</a></li>
+    </ul>
+  </li>
+  <li><a target="_blank" href="http://download.intel.com/support/processors/quark/sb/sourcedebugusingopenocd_quark_appnote_330015_003.pdf">Hardware Setup and Software Installation</a></li>
+  <li>USB Serial cable: FTDI <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=FTDI+TTL-232R-3V3">TTL-232R-3V3</a></li>
+</ul>
+
+
+<hr>
+<p>Modified: 29 February 2016</p>
+  </body>
+</html>

firmware/coreboot/Documentation/Intel/SoC/quark.html

@@ -0,0 +1,220 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Quark&trade; SoC</title>
+  </head>
+  <body>
+
+<h1>Intel&reg; Quark&trade; SoC</h1>
+<table>
+  <tr>
+    <td><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-quark-block-diagram-16x9.png"><img alt="Quark Block Diagram" src="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-quark-block-diagram-16x9.png" width=500></a></td>
+    <td>
+      The Quark&trade; SoC code was developed using the
+      <a target="_blank" href="../Board/galileo.html">Galileo Gen 2</a>
+      board:
+      <ul>
+        <li><a target="_blank" href="../development.html">Overall</a> development</li>
+        <li><a target="_blank" href="soc.html">SoC</a> support</li>
+        <li><a target="_blank" href="../fsp1_1.html">FSP 1.1</a> integration</li>
+        <li><a target="_blank" href="../Board/board.html">Board</a> support</li>
+        <li><a target="_blank" href="#QuarkFsp">Quark&trade; FSP</a></li>
+        <li><a target="_blank" href="#CorebootPayloadPkg">CorebootPayloadPkg</a></li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+
+<hr>
+<h2>Quark&trade; Documentation</h2>
+<ul>
+  <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-quark-block-diagram-16x9.png">Block Diagram</a></li>
+  <li><a target="_blank" href="http://www.intel.com/content/www/us/en/embedded/products/quark/specifications.html">Specifications</a>:
+    <ul>
+      <li><a target="_blank" href="http://ark.intel.com/products/79084/Intel-Quark-SoC-X1000-16K-Cache-400-MHz">X1000</a>
+        - <a target="_blank" href="http://www.intel.com/content/www/us/en/search.html?keyword=X1000">Documentation</a>:
+        <ul>
+          <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/datasheets/quark-x1000-datasheet.pdf">Datasheet</a></li>
+          <li><a target="_blank" href="http://www.intel.com/content/dam/support/us/en/documents/processors/quark/sb/intelquarkcore_devman_001.pdf">Developer's Manual</a></li>
+          <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/intel-quark-product-brief-v3.pdf">Product Brief</a></li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li><a target="_blank" href="../index.html#Documentation">More documentation</a></li>
+</ul>
+
+
+
+<hr>
+<h2><a name="CorebootPayloadPkg">Quark&trade; EDK2 CorebootPayloadPkg</a></h2>
+<p>
+Build Instructions:
+</p>
+<ol>
+  <li>Set up <a href="#BuildEnvironment">build environment</a></li>
+  <li>Linux (assumes GCC48):
+<pre><code>build  -p CorebootPayloadPkg/CorebootPayloadPkgIa32.dsc  -a IA32  \
+    -t GCC48  -b DEBUG  -DDEBUG_PROPERTY_MASK=0x27  \
+    -DDEBUG_PRINT_ERROR_LEVEL=0x80000042  -DSHELL_TYPE=BUILD_SHELL  \
+    -DMAX_LOGICAL_PROCESSORS=1
+ls Build/CorebootPayloadPkgIA32/DEBUG_GCC48/FV/UEFIPAYLOAD.fd
+</code></pre>
+  </li>
+  <li>Windows (assumes Visual Studio 2015):
+<pre><code>build  -p CorebootPayloadPkg\CorebootPayloadPkgIa32.dsc  -a IA32  -t VS2015x86  -b DEBUG  -DDEBUG_PROPERTY_MASK=0x27  -DDEBUG_PRINT_ERROR_LEVEL=0x80000042  -DSHELL_TYPE=BUILD_SHELL  -DMAX_LOGICAL_PROCESSORS=1
+dir Build\CorebootPayloadPkgIA32\DEBUG_VS2015x86\FV\UEFIPAYLOAD.fd
+</code></pre>
+  </li>
+  <li>In the .config for coreboot, set the following Kconfig values:
+    <ul>
+      <li>CONFIG_PAYLOAD_ELF=y</li>
+      <li>CONFIG_PAYLOAD_FILE="path to UEFIPAYLOAD.fd"</li>
+    </ul>
+  </li>
+  <li>Build coreboot</li>
+  <li>Copy the image build/coreboot.rom into flash</li>
+</ol>
+
+
+
+<hr>
+<h2><a name="BuildEnvironment">Quark&trade; EDK2 Build Environment</a></h2>
+<p>
+  Use the following steps to setup a build environment:
+</p>
+<ol>
+  <li>Get the EDK2 sources:
+    <ol type="A">
+      <li>EDK2: git clone <a target="_blank" href="https://github.com/tianocore/edk2.git">https://github.com/tianocore/edk2.git</a></li>
+      <li>EDK2-non-osi: git clone <a target="_blank" href="https://github.com/tianocore/edk2-non-osi.git">https://github.com/tianocore/edk2-non-osi.git</a></li>
+      <li>Win32 BaseTools: git clone <a target="_blank" href="https://github.com/tianocore/edk2-BaseTools-win32.git">https://github.com/tianocore/edk2-BaseTools-win32.git</a></li>
+    </ol>
+  </li>
+  <li>Set up a build window:
+    <ul>
+      <li>Linux:
+<pre><code>export WORKSPACE=$PWD
+export PACKAGES_PATH="$PWD/edk2:$PWD/edk2-non-osi"
+cd edk2
+export WORKSPACE=$PWD
+. edksetup.sh
+</code></pre>
+      </li>
+      <li>Windows:
+<pre><code>set WORKSPACE=%CD%
+set PACKAGES_PATH=%WORKSPACE%\edk2;%WORKSPACE%\edk2-non-osi
+set EDK_TOOLS_BIN=%WORKSPACE%\edk2-BaseTools-win32
+cd edk2
+edksetup.bat
+</code></pre>
+      </li>
+    </ul>
+  </li>
+</ol>
+
+
+
+<hr>
+<h2><a name="QuarkFsp">Quark&trade; FSP</a></h2>
+<p>
+Getting the Quark FSP source:
+</p>
+<ol>
+  <li>Set up an EDK-II <a href="#BuildEnvironment">Build Environment</a></li>
+  <li>cd edk2</li>
+  <li>mkdir QuarkFspPkg</li>
+  <li>cd QuarkFspPkg</li>
+  <li>Use git to clone <a target="_blank" href="https://review.gerrithub.io/#/admin/projects/LeeLeahy/quarkfsp">QuarkFspPkg</a> into the QuarkFpsPkg directory (.)</li>
+</ol>
+
+<h3>Building QuarkFspPkg</h3>
+<p>
+There are two versions of FSP: FSP 1.1 and FSP 2.0.  There are also two
+different implementations of FSP, one using subroutines without SEC and
+PEI core and the original implementation which relies on SEC and PEI core.
+Finally there are two different build x86 types release (r32) and debug (d32).
+</p>
+<p>Note that the subroutine implementations are a <b>work in progress</b>.</p>
+<p>
+Build commands shown building debug FSP:
+</p>
+<ul>
+  <li>Linux:
+    <ul>
+      <li>QuarkFspPkg/BuildFsp1_1.sh  -d32</li>
+      <li>QuarkFspPkg/BuildFsp1_1Pei.sh  -d32</li>
+      <li>QuarkFspPkg/BuildFsp2_0.sh  -d32</li>
+      <li>QuarkFspPkg/BuildFsp2_0Pei.sh  -d32</li>
+    </ul>
+  <li>Windows:
+    <ul>
+      <li>QuarkFspPkg/BuildFsp1_1.bat  -d32</li>
+      <li>Windows: QuarkFspPkg/BuildFsp2_0.bat  -d32</li>
+    </ul>
+  </li>
+</ul>
+
+<h3>Copying FSP files into coreboot Source Tree</h3>
+<p>
+There are some helper scripts to copy the FSP output into the coreboot
+source tree.  The parameters to these scripts are:
+</p>
+<ol>
+  <li>EDK2 tree root</li>
+  <li>coreboot tree root</li>
+  <li>Build type: DEBUG or RELEASE</li>
+</ol>
+<p>
+Script files:
+</p>
+<ul>
+  <li>Linux:
+    <ul>
+      <li>QuarkFspPkg/coreboot_fsp1_1.sh</li>
+      <li>QuarkFspPkg/coreboot_fsp1_1Pei.sh</li>
+      <li>QuarkFspPkg/coreboot_fsp2_0.sh</li>
+      <li>QuarkFspPkg/coreboot_fsp2_0Pei.sh</li>
+    </ul>
+</ul>
+
+
+<hr>
+<h2>Quark&trade; EDK2 BIOS</h2>
+<p>
+Build Instructions:
+</p>
+<ol>
+  <li>Set up <a href="#BuildEnvironment">build environment</a></li>
+  <li>Build the image:
+    <ul>
+      <li>Linux:
+<pre><code>build -p QuarkPlatformPkg/Quark.dsc  -a IA32  -t GCC48  -b DEBUG  -DDEBUG_PROPERTY_MASK=0x27  -DDEBUG_PRINT_ERROR_LEVEL=0x80000042
+ls Build/Quark/DEBUG_GCC48/FV/Quark.fd
+</code></pre>
+      </li>
+      <li>Windows:
+<pre><code>build -p QuarkPlatformPkg/Quark.dsc  -a IA32  -t VS2012x86  -b DEBUG  -DDEBUG_PROPERTY_MASK=0x27  -DDEBUG_PRINT_ERROR_LEVEL=0x80000042
+dir Build\Quark\DEBUG_VS2012x86\FV\Quark.fd
+</code></pre>
+  </li>
+    </ul>
+  </li>
+</ol>
+
+<p>
+Documentation:
+</p>
+<ul>
+  <li><a target="_blank" href="https://github.com/tianocore/edk2/tree/master/QuarkPlatformPkg">EDK II firmware for Intel&reg; Quark&trade; SoC X1000 based platforms</a></li>
+  <li>Intel&reg; Quark&trade; SoC X1000 <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/quark-x1000-uefi-firmware-writers-guide.pdf">UEFI Firmware Writer's Guide</a></li>
+</ul>
+
+
+
+<hr>
+<p>Modified: 17 May 2016</p>
+  </body>
+</html>

firmware/coreboot/Documentation/Intel/SoC/soc.html

@@ -0,0 +1,733 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>SoC</title>
+  </head>
+  <body>
+
+<h1>x86 System on a Chip (SoC) Development</h1>
+<p>
+  SoC development is best done in parallel with development for a specific
+  board.  The combined steps are listed
+  <a target="_blank" href="../development.html">here</a>.
+  The development steps for the SoC are listed below:
+</p>
+<ol>
+  <li><a target="_blank" href="../fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li>
+  <li>SoC <a href="#RequiredFiles">Required Files</a></li>
+  <li><a href="#Descriptor">Start Booting</a></li>
+  <li><a href="#EarlyDebug">Early Debug</a></li>
+  <li><a href="#Bootblock">Bootblock</a></li>
+  <li><a href="#TempRamInit">TempRamInit</a></li>
+  <li><a href="#Romstage">Romstage</a>
+    <ol type="A">
+      <li>Enable <a href="#SerialOutput">Serial Output"</a></li>
+      <li>Get the <a href="#PreviousSleepState">Previous Sleep State</a></li>
+      <li>Add the <a href="#MemoryInit">MemoryInit</a> Support</li>
+      <li>Disable the <a href="#DisableShadowRom">Shadow ROM</a></li>
+    </ol>
+  </li>
+  <li><a href="#Ramstage">Ramstage</a>
+    <ol type="A">
+      <li><a href="#DeviceTree">Start Device Tree Processing</a></li>
+      <li>Set up the <a href="#MemoryMap">Memory Map"</a></li>
+    </ol>
+  </li>
+  <li><a href="#AcpiTables">ACPI Tables</a></li>
+  <li><a href="#LegacyHardware">Legacy Hardware</a></li>
+</ol>
+
+
+<hr>
+<h2><a name="RequiredFiles">Required Files</a></h2>
+<p>
+  Create the directory as src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;.
+</p>
+
+<p>
+  The following files are required to build a new SoC:
+</p>
+<ul>
+  <li>Include files
+    <ul>
+      <li>include/soc/pei_data.h</li>
+      <li>include/soc/pm.h</li>
+    </ul>
+  </li>
+  <li>Kconfig - Defines the Kconfig value for the SoC and selects the tool
+    chains for the various stages:
+    <ul>
+      <li>select ARCH_BOOTBLOCK_&lt;Tool Chain&gt;</li>
+      <li>select ARCH_RAMSTAGE_&lt;Tool Chain&gt;</li>
+      <li>select ARCH_ROMSTAGE_&lt;Tool Chain&gt;</li>
+      <li>select ARCH_VERSTAGE_&lt;Tool Chain&gt;</li>
+    </ul>
+  </li>
+  <li>Makefile.inc - Specify the include paths</li>
+  <li>memmap.c - Top of usable RAM</li>
+</ul>
+
+
+<hr>
+<h2><a name="Descriptor">Start Booting</a></h2>
+<p>
+  Some SoC parts require additional firmware components in the flash.
+  This section describes how to add those pieces.
+</p>
+
+<h3>Intel Firmware Descriptor</h3>
+<p>
+  The Intel Firmware Descriptor (IFD) is located at the base of the flash part.
+  The following command overwrites the base of the flash image with the Intel
+  Firmware Descriptor:
+</p>
+<pre><code>dd if=descriptor.bin of=build/coreboot.rom conv=notrunc >/dev/null 2>&1</code></pre>
+
+
+<h3><a name="MEB">Management Engine Binary</a></h3>
+<p>
+  Some SoC parts contain and require that the Management Engine (ME) be running
+  before it is possible to bring the x86 processor out of reset.  A binary file
+  containing the management engine code must be added to the firmware using the
+  ifdtool.  The following commands add this binary blob:
+</p>
+<pre><code>util/ifdtool/ifdtool -i ME:me.bin  build/coreboot.rom
+mv build/coreboot.rom.new build/coreboot.rom
+</code></pre>
+
+
+<h3><a name="EarlyDebug">Early Debug</a></h3>
+<p>
+  Early debugging between the reset vector and the time the serial port is enabled
+  is most easily done by writing values to port 0x80.
+</p>
+
+
+<h3>Success</h3>
+<p>
+  When the reset vector is successfully invoked, port 0x80 will output the following value:
+</p>
+<ul>
+  <li>0x01: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l45">POST_RESET_VECTOR_CORRECT</a>
+    - Bootblock successfully executed the
+    <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/reset16.inc;hb=HEAD#l4">reset vector</a>
+    and entered the 16-bit code at
+    <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/entry16.inc;hb=HEAD#l35">_start</a>
+  </li>
+</ul>
+
+
+<hr>
+<h2><a name="Bootblock">Bootblock</a></h2>
+<p>
+  Implement the bootblock using the following steps:
+</p>
+<ol>
+  <li>Create the directory as src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/bootblock</li>
+  <li>Add the timestamp.inc file which initializes the floating point registers and saves
+    the initial timestamp.
+  </li>
+  <li>Add the bootblock.c file which:
+    <ol type="A">
+      <li>Enables memory-mapped PCI config access</li>
+      <li>Updates the microcode by calling intel_update_microcode_from_cbfs</li>
+      <li>Enable ROM caching</li>
+    </ol>
+  </li>
+  <li>Edit the src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/Kconfig file
+    <ol type="A">
+      <li>Add the BOOTBLOCK_CPU_INIT value to point to the bootblock.c file</li>
+      <li>Add the CHIPSET_BOOTBLOCK_INCLUDE value to point to the timestamp.inc file</li>
+    </ol>
+  </li>
+  <li>Edit the src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/Makefile.inc file
+    <ol type="A">
+      <li>Add the bootblock subdirectory</li>
+    </ol>
+  </li>
+  <li>Edit the src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/memmap.c file
+    <ol type="A">
+      <li>Add the fsp/memmap.h include file</li>
+      <li>Add the mmap_region_granularity routine</li>
+    </ol>
+  </li>
+  <li>Add the necessary .h files to define the necessary values and structures</li>
+  <li>When successful port 0x80 will output the following values:
+    <ol type="A">
+      <li>0x01: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l45">POST_RESET_VECTOR_CORRECT</a>
+        - Bootblock successfully executed the
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/reset16.inc;hb=HEAD#l4">reset vector</a>
+        and entered the 16-bit code at
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/entry16.inc;hb=HEAD#l35">_start</a>
+      </li>
+      <li>0x10: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l53">POST_ENTER_PROTECTED_MODE</a>
+        - Bootblock executing in
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/32bit/entry32.inc;hb=HEAD#l55">32-bit mode</a>
+      </li>
+      <li>0x10 - Verstage/romstage reached 32-bit mode</li>
+    </ol>
+  </li>
+</ol>
+
+<p>
+  <b>Build Note:</b> The following files are included into the default bootblock image:
+</p>
+<ul>
+  <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/bootblock_romcc.S;hb=HEAD">src/arch/x86/bootblock_romcc.S</a>
+    added by   <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l133">src/arch/x86/Makefile.inc</a>
+    and includes the following files:
+    <ul>
+      <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/prologue.inc">src/arch/x86/prologue.inc</a></li>
+      <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/reset16.inc">src/cpu/x86/16bit/reset16.inc</a></li>
+      <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/entry16.inc">src/cpu/x86/16bit/entry16.inc</a></li>
+      <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/32bit/entry32.inc">src/cpu/x86/32bit/entry32.inc</a></li>
+      <li>The code in
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/bootblock_romcc.S">src/arch/x86/bootblock_romcc.S</a>
+        includes src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/bootblock/timestamp.inc using the
+        CONFIG_CHIPSET_BOOTBLOCK_INCLUDE value set above
+      </li>
+      <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/sse_enable.inc">src/cpu/x86/sse_enable.inc</a></li>
+      <li>The code in
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l156">src/arch/x86/Makefile.inc</a>
+        invokes the ROMCC tool to convert the following "C" code into assembler as bootblock.inc:
+        <ul>
+          <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/include/arch/bootblock_romcc.h">src/arch/x86/include/arch/bootblock_romcc.h</a></li>
+          <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/lapic/boot_cpu.c">src/cpu/x86/lapic/boot_cpu.c</a></li>
+          <li>The CONFIG_BOOTBLOCK_CPU_INIT value set above typically points to the code in
+            src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/bootblock/bootblock.c
+          </li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/id.S">src/arch/x86/id.S</a>
+    added by <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l110">src/arch/x86/Makefile.inc</a>
+  </li>
+  <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/intel/fit/fit.S">src/cpu/intel/fit/fit.S</a>
+    added by <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/intel/fit/Makefile.inc;hb=HEAD">src/cpu/intel/fit/Makefile.inc</a>
+  </li>
+  <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/walkcbfs.S">src/arch/x86/walkcbfs.S</a>
+    added by <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l137">src/arch/x86/Makefile.inc</a>
+  </li>
+</ul>
+
+
+<hr>
+<h2><a name="TempRamInit">TempRamInit</a></h2>
+<p>
+  Enable the call to TempRamInit in two stages:
+</p>
+<ol>
+  <li>Finding the FSP binary in the read-only CBFS region</li>
+  <li>Call TempRamInit</li>
+</ol>
+
+
+<h3>Find FSP Binary</h3>
+<p>
+Use the following steps to locate the FSP binary:
+</p>
+<ol>
+  <li>Edit the src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/Kconfig file
+    <ol type="A">
+      <li>Add "select USE_GENERIC_FSP_CAR_INC" to enable the use of
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc">src/drivers/intel/fsp1_1/cache_as_ram.inc</a>
+      </li>
+      <li>Add "select SOC_INTEL_COMMON" to enable the use of the files from src/soc/intel/common
+        specifically building
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/soc/intel/common/util.c">util.c</a>
+      </li>
+    </ol>
+  </li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x90: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
+        - Just before calling
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
+      </li>
+      <li>Alternating 0xba and 0x01 - The FSP image was not found</li>
+    </ol>
+  </li>
+  <li>Add the <a target="_blank" href="../fsp1_1.html#FspBinary">FSP binary file</a> to the flash image</li>
+  <li>Set the following Kconfig values:
+    <ul>
+      <li>CONFIG_FSP_LOC to the FSP base address specified in the previous step</li>
+      <li>CONFIG_FSP_IMAGE_ID_STRING</li>
+    </ul>
+  </li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x90: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
+        - Just before calling
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
+      </li>
+      <li>Alternating 0xbb and 0x02 - TempRamInit executed, no CPU microcode update found</li>
+    </ol>
+  </li>
+</ol>
+
+
+<h3>Calling TempRamInit</h3>
+<p>
+Use the following steps to debug the call to TempRamInit:
+</p>
+<ol>
+  <li>Add the CPU microcode update file
+    <ol type="A">
+      <li>Add the microcode file with the following command
+<pre><code>util/cbfstool/cbfstool build/coreboot.rom add -t microcode -n cpu_microcode_blob.bin -b &lt;base address&gt; -f cpu_microcode_blob.bin</code></pre>
+      </li>
+      <li>Set the Kconfig values
+        <ul>
+          <li>CONFIG_CPU_MICROCODE_CBFS_LOC set to the value from the previous step</li>
+          <li>CONFIG_CPU_MICROCODE_CBFS_LEN</li>
+        </ul>
+      </li>
+    </ol>
+  </li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x90: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
+        - Just before calling
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
+      </li>
+      <li>0x2A - Just before calling
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">cache_as_ram_main</a>
+        which is the start of the verstage code which may be part of romstage
+      </li>
+    </ol>
+  </li>
+</ol>
+
+
+<hr>
+<h2><a name="Romstage">Romstage</a></h2>
+
+<h3><a name="SerialOutput">Serial Output</a></h3>
+<p>
+  The following steps add the serial output support for romstage:
+</p>
+<ol>
+  <li>Create the romstage subdirectory</li>
+  <li>Add romstage/romstage.c
+    <ol type="A">
+      <li>Program the necessary base addresses</li>
+      <li>Disable the TCO</li>
+    </ol>
+  </li>
+  <li>Add romstage/Makefile.inc
+    <ol type="A">
+      <li>Add romstage.c to romstage</li>
+    </ol>
+  </li>
+  <li>Add gpio configuration support if necessary</li>
+  <li>Add the necessary .h files to support the build</li>
+  <li>Update Makefile.inc
+    <ol type="A">
+      <li>Add the romstage subdirectory</li>
+      <li>Add the gpio configuration support file to romstage</li>
+    </ol>
+  </li>
+  <li>Set the necessary Kconfig values to enable serial output:
+    <ul>
+      <li>CONFIG_DRIVERS_UART_&lt;driver&gt;=y</li>
+      <li>CONFIG_CONSOLE_SERIAL=y</li>
+      <li>CONFIG_UART_FOR_CONSOLE=&lt;port&gt;</li>
+      <li>CONFIG_CONSOLE_SERIAL_115200=y</li>
+    </ul>
+  </li>
+</ol>
+
+
+<h3><a name="PreviousSleepState">Determine Previous Sleep State</a></h3>
+<p>
+  The following steps implement the code to get the previous sleep state:
+</p>
+<ol>
+  <li>Implement the fill_power_state routine which determines the previous sleep state</li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x32:
+        - Just after entering
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/romstage.c;hb=HEAD#l99">romstage_common</a>
+      </li>
+      <li>0x33 - Just after calling
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/romstage.c;hb=HEAD#l113">soc_pre_ram_init</a>
+      </li>
+      <li>0x34:
+        - Just after entering
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l67">raminit</a>
+      </li>
+    </ol>
+</ol>
+
+
+<h3><a name="MemoryInit">MemoryInit Support</a></h3>
+<p>
+  The following steps implement the code to support the FSP MemoryInit call:
+</p>
+<ol>
+  <li>Add the chip.h header file to define the UPD values which get passed
+    to MemoryInit.  Skip the values containing SPD addresses and DRAM
+    configuration data which is determined by the board.
+    <p>
+      <b>Build Note</b>: The src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/devicetree.cb
+      file specifies the default values for these parameters.  The build
+      process creates the static.c module which contains the config data
+      structure containing these values.
+    </p>
+  </li>
+  <li>Edit romstage/romstage.c
+    <ol type="A">
+      <li>Implement the romstage/romstage.c/soc_memory_init_params routine to
+        copy the values from the config structure into the UPD structure
+      </li>
+      <li>Implement the soc_display_memory_init_params routine to display
+        the updated UPD parameters by calling fsp_display_upd_value
+      </li>
+    </ol>
+  </li>
+</ol>
+
+
+<h3><a name="DisableShadowRom">Disable Shadow ROM</a></h3>
+<p>
+  A shadow of the SPI flash part is mapped from 0x000e0000 to 0x000fffff.
+  This shadow needs to be disabled to allow RAM to properly respond to
+  this address range.
+</p>
+<ol>
+  <li>Edit romstage/romstage.c and add the soc_after_ram_init routine</li>
+</ol>
+
+
+<hr>
+<h2><a name="Ramstage">Ramstage</a></h2>
+
+<h3><a name="DeviceTree">Start Device Tree Processing</a></h3>
+<p>
+  The src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/devicetree.cb file drives the
+  execution during ramstage.  This file is processed by the util/sconfig utility
+  to generate build/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/static.c.  The various
+  state routines in
+  src/lib/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/lib/hardwaremain.c;hb=HEAD#l128">hardwaremain.c</a>
+  call dev_* routines which use the tables in static.c to locate operation tables
+  associated with the various chips and devices.  After location the operation
+  tables, the state routines call one or more functions depending upon the
+  state of the state machine.
+</p>
+
+<h4><a name="ChipOperations">Chip Operations</a></h4>
+<p>
+  Kick-starting the ramstage state machine requires creating the operation table
+  for the chip listed in devicetree.cb:
+</p>
+<ol>
+  <li>Edit src/soc/&lt;SoC Vendor&gt;/&lt;SoC Family&gt;/chip.c:
+    <ol type="A">
+      <li>
+        This chip's operation table has the name
+        soc_&lt;SoC Vendor&gt;_&lt;SoC Family&gt;_ops which is derived from the
+        chip path specified in the devicetree.cb file.
+      </li>
+      <li>Use the CHIP_NAME macro to specify the name for the chip</li>
+      <li>For FSP 1.1, specify a .init routine which calls intel_silicon_init</li>
+    </ol>
+  </li>
+  <li>Edit src/soc/&lt;SoC Vendor&gt;/&lt;SoC Family&gt;/Makefile.inc and add chip.c to ramstage</li>
+</ol>
+
+<h4>Domain Operations</h4>
+<p>
+  coreboot uses the domain operation table to initiate operations on all of the
+  devices in the domain.  By default coreboot enables all PCI devices which it
+  finds.  Listing a device in devicetree.cb gives the board vendor control over
+  the device state.  Non-PCI devices may also be listed under PCI device such as
+  the LPC bus or SMbus devices.
+</p>
+<ol>
+  <li>Edit src/soc/&lt;SoC Vendor&gt;/&lt;SoC Family&gt;/chip.c:
+    <ol type="A">
+      <li>
+        The domain operation table is typically placed in
+        src/soc/&lt;SoC Vendor&gt;/&lt;SoC Family&gt;/chip.c.
+        The table typically looks like the following:
+<pre><code>static struct device_operations pci_domain_ops = {
+	.read_resources	= pci_domain_read_resources,
+	.set_resources	= pci_domain_set_resources,
+	.scan_bus	= pci_domain_scan_bus,
+};
+</code></pre>
+      </li>
+      <li>
+        Create a .enable_dev entry in the chip operations table which points to a
+        routine which sets the domain table for the device with the DEVICE_PATH_DOMAIN.
+<pre><code>	if (dev->path.type == DEVICE_PATH_DOMAIN) {
+		dev->ops = &pci_domain_ops;
+	}
+</code></pre>
+      </li>
+      <li>
+        During the BS_DEV_ENUMERATE state, ramstage now display the device IDs
+        for the PCI devices on the bus.
+      </li>
+    </ol>
+  </li>
+  <li>Set CONFIG_DEBUG_BOOT_STATE=y in the .config file</li>
+  <li>
+    Debug the result until the PCI vendor and device IDs are displayed
+    during the BS_DEV_ENUMERATE state.
+  </li>
+</ol>
+
+
+<h3><a name="DeviceDrivers">PCI Device Drivers</a></h3>
+<p>
+  PCI device drivers consist of a ".c" file which contains a "pci_driver" data
+  structure at the end of the file with the attribute tag "__pci_driver".  This
+  attribute tag places an entry into a link time table listing the various
+  coreboot device drivers.
+</p>
+<p>
+  Specify the following fields in the table:
+</p>
+<ol>
+  <li>.vendor - PCI vendor ID value of the device</li>
+  <li>.device - PCI device ID value of the device or<br>
+  .devices - Address of a zero terminated array of PCI device IDs
+  </li>
+  <li>.ops - Operations table for the device.  This is the address
+    of a "static struct device_operations" data structure specifying
+    the routines to execute during the different states and sub-states
+    of ramstage's processing.
+  </li>
+  <li>Turn on the device in mainboard/&lt;Vendor&gt;/&lt;Board&gt;/devicetree.cb</li>
+  <li>
+    Debug until the device is on and properly configured in coreboot and
+    usable by the payload
+  </li>
+</ol>
+
+<h4><a name="SubsystemIds">Subsystem IDs</a></h4>
+<p>
+  PCI subsystem IDs are assigned during the BS_DEV_ENABLE state.  The device
+  driver may use the common mechanism to assign subsystem IDs by adding
+  the ".ops_pci" to the pci_driver data structure.  This field points to
+  a "struct pci_operations" that specifies a routine to set the subsystem
+  IDs for the device.  The routine might look something like this:
+</p>
+<pre><code>static void pci_set_subsystem(struct device *dev, unsigned vendor, unsigned device)
+{
+	if (!vendor || !device) {
+		vendor = pci_read_config32(dev, PCI_VENDOR_ID);
+		device = vendor >> 16;
+	}
+	printk(BIOS_SPEW,
+		"PCI: %02x:%02x:%d subsystem vendor: 0x%04x, device: 0x%04x\n",
+		0, PCI_SLOT(dev->path.pci.devfn), PCI_FUNC(dev->path.pci.devfn),
+		vendor & 0xffff, device);
+	pci_write_config32(dev, PCI_SUBSYSTEM_VENDOR_ID,
+			((device & 0xffff) << 16) | (vendor & 0xffff));
+}
+</code></pre>
+
+
+
+<h3>Set up the <a name="MemoryMap">Memory Map</a></h3>
+<p>
+  The memory map is built by the various PCI device drivers during the
+  BS_DEV_RESOURCES state of ramstage.  The northcluster driver will typically
+  specify the DRAM resources while the other drivers will typically specify
+  the IO resources.  These resources are hung off the struct device *data structure by
+  src/device/device_util.c/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/device/device_util.c;hb=HEAD#l448">new_resource</a>.
+</p>
+<p>
+  During the BS_WRITE_TABLES state, coreboot collects these resources and
+  places them into a data structure identified by LB_MEM_TABLE.
+</p>
+<p>
+  Edit the device driver file:
+</p>
+<ol>
+  <li>
+    Implement a read_resources routine which calls macros defined in
+    src/include/device/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/device/device.h;hb=HEAD#l237">device.h</a>
+    like:
+    <ul>
+      <li>ram_resource</li>
+      <li>reserved_ram_resource</li>
+      <li>bad_ram_resource</li>
+      <li>uma_resource</li>
+      <li>mmio_resource</li>
+    </ul>
+  </li>
+</ol>
+
+<p>
+  Testing: Verify that the resources are properly displayed by coreboot during the BS_WRITE_TABLES state.
+</p>
+
+
+
+<hr>
+<h2><a name="AcpiTables">ACPI Tables</a></h2>
+<p>
+  One of the payloads that needs ACPI tables is the EDK2 <a target="_blank" href="quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>.
+</p>
+
+<h3>FADT</h3>
+<p>
+  The EDK2 module
+  CorebootModulePkg/Library/CbParseLib/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/Library/CbParseLib/CbParseLib.c#l450">CbParseLib.c</a>
+  requires that the FADT contains the values in the table below.
+  These values are placed into a HOB identified by
+  <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/CorebootModulePkg.dec#l36">gUefiAcpiBoardInfoGuid</a>
+  by routine
+  CorebootModulePkg/CbSupportPei/CbSupportPei/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/CbSupportPei/CbSupportPei.c#l364">CbPeiEntryPoint</a>.
+</p>
+<table border="1">
+  <tr bgcolor="#c0ffc0">
+    <td>coreboot Field</td>
+    <td>EDK2 Field</td>
+    <td>gUefiAcpiBoardInfoGuid</td>
+    <td>Use</li>
+    <td>
+      <a target="_blank" href="http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf">ACPI Spec.</a>
+      Section
+    </td>
+  </tr>
+  <tr>
+    <td>gpe0_blk<br>gpe0_blk_len</td>
+    <td>Gpe0Blk<br>Gpe0BlkLen</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/Library/CbParseLib/CbParseLib.c#l477">PmGpeEnBase</a>
+    </td>
+    <td><a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l129">Shutdown</a></td>
+    <td>4.8.4.1</td>
+  </tr>
+  <tr>
+    <td>pm1a_cnt_blk</td>
+    <td>Pm1aCntBlk</td>
+    <td>PmCtrlRegBase</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l139">Shutdown</a><br>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l40">Suspend</a>
+    </td>
+    <td>4.8.3.2.1</td>
+  </tr>
+  <tr>
+    <td>pm1a_evt_blk</td>
+    <td>Pm1aEvtBlk</td>
+    <td>PmEvtBase</td>
+    <td><a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l134">Shutdown</a></td>
+    <td>4.8.3.1.1</td>
+  </tr>
+  <tr>
+    <td>pm_tmr_blk</td>
+    <td>PmTmrBlk</td>
+    <td>PmTimerRegBase</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/AcpiTimerLib/AcpiTimerLib.c#l55">Timer</a>
+    </td>
+    <td>4.8.3.3</td>
+  </tr>
+  <tr>
+    <td>reset_reg.</td>
+    <td>ResetReg.Address</td>
+    <td>ResetRegAddress</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l71">Cold</a>
+      and
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l98">Warm</a>
+      resets
+    </td>
+    <td>4.3.3.6</td>
+  </tr>
+  <tr>
+    <td>reset_value</td>
+    <td>ResetValue</td>
+    <td>ResetValue</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l71">Cold</a>
+      and
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l98">Warm</a>
+      resets
+    </td>
+    <td>4.8.3.6</td>
+  </tr>
+</table>
+<p>
+  The EDK2 data structure is defined in
+  MdeModulePkg/Include/IndustryStandard/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/MdePkg/Include/IndustryStandard/Acpi61.h#l111">Acpi61.h</a>
+  The coreboot data structure is defined in
+  src/arch/x86/include/arch/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/include/arch/acpi.h;hb=HEAD#l237">acpi.h</a>
+</p>
+
+<ol>
+  <li>
+    Select <a target="_blank" href="../Board/board.html#AcpiTables">HAVE_ACPI_TABLES</a>
+    in the board's Kconfig file
+  </li>
+  <li>Create a acpi.c module:
+    <ol type="A">
+      <li>Add the acpi_fill_in_fadt routine and initialize the values above</li>
+    </ol>
+  </li>
+</ol>
+
+
+
+<hr>
+<h2><a name="LegacyHardware">Legacy Hardware</a></h2>
+<p>
+  One of the payloads that needs legacy hardare is the EDK2 <a target="_blank" href="quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>.
+</p>
+
+<table border="1">
+  <tr bgcolor="c0ffc0">
+    <th>Peripheral</th>
+    <th>Use</th>
+    <th>8259 Interrupt Vector</th>
+    <th>IDT Base Offset</th>
+    <th>Interrupt Handler</th>
+  </tr>
+  <tr>
+    <td>
+      <a target="_blank" href="http://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf">8254</a>
+      Programmable Interval Timer
+    </td>
+    <td>
+      EDK2: PcAtChipsetPkg/8254TimerDxe/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8254TimerDxe/Timer.c">Timer.c</a>
+    </td>
+    <td>0</td>
+    <td>0x340</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8254TimerDxe/Timer.c#l71">TimerInterruptHandler</a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a target="_blank" href="https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0ahUKEwibxYKU3ZDLAhVOzWMKHfuqB40QFggcMAA&url=http%3A%2F%2Fbochs.sourceforge.net%2Ftechspec%2Fintel-8259a-pic.pdf.gz&usg=AFQjCNF1NT0OQ6ys1Pn6Iv9sv6cKRzZbGg&sig2=HfBszp9xTVO_fajjPWCsJw">8259</a>
+      Programmable Interrupt Controller
+    </td>
+    <td>
+      EDK2: PcAtChipsetPkg/8259InterruptControllerDxe/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8259InterruptControllerDxe/8259.c">8259.c</a>
+    </td>
+    <td>
+      Master interrupts: 0, 2 - 7<br>
+      Slave interrupts: 8 - 15<br>
+      Interrupt vector 1 is never generated, the cascaded input generates interrupts 8 - 15
+    </td>
+    <td>
+      Master: 0x340, 0x350 - 0x378<br>
+      Slave: 0x380 - 0x3b8<br>
+      Interrupt descriptors are 8 bytes each
+    </td>
+    <td>&nbsp;</td>
+  </tr>
+</table>
+
+<hr>
+<p>Modified: 4 March 2016</p>
+  </body>
+</html>

firmware/coreboot/Documentation/Intel/development.html

@@ -0,0 +1,377 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Development</title>
+  </head>
+  <body>
+
+<h1>Intel&reg; x86 coreboot/FSP Development Process</h1>
+<p>
+  The x86 development process for coreboot is broken into the following components:
+</p>
+<ul>
+  <li>coreboot <a target="_blank" href="SoC/soc.html">SoC</a> development</li>
+  <li>coreboot <a target="_blank" href="Board/board.html">mainboard</a> development</li>
+  <li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration</li>
+</ul>
+<p>
+  The development process has two main phases:
+</p>
+<ol>
+  <li>Minimal coreboot; This phase is single threaded</li>
+  <li>Adding coreboot features</li>
+</ol>
+
+<h2>Minimal coreboot</h2>
+<p>
+  The combined steps below describe how to bring up a minimal coreboot for a
+  system-on-a-chip (SoC) and a development board:
+</p>
+<table>
+  <tr bgcolor="#ffffc0">
+    <td>The initial coreboot steps are single threaded!
+      The initial minimal FSP development is also single threaded.
+      Progress can speed up by adding more developers after the minimal coreboot/FSP
+      implementation reaches the payload.
+    </td>
+  </tr>
+</table>
+<ol>
+  <li>Get the necessary tools:
+    <ul>
+      <li>Linux: Use your package manager to install m4 bison flex and the libcurses development
+        package.
+        <ul>
+          <li>Ubuntu or other Linux distribution that use apt, run:
+<pre><code>sudo apt-get install m4 bison flex libncurses5-dev
+</code></pre>
+          </li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li>Build the cross tools for i386:
+    <ul>
+      <li>Linux:
+<pre><code>make crossgcc-i386</code></pre>
+        To use multiple processors for the toolchain build (which takes a long time), use:
+<pre><code>make crossgcc-i386 CPUS=N</code></pre>
+        where N is the number of cores to use for the build.
+      </li>
+    </ul>
+  </li>
+  <li>Get something to build:
+    <ol type="A">
+      <li><a target="_blank" href="fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li>
+      <li><a target="_blank" href="SoC/soc.html#RequiredFiles">SoC</a> required files</li>
+      <li><a target="_blank" href="Board/board.html#RequiredFiles">Board</a> required files</li>
+    </ol>
+  </li>
+  <li>Get result to start <a target="_blank" href="SoC/soc.html#Descriptor">booting</a></li>
+  <li><a target="_blank" href="SoC/soc.html#EarlyDebug">Early Debug</a></li>
+  <li>Implement and debug the <a target="_blank" href="SoC/soc.html#Bootblock">bootblock</a> code</li>
+  <li>Implement and debug the call to <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></li>
+  <li>Enable the serial port
+    <ol type="A">
+      <li>Power on, enable and configure GPIOs for the
+        <a target="_blank" href="Board/board.html#SerialOutput">debug serial UART</a>
+      </li>
+      <li>Add the <a target="_blank" href="SoC/soc.html#SerialOutput">serial outupt</a>
+        support to romstage
+      </li>
+    </ol>
+  </li>
+  <li>Enable <a target="_blank" href="fsp1_1.html#corebootFspDebugging">coreboot/FSP</a> debugging</li>
+  <li>Determine the <a target="_blank" href="SoC/soc.html#PreviousSleepState">Previous Sleep State</a></li>
+  <li>Enable DRAM:
+    <ol type="A">
+      <li>Implement the SoC
+        <a target="_blank" href="SoC/soc.html#MemoryInit">MemoryInit</a>
+        Support
+      </li>
+      <li>Implement the board support to read the
+        <a target="_blank" href="Board/board.html#SpdData">Memory Timing Data</a>
+      </li>
+    </ol>
+  </li>
+  <li>Disable the
+    <a target="_blank" href="SoC/soc.html#DisableShadowRom">Shadow ROM</a>
+  </li>
+  <li>Enable CONFIG_DISPLAY_MTRRS to verify the MTRR configuration</li>
+  <li>
+    Implement the .init routine for the
+    <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a>
+    structure which calls FSP SiliconInit
+  </li>
+  <li>
+    Start ramstage's
+    <a target="_blank" href="SoC/soc.html#DeviceTree">device tree processing</a>
+    to display the PCI vendor and device IDs
+  </li>
+  <li>
+    Disable the
+    <a target="_blank" href="Board/board.html#DisablePciDevices">PCI devices</a>
+  </li>
+  <li>
+    Implement the
+    <a target="_blank" href="SoC/soc.html#MemoryMap">memory map</a>
+  </li>
+  <li>coreboot should now attempt to load the payload</li>
+</ol>
+
+
+
+<h2>Add coreboot Features</h2>
+<p>
+  Most of the coreboot development gets done in this phase.  Implementation tasks in this
+  phase are easily done in parallel.
+</p>
+<ul>
+  <li>Payload and OS Features:
+    <ul>
+      <li><a target="_blank" href="SoC/soc.html#AcpiTables">ACPI Tables</a></li>
+      <li><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</li>
+    </ul>
+  </li>
+</ul>
+
+
+
+<hr>
+<table border="1">
+  <tr bgcolor="#c0ffc0">
+    <th colspan=3><h1>Features</h1></th>
+  </tr>
+  <tr bgcolor="#c0ffc0">
+    <th>SoC</th>
+    <th>Where</th>
+    <th>Testing</th>
+  </tr>
+  <tr>
+    <td>8254 Programmable Interval Timer</td>
+    <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
+    <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
+  </tr>
+  <tr>
+    <td>8259 Programmable Interrupt Controller</td>
+    <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
+    <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
+  </tr>
+  <tr>
+    <td>Cache-as-RAM</td>
+    <td>
+      <a target="_blank" href="SoC/soc.html#TempRamInit">Find</a>
+      FSP binary:
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l38">cache_as_ram.inc</a><br>
+      Enable: FSP 1.1 <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a>
+      called from
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">cache_as_ram.inc</a><br>
+      Disable: FSP 1.1 TempRamExit called from
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
+    </td>
+    <td>FindFSP: POST code 0x90
+      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
+      is displayed<br>
+      Enable: POST code
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
+      is displayed<br>
+      Disable: CONFIG_DISPLAY_MTRRS=y, MTRRs displayed after call to TempRamExit
+    </td>
+  </tr>
+  <tr>
+    <td>Memory Map</td>
+    <td>
+      Implement a device driver for the
+      <a target="_blank" href="SoC/soc.html#MemoryMap">north cluster</a>
+    </td>
+    <td>coreboot displays the memory map correctly during the BS_WRITE_TABLES state</td>
+  </tr>
+  <tr>
+    <td>MTRRs</td>
+    <td>
+      Set values: src/drivers/intel/fsp1_1/stack.c/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/stack.c;hb=HEAD#l42">setup_stack_and_mtrrs</a><br>
+      Load values: src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l71">after_raminit.S</a>
+    </td>
+    <td>Set: Post code 0x91
+      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l213">POST_FSP_TEMP_RAM_EXIT</a>)
+      is displayed by
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
+      Load: Post code 0x3C is displayed by
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l152">after_raminit.S</a><br>
+      and CONFIG_DISPLAY_MTRRS=y displays the correct memory regions</td>
+  </tr>
+  <tr>
+    <td>PCI Device Support</td>
+    <td>Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a></td>
+    <td>The device is detected by coreboot and usable by the payload</td>
+  </tr>
+  <tr>
+    <td>Ramstage state machine</td>
+    <td>
+      Implement the chip and domain operations to start the
+      <a target="_blank" href="SoC/soc.html#DeviceTree">device tree</a>
+      processing
+    </td>
+    <td>
+      During the BS_DEV_ENUMERATE state, ramstage now display the device IDs
+      for the PCI devices on the bus.
+    </td>
+  </tr>
+  <tr>
+    <td>ROM Shadow<br>0x000E0000 - 0x000FFFFF</td>
+    <td>
+      Disable: src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/romstage/romstage.c/<a target="_blank" href="SoC/soc.html#DisableShadowRom">soc_after_ram_init routine</a>
+    </td>
+    <td>Operates as RAM: Writes followed by a read to the 0x000E0000 - 0x000FFFFF region returns the value written</td>
+  </tr>
+
+
+  <tr bgcolor="#c0ffc0">
+    <th>Board</th>
+    <th>Where</th>
+    <th>Testing</th>
+  </tr>
+  <tr>
+    <td>Device Tree</td>
+    <td>
+      <a target="_blank" href="SoC/soc.html#DeviceTree">List</a> PCI vendor and device IDs by starting
+      the device tree processing<br>
+      <a target="_blank" href="Board/board.html#DisablePciDevices">Disable</a> PCI devices<br>
+      Enable: Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a>
+    <td>
+      List: BS_DEV_ENUMERATE state displays PCI vendor and device IDs<br>
+      Disable: BS_DEV_ENUMERATE state shows the devices as disabled<br>
+      Enable: BS_DEV_ENUMERATE state shows the device as on and the device works for the payload
+    </td>
+  </tr>
+  <tr>
+    <td>DRAM</td>
+    <td>
+      Load SPD data: src/soc/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/spd/<a target="_blank" href="Board/board.html#SpdData">spd.c</a><br>
+      UPD Setup:
+      <ul>
+        <li>src/soc&lt;Vendor&gt;//&lt;Chip Family&gt;/romstage/<a target="_blank" href="SoC/soc.html#MemoryInit">romstage.c</a></li>
+        <li>src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/<a target="_blank" href="Board/board.html#SpdData">romstage.c</a></li>
+      </ul>
+      FSP 1.1 MemoryInit called from src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l126">raminit.c</a>
+    </td>
+    <td>Select the following Kconfig values
+      <ul>
+        <li>DISPLAY_HOBS</li>
+        <li>DISPLAY_UPD_DATA</li>
+      </ul>
+      Testing successful if:
+      <ul>
+        <li>MemoryInit UPD values are correct</li>
+        <li>MemoryInit returns 0 (success) and</li>
+        <li>The the message "ERROR - coreboot's requirements not met by FSP binary!"
+          is not displayed
+        </li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>Serial Port</td>
+    <td>
+      SoC <a target="_blank" href="SoC/soc.html#SerialOutput">Support</a><br>
+      Enable: src/soc/mainboard/&lt;Board&gt;/com_init.c/<a target="_blank" href="Board/board.html#SerialOutput">car_mainboard_pre_console_init</a>
+    </td>
+    <td>Debug serial output works</td>
+  </tr>
+
+
+  <tr bgcolor="#c0ffc0">
+    <th>Payload</th>
+    <th>Where</th>
+    <th>Testing</th>
+  </tr>
+  <tr>
+    <td>ACPI Tables</td>
+    <td>
+      SoC <a target="_blank" href="SoC/soc.html#AcpiTables">Support</a><br>
+    </td>
+    <td>Verified by payload or OS</td>
+  </tr>
+
+
+  <tr bgcolor="#c0ffc0">
+    <th>FSP</th>
+    <th>Where</th>
+    <th>Testing</th>
+  </tr>
+  <tr>
+    <td>TempRamInit</td>
+    <td>FSP <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></td>
+    <td>FSP binary found: POST code 0x90
+      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
+      is displayed<br>
+      TempRamInit successful: POST code
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
+      is displayed<br>
+    </td>
+  </tr>
+  <tr>
+    <td>MemoryInit</td>
+    <td><a target="_blank" href="SoC/soc.html#MemoryInit">SoC</a> support<br>
+      <a target="_blank" href="Board/board.html#SpdData">Board</a> support<br>
+    </td>
+    <td>Select the following Kconfig values
+      <ul>
+        <li>DISPLAY_HOBS</li>
+        <li>DISPLAY_UPD_DATA</li>
+      </ul>
+      Testing successful if:
+      <ul>
+        <li>MemoryInit UPD values are correct</li>
+        <li>MemoryInit returns 0 (success) and</li>
+        <li>The the message "ERROR - coreboot's requirements not met by FSP binary!"
+          is not displayed
+        </li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>TempRamExit</td>
+    <td>src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l51">after_raminit.S</a></td>
+    <td>Post code 0x91
+      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l212">POST_FSP_TEMP_RAM_EXIT</a>)
+      is displayed before calling TempRamExit by
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l141">after_raminit.S</a>,
+      CONFIG_DISPLAY_MTRRS=y displays the correct memory regions and
+      Post code 0x39 is displayed by
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l141">after_raminit.S</a><br>
+    </td>
+  </tr>
+  <tr>
+    <td>SiliconInit</td>
+    <td>
+      Implement the .init routine for the
+      <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a> structure
+    </td>
+    <td>During BS_DEV_INIT_CHIPS state, SiliconInit gets called and returns 0x00000000</td>
+  </tr>
+  <tr>
+    <td>FspNotify</td>
+    <td>
+      The code which calls FspNotify is located in
+      src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/fsp_util.c;hb=HEAD#l182">fsp_util.c</a>.
+      The fsp_notify_boot_state_callback routine is called three times as specified
+      by the BOOT_STATE_INIT_ENTRY macros below the routine.
+    </td>
+    <td>
+      The FspNotify routines are called during:
+      <ul>
+        <li>BS_DEV_RESOURCES - on exit</li>
+        <li>BS_PAYLOAD_LOAD - on exit</li>
+        <li>BS_OS_RESUME - on entry (S3 resume)</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+
+<hr>
+<p>Modified: 4 March 2016</p>
+  </body>
+</html>

firmware/coreboot/Documentation/Intel/fsp1_1.html

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>FSP 1.1</title>
+  </head>
+  <body>
+
+<h1>FSP 1.1</h1>
+
+<h2>x86 FSP 1.1 Integration</h2>
+<p>
+  Firmware Support Package (FSP) integration requires System-on-a-Chip (SoC)
+  and board support.  The combined steps are listed
+  <a target="_blank" href="development.html">here</a>.
+  The development steps for FSP are listed below:
+</p>
+<ol>
+  <li><a href="#RequiredFiles">Required Files</a></li>
+  <li>Add the <a href="#FspBinary">FSP Binary File</a> to the coreboot File System</li>
+  <li>Enable <a href="#corebootFspDebugging">coreboot/FSP Debugging</a></li>
+</ol>
+
+<p>
+  FSP Documentation:
+</p>
+<ul>
+  <li>Intel&reg; Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec-v1-1.pdf">V1.1</a></li>
+</ul>
+
+<hr>
+<h2><a name="RequiredFiles">Required Files</a></h2>
+<h3><a name="corebootRequiredFiles">coreboot Required Files</a></h3>
+<ol>
+  <li>Create the following directories if they do not already exist:
+    <ul>
+      <li>src/vendorcode/intel/fsp/fsp1_1/&lt;Chip Family&gt;</li>
+      <li>3rdparty/blobs/mainboard/&lt;Board Vendor&gt;/&lt;Board Name&gt;</li>
+    </ul>
+  </li>
+  <li>
+    The following files may need to be copied from the FSP build or release into the
+    directories above if they are not present or are out of date:
+    <ul>
+      <li>FspUpdVpd.h: src/vendorcode/intel/fsp/fsp1_1/&lt;Chip Family&gt;/FspUpdVpd.h</li>
+      <li>FSP.bin: 3rdparty/blobs/mainboard/&lt;Board Vendor&gt;/&lt;Board Name&gt;/fsp.bin</li>
+    </ul>
+  </li>
+</ol>
+
+
+<hr>
+<h2><a name="FspBinary">Add the FSP Binary File to coreboot File System</a></h2>
+<p>
+  Add the FSP binary to the coreboot flash image using the following command:
+</p>
+<pre><code>util/cbfstool/cbfstool build/coreboot.rom add -t fsp -n fsp.bin -b &lt;base address&gt; -f fsp.bin</code></pre>
+<p>
+  This command relocates the FSP binary to the 4K byte aligned location in CBFS so that the
+  FSP code for TempRamInit may be executed in place.
+</p>
+
+
+<hr>
+<h2><a name="corebootFspDebugging">Enable coreboot/FSP Debugging</a></h2>
+<p>
+  Set the following Kconfig values:
+</p>
+<ul>
+  <li>CONFIG_DISPLAY_FSP_ENTRY_POINTS - Display the FSP entry points in romstage</li>
+  <li>CONFIG_DISPLAY_HOBS - Display and verify the hand-off-blocks (HOBs) returned by MemoryInit</li>
+  <li>CONFIG_DISPLAY_VBT - Display Video BIOS Table (VBT) used for GOP</li>
+  <li>CONFIG_DISPLAY_UPD_DATA - Display the user specified product data passed to MemoryInit and SiliconInit</li>
+</ul>
+
+
+<hr>
+<p>Modified: 17 May 2016</p>
+  </body>
+</html>

firmware/coreboot/Documentation/Intel/index.html

@@ -0,0 +1,129 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Intel&reg; x86</title>
+  </head>
+  <body>
+
+<h1>Intel&reg; x86</h1>
+
+<h2>Intel&reg; x86 Boards</h2>
+<ul>
+  <li><a target="_blank" href="Board/galileo.html">Galileo</a></li>
+  <li><a target="_blank" href="http://wiki.minnowboard.org/Coreboot">MinnowBoard MAX</a></li>
+</ul>
+
+<h2>Intel&reg; x86 SoCs</h2>
+<ul>
+  <li><a target="_blank" href="SoC/quark.html">Quark&trade;</a></li>
+</ul>
+
+
+
+<hr>
+<h2>x86 coreboot Development</h2>
+<ul>
+  <li>Get the <a target="_blank" href="https://www.coreboot.org/Git">coreboot source</li>
+  <li><a target="_blank" href="development.html">Overall</a> development</li>
+  <li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration
+  </li>
+  <li><a target="_blank" href="SoC/soc.html">SoC</a> support</li>
+  <li><a target="_blank" href="Board/board.html">Board</a> support</li>
+  <li><a target="_blank" href="vboot.html">Verified Boot (vboot)</a> support</li>
+</ul>
+
+
+
+<hr>
+<h2>Payload Development</h2>
+<ul>
+  <li><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>
+    <ul>
+      <li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process">EDK II Development Process</a></li>
+      <li>EDK II <a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/EDK%20II%20White%20papers">White Papers</a></li>
+      <li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/SourceForge-to-Github-Quick-Start">SourceForge to Github Quick Start</a></li>
+      <li>UEFI <a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI%20Spec%202_5_Errata_A.PDF">2.5 Errata A</a></li>
+    </ul>
+  </li>
+</ul>
+
+
+
+<hr>
+<h2><a name="Documentation">Documentation</a></h2>
+<ul>
+  <li>Intel&reg; 64 and IA-32 Architectures <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-manual-325462.pdf">Software Developer Manual</a></li>
+  <li><a target="_blank" href="http://www.uefi.org/specifications">UEFI Specifications</a></li>
+</ul>
+
+<h3><a name="Edk2Documentation">EDK-II Documentation</a></h3>
+<ul>
+  <li>Build <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/Build_Spec_1_26.pdf">V1.26</a></li>
+  <li>Coding Standards <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/CCS_2_1_Draft.pdf">V2.1</a></li>
+  <li>DEC <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/DEC_Spec_1_25.pdf">V1.25</a></li>
+  <li>DSC <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/DSC_Spec_1_26.pdf">V1.26</a></li>
+  <li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/UEFI-Driver-Writer's-Guide">Driver Writer's Guide</a></li>
+  <li>Expression Syntax <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/ExpressionSyntax_1.1.pdf">V1.1</a></li>
+  <li>FDF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/FDF_Spec_1_26.pdf">V1.26</a></li>
+  <li>INF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/INF_Spec_1_25.pdf">V1.25</a></li>
+  <li>PCD <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/PCD_Infrastructure.pdf">PCD</a>V0.55</li>
+  <li>UNI <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/UNI_File_Spec_v1_2_Errata_A.pdf">V1.2 Errata A</a></li>
+  <li>VRF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/VFR_1_9.pdf">V1.9</a></li>
+</ul>
+
+<h3><a name="FspDocumentation">FSP Documentation</a></h3>
+<ul>
+  <li>Intel&reg; Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec-v2.pdf">V2.0</a></li>
+  <li>Intel&reg; Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec-v1-1.pdf">V1.1</a></li>
+  <li>Intel&reg; Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec.pdf">V1.0</a></li>
+</ul>
+
+<h3><a name="FeatureDocumentation">Feature Documentation</a></h3>
+<table border="1">
+  <tr bgcolor="#c0ffc0"><th>Feature/Specification</th><th>Linux View/Test</th><th>EDK-II View/Test</th></tr>
+  <tr>
+    <td><a target="_blank" href="https://en.wikipedia.org/wiki/E820">e820</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/dmesg.1.html">dmesg</a></td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="http://www.uefi.org/specifications">ACPI</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/precise/man1/acpidump.1.html">acpidump</a></td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="https://en.wikipedia.org/wiki/Extended_Display_Identification_Data">EDID</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/get-edid.1.html">get-edid | parse-edid</a></td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I2C</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/get-edid.1.html">i2cdetect</a></td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="http://www.intel.com/design/archives/processors/pro/docs/242016.htm">Multiprocessor</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/lscpu.1.html">lscpu</a></td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="https://pcisig.com/specifications">PCI</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man8/lspci.8.html">lspci</a></td>
+    <td><a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf">pci</a></td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="https://www.dmtf.org/sites/default/files/standards/documents/DSP0134_3.0.0.pdf">SMBIOS</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man8/dmidecode.8.html">dmidecode</a></td>
+    <td><a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf">smbiosview</a></td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="http://www.usb.org/developers/docs/">USB</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/xenial/man8/lsusb.8.html">lsusb</a></td>
+    <td>&nbsp;</td>
+  </tr>
+</table>
+
+<hr>
+<p>Modified: 18 June 2016</p>
+  </body>
+</html>

firmware/coreboot/Documentation/Intel/vboot.html

@@ -0,0 +1,402 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>vboot - Verified Boot Support</title>
+  </head>
+  <body>
+
+<h1>vboot - Verified Boot Support</h1>
+
+<p>
+Google's verified boot support consists of:
+</p>
+<ul>
+  <li>A root of trust</li>
+  <li>Special firmware layout</li>
+  <li>Firmware verification</li>
+  <li>Firmware measurements</li>
+  <li>A firmware update mechanism</li>
+  <li>Specific build flags</li>
+  <li>Signing the coreboot image</li>
+</ul>
+
+Google's vboot verifies the firmware and places measurements
+within the TPM.
+
+<hr>
+<h2>Root of Trust</h2>
+<p>
+When using vboot, the root-of-trust is basically the read-only portion of the
+SPI flash.  The following items factor into the trust equation:
+</p>
+<ul>
+  <li>The GCC compiler must reliably translate the code into machine code
+      without inserting any additional code (virus, backdoor, etc.)
+  </li>
+  <li>The CPU must reliably execute the reset sequence and instructions as
+      documented by the CPU manufacturer.
+  </li>
+  <li>The SPI flash must provide only the code programmed into it to the CPU
+      without providing any alternative reset vector or code sequence.
+  </li>
+  <li>The SPI flash must honor the write-protect input and protect the
+      specified portion of the SPI flash from all erase and write accesses.
+  </li>
+</ul>
+
+<p>
+The firmware is typically protected using the write-protect pin on the SPI
+flash part and setting some of the write-protect bits in the status register
+during manufacturing.  The protected area is platform specific and for x86
+platforms is typically 1/4th of the SPI flash
+part size.  Because this portion of the SPI flash is hardware write protected,
+it is not possible to update this portion of the SPI flash in the field,
+without altering the system to eliminate the ground connection to the SPI flash
+write-protect pin.  Without hardware modifications, this portion of the SPI
+flash maintains the manufactured state during the system's lifetime.
+</p>
+
+<hr>
+<h2>Firmware Layout</h2>
+<p>
+Several sections are added to the firmware layout to support vboot:
+</p>
+<ul>
+  <li>Read-only section</li>
+  <li>Google Binary Blob (GBB) area</li>
+  <li>Read/write section A</li>
+  <li>Read/write section B</li>
+</ul>
+<p>
+The following sections describe the various portions of the flash layout.
+</p>
+
+<h3>Read-Only Section</h3>
+<p>
+The read-only section contains a coreboot file system (CBFS) that contains all
+of the boot firmware necessary to perform recovery for the system. This
+firmware is typically protected using the write-protect pin on the SPI flash
+part and setting some of the write-protect bits in the status register during
+manufacturing.  The protected area is typically 1/4th of the SPI flash part
+size and must cover the entire read-only section which consists of:
+</p>
+<ul>
+  <li>Vital Product Data (VPD) area</li>
+  <li>Firmware ID area</li>
+  <li>Google Binary Blob (GBB) area</li>
+  <li>coreboot file system containing read-only recovery firmware</li>
+</ul>
+
+<h3>Google Binary Blob (GBB) Area</h3>
+<p>
+The GBB area is part of the read-only section.  This area contains a 4096 or
+8192 bit public root RSA key that is used to verify the VBLOCK area to obtain
+the firmware signing key.
+</p>
+
+<h3>Recovery Firmware</h3>
+<p>
+The recovery firmware is contained within a coreboot file system and consists
+of:
+</p>
+<ul>
+  <li>reset vector</li>
+  <li>bootblock</li>
+  <li>verstage</li>
+  <li>romstage</li>
+  <li>postcar</li>
+  <li>ramstage</li>
+  <li>payload</li>
+  <li>flash map file</li>
+  <li>config file</li>
+  <li>processor specific files:
+    <ul>
+      <li>Microcode</li>
+      <li>fspm.bin</li>
+      <li>fsps.bin</li>
+    </ul>
+  </li>
+</ul>
+
+<p>
+The recovery firmware is written during manufacturing and typically contains
+code to write the storage device (eMMC device or hard disk).  The recovery
+image is usually contained on a socketed device such as a USB flash drive or
+an SD card.  Depending upon the payload firmware doing the recovery, it may
+be possible for the user to interact with the system to specify the recovery
+image path.  Part of the recovery is also to write the A and B areas of the
+SPI flash device to boot the system.
+</p>
+
+
+<h3>Read/Write Section</h3>
+
+<p>
+The read/write sections contain an area which contains the firmware signing
+key and signature and an area containing a coreboot file system with a subset
+of the firmware.  The firmware files in FW_MAIN_A and FW_MAIN_B are:
+</p>
+<ul>
+  <li>romstage</li>
+  <li>postcar</li>
+  <li>ramstage</li>
+  <li>payload</li>
+  <li>config file</li>
+  <li>processor specific files:
+    <ul>
+      <li>Microcode</li>
+      <li>fspm.bin</li>
+      <li>fsps.bin</li>
+    </ul>
+  </li>
+</ul>
+
+<p>
+The firmware subset enables most issues to be fixed in the field with firmware
+updates.  The firmware files handle memory and most of silicon initialization.
+These files also produce the tables which get passed to the operating system.
+</p>
+
+<hr>
+<h2>Firmware Updates</h2>
+<p>
+The read/write sections exist in one of three states:
+</p>
+<ul>
+  <li>Invalid</li>
+  <li>Ready to boot</li>
+  <li>Successfully booted</li>
+</ul>
+
+<table border="1">
+<tr bgcolor="#ffc0c0">
+<td>
+Where is this state information written?
+<br/>CMOS?
+<br/>RW_NVRAM?
+<br/>RW_FWID_*
+</td>
+</tr>
+</table>
+
+<p>
+Firmware updates are handled by the operating system by writing any read/write
+section that is not in the "successfully booted" state.  Upon the next reboot,
+vboot determines the section to boot.  If it finds one in the "ready to boot"
+state then it attempts to boot using that section.  If the boot fails then
+vboot marks the section as invalid and attempts to fall back to a read/write
+section in the "successfully booted" state.  If vboot is not able to find a
+section in the "successfully booted" state then vboot enters recovery mode.
+</p>
+
+<p>
+Only the operating system is able to transition a section from the "ready to
+boot" state to the "successfully booted" state.  The transition is typically
+done after the operating system has been running for a while indicating
+that successful boot was possible and the operating system is stable.
+</p>
+
+<p>
+Note that as long as the SPI write protection is in place then the system is
+always recoverable.  If the flash update fails then the system will continue
+to boot using the previous read/write area.  The same is true if coreboot
+passes control to the payload or the operating system and then the boot fails.
+In the worst case, the SPI flash gets totally corrupted in which case vboot
+fails the signature checks and enters recovery mode.  There are no times where
+the SPI flash is exposed and the reset vector or part of the recovery firmware
+gets corrupted.
+</p>
+
+<hr>
+<h2>Build Flags</h2>
+<p>
+The following Kconfig values need to be selected to enable vboot:
+</p>
+<ul>
+  <li>COLLECT_TIMESTAMPS</li>
+  <li>VBOOT</li>
+</ul>
+
+<p>
+The starting stage needs to be specified by selecting either
+VBOOT_STARTS_IN_BOOTBLOCK or VBOOT_STARTS_IN_ROMSTAGE.
+</p>
+
+<p>
+If vboot starts in bootblock then vboot may be built as a separate stage by
+selecting VBOOT_SEPARATE_VERSTAGE.  Additionally, if static RAM is too small
+to fit both verstage and romstage then selecting VBOOT_RETURN_FROM_VERSTAGE
+enables bootblock to reuse the RAM occupied by verstage for romstage.
+</p>
+
+<p>
+Non-volatile flash is needed for vboot operation.  This flash area may be in
+CMOS, the EC, or in a read/write area of the SPI flash device.  Select one of
+the following:
+</p>
+<ul>
+  <li>VBOOT_VBNV_CMOS</li>
+  <li>VBOOT_VBNV_EC</li>
+  <li>VBOOT_VBNV_FLASH</li>
+</ul>
+<p>
+More non-volatile storage features may be found in src/vboot/Kconfig.
+</p>
+
+<p>
+A TPM is also required for vboot operation.  TPMs are available in
+drivers/i2c/tpm and drivers/pc80/tpm.
+</p>
+
+<p>
+In addition to adding the coreboot files into the read-only region, enabling
+vboot causes the build script to add the read/write files into coreboot file
+systems in FW_MAIN_A and FW_MAIN_B.
+</p>
+
+<hr>
+<h2>Signing the coreboot Image</h2>
+<p>
+The following command script is an example of how to sign the coreboot image file.
+This script is used on the Intel Galileo board and creates the GBB area and
+inserts it into the coreboot image.  It also updates the VBLOCK areas with the
+firmware signing key and the signature for the FW_MAIN firmware.  More details
+are available in 3rdparty/vboot/README.
+</p>
+
+<pre><code>#!/bin/sh
+#
+#  The necessary tools were built and installed using the following commands:
+#
+#        pushd 3rdparty/vboot
+#        make
+#        sudo make install
+#        popd
+#
+#  The keys were made using the following command
+#
+#        3rdparty/vboot/scripts/keygeneration/create_new_keys.sh  \
+#                --4k --4k-root --output $PWD/keys
+#
+#
+#  The "magic" numbers below are derived from the GBB section in
+#  src/mainboard/intel/galileo/vboot.fmd.
+#
+#  GBB Header Size:     0x80
+#  GBB Offset:      0x611000, 4KiB block number: 1553 (0x611)
+#  GBB Length:       0x7f000, 4KiB blocks:        127  (0x7f)
+#  COREBOOT Offset: 0x690000, 4KiB block number: 1680 (0x690)
+#  COREBOOT Length: 0x170000, 4KiB blocks:        368 (0x170)
+#
+#  0x7f000 (GBB Length) = 0x80 + 0x100 + 0x1000 + 0x7ce80 + 0x1000
+#
+#  Create the GBB area blob
+#  Parameters: hwid_size,rootkey_size,bmpfv_size,recoverykey_size
+#
+gbb_utility -c 0x100,0x1000,0x7ce80,0x1000 gbb.blob
+
+#
+#  Copy from the start of the flash to the GBB region into the signed flash
+#  image.
+#
+#  1553 * 4096 = 0x611 * 0x1000 = 0x611000, size of area before GBB
+#
+dd  conv=fdatasync  ibs=4096  obs=4096  count=1553  \
+    if=build/coreboot.rom  of=build/coreboot.signed.rom
+
+#
+#  Append the empty GBB area to the coreboot.rom image.
+#
+#  1553 * 4096 = 0x611 * 0x1000 = 0x611000, offset to GBB
+#
+dd  conv=fdatasync  obs=4096  obs=4096  seek=1553  if=gbb.blob  \
+    of=build/coreboot.signed.rom
+
+#
+#  Append the rest of the read-only region into the signed flash image.
+#
+#  1680 * 4096 = 0x690 * 0x1000 = 0x690000, offset to COREBOOT area
+#   368 * 4096 = 0x170 * 0x1000 = 0x170000, length of COREBOOT area
+#
+dd  conv=fdatasync  ibs=4096  obs=4096  skip=1680  seek=1680  count=368  \
+    if=build/coreboot.rom  of=build/coreboot.signed.rom
+
+#
+#  Insert the HWID and public root and recovery RSA keys into the GBB area.
+#
+gbb_utility                          \
+   --set --hwid='Galileo'            \
+   -r $PWD/keys/recovery_key.vbpubk  \
+   -k $PWD/keys/root_key.vbpubk      \
+   build/coreboot.signed.rom
+
+#
+#  Sign the read/write firmware areas with the private signing key and update
+#  the VBLOCK_A and VBLOCK_B regions.
+#
+3rdparty/vboot/scripts/image_signing/sign_firmware.sh  \
+   build/coreboot.signed.rom                           \
+   $PWD/keys                                           \
+   build/coreboot.signed.rom
+</code></pre>
+
+<hr>
+<h2>Boot Flow</h2>
+<p>
+The reset vector exist in the read-only area and points to the bootblock entry
+point.  The only copy of the bootblock exists in the read-only area of the SPI
+flash.  Verstage may be part of the bootblock or a separate stage.  If separate
+then the bootblock loads verstage from the read-only area and transfers control
+to it.
+</p>
+
+<p>
+Upon first boot, verstage attempts to verify the read/write section A.  It gets
+the public root key from the GBB area and uses that to verify the VBLOCK area
+in read-write section A.  If the VBLOCK area is valid then it extracts the
+firmware signing key (1024-8192 bits) and uses that to verify the FW_MAIN_A
+area of read/write section A.  If the verification is successful then verstage
+instructs coreboot to use the coreboot file system in read/write section A for
+the contents of the remaining boot firmware (romstage, postcar, ramstage and
+the payload).
+</p>
+
+<p>
+If verification fails for the read/write area and the other read/write area is
+not valid vboot falls back to the read-only area to boot into system recovery.
+</p>
+
+<hr>
+<h2>Chromebook Special Features</h2>
+<p>
+Google's Chromebooks have some special features:
+</p>
+<ul>
+  <li>Developer mode</li>
+  <li>Write-protect screw</li>
+</ul>
+
+<h3>Developer Mode</h3>
+<p>
+Developer mode allows the user to use coreboot to boot another operating system.
+This may be a another (beta) version of Chrome OS, or another flavor of
+GNU/Linux.  Use of developer mode does not void the system warranty.  Upon
+entry into developer mode, all locally saved data on the system is lost.
+This prevents someone from entering developer mode to subvert the system
+security to access files on the local system or cloud.
+</p>
+
+<h3>Write Protect Screw</h3>
+<p>
+Chromebooks have a write-protect screw which provides the ground to the
+write-protect pin of the SPI flash.  Google specifically did this to allow
+the manufacturing line and advanced developers to re-write the entire SPI flash
+part.  Once the screw is removed, any firmware may be placed on the device.
+However, accessing this screw requires opening the case and voids the system
+warranty!
+</p>
+
+<hr>
+<p>Modified: 2 May 2017</p>
+  </body>
+</html>

firmware/coreboot/Documentation/Kconfig.tex

@@ -0,0 +1,480 @@
+\documentclass[10pt,letterpaper]{article}
+\usepackage[latin1]{inputenc}
+\usepackage{amsmath}
+\usepackage{amsfonts}
+\usepackage{amssymb}
+\author{Ron Minnich}
+\title{Kconfig usage in coreboot v2}
+\begin{document}
+\section{Introduction}
+This document describes how to use Kconfig in v2. We describe our usage of Kconfig files, Makefile.inc files, when and where to use them, how to use them, and, interestingly, when and where not to use them.
+\section{Kconfig variations}
+Most Kconfig files set variables, which can be set as part of the Kconfig dialog. Not all Kconfig variables are set by the user, however; some are too dangerous. These are merely enabled by the mainboard.
+
+For variables set by the user, see src/console/Kconfig.
+
+For variables not set by the user, see src/mainboard/amd/serengeti\_cheetah/Kconfig. Users should never set such variables as the cache as RAM base. These are highly mainboard dependent.
+
+Kconfig files use the source command to include subdirectories. In most cases, save for limited cases described below, subdirectories have Kconfig files. They are always sourced unconditionally.
+
+\section{Makefile and Makefile.inc}
+There is only one Makefile, at the top level. All other makefiles are included as Makefile.inc. All the next-level Makefile.inc files are selected in the top level Makefile. Directories that are platform-independent are in BUILD-y; platform-dependent (e.g. Makefile.inc's that depend on architecture) are included in PLATFORM-y.
+
+Make is not recursive. There is only one make process.
+\subsection{subdirs usage}
+Further includes of Makefile.inc, if needed, are done via subdirs-y commands. As in Linux, the subdirs can be conditional or unconditional. Conditional includes are done via subdirs-\$(CONFIG\_VARIABLE) usage; unconditional are done via subdirs-y.
+
+We define the common rules for which variation to use below.
+\subsection{object file specification}
+There are several different types of objects specified in the tree. They are:
+\begin{description}
+\item[obj]objects for the RAM part of the code
+\item[driver]drivers for the RAM part. Drivers are not represented in the device tree but do have a driver struct attached in the driver section.
+\item[initobj]seperately-compiled code for the ROM section of coreboot
+\end{description}
+These items are specified via the -y syntax as well. Conditional object inclusion is done via the -\$(CONFIG\_VARIABLE) syntax.
+
+\section{Example: AMD serengeti cheetah}
+\subsection{mainboard/Kconfig}
+Defines Vendor variables. Currently defined variables are:
+Sources all Kconfig files in the vendor directories.
+\input{ mainboardkconfig.tex}
+\subsection{mainboard/Makefile.inc}
+There is none at this time.
+\subsection{mainboard/$<$vendor$>$/Kconfig}
+We use the amd as a model. The only action currently taken is to source all Kconfig's in the
+subdirectories.
+\subsection{mainboard/$<$vendor$>$/Makefile.inc}
+We use amd as a model. There is currently no Makefile.inc at this level.
+\subsection{mainboard/$<$vendor$>$/$<$board$>$/Kconfig}
+The mainboard Kconfig and Makefile.inc are designed to be the heart of the build. The defines
+and rules in here determine everything about how a mainboard target is built.
+We will use serengeti\_cheetah as a model. It defines these variables.
+\input{ mainboardkconfig.tex}
+\subsection{mainboard/$<$vendor$>$/$<$board$>$/Makefile.inc}
+This is a fairly complex Makefile.inc. Because this is such a critical component, we are going to excerpt and take it piece by piece.
+Note that this is the mainboard as of August, 2009, and it may change over time.
+\subsubsection{objects}
+We define objects in the first part. The mainbard itself is a driver and included unconditionally. Other objects are conditional:
+\begin{verbatim}
+driver-y +=  mainboard.o
+
+#needed by irq_tables and mptable and acpi_tables
+obj-y += get_bus_conf.o
+obj-$(CONFIG_HAVE_MP_TABLE) += mptable.o
+obj-$(CONFIG_HAVE_PIRQ_TABLE) += irq_tables.o
+obj-$(CONFIG_HAVE_ACPI_TABLES) +=  dsdt.o
+obj-$(CONFIG_HAVE_ACPI_TABLES) +=  acpi_tables.o
+obj-$(CONFIG_HAVE_ACPI_TABLES) +=  fadt.o
+
+#./ssdt.o is in northbridge/amd/amdk8/Config.lb
+obj-$(CONFIG_ACPI_SSDTX_NUM) +=  ssdt2.o
+obj-$(CONFIG_ACPI_SSDTX_NUM) +=  ssdt3.o
+obj-$(CONFIG_HAVE_ACPI_TABLES) +=  ssdt4.o
+driver-y += ../../../drivers/i2c/i2cmux/i2cmux.o
+
+# This is part of the conversion to init-obj and away from included code.
+
+initobj-y += crt0.o
+\end{verbatim}
+\subsubsection{romcc legacy support}
+We hope to move away from romcc soon, but for now, if one is using romcc, the Makefile.inc must define
+crt0 include files (assembly code for startup, usually); and several ldscripts. These are taken directly from the
+old Config.lb. Note that these use the -y syntax and can use the ability to be included conditionally.
+\begin{verbatim}
+crt0-y += ../../../../src/cpu/x86/16bit/entry16.inc
+crt0-y += ../../../../src/cpu/x86/32bit/entry32.inc
+crt0-y += ../../../../src/cpu/x86/16bit/reset16.inc
+crt0-y += ../../../../src/arch/i386/lib/id.inc
+crt0-y += ../../../../src/cpu/amd/car/cache_as_ram.inc
+crt0-y += auto.inc
+
+ldscript-y += ../../../../src/arch/i386/init/ldscript_fallback_cbfs.lb
+ldscript-y += ../../../../src/cpu/x86/16bit/entry16.lds
+ldscript-y += ../../../../src/cpu/x86/16bit/reset16.lds
+ldscript-y += ../../../../src/arch/i386/lib/id.lds
+ldscript-y += ../../../../src/arch/i386/lib/failover.lds
+
+\end{verbatim}
+\subsubsection{POST\_EVALUATION}
+POST\_EVALUATION rules should be placed after this section:
+\begin{verbatim}
+ifdef POST_EVALUATION
+\end{verbatim}
+to ensure that the values of variables are correct.
+Here are the post-evaluation rules for this mainboard:
+\begin{verbatim}
+$(obj)/dsdt.c: $(src)/mainboard/$(MAINBOARDDIR)/dsdt.asl
+  iasl -p dsdt -tc $(src)/mainboard/$(MAINBOARDDIR)/dsdt.asl
+  mv dsdt.hex $@
+
+$(obj)/mainboard/$(MAINBOARDDIR)/dsdt.o: $(obj)/dsdt.c
+  $(CC) $(DISTRO_CFLAGS) $(CFLAGS) $(CPPFLAGS) $(DEBUG_CFLAGS) -I$(src) -I. -c $< -o $@
+
+$(obj)/ssdt2.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci2.asl
+  iasl -p $(CURDIR)/pci2 -tc $(CONFIG_MAINBOARD)/dx/pci2.asl
+  perl -pi -e 's/AmlCode/AmlCode_ssdt2/g' pci2.hex
+  mv pci2.hex ssdt2.c
+
+$(obj)/ssdt3.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci3.asl"
+  iasl -p $(CURDIR)/pci3 -tc $(CONFIG_MAINBOARD)/
+  perl -pi -e 's/AmlCode/AmlCode_ssdt3/g' pci3.hex
+  mv pci3.hex ssdt3.c
+
+$(obj)/ssdt4.c: $(src)/mainboard/$(MAINBOARDDIR)/dx/pci4.asl"
+  iasl -p $(CURDIR)/pci4 -tc $(CONFIG_MAINBOARD)/dx/pci4.asl
+  perl -pi -e 's/AmlCode/AmlCode_ssdt4/g' pci4.hex
+  mv pci4.hex ssdt4.c
+
+$(obj)/mainboard/$(MAINBOARDDIR)/auto.inc: $(src)/mainboard/$(MAINBOARDDIR)/rom.c $(obj)/option_table.h
+  $(CC) $(DISTRO_CFLAGS) $(CFLAGS) $(CPPFLAGS) $(DEBUG_CFLAGS) -I$(src) -I. -c -S  $(src)/mainboard/$(MAINBOARDDIR)/rom.c -o $@
+  perl -e 's/\.rodata/.rom.data/g' -pi $@
+  perl -e 's/\.text/.section .rom.text/g' -pi $@
+
+\end{verbatim}
+The last rule is for romcc, and, again, we hope to eliminate romcc usage and this rule soon. The first set of rules concern ACPI tables.
+\subsubsection{devicetree.cb}
+Most of the old Config.lb is gone, but one piece remains: the device tree specification. This tree is still required to build a mainboard
+properly, as it defines topology and chips that can be defined no other way.
+Let's go through the tree.
+\begin{verbatim}
+chip northbridge/amd/amdk8/root_complex
+  device cpu_cluster 0 on
+    chip cpu/amd/socket_F
+      device lapic 0 on end
+    end
+  end
+\end{verbatim}
+This topology is always somewhat confusing to newcomers, and even to coreboot veterans.
+
+We root the tree at the pci-e {\it root complex}. There is always the question of how and where to root the tree. Over the years we
+have found that the one part that never goes away is the root complex. CPU sockets may be empty or full; but there is always a northbridge
+somewhere, since it runs memory.
+
+
+What is the APIC? Northbridges always have an Advanced Programmable Interrupt Controller, and that {\it APIC cluster} is a topological connection to the
+CPU socket. So the tree is rooted at the northbridge, which has a link to a CPU cluster, and then the CPU. The CPU contains
+its own APIC, and will define any parameters needed. In this case, we have a northbridge of type
+{\it northbridge/amd/amdk8/root\_complex}, with its own cpu\_cluster device which we turn on,
+which connects to a {\it cpu/amd/socket\_F},
+which has a local apic, which is on.
+
+Note that we do not enumerate all CPUs, even on this SMP mainboard. The reason is they may not all be there. The CPU we define here
+is the so-called Boot Strap Processor, or BSP; the other CPUs will come along later, as the are discovered. We do not require (unlike many
+BIOSes) that the BSP be CPU 0; any CPU will do.
+\begin{verbatim}
+  device domain 0 on
+    chip northbridge/amd/amdk8
+      device pci 18.0 on #  northbridge
+        #  devices on link 0, link 0 == LDT 0
+\end{verbatim}
+Here begins the pci domain, which usually starts with 0. Then there is the northbridge, which bridges to the PCI bus. On
+Opterons, certain CPU control registers are managed in PCI config space in device 18.0 (BSP), 19.0 (AP), and up.
+\begin{verbatim}
+        chip southbridge/amd/amd8132
+          # the on/off keyword is mandatory
+          device pci 0.0 on end
+          device pci 0.1 on end
+          device pci 1.0 on end
+          device pci 1.1 on end
+        end
+\end{verbatim}
+This is the 8132, a bridge to a secondary PCI bus.
+\begin{verbatim}
+        chip southbridge/amd/amd8111
+          # this "device pci 0.0" is the parent the next one
+          # PCI bridge
+          device pci 0.0 on
+            device pci 0.0 on end
+            device pci 0.1 on end
+            device pci 0.2 off end
+            device pci 1.0 off end
+          end
+\end{verbatim}
+The 8111 is a bridge to other busses and to the legacy ISA devices such as superio.
+\begin{verbatim}
+          device pci 1.0 on
+            chip superio/winbond/w83627hf
+              device pnp 2e.0 off #  Floppy
+                 io 0x60 = 0x3f0
+                irq 0x70 = 6
+                drq 0x74 = 2
+              end
+              device pnp 2e.1 off #  Parallel Port
+                 io 0x60 = 0x378
+                irq 0x70 = 7
+              end
+              device pnp 2e.2 on #  Com1
+                 io 0x60 = 0x3f8
+                irq 0x70 = 4
+              end
+              device pnp 2e.3 off #  Com2
+                 io 0x60 = 0x2f8
+                irq 0x70 = 3
+              end
+              device pnp 2e.5 on #  Keyboard
+                 io 0x60 = 0x60
+                 io 0x62 = 0x64
+                irq 0x70 = 1
+                irq 0x72 = 12
+              end
+              device pnp 2e.6 off #  CIR
+                io 0x60 = 0x100
+              end
+              device pnp 2e.7 off #  GAME_MIDI_GIPO1
+                io 0x60 = 0x220
+                io 0x62 = 0x300
+                irq 0x70 = 9
+              end
+              device pnp 2e.8 off end #  GPIO2
+              device pnp 2e.9 off end #  GPIO3
+              device pnp 2e.a off end #  ACPI
+              device pnp 2e.b on #  HW Monitor
+                  io 0x60 = 0x290
+                irq 0x70 = 5
+              end
+            end
+          end
+\end{verbatim}
+The pnp refers to the many Plug N Play devices on a superio. 2e refers to the base I/O address of the superio, and the number following the
+2e (i.e. 2e.1) is the Logical Device Number, or LDN. Each LDN has a common configuration (base, irq, etc.) and these are set by the statements under the LDN.
+\begin{verbatim}
+          device pci 1.1 on end
+          device pci 1.2 on end
+\end{verbatim}
+More devices. These statements set up placeholders in the device tree.
+\begin{verbatim}
+          device pci 1.3 on
+            chip drivers/i2c/i2cmux # pca9556 smbus mux
+              device i2c 18 on #0 pca9516 1
+                chip drivers/generic/generic #dimm 0-0-0
+                  device i2c 50 on end
+                end
+                chip drivers/generic/generic #dimm 0-0-1
+                  device i2c 51 on end
+                end
+                chip drivers/generic/generic #dimm 0-1-0
+                  device i2c 52 on end
+                end
+                chip drivers/generic/generic #dimm 0-1-1
+                  device i2c 53 on end
+                end
+              end
+              device i2c 18 on #1 pca9516 2
+                chip drivers/generic/generic #dimm 1-0-0
+                  device i2c 50 on end
+                end
+                chip drivers/generic/generic #dimm 1-0-1
+                  device i2c 51 on end
+                end
+                chip drivers/generic/generic #dimm 1-1-0
+                  device i2c 52 on end
+                end
+                chip drivers/generic/generic #dimm 1-1-1
+                  device i2c 53 on end
+                end
+                chip drivers/generic/generic #dimm 1-2-0
+                  device i2c 54 on end
+                end
+                chip drivers/generic/generic #dimm 1-2-1
+                  device i2c 55 on end
+                end
+                chip drivers/generic/generic #dimm 1-3-0
+                  device i2c 56 on end
+                end
+                chip drivers/generic/generic #dimm 1-3-1
+                  device i2c 57 on end
+                end
+              end
+            end
+          end # acpi
+\end{verbatim}
+These are the i2c devices.
+\begin{verbatim}
+          device pci 1.5 off end
+          device pci 1.6 off end
+\end{verbatim}
+More placeholders.
+\begin{verbatim}
+               register "ide0_enable" = "1"
+          register "ide1_enable" = "1"
+        end
+      end #  device pci 18.0
+
+\end{verbatim}
+These "register" commands set controls in the southbridge.
+\begin{verbatim}
+           device pci 18.0 on end
+      device pci 18.0 on end
+\end{verbatim}
+These are the other two hypertransport links.
+\begin{verbatim}
+      device pci 18.1 on end
+      device pci 18.2 on end
+      device pci 18.3 on end
+\end{verbatim}
+The 18.1 devices are, again, northbridge control for various k8 functions.
+\begin{verbatim}
+    end
+  \end{verbatim}
+That's it for the BSP I/O and HT busses. Now we begin the AP busses. Not much here.
+\begin{verbatim}
+        chip northbridge/amd/amdk8
+      device pci 19.0 on #  northbridge
+        chip southbridge/amd/amd8151
+          # the on/off keyword is mandatory
+          device pci 0.0 on end
+          device pci 1.0 on end
+        end
+      end #  device pci 19.0
+
+      device pci 19.0 on end
+      device pci 19.0 on end
+      device pci 19.1 on end
+      device pci 19.2 on end
+      device pci 19.3 on end
+    end
+
+
+\end{verbatim}
+
+\subsection{cpu socket}
+The CPU socket is the key link from mainboard to its CPUs. Since many models of CPU can go in a socket, the mainboard mentions only
+the socket, and the socket, in turn, references the various model CPUs which can be plugged into it. The socket is thus the focus
+of all defines and Makefile controls for building the CPU components of a board.
+
+\subsubsection{ cpu/Kconfig}
+Defines variables. Current variables are:
+\input{cpukconfig.tex}
+Sources all Kconfig files in the vendor directories.
+\subsubsection{ cpu/Makefile.inc}
+Unconditionally sources all Makefile.inc in the vendor directories.
+
+\subsection{cpu/$<$vendor$>$/Kconfig}
+The only action currently taken is to source all Kconfig's in the
+subdirectories.
+\subsection{cpu/$<$vendor$>$/Makefile.inc}
+{\em Conditionally} source the socket directories.
+Example:
+\begin{verbatim}
+subdirs-$(CONFIG_CPU_AMD_SOCKET_F) += socket_F
+\end{verbatim}
+.
+CONFIG\_CPU\_AMD\_SOCKET\_F is set in a mainboard file.
+
+\subsection{cpu/$<$vendor$>$/$<$socket$>$/Kconfig}
+Set variables that relate to this {\em socket}, and {\em any models that plug into this socket}. Note that
+the socket, as much as possible, should control the models, because the models may plug into many sockets.
+Socket\_F currently sets:
+\input{socketfkconfig.tex}
+
+It sources only those Kconfigs that relate to this particular socket, i.e. not all possible models are sourced.
+
+\subsection{cpu/$<$vendor$>$/$<$model$>$/Kconfig}
+CPU Model Kconfigs only set variables, We do not expect that they will source any other Kconfig. The socket Kconfig should do that
+if needed.
+\subsection{cpu/$<$vendor$>$/$<$model$>$/Makefile.inc}
+The Makefile.inc {\em unconditionally} specifies drivers and objects to be included in the build. There is no conditional
+compilation at this point. IF a socket is included, it includes the models. If a model is included, it should include {em all}
+objects, because it is not possible to determine at build time what options may be needed for a given model CPU.
+This Makefile.inc includes no other Makefile.inc files; any inclusion should be done in the socket Makefile.inc.
+
+\subsection{northbridge}
+\subsubsection{northbridge/Kconfig}
+No variables. Source all vendor directory Kconfigs.
+\subsubsection{northbridge/Makefile.inc}
+No variables. unconditionally include all vendor Makefile.inc
+\subsubsection{northbridge/$<$vendor$>$/Kconfig}
+No variables. Source all chip directory Kconfigs.
+\subsubsection{northbridge/$<$vendor$>$/Makefile.inc}
+No variables. {\em Conditionally} include all chipset Makefile.inc. The variable
+is the name of the part, e.g.
+\begin{verbatim}
+subdirs-$(CONFIG_NORTHBRIDGE_AMD_AMDK8) += amdk8
+\end{verbatim}
+.
+\subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Kconfig}
+Typically a small number of variables. One defines the part name. Here is an example
+of the variables defined for the K8.
+\begin{verbatim}
+config NORTHBRIDGE_AMD_AMDK8
+  bool
+  default n
+
+config AGP_APERTURE_SIZE
+  hex
+  default 0x4000000
+\end{verbatim}
+\subsubsection{northbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc}
+Typically very small set of rules, and very simple.
+Since this file is already conditionally included,
+we don't need to test for the chipset CONFIG variable. We
+can therefore test other variables (which is part of the reason
+we set up conditional inclusion of this file, instead
+of unconditionally including it). Here is an example from AMD K8.
+Note that we can make a variable conditional on the ACPI tables.
+\begin{verbatim}
+driver-y += northbridge.o
+driver-y += misc_control.o
+obj-y +=  get_sblk_pci1234.o
+obj-$(CONFIG_HAVE_ACPI_TABLES) +=  amdk8_acpi.o
+\end{verbatim}
+
+\subsection{southbridge}
+\subsubsection{southbridge/Kconfig}
+No variables. Source all vendor directory Kconfigs.
+\subsubsection{southbridge/Makefile.inc}
+No variables. {\em Unconditionally} include all vendor Makefile.inc
+\subsubsection{southbridge/$<$vendor$>$/Kconfig}
+No variables. Source all chip directory Kconfigs.
+\subsubsection{southbridge/$<$vendor$>$/Makefile.inc}
+No variables. {\em Conditionally} include all chipset Makefile.inc. The variable
+is the name of the part, e.g.
+\begin{verbatim}
+subdirs-$(CONFIG_SOUTHBRIDGE_AMD_AMD8111) += amd8111
+\end{verbatim}
+.
+\subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Kconfig}
+Typically a small number of variables. One defines the part name. Here is an example
+of the variables defined for the K8.
+\begin{verbatim}
+config SOUTHBRIDGE_AMD_AMD8111
+	bool
+	default n
+
+\end{verbatim}
+\subsubsection{southbridge/$<$vendor$>$/$<$chip$>$/Makefile.inc}
+Typically very small set of rules, and very simple.
+Since this file is already conditionally included,
+we don't need to test for the chipset CONFIG variable. We
+can therefore test other variables (which is part of the reason
+we set up conditional inclusion of this file, instead
+of unconditionally including it). Here is an example from AMD 8111.
+No conditionals in this one yet.
+\begin{verbatim}
+driver-y += amd8111.o
+driver-y += amd8111_usb.o
+driver-y += amd8111_lpc.o
+driver-y += amd8111_ide.o
+driver-y += amd8111_acpi.o
+driver-y += amd8111_usb2.o
+driver-y += amd8111_ac97.o
+driver-y += amd8111_nic.o
+driver-y += amd8111_pci.o
+driver-y += amd8111_smbus.o
+obj-y += amd8111_reset.o
+\end{verbatim}
+
+\subsubsection{vendor and part}
+\subsection{southbridge}
+\subsubsection{vendor and part}
+\subsection{superio}
+\subsection{drivers/i2c}
+This is a rather special case. There are no Kconfig files or Makefile.inc files here. They are not needed.
+To compile in one of these files, name the .o directory. E.g. in serengeti\_cheetah we have:
+\begin{verbatim}
+\end{verbatim}
+
+\subsubsection{vendor and part}
+
+\end{document}

firmware/coreboot/Documentation/Makefile

@@ -0,0 +1,76 @@
+#
+# Makefile for coreboot paper.
+# hacked together by Stefan Reinauer <stepan@openbios.org>
+#
+
+PDFLATEX=pdflatex -t a4
+
+FIGS=codeflow.pdf hypertransport.pdf
+
+all: corebootPortingGuide.pdf Kconfig.pdf
+
+SVG2PDF=$(shell which svg2pdf)
+INKSCAPE=$(shell which inkscape)
+CONVERT=$(shell which convert)
+
+codeflow.pdf: codeflow.svg
+ifneq ($(strip $(SVG2PDF)),)
+	svg2pdf $< $@
+else ifneq ($(strip $(INKSCAPE)),)
+	inkscape $< --export-pdf=$@
+else ifneq ($(strip $(CONVERT)),)
+	convert $< $@
+endif
+
+hypertransport.pdf: hypertransport.svg
+ifneq ($(strip $(SVG2PDF)),)
+	svg2pdf $< $@
+else ifneq ($(strip $(INKSCAPE)),)
+	inkscape $< --export-pdf=$@
+else ifneq ($(strip $(CONVERT)),)
+	convert $< $@
+endif
+
+corebootPortingGuide.toc: $(FIGS) corebootBuildingGuide.tex
+	# 2 times to make sure we have a current toc.
+	$(PDFLATEX) corebootBuildingGuide.tex
+	$(PDFLATEX) corebootBuildingGuide.tex
+
+corebootPortingGuide.pdf: $(FIGS) corebootBuildingGuide.tex corebootPortingGuide.toc
+	$(PDFLATEX) corebootBuildingGuide.tex
+
+Kconfig.pdf: Kconfig.tex mainboardkconfig.tex cpukconfig.tex socketfkconfig.tex
+	$(PDFLATEX) $<
+
+# quick, somebody! make me a macro!
+mainboardkconfig.tex: ../src/mainboard/Kconfig
+	cat beginverbatim.tex  > $@
+	grep '^config' $< | awk '{print $2}'  >>$@
+	cat endverbatim.tex  >> $@
+
+skconfig.tex: ../src/mainboard/amd/serengeti_cheetah/Kconfig
+	cat beginverbatim.tex  > $@
+	grep '^config' $< | awk '{print $2}'  >>$@
+	cat endverbatim.tex  >> $@
+
+cpukconfig.tex: ../src/cpu/Kconfig
+	cat beginverbatim.tex  > $@
+	grep '^config' $< | awk '{print $2}'  >>$@
+	cat endverbatim.tex  >> $@
+
+socketfkconfig.tex: ../src/cpu/amd/socket_F/Kconfig
+	cat beginverbatim.tex  > $@
+	grep '^config' $< | awk '{print $2}'  >>$@
+	cat endverbatim.tex  >> $@
+
+sphinx:
+	$(MAKE) -f Makefile.sphinx html
+
+clean-sphinx:
+	$(MAKE) -f Makefile.sphinx clean
+
+clean: clean-sphinx
+	rm -f *.aux *.idx *.log *.toc *.out $(FIGS) mainboardkconfig.tex skconfig.tex cpukconfig.tex socketfkconfig.tex
+
+distclean: clean
+	rm -f corebootPortingGuide.pdf Kconfig.pdf

firmware/coreboot/Documentation/Makefile.sphinx

@@ -0,0 +1,225 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  epub3      to make an epub3"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  dummy      to check syntax errors of document sources"
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: dirhtml
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/coreboot.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/coreboot.qhc"
+
+.PHONY: applehelp
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+.PHONY: devhelp
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/coreboot"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/coreboot"
+	@echo "# devhelp"
+
+.PHONY: epub
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:
+	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+	@echo
+	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: latex
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+.PHONY: dummy
+dummy:
+	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
+	@echo
+	@echo "Build finished. Dummy builder generates no files."

firmware/coreboot/Documentation/POSTCODES

@@ -0,0 +1,25 @@
+-------------------------------------------------------------------------------
+coreboot POST Codes
+-------------------------------------------------------------------------------
+
+This is an (incomplete) list of POST codes emitted by coreboot v4.
+
+0x10 Entry into protected mode
+0x01 Entry into 'crt0.s' reset code jumps to here
+0x11 Start copying coreboot to RAM with decompression if compressed
+0x12 Copy/decompression finished jumping to RAM
+0x80 Entry into coreboot in RAM
+0x13 Entry into c_start
+0xfe Pre call to hardwaremain()
+0x39 Console is initialized
+0x40 Console boot message succeeded
+0x66 Devices have been enumerated
+0x88 Devices have been configured
+0x89 Devices have been enabled
+0xf8 Entry into elf boot
+0xf3 Jumping to payload
+
+Errors (used in several places):
+
+0xee Not supposed to get here
+0xff Elfload fail or die() called

firmware/coreboot/Documentation/RFC/chip.tex

@@ -0,0 +1,266 @@
+		RFC for the chip specification architecture
+
+\begin{abstract}
+At the end of this document is the original message that motivated the
+change.
+\end{abstract}
+
+\section{Scope}
+This document defines how LinuxBIOS programmers can specify chips that
+are used, specified, and initalized. The current scope is for superio
+chips, but the architecture should allow for specification of other chips such
+as southbridges. Multiple chips of same or different type are supported.
+
+\section{Goals}
+The goals of the new chip architecture are these:
+\begin{itemize}
+\item separate implementation details from specification in the Config file
+(translation: no more C code in Config files)
+\item make the specification easier for people to use and understand
+\item remove private details of a given chip to the chip file as much
+as possible
+\item allow unique register-set-specifiers for each chip
+\end{itemize}
+
+\section{Specification in the Config file}
+The specification looks like this:
+\begin{verbatim}
+chip <name> [path=<path>] ["<configuration>"]
+\end{verbatim}
+The name is in the standard LinuxBIOS form of type/vendor/name, e.g.
+"southbridge/intel/piix4e" or "superio/ite/it8671f". The class of the
+chip is derived from the first pathname component of the name, and the chip
+configuration is derived from the following components.
+
+The path defines the access mechanism to the chip.
+It is optional. If present, it overrides the default path to the chip.
+
+The configuration defines chip-specific configuration details, and is also
+optional. Note that an empty configuration will leave the chip with
+no enabled resources. This may be desirable in some cases.
+
+\section{Results of specifying a chip}
+
+When one or more chips are specified, the data about the chips
+is saved until the entire file is parsed. At this point, the config tool
+creates a file in the build directory called chip.c This file contains
+a common struct containing information about
+each individual chip and an array of pointers to these structures.
+
+For each chip, there are two structures. The structures contain control
+information for the chip, and register initialization information. The
+names of the structures are derived by ``flattening'' the chip name,
+as in the current linuxbios. For example, superio/ite/xyz uses
+two structs, one called superio_ite_xyz_control and one called
+superio_ite_xyz_init. The control struct is initialized from the
+chip name and path information, and has a pointer to the
+config struct. The config struct is initialized from the quote string
+
+\begin{verbatim}
+From rminnich@lanl.gov Fri May 16 10:34:13 2003
+Date: Tue, 13 May 2003 08:11:46 -0600 (MDT)
+From: ron minnich <rminnich@lanl.gov>
+To: linuxbios@clustermatic.org
+Subject: RFC:new superio proposal
+
+Abstract:
+	The superio architecture for linuxbios has worked for the last 2
+years but is being stretched to the limit by the changes in superio chips.
+The architecture depended on superio resources being relatively constant
+between chips, but this assumption no longer holds. In this document we
+propose several alternatives and solicit comments.
+
+Overview:
+The superio architecture in linuxbios was developed over time, and
+modified as circumstances required. In the beginning it was relatively
+simple and assumed only one superio per mainboard. The latest version
+allows an arbitrary number of superios per mainboard, and allows complete
+specification of the superio base I/O address along with the specification
+of reasonable default valures for both the base I/O address and the
+superio parameters such as serial enable, baud rate, and so on.
+
+Specification of superio control parameters is done by a configuration
+line such as:
+
+nsuperio sis/950 com1={1} floppy=1  lpt=1
+
+This fragment sets the superio type to sis/950; sets com1, floppy, and lpt
+to enabled; and leaves the defaults to com1 (baud rate, etc.) to the
+default values.
+
+While it is not obvious, these configuration parameters are fragments of a
+C initializer. The initializers are used to build a statically initialized
+structure of this type:
+
+struct superio {
+        struct superio_control *super; // the ops for the device.
+        unsigned int port; // if non-zero, overrides the default port
+        // com ports. This is not done as an array (yet).
+        // We think it's easier to set up from python if it is not an
+	// array.
+        struct com_ports com1, com2, com3, com4;
+        // DMA, if it exists.
+        struct lpt_ports lpt1, lpt2;
+        /* flags for each device type. Unsigned int. */
+        // low order bit ALWAYS means enable. Next bit means to enable
+        // LPT is in transition, so we leave this here for the moment.
+        // The winbond chips really stretched the way this works.
+        // so many functions!
+        unsigned int ide, floppy, lpt;
+        unsigned int keyboard, cir, game;
+        unsigned int gpio1, gpio2, gpio3;
+        unsigned int acpi,hwmonitor;
+};
+
+These structures are, in turn, created and statically initialized by a
+config-tool-generated structure that defines all the superios. This file
+is called nsuperio.c, is created for each mainboard you build, only
+appears in the build directory, and looks like this:
+
+===
+extern struct superio_control superio_winbond_w83627hf_control;
+
+struct superio superio_winbond_w83627hf= {
+  &superio_winbond_w83627hf_control,
+  .com1={1}, .com2={1}, .floppy=1, .lpt=1, .keyboard=1, .hwmonitor=1};
+
+struct superio *all_superio[] = {&superio_winbond_w83627hf,
+};
+
+unsigned long nsuperio = 1;
+===
+
+This example shows a board with one superio (nsuperio). The superio
+consists of a winbond w83627hf, with com1, com2, floppy, lpt, keyboard,
+and hwmonitor enabled. Note that this structure also allows for
+over-riding the default superio base, although that capability is rarely
+used.
+
+The control structure is used to define how to access the superio for
+purposes of control. It looks like this:
+===
+struct superio_control {
+  void (*pre_pci_init)(struct superio *s);
+  void (*init)(struct superio *s);
+  void (*finishup)(struct superio *s);
+  unsigned int defaultport;     /* the defaultport. Can be overridden
+                                 * by commands in config
+                                 */
+  // This is the print name for debugging
+  char *name;
+};
+===
+
+There are three methods for stages of hardwaremain. First is pre_pci_init
+(for chips like the acer southbridge that require you to enable some
+resources BEFORE pci scan); init, called during the 'middle' phase of
+hardwaremain; and finishup, called before the payload is loaded.
+
+This approach was inspired by and borrows heavily on the Plan 9 kernel
+configuration tools.
+
+The problem:
+
+When the first version of the superio structure came out it was much
+smaller. It has grown and in the limit this structure is the union of all
+possibly superio chips. Obviously, in the long term, this is not
+practical: we can not anticipate all possible superio chips for all time.
+
+The common PC BIOS solution to this type of problem is to continue with
+binary structures but add version numbers to them, so that all code that
+uses a given structure has to check the version number. Personally, I find
+this grotesque and would rather not work this way.
+
+Using textual strings for configuration is something I find far more
+attractive. Plan 9 has shown that this approach has no real limits and
+suffices for configuration tasks. The Linux kernel does more limited use
+of strings for configuration, but still depends on them. Strings are
+easier to read and work with than binary structures, and more important, a
+lot easier to deal with when things start going wrong.
+
+The proposed solution:
+
+What follows are three possible ideas for specifying superio resources and
+their settings.
+
+A common part of the new idea is to eliminate the common superio
+structure, due to the many variations in chips, and make it invisible
+outside a given superio source file -- the superio structure is now
+private to a given superio. Thus, sis/950/superio.c would contain its own
+superio structure definitions, and also might contain more than once
+instance of these structures (consider a board with 2 sis 950 chips).
+
+The control structure would change as follows:
+struct superio_control {
+  int (*create)(struct superio *s);
+  void (*pre_pci_init)(struct superio *s);
+  void (*init)(struct superio *s);
+  void (*finishup)(struct superio *s);
+  unsigned int defaultport;     /* the defaultport. Can be overridden
+                                 * by commands in config
+                                 */
+  // This is the print name for debugging
+  char *name;
+};
+
+I.e. we add a new function for creating the superio.
+
+Communication of superio settings from linuxbios to the superio would be
+via textual strings. The superio structure becomes this:
+
+struct superio {
+        struct superio_control *super; // the ops for the device.
+        unsigned int port; // if non-zero, overrides the default port
+	struct configuration *config;
+};
+
+
+So now the question becomes, what is the configuration structure?
+There are several choices. The simplest, from my point of view, are
+keyword-value pairs:
+struct configuration {
+	const char *keyword;
+	const char *value;
+};
+
+These get filled in by the config tool as before. The linuxbios library can
+then provide a generic parsing function for the superios to use.
+
+The remaining question is how should the superio command look in
+freebios2?
+
+superio sis/950 "com1=115200,8n1 lpt=1 com2=9600"
+
+or
+
+superio sis/950 "com1baud=115200 lpt=1 com1chars=8n1"
+
+or
+
+superio sis/950 ((com1 115200 8n1) (lpt 1))
+
+So,  my questions:
+
+1. Does this new scheme look workable. If not, what needs to change?
+2. What should the 'struct configuration' be? does keyword/value work?
+3. what should the superio command look like?
+
+Comments welcome.
+
+I'd like to adopt this "RFC" approach for freebios2 as much as we can.
+There was a lot of give-and-take in the early days of linuxbios about
+structure and it proved useful. There's a lot that will start happening in
+freebios2 now, and we need to try to make sure it will work for everyone.
+
+Those of you who are doing mainboards, please look at freebios2 and see
+how it looks for you. There's a lot of good work that has been done (not
+by me so far, thanks Eric and Stefan), and more that needs to be done.
+Consider trying out romcc as an "assembly code killer". See how it fits
+together and if you can work with it or need changes. Bring comments back
+to this list.
+
+thanks
+
+ron
+
+\end{verbatim}

firmware/coreboot/Documentation/RFC/config.tex

@@ -0,0 +1,290 @@
+		New config language for LinuxBIOS
+
+\begin{abstract}
+We describe the new configuration language for LinuxBIOS.
+\end{abstract}
+
+\section{Scope}
+This document defines the new configuration language for LinuxBIOS.
+
+\section{Goals}
+The goals of the new language are these:
+\begin{itemize}
+\item Simplified Makefiles so people can see what is set
+\item Move from the regular-expression-based language to something
+a bit more comprehensible and flexible
+\item make the specification easier for people to use and understand
+\item allow unique register-set-specifiers for each chip
+\item allow generic register-set-specifiers for each chip
+\item generate static initialization code, as needed, for the
+specifiers.
+\end{itemize}
+
+\section{Language}
+Here is the new language. It is very similar to the old one, differing
+in only a few respects. It borrows heavily from Greg Watson's suggestions.
+
+I am presenting it in a pseudo-BNF in the hopes it will be easier. Things
+in '' are keywords; things in ``'' are strings in the actual text.
+\begin{verbatim}
+#exprs are composed of factor or factor + factor etc.
+expr ::= factor ( ``+'' factor | ``-'' factor | )*
+#factors are term or term * term or term / term or ...
+factor ::=  term ( ``*'' term | ``/'' term | ... )*
+#
+unary-op ::= ``!'' ID
+# term is a number, hexnumber, ID, unary-op, or a full-blown expression
+term ::= NUM | XNUM | ID | unary-op | ``(`` expr ``)''
+
+# Option command. Can be an expression or quote-string.
+# Options are used in the config tool itself (in expressions and 'if')
+# and are also passed to the C compiler when building linuxbios.
+# It is an error to have two option commands in a file.
+# It is an error to have an option command after the ID has been used
+#   in an expression (i.e. 'set after used' is an error)
+option ::= 'option' ID '=' (``value'' | term)
+
+# Default command. The ID is set to this value if no option command
+# is scanned.
+# Multiple defaults for an ID will produce warning, but not errors.
+# It is OK to scan a default command after use of an ID.
+# Options always over-ride defaults.
+default ::= 'default' ID '=' (``value'' | term)
+
+# the mainboard, southbridge, northbridge commands
+# cause sourcing of Config.lb files as in the old config tool
+# as parts are sourced, a device tree is built. The structure
+# of the tree is determined by the structure of the components
+# as they are specified. To attach a superio to a southbridge, for
+# example, one would do this:
+# southbridge acer/5432
+#   superio nsc/123
+#   end
+# end
+# the tool generates static initializers for this hierarchy.
+
+# add C code to the current component (motherboard, etc. )
+# to initialise the component-INDEPENDENT structure members
+init ::= 'init' ``CODE''
+
+# add C code to the current component (motherboard, etc. )
+# to initialise the component-DEPENDENT structure members
+register ::= 'register' ``CODE''
+
+
+# mainboard command
+# statements in this block will set variables controlling the mainboard,
+# and will also place components (northbridge etc.) in the device tree
+# under this mainboard
+mainboard ::= 'mainboard' PATH (statements)* 'end'
+
+# standard linuxbios commands
+southbridge ::= 'southbridge' PATH (statemnts)* 'end'
+northbridge ::= 'northbridge' PATH (statemnts)* 'end'
+superio ::= 'superio PATH (statemnts)* 'end'
+cpu ::= 'cpu' PATH (statemnts)* 'end'
+arch ::= 'arch' PATH (statemnts)* 'end'
+
+# files for building linuxbios
+# include a file in crt0.S
+mainboardinit ::= 'mainboardinit' PATH
+
+# object file
+object ::= 'object' PATH
+# driver objects are just built into the image in a different way
+driver ::= 'driver' PATH
+
+# Use the Config.lb file in the PATH
+dir ::= 'dir' PATH
+
+# add a file to the set of ldscript files
+ldscript ::= 'ldscript' PATH
+
+# dependencies or actions for the makerule command
+dep ::= 'dep' ``dependency-string''
+act ::= 'act' ``actions''
+depsacts ::= (dep | act)*
+# set up a makerule
+#
+makerule ::= 'makerule' PATH depsacts
+
+#defines for use in makefiles only
+# note usable in the config tool, not passed to cc
+makedefine ::= 'makedefine' ``RAWTEXT''
+
+# add an action to an existing make rule
+addaction ::= 'addaction' PATH ``ACTION''
+
+# statements
+statement ::=
+		  option
+		| default
+		| cpu
+		| arch
+		| northbridge
+		| southbridge
+		| superio
+		| object
+		| driver
+		| mainboardinit
+		| makerule
+		| makedefine
+		| addaction
+		| init
+		| register
+		| iif
+		| dir
+		| ldscript
+
+statements ::= (statement)*
+
+# target directory specification
+target ::= 'target' PATH
+
+# and the whole thing
+board ::= target (option)* mainboard
+
+\end{verbatim}
+
+\subsubsection{Command definitions}
+\subsubsubsection{option}
+\subsubsubsection{default}
+\subsubsubsection{cpu}
+\subsubsubsection{arch}
+\subsubsubsection{northbridge}
+\subsubsubsection{southbridge}
+\subsubsubsection{superio}
+\subsubsubsection{object}
+\subsubsubsection{driver}
+\subsubsubsection{mainboardinit}
+\subsubsubsection{makerule}
+\subsubsubsection{makedefine}
+\subsubsubsection{addaction}
+\subsubsubsection{init}
+\subsubsubsection{register}
+\subsubsubsection{iif}
+\subsubsubsection{dir}
+\subsubsubsection{ldscript}
+
+
+A sample file:
+
+\begin{verbatim}
+target x
+
+# over-ride the default ROM size in the mainboard file
+option CONFIG_ROM_SIZE=1024*1024
+mainboard amd/solo
+end
+
+\end{verbatim}
+
+Sample mainboard file
+\begin{verbatim}
+#
+###
+### Set all of the defaults for an x86 architecture
+###
+arch i386 end
+cpu k8 end
+#
+option CONFIG_DEBUG=1
+default CONFIG_USE_FALLBACK_IMAGE=1
+option A=(1+2)
+option B=0xa
+#
+###
+### Build our 16 bit and 32 bit linuxBIOS entry code
+###
+mainboardinit cpu/i386/entry16.inc
+mainboardinit cpu/i386/entry32.inc
+ldscript cpu/i386/entry16.lds
+ldscript cpu/i386/entry32.lds
+#
+###
+### Build our reset vector (This is where linuxBIOS is entered)
+###
+if CONFIG_USE_FALLBACK_IMAGE
+	mainboardinit cpu/i386/reset16.inc
+	ldscript cpu/i386/reset16.lds
+else
+	mainboardinit cpu/i386/reset32.inc
+	ldscript cpu/i386/reset32.lds
+end
+.
+.
+.
+if CONFIG_USE_FALLBACK_IMAGE mainboardinit arch/i386/lib/noop_failover.inc  end
+#
+###
+### Romcc output
+###
+#makerule ./failover.E dep "$(CONFIG_MAINBOARD)/failover.c" act "$(CPP) -I$(TOP)/src $(CPPFLAGS) $(CONFIG_MAINBOARD)/failover.c > ./failever.E"
+#makerule ./failover.inc dep "./romcc ./failover.E" act "./romcc -O ./failover.E > failover.inc"
+#mainboardinit ./failover.inc
+makerule ./auto.E dep "$(CONFIG_MAINBOARD)/auto.c" act "$(CPP) -I$(TOP)/src -$(ROMCCPPFLAGS) $(CPPFLAGS) $(CONFIG_MAINBOARD)/auto.c > ./auto.E"
+makerule ./auto.inc dep "./romcc ./auto.E" act "./romcc -O ./auto.E > auto.inc"
+mainboardinit ./auto.inc
+#
+###
+### Include the secondary Configuration files
+###
+northbridge amd/amdk8
+end
+southbridge amd/amd8111
+end
+#mainboardinit arch/i386/smp/secondary.inc
+superio nsc/pc87360
+	register "com1={1} com2={0} floppy=1 lpt=1 keyboard=1"
+end
+dir /pc80
+##dir /src/superio/winbond/w83627hf
+cpu p5 end
+cpu p6 end
+cpu k7 end
+cpu k8 end
+#
+###
+### Build the objects we have code for in this directory.
+###
+##object mainboard.o
+driver mainboard.o
+object static_devices.o
+if CONFIG_HAVE_MP_TABLE object mptable.o end
+if CONFIG_HAVE_PIRQ_TABLE object irq_tables.o end
+### Location of the DIMM EEPROMS on the SMBUS
+### This is fixed into a narrow range by the DIMM package standard.
+###
+option SMBUS_MEM_DEVICE_START=(0xa << 3)
+option SMBUS_MEM_DEVICE_END=(SMBUS_MEM_DEVICE_START +1)
+option SMBUS_MEM_DEVICE_INC=1
+#
+### The linuxBIOS bootloader.
+###
+option CONFIG_PAYLOAD_SIZE            = (CONFIG_ROM_SECTION_SIZE - CONFIG_ROM_IMAGE_SIZE)
+option CONFIG_ROM_PAYLOAD_START = (0xffffffff - CONFIG_ROM_SIZE + CONFIG_ROM_SECTION_OFFSET + 1)
+#
+
+\end{verbatim}
+
+I've found the output of the new tool to be easier to
+handle. Makefile.settings looks like this, for example:
+\begin{verbatim}
+TOP:=/home/rminnich/src/yapps2/freebios2
+TARGET_DIR:=x
+export CONFIG_MAINBOARD:=/home/rminnich/src/yapps2/freebios2/src/mainboard/amd/solo
+export CONFIG_ARCH:=i386
+export CONFIG_RAMBASE:=0x4000
+export CONFIG_ROM_IMAGE_SIZE:=65535
+export CONFIG_PAYLOAD_SIZE:=131073
+export CONFIG_MAX_CPUS:=1
+export CONFIG_HEAP_SIZE:=8192
+export CONFIG_STACK_SIZE:=8192
+export CONFIG_MEMORY_HOLE:=0
+export COREBOOT_VERSION:=1.1.0
+export CC:=$(CONFIG_CROSS_COMPILE)gcc
+
+\end{verbatim}
+
+In other words, instead of expressions, we see the values. It's easier to
+deal with.

firmware/coreboot/Documentation/_static/theme_overrides.css

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2018 Patrick Rudolph <siro@das-labor.org>
+ *
+ * licensed under CC-by 4.0
+ */
+
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}
+

firmware/coreboot/Documentation/abi-data-consumption.md

@@ -0,0 +1,24 @@
+# ABI data consumption
+
+This text describes the ABI coreboot presents to downstream users. Such
+users are payloads and/or operating systems. Therefore, this text serves
+at what can be relied on for downstream consumption. Anything not explicitly
+listed as consumable is subject to change without notice.
+
+## Background and Usage
+
+coreboot passes information to downstream users using coreboot tables. These
+table definitions can be found in src/include/boot/coreboot_tables.h and
+payloads/libpayload/include/coreboot_tables.h respectively within coreboot
+and libpayload. One of the most vital and important pieces of information
+found within these tables is the memory map of the system indicating
+available and reserved memory.
+
+In 2009 cbmem was added to coreboot. The "CBMEM high table memory manager"
+serves a way for coreboot to bookkeep its own internal data. While some
+of this data may be exposed through the coreboot tables the data structures
+used to manage the data within the cbmem area is subject to change.
+
+Provided the above, if one needs a piece of data exposed to the OS
+or payload it should reside within the coreboot tables. If it isn't there
+then a code change will be required to add it to the coreboot tables.

firmware/coreboot/Documentation/acpi/gpio.md

@@ -0,0 +1,181 @@
+# GPIO toggling in ACPI AML for coreboot
+
+## Table of contents
+- Introduction
+- Platform Interface
+- Helper routines
+- Implementation details
+- Arguments and Local Variables Management
+
+## Introduction
+
+ACPI provides platform-independent interfaces enabling the operating
+system to perform power management for devices as well as the entire
+system. An operating system can simply call into Method()s implemented
+by the interface to request different power management operations. In
+order to be able to perform these operations, an interface might
+require toggling of GPIOs. e.g. a touchscreen device interface might
+require toggling of reset-gpio in order to take the device out of
+reset or to put it back into reset.
+
+Thus, any coreboot driver that implements such an ACPI interface might
+require the ability to toggle GPIOs. However, toggling of GPIO is not
+the same across different platforms and it will require the driver to
+depend upon platform to do the required work. This document presents a
+simple interface that can be used by any coreboot driver to generate
+ACPI AML code for reading or toggling platform GPIOs.
+
+## Platform Interface
+
+All platforms that use drivers requiring ACPI AML code for GPIO
+interactions need to be implement the following functions:
+1. Return GPIO Rx value if it is acting as input
+   int acpigen_soc_read_rx_gpio(unsigned int gpio_num)
+2. Return GPIO Tx value if it is acting as output
+   int acpigen_soc_get_tx_gpio(unsigned int gpio_num)
+3. Set GPIO Tx value to 1 if it is acting as output
+   int acpigen_soc_set_tx_gpio(unsigned int gpio_num)
+4. Set GPIO Tx value to 0 if it is acting as output
+   int acpigen_soc_clear_tx_gpio(unsigned int gpio_num)
+
+Each of the above functions takes as input gpio_num which is the gpio
+number that needs to be read or toggled and returns an integer which
+is:
+1. Error = -1
+2. Success = 0
+
+Above callback functions are chosen to be implemented in C rather than
+adding them as AML code callbacks for the following reasons:
+1. It is easier to add error prints in C which will inform the
+   developer that these callbacks are missing. It restricts debugging
+   to coreboot logs.
+2. GPIO conversion from number to register offset can be easily done
+   in C by reusing implemented functions rather than adding all the
+   logic to AML code or depending upon complicated macros to be added
+   to device-tree.
+3. Allows GPIO AML methods to be present under any device scope and
+   gives SoC the flexibility to call them without any restrictions.
+
+## Helper routines
+
+In order to relieve drivers of the task of implementing the same code
+for enabling/disabling Tx GPIOs based on the GPIO polarity, helper
+routines are provided which implement this common code and can be used
+directly in the driver routines:
+1. Enable Tx GPIO
+   int acpigen_enable_tx_gpio(struct acpi_gpio gpio)
+2. Disable Tx GPIO
+   int acpigen_disable_tx_gpio(struct acpi_gpio gpio)
+
+Both the above functions take as input struct acpi_gpio type and
+return -1 on error and 0 on success. These helper routines end up
+calling the platform specific acpigen_soc_{set,clear}_tx_gpio
+functions internally. Thus, all the ACPI AML calling conventions for
+the platform functions apply to these helper functions as well.
+
+## Implementation Details
+
+ACPI library in coreboot will provide weak definitions for all the
+above functions with error messages indicating that these functions
+are being used. This allows drivers to conditionally make use of GPIOs
+based on device-tree entries or any other config option. It is
+recommended that the SoC code in coreboot should provide
+implementations of all the above functions generating ACPI AML code
+irrespective of them being used in any driver. This allows mainboards
+to use any drivers and take advantage of this common infrastructure.
+
+Platforms are restricted to using Local5, Local6 and Local7 variables
+only in implementations of the above functions. Any AML methods called
+by the above functions do not have any such restrictions on use of
+Local variables in AML code. Local0 is to be used for all get/read
+functions to return values. This means that the driver code should not
+make any assumptions about the values in Local5, Local6 and Local7
+variables.
+
+```
+ **Function**                   **Operation**                **Return**
+ acpigen_soc_read_rx_gpio     Generate ACPI AML code to      Error = -1
+                              read value of Rx in Local0.    Success = 0
+ acpigen_soc_get_tx_gpio      Generate ACPI AML code to      Error = -1
+                              get value of Tx in Local0.     Success = 0
+ acpigen_soc_set_tx_gpio      Generate ACPI AML code to      Error = -1
+                              set Tx to 1.                   Success = 0
+ acpigen_soc_clear_tx_gpio    Generate ACPI AML code to      Error = -1
+                              set Tx to 0.                   Success = 0
+```
+
+Ideally, the operation column in the above table should use one or
+more functions implemented by the platform in AML code library (like
+gpiolib.asl). In the example below SPC0 and GPC0 need to be
+implemented by the SoC in AML code library and they can be used by
+acpi_soc_set_tx_gpio to read and set bit in the appropriate register
+for the GPIO.
+
+**acpigen_soc_set_tx_gpio**
+
+	uint64_t gpio_reg_offset = gpio_get_reg_offset(gpio_num);
+
+	/* Store (\_SB.GPC0(gpio_reg_offset, Local5) */
+	acpigen_write_store();
+	acpigen_emit_namestring(“\\_SB.GPC0”);
+	acpigen_write_integer(gpio_reg_offset);
+	acpigen_emit_byte(LOCAL5_OP);
+
+
+	/* Or (Local5, TX_BIT, Local5) */
+	acpigen_write_or(LOCAL5_OP, TX_BIT, LOCAL5_OP);
+
+	/* \_SB.SPC0(gpio_reg_offset, LOCAL5) */
+	acpigen_emit_namestring(“\\_SB.SPC0”);
+	acpigen_write_integer(gpio_reg_offset);
+	acpigen_emit_byte(LOCAL5_OP);
+
+	return 0;
+
+**acpigen_soc_get_tx_gpio**
+
+	uint64_t gpio_reg_offset = gpio_get_reg_offset(gpio_num);
+
+
+	/* Store (\_SB.GPC0(gpio_reg_offset, Local5) */
+	acpigen_write_store();
+	acpigen_emit_namestring(“\\_SB.GPC0”);
+	acpigen_write_integer(gpio_reg_offset);
+	acpigen_emit_byte(LOCAL5_OP);
+
+
+	/*
+	 * If (And (Local5, TX_BIT)) Store (One, Local0) Else Store (Zero,
+	 * Local0)
+	 */
+	acpigen_write_if_and(Local5, TX_BIT);
+	acpigen_write_store_args(ONE_OP, LOCAL0_OP);
+	acpigen_pop_len();
+	acpigen_write_else();
+	acpigen_write_store_args(ZERO_OP, LOCAL0_OP);
+	acpigen_pop_len();
+
+	return 0;
+
+
+These are reference implementations and the platforms are free to
+implement these functions in any way they like. coreboot driver can
+then simply call into these functions to generate ACPI AML code to
+get/set/clear any GPIO. In order to decide whether GPIO operations are
+required, driver code can rely either on some config option or read
+device-tree to use any user-provided GPIOs.
+
+## Arguments and Local Variables Management
+
+Platform-defined functions can call methods using the same calling
+conventions provided by AML code. However, use of Local Variables is
+restricted to Local5, Local6 and Local7 unless they call into some
+other method. Called method can use any Local variables, Local0 -
+Local7. In case of functions expected to return back value to the
+caller, this value is expected to be returned in Local0.
+
+Driver code should not make any assumptions about the contents of
+Local5, Local6 and Local7 across callbacks to SoC code. If it makes a
+read or get call to SoC, the return value should be used from Local0
+on return. However, if it makes a set or clear call to SoC, the value
+in Local0 is undefined.

firmware/coreboot/Documentation/beginverbatim.tex

@@ -0,0 +1 @@
+\begin{verbatim}

firmware/coreboot/Documentation/cbfs.txt

@@ -0,0 +1,421 @@
+
+Received: from www.crouse-house.com ([199.45.160.146]
+	for coreboot@coreboot.org; Fri, 19 Dec 2008 23:11:59 +0100
+From: Jordan Crouse <jordan@cosmicpenguin.net>
+
+
+Greetings.  I apologize for the incompleteness of what I am about to
+discuss.  I was planning on working on it leisurely, but my employment
+circumstances changed and I've been trying to get it completed in a
+hurry before I had to leave it behind.
+
+I've been thinking a lot about LAR lately, and ways to make it more
+extensible and robust.  Marc and I have been trading ideas back and
+forth for a number of months, and over time a clear idea of what I
+wanted to do started to take shape.
+
+My goal was to add small things to LAR while retaining the overall
+scheme.  Over time, the scheme evolved slightly, but I think you'll find
+that it remains true to the original idea.  Below is the beginnings of
+an architecture document - I did it in text form, but if met with
+aclaim, it should be wikified.  This presents what I call CBFS - the
+next generation LAR for next generation coreboot.  Its easier to
+describe what it is by describing what changed:
+
+A header has been added somewhere in the bootblock similar to Carl
+Daniel's scheme.  In addition to the coreboot information, the header
+reports the size of the ROM, the alignment of the blocks, and the offset
+of the first component in the CBFS.   The master header provides all
+the information LAR needs plus the magic number information flashrom needs.
+
+Each "file" (or component, as I style them) now has a type associated
+with it. The type is used by coreboot to identify the type of file that
+it is loading, and it can also be used by payloads to group items in the
+CBFS by type (i.e - bayou can ask for all components that are payloads).
+
+The header on each "file" (or component, as I like to style them) has
+been simplified - We now only store the length, the type, the checksum,
+and the offset to the data.  The name scheme remains the same.  The
+additional information, which is component specific, has been moved to
+the component itself (see below).
+
+The components are arranged in the ROM aligned along the specified
+alignment from the master header - this is to facilitate partial re-write.
+
+Other then that, the LAR ideas remain pretty much the same.
+
+The plan for moving the metadata to the components is to allow many
+different kinds of components, not all of which are groked by coreboot.
+  However, there are three essential component types that are groked by
+coreboot, and they are defined:
+
+stage - the stage is being parsed from the original ELF, and stored in
+the ROM as a single blob of binary data.  The load address, start
+address, compression type and length are stored in the component sub-header.
+
+payload - this is essentially SELF in different clothing - same idea as
+SELF, with the sub-header as above.
+
+optionrom - This is in flux - right now, the optionrom is stored
+unadulterated and uncompressed, but that is likely to be changed.
+
+Following this email are two replies containing the v3 code and a new
+ROM tool to implement this respectively.  I told you that I was trying
+to get this out before I disappear, and I'm not kidding - the code is
+compile tested and not run-tested.  I hope that somebody will embrace
+this code and take it the rest of the way, otherwise it will die a
+pretty short death.
+
+I realize that this will start an awesome flamewar, and I'm looking
+forward to it.  Thanks for listening to me over the years - and good
+luck with coreboot.  When you all make a million dollars, send me a few
+bucks, will you?
+
+Jordan
+
+coreboot CBFS Specification
+Jordan Crouse <jordan@cosmicpenguin.net>
+
+= Introduction =
+
+This document describes the coreboot CBFS specification (from here
+referred to as CBFS).  CBFS is a scheme for managing independent chunks
+of data in a system ROM.  Though not a true filesystem, the style and
+concepts are similar.
+
+
+= Architecture =
+
+The CBFS architecture looks like the following:
+
+/---------------\ <-- Start of ROM
+| /-----------\ | --|
+| | Header    | |   |
+| |-----------| |   |
+| | Name      | |   |-- Component
+| |-----------| |   |
+| |Data       | |   |
+| |..         | |   |
+| \-----------/ | --|
+|               |
+| /-----------\ |
+| | Header    | |
+| |-----------| |
+| | Name      | |
+| |-----------| |
+| |Data       | |
+| |..         | |
+| \-----------/ |
+|               |
+| ...           |
+| /-----------\ |
+| |           | |
+| | Bootblock | |
+| | --------- | |
+| | Reset     | | <- 0xFFFFFFF0
+| \-----------/ |
+\---------------/
+
+
+The CBFS architecture consists of a binary associated with a physical
+ROM disk referred hereafter as the ROM. A number of independent of
+components, each with a  header prepended on to data are located within
+the ROM.  The components are nominally arranged sequentially, though they
+are aligned along a pre-defined boundary.
+
+The bootblock occupies the last 20k of the ROM.  Within
+the bootblock is a master header containing information about the ROM
+including the size, alignment of the components, and the offset of the
+start of the first CBFS component within the ROM.
+
+= Master Header =
+
+The master header contains essential information about the ROM that is
+used by both the CBFS implementation within coreboot at runtime as well
+as host based utilities to create and manage the ROM.  The master header
+will be located somewhere within the bootblock (last 20k of the ROM).  A
+pointer to the location of the header will be located at offset
+-4 from the end of the ROM.  This translates to address 0xFFFFFFFC on a
+normal x86 system.  The pointer will be to physical memory somewhere
+between - 0xFFFFB000 and 0xFFFFFFF0.  This makes it easier for coreboot
+to locate the header at run time.  Build time utilities will
+need to read the pointer and do the appropriate math to locate the header.
+
+The following is the structure of the master header:
+
+struct cbfs_header {
+        u32 magic;
+        u32 version;
+        u32 romsize;
+        u32 bootblocksize;
+        u32 align;
+        u32 offset;
+        u32 architecture;
+        u32 pad[1];
+} __packed;
+
+The meaning of each member is as follows:
+
+'magic' is a 32 bit number that identifies the ROM as a CBFS type.  The
+magic
+number is 0x4F524243, which is 'ORBC' in ASCII.
+
+'version' is a version number for CBFS header. cbfs_header structure may be
+different if version is not matched.
+
+'romsize' is the size of the ROM in bytes.  coreboot will subtract 'size' from
+0xFFFFFFFF to locate the beginning of the ROM in memory.
+
+'bootblocksize' is the size of bootblock reserved in firmware image.
+
+'align' is the number of bytes that each component is aligned to within the
+ROM.  This is used to make sure that each component is aligned correctly
+with
+regards to the erase block sizes on the ROM - allowing one to replace a
+component at runtime without disturbing the others.
+
+'offset' is the offset of the the first CBFS component (from the start of
+the ROM).  This is to allow for arbitrary space to be left at the beginning
+of the ROM for things like embedded controller firmware.
+
+'architecture' describes which architecture (x86, arm, ...) this CBFS is created
+for.
+
+= Bootblock =
+The bootblock is a mandatory component in the ROM.  It is located in the
+last
+20k of the ROM space, and contains, among other things, the location of the
+master header and the entry point for the loader firmware.  The bootblock
+does not have a component header attached to it.
+
+= Components =
+
+CBFS components are placed in the ROM starting at 'offset' specified in
+the master header and ending at the bootblock.  Thus the total size
+available
+for components in the ROM is (ROM size - 20k - 'offset').  Each CBFS
+component is to be aligned according to the 'align' value in the header.
+Thus, if a component of size 1052 is located at offset 0 with an 'align'
+value
+of 1024, the next component will be located at offset 2048.
+
+Each CBFS component will be indexed with a unique ASCII string name of
+unlimited size.
+
+Each CBFS component starts with a header:
+
+struct cbfs_file {
+         char magic[8];
+         unsigned int len;
+         unsigned int type;
+         unsigned int checksum;
+         unsigned int offset;
+};
+
+'magic' is a magic value used to identify the header.  During runtime,
+coreboot will scan the ROM looking for this value.  The default magic is
+the string 'LARCHIVE'.
+
+'len' is the length of the data, not including the size of the header and
+the size of the name.
+
+'type' is a 32 bit number indicating the type of data that is attached.
+The data type is used in a number of ways, as detailed in the section
+below.
+
+'checksum' is a 32bit checksum of the entire component, including the
+header and name.
+
+'offset' is the start of the component data, based off the start of the
+header.
+The difference between the size of the header and offset is the size of the
+component name.
+
+Immediately following the header will be the name of the component,
+which will
+null terminated and 16 byte aligned.   The following picture shows the
+structure of the header:
+
+/--------\  <- start
+| Header |
+|--------|  <- sizeof(struct cbfs_file)
+| Name   |
+|--------|  <- 'offset'
+| Data   |
+| ...    |
+\--------/  <- start + 'offset' + 'len'
+
+== Searching Algorithm ==
+
+To locate a specific component in the ROM, one starts at the 'offset'
+specified in the CBFS master header.  For this example, the offset will
+be 0.
+
+ From that offset, the code should search for the magic string on the
+component, jumping 'align' bytes each time.  So, assuming that 'align' is
+16, the code will search for the string 'LARCHIVE' at offset 0, 16, 32, etc.
+If the offset ever exceeds the allowable range for CBFS components, then no
+component was found.
+
+Upon recognizing a component, the software then has to search for the
+specific name of the component.  This is accomplished by comparing the
+desired name with the string on the component located at
+offset + sizeof(struct cbfs_file).  If the string matches, then the
+component
+has been located, otherwise the software should add 'offset' + 'len' to
+the offset and resume the search for the magic value.
+
+== Data Types ==
+
+The 'type' member of struct cbfs_file is used to identify the content
+of the component data, and is used by coreboot and other
+run-time entities to make decisions about how to handle the data.
+
+There are three component types that are essential to coreboot, and so
+are defined here.
+
+=== Stages ===
+
+Stages are code loaded by coreboot during the boot process.  They are
+essential to a successful boot.   Stages are comprised of a single blob
+of binary data that is to be loaded into a particular location in memory
+and executed.   The uncompressed header contains information about how
+large the data is, and where it should be placed, and what additional memory
+needs to be cleared.
+
+Stages are assigned a component value of 0x10.  When coreboot sees this
+component type, it knows that it should pass the data to a sub-function
+that will process the stage.
+
+The following is the format of a stage component:
+
+/--------\
+| Header |
+|--------|
+| Binary |
+| ..     |
+\--------/
+
+The header is defined as:
+
+struct cbfs_stage {
+         unsigned int compression;
+         unsigned long long entry;
+         unsigned long long load;
+         unsigned int len;
+         unsigned int memlen;
+};
+
+'compression' is an integer defining how the data is compressed.  There
+are three compression types defined by this version of the standard:
+none (0x0), lzma (0x1), and nrv2b (0x02, deprecated), though additional
+types may be added assuming that coreboot understands how to handle the scheme.
+
+'entry' is a 64 bit value indicating the location where  the program
+counter should jump following the loading of the stage.  This should be
+an absolute physical memory address.
+
+'load' is a 64 bit value indicating where the subsequent data should be
+loaded.  This should be an absolute physical memory address.
+
+'len' is the length of the compressed data in the component.
+
+'memlen' is the amount of memory that will be used by the component when
+it is loaded.
+
+The component data will start immediately following the header.
+
+When coreboot loads a stage, it will first zero the memory from 'load' to
+'memlen'.  It will then decompress the component data according to the
+specified scheme and place it in memory starting at 'load'.  Following that,
+it will jump execution to the address specified by 'entry'.
+Some components are designed to execute directly from the ROM - coreboot
+knows which components must do that and will act accordingly.
+
+=== Payloads ===
+
+Payloads are loaded by coreboot following the boot process.
+
+Stages are assigned a component value of 0x20.  When coreboot sees this
+component type, it knows that it should pass the data to a sub-function
+that will process the payload.  Furthermore, other run time
+applications such as 'bayou' may easily index all available payloads
+on the system by searching for the payload type.
+
+
+The following is the format of a stage component:
+
+/-----------\
+| Header    |
+| Segment 1 |
+| Segment 2 |
+| ...       |
+|-----------|
+| Binary    |
+| ..        |
+\-----------/
+
+The header is as follows:
+
+struct cbfs_payload {
+         struct cbfs_payload_segment segments;
+}
+
+The header contains a number of segments corresponding to the segments
+that need to be loaded for the payload.
+
+The following is the structure of each segment header:
+
+struct cbfs_payload_segment {
+         unsigned int type;
+         unsigned int compression;
+         unsigned int offset;
+         unsigned long long load_addr;
+         unsigned int len;
+         unsigned int mem_len;
+};
+
+'type' is the type of segment, one of the following:
+
+PAYLOAD_SEGMENT_CODE   0x45444F43   The segment contains executable code
+PAYLOAD_SEGMENT_DATA   0x41544144   The segment contains data
+PAYLOAD_SEGMENT_BSS    0x20535342   The memory specified by the segment
+                                     should be zeroed
+PAYLOAD_SEGMENT_PARAMS 0x41524150   The segment contains information for
+                                     the payload
+PAYLOAD_SEGMENT_ENTRY  0x52544E45   The segment contains the entry point
+		  		    for the payload
+
+'compression' is the compression scheme for the segment.  Each segment can
+be independently compressed. There are three compression types defined by
+this version of the standard: none (0x0), lzma (0x1), and nrv2b
+(0x02, deprecated), though additional types may be added assuming that
+coreboot understands how to handle the scheme.
+
+'offset' is the address of the data within the component, starting from
+the component header.
+
+'load_addr' is a 64 bit value indicating where the segment should be placed
+in memory.
+
+'len' is a 32 bit value indicating the size of the segment within the
+component.
+
+'mem_len' is the size of the data when it is placed into memory.
+
+The data will located immediately following the last segment.
+
+=== Option ROMS ===
+
+The third specified component type will be Option ROMs.  Option ROMS will
+have component type '0x30'.  They will have no additional header, the
+uncompressed binary data will be located in the data portion of the
+component.
+
+=== NULL ===
+
+There is a 4th component type ,defined as NULL (0xFFFFFFFF).  This is
+the "don't care" component type.  This can be used when the component
+type is not necessary (such as when the name of the component is unique.
+i.e. option_table).  It is recommended that all components be assigned a
+unique type, but NULL can be used when the type does not matter.

firmware/coreboot/Documentation/codeflow.svg

@@ -0,0 +1,234 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="256px" height="640px" viewBox="0 0 256 640" enable-background="new 0 0 256 640" xml:space="preserve">
+<font horiz-adv-x="1000">
+<font-face font-family="MyriadPro-Regular" units-per-em="1000" underline-position="-100" underline-thickness="50"/>
+<missing-glyph horiz-adv-x="500" d="M0,0l500,0l0,700l-500,0M250,395l-170,255l340,0M280,350l170,255l0,-510M80,50l170,255l170,-255M50,605l170,-255l-170,-255z"/>
+<glyph unicode="A" horiz-adv-x="612" d="M424,212l72,-212l93,0l-230,674l-104,0l-230,-674l90,0l70,212M203,280l66,195C283,516 293,558 303,597l2,0C315,558 325,518 340,474l67,-194z"/>
+<glyph unicode="B" horiz-adv-x="542" d="M76,2C105,-2 151,-6 211,-6C321,-6 397,14 443,57C478,89 501,134 501,192C501,292 426,345 362,360l0,3C432,388 476,445 476,511C476,564 454,604 419,630C378,664 322,679 235,679C175,679 114,673 76,664M163,606C177,609 200,612 240,612C328,612 387,580 387,502C387,437 333,388 242,388l-79,0M163,323l72,0C330,323 409,284 409,193C409,95 326,62 236,62C205,62 181,63 163,66z"/>
+<glyph unicode="C" horiz-adv-x="580" d="M529,91C494,74 440,63 386,63C223,63 128,168 128,334C128,511 233,612 391,612C447,612 494,600 526,584l22,71C525,667 471,685 388,685C179,685 36,543 36,331C36,109 178,-11 368,-11C450,-11 515,5 546,21z"/>
+<glyph unicode="D" horiz-adv-x="666" d="M76,2C120,-3 171,-6 234,-6C365,-6 469,28 533,91C595,153 630,243 630,353C630,462 595,540 534,595C475,649 386,679 261,679C192,679 129,673 76,664M163,601C186,606 220,610 265,610C449,610 539,509 538,350C538,168 438,64 251,64C217,64 185,65 163,68z"/>
+<glyph unicode="E" horiz-adv-x="492" d="M424,388l-261,0l0,213l277,0l0,73l-365,0l0,-674l380,0l0,73l-292,0l0,243l261,0z"/>
+<glyph unicode="F" horiz-adv-x="487" d="M75,0l88,0l0,305l254,0l0,72l-254,0l0,224l275,0l0,73l-363,0z"/>
+<glyph unicode="H" horiz-adv-x="652" d="M75,674l0,-674l88,0l0,316l326,0l0,-316l88,0l0,674l-88,0l0,-282l-326,0l0,282z"/>
+<glyph unicode="I" horiz-adv-x="239" d="M75,674l0,-674l88,0l0,674z"/>
+<glyph unicode="L" horiz-adv-x="472" d="M75,0l376,0l0,73l-288,0l0,601l-88,0z"/>
+<glyph unicode="M" horiz-adv-x="804" d="M660,0l86,0l-42,674l-111,0l-120,-326C443,263 419,189 401,121l-2,0C381,191 359,265 331,348l-115,326l-111,0l-47,-674l83,0l18,289C165,391 170,503 172,587l2,0C193,507 219,421 251,325l110,-321l66,0l119,327C580,424 607,509 631,587l2,0C633,504 639,390 644,296z"/>
+<glyph unicode="N" horiz-adv-x="658" d="M158,0l0,288C158,400 157,481 152,566l3,1C188,494 233,417 280,342l214,-342l88,0l0,674l-82,0l0,-282C500,287 502,205 510,115l-3,-1C476,183 436,254 387,333l-215,341l-96,0l0,-674z"/>
+<glyph unicode="O" horiz-adv-x="689" d="M348,686C168,686 36,546 36,332C36,128 160,-11 339,-11C511,-11 652,113 652,344C652,545 533,686 348,686M345,615C490,615 560,475 560,340C560,187 482,60 344,60C206,60 128,189 128,334C128,481 200,615 345,615z"/>
+<glyph unicode="P" horiz-adv-x="532" d="M76,0l87,0l0,270C183,265 207,264 233,264C318,264 392,289 439,338C473,373 491,421 491,482C491,542 468,591 432,623C392,659 329,679 243,679C173,679 118,673 76,666M163,603C178,607 207,610 245,610C340,610 404,567 404,477C404,386 340,334 235,334C206,334 182,336 163,341z"/>
+<glyph unicode="Q" horiz-adv-x="689" d="M657,-26C600,-16 527,0 460,17l0,4C572,61 652,171 652,345C652,544 533,686 349,686C167,686 36,547 36,331C36,113 172,-5 333,-11C346,-11 359,-16 374,-21C452,-48 541,-75 632,-99M344,60C206,60 128,189 128,333C128,479 200,615 347,615C490,615 560,476 560,340C560,187 482,60 344,60z"/>
+<glyph unicode="R" horiz-adv-x="538" d="M76,0l87,0l0,292l82,0C324,289 361,254 381,161C399,77 414,20 425,0l90,0C501,26 485,91 463,185C447,255 416,303 365,321l0,3C435,348 491,407 491,495C491,548 471,594 438,624C397,661 336,679 243,679C184,679 120,673 76,665M163,604C178,608 207,611 249,611C341,611 404,573 404,486C404,409 345,358 252,358l-89,0z"/>
+<glyph unicode="S" horiz-adv-x="493" d="M42,33C78,9 149,-11 214,-11C373,-11 449,80 449,184C449,283 392,338 278,382C185,418 144,449 144,512C144,558 179,613 271,613C332,613 377,594 398,581l24,71C393,669 342,685 274,685C143,685 56,607 56,502C56,408 124,350 234,310C325,276 361,239 361,177C361,109 309,62 220,62C160,62 104,81 65,106z"/>
+<glyph unicode="T" horiz-adv-x="497" d="M204,0l88,0l0,600l206,0l0,74l-499,0l0,-74l205,0z"/>
+<glyph unicode="U" horiz-adv-x="647" d="M75,674l0,-397C75,67 179,-11 317,-11C463,-11 572,73 572,280l0,394l-88,0l0,-400C484,126 419,60 320,60C230,60 163,124 163,274l0,400z"/>
+<glyph unicode="a" horiz-adv-x="482" d="M413,297C413,393 377,494 229,494C168,494 109,477 69,452l20,-59C123,416 170,429 216,429C315,430 326,357 326,318l0,-10C139,309 35,245 35,128C35,58 85,-11 183,-11C252,-11 304,23 331,61l3,0l7,-61l79,0C415,33 413,74 413,116M328,163C328,155 327,145 324,135C310,94 269,54 205,54C161,54 123,80 123,138C123,232 232,249 328,247z"/>
+<glyph unicode="b" horiz-adv-x="569" d="M73,125C73,82 71,33 69,0l75,0l5,79l2,0C188,16 244,-11 314,-11C422,-11 532,75 532,248C532,394 448,494 327,494C249,494 193,460 162,406l-2,0l0,304l-87,0M160,280C160,294 162,306 165,317C183,383 239,425 298,425C393,425 443,342 443,245C443,134 389,59 296,59C232,59 180,101 164,162C161,172 160,183 160,194z"/>
+<glyph unicode="c" horiz-adv-x="448" d="M403,83C378,72 345,60 295,60C199,60 127,129 127,241C127,341 187,424 298,424C346,424 379,412 400,401l20,67C396,481 350,494 298,494C140,494 38,385 38,236C38,88 133,-11 279,-11C344,-11 395,6 418,17z"/>
+<glyph unicode="," horiz-adv-x="207" d="M78,-117C106,-70 150,41 174,126l-98,-10C65,43 38,-64 16,-124z"/>
+<glyph unicode="d" horiz-adv-x="564" d="M403,710l0,-289l-2,0C379,459 330,494 255,494C138,494 37,396 38,235C38,88 129,-11 246,-11C325,-11 383,30 409,84l3,0l4,-84l78,0C492,33 490,82 490,125l0,585M403,203C403,189 402,177 399,165C383,100 329,60 270,60C176,60 127,141 127,239C127,345 181,425 272,425C338,425 386,379 399,324C402,313 403,298 403,287z"/>
+<glyph unicode="e" horiz-adv-x="501" d="M462,226C464,236 465,249 465,267C465,356 424,494 265,494C124,494 38,380 38,234C38,88 127,-11 276,-11C353,-11 407,6 438,20l-16,63C390,69 351,58 288,58C199,58 124,107 122,226M123,289C130,350 168,431 258,431C357,431 381,344 380,289z"/>
+<glyph unicode="h" horiz-adv-x="555" d="M73,0l88,0l0,292C161,308 162,321 167,334C184,381 228,421 285,421C368,421 397,356 397,278l0,-278l88,0l0,288C485,454 381,494 316,494C283,494 252,485 226,470C199,455 177,432 163,407l-2,0l0,303l-88,0z"/>
+<glyph unicode="-" horiz-adv-x="307" d="M30,302l0,-64l247,0l0,64z"/>
+<glyph unicode="i" horiz-adv-x="234" d="M161,0l0,484l-88,0l0,-484M117,675C84,675 62,650 62,620C62,590 83,566 115,566C150,566 171,590 171,620C171,651 149,675 117,675z"/>
+<glyph unicode="k" horiz-adv-x="469" d="M160,710l-87,0l0,-710l87,0l0,182l45,50l166,-232l108,0l-213,285l186,199l-105,0l-143,-167C190,300 174,279 162,262l-2,0z"/>
+<glyph unicode="l" horiz-adv-x="236" d="M73,0l88,0l0,710l-88,0z"/>
+<glyph unicode="m" horiz-adv-x="834" d="M73,0l86,0l0,291C159,306 161,322 166,334C180,378 221,422 275,422C342,422 376,367 376,290l0,-290l86,0l0,299C462,315 465,330 469,343C485,385 523,422 574,422C644,422 679,367 679,273l0,-273l86,0l0,284C765,452 670,494 605,494C559,494 528,482 499,460C479,445 459,425 444,397l-2,0C421,454 371,494 306,494C225,494 180,451 153,405l-3,0l-4,79l-77,0C71,444 73,404 73,353z"/>
+<glyph unicode="n" horiz-adv-x="555" d="M73,0l88,0l0,291C161,306 163,321 167,332C183,381 228,422 285,422C368,422 397,357 397,279l0,-279l88,0l0,288C485,454 381,494 314,494C234,494 178,449 154,404l-2,0l-5,80l-78,0C72,444 73,404 73,353z"/>
+<glyph unicode="o" horiz-adv-x="549" d="M278,494C145,494 38,399 38,238C38,85 140,-11 270,-11C386,-11 511,67 511,246C511,393 417,494 278,494M276,428C380,428 421,325 421,243C421,134 358,55 274,55C188,55 128,135 128,241C128,332 173,428 276,428z"/>
+<glyph unicode="p" horiz-adv-x="569" d="M73,-198l87,0l0,263l2,0C191,17 247,-11 311,-11C425,-11 532,75 532,249C532,395 444,494 326,494C247,494 189,460 154,401l-2,0l-5,83l-78,0C71,438 73,388 73,326M160,281C160,292 163,305 166,316C182,382 239,424 299,424C392,424 443,341 443,245C443,134 389,58 296,58C233,58 180,100 164,161C161,172 160,184 160,197z"/>
+<glyph unicode="(" horiz-adv-x="284" d="M195,694C132,610 65,481 64,285C64,90 132,-38 195,-121l68,0C193,-21 138,106 138,284C138,466 190,595 263,694z"/>
+<glyph unicode=")" horiz-adv-x="284" d="M88,-121C151,-37 218,91 219,287C219,483 151,612 88,694l-68,0C91,594 145,467 145,287C145,107 90,-22 20,-121z"/>
+<glyph unicode="." horiz-adv-x="207" d="M110,-11C147,-11 171,16 171,52C171,89 147,115 112,115C77,115 52,88 52,52C52,16 76,-11 110,-11z"/>
+<glyph unicode="?" horiz-adv-x="406" d="M220,192l-2,25C215,268 231,313 275,365C323,422 361,471 361,539C361,615 309,686 194,686C141,686 85,670 51,646l24,-63C100,602 140,614 176,614C239,613 271,579 271,528C271,483 246,444 201,391C151,331 133,271 139,218l2,-26M178,-11C215,-11 238,16 238,51C238,88 215,114 179,114C145,114 120,88 120,51C120,16 144,-11 178,-11z"/>
+<glyph unicode="r" horiz-adv-x="327" d="M73,0l88,0l0,258C161,272 162,287 164,299C176,365 220,411 282,411C294,411 303,411 312,409l0,83C304,493 297,494 288,494C229,494 175,453 153,388l-3,0l-4,96l-77,0C72,439 73,390 73,333z"/>
+<glyph unicode="s" horiz-adv-x="396" d="M40,23C74,3 123,-11 176,-11C289,-11 356,49 356,135C356,207 312,249 229,280C166,305 138,323 138,363C138,399 166,429 218,429C263,429 298,412 317,400l21,64C312,481 269,494 220,494C117,494 53,430 53,352C53,294 94,247 182,215C246,191 271,169 271,127C271,86 241,55 178,55C134,55 88,73 61,89z"/>
+<glyph unicode="/" horiz-adv-x="343" d="M66,-39l280,725l-69,0l-278,-725z"/>
+<glyph unicode=" " horiz-adv-x="212"/>
+<glyph unicode="t" horiz-adv-x="331" d="M93,574l0,-90l-75,0l0,-67l75,0l0,-264C93,96 103,53 127,26C148,3 181,-11 222,-11C256,-11 283,-5 300,1l-4,67C283,64 269,62 245,62C196,62 179,96 179,156l0,261l126,0l0,67l-126,0l0,116z"/>
+<glyph unicode="2" horiz-adv-x="513" d="M460,0l0,73l-291,0l0,2l51,48C357,255 444,352 444,472C444,565 385,661 245,661C171,661 106,632 62,595l28,-62C120,558 169,588 228,588C325,588 356,527 356,461C356,363 280,279 114,121l-69,-67l0,-54z"/>
+<glyph unicode="u" horiz-adv-x="551" d="M478,484l-88,0l0,-296C390,171 387,155 382,143C366,103 325,62 266,62C187,62 158,125 158,217l0,267l-88,0l0,-283C70,32 161,-11 237,-11C323,-11 375,40 397,79l2,0l5,-79l78,0C479,38 478,82 478,133z"/>
+<glyph unicode="v" horiz-adv-x="481" d="M13,484l184,-484l84,0l190,484l-92,0l-94,-271C269,168 255,128 244,88l-3,0C231,128 218,168 202,213l-95,271z"/>
+<glyph unicode="x" horiz-adv-x="463" d="M16,484l164,-237l-172,-247l97,0l70,109C194,138 210,164 226,193l2,0C245,164 261,137 280,109l72,-109l99,0l-169,250l165,234l-96,0l-67,-103C267,355 251,330 235,302l-2,0C217,329 202,353 183,380l-69,104z"/>
+<glyph unicode="y" horiz-adv-x="471" d="M9,484l178,-446C192,27 194,20 194,15C194,10 191,3 187,-6C166,-51 137,-85 113,-104C87,-126 58,-140 36,-147l22,-73C80,-216 122,-201 166,-164C226,-111 269,-27 332,139l132,345l-93,0l-96,-284C263,165 253,128 244,99l-2,0C234,128 222,166 210,198l-105,286z"/>
+<glyph unicode="z" horiz-adv-x="428" d="M18,0l392,0l0,70l-282,0l0,2C150,96 169,121 190,148l216,281l0,55l-368,0l0,-70l262,0l0,-2C278,386 258,363 236,336l-218,-285z"/>
+</font>
+
+	<g>
+	<rect y="1.152" fill="#AAAAAA" stroke="#000000" width="256" height="36.887"/>
+	<text transform="matrix(1 0 0 1 27.7441 23.7046)" font-family="'MyriadPro-Regular'" font-size="14">Enter protected mode</text>
+</g>
+<g>
+	<rect y="45.642" fill="#AAAAAA" stroke="#000000" width="256" height="43.62"/>
+	<text transform="matrix(1 0 0 1 27.7441 71.5605)" font-family="'MyriadPro-Regular'" font-size="14">non-coherent HT enumeration</text>
+</g>
+<g>
+	<rect y="98.359" fill="#AAAAAA" stroke="#000000" width="256" height="60.15"/>
+	<text transform="matrix(1 0 0 1 27.7441 132.5435)" font-family="'MyriadPro-Regular'" font-size="14">coherent HT initialization</text>
+</g>
+<g>
+	<rect y="165.983" fill="#AAAAAA" stroke="#000000" width="256" height="68.421"/>
+	<text transform="matrix(1 0 0 1 27.7441 204.3022)" font-family="'MyriadPro-Regular'" font-size="14">Fallback / Normal?</text>
+</g>
+<g>
+	<rect y="243.893" fill="#AAAAAA" stroke="#000000" width="256" height="69.173"/>
+	<text transform="matrix(1 0 0 1 27.7441 282.5879)" font-family="'MyriadPro-Regular'" font-size="14">RAM initialization</text>
+</g>
+<g>
+	<rect y="410.747" fill="#AAAAAA" stroke="#000000" width="256" height="52.632"/>
+	<text transform="matrix(1 0 0 1 27.7441 432.7725)"><tspan x="0" y="0" font-family="'MyriadPro-Regular'" font-size="14">Create external tables (coreboot table,</tspan><tspan x="0" y="16.8" font-family="'MyriadPro-Regular'" font-size="14">ACPI, MP, PIRQ, DMI)</tspan></text>
+</g>
+<g>
+	<rect y="323.526" fill="#AAAAAA" stroke="#000000" width="256" height="77.443"/>
+	<text transform="matrix(1 0 0 1 27.7441 339.3154)"><tspan x="0" y="0" font-family="'MyriadPro-Regular'" font-size="14">Resource Allocation (PCI, PCIe, I2C, SIO, </tspan><tspan x="0" y="16.8" font-family="'MyriadPro-Regular'" font-size="14">CPU, mainboard...)</tspan></text>
+	<rect x="27.744" y="362.248" fill="#BCBCBC" width="228.256" height="38.722"/>
+</g>
+<g>
+	<rect y="473.781" fill="#AAAAAA" stroke="#000000" width="256" height="80.076"/>
+	<text transform="matrix(1 0 0 1 27.7441 497.4658)" font-family="'MyriadPro-Regular'" font-size="14">ELF / Payload Loader</text>
+	<rect x="27.744" y="507.993" fill="#BCBCBC" width="228.256" height="45.864"/>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,31.246 130.359,46.62 132.854,44.7
+									132.027,51.206 131.201,57.711 124.701,56.845 118.201,55.98 120.608,54.127 110.178,33.439								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,57.636 132.228,59.101 133.828,45.178 133.062,44.181							"/>
+							<polygon fill="#231F20" points="131.152,57.643 132.28,59.108 118.41,57.093 117.644,56.096							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,81.246 130.359,96.62 132.854,94.7
+									132.027,101.206 131.201,107.711 124.701,106.845 118.201,105.98 120.608,104.127 110.178,83.439								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,107.636 132.228,109.101 133.828,95.178 133.062,94.181							"/>
+							<polygon fill="#231F20" points="131.152,107.643 132.28,109.108 118.41,107.093 117.644,106.096							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,151.586 130.359,166.961 132.854,165.041
+									132.027,171.546 131.201,178.052 124.701,177.186 118.201,176.321 120.608,174.468 110.178,153.78								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,177.977 132.228,179.442 133.828,165.519 133.062,164.522							"/>
+							<polygon fill="#231F20" points="131.152,177.983 132.28,179.449 118.41,177.434 117.644,176.437							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,227.013 130.359,242.387 132.854,240.467
+									132.027,246.973 131.201,253.478 124.701,252.612 118.201,251.747 120.608,249.894 110.178,229.207								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,253.403 132.228,254.868 133.828,240.945 133.062,239.948							"/>
+							<polygon fill="#231F20" points="131.152,253.41 132.28,254.875 118.41,252.86 117.644,251.863							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,303.013 130.359,318.388 132.854,316.468
+									132.027,322.973 131.201,329.479 124.701,328.612 118.201,327.747 120.607,325.895 110.178,305.207								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,329.404 132.228,330.868 133.829,316.945 133.062,315.948							"/>
+							<polygon fill="#231F20" points="131.152,329.41 132.28,330.876 118.41,328.86 117.643,327.864							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,395.872 130.359,411.247 132.854,409.327
+									132.027,415.833 131.201,422.338 124.701,421.473 118.201,420.606 120.608,418.754 110.178,398.066								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,422.264 132.228,423.728 133.828,409.805 133.062,408.808							"/>
+							<polygon fill="#231F20" points="131.152,422.27 132.28,423.735 118.41,421.72 117.644,420.724							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,452.152 130.359,467.528 132.854,465.608
+									132.027,472.113 131.201,478.619 124.701,477.753 118.201,476.888 120.607,475.035 110.178,454.347								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,478.545 132.228,480.009 133.829,466.085 133.062,465.089							"/>
+							<polygon fill="#231F20" points="131.152,478.551 132.28,480.017 118.41,478.001 117.643,477.004							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<text transform="matrix(1 0 0 1 59.3232 385.7627)" font-family="'MyriadPro-Regular'" font-size="14">Drivers</text>
+<text transform="matrix(1 0 0 1 55.564 535.3789)" font-family="'MyriadPro-Regular'" font-size="14">Linux, FILO, SeaBIOS, ...</text>
+</svg>

firmware/coreboot/Documentation/conf.py

@@ -0,0 +1,190 @@
+# -*- coding: utf-8 -*-
+import subprocess
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+source_suffix = ['.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'coreboot'
+copyright = u'CC-by 4.0 the coreboot project'
+author = u'the coreboot project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The full version, including alpha/beta/rc tags.
+release = subprocess.check_output(('git', 'describe'))
+# The short X.Y version.
+version = release.split("-")[0]
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+# keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+html_context = {
+      'css_files': [
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+      ],
+}
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'corebootdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+     # The paper size ('letterpaper' or 'a4paper').
+     #
+     # 'papersize': 'letterpaper',
+
+     # The font size ('10pt', '11pt' or '12pt').
+     #
+     # 'pointsize': '10pt',
+
+     # Additional stuff for the LaTeX preamble.
+     #
+     # 'preamble': '',
+
+     # Latex figure (float) alignment
+     #
+     # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'coreboot.tex', u'coreboot Documentation',
+     u'the coreboot project', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#
+# latex_use_parts = False
+
+# If true, show page references after internal links.
+#
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#
+# latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#
+# latex_appendices = []
+
+# If false, will not define \strong, \code,	itleref, \crossref ... but only
+# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
+# packages.
+#
+# latex_keep_old_macro_names = True
+
+# If false, no module index is generated.
+#
+# latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'coreboot', u'coreboot Documentation',
+     [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#
+# man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'coreboot', u'coreboot Documentation',
+     author, 'coreboot', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+source_parsers = {
+    '.md': 'recommonmark.parser.CommonMarkParser',
+}
+
+# Documents to append as an appendix to all manuals.
+#
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+#
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#
+# texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#
+# texinfo_no_detailmenu = False
+
+enable_auto_toc_tree = True
+
+
+def setup(app):
+    from recommonmark.transform import AutoStructify
+    app.add_config_value('recommonmark_config', {
+        'enable_auto_toc_tree': True,
+        'enable_auto_doc_ref': True,
+        'enable_eval_rst': True,
+        'url_resolver': lambda url: '/' + url
+    }, True)
+    app.add_transform(AutoStructify)

firmware/coreboot/Documentation/corebootBuildingGuide.tex

@@ -0,0 +1,671 @@
+%
+% This document is released under the GPL
+% Initially written by Stefan Reinauer, <stepan@coresystems.de>
+%
+
+\documentclass[titlepage,12pt]{article}
+\usepackage{a4}
+\usepackage{graphicx}
+\usepackage{epsfig}
+\usepackage{epstopdf}
+\usepackage{url}
+\usepackage{color}
+% \usepackage{geometry}
+\usepackage[pdftex]{hyperref}
+% \usepackage{makeidx}
+% \makeindex
+% \geometry{left=2cm,right=2cm,top=2cm,bottom=2cm}
+
+\hypersetup{
+    urlbordercolor={1 1 1},
+    menubordercolor={1 1 1},
+    linkbordercolor={1 1 1},
+    colorlinks=false,
+    % pdfpagemode=None,  % PDF-Viewer starts without TOC
+    % pdfstartview=FitH,
+    pdftitle={coreboot Porting Guide},
+    pdfauthor={Zheng Bao},
+    pdfsubject={coreboot configuration and build process},
+    pdfkeywords={coreboot, AMD, configuration, Build}
+}
+
+\setlength{\parindent}{0pt}
+\setlength{\hoffset}{0pt}
+
+\title{coreboot from Scratch}
+\author{Stefan Reinauer $<$stepan@coresystems.de$>$\and Zheng Bao $<$zheng.bao@amd.com$>$}
+\date{Dec 4th, 2013}
+
+\begin{document}
+
+\maketitle
+
+\thispagestyle{empty}
+
+\tableofcontents
+
+\newpage
+
+\section{What is coreboot}
+coreboot aims to replace the normal BIOS found on x86, AMD64, PPC,
+Alpha, and other machines with a Linux kernel that can boot Linux from a cold
+start. The startup code of an average coreboot port is about 500 lines of
+assembly and 5000 lines of C. It executes 16 instructions to get into 32bit
+protected mode and then performs DRAM and other hardware initializations
+required before Linux can take over.
+
+The projects primary motivation initially was maintenance of large
+clusters. Not surprisingly interest and contributions have come from
+people with varying backgrounds.  Nowadays a large and growing number of
+Systems can be booted with coreboot, including embedded systems,
+Desktop PCs and Servers.
+
+This document is used to build, modify, and port the coreboot code
+base on the AMD platform.
+
+
+\section{Changes}
+
+ \begin{itemize}
+ \item 2013/12/20 Add Git, Gerrit, toolchains building.
+ \item 2009/04/19 replace LinuxBIOS with coreboot
+ \item 2004/06/02 url and language fixes from Ken Fuchs $<$kfuchs@winternet.com$>$
+ \item 2004/02/10 ACPI and option ROM updates
+ \item 2003/11/18 initial release
+ \end{itemize}
+
+%
+% Build Requirements
+%
+
+\section{Build Requirements}
+To build coreboot for AMD64 from the sources you need a recent Linux.
+SUSE Linux 11.2, CentOS release 6.3, Fedora Core 16, Cygwin, FreeBSD,
+NetBSD are known to work fine.
+
+To build the toolchain, you need following host compilers:
+
+ \begin{itemize}
+ \item GNUtar
+ \item GNUpatch
+ \item GNUmake
+ \item GCC
+ \item binutils
+ \item bison
+ \item flex
+ \item m4
+ \item wget
+ \end{itemize}
+
+Besides the tools above, after the toolchains are built, you also need the following
+tools to build the source.
+
+ \begin{itemize}
+ \item git: Get the source code from repository
+ \item libncurses-dev (or ncursesw, ncurses, curses, pdcursesw, pdcurses): for menuconfig
+ \item python: Optional for gdb.
+ \item perl: Optional for gdb.
+ \end{itemize}
+
+%
+% Getting coreboot
+%
+
+\section{Getting coreboot}
+The latest coreboot sources are available via GIT.
+For users who doesn't need to change and commit the code:
+{ \small
+\begin{verbatim}
+$ git clone https://review.coreboot.org/coreboot
+\end{verbatim}
+}
+For developers, you need to get a gerrit account which you can register
+at \url{https://review.coreboot.org}. Please refer section ~\ref{sec:gerrit}
+{ \small
+\begin{verbatim}
+$ git clone ssh://<username>@review.coreboot.org:29418/coreboot
+$ git clone https://[<username>:<password>@]review.coreboot.org/coreboot.git
+\end{verbatim}
+}
+
+Checks out a sub-repository in the 3rdparty directory.
+{ \small
+\begin{verbatim}
+$ git submodule update --init --checkout
+\end{verbatim}
+}
+
+%
+% Building the toolchain
+%
+
+\section{Building the toolchain}
+coreboot recommends and guarantees the toolchain integrated with coreboot.
+Linux distributions usually modify their compilers in ways incompatible with coreboot.
+
+{ \small
+\begin{verbatim}
+$ cd coreboot
+$ make crossgcc
+\end{verbatim}
+}
+
+or
+
+{ \small
+\begin{verbatim}
+$ cd util/crossgcc
+$ buildgcc
+\end{verbatim}
+}
+
+The buildgcc will try to get packages from website. You need to make sure you can
+get access the internet. Or you can get the source.tar.gz and put it in util/crossgcc/tarballs.
+
+{ \small
+\textcolor{blue} {Welcome to the} \textcolor{red} {coreboot} \textcolor{blue} {cross toolchain builder v1.23 (September 20th, 2013)}
+
+Target arch is now i386-elf
+
+Will skip GDB ... ok
+
+Downloading tar balls ...
+
+ * gmp-5.1.2.tar.bz2 (cached)
+
+ * mpfr-3.1.2.tar.bz2 (cached)
+
+ * mpc-1.0.1.tar.gz (cached)
+
+ * libelf-0.8.13.tar.gz (cached)
+
+ * gcc-4.7.3.tar.bz2 (cached)
+
+ * binutils-2.23.2.tar.bz2 (cached)
+
+ * acpica-unix-20130626.tar.gz (cached)
+
+Downloaded tar balls ... \textcolor {green}{ok}
+
+Unpacking and patching ...
+
+ * gmp-5.1.2.tar.bz2
+
+ * mpfr-3.1.2.tar.bz2
+
+ * mpc-1.0.1.tar.gz
+
+ * libelf-0.8.13.tar.gz
+
+ * gcc-4.7.3.tar.bz2
+
+ * binutils-2.23.2.tar.bz2
+
+   o binutils-2.23.2\_arv7a.patch
+
+   o binutils-2.23.2\_no-bfd-doc.patch
+
+ * acpica-unix-20130626.tar.gz
+
+Unpacked and patched ... \textcolor {green}{ok}
+
+Building GMP 5.1.2 ... \textcolor {green}{ok}
+
+Building MPFR 3.1.2 ... \textcolor {green}{ok}
+
+Building MPC 1.0.1 ... \textcolor {green}{ok}
+
+Building libelf 0.8.13 ... \textcolor {green}{ok}
+
+Building binutils 2.23.2 ... \textcolor {green}{ok}
+
+Building GCC 4.7.3 ...  ok
+
+Skipping Expat (Python scripting not enabled)
+
+Skipping Python (Python scripting not enabled)
+
+Skipping GDB (GDB support not enabled)
+
+Building IASL 20130626 ... \textcolor {green}{ok}
+
+Cleaning up... \textcolor {green}{ok}
+
+\textcolor {green}{You can now run your i386-elf cross toolchain from /home/baozheng/x86/coreboot-gerrit/util/crossgcc/xgcc.}
+}
+If you are lucky, you can get toolchains located in util/crossgcc/xgcc.
+
+%
+% Build coreboot
+%
+
+\section{Building coreboot}
+\subsection{Build main module of coreboot}
+{ \small
+\begin{verbatim}
+$ cd coreboot
+$ make menuconfig
+.config - coreboot v4.0-4895-gc5025a4-dirty Configuration
++------------------------ coreboot Configuration -------------------------+
+|  Arrow keys navigate the menu.  <Enter> selects submenus --->.          |
+|  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, |
+|  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </> |
+|  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       |
+| +---------------------------------------------------------------------+ |
+| |        General setup  --->                                          | |
+| |        Mainboard  --->                                              | |
+| |        Architecture (x86)  --->                                     | |
+| |        Chipset  --->                                                | |
+| |        Devices  --->                                                | |
+| |        VGA BIOS  --->                                               | |
+| |        Display  --->                                                | |
+| |        PXE ROM  --->                                                | |
+| |        Generic Drivers  --->                                        | |
+| |        Console  --->                                                | |
+| |    [ ] Relocatable Modules                                          | |
+| |        System tables  --->                                          | |
+| |        Payload  --->                                                | |
+| |        Debugging  --->                                              | |
+| |    ---                                                              | |
+| +----v(+)-------------------------------------------------------------+ |
++-------------------------------------------------------------------------+
+|                    <Select>    < Exit >    < Help >                     |
++-------------------------------------------------------------------------
+\end{verbatim}
+}
+Select Mainboard -$>$ Mainboard Vendor -$>$ AMD
+                 -$>$ Mainboard Model  -$>$ Olive Hill
+
+Then save, exit and run make.
+
+{ \small
+\begin{verbatim}
+$ make
+\end{verbatim}
+}
+The built image, coreboot.rom, is located at folder build.
+
+\section{Programming coreboot to flash memory}
+The image resulting from a coreboot build can be directly programmed to
+a flash device, either using an external flash programmers, e.g., Dediprog SF100, or by using the
+Linux flash utility, flashrom.
+
+
+\subsection{Add modules and payload}
+
+\subsubsection{VGA BIOS}
+There is a big Chance that you need to get a VGA BIOS.
+{ \small
+\begin{verbatim}
+.config - coreboot v4.0 Configuration
+------------------------------------------------------------------------------
++-------------------------------- VGA BIOS --------------------------------+
+|  Arrow keys navigate the menu.  <Enter> selects submenus --->.           |
+|  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes,  |
+|  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </>  |
+|  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < > module |
+| +----------------------------------------------------------------------+ |
+| |    [*] Add a VGA BIOS image                                          | |
+| |    (vgabios.bin) VGA BIOS path and filename                          | |
+| |    (1002,1306) VGA device PCI IDs                                    | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| +----------------------------------------------------------------------+ |
++--------------------------------------------------------------------------+
+|                     <Select>    < Exit >    < Help >                     |
++--------------------------------------------------------------------------+
+\end{verbatim}
+}
+Select VGA BIOS. ``The VGA device PCI IDs'' should be the same as your device. Get the
+Option ROM from Vendor's website.
+
+\subsubsection{Payload}
+coreboot in itself is "only" minimal code for initializing a mainboard
+with peripherals. After the initialization, it jumps to a payload.
+
+Currently, SeaBIOS is the most widely used payload. The best way to integrate SeaBIOS
+is setting it in menuconfig.
+{ \small
+\begin{verbatim}
++------------------------------- Payload ---------------------------------+
+|  Arrow keys navigate the menu.  <Enter> selects submenus --->.           |
+|  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes,  |
+|  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </>  |
+|  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < > module |
+| +----------------------------------------------------------------------+ |
+| |        Add a payload (SeaBIOS)  --->                                 | |
+| |        SeaBIOS version (1.7.2.1)  --->                               | |
+| |    [*] Use LZMA compression for payloads (NEW)                       | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| +----------------------------------------------------------------------+ |
++--------------------------------------------------------------------------+
+|                     <Select>    < Exit >    < Help >                     |
++--------------------------------------------------------------------------+
+\end{verbatim}
+The script in Makefile will automatically checkout, config, build the SeaBIOS source,
+and integrat the binary into the final image.
+
+%
+% Working with Git
+%
+
+\section{Working with Git}
+\subsection{Configuration of Git}
+Inside the checkout you should install a commit-msg hook that adds a
+Change-Id into commit messages, which uniquely identifies the logical
+change in Gerrit even across multiple iterations of the commit. The
+hook only needs to be installed once per clone, and installation can
+be done with:
+{ \small
+\begin{verbatim}
+$ cd coreboot
+$ cp ./util/gitconfig/* .git/hooks
+\end{verbatim}
+}
+configure your name and email in git.
+{ \small
+\begin{verbatim}
+$ git config --global user.name "Your Name Comes Here"
+$ git config --global user.email your.email@example.com'
+\end{verbatim}
+}
+The name~\ref{user name} and email~\ref{Contact Information} should be the same the settings in gerrit.
+Otherwise you can not push you code to community.
+
+Then run the following command once, to tell git that by default you
+want to submit all commits in the currently checked-out branch for
+review on gerrit:
+{ \small
+\begin{verbatim}
+$ git config remote.origin.push HEAD:refs/for/master
+\end{verbatim}
+}
+
+The above configurations for git has been integrated into Makefile. You can run
+{ \small
+\begin{verbatim}
+$ make gitconfig
+\end{verbatim}
+}
+
+\subsection{Work flow}
+
+It is recommended that you make a new branch when you start to work, not pushing changes to master.
+{ \small
+\begin{verbatim}
+$ git checkout master -b mybranch
+\end{verbatim}
+}
+After you have done your changes, run:
+{ \small
+\begin{verbatim}
+$ git add file_need_to_submit.c
+$ git commit -m "my first change."
+\end{verbatim}
+}
+
+% Does anyone have a better word to describe the philosophy of splitting changes to patches?
+You need to realize that the changes you have made should be well divided into
+several commits. Each of them has one and only one meaning. You could use git rebase -i to
+split, squash, remove, rewrite you comment.
+
+Here is an example of a well-formatted commit message:
+
+{ \small
+\begin{verbatim}
+examplecomponent: Refactor duplicated setup into a function
+
+Setting up the demo device correctly requires the exact same register
+values to be written into each of the PCI device functions. Moving the
+writes into a function allows also otherexamplecomponent to use them.
+
+Signed-off-by: Joe Hacker <joe@hacker.email>
+\end{verbatim}
+}
+
+Then you can push the code.
+{ \small
+\begin{verbatim}
+$ git push
+\end{verbatim}
+}
+
+You can go to the ~\ref{sec:gerrit} gerrit to see if your changes is successfully pushed.
+
+Often it might happen that the patch you sent for approval is not good
+enough from the first attempt. Gerrit and git make it easy to track
+patch evolution during the review process until patches meet our
+quality standards and are ready for approval.
+
+You can easily modify a patch sent to gerrit by you or even by someone
+else. Just apply it locally using one of the possible ways to do it,
+make a new local commit that fixes the issues reported by the
+reviewers, then rebase the change by preserving the same Change-ID. We
+recommend you to use the git rebase command in interactive mode,
+
+Once your patch gets a +2 comment, your patch can be merged (cherry-pick, actually) to origin/master.
+
+%
+% Working with Gerrit
+%
+
+\section{Working with Gerrit}
+\label{sec:gerrit}
+If you are a coreboot user, not planning to contribute, you can skip this section.
+\subsection{Get gerrit account}
+You need to get an OpenID first. Currently Google account give you an OpenID. It means, if you have a gmail account, you have an OpenID. You can try to signed in.
+click \url{https://review.coreboot.org}
+
+%\includegraphics[width=6.00in,height=1.00in]{gerrit_signin.png}
+{ \small
+\begin{verbatim}
++-----------------------------------------------------------+
+|All    Projects  Documentation           Register  Sign In |
+|Open Merged   Abandoned                                    |
+|Search for status:open                                     |
++-----------------------------------------------------------+
+|Subject      Status   Owner  Project  Branch Updated CR V  |
+|cpu: Rename..      Alexandru coreboot master 1:20 PM +1    |
+|cpu: Only a..      Alexandru coreboot master 1:17 PM    X  |
+|arch/x86: D..      Alexandru coreboot master 1:09 PM       |
+|                                                           |
+|                                                  Next ->  |
+|Press '?' to view keyboard shortcuts | Powered by Gerrit   |
++-----------------------------------------------------------+
+\end{verbatim}
+}
+Click ``Sign In'', You will get
+
+%\includegraphics[width=6.00in,height=4.00in]{openid.png}
+
+You will be redirected to Google to get logging in.
+
+% \includegraphics[width=6.00in,height=1.50in]{login.png}
+{ \small
+\begin{verbatim}
+Sign In to Gerrit Code Review at review.coreboot.org
++--------------------------------------------------+
++--------------------------------------------------+
+[] Remember me
+Sign In Cancel
+Sign in with a Google Account
+Sign in with a Yahoo! ID
+What is OpenID?
+
+OpenID provides secure single-sign-on, without revealing your passwords to this website.
+
+There are many OpenID providers available. You may already be member of one!
+
+Get OpenID
+\end{verbatim}
+}
+
+\subsection{Configure account}
+Click the dropdown button near the user name and click ``Settings''
+
+% \includegraphics[width=6.00in,height=4.00in]{settings}
+% \epsfig{figure=keystroke_left}
+% \epstopdf {file=settings.eps}
+% \epsfig{file=settings.eps}
+
+\label{user name} In ``profile'' section, type the user name for git. This probably can be changed only once.
+{ \small
+\begin{verbatim}
+Profile               Username      zbao
+Preferences           Full Name     Zheng Bao
+Watched Projects      Email Address zheng.bao@amd.com
+Contact Information   Registered    Jun 28, 2011 4:33 PM
+SSH Public Keys       Account ID    1000034
+HTTP Password
+Identities
+Groups
+\end{verbatim}
+}
+
+\label{Contact Information} In ``Contact Information'', enter you full name and your Email, which should be configured in your .gitconfig
+{ \small
+\begin{verbatim}
+      Full Name  __________________________________
+Preferred Email  ______________   Registered Email
+
+Save Changes
+\end{verbatim}
+}
+
+In ``SSH Public Keys'' section, upload your public key.
+{ \small
+\begin{verbatim}
+Status  Algorithm   Key Comment
+
+Delete
+Add SSH Public Key
+ > How to Generate an SSH Key
++--------------------------+
+|                          |
+|                          |
+|                          |
+|                          |
+|                          |
+|                          |
+|                          |
+|                          |
+|                          |
++--------------------------+
+clear       Add  Close
+\end{verbatim}
+}
+
+Click ``Add Key ...''
+Go back to you linux command line and type:
+{ \small
+\begin{verbatim}
+$ ssh-keygen
+Generating public/private rsa key pair.
+Enter file in which to save the key (/home/zhengbao/.ssh/id_rsa):
+Enter passphrase (empty for no passphrase):
+Enter same passphrase again:
+Your identification has been saved in /home/zhengbao/.ssh/id_rsa.
+Your public key has been saved in /home/zhengbao/.ssh/id_rsa.pub.
+The key fingerprint is:
+xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx zhengb@host.domain
+The key's randomart image is:
++--[ RSA 2048]----+
+|                 |
+|                 |
+|                 |
+|                 |
+|                 |
+|                 |
+|                 |
+|                 |
+|                 |
++-----------------+
+\end{verbatim}
+}
+The data in ~/.ssh/id\_rsa.pub is your public key. Copy them to the box in the page of ``SSH Public Keys'' and click add.
+
+In ``HTTP Password'' section, click button ``Generate Password''. You will get the password for http checkout.
+{ \small
+\begin{verbatim}
+Username    XXX
+Password    XXXXXXXXXXXX
+
+Generate Password   Clear Password
+
+\end{verbatim}
+}
+
+\subsection{Reviewing Changes}
+For each listed changes in Gerrit, you can review, comment, evaluate,
+cherry-pick, and even re-submit them. For you own patches, only you can
+abandon them. Click in the file and commit message, you can add in-line comment.
+
+%
+% 14 Glossary
+%
+
+\section{Glossary}
+\begin{itemize}
+\item payload
+
+coreboot only cares about low level machine initialization, but also has
+very simple mechanisms to boot a file either from FLASHROM or IDE. That
+file, possibly a Linux Kernel, a boot loader or Etherboot, are called
+payload, since it is the first software executed that does not cope with
+pure initialization.
+
+\item flash device
+
+Flash devices are commonly used in all different computers since unlike
+ROMs they can be electronically erased and reprogrammed.
+
+\item Gerrit
+
+Gerrit is a web based code review system, facilitating online code
+reviews for projects using the Git version control system.
+
+Gerrit makes reviews easier by showing changes in a side-by-side
+display, and allowing inline comments to be added by any reviewer.
+
+Gerrit simplifies Git based project maintainership by permitting any
+authorized user to submit changes to the master Git repository, rather
+than requiring all approved changes to be merged in by hand by the
+project maintainer. This functionality enables a more centralized
+usage of Git.
+
+\end{itemize}
+
+\newpage
+
+%
+% 14 Bibliography
+%
+
+\section{Bibliography}
+\subsection{Additional Papers on coreboot}
+
+\begin{itemize}
+ \item
+ \textit{\url{https://www.coreboot.org/Documentation}}
+\end{itemize}
+
+\subsection {Links}
+
+\begin{itemize}
+ \item Etherboot: \textit{\url{http://www.etherboot.org/}}
+ \item OpenBIOS: \textit{\url{http://www.openbios.org/}}
+ \item Flashrom: \textit{\url{http://www.flashrom.org/}}
+ \item Seabios: \textit{\url{http://www.seabios.org/}}
+\end{itemize}
+
+
+\end{document}

firmware/coreboot/Documentation/doxygen/Doxyfile.coreboot_platform

@@ -0,0 +1,319 @@
+# Doxyfile 1.8.11
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "coreboot for $(DOXYGEN_PLATFORM)"
+PROJECT_NUMBER         =
+PROJECT_BRIEF          = "coreboot is an Open Source project aimed at replacing the proprietary BIOS found in most computers."
+PROJECT_LOGO           = Documentation/coreboot_logo.png
+OUTPUT_DIRECTORY       = $(DOXYGEN_OUTPUT_DIR)
+CREATE_SUBDIRS         = YES
+ALLOW_UNICODE_NAMES    = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       =
+ALWAYS_DETAILED_SEC    = YES
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        =
+STRIP_FROM_INC_PATH    =
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                =
+TCL_SUBST              =
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+EXTENSION_MAPPING      =
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = NO
+LOOKUP_CACHE_SIZE      = 0
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_PACKAGE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       =
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    =
+LAYOUT_FILE            =
+CITE_BIB_FILES         =
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = YES
+WARN_AS_ERROR          = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           =
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = $(DOXYFILES)
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          =
+RECURSIVE              = NO
+EXCLUDE                =
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       =
+EXCLUDE_SYMBOLS        =
+EXAMPLE_PATH           =
+EXAMPLE_PATTERNS       =
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             =
+INPUT_FILTER           =
+FILTER_PATTERNS        =
+FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE =
+#---------------------------------------------------------------------------
+# Configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = NO
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+CLANG_ASSISTED_PARSING = NO
+CLANG_OPTIONS          =
+#---------------------------------------------------------------------------
+# Configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = YES
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          =
+#---------------------------------------------------------------------------
+# Configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            =
+HTML_FOOTER            =
+HTML_STYLESHEET        =
+HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_FILES       =
+HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_GAMMA  = 80
+HTML_TIMESTAMP         = NO
+HTML_DYNAMIC_SECTIONS  = NO
+HTML_INDEX_NUM_ENTRIES = 100
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen documentation"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
+DOCSET_PUBLISHER_NAME  = Publisher
+GENERATE_HTMLHELP      = NO
+CHM_FILE               =
+HHC_LOCATION           =
+GENERATE_CHI           = NO
+CHM_INDEX_ENCODING     =
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+GENERATE_QHP           = NO
+QCH_FILE               =
+QHP_NAMESPACE          = org.doxygen.Project
+QHP_VIRTUAL_FOLDER     = doc
+QHP_CUST_FILTER_NAME   =
+QHP_CUST_FILTER_ATTRS  =
+QHP_SECT_FILTER_ATTRS  =
+QHG_LOCATION           =
+GENERATE_ECLIPSEHELP   = NO
+ECLIPSE_DOC_ID         = org.doxygen.Project
+DISABLE_INDEX          = NO
+GENERATE_TREEVIEW      = YES
+ENUM_VALUES_PER_LINE   = 4
+TREEVIEW_WIDTH         = 250
+EXT_LINKS_IN_WINDOW    = NO
+FORMULA_FONTSIZE       = 10
+FORMULA_TRANSPARENT    = YES
+USE_MATHJAX            = NO
+MATHJAX_FORMAT         = HTML-CSS
+MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
+MATHJAX_EXTENSIONS     =
+MATHJAX_CODEFILE       =
+SEARCHENGINE           = YES
+SERVER_BASED_SEARCH    = NO
+EXTERNAL_SEARCH        = NO
+SEARCHENGINE_URL       =
+SEARCHDATA_FILE        = searchdata.xml
+EXTERNAL_SEARCH_ID     =
+EXTRA_SEARCH_MAPPINGS  =
+#---------------------------------------------------------------------------
+# Configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         =
+LATEX_HEADER           =
+LATEX_FOOTER           =
+LATEX_EXTRA_STYLESHEET =
+LATEX_EXTRA_FILES      =
+PDF_HYPERLINKS         = NO
+USE_PDFLATEX           = NO
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+LATEX_SOURCE_CODE      = NO
+LATEX_BIB_STYLE        = plain
+LATEX_TIMESTAMP        = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    =
+RTF_EXTENSIONS_FILE    =
+RTF_SOURCE_CODE        = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_SUBDIR             =
+MAN_LINKS              = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the DOCBOOK output
+#---------------------------------------------------------------------------
+GENERATE_DOCBOOK       = NO
+DOCBOOK_OUTPUT         = docbook
+DOCBOOK_PROGRAMLISTING = NO
+#---------------------------------------------------------------------------
+# Configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           =
+INCLUDE_FILE_PATTERNS  =
+PREDEFINED             = __attribute__(x)=
+EXPAND_AS_DEFINED      =
+SKIP_FUNCTION_MACROS   = YES
+#---------------------------------------------------------------------------
+# Configuration options related to external references
+#---------------------------------------------------------------------------
+TAGFILES               =
+GENERATE_TAGFILE       =
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+EXTERNAL_PAGES         = YES
+PERL_PATH              = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = YES
+MSCGEN_PATH            =
+DIA_PATH               =
+HIDE_UNDOC_RELATIONS   = NO
+HAVE_DOT               = NO
+DOT_NUM_THREADS        = 0
+DOT_FONTNAME           = Helvetica
+DOT_FONTSIZE           = 10
+DOT_FONTPATH           =
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = YES
+UML_LIMIT_NUM_FIELDS   = 10
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = YES
+CALLER_GRAPH           = YES
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+INTERACTIVE_SVG        = NO
+DOT_PATH               =
+DOTFILE_DIRS           =
+MSCFILE_DIRS           =
+DIAFILE_DIRS           =
+PLANTUML_JAR_PATH      =
+PLANTUML_INCLUDE_PATH  =
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = YES
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES

firmware/coreboot/Documentation/endverbatim.tex

@@ -0,0 +1 @@
+\end{verbatim}

firmware/coreboot/Documentation/gcov.txt

@@ -0,0 +1,227 @@
+This patch contains our local modifications for gcov-io.h and libgcov.c.
+The file gcov-iov.h is taken from a gcc build (produced at compile
+time). The file gcov-io.c is unchanged.
+
+--- gcc-4.7.2/gcc/gcov-io.h	2011-12-04 10:27:19.000000000 -0800
++++ coreboot/src/lib/gcov-io.h	2013-01-12 16:45:57.000000000 -0800
+@@ -163,6 +163,24 @@
+ #ifndef GCC_GCOV_IO_H
+ #define GCC_GCOV_IO_H
+ 
++#ifdef __COREBOOT__
++#define GCOV_LINKAGE /* nothing */
++/* We need the definitions for
++    BITS_PER_UNIT and
++    LONG_LONG_TYPE_SIZE
++   They are defined in gcc/defaults.h and gcc/config/<arch_depend_files>
++   (like, gcc/config/i386/i386.h). And it can be overridden by setting
++   in build scripts. Here I hardcoded the value for x86. */
++#define BITS_PER_UNIT 8
++#define LONG_LONG_TYPE_SIZE 64
++
++/* There are many gcc_assertions. Set the vaule to 1 if we want a warning
++   message if the assertion fails.  */
++#ifndef ENABLE_ASSERT_CHECKING
++#define ENABLE_ASSERT_CHECKING 1
++#endif
++#endif /* __COREBOOT__ */
++
+ #if IN_LIBGCOV
+ /* About the target */
+ 
+@@ -232,7 +250,9 @@
+    is not also used in a DSO.  */
+ #if IN_LIBGCOV
+ 
++#ifndef __COREBOOT__
+ #include "tconfig.h"
++#endif /* __COREBOOT__ */
+ 
+ #define gcov_var __gcov_var
+ #define gcov_open __gcov_open
+@@ -455,8 +475,10 @@
+ /* Register a new object file module.  */
+ extern void __gcov_init (struct gcov_info *) ATTRIBUTE_HIDDEN;
+ 
++#ifndef __COREBOOT__
+ /* Called before fork, to avoid double counting.  */
+ extern void __gcov_flush (void) ATTRIBUTE_HIDDEN;
++#endif
+ 
+ /* The merge function that just sums the counters.  */
+ extern void __gcov_merge_add (gcov_type *, unsigned) ATTRIBUTE_HIDDEN;
+--- gcc-4.7.2/libgcc/libgcov.c	2012-01-11 10:50:21.000000000 -0800
++++ coreboot/src/lib/libgcov.c	2013-01-16 09:45:11.000000000 -0800
+@@ -25,12 +25,41 @@
+ see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
+ <http://www.gnu.org/licenses/>.  */
+ 
++#define __COREBOOT__
++#ifdef __COREBOOT__
++#include <stdlib.h>
++#include <string.h>
++#include <console/console.h>
++#include <assert.h>
++typedef s32 pid_t;
++#define gcc_assert(x) ASSERT(x)
++#define fprintf(file, x...) printk(BIOS_ERR, x)
++#define alloca(size)   __builtin_alloca (size)
++#include "gcov-glue.c"
++
++/* Define MACROs to be used by coreboot compilation.  */
++# define L_gcov
++# define L_gcov_interval_profiler
++# define L_gcov_pow2_profiler
++# define L_gcov_one_value_profiler
++# define L_gcov_indirect_call_profiler
++# define L_gcov_average_profiler
++# define L_gcov_ior_profiler
++
++# define HAVE_CC_TLS 0
++# define __GCOV_KERNEL__
++
++# define IN_LIBGCOV 1
++# define IN_GCOV 0
++#else /* __COREBOOT__ */
+ #include "tconfig.h"
+ #include "tsystem.h"
+ #include "coretypes.h"
+ #include "tm.h"
+ #include "libgcc_tm.h"
++#endif /* __COREBOOT__ */
+ 
++#ifndef __COREBOOT__
+ #if defined(inhibit_libc)
+ #define IN_LIBGCOV (-1)
+ #else
+@@ -41,6 +70,7 @@
+ #define GCOV_LINKAGE /* nothing */
+ #endif
+ #endif
++#endif /* __COREBOOT__ */
+ #include "gcov-io.h"
+ 
+ #if defined(inhibit_libc)
+@@ -68,12 +98,17 @@
+ 
+ #else
+ 
++#ifndef __COREBOOT__
+ #include <string.h>
+ #if GCOV_LOCKED
+ #include <fcntl.h>
+ #include <errno.h>
+ #include <sys/stat.h>
+ #endif
++#else
++void __gcov_merge_add(gcov_type *counters  __attribute__ ((unused)),
++			unsigned n_counters __attribute__ ((unused))) {}
++#endif /* __COREBOOT__ */
+ 
+ #ifdef L_gcov
+ #include "gcov-io.c"
+@@ -99,6 +134,10 @@
+ static int
+ create_file_directory (char *filename)
+ {
++#ifdef __COREBOOT__
++  (void) filename;
++  return 0;
++#else
+ #if !defined(TARGET_POSIX_IO) && !defined(_WIN32)
+   (void) filename;
+   return -1;
+@@ -137,6 +176,7 @@
+       };
+   return 0;
+ #endif
++#endif
+ }
+ 
+ static struct gcov_fn_buffer *
+@@ -279,7 +319,7 @@
+   struct gcov_ctr_summary *cs_ptr;
+   const struct gcov_ctr_info *ci_ptr;
+   unsigned t_ix;
+-  int f_ix;
++  int f_ix = 0;
+   gcov_unsigned_t c_num;
+   const char *gcov_prefix;
+   int gcov_prefix_strip = 0;
+@@ -329,6 +369,7 @@
+ 	}
+     }
+ 
++#ifndef __COREBOOT__
+   {
+     /* Check if the level of dirs to strip off specified. */
+     char *tmp = getenv("GCOV_PREFIX_STRIP");
+@@ -352,6 +393,7 @@
+ 	prefix_length--;
+     }
+   else
++#endif
+     prefix_length = 0;
+ 
+   /* If no prefix was specified and a prefix stip, then we assume
+@@ -696,8 +738,10 @@
+       if (filename_length > gcov_max_filename)
+         gcov_max_filename = filename_length;
+ 
++#ifndef __COREBOOT__
+       if (!gcov_list)
+ 	atexit (gcov_exit);
++#endif
+ 
+       info->next = gcov_list;
+       gcov_list = info;
+@@ -767,14 +811,15 @@
+ 
+ #ifdef L_gcov_merge_single
+ /* The profile merging function for choosing the most common value.
+-   It is given an array COUNTERS of N_COUNTERS old counters and it
+-   reads the same number of counters from the gcov file.  The counters
+-   are split into 3-tuples where the members of the tuple have
+-   meanings:
+-
+-   -- the stored candidate on the most common value of the measured entity
+-   -- counter
+-   -- total number of evaluations of the value  */
++ * It is given an array COUNTERS of N_COUNTERS old counters and it
++ * reads the same number of counters from the gcov file.  The counters
++ * are split into 3-tuples where the members of the tuple have
++ * meanings:
++ *
++ * -- the stored candidate on the most common value of the measured entity
++ * -- counter
++ * -- total number of evaluations of the value
++ */
+ void
+ __gcov_merge_single (gcov_type *counters, unsigned n_counters)
+ {
+@@ -805,15 +850,16 @@
+ 
+ #ifdef L_gcov_merge_delta
+ /* The profile merging function for choosing the most common
+-   difference between two consecutive evaluations of the value.  It is
+-   given an array COUNTERS of N_COUNTERS old counters and it reads the
+-   same number of counters from the gcov file.  The counters are split
+-   into 4-tuples where the members of the tuple have meanings:
+-
+-   -- the last value of the measured entity
+-   -- the stored candidate on the most common difference
+-   -- counter
+-   -- total number of evaluations of the value  */
++ * difference between two consecutive evaluations of the value.  It is
++ * given an array COUNTERS of N_COUNTERS old counters and it reads the
++ * same number of counters from the gcov file.  The counters are split
++ * into 4-tuples where the members of the tuple have meanings:
++ *
++ * -- the last value of the measured entity
++ * -- the stored candidate on the most common difference
++ * -- counter
++ * -- total number of evaluations of the value
++ */
+ void
+ __gcov_merge_delta (gcov_type *counters, unsigned n_counters)
+ {

firmware/coreboot/Documentation/getting_started/build_system.md

@@ -0,0 +1,86 @@
+# The coreboot build system
+(this document is still incomplete and will be filled in over time)
+
+## General operation
+The coreboot build system is based on GNU make but extends it significantly
+to the point of providing its own custom language.
+The overhead of learning this new syntax is (hopefully) offset by its lower
+complexity.
+
+The build system is defined in the toplevel `Makefile` and `toolchain.inc`
+and is supposed to be generic (and is in fact used with a number of other
+projects).  Project specific configuration should reside in files called
+`Makefile.inc`.
+
+In general, the build system provides a number of "classes" that describe
+various parts of the build. These cover the various build targets in coreboot
+such as the stages, subdirectories with more source code, and the general
+addition of files.
+
+Each class has a name (eg. `romstage`, `subdirs`, `cbfs-files`) and is used
+by filling in a variable of that name followed by `-y` (eg. `romstage-y`,
+`subdirs-y`, `cbfs-files-y`).
+The `-y` suffix allows a simple interaction with our Kconfig build
+configuration system: Kconfig options are available as variables starting
+with a `CONFIG_` prefix and boolean options contain `y`, `n` or are empty.
+
+This allows `class-$(CONFIG_FOO) += bar` to conditionally add `bar` to
+`class` depending on the choice for `FOO`.
+
+## classes
+Classes can be defined as required. `subdirs` is handled internally since
+it's parsed per subdirectory to add further directories to the rule set.
+
+TODO: explain how to create new classes and how to evaluate them.
+
+### subdirs
+`subdirs` contains subdirectories (relative to the current directory) that
+should also be handled by the build system. The build system expects these
+directories to contain a file called `Makefile.inc`.
+
+Subdirectories are not read at the point where the `subdirs` statement
+resides but later, after the current directory is handled (and potentially
+others, too).
+
+### cbfs-files
+This class is used to add files to the final CBFS image. Since several more
+options need to be maintained than can comfortably fit in that single
+variable, additional variables are used.
+
+`cbfs-files-y` contains the file name used in the CBFS image (called `foo`
+here). Additional options are added in `foo-$(option)` variables. The
+supported options are:
+
+*  `file`: The on-disk file to add as `foo` (required)
+*  `type`: The file type. Can be `raw`, `stage`, `payload`, and `flat-binary`
+   (required)
+*  `compression`: Can be `none` or `lzma` (default: none)
+*  `position`: An absolute position constraint for the placement of the file
+   (default: none)
+*  `align`: Minimum alignment for the file (default: none)
+*  `options`: Additional cbfstool options (default: none)
+
+`position` and `align` are mutually exclusive.
+
+#### FMAP region support
+With the addition of FMAP flash partitioning support to coreboot, there was a
+need to extend the specification of files to provide more precise control
+which regions should contain which files, and even change some flags based on
+the region.
+
+Since FMAP policies depend on features using FMAP, that's kept separate from
+the cbfs-files class.
+
+The `position` and `align` options for file `foo` can be overwritten for a
+region `REGION` using `foo-REGION-position` and `foo-REGION-align`.
+
+The regions that each file should end in can be defined by overriding a
+function called `regions-for-file` that's called as
+`$(call regions-for-file,$(filename))` and should return a comma-separated
+list of regions, such as `REGION1,REGION2,REGION3`.
+
+The default implementation just returns `COREBOOT` (the default region) for
+all files.
+
+vboot provides its own implementation of `regions-for-file` that can be used
+as reference in `src/vboot/Makefile.inc`.

firmware/coreboot/Documentation/getting_started/gerrit_guidelines.md

@@ -0,0 +1,277 @@
+coreboot Gerrit Etiquette and Guidelines
+========================================
+
+The following rules are the requirements for behavior in the coreboot
+codebase in gerrit. These have mainly been unwritten rules up to this
+point, and should be familiar to most users who have been active in
+coreboot for a period of time. Following these rules will help reduce
+friction in the community.
+
+Note that as with many rules, there are exceptions. Some have been noted
+in the 'More Detail' section. If you feel there is an exception not listed
+here, please discuss it in the mailing list to get this document  updated.
+Don't just assume that it's okay, even if someone on IRC says it is.
+
+
+Summary:
+--------
+These are the expectations for committing, reviewing, and submitting code
+into coreboot git and gerrit. While breaking individual rules may not have
+immediate consequences, the coreboot leadership may act on repeated or
+flagrant violations with or without notice.
+
+* Don't violate the licenses.
+* Let non-trivial patches sit in a review state for at least 24 hours
+before submission.
+* Try to coordinate with platform maintainers when making changes to
+platforms.
+* If you give a patch a -2, you are responsible for giving concrete
+recommendations for what could be changed to resolve the issue the patch
+addresses.
+* Don't modify other people's patches without their consent.
+* Be respectful to others when commenting.
+* Don’t submit patches that you know will break other platforms.
+
+
+More detail:
+------------
+* Don't violate the licenses. If you're submitting code that you didn't
+write yourself, make sure the license is compatible with the license of the
+project you're submitting the changes to. If you’re submitting code that
+you wrote that might be owned by your employer, make sure that your
+employer is aware and you are authorized to submit the code. For
+clarification, see the Developer's Certificate of Origin in the coreboot
+[Signed-off-by policy](https://www.coreboot.org/Development_Guidelines#Sign-off_Procedure).
+
+* Let non-trivial patches sit in a review state for at least 24 hours
+before submission. Remember that there are coreboot developers in timezones
+all over the world, and everyone should have a chance to contribute.
+Trivial patches would be things like whitespace changes or spelling fixes.
+In general, small changes that don’t impact the final binary output. The
+24-hour period would start at submission, and would be restarted at any
+update which significantly changes any part of the patch. Patches can be
+'Fast-tracked' and submitted in under this 24 hour with the agreement of at
+least 3 +2 votes.
+
+* Do not +2 patches that you authored or own, even for something as trivial
+as whitespace fixes. When working on your own patches, it’s easy to
+overlook something like accidentally updating file permissions or git
+submodule commit IDs. Let someone else review the patch. An exception to
+this would be if two people worked in the patch together. If both +2 the
+patch, that is acceptable, as each is giving a +2 to the other's work.
+
+* Try to coordinate with platform maintainers and other significant
+contributors to the code when making changes to platforms. The platform
+maintainers are the users who initially pushed the code for that platform,
+as well as users who have made significant changes to a platform. To find
+out who maintains a piece of code, please use util/scripts/maintainers.go
+or refer to the original author of the code in git log.
+
+* If you give a patch a -2, you are responsible for giving concrete
+recommendations for what could be changed to resolve the issue the patch
+addresses. If you feel strongly that a patch should NEVER be merged, you
+are responsible for defending your position and listening to other points
+of view. Giving a -2 and walking away is not acceptable, and may cause your
+ -2 to be removed by the coreboot leadership after no less than a week. A
+ notification that the -2 will be removed unless there is a response will
+ be sent out at least 2 days before it is removed.
+
+* Don't modify other people's patches unless you have coordinated this with
+the owner of that patch. Not only is this considered rude, but your changes
+could be unintentionally lost. An exception to this would be for patches
+that have not been updated for more than 90 days. In that case, the patch
+can be taken over if the original author does not respond to requests for
+updates. Alternatively, a new patch can be pushed with the original
+content, and both patches should be updated to reference the other.
+
+* Be respectful to others when commenting on patches. Comments should
+be kept to the code, and should be kept in a polite tone. We are a
+worldwide community and English is a difficult language. Assume your
+colleagues are intelligent and do not intend disrespect. Resist the urge to
+retaliate against perceived verbal misconduct, such behavior is not
+conducive to getting patches merged.
+
+* Don’t submit code that you know will break other platforms. If your patch
+affects code that is used by other platforms, it should be compatible with
+those platforms. While it would be nice to update any other platforms, you
+must at least provide a path that will allow other platforms to continue
+working.
+
+
+Recommendations for gerrit activity:
+------------------------------------
+These guidelines are less strict than the ones listed above. These are more
+of the “good idea” variety. You are requested to follow the below
+guidelines, but there will probably be no actual consequences if they’re
+not followed. That said, following the recommendations below will speed up
+review of your patches, and make the members of the community do less work.
+
+* Each patch should be kept to one logical change, which should be
+described in the title of the patch. Unrelated changes should be split out
+into separate patches. Fixing whitespace on a line you’re editing is
+reasonable. Fixing whitespace around the code you’re working on should be a
+separate ‘cleanup’ patch. Larger patches that touch several areas are fine,
+so long as they are one logical change. Adding new chips and doing code
+cleanup over wide areas are two examples of this.
+
+* Test your patches before submitting them to gerrit. It's also appreciated
+if you add a line to the commit message describing how the patch was
+tested. This prevents people from having to ask whether and how the patch
+was tested. Examples of this sort of comment would be ‘TEST=Built
+platform’ or ‘Tested by building and booting platform’.  Stating that the
+patch was not tested is also fine, although you might be asked to do some
+testing in cases where that would be reasonable.
+
+* Take advantage of the lint tools to make sure your patches don’t contain
+trivial mistakes. By running ‘make gitconfig’, the lint-stable tools are
+automatically put in place and will test your patches before they are
+committed. As a violation of these tools will cause the jenkins build test
+to fail, it’s to your advantage to test this before pushing to gerrit.
+
+* Don't submit patch trains longer than around 20 patches unless you
+understand how to manage long patch trains. Long patch trains can become
+difficult to handle and tie up the build servers for long periods of time
+if not managed well. Rebasing a patch train over and over as you fix
+earlier patches in the train can hide comments, and make people review the
+code multiple times to see if anything has changed between revisions. When
+pushing long patch trains, it is recommended to only push the full patch
+train once - the initial time, and only to rebase three or four patches at
+a time.
+
+* Run 'make what-jenkins-does' locally on patch trains before submitting.
+This helps verify that the patch train won’t tie up the jenkins builders
+for no reason if there are failing patches in the train. For running
+parallel builds, you can specify the number of cores to use by setting the
+the CPUS environment variable. Example:
+        make what-jenkins-does CPUS=8
+
+* Use a topic when pushing a train of patches. This groups the commits
+together so people can easily see the connection at the top level of
+gerrit. Topics can be set for individual patches in gerrit by going into
+the patch and clicking on the icon next to the topic line. Topics can also
+be set when you push the patches into gerrit. For example, to push a set of
+commits with the the i915-kernel-x60 set, use the command:
+        git push origin HEAD:refs/for/master/i915-kernel-x60
+
+* If one of your patches isn't ready to be merged, make sure it's obvious
+that you don't feel it's ready for merge yet. The preferred way to show
+this is by marking in the commit message that it’s not ready until X. The
+commit message can be updated easily when it’s ready to be pushed.
+Examples of this are "WIP: title" or "[NEEDS_TEST]: title".  Another way to
+mark the patch as not ready would be to give it a -1 or -2 review, but
+isn't as obvious as the commit message. These patches can also be pushed as
+drafts as shown in the next guideline.
+
+* When pushing patches that are not for submission, these should be marked
+as such. This can be done in the title ‘[DONOTSUBMIT]’, or can be pushed as
+draft commits, so that only explicitly added reviewers will see them. These
+sorts of patches are frequently posted as ideas or RFCs for the community
+to look at. To push a draft, use the command:
+        git push origin HEAD:refs/drafts/master
+
+* Respond to anyone who has taken the time to review your patches, even if
+it's just to say that you disagree. While it may seem annoying to address a
+request to fix spelling or 'trivial' issues, it’s generally easy to handle
+in gerrit’s built-in editor. If you do use the built-in editor, remember to
+get that change to your local copy before re-pushing. It's also acceptable
+to add fixes for these sorts of comments to another patch, but it's
+recommended that that patch be pushed to gerrit before the initial patch
+gets submitted.
+
+* Consider breaking up large individual patches into smaller patches
+grouped by areas. This makes the patches easier to review, but increases
+the number of patches. The way you want to handle this is a personal
+decision, as long as each patch is still one logical change.
+
+* If you have an interest in a particular area or mainboard, set yourself
+up as a ‘maintainer’ of that area by adding yourself to the MAINTAINERS
+file in the coreboot root directory. Eventually, this should automatically
+add you as a reviewer when an area that you’re listed as a maintainer is
+changed.
+
+* Submit mainboards that you’re working on to the board-status repo. This
+helps others and shows that these mainboards are currently being
+maintained. At some point, boards that are not up to date in the
+board-status repo will probably end up getting removed from the coreboot
+master branch.
+
+* Abandon patches that are no longer useful, or that you don’t intend to
+keep working on to get submitted.
+
+* Bring attention to patches that you would like reviewed. Add reviewers,
+ask for reviewers on IRC or even just rebase it against the current
+codebase to bring it to the top of the gerrit list. If you’re not sure who
+would be a good reviewer, look in the MAINTAINERS file or git history of
+the files that you’ve changed, and add those people.
+
+* Familiarize yourself with the coreboot [commit message
+guidelines](https://www.coreboot.org/Git#Commit_messages), before pushing
+patches. This will help to keep annoying requests to fix your commit
+message to a minimum.
+
+* If there have been comments or discussion on a patch, verify that the
+comments have been addressed before giving a +2. If you feel that a comment
+is invalid, please respond to that comment instead of just ignoring it.
+
+* Be conscientious when reviewing patches. As a reviewer who approves (+2)
+a patch, you are responsible for the patch and the effect it has on the
+codebase. In the event that the patch breaks things, you are expected to
+be actively involved in the cleanup effort. This means you shouldn’t +2 a
+patch just because you trust the author of a patch - Make sure you
+understand what the implications of a patch might be, or leave the review
+to others. Partial reviews, reviewing code style, for example, can be given
+a +1 instead of a +2. This also applies if you think the patch looks good,
+but may not have the experience to know if there may be unintended
+consequences.
+
+* If there is still ongoing discussion to a patch, try to wait for a
+conclusion to the discussion before submitting it to the tree. If you feel
+that someone is just bikeshedding, maybe just state that and give a time
+that the patch will be submitted if no new objections are raised.
+
+* When working with patch trains, for minor requests it’s acceptable to
+create a fix addressing a comment in another patch at the end of the patch
+train. This minimizes rebases of the patch train while still addressing the
+request. For major problems where the change doesn’t work as intended or
+breaks other platforms, the change really needs to go into the original
+patch.
+
+* When bringing in a patch from another git repo, update the original
+git/gerrit tags by prepending the lines with 'Original-'.  Marking
+the original text this way makes it much easier to tell what changes
+happened in which repository. This applies to these lines, not the actual
+commit message itself:
+        Commit-Id:
+        Change-Id:
+        Signed-off-by:
+        Reviewed-on:
+        Tested-by:
+        Reviewed-by:
+The script 'util/gitconfig/rebase.sh' can be used to help automate this.
+Other tags such as 'Commit-Queue' can simply be removed.
+
+
+Expectations contributors should have:
+--------------------------------------
+* Don't expect that people will review your patch unless you ask them to.
+Adding other people as reviewers is the easiest way. Asking for reviews for
+individual patches in the IRC channel, or by sending a direct request to an
+individual through your favorite messenger is usually the best way to get a
+patch reviewed quickly.
+
+* Don't expect that your patch will be submitted immediately after getting
+a +2. As stated previously, non-trivial patches should wait at least 24
+hours before being submitted. That said, if you feel that your patch or
+series of patches has been sitting longer than needed, you can ask for it
+to be submitted on IRC, or comment that it's ready for submission in the
+patch. This will move it to the top of the list where it's more likely to
+be noticed and acted upon.
+
+* Reviews are about the code. It's easy to take it personally when someone
+is criticising your code, but the whole idea is to get better code into our
+codebase. Again, this also applies in the other direction: review code,
+criticize code, but don’t make it personal.
+
+
+Requests for clarification and suggestions for updates to these guidelines
+should be sent to the coreboot mailing list at <coreboot@coreboot.org>.

firmware/coreboot/Documentation/getting_started/index.md

@@ -0,0 +1,8 @@
+# Getting Started
+
+* [Build System](build_system.md)
+* [Submodules](submodules.md)
+* [Kconfig](kconfig.md)
+* [Gerrit Guidelines](gerrit_guidelines.md)
+* [Documentation License](license.md)
+* [Writing Documentation](writing_documentation.md)

firmware/coreboot/Documentation/getting_started/license.md

@@ -0,0 +1,164 @@
+# coreboot documentation license
+
+Files under Documentation/ are licensed under CC-BY 4.0 terms, printed below.
+As an exception, files under Documentation/ with a history older than 2017-05-24
+might be under different licenses (but should be cleared up ASAP).
+
+## Attribution 4.0 International
+
+Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
+
+### Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
+
+* __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors).
+
+* __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees).
+
+## Creative Commons Attribution 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
+
+### Section 1 – Definitions.
+
+a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
+
+b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
+
+c. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
+
+d. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
+
+e. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
+
+f. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
+
+g. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
+
+h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License.
+
+i. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
+
+j. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
+
+k. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
+
+### Section 2 – Scope.
+
+a. ___License grant.___
+
+   1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
+
+       A. reproduce and Share the Licensed Material, in whole or in part; and
+
+       B. produce, reproduce, and Share Adapted Material.
+
+   2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
+
+   3. __Term.__ The term of this Public License is specified in Section 6(a).
+
+   4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
+
+   5. __Downstream recipients.__
+
+       A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
+
+       B. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
+
+   6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
+
+b. ___Other rights.___
+
+   1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
+
+   2. Patent and trademark rights are not licensed under this Public License.
+
+   3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.
+
+### Section 3 – License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the following conditions.
+
+a. ___Attribution.___
+
+   1. If You Share the Licensed Material (including in modified form), You must:
+
+       A. retain the following if it is supplied by the Licensor with the Licensed Material:
+
+         i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
+
+         ii. a copyright notice;
+
+         iii. a notice that refers to this Public License;
+
+         iv. a notice that refers to the disclaimer of warranties;
+
+         v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
+
+       B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
+
+       C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
+
+   2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
+
+   3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
+
+   4. If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License.
+
+### Section 4 – Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
+
+a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;
+
+b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and
+
+c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
+
+### Section 5 – Disclaimer of Warranties and Limitation of Liability.
+
+a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__
+
+b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__
+
+c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
+
+### Section 6 – Term and Termination.
+
+a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
+
+b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
+
+   1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
+
+   2. upon express reinstatement by the Licensor.
+
+   For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
+
+c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
+
+d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
+
+### Section 7 – Other Terms and Conditions.
+
+a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
+
+b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
+
+### Section 8 – Interpretation.
+
+a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
+
+b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
+
+c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
+
+d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
+
+> Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
+>
+> Creative Commons may be contacted at creativecommons.org
+

firmware/coreboot/Documentation/getting_started/submodules.md

@@ -0,0 +1,46 @@
+Use of git submodules in coreboot
+=================================
+coreboot uses git submodules to keep certain parts of the tree separate,
+with two major use cases:
+
+First, we use a vendor tool by NVIDIA for systems based on their SoC
+and since they publish it through git, we can just import it into our
+tree using submodules.
+
+Second, lots of boards these days require binaries and we want to keep
+them separate from coreboot proper to clearly delineate shiny Open Source
+from ugly blobs.
+Since we don't want to impose blobs on users who really don't need them,
+that repository is only downloaded and checked out on explicit request.
+
+Handling submodules
+-------------------
+For the most part, submodules should be automatically checked out on the
+first execution of the coreboot Makefile.
+
+To manually fetch all repositories (eg. when you want to prepare the tree
+for archiving, or to use it without network access), run
+
+    $ git submodule update --init --checkout
+
+This also checks out the binaries below `3rdparty/`
+
+Mirroring coreboot
+------------------
+When running a coreboot mirror to checkout from, for full operation, you
+should also mirror the blobs and nvidia-cbootimage repository, and place
+them in the same directory as the coreboot repository mirror.
+
+That is, when residing in coreboot's repository, `cd ../blobs.git`
+should move you to the blobs repository.
+
+With that, no matter what the URL of your coreboot repository is, the
+git client (of a sufficiently new version) is able to pick up the other
+repositories transparently.
+
+Minimum requirements
+--------------------
+git needs to be able to handle relative paths to submodule repositories,
+and it needs to know about non-automatic submodules.
+
+For these features, we require git version 1.7.6.1 or newer.

firmware/coreboot/Documentation/getting_started/writing_documentation.md

@@ -0,0 +1,74 @@
+# coreboot documentation guidelines
+
+> Documentation is like sex: when it is good, it is very, very good;
+> and when it is bad, it is better than nothing.
+
+That said please always try to write documentation! One problem in the
+firmware development is the missing documentation. In this document
+you will get a brief introduction how to write, submit and publish
+documenation to coreboot.
+
+## Preparations
+
+coreboot uses [Sphinx] documentation tool. We prefer the markdown format
+over reStructuredText so only embedded ReST is supported. Checkout the
+[Markdown Guide] for more information.
+
+### Install Sphinx
+
+Please follow this official [guide].
+
+### Optional
+
+Install [shpinx-autobuild] for rebuilding markdown/rst sources on the fly!
+
+## Basic and simple rules
+
+The following rules should be followed in order to get it at least reviewed
+on [review.coreboot.org].
+
+Documentation:
+
+1.  Must be written in **markdown** with **embedded reStructuredText**
+    format.
+2.  Must be written in **English**.
+3.  Must be placed into **Documentation/** directory subfolder.
+4.  Should follow the same directory structure as **src/** when practical.
+5.  Must be referenced from within other markdown files
+6.  The commit must follow the [Gerrit Guidelines].
+7.  Must have all **lowercase filenames**.
+8.  Running text should have a visible width of about **72 chars**.
+9.  Should not **duplicate** documentation, but reference it instead.
+10.  Must not include the same picture in multiple markdown files.
+11.  Images should be kept small. They should be under 700px in width, as
+     the current theme doesn't allow bigger images.
+12.  Shouldn't cover implementation details; for details, the code is the
+     reference.
+
+## Markdown and Tables
+
+Under Sphinx markdown tables are not supported. Therefore you can use following
+code block to write tables in reStructuredText and embed them into the markdown:
+
+    ```eval_rst
+    +------------+------------+-----------+
+    | Header 1   | Header 2   | Header 3  |
+    +============+============+===========+
+    | body row 1 | column 2   | column 3  |
+    +------------+------------+-----------+
+    | body row 2 | Cells may span columns.|
+    +------------+------------+-----------+
+    | body row 3 | Cells may  | - Cells   |
+    +------------+ span rows. | - contain |
+    | body row 4 |            | - blocks. |
+    +------------+------------+-----------+
+    ``` #just a code block is enough
+
+[coreboot]: https://coreboot.org
+[Documentation]: https://review.coreboot.org/cgit/coreboot.git/tree/Documentation
+[shpinx-autobuild]: https://github.com/GaretJax/sphinx-autobuild
+[guide]: http://www.sphinx-doc.org/en/stable/install.html
+[Sphinx]: http://www.sphinx-doc.org/en/master/
+[Markdown Guide]: https://www.markdownguide.org/
+[Gerrit Guidelines]: https://doc.coreboot.org/gerrit_guidelines.html
+[review.coreboot.org]: https://review.coreboot.org

firmware/coreboot/Documentation/gfx/libgfxinit.md

@@ -0,0 +1,124 @@
+libgfxinit - Native Graphics Initialization
+===========================================
+
+Introduction and Current State in coreboot
+------------------------------------------
+
+*libgfxinit* is a library of full-featured graphics initialization
+(aka. modesetting) drivers. It's implemented in SPARK (a subset of
+Ada with formal verification features). While not restricted to in
+any way, it currently only supports Intel's integrated gfx control-
+lers (GMA).
+
+Currently, it supports the Intel Core i3/i5/i7 processor line and
+will support HDMI and DP on the Atom successor Apollo Lake. At the
+time of writing, Sandy Bridge, Ivy Bridge, and Haswell are veri-
+fied to work within *coreboot*.
+
+GMA: Framebuffer Configuration
+------------------------------
+
+*coreboot* supports two different framebuffer setups. The default
+enables the legacy VGA plane in textmode. Due to legacy hardware
+constraints, only the first found display is enabled in this mode.
+(cf. `src/drivers/intel/gma/text_fb/gma.adb`).
+
+The second option sets up a high-resolution framebuffer with the
+native resolution of the display if only one is detected, or the
+smallest of all resolutions (per dimension) if multiple displays
+are detected. This option is selected by
+`CONFIG_FRAMEBUFFER_KEEP_VESA_MODE`.
+(cf. `src/drivers/intel/gma/hires_fb/gma.adb`).
+
+In any case, a smaller framebuffer is up-scaled to each display's
+native resolution while keeping aspect ratio.
+
+GMA: Hook-up in Chipset Initialization
+--------------------------------------
+
+Both configurations described above implement a procedure
+`GMA.gfxinit()`:
+
+    procedure gfxinit (lightup_ok : out int);
+
+This procedure is exported as the C function `gma_gfxinit()` as
+follows:
+
+    void gma_gfxinit(int *lightup_ok);
+
+* `lightup_ok`: returns whether the initialization succeeded `1` or
+                failed `0`. Currently, only the case that no display
+                could be found counts as failure. A failure at a la-
+                ter stage (e.g. failure to train a DP) is not propa-
+                gated.
+
+GMA: Per Board Configuration
+----------------------------
+
+There are a few Kconfig symbols to consider. To indicate that a
+board can initialize graphics through *libgfxinit*:
+
+    select MAINBOARD_HAS_LIBGFXINIT
+
+Internal ports share some hardware blocks (e.g. backlight, panel
+power sequencer). Therefore, each board has to select either eDP
+or LVDS as the internal port, if any:
+
+    select GFX_GMA_INTERNAL_IS_EDP	# the default, or
+    select GFX_GMA_INTERNAL_IS_LVDS
+
+Boards with a DVI-I connector share the DDC (I2C) pins for both
+analog and digital displays. In this case, *libgfxinit* needs to
+know through which interface the EDID can be queried:
+
+    select GFX_GMA_ANALOG_I2C_HDMI_B	# or
+    select GFX_GMA_ANALOG_I2C_HDMI_C	# or
+    select GFX_GMA_ANALOG_I2C_HDMI_D
+
+Beside Kconfig options, *libgfxinit* needs to know which ports are
+implemented on a board and should be probed for displays. Each
+board has to implement the package `GMA.Mainboard` with a list:
+
+    ports : HW.GFX.GMA.Display_Probing.Port_List;
+
+or a function returning such a list:
+
+    function ports return HW.GFX.GMA.Display_Probing.Port_List;
+
+You can select from the following Ports:
+
+    type Port_Type is
+      (Disabled,	-- optionally terminates the list
+       Internal,	-- either eDP or LVDS as selected in Kconfig
+       DP1,
+       DP2,
+       DP3,
+       HDMI1,		-- also DVI-D, or HDMI over DP++
+       HDMI2,
+       HDMI3,
+       Analog);		-- legacy VGA port, or analog part of DVI-I
+
+Each `DPx` and `HDMIx` pair share pins. If they are exposed as DP
+ports, they are usually DP++ (aka. dual-mode DP) ports that can
+also output HDMI signals through passive adapters. In this case,
+both DPx and HDMIx should be listed.
+
+A good example is the mainboard Kontron/KTQM77, it features two
+DP++ ports (DP2/HDMI2, DP3/HDMI3), one DVI-I port (HDMI1/Analog),
+eDP and LVDS. Due to the constraints mentioned above, only one of
+eDP and LVDS can be enabled. It defines `ports` as follows:
+
+    ports : constant Port_List :=
+      (DP2,
+       DP3,
+       HDMI1,
+       HDMI2,
+       HDMI3,
+       Analog,
+       Internal,
+       others => Disabled);
+
+The `GMA.gfxinit()` procedure probes for display EDIDs in the
+given order until all available pipes are taken. That's 1 pipe
+in VGA textmode, 2 pipes in high-resolution mode until Sandy
+Bridge, 3 pipes from Ivy Bridge on.

firmware/coreboot/Documentation/hypertransport.svg

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="256px" height="512px" viewBox="0 0 256 512" enable-background="new 0 0 256 512" xml:space="preserve">
+<font horiz-adv-x="2048">
+<font-face font-family="ArialMT" units-per-em="2048" underline-position="-217" underline-thickness="150"/>
+<missing-glyph horiz-adv-x="1536" d="M256,0l0,1280l1024,0l0,-1280M288,32l960,0l0,1216l-960,0z"/>
+<glyph unicode=" " horiz-adv-x="569"/>
+<glyph unicode="(" horiz-adv-x="682" d="M479,-431C380,-306 296,-159 227,9C158,177 124,351 124,531C124,690 150,842 201,987C261,1156 354,1324 479,1491l129,0C527,1352 474,1253 448,1194C407,1102 375,1006 352,906C323,781 309,656 309,530C309,209 409,-111 608,-431z"/>
+<glyph unicode=")" horiz-adv-x="682" d="M253,-431l-129,0C323,-111 423,209 423,530C423,655 409,780 380,903C357,1003 326,1099 285,1191C259,1251 205,1351 124,1491l129,0C378,1324 471,1156 531,987C582,842 608,690 608,531C608,351 574,177 505,9C436,-159 352,-306 253,-431z"/>
+<glyph unicode="-" horiz-adv-x="682" d="M65,440l0,181l553,0l0,-181z"/>
+<glyph unicode="0" horiz-adv-x="1139" d="M85,723C85,896 103,1036 139,1142C174,1247 227,1329 298,1386C368,1443 456,1472 563,1472C642,1472 711,1456 770,1425C829,1393 878,1347 917,1288C956,1228 986,1155 1008,1070C1030,984 1041,868 1041,723C1041,551 1023,412 988,307C953,201 900,119 830,62C759,4 670,-25 563,-25C422,-25 311,26 230,127C133,249 85,448 85,723M270,723C270,482 298,322 355,243C411,163 480,123 563,123C646,123 715,163 772,243C828,323 856,483 856,723C856,964 828,1125 772,1204C715,1283 645,1323 561,1323C478,1323 412,1288 363,1218C301,1129 270,964 270,723z"/>
+<glyph unicode="1" horiz-adv-x="1139" d="M763,0l-180,0l0,1147C540,1106 483,1064 413,1023C342,982 279,951 223,930l0,174C324,1151 412,1209 487,1276C562,1343 616,1409 647,1472l116,0z"/>
+<glyph unicode="2" horiz-adv-x="1139" d="M1031,173l0,-173l-969,0C61,43 68,85 83,125C108,191 147,256 202,320C256,384 334,458 437,542C596,673 704,776 760,853C816,929 844,1001 844,1069C844,1140 819,1201 768,1250C717,1299 650,1323 568,1323C481,1323 412,1297 360,1245C308,1193 282,1121 281,1029l-185,19C109,1186 156,1291 239,1364C322,1436 433,1472 572,1472C713,1472 824,1433 906,1355C988,1277 1029,1180 1029,1065C1029,1006 1017,949 993,892C969,835 929,776 874,713C818,650 725,564 596,455C488,364 419,303 388,271C357,238 332,206 312,173z"/>
+<glyph unicode="3" horiz-adv-x="1139" d="M86,387l180,24C287,309 322,236 372,191C421,146 482,123 553,123C638,123 709,152 768,211C826,270 855,342 855,429C855,512 828,580 774,634C720,687 651,714 568,714C534,714 492,707 441,694l20,158C473,851 483,850 490,850C567,850 636,870 697,910C758,950 789,1012 789,1095C789,1161 767,1216 722,1259C677,1302 620,1324 549,1324C479,1324 421,1302 374,1258C327,1214 297,1148 284,1060l-180,32C126,1213 176,1306 254,1373C332,1439 429,1472 545,1472C625,1472 699,1455 766,1421C833,1386 885,1339 921,1280C956,1221 974,1158 974,1091C974,1028 957,970 923,918C889,866 839,825 772,794C859,774 926,733 974,670C1022,607 1046,528 1046,433C1046,305 999,197 906,108C813,19 695,-26 552,-26C423,-26 317,12 232,89C147,166 98,265 86,387z"/>
+<glyph unicode="8" horiz-adv-x="1139" d="M362,795C287,822 232,861 196,912C160,963 142,1023 142,1094C142,1201 180,1290 257,1363C334,1436 436,1472 563,1472C691,1472 794,1435 872,1361C950,1286 989,1196 989,1089C989,1021 971,962 936,912C900,861 846,822 773,795C863,766 932,718 979,653C1026,588 1049,510 1049,419C1049,294 1005,188 916,103C827,18 711,-25 566,-25C421,-25 305,18 216,104C127,189 83,296 83,424C83,519 107,599 156,664C204,728 273,772 362,795M326,1100C326,1031 348,974 393,930C438,886 496,864 567,864C636,864 693,886 738,930C782,973 804,1027 804,1090C804,1156 781,1212 736,1257C690,1302 633,1324 565,1324C496,1324 439,1302 394,1258C349,1214 326,1161 326,1100M268,423C268,372 280,322 305,274C329,226 365,189 413,163C461,136 513,123 568,123C654,123 725,151 781,206C837,261 865,332 865,417C865,504 836,575 779,632C721,689 649,717 562,717C477,717 407,689 352,633C296,577 268,507 268,423z"/>
+<glyph unicode="B" horiz-adv-x="1366" d="M150,0l0,1466l550,0C812,1466 902,1451 970,1422C1037,1392 1090,1346 1129,1285C1167,1223 1186,1158 1186,1091C1186,1028 1169,969 1135,914C1101,859 1050,814 981,780C1070,754 1138,710 1186,647C1233,584 1257,510 1257,425C1257,356 1243,293 1214,234C1185,175 1149,129 1106,97C1063,65 1010,41 946,25C881,8 802,0 709,0M344,850l317,0C747,850 809,856 846,867C895,882 933,906 958,940C983,974 995,1017 995,1068C995,1117 983,1160 960,1197C937,1234 903,1259 860,1273C817,1286 742,1293 637,1293l-293,0M344,173l365,0C772,173 816,175 841,180C886,188 923,201 953,220C983,239 1008,266 1027,302C1046,337 1056,378 1056,425C1056,480 1042,527 1014,568C986,608 947,636 898,653C848,669 776,677 683,677l-339,0z"/>
+<glyph unicode="C" horiz-adv-x="1479" d="M1204,514l194,-49C1357,306 1284,184 1179,101C1073,17 944,-25 791,-25C633,-25 505,7 406,72C307,136 231,229 180,351C128,473 102,604 102,744C102,897 131,1030 190,1144C248,1257 331,1344 439,1403C546,1462 665,1491 794,1491C941,1491 1064,1454 1164,1379C1264,1304 1334,1199 1373,1064l-191,-45C1148,1126 1099,1203 1034,1252C969,1301 888,1325 790,1325C677,1325 583,1298 508,1244C432,1190 379,1118 348,1027C317,936 302,842 302,745C302,620 320,512 357,419C393,326 449,256 526,210C603,164 686,141 775,141C884,141 976,172 1051,235C1126,298 1177,391 1204,514z"/>
+<glyph unicode="D" horiz-adv-x="1479" d="M158,0l0,1466l505,0C777,1466 864,1459 924,1445C1008,1426 1080,1391 1139,1340C1216,1275 1274,1191 1313,1090C1351,988 1370,872 1370,741C1370,630 1357,531 1331,445C1305,359 1272,288 1231,232C1190,175 1146,131 1098,99C1049,66 991,42 923,25C854,8 776,0 687,0M352,173l313,0C762,173 838,182 893,200C948,218 991,243 1024,276C1070,322 1106,384 1132,462C1157,539 1170,633 1170,744C1170,897 1145,1015 1095,1098C1044,1180 983,1235 911,1263C859,1283 775,1293 660,1293l-308,0z"/>
+<glyph unicode="I" horiz-adv-x="569" d="M191,0l0,1466l194,0l0,-1466z"/>
+<glyph unicode="L" horiz-adv-x="1139" d="M150,0l0,1466l194,0l0,-1293l722,0l0,-173z"/>
+<glyph unicode="P" horiz-adv-x="1366" d="M158,0l0,1466l553,0C808,1466 883,1461 934,1452C1006,1440 1066,1417 1115,1384C1164,1350 1203,1303 1233,1242C1262,1181 1277,1115 1277,1042C1277,917 1237,812 1158,726C1079,639 935,596 728,596l-376,0l0,-596M352,769l379,0C856,769 945,792 998,839C1051,886 1077,951 1077,1036C1077,1097 1062,1150 1031,1194C1000,1237 959,1266 908,1280C875,1289 815,1293 727,1293l-375,0z"/>
+<glyph unicode="S" horiz-adv-x="1366" d="M92,471l183,16C284,414 304,354 336,307C367,260 416,222 483,193C550,164 625,149 708,149C782,149 847,160 904,182C961,204 1003,234 1031,273C1058,311 1072,353 1072,398C1072,444 1059,484 1032,519C1005,553 961,582 900,605C861,620 774,644 639,677C504,709 410,739 356,768C286,805 234,850 200,905C165,959 148,1020 148,1087C148,1161 169,1230 211,1295C253,1359 314,1408 395,1441C476,1474 565,1491 664,1491C773,1491 869,1474 952,1439C1035,1404 1098,1352 1143,1284C1188,1216 1212,1139 1215,1053l-186,-14C1019,1132 985,1202 928,1249C870,1296 785,1320 672,1320C555,1320 469,1299 416,1256C362,1213 335,1161 335,1100C335,1047 354,1004 392,970C429,936 527,901 685,866C842,830 950,799 1009,772C1094,733 1157,683 1198,623C1239,562 1259,493 1259,414C1259,336 1237,263 1192,194C1147,125 1083,71 1000,33C916,-6 822,-25 717,-25C584,-25 473,-6 384,33C294,72 224,130 173,208C122,285 95,373 92,471z"/>
+<glyph unicode="T" horiz-adv-x="1251" d="M531,0l0,1293l-483,0l0,173l1162,0l0,-173l-485,0l0,-1293z"/>
+<glyph unicode="U" horiz-adv-x="1479" d="M1120,1466l194,0l0,-847C1314,472 1297,355 1264,268C1231,181 1171,111 1084,57C997,2 882,-25 741,-25C604,-25 491,-1 404,46C317,93 254,162 217,252C180,341 161,464 161,619l0,847l194,0l0,-846C355,493 367,399 391,339C414,278 455,232 513,199C570,166 641,150 724,150C867,150 968,182 1029,247C1090,312 1120,436 1120,620z"/>
+<glyph unicode="X" horiz-adv-x="1366" d="M9,0l567,764l-500,702l231,0l266,-376C628,1012 668,952 691,910C724,963 762,1019 807,1077l295,389l211,0l-515,-691l555,-775l-240,0l-369,523C723,553 702,586 680,621C647,568 624,531 610,511l-368,-511z"/>
+</font>
+
+	<rect x="7.465" y="10.627" fill="#A0A0A0" stroke="#000000" width="80.473" height="80.473"/>
+<rect x="150.491" y="10.923" fill="#A0A0A0" stroke="#000000" width="80.474" height="80.178"/>
+<rect x="8.479" y="129.379" fill="#A0A0A0" stroke="#000000" width="80.473" height="80.473"/>
+<rect x="150.491" y="129.674" fill="#A0A0A0" stroke="#000000" width="80.474" height="80.178"/>
+<rect x="8.479" y="241.805" fill="#A0A0A0" stroke="#000000" width="80.473" height="80.473"/>
+<rect x="150.491" y="242.1" fill="#A0A0A0" stroke="#000000" width="80.474" height="80.177"/>
+<line fill="none" stroke="#000000" x1="48.716" y1="91.101" x2="48.716" y2="129.379"/>
+<line fill="none" stroke="#000000" x1="88.953" y1="50.864" x2="150.491" y2="51.012"/>
+<line fill="none" stroke="#000000" x1="88.953" y1="169.763" x2="150.491" y2="169.763"/>
+<line fill="none" stroke="#000000" x1="190.729" y1="91.101" x2="190.729" y2="129.379"/>
+<line fill="none" stroke="#000000" x1="48.716" y1="209.852" x2="48.716" y2="241.805"/>
+<line fill="none" stroke="#000000" x1="88.953" y1="282.189" x2="150.491" y2="282.189"/>
+<text transform="matrix(1 0 0 1 23.6948 57.3003)" font-family="'ArialMT'" font-size="18">CPU2</text>
+<text transform="matrix(1 0 0 1 22.3374 174.46)" font-family="'ArialMT'" font-size="18">CPU0</text>
+<text transform="matrix(1 0 0 1 169.082 55.1167)" font-family="'ArialMT'" font-size="18">CPU3</text>
+<text transform="matrix(1 0 0 1 169.082 175.8271)" font-family="'ArialMT'" font-size="18">CPU1</text>
+<text transform="matrix(1 0 0 1 22.6807 277.1895)"><tspan x="0" y="0" font-family="'ArialMT'" font-size="18">PCI-X</tspan><tspan x="0" y="21.601" font-family="'ArialMT'" font-size="18">(8131)</tspan></text>
+<text transform="matrix(1 0 0 1 169.082 275.1895)"><tspan x="0" y="0" font-family="'ArialMT'" font-size="18">  SB</tspan><tspan x="0" y="21.6" font-family="'ArialMT'" font-size="18">(8111)</tspan></text>
+<text transform="matrix(1 0 0 1 93.0947 63.8721)" font-family="'ArialMT'" font-size="10">LDT1</text>
+<text transform="matrix(1 0 0 1 124.5088 46.7715)" font-family="'ArialMT'" font-size="10">LDT1</text>
+<text transform="matrix(1 0 0 1 196.6982 102.9844)" font-family="'ArialMT'" font-size="10">LDT0</text>
+<text transform="matrix(1 0 0 1 161.1953 126.0615)" font-family="'ArialMT'" font-size="10">LDT1</text>
+<text transform="matrix(1 0 0 1 22.3374 126.0615)" font-family="'ArialMT'" font-size="10">LDT2</text>
+<text transform="matrix(1 0 0 1 55.2783 103.5767)" font-family="'ArialMT'" font-size="10">LDT0</text>
+<text transform="matrix(1 0 0 1 52.9111 221.3276)" font-family="'ArialMT'" font-size="10">LDT0</text>
+<text transform="matrix(1 0 0 1 93.0947 181.6719)" font-family="'ArialMT'" font-size="10">LDT1</text>
+<text transform="matrix(1 0 0 1 124.5088 166.2979)" font-family="'ArialMT'" font-size="10">LDT0</text>
+<ellipse fill="#FF0606" cx="150.491" cy="51.012" rx="4.438" ry="4.563"/>
+<ellipse fill="#FF0606" cx="88.953" cy="169.763" rx="4.438" ry="4.563"/>
+<ellipse fill="#FF0606" cx="190.729" cy="129.379" rx="4.438" ry="4.563"/>
+</svg>

firmware/coreboot/Documentation/index.md

@@ -0,0 +1,21 @@
+# Welcome to the coreboot documentation
+
+This is the developer documentation for [coreboot](https://coreboot.org).
+It is built from Markdown files in the
+[Documentation](https://review.coreboot.org/cgit/coreboot.git/tree/Documentation)
+directory in the source code.
+
+Contents:
+
+* [Getting Started](getting_started/index.md)
+* [Rookie Guide](lessons/index.md)
+* [Timestamps](timestamp.md)
+* [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)
+* [ABI data consumption](abi-data-consumption.md)
+* [GPIO toggling in ACPI AML](acpi/gpio.md)
+* [Native Graphics Initialization with libgfxinit](gfx/libgfxinit.md)
+* [Northbridge-specific documentation](northbridge/index.md)
+* [System on Chip-specific documentation](soc/index.md)
+* [Mainboard-specific documentation](mainboard/index.md)
+* [SuperIO-specific documentation](superio/index.md)
+* [Release notes for past releases](releases/index.md)

firmware/coreboot/Documentation/lessons/index.md

@@ -0,0 +1,4 @@
+# Rookie Guide
+
+* [Lesson 1: Starting from scratch](lesson1.md)
+* [Lesson 2: Submitting a patch to coreboot.org](lesson2.md)

firmware/coreboot/Documentation/lessons/lesson1.md

@@ -0,0 +1,168 @@
+coreboot lesson 1 - Starting from scratch
+=========================================
+
+From a fresh Ubuntu 16.04 or 18.04 install, here are all the steps required for
+a very basic build:
+
+Download, configure, and build coreboot
+---------------------------------------
+
+### Step 1 - Install tools and libraries needed for coreboot
+    $ sudo apt-get install -y bison build-essential curl flex git gnat-5 libncurses5-dev m4 zlib1g-dev
+
+### Step 2 - Download coreboot source tree
+    $ git clone https://review.coreboot.org/coreboot
+    $ cd coreboot
+
+### Step 3 - Build the coreboot toolchain
+Please note that this can take a significant amount of time
+
+    $ make crossgcc-i386 CPUS=$(nproc)
+
+Also note that you can possibly use your system toolchain, but the results are
+not reproducible, and may have issues, so this is not recommended.  See step 5
+to use your system toolchain.
+
+### Step 4 - Build the payload - coreinfo
+    $ make -C payloads/coreinfo olddefconfig
+    $ make -C payloads/coreinfo
+
+### Step 5 - Configure the build
+
+##### Configure your mainboard
+    $ make menuconfig
+       select 'Mainboard' menu
+       Beside 'Mainboard vendor' should be '(Emulation)'
+       Beside 'Mainboard model' should be 'QEMU x86 i440fx/piix4'
+       select < Exit >
+These should be the default selections, so if anything else was set, run
+`make distclean` to remove your old config file and start over.
+
+##### Optionally use your system toolchain (Again, not recommended)
+       select 'General Setup' menu
+       select 'Allow building with any toolchain'
+       select < Exit >
+
+##### Select the payload
+       select 'Payload' menu
+       select 'Add a Payload'
+       choose 'An Elf executable payload'
+       select 'Payload path and filename'
+       enter 'payloads/coreinfo/build/coreinfo.elf'
+       select < Exit >
+       select < Exit >
+       select < Yes >
+
+##### check your configuration (optional step):
+
+    $ make savedefconfig
+    $ cat defconfig
+
+There should only be two lines (or 3 if you're using the system toolchain):
+
+    CONFIG_PAYLOAD_ELF=y
+    CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf"
+
+### Step 6 - build coreboot
+    $ make
+
+At the end of the build, you should see:
+
+    Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4)
+
+This means your build was successful. The output from the build is in the build
+directory. build/coreboot.rom is the full rom file.
+
+Test the image using QEMU
+-------------------------
+
+### Step 7 - Install QEMU
+    $ sudo apt-get install -y qemu
+
+### Step 8 - Run QEMU
+Start QEMU, and point it to the ROM you just built:
+
+    $ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio
+
+You should see the serial output of coreboot in the original console window, and
+a new window will appear running the coreinfo payload.
+
+Summary
+-------
+
+### Step 1 summary - Install tools and libraries needed for coreboot
+You installed the minimum additional requirements for ubuntu to download and
+build coreboot. Ubuntu already has most of the other tools that would be
+required installed by default.
+
+* `build-essential` is the basic tools for doing builds.  It comes pre-installed
+on some Ubuntu flavors, and not on others.
+* `git` is needed to download coreboot from the coreboot git repository.
+* `libncurses5-dev` is needed to build the menu for 'make menuconfig'
+* `m4, bison, curl, flex, gnat-5, zlib1g-dev` are needed to build the coreboot
+toolchain.
+
+If you started with a different distribution, you might need to install many
+other items which vary by distribution.
+
+### Step 2 summary - Download coreboot source tree
+This will download a 'read-only' copy of the coreboot tree. This just means
+that if you made changes to the coreboot tree, you couldn't immediately
+contribute them back to the community. To pull a copy of coreboot that would
+allow you to contribute back, you would first need to sign up for an account on
+gerrit.
+
+### Step 3 summary - Build the coreboot toolchain.
+This builds one of the coreboot cross-compiler toolchains for X86 platforms.
+Because of the variability of compilers and the other required tools between
+the various operating systems that coreboot can be built on, coreboot supplies
+and uses its own cross-compiler toolchain to build the binaries that end up as
+part of the coreboot ROM. The toolchain provided by the operating system (the
+'host toolchain') is used to build various tools that will run on the local
+system during the build process.
+
+### Step 4 summary - Build the payload
+To actually do anything useful with coreboot, you need to build a payload to
+include in the rom. The idea behind coreboot is that it does the minimum amount
+possible before passing control of the machine to a payload. There are various
+payloads such as grub or SeaBIOS that are typically used to boot the operating
+system. Instead, we used coreinfo, a small demonstration payload that allows the
+user to look at various things such as memory and the contents of coreboot's
+cbfs - the pieces that make up the coreboot rom.
+
+### Step 5 summary - Configure the build
+This step configures coreboot's build options using the menuconfig interface to
+Kconfig. Kconfig is the same configuration program used by the linux kernel. It
+allows you to enable, disable, and change various values to control the coreboot
+build process, including which mainboard(motherboard) to use, which toolchain to
+use, and how the runtime debug console should be presented and saved.
+Anytime you change mainboards in Kconfig, you should always run `make distclean`
+before running `make menuconfig`. Due to the way that Kconfig works, values will
+be kept from the previous mainboard if you skip the clean step. This leads to a
+hybrid configuration which may or may not work as expected.
+
+### Step 6 summary - Build coreboot
+You may notice that a number of other pieces are downloaded at the beginning of
+the build process. These are the git submodules used in various coreboot builds.
+By default, the BLOBS submodule is not downloaded. This git submodule may be
+required for other builds for microcode or other binaries. To enable downloading
+this submodule, select the option "Allow use of binary-only repository" in the
+"General Setup" menu of Kconfig
+This attempts to build the coreboot rom. The rom file itself ends up in the
+build directory as 'coreboot.rom'. At the end of the build process, the build
+displayed the contents of the rom file.
+
+### Step 7 summary - Install QEMU
+QEMU is a processor emulator which we can use to show coreboot
+
+### Step 8 summary - Run QEMU
+Here's the command line broken down:
+* `qemu-system-x86_64`
+This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to
+ISA bridge.
+* `-bios build/coreboot.rom`
+Use the bios rom image that we just built. If this is left off, the standard
+SeaBIOS image that comes with QEMU is used.
+* `-serial stdio`
+Send the serial output to the console. This allows you to view the coreboot
+debug output.

firmware/coreboot/Documentation/lessons/lesson2.md

@@ -0,0 +1,281 @@
+# coreboot Lesson 2: Submitting a patch to coreboot.org
+
+## Part 1: Setting up an account at coreboot.org
+
+If you already have an account, skip to Part 2.
+
+Otherwise, go to <https://review.coreboot.org> in your preferred web browser.
+Select **Register** in the upper right corner.
+
+Select the appropriate sign-in. For example, if you have a Google account,
+select **Google OAuth2** (gerrit-oauth-provider plugin)".**Note:** Your
+username for the account will be the username of the account you used to
+sign-in with. (ex. your Google username).
+
+## Part 2a: Set up RSA Private/Public Key
+
+If you prefer to use an HTTP password instead, skip to Part 2b.
+
+For the most up-to-date instructions on how to set up SSH keys with Gerrit go to
+<https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.2/user-upload.html#configure_ssh)>
+and follow the instructions there. Then, skip to Part 3.
+
+Additionally, that section of the Web site provides explanation on starting
+an ssh-agent, which may be particularly helpful for those who anticipate
+frequently uploading changes.
+
+If you instead prefer to have review.coreboot.org specific instructions,
+follow the steps below. Note that this particular section may have the
+most up-to-date instructions.
+
+If you do not have an RSA key set up on your account already (as is the case
+with a newly created account), follow the instructions below; otherwise,
+doing so could overwrite an existing key.
+
+In the upper right corner, select your name and click on **Settings**.
+Select **SSH Public Keys** on the left-hand side.
+
+In a terminal, run "ssh-keygen" and confirm the default path ".ssh/id_rsa".
+
+Make a passphrase -- remember this phrase. It will be needed whenever you use
+this RSA Public Key. **Note:** You might want to use a short password, or
+forego the password altogether as you will be using it very often.
+
+Open "id_rsa.pub", copy all contents and paste into the textbox under
+"Add SSH Public Key" in the https://review.coreboot.org webpage.
+
+## Part 2b: Setting up an HTTP Password
+
+Alternatively, instead of using SSH keys, you can use an HTTP password. To do so,
+after you select your name and click on **Settings** on the left-hand side, rather
+than selecting **SSH Public Keys**, select **HTTP Password**.
+
+Click **Generate Password**. This should fill the "Password" box with a password. Copy
+the password, and add the following to your $HOME/.netrc file:
+
+	machine review.coreboot.org login YourUserNameHere password YourPasswordHere
+
+where YourUserNameHere is your username, and YourPasswordHere is the password you
+just generated.
+
+## Part 3: Clone coreboot and configure it for submitting patches
+
+Go to the **Projects** tab in the upper left corner and select **List**.
+From the dropdown menu that appears, select "coreboot".
+
+If you are using SSH keys, select **ssh** from the tabs under "Project coreboot"
+and run the command that appears. This should prompt you for your id_rsa passphrase,
+if you previously set one.
+
+If you are using HTTP, instead, select **http** from the tabs under "Project coreboot"
+and run the command that appears
+
+After it finishes cloning, "cd coreboot" will take you into the local
+git repository. Run "make gitconfig" to set up the hooks and configurations.
+For example, you will be asked to run the following commands to set your
+username and email.
+
+	git config --global user.name "Your Name"
+	git config --global user.email "Your Email"
+
+## Part 4: Submit a commit
+
+An easy first commit to make is fixing existing checkpatch errors and warnings
+in the source files. To see errors that are already present, build the files in
+the repository by running 'make lint' in the coreboot directory. Alternatively,
+if you want to run 'make lint' on a specific directory, run:
+
+	for file in $(git ls-files | grep src/amd/quadcore); do \
+	util/lint/checkpatch.pl --file $file --terse; done
+
+where <filepath> is the filepath of the directory (ex. src/cpu/amd/car).
+
+Any changes made to files under the src directory are made locally,
+and can be submitted for review.
+
+Once you finish making your desired changes, use the command line to stage
+and submit your changes. An alternative and potentially easier way to stage
+and submit commits is to use git cola, a graphical user interface for git. For
+instructions on how to do so, skip to Part 4b.
+
+## Part 4a: Using the command line to stage and submit a commit
+
+To use the command line to stage a commit, run
+
+	git add <filename>
+
+where `filename` is the name of your file.
+
+To commit the change, run
+
+	git commit -s
+
+**Note:** The -s adds a signed-off-by line by the committer. Your commit should be
+signed off with your name and email (i.e. **Your Name** **<Your Email>**, based on
+what you set with git config earlier).
+
+Running git commit first checks for any errors and warnings using lint. If
+there are any, you must go back and fix them before submitting your commit.
+You can do so by making the necessary changes, and then staging your commit again.
+
+When there are no errors or warnings, your default text editor will open.
+This is where you will write your commit message.
+
+The first line of your commit message is your commit summary. This is a brief
+one-line description of what you changed in the files using the template
+below:
+
+<filepath>: Short description
+*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors*
+**Note:** It is good practice to use present tense in your descriptions
+and do not punctuate your summary.
+
+Then hit Enter. The next paragraph should be a more in-depth explanation of the
+changes you've made to the files. Again, it is good practice to use present
+tense.
+*ex.  Fix space prohibited between function name and open parenthesis,
+line over 80 characters, unnecessary braces for single statement blocks,
+space required before open brace errors and warnings.*
+
+When you have finished writing your commit message, save and exit the text
+editor. You have finished committing your change. If, after submitting your
+commit, you wish to make changes to it, running "git commit --amend" allows
+you to take back your commit and amend it.
+
+When you are done with your commit, run 'git push' to push your commit to
+coreboot.org. **Note:** To submit as a draft, use
+'git push origin HEAD:refs/drafts/master' Submitting as a draft means that
+your commit will be on coreboot.org, but is only visible to those you add
+as reviewers.
+
+## Part 4b: Using git cola to stage and submit a commit
+
+If git cola is not installed on your machine, see
+https://git-cola.github.io/downloads.html for download instructions.
+
+After making some edits to src files, rather than run "git add," run
+'git cola' from the command line. You should see all of the files
+edited under "Modified".
+
+In the textbox labeled "Commit summary" provide a brief one-line
+description of what you changed in the files according to the template
+below:
+
+<filepath>: Short description
+*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors*
+**Note:** It is good practice to use present tense in your descriptions
+and do not punctuate your short description.
+
+In the larger text box labeled 'Extended description...' provide a more
+in-depth explanation of the changes you've made to the files. Again, it
+is good practice to use present tense.
+*ex.  Fix space prohibited between function name and open parenthesis,
+line over 80 characters, unnecessary braces for single statement blocks,
+space required before open brace errors and warnings.*
+
+Then press Enter two times to move the cursor to below your description.
+To the left of the text boxes, there is an icon with an downward arrow.
+Press the arrow and select "Sign Off." Make sure that you are signing off
+with your name and email (i.e. **Your Name** **<Your Email>**, based on what
+you set with git config earlier).
+
+Now, review each of your changes and mark either individual changes or
+an entire file as Ready to Commit by marking it as 'Staged'. To do
+this, select one file from the 'Modified' list. If you only want to
+submit particular changes from each file, then highlight the red and
+green lines for your changes, right click and select 'Stage Selected
+Lines'. Alternatively, if an entire file is ready to be committed, just
+double click on the file under 'Modified' and it will be marked as
+Staged.
+
+Once the descriptions are done and all the edits you would like to
+commit have been staged, press 'Commit' on the right of the text
+boxes.
+
+If the commit fails due to persisting errors, a text box will appear
+showing the errors. You can correct these errors within 'git cola' by
+right-clicking on the file in which the error occurred and selecting
+'Launch Diff Tool'. Make necessary corrections, close the Diff Tool and
+'Stage' the corrected file again. It might be necessary to refresh
+'git cola' in order for the file to be shown under 'Modified' again.
+Note: Be sure to add any other changes that haven't already been
+explained in the extended description.
+
+When ready, select 'Commit' again. Once all errors have been satisfied
+and the commit succeeds, move to the command line and run 'git push'.
+**Note:** To submit as a draft, use 'git push origin HEAD:refs/drafts/master'
+Submitting as a draft means that your commit will be on coreboot.org, but is
+only visible to those you add as reviewers.
+
+## Part 5: Getting your commit reviewed
+
+Your commits can now be seen on review.coreboot.org if you select “My”
+and click on “Changes” and can be reviewed by others. Your code will
+first be reviewed by build bot (Jenkins), which will either give you a warning
+or verify a successful build; if so, your commit will receive a +1. Other
+users may also give your commit +1.  For a commit to be merged, it needs
+to receive a +2.**Note:** A +1 and a +1 does not make a +2. Only certain users
+can give a +2.
+
+## Part 6 (optional): bash-git-prompt
+
+To help make it easier to understand the state of the git repository
+without running 'git status' or 'git log', there is a way to make the
+command line show the status of the repository at every point. This
+is through bash-git-prompt.
+
+Instructions for installing this are found at:
+https://github.com/magicmonty/bash-git-prompt
+**Note:** Feel free to search for different versions of git prompt,
+as this one is specific to bash.
+
+Alternatively, follow the instructions below:
+Run the following two commands in the command line:
+
+    cd
+    git clone https://github.com/magicmonty/bash-git-prompt.git .bash-git-prompt --depth=1
+
+**Note:** cd will change your directory to your home directory, so the
+git clone command will be run there.
+
+Finally, open the ~/.bashrc file and append the following two lines:
+
+    GIT_PROMPT_ONLY_IN_REPO=1
+    source ~/.bash-git-prompt/gitprompt.sh
+
+Now, whenever you are in a git repository, it will continuously display
+its state.
+
+There also are additional configurations that you can change depending on your
+preferences. If you wish to do so, look at the "All configs for .bashrc" section
+on https://github.com/magicmonty/bash-git-prompt. Listed in that section are
+various lines that you can copy, uncomment and add to your .bashrc file to
+change the configurations. Example configurations include avoid fetching remote
+status, and supporting versions of Git older than 1.7.10.
+
+## Appendix: Miscellaneous Advice
+
+### Updating a commit after running git push:
+
+Suppose you would like to update a commit that has already been pushed to the
+remote repository. If the commit you wish to update is the most recent
+commit you have made, after making your desired changes, stage the files
+(either using git add or in git cola), and amend the commit. To do so,
+if you are using the command line, run "git commit --amend." If you are
+using git cola, click on the gear icon located on the upper left side under
+**Commit** and select **Amend Last Commit** in the drop down menu. Then, stage
+the files you have changed, commit the changes, and run git push to push the
+changes to the remote repository. Your change should be reflected in Gerrit as
+a new patch set.
+
+If, however, the commit you wish to update is not the most recent commit you
+have made, you will first need to checkout that commit. To do so, find the
+URL of the commit on <https://review.coreboot.org> and go to that page; if
+the commit is one that you previously pushed, it can be found by selecting
+**My** and then **Changes** in the upper left corner. To checkout this commit,
+in the upper right corner, click on **Download**, and copy the command listed
+next to checkout by clicking **Copy to clipboard**. Then, run the copied
+command in your coreboot repository. Now, the last commit should be the most
+recent commit to that patch; to update it, make your desired changes, stage
+the files, then amend and push the commit using the instructions in the above
+paragraph.

firmware/coreboot/Documentation/mainboard/gigabyte/ga-h61m-s2pv.md

@@ -0,0 +1,54 @@
+# Gigabyte GA-H61M-S2PV
+
+This page describes how to run coreboot on the [Gigabyte GA-H61M-S2PV] desktop
+from [Gigabyte].
+
+## Flashing coreboot
+
+```eval_rst
++---------------------+------------+
+| Type                | Value      |
++=====================+============+
+| Socketed flash      | no         |
++---------------------+------------+
+| Model               | MX25L3206E |
++---------------------+------------+
+| Size                | 4 MiB      |
++---------------------+------------+
+| In circuit flashing | yes        |
++---------------------+------------+
+| Package             | SOIC-8     |
++---------------------+------------+
+| Write protection    | No         |
++---------------------+------------+
+| Dual BIOS feature   | Yes        |
++---------------------+------------+
+| Internal flashing   | yes        |
++---------------------+------------+
+```
+
+### Internal programming
+
+The main SPI flash can be accessed using [flashrom].
+
+## Technology
+
+```eval_rst
++------------------+--------------------------------------------------+
+| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
++------------------+--------------------------------------------------+
+| Southbridge      | bd82x6x                                          |
++------------------+--------------------------------------------------+
+| CPU              | model_206ax                                      |
++------------------+--------------------------------------------------+
+| SuperIO          | ITE IT8728F                                      |
++------------------+--------------------------------------------------+
+| EC               |                                                  |
++------------------+--------------------------------------------------+
+| Coprocessor      | Intel ME                                         |
++------------------+--------------------------------------------------+
+```
+
+[Gigabyte GA-H61M-S2PV]: https://www.gigabyte.com/us/Motherboard/GA-H61M-S2PV-rev-10
+[Gigabyte]: https://www.gigabyte.com
+[flashrom]: https://flashrom.org/Flashrom

firmware/coreboot/Documentation/mainboard/hp/compaq_8200_sff.md

@@ -0,0 +1,80 @@
+# HP Compaq 8200 Elite SFF
+
+This page describes how to run coreboot on the [Compaq 8200 Elite SFF] desktop
+from [HP].
+
+## TODO
+
+The following things are still missing from this coreboot port:
+
+- Extended HWM reporting
+- Advanced LED control
+- Advanced power configuration in S3
+
+## Flashing coreboot
+
+```eval_rst
++---------------------+------------+
+| Type                | Value      |
++=====================+============+
+| Socketed flash      | no         |
++---------------------+------------+
+| Model               | MX25L6406E |
++---------------------+------------+
+| Size                | 8 MiB      |
++---------------------+------------+
+| In circuit flashing | yes        |
++---------------------+------------+
+| Package             | SOIC-8     |
++---------------------+------------+
+| Write protection    | No         |
++---------------------+------------+
+| Dual BIOS feature   | No         |
++---------------------+------------+
+| Internal flashing   | yes        |
++---------------------+------------+
+```
+
+### Internal programming
+
+The SPI flash can be accessed using [flashrom].
+
+### External programming
+
+External programming with an SPI adapter and [flashrom] does work, but it powers the
+whole southbridge complex. You need to supply enough current through the programming adapter.
+
+If you want to use a SOIC pomona test clip, you have to cut the 2nd DRAM DIMM holder,
+as otherwise there's not enough space near the flash.
+
+**Position of SOIC-8 flash IC near 2nd DIMM holder**
+![][compaq_8200_flash1]
+
+[compaq_8200_flash1]: compaq_8200_sff_flash1.jpg
+
+**Closeup view of SOIC-8 flash IC**
+![][compaq_8200_flash2]
+
+[compaq_8200_flash2]: compaq_8200_sff_flash2.jpg
+
+## Technology
+
+```eval_rst
++------------------+--------------------------------------------------+
+| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
++------------------+--------------------------------------------------+
+| Southbridge      | bd82x6x                                          |
++------------------+--------------------------------------------------+
+| CPU              | model_206ax                                      |
++------------------+--------------------------------------------------+
+| SuperIO          | :doc:`../../superio/nuvoton/npcd378`             |
++------------------+--------------------------------------------------+
+| EC               |                                                  |
++------------------+--------------------------------------------------+
+| Coprocessor      | Intel ME                                         |
++------------------+--------------------------------------------------+
+```
+
+[Compaq 8200 Elite SFF]: https://support.hp.com/us-en/document/c03414707
+[HP]: https://www.hp.com/
+[flashrom]: https://flashrom.org/Flashrom

firmware/coreboot/Documentation/mainboard/index.md

@@ -0,0 +1,11 @@
+# Mainboard-specific documentation
+
+This section contains documentation about coreboot on specific mainboards.
+
+## SiFive
+
+- [SiFive HiFive Unleashed](sifive/hifive-unleashed.md)
+
+## HP
+
+- [Compaq 8200 Elite SFF](hp/compaq_8200_sff.md)

firmware/coreboot/Documentation/mainboard/sifive/hifive-unleashed.md

@@ -0,0 +1,104 @@
+# SiFive HiFive Unleashed
+
+This page describes how to run coreboot on the [HiFive Unleashed] development
+board from [SiFive], the first RISC-V board on the market with enough resources
+to run a multiuser operating system.
+
+For general setup instructions, please refer to the [Getting Started Guide].
+
+
+## TODO
+
+The following things are still missing from this coreboot port:
+
+- Trampoline in the MBR block to support boot mode 1
+- SiFive UART driver
+- CBMEM support
+- FU540 clock configuration
+- FU540 RAM init
+- Placing the ramstage in DRAM
+- Starting the U54 cores
+- FU540 PIN configuration and GPIO access macros
+- FU540 OTP driver and serial number read-out
+- Support for booting Linux on RISC-V
+
+
+## Configuration
+
+Run `make menuconfig` and select _SiFive_/_HiFive Unleashed_ in the _Mainboard_
+menu.
+
+
+### Boot modes
+
+A total of 16 boot modes can be configured using the switches labeled `MSEL0`
+through `MSEL3`. The most important ones are as follows:
+
+- **MSEL=1**: Jump directly into the SPI flash, bypassing ROM1
+- **MSEL=11**: Load FSBL from SD-card
+- **MSEL=15**: Default boot mode; Load FSBL/coreboot from a GPT partition on
+  SPI flash
+
+
+## Flashing coreboot
+
+The HiFive Unleashed has an 32 MiB SPI flash (**ISSI IS25WP256D**), that can be
+programmed from within Linux running on the board, via USB/JTAG, or directly
+with an SPI programmer.
+
+### Internal programming
+
+The SPI flash can be accessed as `/dev/mtd0` from Linux.
+
+### USB/JTAG
+
+To program the flash via USB/JTAG, connect the USB port to a computer. If the
+board is powered on, two new serial ports, for example `/dev/ttyUSB0` and
+`/dev/ttyUSB1` will appear. The first is JTAG, and the second is connected to
+the SoC's UART.
+
+- Download and build the [RISC-V fork of OpenOCD].
+- Download the [OpenOCD script] for Freedom Unleashed.
+- Start OpenOCD with `openocd -f openocd.cfg`
+- Connect to OpenOCD's command interface (via telnet) and enter the line
+  marked with `> `:
+```
+> flash write_image erase unlock build/coreboot.rom 0x20000000
+auto erase enabled
+auto unlock enabled
+wrote 33554432 bytes from file build/coreboot.rom in 1524.943848s (21.488 KiB/s)
+```
+  Note that programming the whole flash with OpenOCD isn't fast. In this
+  example it took just over 25 minutes. This process can be sped up
+  considerably by building/flashing a smaller image; OpenOCD does not check if
+  the image and the flash have the same size.
+
+
+### External programming
+
+External programming with an SPI adapter and [flashrom] may work, but has not
+been tested. Please study the [schematics] before going this route.
+
+
+## Error codes
+
+The zeroth-stage bootloader (ZSBL) in ROM1 can print error codes on the serial
+console in certain situations.
+
+```
+// Error codes are formatted as follows:
+// [63:60]    [59:56]  [55:0]
+// bootstage  trap     errorcode
+// If trap == 1, then errorcode is actually the mcause register with the
+// interrupt bit shifted to bit 55.
+```
+(--- from the [SiFive forum](https://forums.sifive.com/t/loading-fsbl-from-sd/1156/4))
+
+
+[HiFive Unleashed]: https://www.crowdsupply.com/sifive/hifive-unleashed
+[SiFive]: https://www.sifive.com/
+[Getting Started Guide]: https://www.sifive.com/documentation/boards/hifive-unleashed/hifive-unleashed-getting-started-guide/
+[RISC-V fork of OpenOCD]: https://github.com/riscv/riscv-openocd
+[OpenOCD script]: https://github.com/sifive/freedom-u-sdk/blob/057a47f657fa33e2c60df7f183884a68e90381cc/bsp/env/freedom-u500-unleashed/openocd.cfg
+[flashrom]: https://flashrom.org/Flashrom
+[schematics]: https://www.sifive.com/documentation/boards/hifive-unleashed/hifive-unleashed-schematics/

firmware/coreboot/Documentation/mainboard_io_trap_handler_sample.c

@@ -0,0 +1,51 @@
+/*
+ * This file is part of the coreboot project.
+ *
+ * Copyright (C) 2008-2009 coresystems GmbH
+ * Copyright 2013 Google Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 2 of the License.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ */
+
+#include <arch/io.h>
+#include <console/console.h>
+#include <cpu/x86/smm.h>
+#include <soc/pm.h>
+#include <soc/smm.h>
+#include <elog.h>
+#include <ec/google/chromeec/ec.h>
+#include <soc/gpio.h>
+#include <soc/iomap.h>
+#include <soc/nvs.h>
+#include <soc/pm.h>
+#include <soc/smm.h>
+#include "ec.h"
+#include "gpio.h"
+
+int mainboard_io_trap_handler(int smif)
+{
+       switch (smif) {
+       case 0x99:
+               printk(BIOS_DEBUG, "Sample\n");
+               smm_get_gnvs()->smif = 0;
+               break;
+       default:
+               return 0;
+       }
+
+       /* On success, the IO Trap Handler returns 0
+        * On failure, the IO Trap Handler returns a value != 0
+        *
+        * For now, we force the return value to 0 and log all traps to
+        * see what's going on.
+        */
+       //smm_get_gnvs()->smif = 0;
+       return 1;
+}

firmware/coreboot/Documentation/northbridge/index.md

@@ -0,0 +1,7 @@
+# Northbridge-specific documentation
+
+This section contains documentation about coreboot on specific northbridges.
+
+## Vendor
+
+- [Intel](intel/index.md)

firmware/coreboot/Documentation/northbridge/intel/index.md

@@ -0,0 +1,7 @@
+# Intel Northbridge-specific documentation
+
+This section contains documentation about coreboot on specific Intel Northbridges.
+
+## Platforms
+
+- [Sandy Bridge](sandybridge/index.md)

firmware/coreboot/Documentation/northbridge/intel/sandybridge/index.md

@@ -0,0 +1,7 @@
+# Intel Sandy Bridge-specific documentation
+
+This section contains documentation about coreboot on specific Intel "Sandy Bridge" northbridge.
+
+## Topics
+
+- [Native Ram Initialization](nri.md)

firmware/coreboot/Documentation/northbridge/intel/sandybridge/nri.md

@@ -0,0 +1,135 @@
+# Sandy Bridge Raminit
+
+## Introduction
+
+This documentation is intended to document the closed source memory controller
+hardware for Intel 2nd Gen (Sandy Bride) and 3rd Gen (Ivy Bridge) core-i CPUs.
+
+The memory initialization code has to take care of lots of duties:
+1. Selection of operating frequency
+* Selection of common timings
+* Applying frequency specific compensation values
+* Read training of all populated channels
+* Write training of all populated channels
+* Adjusting delay networks of address and command signals
+* DQS training of all populated channels
+* Programming memory map
+* Report DRAM configuration
+* Error handling
+
+## Definitions
+```eval_rst
++---------+-------------------------------------------------------------------+------------+--------------+
+| Symbol  | Description                                                       | Units      | Valid region |
++=========+===================================================================+============+==============+
+| SCK     | DRAM system clock cycle time                                      | s          |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| tCK     | DRAM system clock cycle time                                      | 1/256th ns |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| DCK     | Data clock cycle time: The time between two SCK clock edges       | s          |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| timA    | IO phase: The phase delay of the IO signals                       | 1/64th DCK | [0-512)      |
++---------+-------------------------------------------------------------------+------------+--------------+
+| SPD     | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes      |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| REFCK   | Reference clock, either 100 or 133                                | Mhz        | 100, 133     |
++---------+-------------------------------------------------------------------+------------+--------------+
+| MULT    | DRAM PLL multiplier                                               |            | [3-12]       |
++---------+-------------------------------------------------------------------+------------+--------------+
+| XMP     | Extreme Memory Profiles                                           |            |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+```
+
+## (Inoffical) register documentation
+- [Sandy Bride - Register documentation](nri_registers.md)
+
+## Frequency selection
+- [Sandy Bride - Frequency selection](nri_freq.md)
+
+## Read training
+- [Sandy Bride - Read training](nri_read.md)
+
+### SMBIOS type 17
+The SMBIOS specification allows to report the memory configuration in use.
+On GNU/Linux you can run `# dmidecode -t 17` to view it.
+Example output of dmidecode:
+
+```
+Handle 0x0045, DMI type 17, 34 bytes
+    Memory Device
+	Array Handle: 0x0042
+	Error Information Handle: Not Provided
+	Total Width: 64 bits
+	Data Width: 64 bits
+	Size: 8192 MB
+	Form Factor: DIMM
+	Set: None
+	Locator: ChannelB-DIMM0
+	Bank Locator: BANK 2
+	Type: DDR3
+	Type Detail: Synchronous
+	Speed: 933 MHz
+	Manufacturer: 0420
+	Serial Number: 00000000
+	Asset Tag: 9876543210
+	Part Number: F3-1866C9-8GSR
+	Rank: 2
+	Configured Clock Speed: 933 MHz
+```
+The memory frequency printed by dmidecode is the active memory frequency. It's
+**not** the double datarate and it's **not** the one encoded maximum frequency
+in each DIMM's SPD.
+
+> **Note:** This feature is available since coreboot 4.4
+
+### MRC cache
+The name *MRC cache* might be missleading as in case of *Native ram init*
+there's no MRC, but for historical reasons it's still named *MRC cache*.
+The MRC cache is part of flash memory that is writeable by coreboot.
+At the end of the boot process coreboot will write the RAM training results to
+flash for future use, as RAM training is time intensive. Storing the results
+allows to boot faster on normal boot and allows to support S3 resume,
+as the RAM training results can't be stored in RAM (you need to configure
+the memory controller first to access RAM).
+
+The MRC cache needs to be invalidated in case the memory configuration has
+been changed. To detect a changed memory configuration the CRC16 of each DIMM
+is stored to MRC cache.
+> **Note:** This feature is available since coreboot 4.4
+
+### Error handling
+As of writing the only supported error handling is to disable the failing
+channel and restart the memory training sequence. It's very likely to succeed,
+as memory channels operate independent of each other.
+In case no DIMM could be initilized coreboot will halt. The screen will stay
+black until you power of your device. On some platforms there's additional
+feedback to indicate such an event.
+
+If you find `dmidecode -t 17` to report only half of the memory installed,
+it's likely that a fatal memory init failure had happened.
+It is assumed, that a working board with less physical memory, is much better,
+than a board that doesn't boot at all.
+
+> **Note:** This feature is available since coreboot 4.5
+
+Try to swap memory modules and or try to use a different vendor. If nothing
+helps you could have a look at capter [Debuggin] or report a ticket
+at [ticket.coreboot.org]. Please provide a full RAM init log,
+that has been captured using EHCI debug.
+
+To enable extensive RAM training logging enable the Kconfig option
+`DEBUG_RAM_SETUP`
+#### Lenovo Thinkpads
+Lenovo Thinkpads do have an additional feature to indicate that RAM init has
+failed and coreboot has died (it calls die() on fatal error, thus the name).
+The Kconfig options
+`H8_BEEP_ON_DEATH`
+`H8_FLASH_LEDS_ON_DEATH`
+enable blinking LEDs and enable a beep to indicate death.
+
+> **Note:** This feature is available since coreboot 4.7
+
+## Debugging
+It's recommended to use an external debugger, such as serial or EHCI debug
+dongle. In case of failing memory init the board might not boot at all,
+preventing you from using CBMEM.

firmware/coreboot/Documentation/northbridge/intel/sandybridge/nri_freq.md

@@ -0,0 +1,165 @@
+# Frequency selection
+
+## Introduction
+This chapter explains the frequency selection done on Sandybride and Ivybridge.
+
+## Definitions
+```eval_rst
++---------+-------------------------------------------------------------------+------------+--------------+
+| Symbol  | Description                                                       | Units      | Valid region |
++=========+===================================================================+============+==============+
+| SCK     | DRAM system clock cycle time                                      | s          |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| tCK     | DRAM system clock cycle time                                      | 1/256th ns |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| DCK     | Data clock cycle time: The time between two SCK clock edges       | s          |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| SPD     | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes      |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| REFCK   | Reference clock, either 100 or 133                                | MHz        | 100, 133     |
++---------+-------------------------------------------------------------------+------------+--------------+
+| MULT    | DRAM PLL multiplier                                               |            | [3-12]       |
++---------+-------------------------------------------------------------------+------------+--------------+
+| XMP     | Extreme Memory Profiles                                           |            |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+```
+## SPD
+The [SPD](https://de.wikipedia.org/wiki/Serial_Presence_Detect "Serial Presence Detect")
+located on every DIMM is factory program with various timings. One of them
+specifies the maximum clock frequency the DIMM should be used with. The
+operating frequency is stores as fixed point value (tCK), rounded to the next
+smallest supported operating frequency. Some
+[SPD](https://de.wikipedia.org/wiki/Serial_Presence_Detect "Serial Presence Detect")
+contains additional and optional
+[XMP](https://de.wikipedia.org/wiki/Extreme_Memory_Profile "Extreme Memory Profile")
+data, that stores so called "performance" modes, that advertises higher clock
+frequencies.
+
+## XMP profiles
+At time of writing coreboot's raminit is able to parse XMP profile 1 and 2.
+Only **XMP profile 1** is being used in case it advertises:
+* 1.5V operating voltage
+* The channel's installed DIMM count doesn't exceed the XMP coded limit
+
+In case the XMP profile doesn't fullfill those limits, the regular SPD will be
+used.
+> **Note:** XMP Profiles are supported since coreboot 4.4.
+
+It is possible to ignore the max DIMM count limit set by XMP profiles.
+By activating Kconfig option `NATIVE_RAMINIT_IGNORE_XMP_MAX_DIMMS` it is
+possible to install two DIMMs per channel, even if XMP tells you not to do.
+
+> **Note:** Ignoring XMP Profiles limit is supported since coreboot 4.7.
+
+## Soft fuses
+Every board manufacturer does program "soft" fuses to indicate the maximum
+DRAM frequency supported. However, those fuses don't set a limit in hardware
+and thus are called "soft" fuses, as it is possible to ignore them.
+
+> **Note:** Ignoring the fuses might cause system instability !
+
+On Sandy Bride *CAPID0_A* is being read, and on Ivybridge *CAPID0_B* is being
+read. coreboot reads those registers and honors the limit in case the Kconfig
+option `CONFIG_NATIVE_RAMINIT_IGNORE_MAX_MEM_FUSES` wasn't set.
+Power users that want to let their RAM run at DRAM's "stock" frequency need to
+enable the Kconfig symbol.
+
+It is possible to override the soft fuses limit by using a board-specific
+[devicetree](#devicetree) setting.
+
+> **Note:** Ignoring max mem freq. fuses is supported since coreboot 4.7.
+
+## Hard fuses
+"Hard" fuses are programmed by Intel and limit the maximum frequency that can
+be used on a given CPU/board/chipset. At time of writing there's no register
+to read this limit, before trying to set a given DRAM frequency. The memory PLL
+won't lock, indicating that the chosen memory multiplier isn't available. In
+this case coreboot tries the next smaller memory multiplier until the PLL will
+lock.
+
+## Devicetree
+The devicetree register `max_mem_clock_mhz` overrides the "soft" fuses set
+by the board manufacturer.
+
+By using this register it's possible to force a minimum operating frequency.
+
+## Reference clock
+While Sandybride supports 133 MHz reference clock (REFCK), Ivy Bridge also
+supports 100 MHz reference clock. The reference clock is multiplied by the DRAM
+multiplier to select the DRAM frequency (SCK) by the following formula:
+
+ REFCK * MULT = 1 / DCK
+
+> **Note:** Since coreboot 4.6 Ivy Bridge supports 100MHz REFCK.
+
+## Sandy Bride's supported frequencies
+```eval_rst
++------------+-----------+------------------+-------------------------+---------------+
+| SCK [Mhz]  | DDR [Mhz] | Mutiplier (MULT) | Reference clock (REFCK) | Comment       |
++============+===========+==================+=========================+===============+
+| 400        | DDR3-800  | 3                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 533        | DDR3-1066 | 4                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 666        | DDR3-1333 | 5                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 800        | DDR3-1600 | 6                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 933        | DDR3-1866 | 7                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 1066       | DDR3-2166 | 8                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+```
+
+## Ivybridge's supported frequencies
+```eval_rst
++------------+-----------+------------------+-------------------------+---------------+
+| SCK [Mhz]  | DDR [Mhz] | Mutiplier (MULT) | Reference clock (REFCK) | Comment       |
++============+===========+==================+=========================+===============+
+| 400        | DDR3-800  | 3                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 533        | DDR3-1066 | 4                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 666        | DDR3-1333 | 5                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 800        | DDR3-1600 | 6                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 933        | DDR3-1866 | 7                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 1066       | DDR3-2166 | 8                | 133 MHz                 |               |
++------------+-----------+------------------+-------------------------+---------------+
+| 700        | DDR3-1400 | 7                | 100 MHz                 | '1            |
++------------+-----------+------------------+-------------------------+---------------+
+| 800        | DDR3-1600 | 8                | 100 MHz                 | '1            |
++------------+-----------+------------------+-------------------------+---------------+
+| 900        | DDR3-1800 | 9                | 100 MHz                 | '1            |
++------------+-----------+------------------+-------------------------+---------------+
+| 1000       | DDR3-2000 | 10               | 100 MHz                 | '1            |
++------------+-----------+------------------+-------------------------+---------------+
+| 1100       | DDR3-2200 | 11               | 100 MHz                 | '1            |
++------------+-----------+------------------+-------------------------+---------------+
+| 1200       | DDR3-2400 | 12               | 100 MHz                 | '1            |
++------------+-----------+------------------+-------------------------+---------------+
+```
+> '1: since coreboot 4.6
+
+## Multiplier selection
+coreboot select the maximum frequency to operate at by the following formula:
+```
+if devicetree's max_mem_clock_mhz > 0:
+     freq_max := max_mem_clock_mhz
+else:
+     freq_max := soft_fuse_max_mhz
+
+for i in SPDs:
+     freq_max := MIN(freq_max, ddr_spd_max_mhz[i])
+```
+
+As you can see, by using DIMMs with different maximum DRAM frequencies, the
+slowest DIMMs' frequency will be selected, to prevent over-clocking it.
+
+The selected frequency gives the PLL multiplier to operate at. In case the PLL
+locks (see Take me to [Hard fuses](#hard_fuses)) the frequency will be used for
+all DIMMs. At this point it's not possible to change the multiplier again,
+until the system has been powered off. In case the PLL doesn't lock, the next
+smaller multiplier will be used until a working multiplier will be found.

firmware/coreboot/Documentation/northbridge/intel/sandybridge/nri_read.md

@@ -0,0 +1,153 @@
+# Read training
+
+## Introduction
+
+This chapter explains the read training sequence done on Sandy Bride and
+Ivy Bridge memory initialization.
+
+Read training is done to compensate the skew between DQS and SCK and to find
+the smallest supported roundtrip delay.
+
+Every board does have a vendor depended routing topology, and can be equip
+with any combination of DDR3 memory modules, that introduces different
+skew between the memory lanes. With DDR3 a "Fly-By" routing topology
+has been introduced, that makes the biggest part of DQS-SCK skew.
+The memory code measures the actual skew and actives delay gates,
+that will "compensate" the skew.
+
+When in read training the DRAM and the controller are placed in a special mode.
+On every read instruction the DRAM outputs a predefined pattern and the memory
+controller samples the DQS after a given delay. As the pattern is known, the
+actual delay of every lane can be measured.
+
+The values programmed in read training effect DRAM-to-MC transfers only !
+
+## Definitions
+```eval_rst
++---------+-------------------------------------------------------------------+------------+--------------+
+| Symbol  | Description                                                       | Units      | Valid region |
++=========+===================================================================+============+==============+
+| SCK     | DRAM system clock cycle time                                      | s          |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| tCK     | DRAM system clock cycle time                                      | 1/256th ns |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| DCK     | Data clock cycle time: The time between two SCK clock edges       | s          |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| timA    | IO phase: The phase delay of the IO signals                       | 1/64th DCK | [0-512)      |
++---------+-------------------------------------------------------------------+------------+--------------+
+| SPD     | Manufacturer set memory timings located on an EEPROM on every DIMM| bytes      |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| REFCK   | Reference clock, either 100 or 133                                | MHz        | 100, 133     |
++---------+-------------------------------------------------------------------+------------+--------------+
+| MULT    | DRAM PLL multiplier                                               |            | [3-12]       |
++---------+-------------------------------------------------------------------+------------+--------------+
+| XMP     | Extreme Memory Profiles                                           |            |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+| DQS     | Data Strobe signal used to sample all lane's DQ signals           |            |              |
++---------+-------------------------------------------------------------------+------------+--------------+
+```
+## Hardware
+The hardware does have delay logic blocks that can delay the DQ / DQS of a
+lane/rank by one or multiple clock cylces and it does have delay logic blocks
+that can delay the signal by a multiple of 1/64th DCK per lane.
+
+All delay values can be controlled via software by writing registers in the
+MCHBAR.
+
+## IO phase
+
+The IO phase can be adjusted in [0-512) * 1/64th DCK. Incrementing it by 64 is
+the same as Incrementing IO delay by 1.
+
+## IO delay
+Delays the DQ / DQS signal by one or multiple clock cycles.
+
+### Roundtrip time
+The roundtrip time is the time the memory controller waits for data arraving
+after a read has been issued. Due to clock-domain crossings, multiple
+delay instances and phase interpolators, the signal runtime to DRAM and back
+to memory controller defaults to 55 DCKs. The real roundtrip time has to be
+measured.
+
+After a read command has been issued, a counter counts down until zero has been
+reached and activates the input buffers.
+
+The following pictures shows the relationship between those three values.
+The picture was generated from 16 IO delay values times 64 timA values.
+The highest IO delay was set on the right-hand side, while the last block
+on the left-hand side has zero IO delay.
+
+#### roundtrip 55 DCKs
+![timA for lane0 - lane3, roundtrip 55][timA_lane0-3_rt55]
+
+[timA_lane0-3_rt55]: timA_lane0-3_rt55.png
+
+#### roundtrip 54 DCKs
+![timA for lane0 - lane3, roundtrip 54][timA_lane0-3_rt54]
+
+[timA_lane0-3_rt54]: timA_lane0-3_rt54.png
+
+
+#### roundtrip 53 DCKs
+![timA for lane0 - lane3, roundtrip 53][timA_lane0-3_rt53]
+
+[timA_lane0-3_rt53]: timA_lane0-3_rt53.png
+
+As you can see the signal has some jitter as every sample was taken in a
+different loop iteration. The result register only contains a single bit per
+lane.
+
+## Algorithm
+### Steps
+The algorithm finds the roundtrip time, IO delay and IO phase. The IO phase
+will be adjusted to match the falling edge of the preamble of each lane.
+The roundtrip time is adjusted to an minimal value, that still includes the
+preamble.
+
+### Synchronize to data phase
+
+The first measurement done in read-leveling samples all DQS values for one
+phase [0-64) * 1/64th DCK. It then searches for the middle of the low data
+symbol and adjusts timA to the found phase and thus the following measurements
+will be aligned to the low data symbol.
+The code assumes that the initial roundtrip time causes the measurement to be
+in the alternating pattern data phase.
+
+### Finding the preamble
+After adjusting the IO phase to the middle of one data symbol the preamble will
+be located. Unlike the data phase, which is an alternating pattern (010101...),
+the preamble consists of two high data cycles.
+
+The code decrements the IO delay/RTT and samples the DQS signal with timA
+untouched. As it has been positioned in the middle of the data symbol, it'll
+read as either "low" or "high".
+
+If it's "low" we are still in the data phase.
+If it's "high" we have found the preamble.
+
+The roundtrip time and IO delay will be adjusted until all lanes are aligned.
+The resulting IO delay is visible in the picture below.
+
+**roundtrip time: 49 DCKs, IO delay (at blue point): 6 DCKs**
+![timA for lane0 - lane3, finding minimum roundtrip time][timA_lane0-3_discover_420x]
+
+[timA_lane0-3_discover_420x]: timA_lane0-3_discover_420x.png
+
+**Note: The sampled data has been shifted by timA. The preamble is now
+in phase.**
+
+## Fine adjustment
+
+As timA still points the middle of the data symbol an offset of 32 is added.
+It now points the falling edge of the preamble.
+The fine adjustment is to reduce errors introduced by jitter. The phase is
+adjusted from `timA - 25` to `timA + 25` and the DQS signal is sampled 100
+times. The fine adjustment finds the middle of each rising edge (it's actual
+the falling edge of the preamble) to get the final IO phase. You can see the
+result in the picture below.
+
+![timA for lane0 - lane3, fine adjustment][timA_lane0-3_adjust_fine]
+
+[timA_lane0-3_adjust_fine]: timA_lane0-3_adjust_fine.png
+
+Lanes 0 - 2 will be adjusted by a phase of -10, while lane 3 is already correct.

firmware/coreboot/Documentation/releases/coreboot-4.1-relnotes.md

@@ -0,0 +1,58 @@
+Announcing coreboot 4.1
+=======================
+
+Dear coreboot community,
+
+It has been more than 5 years since we have "released" coreboot 4.0.
+That last release marked some very important milestones that we
+originally prototyped in the abandoned LinuxBIOS v3 efforts, like the
+coreboot filesystem (CBFS), Kconfig support, and (strictly) separate
+device trees, build logic and configuration.
+
+Since then there have been as many significant original developments,
+such as support for many new architectures (ARM, ARM64, MIPS, RISC-V),
+and related architectural changes like access to non-memory mapped SPI
+flash, or better insight about the internals of coreboot at runtime
+through the cbmem console, timestamp collection, or code coverage
+support.
+
+It became clear that a new release is overdue. With our new release
+process only slowly getting in shape, I decided to take a random commit
+and call it 4.1.
+
+The release itself happens at an arbitrary point in time, but will serve
+as a starting point for other activities that require some kind of
+starting point to build on, described below.
+
+Future releases will happen more frequently, and with more guarantees
+about the state of the release, like having a cool down phase where
+boards can be tested and so on. I plan to create a release every three
+months, so the changes between any two release don't become too
+overwhelming.
+
+With the release of coreboot 4.1, you get an announcement (this email),
+a git tag (4.1), and tar archives at http://www.coreboot.org/releases/,
+for the coreboot sources and the redistributable blobs.
+
+Starting with coreboot 4.1, we will maintain a high level changelog and
+'flag days' document. The latter will provide a concise list of changes
+which went into coreboot that require chipset or mainboard code to
+change to keep it working with the latest upstream coreboot.
+
+For the time being, I will run these efforts, but I'll happily share
+documentation duties with somebody else. It is a great opportunity to
+keep track of things, learn about the project and its design and various
+internals, while contributing to the project without the need to code.
+
+Please contact me (for example by email or on IRC) if you're interested,
+and we'll work out how to collaborate on this.
+
+The process should enable users of coreboot to follow releases if they
+want a more static base to build on, while making it easier to follow
+along with new developments by providing upgrade documentation.
+
+Since moving away from a rolling (non-)release model is new for
+coreboot, things may still be a bit rough around the edges, but I'll
+provide support for any issues that arise from the release process.
+
+Patrick

firmware/coreboot/Documentation/releases/coreboot-4.2-relnotes.md

@@ -0,0 +1,182 @@
+Announcing coreboot 4.2
+=======================
+
+Halloween 2015 release - just as scary as that sounds
+
+Dear coreboot community,
+today marks the release of coreboot 4.2, the second release on our time
+based release schedule. Since 4.1 there were 936 commits by 90 authors,
+increasing the code base by approximately 17000 lines of code. We saw 35
+new contributors - welcome to coreboot! More than 34 developers were
+active as reviewers in that period. Thanks go to all contributors who
+helped shape this release.
+
+As with 4.1, the release tarballs are available at
+http://www.coreboot.org/releases/. There's also a 4.2 tag and branch in
+the git repository.
+
+This marks the first release that features a changelog comparing it to
+the previous release. There was some limited testing to make sure that
+the code is usable, and it boots on some devices. A structured test plan
+will only become part of the release procedure of future versions. I'm
+grateful to Martin for assembling this release's changelog.
+
+This is also the first release that will be followed by the removal of
+old, unused code. There will be a policy on how to announce deprecation
+and removal of mainboard and chipset code for future releases.
+
+Regards,
+Patrick
+
+Log of commit d5e6618a4f076610e683b174c4dd5108d960c785 to
+commit 439a527014fa0cb3e4ef60ba59e5c57c737b4444
+
+Changes between 4.1 and 4.2
+---------------------------
+
+### Build system:
+* Store a minimized coreboot config file in cbfs instead of the full
+  config
+* Store the payload config and revision in CBFS when that info is
+  available
+* Add -compression option for cbfs-files-y. Valid entries are now -file,
+  -type, -align, and -compression
+* Change Microcode inclusion method from building .h files to pre-built
+  binaries
+* Update Builder tests for each commit to test utilities and run lint
+  tools
+* Many other small makefile and build changes and fixes
+* Remove expert mode as a Kconfig option
+
+### Utilities:
+* Many fixes and updates to many utilities (158 total commits)
+* ifdtool: Update for skylake, handle region masks correctly
+* crossgcc: Update to gcc 5.2.0
+* kconfig: Add strict mode to fail on kconfig errors and warnings
+* vgabios: Significant fixes to remove issues in linking into coreboot
+  code
+* Add script to parse MAINTAINERS file
+* Add Kconfig lint tool
+* Create a common library to share coreboot routines with utilities
+
+#### Significant changes and cleanup to cbfstool (81 commits)
+* Update cbfstool to change the internal location of FSP binaries when
+  adding them
+* Decompress stage files on extraction and turn them into ELF binaries
+* Header sizes are now variable, containing extended attributes
+* Add compression tags to all cbfs headers so all cbfs files can be
+  compressed
+* Add and align CBFS components in one pass instead of two
+* Add XIP support for X86 to relocate the romstage when it'™s added
+* Removed locate command as it'™s no longer needed
+* Add bootblock and cbfs_header file types so the master header knows
+  about them
+* Prefer FMAP data to CBFS master header if FMAP data exists
+* Add hashes to cbfs file metadata for verification of images
+
+### Payloads:
+* SeaBIOS: update stable release from 1.7.5 to 1.8.2
+* Libpayload had some significant changes (61 commits). Major changes:
+* Add support for fmap tables
+* Add support for SuperSpeed (3.0) USB hubs
+* Updates and bugfixes for DesignWare OTG controller (DWC2)
+* Add video_printf to print text with specified foreground & background
+  colors
+* Updates to match changes to cbfs/cbfstool
+* Add cbgfx, a library to show graphics and text on a display
+* Read cbfs offset and size from sysinfo when available
+
+### Vendorcode:
+* fsp_baytrail: Support Baytrail FSP Gold 4 release
+* AMD binary PI: add support for fan control
+* Work to get AMD AGESA to compile correctly as 64-bit code
+* Add standalone (XIP) verstage support for x86 to verify romstage
+
+### Mainboards:
+* New Mainboards:
+* apple/macbookair4_2 * Sandy/Ivy Bridge with Panther / Cougar point
+chipset
+* asus/kgpe-d16 - AMD Family 10, SB700/SR5650 platform
+* emulation/spike-riscv - RISCV virtualized platform
+* google/chell - Intel Skylake chrome platform
+* google/cyan - Intel Braswell chrome platform
+* google/glados - Intel Skylake chrome platform
+* google/lars - Intel Skylake chrome platform
+* intel/kunimitsu - Intel Skylake chrome platform
+* intel/sklrvp - Intel Skylake reference platform
+* intel/strago - Intel Braswell chrome platform
+* Cleanups of many mainboards - several patches each for:
+* amd/bettong
+* getac/p470
+* google/auron, google/smaug and google/veyron_rialto
+* pcengines/apu1
+* siemens/mc_tcu3
+* Combine the google/veyron_(jerry, mighty, minnie, pinkie, shark &
+  speedy) mainboards into the single google/veyron mainboard directory
+
+### Console:
+* Add EM100 ˜hyper term" spi console support in ramstage & smm
+* Add console support for verstage
+
+### ARM:
+* armv7: use asm coded memory operations for 32/16 bit read/write
+* Many cleanups to the nvidia tegra chips (40 patches)
+
+### RISC-V:
+* Add trap handling
+* Add virtual Memory setup
+
+### X86:
+* Remove and re-add Rangeley and Ivy Bridge / panther point FSP
+  platforms
+* Update microcode update parser to use stock AMD microcode blobs from
+  CBFS
+* ACPI: Align FACS to 64 byte boundary. Fixes FWTS error
+* AMD/SB700: Init devices in early boot, restore power state after power
+  failure. Add IDE/SATA asl code
+* Add initial support for AMD Socket G34 processors
+* Add tick frequency to timestamp table to calculate boot times more
+  accurately
+* Unify X86 romstage / ramstage linking to match other platforms
+* Start preparing X86 bootblock for non-memory-mapped BIOS media
+* cpu/amd/car: Add Suspend to RAM (S3) support
+* Native VGA init fixes on several platforms
+* Significant updates to FSP 1.1 code for cleanup and cbfstool changes
+* SMMhandler: on i945..nehalem, crash if LAPIC overlaps with ASEG to
+  prevent the memory sinkhole smm hack
+
+### Drivers:
+* Add native text mode support for the Aspeed AST2050
+* w83795: Add support for for fan control and voltage monitoring
+* Intel GMA ACPI consolidation and improvements
+* Set up the 8254 timer before running option ROMs
+* Resource allocator: Page align memory mapped PCI resources
+
+### Lib:
+* Derive fmap name from offset/size
+* Several edid fixes
+* Updates to cbfs matching changes in cbfstool
+
+Submodules:
+----------
+### 3rdparty/blobs:
+Total commits: 16
+Log of commit 61d663e3 to commit aab093f0
+* AMD Merlin Falcon: Update to CarrizoPI 1.1.0.0 (Binary PI 1.4)
+* AMD Steppe Eagle: Update to MullinsPI 1.0.0.A (Binary PI 1.1)
+* Update microcode to binary blobs. Remove old .h microcode files
+
+### 3rdparty/arm-trusted-firmware:
+* No Changes
+
+### 3rdparty/vboot:
+Total commits: 41
+Log of commit fbf631c8 to commit d6723ed1
+* Update the code to determine the write protect line gpio value
+* Several updates to futility and image_signing scripts
+* Update crossystem to accommodate Android mosys location
+* Support reboot requested by secdata
+* Add NV flag to default boot legacy OS
+
+### util/nvidia/cbootimage:
+* No Changes

firmware/coreboot/Documentation/releases/coreboot-4.3-relnotes.md

@@ -0,0 +1,183 @@
+Announcing coreboot 4.3
+=======================
+
+The "Oh, has FOSDEM started?" release
+
+Dear coreboot community,
+
+today marks the release of coreboot 4.3, the third release on our time
+based release schedule. Since the last release, 1030 commits by 114
+authors added a net total of 17500 lines to the source code. Thank you
+to all who contributed!
+
+The release tarballs are available at http://www.coreboot.org/releases/.
+There's also a 4.3 tag and branch in the git repository.
+
+Besides the usual addition of new mainboards (14) and chipsets
+(various), a big theme of the development since 4.2 was cleaning up the
+code: 20 mainboards were removed that aren't on the market for years
+(and even hard to get on Ebay). For several parts of the tree, we
+established tighter controls, making errors out of what were warnings
+(and cleaning up the code to match) and provided better tests for
+various aspects of the tree, and in general tried to establish a more
+consistent structure across the code base.
+
+Besides that, we had various improvements across the tree, each
+important when using the hardware, but to numerous for individual shout
+outs. Martin compiled a list that's best posted verbatim. Thanks Martin!
+
+Log of commit 529fd81f640fa514ea4c443dd561086e7c582a64 to commit
+1bf5e6409678d04fd15f9625460078853118521c for a total of 1030 commits:
+
+Mainboards
+----------
+
+### Added 14 mainboards
+
+* asus/kfsn4-dre_k8: Native init Dual AMD K8 CPUs & Nvidia CK804
+  southbridge
+* esd/atom15: Bay Trail SOC mainboard using Intel's FSP
+* gigabyte/ga-g41m-es2l: Intel Core 2 / Native init x4x NB / I82801GX SB
+* google/guado: Intel Broadwell chromebox (Asus Chromebox CN62)
+* google/oak: Mediatek MT8173 SoC chromebook
+* google/tidus: Intel Broadwell chromebox (Lenovo ThinkCentre Chromebox)
+* google/veyron_emile: Rockchip RK3288 SoC board
+* intel/d510mo: Native init Intel Pineview with Intel I82801GX
+  southbridge
+* intel/littleplains: Intel Atom c2000 (Rangeley) SoC board
+* intel/stargo2: Intel Ivy Bridge / Cave Creek usint Intel's FSP
+* lenovo/r400: Intel Core 2 / Native init GM45 NB / Intel I82801IX SB
+* lenovo/t500: Intel Core 2 / Native init GM45 NB / Intel I82801IX SB
+* purism/librem13: Intel Broadwell Laptop using Intel MRC
+* sunw/ultra40m2: Native init Dual AMD K8 Processors & Nvidia MCP55 SB
+
+### Removed 20 mainboards
+
+* arima/hdama
+* digitallogic/adl855pc
+* ibm/e325, e326
+* intel/sklrvp
+* iwill/dk8s2, dk8x
+* newisys/khepri
+* tyan/s2735, s2850, s2875, s2880, s2881 & s2882
+* tyan/s2885, s2891, s2892, s2895, s4880 & s4882
+
+### Improvements to mainboards
+
+* amd/bettong: fixes to Interrupts, Memory config, S4, EMMC, UARTS
+* asus/kgpe-d16: IOMMU and memory fixes, Add CMOS options, Enable GART
+* intel/strago: GPIO, DDR, & SD config, FSP updates, Clock fixes
+* ACPI fixes across various platforms
+* Many individual fixes to other mainboards
+
+### Continued updates for the Intel Skylake platform
+
+* google/chell, glados, & lars: FSP & Memory updates, Add Fan & NHLT
+  support
+* intel/kunimitsu: FSP & GPIO updates, Add Fan & NHLT (audio) support
+
+Build system
+------------
+* Update build to use FMAP based firmware layout with multiple cbfs
+  sections
+* Enable Kconfig strict mode - Kconfig warnings are no longer allowed.
+* Enable ACPI warnings are errors in IASL - warnings are no longer
+  allowed.
+* Tighten checking on toolchains and give feedback to users if there are
+  issues
+* Updates to get the ADA compiler to work correctly for coreboot
+* Various improvements to Makefiles and build scripts
+* Cleanup of CBFS file handling
+
+Utilities
+---------
+* cleanups and improvements to many of the utilities
+* cbfstool: Many fixes and extensions to integrate with FMAP
+* Add amdfwtool to combine AMD firmware blobs instead of using shell
+  scripts.
+* Toolchain updates: new versions of GMP & MPFR. Add ADA.
+* Updates for building on NetBSD & OS X
+
+Payloads
+--------
+* SeaBIOS: Update stable release to 1.9.0
+* coreinfo: fix date, hide cursor, use crosscompiler to build
+* libpayload: updates for cbfs, XHCI and DesignWare HCD controllers
+
+ARM
+---
+* Added 1 soc: mediatek/mt8173
+* Various fixes for ARM64 platforms
+
+X86
+---
+* Added 2 northbridges: intel/pineview & x4x
+* Removed 1 northbridge: intel/i440lx
+* Added 1 southbridge: intel/fsp_i89xx
+* Removed 2 southbridge(s): intel/esb6300 & i82801cx
+* Rename amd/model_10xxx to family_10h-family_15h.
+* ACPI: fix warnings, Add functions for IVRS, DMAR I/O-APIC and HPET
+  entries
+* Work in many areas fixing issues compiling in 64-bit
+* Numerous other fixes across the tree
+
+Areas with significant work on updates and fixes
+------------------------------------------------
+* cpu/amd/model_fxx
+* intel/fsp1_x: Fix timestanps & postcodes, add native CAR & microcode
+* nb/amd/amdfam10: Add S3, voltage & ACPI, speed fixes & MANY other
+  changes
+* nb/amd/amdmct: Add S3, mem voltage, Fix performance & MANY other
+  changes
+* nb/intel/sandybridge: Add IOMMU & ACPI DMAR support, Memory cleanup
+* soc/intel/braswell: FSP & ACPI updates, GPIO & clock Fixes
+* soc/intel/fsp_baytrail: GPIO, microcode and Interrupt updates.
+* soc/intel/skylake: FSP, Power/Thermal & GPIO Updates, Add NHLT support
+* sb/amd/sb700: Add ACPI & CMOS Setting support, SATA & clock Fixes
+
+MIPS
+----
+* Imgtec Pistachio: Memory, PLL & I2C fixes, add reset
+
+SuperIO
+-------
+* Expand functionality for ite/it8718f & nuvoton/nct5572d superio
+  devices
+
+### Added 3 SIOs
+
+* intel/i8900
+* winbond/w83667hg-a & wpcd376i
+
+### Removed 6 SIOs
+
+* fintek/f71889
+* ite/it8661f
+* nsc/pc8374 & pc97307
+* nuvoton/nct6776
+* smsc/fdc37m60x
+
+Lib
+---
+* Several updates for reading EDID tables
+
+MISC
+----
+* Commonlib: continued updates for cbfs changes
+* Work on getting license headers on all coreboot files
+* Drop the third paragraph of GPL copyright header across all of
+  coreboot
+
+Submodules
+----------
+* 3rdparty/blobs: Update to CarrizoPI 1.1.0.1 (Binary PI 1.5)
+
+coreboot statistics
+-------------------
+Total commits: 1030
+Total authors: 114
+New authors: 46
+Total Reviewers: 41
+Total lines added: 88255
+Total lines removed: -70735
+Total delta: 17520

firmware/coreboot/Documentation/releases/coreboot-4.4-relnotes.md

@@ -0,0 +1,110 @@
+Announcing coreboot 4.4
+=======================
+
+We are happy to announce the release of coreboot 4.4.  This is our
+fourth quarterly release.  Since the last release, we've had 850 commits
+by 90 authors adding 59000 lines to the codebase.
+
+The release tarballs are available at https://www.coreboot.org/releases/
+There is a 4.4 tag and branch in the git repository.
+
+Log of commit 3141eac900 to commit 588ccaa9a7
+
+Major areas that received significant changes in for this release:
+* Build system (30 commits) - Add postcar stage, 'timeless' builds,
+  extend site-local, test toolchain by version string, update
+  dependencies, catch ACPI errors, add additional macros.
+* Toolchain updates (40+ patches) - Update IASL to v20160318 , LLVM to
+  v3.7.1, add GNU make, add nds32le GCC compiler
+* Lint tools (30 patches) - Update existing lint utilities, add lint
+  tests for executable bit, make sure site-local isn't committed, add
+  test to break all lint tests.
+* Payloads (60 commits) - Fixes for libpayload, coreinfo and nvramcui,
+  add new payloads, see below.
+* Maintainers file - (8 patches) - continue adding maintainers for
+  various areas.
+* Documentation for adding Intel FSP-based platforms (20 commits)
+
+Mainboards
+----------
+### Added 9 mainboards
+* asus/kcma-d8
+* emulation/qemu-power8
+* google/auron_paine
+* google/gru
+* intel/amenia
+* intel/apollolake_rvp
+* intel/camelbackmountain_fsp
+* intel/galileo
+* lenovo/t420
+
+### Existing boards with significant updates
+* asus/kgpe-d16
+* google/oak
+* google/chell
+* intel/kunimitsu
+
+Changes in chips
+----------------
+### Added 1 new architecture
+* power8
+
+### Added 1 processor
+* qemu-power8
+
+### Added 5 socs
+* intel/apollolake
+* intel/fsp_broadwell_de
+* intel/quark
+* marvell/armada38x
+* rockchip/rk3399
+
+### Existing chip areas with many changes
+* cpuamd/mct_ddr3
+* drivers/intel/fsp2_0
+* northbridge/intel/sandybridge/raminit
+* soc/intel/apollolake
+* soc/intel/fsp_baytrail
+* soc/intel/skylake
+* soc/mediatek/mt8173
+
+### Added 1 new vendorcode directory
+* siemens
+
+Submodules
+----------
+### Added 1 submodule
+* chromeec
+
+### Updated 3 submodules
+* 3rdparty/arm-trusted-firmware (329 commits)
+* 3rdparty/vboot (28 commits)
+* util/nvidia/cbootimage (13 commits)
+
+Other
+-----
+### Added 4 payloads
+* depthcharge: For ChromeOS verified boot
+* iPXE: For network booting
+* Memtest86+: Updated with fixes for correctly testing coreboot with
+  payloads
+* U-Boot (Experimental): Alternate payload for booting an OS
+
+### Added 6 utilities
+* archive - Concatenates files into a single blob with an indexed header
+* chromeos - Download and extract blobs from a ChromeOS image
+* futility - vboot Firmware utility
+* intelmetool - Shows information about the Intel ME on a platform.
+* marvell/doimage_mv - No usage notes
+* post - Simple utility to test post cards
+
+coreboot statistics
+-------------------
+* Total Commits:          850
+* Total authors:           90
+* New authors:             28
+* Total Reviewers:         40
+* Total Submitters:        17
+* Total lines added:    74054
+* Total lines removed: -15056
+* Total difference:     58998

firmware/coreboot/Documentation/releases/coreboot-4.5-relnotes.md

@@ -0,0 +1,214 @@
+Announcing coreboot 4.5
+=======================
+
+We are happy to announce the release of coreboot 4.5
+
+The 4.5 release covers commit 80a3df260767 to commit 0bc12abc2b26.
+
+This release is the first since the project switched from doing
+quarterly releases to doing biannual releases.  The next release will be
+in April of 2017.
+
+Since the last release in April, the coreboot project has had 1889
+commits by 119 authors.
+
+The release tarballs and gpg signatures are available in the usual place
+at https://www.coreboot.org/downloads
+
+There is a 4.5 tag in the git repository, and a branch will be created
+as needed.
+
+
+Areas with significant updates
+------------------------------
+
+### Toolchain (29 commits)
+* Updated mpfr version from 3.1.3 to 3.1.4
+* Updated gcc version from 5.2.0 to 5.3.0
+* Updated binutils version from 2.25 to 2.26.1 & Fix aarch64 build
+  problem
+* Updated gdb version from 7.9.1 to 7.11
+* Updated iasl version from 20160318 to 20160831
+* Updated python version from 3.4.3 to 3.5.1
+* Updated expat version from 2.1.0 to 2.1.1
+* Updated llvm / clang version from 3.7.1 to 3.8.0
+* Updated make version from 4.1 to 4.2.1
+
+### Build system (32 commits)
+* Updates for cbfstool / fmap changes
+* Order per-region files to optimize placement success
+* Add support for the ADA language and toolchain.
+
+### Utilities (103 commits)
+* Lint - Update checkpatch.pl, add tools  to find non-ascii &
+  unprintable chars and to verify a single newline at the end of files
+* cbfstool - Update for Linux payloads, Honor FSP modules addresses, fix
+  elf parsing
+* Sconfig - Add 10 bit addressing mode for i2c devices, add generic
+  device type, support strings, pass in devicetree filename
+* General code cleanup (197 commits)
+* Cleaning up code formatting and whitespace
+* Fix spelling & capitalization
+* Removing commented out code
+* Transition away from device_t
+
+### TPM (55 commits)
+* Add support for Trusted Platform Module 2.0
+* SPI & refactored I2C TPM driver
+
+### Drivers (54 commits)
+* Add ACPI support in several drivers
+* coreboot_tables -  Extend serial port description
+* Elog - refactor, add debug info
+* I2C - add generic driver,
+* SPI - Add new chip support, major refactoring, don't assume SPI flash
+  boot device
+
+### Lib (33 commits)
+* Add real-time-clock functions
+* Add RW boot device construct
+* reg_script updates: add to bootblock, add xor support, add display
+  support
+* Timestamp fixes & updates
+
+### Vendorcode
+* AMD (14 commits) - Cleanup, add libagesa.a builds, remove unused code.
+* Google (22 commits) - VBoot2 updates and cleanup
+* Intel (86 commits) - Add Intel FSP 2.0, update Broadwell DE support
+
+### Payloads (37 commits)
+* Subpayload support got extend and is enabled by default.
+* nvramcui: refactor, update build
+* SeaBIOS: Update stable version to 1.9.3, add bootorder file
+* iPXE: Update stable version to the last commit of July 2016
+* Fix broken linux boot sequence
+
+Mainboard changes
+-----------------
+
+### Added 13 mainboards, plus a few mainboard variants not included here
+* ADI RCC-DFF networking board (adi/rcc-dff) - intel/rangeley SoC
+* AMD Evaluation Board DB-FT3B-LC (amd/db-ft3b-lc) - amd/00730F01
+  (Family 16h  Models 30h-3Fh (Mullins)) CPU
+* AMD f2950 / TONK 1201/2 Board (amd/f2950) - amd/geode_lx CPU
+* Apple iMAC 5.2 (apple/imac52) - intel/i945 CPU
+* Unibap Development Kit ODE E21XX - amd/00730F01 (Family 16h Models
+  30h-3Fh (Mullins)) CPU
+* elmex/pcm205400 - amd/Family_14 CPU
+* elmex/pcm205401 - amd/Family_14 CPU
+* Lenovo N21 chromebook (google/enguarde) - intel/baytrail SoC
+* google/gale - Qualcomm IPQ40XX SoC
+* AOpen Chromebox (google/ninja) - intel/baytrail SoC
+* google/reef - intel/apollolake SoC
+* Acer Chromebox CXI2 (google/rikku) - intel/Broadwell SoC
+* google/rotor - marvell/MVMAP2315 SoC
+
+### Removed 5 mainboards:
+These were all development boards not available to the public.
+* google/bolt - intel/haswell - removed in commit 139314b
+* google/rush - nvidia/tegra132 - removed in commit e67cd9e
+* google/rush_ryu - nvidia/tegra132 - removed in commit 0c63415
+* google/slippy - intel/haswell - removed in commit bc24b85
+* intel/amenia - intel/apollolake - removed in commit c2586db
+
+### Existing boards with significant updates
+* asus/kgpe-d16 - amd/socket_G34 - Add TPM support, enable secondary
+  serial port
+* emulation/spike-riscv: RISC-V -clean up, use generic bootblock, look
+  for  CBFS in RAM, reimplement SBI
+* google/gru - rockchip/RK3399 SoC (76 commits) - Board bringup
+* google/oak - mediatek/mt8173 SoC- Add Elm variant, update memory,
+  configure display, initialize touchscreen gpio
+* intel/galilleo- intel/quark SoC (14 commits) - Board bringup, add
+  galileo gen1 support, switch to FSP2.0
+* intel/minnowmax - intel/fsp_baytrail SoC - Enable all PCIe ports,
+  Program GPIO for power LED
+* lenovo/x60 - intel/socket_mPGA478 - init GPIOs before dock check, add
+  hda verb table
+* siemens/mc_bdx1 - intel/fsp_broadwell_de SoC - Add external RTC, Set
+  up MAC addresses, Update IRQs
+* siemens/mc_tcu3 - intel/fsp_baytrail SoC - cleanup & LCD panel updates
+
+Changes in chips
+----------------
+### Moved 3 northbridge/southbridge pairs to soc:
+* dmp/vortex86ex
+* intel/sch
+* rdc/r8610
+
+### Added 2 socs:
+* marvell/mvmap2315 (12 commits)
+* qualcomm/ipq40xx (22 commits)
+
+### Removed 1 soc:
+* nvidia/tegra132 - removed in commit 9ba0699
+
+### Added 2 sios:
+* nuvoton/nct6776
+* nuvoton/nct6791d
+
+### ARM (34 commits)
+* Add armv7-r configuration
+
+#### rockchip/rk3399 (73 commits)
+* Bringup, memory updates
+
+### RISC-V (40 commits)
+* Improve and refactor trap handling
+
+### X86 (225 commits)
+
+### ACPI (40 commits)
+* Add support for writing various entries and descriptor
+  types, Add common definitions, Use 'GOOG' id for coreboot table
+* amd/mct_ddr3 northbridge: Support non-ECC DIMMs, Update SMBIOS,
+  various fixes
+* arch/x86: many postcar stage updates, add common ACPI definitions,
+  Support "weak" BIST and timestamp save routines
+* intel/apollolake SoC (211 commits) - Chip bringup, Update bootblock
+* intel/common: ACPI updates, Add smihandler, LPSS I2C driver, and  IGD
+  OpRegion support
+* intel/fsp_broadwell_de: IRQ fixes, SPI message fixes, Add DMAR table
+  to ACPI
+* intel/gm45 northbridge: Fix text mode init, enable vesa framebuffer,
+  use VGA if connected
+* intel/i945 northbridge: add native VGA init, Update divisor
+  calculations
+* intel/quark SoC (62 commits) - Chip bringup, add Fsp2.0 support,
+  updates for serial console
+* intel/skylake CPU (61 commits) - Finished Skylake bringup, start
+  updating for Kabylake FSP
+* intel/x4x northbridge (13 commits) - Memory & Graphics updates
+
+Submodules
+----------
+Updated 4 submodules
+* 3rdparty/blobs (6 commits)
+* 3rdparty/arm-trusted-firmware (425 commits)
+* 3rdparty/vboot (61 commits)
+* 3rdparty/chromeec/ (676 commits)
+
+Tested boards
+-------------
+The following boards were tested for this release:
+* asrock/e350m1                 4.4-1890
+* asus/kfsn4-dre                4.4-1698 / 4.5-17
+* asus/kgpe-d16                 4.4-1802 / 4.5-17
+* emulation/qemu-q35            4.4-1698 / 4.5-8
+* gigabyte/ga-b75m-d3v          4.4-1757
+* google/peppy                  4.4-1882
+* lenovo/g505s                  4.4-1739
+* lenovo/x201                   4.4-1886
+* lenovo/x220                   4.4-1746 / 4.5-17
+
+coreboot statistics
+-------------------
+* Total Commits:            1889
+* Average Commits per day: 10.92
+* Total authors:             119
+* New authors:                47
+* Total Reviewers:            67
+* Total Submitters:           19
+* Total lines added:      164950
+* Total lines removed:   -182737
+* Total difference:       -17787

firmware/coreboot/Documentation/releases/coreboot-4.6-relnotes.md

@@ -0,0 +1,486 @@
+Announcing coreboot 4.6
+=======================
+
+We are happy to announce the April 2017 release of coreboot, version
+4.6.
+
+The 4.6 release covers commit e74f5eaa to commit db508565
+
+Since the last release in October 2016, the coreboot project had 1708
+commits by 121 authors. The release tarballs and gpg signatures are
+available in the usual place at https://www.coreboot.org/downloads
+
+There is a pgp signed 4.6 tag in the git repository, and a branch will
+be created as needed.
+
+Changes: Past, ongoing, and future
+----------------------------------
+
+### CBMEM console development and the Linux Kernel
+
+Our cbmem debug console was updated with some nice features. The cbmem
+console now persists between reboots and is able to be used on some
+platforms via late init. Also there is a new Linux kernel driver which
+removes the need for the old cbmem tool to read from the cbmem area. You
+can find the patch here https://patchwork.kernel.org/patch/9641997/ and
+it can be enabled via GOOGLE_MEMCONSOLE_COREBOOT kconfig option in your
+kernel - Note that this name may change going forward.
+
+### Critical bugs in TPM 1.2 support
+
+coreboot currently has issues with the TPM 1.2 LPC driver
+implementation. This leads to a misbehavior in SeaBIOS where the TPM
+gets temporarily deactivated. We plan to publish the bugfix release
+4.6.1 when we have these issues sorted out.
+
+### Native graphics and ram init improvements
+
+The native graphics was reworked a while ago and should finally support
+Windows. Numerous bug fixes and EDID support is also now available.
+Finally, the native ram initialization for sandybridge/ivybridge
+platforms got patched and supports more RAM modules.
+
+### New and fresh payloads
+
+SeaBIOS, FiLO, and iPXE were all recently updated to the latest
+versions. Https downloads are the default for all payloads now. We
+provide the libpayload project which is used for writing own payloads
+from scratch. The library is MOSTLY licensed under BSD and recently
+received new functionality in order to prepare for the upcoming
+replacement for the old nvramcui payload. This new payload is called
+cbui and is based on the nuklear graphics library including keyboard and
+mouse support. The cbui payload is currently expected to be merged into
+the main coreboot tree before the next release.  The upstream repository
+is here: https://github.com/siro20/coreboot/tree/cbui/payloads/cbui
+
+### UEFI support: A long road to go
+
+coreboot can be used with the Tianocore EDK2 UEFI implementation which
+is open source and available at Github. Sadly it is not currently
+integrated into the coreboot build. This has several reasons:
+
+* EDK2 only supports GCC 4.8 profile. coreboot is now running on GCC 6.3.0.
+* Incompatibilities with code inside the EDK2 which has not been updated.
+
+We started to make progress with the integration into our sources and
+the hope is that by the end of the summer, we finally support the EDK2
+payload out-of-the- box. See the current patch state at
+http://review.coreboot.org/#/c/15057/
+
+### Fighting blobs and proprietary HW components
+
+coreboot's ultimate goal would be to replace any closed source firmware
+stack with free software components. Unfortunately this is not always
+possible due to signed binaries such as the Intel ME firmware, the AMD
+PSP and microcode. Recently, a way was discovered to let the Intel ME
+run in a functional error state and reduce it from 1.5/5MB to 80KB. It's
+not perfect but it works from Nehalem up to Skylake based Intel systems.
+The tool is now integrated into the coreboot build system. The upstream
+repository is https://github.com/corna/me_cleaner
+
+Another ongoing improvement is the new utility blobtool. It is currently
+used for generating the flash descriptor and GbE configuration data on
+older mainboard which are known to be free software. It can easily be
+extended for different binaries with well-defined specifications.
+
+### Did you say Ada?
+
+coreboot now supports Ada, and a lot work was done integrating Ada into
+our toolchain. At the moment only the support for formal verification is
+missing and will be soon added. At that point, we can prove the absence
+of runtime errors in our Ada code. In short, everybody can start
+developing Ada code for our project.
+
+The existing Ada code which can be used from now on is another native
+graphics initialization which will replace in the long term the current
+implementation. The native graphics code supports all Intel platforms up
+to skylake. We offer support for HDMI, VGA, DVI and DP external
+interfaces as well and is ready to be integrated into our mainboard
+implementations.
+
+### Toolchain updates
+
+A new coreboot toolchain is out. The major toolchain change was going
+from GCC version 5.3.0 to 6.3.0. There were also minor version updates
+to GMP, MPFR, Binutils, GDB, IASL, and Clang.
+
+### Deprecation policy for boards
+
+Starting with this release there will be a policy for deprecating
+unmaintained boards. See the end of this announcement for details.
+
+Change Summary
+--------------
+
+Build system (20 commits)
+* Clean up Kconfig
+* Show more useful error messages
+
+Codebase cleanup (94 commits)
+* Many fixes for files to pass checkpatch. Lots more to do here.
+* Remove commented out code
+* Updates to transition away from device_t
+* Work to get rid of included C files
+
+Documentation (6 commits)
+* Start adding technotes/Design docs
+* Add Kconfig documentation
+
+ACPI & acpigen library
+* Add GPIO macros
+* Clean up and add more functions to ACPIGEN library
+
+EC (26 commits)
+* Add roda/it8518 embedded controller
+
+TPM (41 commits)
+* Cleanup
+* Update ACPI ASL, Runtime generate ACPI table for TPM driver
+* Make SPI TPM driver CAR-safe
+* Update TPM init sequence
+
+Devices (24 commits)
+* Add a new SPI device type
+* Allow devicetree accesses in postcar stage
+* PCIEXP_ASPM: Unify code with other PCI-e tuning
+
+Lib (28 commits)
+* Add option to use Ada code in ramstage
+* bootstate: add arch specific hook at coreboot exit
+* cbfs: Add API to locate a file from specific region
+* Add library to handle SPD data in CBFS or DIMM
+* Add region file support
+* Turn CBMEM console into a ring buffer that can persist across reboots
+
+Commonlib (11 commits)
+* Add xmalloc, xzmalloc and dma routines
+* Add input and output buffer helpers
+
+Drivers (29 commits)
+* i2c: Pass in i2c_generic_config into i2c_generic_fill_ssdt
+* i2c/alps: Add support for ALPS Touchpad driver
+* i2c/generic: Add support for GPIO IRQ
+* i2c/generic: Enable support for adding PowerResource for device
+* i2c/hid: Add generic I2C HID driver
+* i2c/max98927: add i2c driver for Maxim 98927 codec
+* i2c/wacom_ts: Add support for WCOM touchscreen device driver
+* pc80/rtc: Check cmos checksum BEFORE reading cmos value
+* regulator: Add driver for handling GPIO-based fixed regulator
+* storage: Add SD/MMC/eMMC driver based upon depthcharge
+
+SPI interface
+* Significant cleanup and refactoring
+
+Include (17 commits)
+* cpu/intel: Add MSR to support enabling turbo frequency
+* elog: Add all EC event codes
+
+SuperIO (12 commits)
+* Updates for ITE SIOs
+* Add 2 new chips
+* Consolidate code to use common routines
+
+Vboot (23 commits)
+* Add support for recovery hash space in TPM
+
+RISC-V (25 commits)
+* Add lowRISC System On Chip support
+* Cbmem patches, move to common architectural code
+
+ARM (16 commits)
+* Init new serial struct variables for samsung exynos5420 & allwinner
+  a10
+* Fix verstage to use proper assembly versions of mem*()
+
+RockChip RK3399 & platforms (46 commits)
+* Memory, I2C, USB, SD & Display fixes
+
+X86 Intel (193 commits)
+* Broadwell/Sata: Add support for setting IOBP registers for Ports 2 and
+  3.
+* cpu/intel/common: Add/Use common function to set virtualization
+* drivers/intel/fsp1_1: Fix boot failure for non-verstage case
+* drivers/intel/fsp2_0: Reset on invalid stage cache.
+* drivers/intel/gma: Add textmode using libgfxinit & use scaling to
+  simplify  config
+* drivers/intel/mipi_camera: Add MIPI CSI camera SSDT generator
+* broadwell_de: Add SMM code
+* intelblocks/msr: Move intel x86 MSR definition into common location
+* intel/broadwell: Use the correct SATA port config for setting IOBP
+  register
+* intel/wifi: Create ACPI objects for wifi SAR configuration
+* lynxpoint bd82x6x: Enable PCI-to-PCI bridge
+* mrc: Add support for separate training cache in recovery mode
+* nb/i945/early_init.c: Add FSB800 and 1067 to Egress Port Virtual
+  Channel
+* nb/i945/raminit: Add fixes for 800MHz & 1067MHz FSB CPUs
+* nb/intel/gm45: Fix panel-power-sequence clock divisor
+* nb/intel/i945: Fix PEG port on 945gc & sdram_enhanced_addressing for
+  channel1
+* nb/intel/pineview: Move to early cbmem
+* nb/pineview/raminit: Skip Jedec init on resume, fix hot reset path
+* nb/intel/sandybridge/gma: Always initialize DP buffer translation
+* sb/ich7: Use common/gpio.h to set up GPIOs
+* sb/intel/bd82x6x: Add TCO_Lock in finalize step
+* sb/intel/common/gpio: Support ICH9M and prior
+* sb/intel/i82801gx: Add i2c_block_read to smbus.h
+
+sandybridge/raminit
+* Fix CAS Write Latency, disable_channel, normalize_training & odt stretch
+* Separate Sandybridge and Ivybridge
+* Reset internal state on fallback attempts
+* Find CMD rate per channel
+
+soc/intel/common
+* Add common routines for HECI, ITSS, PCR, RTC, systemagent, UART, XHCI,
+& LPSS
+* Save Memory DIMM Information in SMBIOS table
+
+Apollolake (183 commits)
+* Switch to common routines for LPSS, RTC, ITSS, UART, XHCI, & PCR
+* Enable turbo
+* Add save/restore variable MRC cache
+* Allow ApolloLake SoC to use FSP CAR Init
+* Allow USB2 eye pattern configuration in devicetree
+
+Quark & platforms (14 commits)
+* Fix I2c & Serial port config
+* Add vboot support
+
+ga-g41m-es2l, x4x northbridge & LGA775 (23 commits)
+* Memory fixes
+* Add S3 suspend/resume
+
+Skylake / Kabylake (208 commits)
+* Add devicetree settings for acoustic noise mitigation
+* Perform CPU MP Init before FSP-S Init
+* Add support for GSPI controller & add GSPI controller get_config
+support
+* Enable Systemagent IMGU
+* Add USB Port Over Current support & Expand USB OC pins support PCH-H
+* Extract DIMM Information from FSP MEM INFO HOB
+* Add support for eSPI SMI events
+* Update ACPI & various methods
+
+X86 amd (116 commits)
+* ACPI S3: Remove HIGH_MEMORY_SAVE where possible
+* AMD fam10 binaryPI: Remove invalid PCI ops on CPU domain
+* binaryPI platforms: Drop ACPI S3 support
+* sb/amd/sb700: Disable LPC ROM mapping when SPI Flash is used
+* southbridge/amd: Add LPC bridge acpi path for Family14 and SB800
+* arch/x86: remove CAR global migration when postcar stage is used
+* x86/acpi: Add VFCT table
+
+AMD: vendorcode, AGESA, binaryPI (72 commits)
+* Cleanup & consolidate duplicate code
+* Fork for new cache-as-ram init code & Fix binaryPI cache-as-ram
+* Refactor S3 support functions and Delay ACPI S3 backup until ramstage
+  loader
+
+amd/mct:
+* Fix CsMux45 configuration, maximum read latency, & DQ mask calculation
+
+Mainboards (198 commits)
+* asus/f2a85-m_le: Activate IOMMU support
+* lenovo/h8: Add USB Always On
+* google/oak: Enable dual DSI for rowan and the BOE 8-lane MIPI/DSI panel
+* google/parrot: Fix keyboard interrupts, DSDT
+* google/veyron: Work around RAM code strapping error
+* lenovo/t400: Rewrite dock from t60
+* intel/d510mo: enable ACPI resume from S3
+* intel/d945gclf: Fix resume from S3 suspend
+* lenovo/t400: Implement hybrid graphic in romstage
+* Enable libgfxinit on lenovo/t420 & x230, kontron/ktqm77, google/slippy
+* lenovo/x60,t60: Move EC CMOS parameters in checksummed space
+* mc_tcu3: Do not abort initialization of PTN3460 when HW-ID is missing
+* mc_tcu3: Swap LVDS even and odd lanes for a certain hardware
+* purism/librem13: Enable support for M.2 NVMe & Fix M.2 issues
+
+Payloads (53 commits)
+* Update FILO, SeaBIOS, & iPXE versions
+* Many libpayload fixes and updates
+
+Toolchain (19 commits)
+* Update GCC, Binutils, GMP, MPFR, GDB, IASL and LLVM
+
+Utilities: (145 commits)
+* abuild: Build saved config files and print failed builds at the end
+* autoport: Create superiotool logs and fix romstage generator
+* board-status: Update bucketize script and add README file
+* cbfstool: Add cbfs-compression-tool and enable adding precompressed
+  files
+* cbmem: Add custom aligned memcpy() implementation
+* ectool: Fix timeout on sending EC command and support OpenBSD
+* ifdtool: Fix ICH Gbe unlock
+* intelmetool: Add support for Wildcat Point LP, fix segfault on edge
+  cases
+* inteltool: Add support for CH6-10, ICH10, Wildcat Point-LP and fix ICH
+SPIBAR
+* sconfig: Add a new SPI device type
+* superiotool: Add new chips - IT8783E/F, W83627DHG, W83627EHG, F71808A
+
+Changes in chips
+----------------
+
+Added 1 processor & northbridge:
+* amd/pi/00670F00
+
+Added 1 soc:
+* lowrisc/lowrisc
+
+Removed 1 northbridge:
+* intel/e7501
+
+Added 2 sios:
+* fintek/f71808a
+* ite/it8783ef
+
+Mainboard changes
+-----------------
+
+Added 52 mainboards and variants:
+* AMD Gardenia - AMD Stoney Ridge
+* Asus F2A85_M_PRO - AMD Family 15h Trinity
+* Asus P5GC_MX - Intel Socket LGA775
+* Gigabyte GA_945GCM_S2L & GA_945GCM_S2C variant - Intel Socket LGA775
+* Google Auron variants: Yuna, Gandof, Lulu - Intel Broadwell
+* Google Beltino variants: McCloud, Monroe, Tricky, Zako - Intel Haswell
+* Google Eve - Intel Kabylake
+* Google Fizz - Intel Kabylake
+* Google Gru variants: Bob, Scarlet - RockChip RK3399
+* Google Oak variants: Hana, Rowan - MediaTek MT8173
+* Google Poppy & Soraka variant - Intel Kabylake
+* Google Rambi variants: Banjo, Candy, Clapper, Glimmer, Gnawty, Heli,
+  Kip, Orco, Quawks, Squawks, Sumo, Swanky, & Winky - Intel Baytrail
+* Google Reef variants: Sand, Snappy, Nasher - Intel Apollolake
+* Google Slippy variants: Leon, Wolf - Intel Haswell
+* Intel KBLRVP3 & KBLRVP7 - Intel Kabylake
+* Intel LEAFHILL - Intel Apollolake
+* Intel MINNOW3 - Intel Apollolake
+* Lenovo L520: Intel Sandybridge
+* Lenovo S230U: Intel Ivybridge
+* Lenovo X1 Carbon GEN1 - Intel Sandybridge
+* lowRISC NEXYS4DDR - RiscV
+* MSI MS7721 - AMD Bulldozer
+* PC Engines APU2 - AMD Jaguar
+* RODA RV11 & RW11 variant - Intel Ivybridge
+* Sapphire Pure Platinum H61 - Intel Socket LGA1155
+* Siemens MC_APL1 - Intel Apollolake
+
+Removed 10 mainboard variants:
+* Google Auron (Still available as a base-board for variants)
+* Google Veyron Chromeboxes: Brain, Danger, Emile, Romy
+* Google Veyron Test Projects: Gus, Nicky, Pinky, Shark, Thea
+
+Utilities
+---------
+
+Added 2 new utilities:
+* blobtool
+* me_cleaner
+
+Submodules
+----------
+
+Updated 5 submodules
+* 3rdparty/blobs (10 commits)
+* 3rdparty/arm-trusted-firmware (172 commits)
+* 3rdparty/vboot (158 commits)
+* 3rdparty/chromeec/ (810 commits)
+* util/nvidia/cbootimage (2 commits)
+
+Tested boards
+-------------
+
+The following boards were tested recently:
+* emulation qemu-q35                    4.6-1
+* asus kgpe-d16                         4.6-1
+* asus kfsn4-dre                        4.6-1
+* asus p5gc-mx                          4.6-1
+* lenovo x60                            4.5-1681 / 4.6-7
+* lenovo x230                           4.5-1674 / 4.6-27
+* asrock e350m1                         4.5-1662 / 4.6-7
+* lenovo t420                           4.5-1640
+* lenovo x200                           4.5-1598 / 4.6-33
+* sapphire pureplatinumh61              4.5-1575
+* gigabyte ga-945gcm-s2l                4.5-1568
+* lenovo t400                           4.5-1564
+* lenovo t60                            4.5-1559
+* gigabyte m57sli                       4.5-1526
+* purism librem13                       4.5-1503
+* gigabyte ga-g41m-es2l                 4.5-1444
+* google slippy                         4.5-1441
+* intel d510mo                          4.5-1341
+
+coreboot statistics from e74f5eaa43 to db508565d2
+-------------------------------------------------
+
+* Total Commits: 1708
+* Average Commits per day: 8.75
+* Total authors: 121
+* New authors: 34
+* Total Reviewers: 72
+* Total Submitters: 19
+* Total lines added: 177576
+* Total lines removed: - 107460
+* Total difference: 70116
+
+Code removal after the 4.6 release
+----------------------------------
+
+The only platform currently scheduled for removal is the
+bifferos/bifferboard & soc/rdc/r8610. This platform is one of two that
+still uses romcc to compile romstage and doesn't have cache-as-ram in
+romstage - the others were all removed long ago. Additionally, it seems
+to be impossible to buy, so as far as it can be determined, no testing
+has been done recently.
+
+Code removal after the 4.7 release
+----------------------------------
+
+One of the things that the coreboot project has struggled with is how to
+maintain the older platforms while still moving the rest of the
+platforms forward. Currently there are numerous platforms in the
+codebase which have not been well maintained.
+
+Starting with the 4.7 release in October, the coreboot leadership is
+going to set standards that platforms are expected to meet to remain in
+the active codebase. These will generally be announced 3 - 6 months in
+advance to give time to get changes in. The expectation is not
+necessarily even that all work to meet the goal will be completed, but
+it is expected that a reasonable effort has started to meet the goal at
+the time of the release. Regardless of the work that's been done,
+platforms which have not met the goal by the following release will be
+removed.
+
+The next expectation that will need to be met for all platforms is cbmem
+in romstage. This currently affects numerous platforms, including most,
+if not all of AMD's platforms. Work to update many of these platforms
+has started, but there are others that have not made any progress
+towards this goal. A list of the platforms that are affected by this
+will be sent to the mailing list shortly.
+
+Code removal after the 4.8 release
+----------------------------------
+
+To further clean things up, starting with the 4.8 release, any platform
+that does not have a successful boot logged in the board_status repo in
+the previous year (that is, within the previous two releases) will be
+removed from the maintained coreboot codebase. Chips that do not have
+any associated boards will also be removed. These platforms will be
+announced before the release so that there is time for people to test if
+desired.
+
+This is not meant to be a high bar, but as a measure to clean up the
+codebase and eliminate boards and chips that are actually no longer
+being used. The cleanup will happen just after the release, so the
+removed platforms will still be available in the release branch if
+desired. If there is still interest, developers can bring back old chips
+and boards by porting them to the new tree (and bringing them to current
+standards).
+
+This gives everyone until April 2018 to get any boards that they care
+about tested before the first removal.
+
+All the code removal information will also be sent to the mailing list
+along with additional details.

firmware/coreboot/Documentation/releases/coreboot-4.7-relnotes.md

@@ -0,0 +1,197 @@
+coreboot 4.7 release notes
+==========================
+
+The 4.7 release covers commit 0a4a4f7ae4 to commit fd470f7163
+Since the last release in April 2017, the coreboot project had 2573 commits by 150 authors.
+
+There is a pgp signed 4.7 tag in the git repository, and a branch will be created as needed.
+
+
+New chipsets
+------------
+
+* AMD Stoney Ridge
+* Intel i82801jx Southbridge (ICH10)
+* Intel Denverton and Denverton-NS
+* Work has started on Intel Cannon Lake
+
+Added 47 mainboards & variants:
+-------------------
+
+* Acer Chromebook 14 CB3-431 [google/edgar]           Intel Braswell
+* Acer Chromebook 15 CB3-532 [google/banon]           Intel Braswell
+* Acer Chromebook N7 C731 [google/relm]               Intel Braswell
+* ASRock B75 Pro3-M                                   Intel Ivy Bridge
+* ASRock G41C-GS R2.0                                 Intel G41/ICH7
+* Asus AM1I-A                                         AMD Kabini
+* Asus Chromebook C202SA/C300SA/C301SA (google/terra) Intel Braswell
+* Biostar A68N-5200                                   AMD Kabini
+* Compulab Intense-PC                                 Intel Ivy Bridge
+* Dell Chromebook 11 3180/3189 (google/kefka)         Intel Braswell
+* Foxconn G41S-K                                      Intel G41/ICH7
+* Google Coral                                        Intel Apollo Lake
+* Google Grunt                                        AMD Stoney Ridge
+* Google Kahlee                                       AMD Stoney Ridge
+* Google Meowth                                       Intel Cannon Lake
+* Google Nami                                         Intel Kaby Lake
+* Google Nautilus                                     Intel Kaby Lake
+* Google Nefario                                      Rockchip RK3399
+* Google Rainier                                      Rockchip RK3399
+* Google Soraka                                       Intel Kaby Lake
+* Google Zoombini                                     Intel Cannon Lake
+* HP Chromebook 11 G5 (google/setzer)                 Intel Braswell
+* HP EliteBook 2570p                                  Intel Ivy Bridge
+* HP EliteBook 2760p                                  Intel Sandy Bridge
+* HP EliteBook 8460p                                  Intel Sandy Bridge
+* HP EliteBook 8470p                                  Intel Ivy Bridge
+* HP EliteBook Revolve 810 G1                         Intel Ivy Bridge
+* Intel Cannnlake RVPU                                Intel Cannon Lake
+* Intel Cannonlake RVPY                               Intel Cannon Lake
+* Intel D410PT                                        Intel Atom D410
+* Intel DG43GT                                        Intel G43/ICH10
+* Intel GLKRVP                                        Intel Gemini Lake
+* Intel Harcuvar                                      Intel Denverton
+* Intel NUC DCP847SKE                                 Intel Sandy Bridge
+* Intel Saddle Brook reference board                  Intel Skylake
+* Lenovo N22/N42 Chromebook (google/reks)             Intel Braswell
+* Lenovo T430                                         Intel Ivy Bridge
+* Lenovo Thinkpad 11e/Yoga Chromebook G3
+  (google/ultima)                                     Intel Braswell
+* Lenovo ThinkPad X131e                               Intel Sandy Bridge
+* Lenovo Z61T                                         Intel i945/ICH7
+* PC Engines APU3                                     AMD Steppe Eagle
+* PC Engines APU4                                     AMD Steppe Eagle
+* PC Engines APU5                                     AMD Steppe Eagle
+* Purism Librem 13 v2                                 Intel Skylake
+* Purism Librem 15 v3                                 Intel Skylake
+* Samsung Chromebook 3 (google/celes)                 Intel Braswell
+* White label Chromebook (google/wizpig)              Intel Braswell
+* WinNET G170                                         VIA CN700
+
+Removed 2 mainboards
+--------------
+
+* Biferos Bifferboard
+* Google Cosmos
+
+New Embedded Controller
+-----------------------
+
+* KBC1126 used in HP EliteBooks
+
+General changes
+---------------
+
+* Integrate me_cleaner
+* Add flashconsole implementation
+* Build Tianocore UEFI payload from upstream source
+* Remove CMOS NVRAM configurable baud rates
+* A common mrc_cache driver to store romstage settings in SPI flash
+
+Google ChromeOS devices:
+------------------------
+
+* Add ACPI USB port definitions for many boards
+* Fix preprocessor guards for LPC TPM
+* Remove non-existent IRQ for LPC TPM
+* Fix LED control for mccloud
+* Enable keyboard backlight at boot on equipped boards
+* Fix ACPI data for non-google EC's to improve Windows compatibility
+* Add missing SPD files for chell, fixing support for > 4GB boards
+
+Lenovo Thinkpads:
+-----------------
+
+* Add support for passive cooling
+* Add ACPI fan control
+* Add BDC detection and power saving
+* Unify hybrid graphics and improved power saving
+
+Intel Braswell:
+---------------
+
+* Add support for all outstanding Braswell ChromeOS devices
+* Update FSP 1.1 header to v1.1.7.0
+* Adjust FSP header revision check to be less stringent
+* Upstream numerous commits from Chromium tree
+* Fix ACPI scope for I2C devices
+* Fix SPI write after flash lockdown set
+
+Legacy Intel Boards:
+--------------------
+
+* Unify Intel VBT handling
+* Add support for loading external VBT
+* Provide the VBT through Intel OpRegion method on all platforms
+* Fix low memory corruption on S3 resume path
+
+Intel Sandy Bridge:
+------------------
+
+* Add a Kconfig option to ignore XMP max DIMMs
+* Add Kconfig option for max. DRAM frequency fuses
+* Advertise correct DRAM frequency on Ivy Bridge
+* Improve CAS/frequency selection
+* Use command rate 2T on channels with two DIMMs installed for improved
+stability
+
+Intel X4X:
+----------
+
+* Fix booting with FSB800 DDR667 combination
+* Rework ram DQS receiver enable training sequence
+* Rework and fix SPD reading and decoding
+* Allow external GPU to take VGA cycles
+
+Intel GM45:
+-----------
+
+* Improve compatibility with mixed DIMMs
+* Add romstage timings
+* Set the display backlight PWM correctly
+
+Intel Pineview:
+---------------
+
+* Enable remapping of memory to allow for 4G or more memory
+
+Intel I440BX
+------------
+
+* Implement early CBMEM support
+* Fix RAM init programming
+
+AMD AGESA
+---------
+
+* Move boards to early CBMEM and add timestamps
+* Refactor boards away from using agesawrapper
+* Wipe unused sources under vendorcode
+* Re-enable ACPI S3 after fixing low memory corruptions
+
+AMD binaryPI
+------------
+
+* Move boards to early CBMEM
+* Continue work on cleaning up headers
+
+libgfxinit
+----------
+
+* Support new hardware: Broxton/APL (DP and HDMI only), Skylake
+* Handle framebuffer mapping in the library
+* Make DP training more compatible and tolerant
+* Enhance compatibility for VGA adaptors
+
+intelmetool
+-----------
+
+* Add support for Sunrise Point LP
+* Add Intel Boot Guard detection
+
+Toolchain
+---------
+
+* buildgcc now verifies downloaded files against hashes
+* Improve GNAT detection
+* Update binutils to 2.29.1

firmware/coreboot/Documentation/releases/coreboot-4.8.1-relnotes.md

@@ -0,0 +1,179 @@
+coreboot 4.8 & 4.8.1 release notes
+==================================
+
+The 4.8.1 release contains 2 commits: 5f0b80b880 and 6794ce02d4.  This
+minor release fixes an issue with adding payloads. The 4.8 release
+covers commit 6dd2f69878 to commit ebdeb4d07d
+
+Since the last release, the coreboot project had 1198 commits by 124
+authors.
+
+There are PGP signed 4.8 and 4.8.1 tags in the git repository.  A branch
+for 4.8 releases (4.8_branch) has been created.
+
+A big thank you to everyone involved in making this release happen. We
+couldn't have done this without the 35 new commit authors, the
+experienced developers, the many reviewers, documentation writers and
+the fantastic community supporting users on both the mailing list and
+the IRC channel.
+
+In general, this has been a calm release cycle. Several old devices were
+removed from the master branch early in the release, as they hinder
+development and nobody stepped up doing the porting effort or was
+willing to test coreboot on them. If there is the desire to get a board
+back, it isn't lost as it’s still in the git history.
+
+Intel i945 platform
+-------------------
+* On Intel 945 devices, native graphics initialization is now skipped
+saving around 100 ms during resume from S3. The OS drivers need to be
+able to handle that. Linux’ i915 driver is able to handle it, but not
+the frame buffer driver.
+
+AMD Stoney Ridge
+----------------------------------
+* Significant cleanup from older AGESA based platforms
+* Fixes to get S3 working
+* Updates to GPIO code to match other modern coreboot chips
+* AGESA interface cleanup - Use native coreboot functions when
+possible
+
+Lenovo mainboards
+-----------------
+* Started integration of VBT (Video Bios Table) binary files to
+support native graphics initialisation
+
+Internal changes
+----------------
+* Rename of payload type 'payload' to 'simple_elf'
+* Progress in removing typedef device_t
+* Migrated all Intel platforms to a common VBT codebase
+* Ongoing cleanup of whitespace, spelling and formatting
+* Support for PCI in ramstage on non-x86
+* Ongoing Intel platform code deduplication
+
+Console changes
+---------------
+* Reduce default loglevel to DEBUG
+* Introduce a way for mainboard to override the loglevel
+* Restrict console messages to after console initialization
+
+Fixed Bugs
+----------
+* qemu-i440fx: Fix ACPI checksum corruption
+* intelmetool: Fix crash, support ME11+ platforms, fix bootguard
+detection
+* tpm: Fix TPM software stack vulnerability in tlcl_read() for TPM 1.2 (https://github.com/nccgroup/TPMGenie)
+* asrock/b75pro3-m: Fixed HDMI
+* Intel/ibexpeak: Fix missing ACPI PIRQ entries
+* Intel/nehalem: Fix freeze during chipset lockdown
+
+Payloads
+--------
+* Bumped SeaBIOS to 1.11.1
+* Improved TianoCore integration
+
+Security
+--------
+* Start of refactoring the TPM software stack
+* Introduced coreboot security section in kconfig
+* VBoot & TPM code moved into src/security
+
+Intelmetool
+-----------
+* Add Intel Boot Guard status support
+
+Documentation
+-------------
+* Switch from Hugo to Sphinx for the Documentation
+* Working on markdown documentation for https://doc.coreboot.org
+
+Added 17 mainboards
+-------------------
+* Asus MAXIMUS_IV_GENE_Z                               Intel Sandybridge
+* Google ATLAS                                         Intel Kabylake
+* Google BIP                                           Intel Geminilake
+* Google CHEZA                                         Qualcomm SDM845
+* Google NOCTURNE                                      Intel Kabylake
+* Google OCTOPUS                                       Intel Geminilake
+* Google PHASER                                        Intel Geminilake
+* Google YORP                                          Intel Geminilake
+* HP 8770W                                             Intel Ivybridge
+* HP FOLIO_9470M                                       Intel Ivybridge
+* Intel KBLRVP8                                        Intel Skylake
+* Lenovo W520                                          Intel Sandybridge
+* OCP MONOLAKE                                         Intel Broadwell DE
+* OCP WEDGE100S                                        Intel Broadwell DE
+* Purism Librem 15 v2                                  Intel Broadwell
+* Scaleway TAGADA                                      Intel Denverton
+* SiFive HIFIVE_UNLEASHED                              SiFive FU540
+
+Removed 39 mainboards
+---------------------
+* Abit BE6_II_V2_0
+* AMD DINAR
+* AMD RUMBA
+* Asus DSBF
+* Asus MEW_AM
+* Asus MEW_VM
+* A-trend ATC_6220
+* A-trend ATC_6240
+* AZZA PT_6IBD
+* Biostar M6TBA
+* Compaq DESKPRO_EN_SFF_P600
+* DMP EX
+* ECS P6IWP_FE
+* Gigabyte GA_6BXC
+* Gigabyte GA_6BXE
+* HP E_VECTRA_P2706T
+* Intel D810E2CB
+* Intel EAGLEHEIGHTS
+* Intel MTARVON
+* Intel TRUXTON
+* Iwave RAINBOW_G6
+* Lanner EM8510
+* Lippert FRONTRUNNER
+* Mitac 6513WU
+* MSI MS_6119
+* MSI MS_6147
+* MSI MS_6156
+* MSI MS_6178
+* NEC POWERMATE_2000
+* Nokia IP530
+* RCA RM4100
+* Soyo SY_6BA_PLUS_III
+* Supermicro H8QGI
+* Supermicro H8SCM
+* Supermicro X7DB8
+* Thomson IP1000
+* Tyan S1846
+* Tyan S8226
+* Wyse S50
+
+Added 2 socs
+------------
+* Qualcomm sdm845
+* SiFive fu540
+
+Removed 2 socs
+--------------
+* DMP vortex86ex
+* Intel sch
+
+Removed 5 processors
+--------------------
+* AMD agesa-family15
+* AMD geode-gx2
+* Intel ep80579
+* Intel model-f0x
+* Intel model-f1x
+
+Statistics
+----------
+* Total commits: 1198
+* Average Commits per day: 9.85
+* Total authors: 124
+* New authors: 35
+* Total lines added: 386113
+* Total lines removed: 291201
+* Total lines difference: 94912

firmware/coreboot/Documentation/releases/coreboot-4.9-relnotes.md

@@ -0,0 +1,30 @@
+coreboot 4.9 release notes
+==========================
+
+The 4.9 release is planned for November 2018
+
+Update this document with changes that should be in the release
+notes.
+* Please use Markdown.
+* See the [4.7](coreboot-4.7-relnotes.md) and [4.8](coreboot-4.8.1-relnotes.md)
+ release notes for the general format.
+* The chip and board additions and removals will be updated right
+before the release, so those do not need to be added.
+
+
+
+General changes
+---------------
+
+* Various code cleanups
+ * Removed `device_t` in favor of `struct device*` in ramstage code
+ * Improve adherence to coding style
+* Expand use of the postcar stage
+* Add bootblock compression capability: on systems that copy the bootblock
+  from very slow flash to ERAM, allow adding a stub that decompresses the
+  bootblock into ERAM to minimize the amount of flash reads
+
+Toolchain
+---------
+
+* Update IASL to version 10280531

firmware/coreboot/Documentation/releases/index.md

@@ -0,0 +1,16 @@
+Release notes for previous releases
+===================================
+
+### * [4.1 - July 2015](coreboot-4.1-relnotes.md)
+### * [4.2 - October 2015](coreboot-4.2-relnotes.md)
+### * [4.3 - January 2016](coreboot-4.3-relnotes.md)
+### * [4.4 - May 2016](coreboot-4.4-relnotes.md)
+### * [4.5 - October 2016](coreboot-4.5-relnotes.md)
+### * [4.6 - April 2017](coreboot-4.6-relnotes.md)
+### * [4.7 - January 2018](coreboot-4.7-relnotes.md)
+### * [4.8 - May 2018](coreboot-4.8.1-relnotes.md)
+
+Upcoming release
+----------------
+### * [4.9 - November 2018](coreboot-4.9-relnotes.md)
+Please add to the release notes as changes are added:

firmware/coreboot/Documentation/soc/index.md

@@ -0,0 +1,7 @@
+# SOC-specific documentation
+
+This section contains documentation about coreboot on specific SOCs.
+
+## Vendor
+
+- [Intel](intel/index.md)

firmware/coreboot/Documentation/soc/intel/icelake/MultiProcessorInit.md

@@ -0,0 +1,85 @@
+# Intel Common Code Block Publishing EFI_MP_SERVICES_PPI
+
+## Introduction
+
+This documentation is intended to document the purpose for creating EFI service
+Interface inside coreboot space to perform CPU feature programming on Application
+Processors for Intel 9th Gen (Cannon Lake) and beyond CPUs.
+
+Today coreboot is capable enough to handle multi-processor initialization on IA platforms.
+
+The multi-processor initialization code has to take care of lots of duties:
+
+1. Bringing all cores out of reset
+2. Load latest microcode on all cores
+3. Sync latest MTRR snapshot between BSP and APs
+4. Perform sets of CPU feature programming
+   * CPU Power & Thermal Management
+   * Overclocking
+   * Intel Trusted Execution Technology
+   * Intel Software Guard Extensions
+   * Intel Processor Trace etc.
+
+This above CPU feature programming lists are expected to grow with current and future
+CPU complexity and there might be some cases where certain feature programming mightbe
+closed source in nature.
+
+Platform code might need to compromise on those closed source nature of CPU programming
+if we don't plan to provide an alternate interface which can be used by coreboot to
+get-rid of such close source CPU programming.
+
+## Proposal
+
+As coreboot is doing CPU multi-processor initialization for IA platform before FSP-S
+initialization and having all possible information about cores in terms of maximum number
+of cores, APIC ids, stack size etc. It’s also possible for coreboot to extend its own
+support model and create a sets of APIs which later can be used by FSP to run CPU feature
+programming using coreboot published APIs.
+
+Due to the fact that FSP is using EFI infrastructure and need to relying on install/locate
+PPI to perform certain API call, hence coreboot has to created MP services APIs known as
+EFI_MP_SERVICES_PPI as per PI specification volume 1, section 8.3.9.
+More details here: [PI_Spec_1_6]
+
+### coreboot to publish EFI_MP_SERVICES_PPI APIs
+
+```eval_rst
++------------------------------+------------------------------------------------------------------+
+| API                          | Description                                                      |
++==============================+==================================================================+
+| PeiGetNumberOfProcessors     | Get the number of CPU's.                                         |
++------------------------------+------------------------------------------------------------------+
+| PeiGetProcessorInfo          | Get information on a specific CPU.                               |
++------------------------------+------------------------------------------------------------------+
+| PeiStartupAllAPs             | Activate all of the application processors.                      |
++------------------------------+------------------------------------------------------------------+
+| PeiStartupThisAP             | Activate a specific application processor.                       |
++------------------------------+------------------------------------------------------------------+
+| PeiSwitchBSP                 | Switch the boot strap processor.                                 |
++------------------------------+------------------------------------------------------------------+
+| PeiEnableDisableAP           | Enable or disable an application processor.                      |
++------------------------------+------------------------------------------------------------------+
+| PeiWhoAmI                    | Identify the currently executing processor.                      |
++------------------------------+------------------------------------------------------------------+
+```
+
+## Code Flow
+
+Here is proposed design flow with coreboot has implemented EFI_MP_SERVICES_PPI API and FSP will make
+use of the same to perform some CPU feature programming.
+
+**coreboot-FSP MP init flow**
+![coreboot-fsp mp init flow][coreboot_publish_mp_service_api]
+
+[coreboot_publish_mp_service_api]: coreboot_publish_mp_service_api.png
+
+## Benefits
+1. coreboot was using SkipMpInit=1 which will skip entire FSP CPU feature programming.
+With proposed model, coreboot will make use of SkipMpInit=0 which will allow to run all
+Silicon recommended CPU programming.
+2. CPU feature programming inside FSP will be more transparent than before as it’s using
+coreboot interfaces to execute those programming.
+3. coreboot will have more control over running those feature programming as API optimization
+handled by coreboot.
+
+[PI_Spec_1_6]: http://www.uefi.org/sites/default/files/resources/PI_Spec_1_6.pdf

firmware/coreboot/Documentation/soc/intel/icelake/index.md

@@ -0,0 +1,7 @@
+# Intel Ice Lake SOC-specific documentation
+
+This section contains documentation about coreboot on specific Intel "Ice Lake" SOCs.
+
+## Multiprocessor Init
+
+- [Multiprocessor Init](MultiProcessorInit.md)

firmware/coreboot/Documentation/soc/intel/index.md

@@ -0,0 +1,7 @@
+# Intel SOC-specific documentation
+
+This section contains documentation about coreboot on specific Intel SOCs.
+
+## Platforms
+
+- [Ice Lake/9th Gen Core-i series](icelake/index.md)

firmware/coreboot/Documentation/superio/index.md

@@ -0,0 +1,7 @@
+# SuperIO-specific documentation
+
+This section contains documentation about coreboot on specific SuperIOs.
+
+## Nuvoton
+
+- [NPCD378](nuvoton/npcd378.md)

firmware/coreboot/Documentation/superio/nuvoton/npcd378.md

@@ -0,0 +1,125 @@
+# NPCD378
+
+This page describes the [Nuvoton] SuperIO chip that can be found on various [HP]
+mainboards.
+
+As no datasheet is available most of the functions have been reverse engineered and
+might be inacurate or wrong.
+
+## LDNs
+
+```eval_rst
++-------+---------------------------+
+| LDN # | Function                  |
++=======+===========================+
+| 0     | FDC                       |
++-------+---------------------------+
+| 1     | Parallel Port             |
++-------+---------------------------+
+| 2     | Com1                      |
++-------+---------------------------+
+| 3     | Com2 / IR                 |
++-------+---------------------------+
+| 4     | LED and PWR button CTRL   |
++-------+---------------------------+
+| 5     | PS/2 AUX                  |
++-------+---------------------------+
+| 6     | PS/2 KB                   |
++-------+---------------------------+
+| 7     | WDT1                      |
++-------+---------------------------+
+| 8     | HWM                       |
++-------+---------------------------+
+| 0xf   | GPIO                      |
++-------+---------------------------+
+| 0x15  | I2C ?                     |
++-------+---------------------------+
+| 0x1e  | SUSPEND CTL ?             |
++-------+---------------------------+
+| 0x1c  | GPIO ?                    |
++-------+---------------------------+
+```
+
+### LDN0
+
+Follows [Nuvoton]'s default FDC register set. See [NCT6102D] for more details.
+
+### LDN1
+
+Follows [Nuvoton]'s default LPT register set. See [NCT6102D] for more details.
+
+### LDN2
+
+Follows [Nuvoton]'s default COM1 register set. See [NCT6102D] for more details.
+
+### LDN3
+
+Follows [Nuvoton]'s default COM2 register set. See [NCT6102D] for more details.
+
+### LDN4
+
+On most SuperIOs the use of LDN4 is forbidden. That's not the case on NPCD378.
+
+It exposes 16 byte of IO config space to control the front LEDs PWM duty cycle
+and power button behaviour on normal / during S3 resume.
+
+### LDN5
+
+A custom PS/2 AUX port.
+
+### LDN6
+
+Follows [Nuvoton]'s default KBC register set. See [NCT6102D] for more details.
+
+### LDN7
+
+Looks like a WDT.
+
+### LDN8
+
+Custom HWM space. It exposes 256 byte of IO config space.
+See [HWM](#HWM) for more details.
+
+## HWM
+
+### Register
+
+The registers are accessible via IO space and are located at LDN8's IOBASE.
+
+```eval_rst
++---------------+-----------------------+
+| IOBASE offset | Register              |
++---------------+-----------------------+
+| 0x4           | Host Write CTRL       |
++---------------+-----------------------+
+| 0x10 - 0xfe   | HWM Page #            |
++---------------+-----------------------+
+| 0xff          | Page index select     |
++---------------+-----------------------+
+```
+
+### Host Write CTRL
+Bit 0 must be cleared prior to writing any of the HWM register and it must be
+set after writing to HWM register to signal the SuperIO that data has changed.
+Reading register is possible at any time and doesn't need special locking.
+
+### HWM Page
+The SuperIO exposes 16 different pages. Nearly all registers are unknown.
+
+**Page 1**
+
+```eval_rst
++---------------+-----------------------+
+| IOBASE offset | Register              |
++---------------+-----------------------+
+| 0x98          | PSU fan PWM           |
++---------------+-----------------------+
+```
+
+### Page index
+The 4 LSB of the page index register selects which HWM page is active.
+A write takes effect immediately.
+
+[NCT6102D]: https://www.nuvoton.com/resource-files/NCT6102D_NCT6106D_Datasheet_V1_0.pdf
+[Nuvoton]: http://www.nuvoton.com/hq/
+[HP]: https://www.hp.com/

firmware/coreboot/Documentation/technotes/2017-02-dealing-with-untrusted-input-in-smm.md

@@ -0,0 +1,136 @@
+Dealing with Untrusted Input in SMM
+===================================
+
+Objective
+---------
+Intel Security recently held a talk and published
+[slides](http://www.intelsecurity.com/advanced-threat-research/content/data/REConBrussels2017_BARing_the_system.pdf)
+on a vulnerability in SMM handlers on x86 systems. They provide examples
+on how both UEFI and coreboot are affected.
+
+Background
+----------
+SMM, the System Management Mode, is a CPU mode that is configured by
+firmware and survives the system’s initialization phase. On certain
+events that mode can be triggered and executes code, suspending the
+current processing that is going on the CPU, no matter whether it’s
+in kernel or user space.
+
+In SMM, the CPU has access to memory dedicated to that mode (SMRAM) that
+is normally inaccessible, and typically some restrictions are lifted as
+well (eg. in some configurations, certain flash write protection registers
+are writable in SMM only).  This makes SMM a target for attacks which
+seek to elevate a ring0 (kernel) exploit to something permanent.
+
+Overview
+--------
+Intel Security showed several places in coreboot’s SMM handler (Slides
+32+) that could be manipulated into writing data at user-chosen addresses
+(SMRAM or otherwise), by modifying the BAR (Base Address Register) on
+certain devices. By picking the right addresses and the right events
+(and with them, mutators on the data at these addresses), it might
+be possible to change the SMM handler itself to call into regular RAM
+(where other code resides that then can work with elevated privileges).
+
+Their proposed mitigations (Slide 37) revolve around making sure
+that the BAR entries are reasonable, and point to a device instead of
+regular memory or SMRAM. They’re not very detailed on how this could
+be implemented, which is what this document discusses.
+
+Detailed Design
+---------------
+The attack works because the SMM handler trusts the results of the
+`pci_read_config32(dev, reg)` function, even though the value read by that
+function can be modified in kernel mode.
+
+In the general case it’s not possible to keep the cached value from
+system initialization because there are legitimate modifications the
+kernel can do to these values, so the only remedy is to make sure that
+the value isn’t totally off.
+
+For applications where hardware changes are limited by design (eg. no
+user-modifiable PCIe slots) and where the running kernel is known,
+such as Chromebooks, further efforts include caching the BAR settings
+at initialization time and comparing later accesses to that.
+
+What "totally off" means is chipset specific because it requires
+knowledge of the memory map as seen by the memory controller: which
+addresses are routed to devices, which are handled by the memory
+controller itself?
+The proposal is that in SMM, the `pci_read_config` functions (which
+aren’t timing critical) _always_ validate the value read from a given
+set of registers (the BARs) and fail hard (ie. cold reset, potentially
+after logging the event) if they’re invalid (because that points to
+a severe kernel bug or an attack).
+The actual validation is done by a function implemented by the chipset code.
+
+Another validation that can be done is to make sure that the BAR has the
+appropriate bits set so it is enabled and points to memory (instead of
+IO space).
+
+In terms of implementation, this might look somewhat as follows. There
+are a bunch of blanks to fill in, in particular how to handle the actual
+config space access and there will be more registers that need to be
+checked for correctness, both official BARs (0-4) and per-chipset
+registers that need to be blacklisted in another chipset specific
+function:
+
+```c
+static inline __attribute__((always_inline))
+uint32_t pci_read_config32[d](pci_devfn_t dev, unsigned int where)
+{
+	uint32_t val = real_pci_read_config32(dev, where);
+	if (IS_ENABLED(__SMM__) && (where == PCI_BASE_ADDRESS_0) &&
+		is_mmio_ptr(dev, where) && !is_address_in_mmio(val)) {
+			cold_reset();
+	}
+	return val;
+}
+```
+
+`is_address_in_mmio(addr)` would be a newly introduced function to be
+implemented by chipset drivers that returns true if the passed address
+points into whatever is considered valid MMIO space.
+`is_mmio_ptr(dev, where)` returns true for PCI config space registers that
+point to BARs (allowing custom overrides because sometimes additional
+registers are used to point to addresses).
+
+For this function what is considered a legal address needs to be
+documented, in accordance with the chipset design. (For example: AMD
+K8 has a bunch of registers that define strictly which addresses are
+"MMIO")
+
+### Fully insured (aka “paranoid”) mode
+For systems with more control over the hardware and kernel (such as
+Chromebooks), it may be possible to set up the BARs in a way that the
+kernel isn’t compelled to rewrite them, and store these values for
+later comparison.
+
+This avoids attacks such as setting the BAR to point to another device’s
+MMIO region which the above method can’t catch. Such a configuration
+would be “illegal”, but depending on the evaluation order of BARs
+in the chipset, this might effectively only disable the device used for
+the attack, while still fooling the SMM handler.
+
+Since this method isn’t generalizable, it has to be an optional
+compile-time feature.
+
+Caveats
+-------
+This capability might need to be hidden behind a Kconfig flag
+because we won’t be able to provide functional implementations of
+`is_address_in_mmio()` for every chipset supported by coreboot from the
+start.
+
+Security Considerations
+-----------------------
+The actual exploitability of the issue is unknown, but fixing it serves
+as defense in depth, similar to the
+[Memory Sinkhole mitigation](https://review.coreboot.org/#/c/11519/) for
+older Intel chipsets.
+
+Testing Plan
+------------
+Manual testing can be conducted easily by creating a small payload that
+provokes the reaction. It should test all conditions that enable the
+address test (ie. the different BAR offsets if used by SMM handlers).

firmware/coreboot/Documentation/thinkpad/codenames.csv

@@ -0,0 +1,29 @@
+t60,magi-5|magi-7|austin-3
+t400,malibu-3
+t400s,shinai
+t410,nozomi-1
+t410s,shinai-2
+t420,nozomi-3
+t420s,shinai-3
+t430,nozomi-4
+t430s,lsn-4
+t500,coronado-5
+t510,kendo-1
+t520,kendo-3
+t530,kendo-4
+w500,coronado-5
+w510,kendo-1 workstation
+w520,kendo-3 workstation
+w530,kendo-4 workstation
+w700,n-note
+x1_carbon_gen1,genesis-1
+x60,ks note
+x61,ks note-3
+x200,mocha-1
+x201,mocha-3
+x220,dasher-1
+x230,dasher-2
+x230s,rogue-1
+x240,rogue-2
+x300,kodachi
+x301,kodachi-2

firmware/coreboot/Documentation/timestamp.md

@@ -0,0 +1,200 @@
+# Timestamps
+
+## Table of Contents
+
+Introduction
+- Transition from cache to cbmem
+
+Data structures used
+- cache_state
+- table
+- entries
+
+Function APIs
+- timestamp_init
+- timestamp_add
+- timestamp_add_now
+- timestamp_sync
+
+Use / Test Cases
+- Case 1: Timestamp Region Exists
+- Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init
+- Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init
+- Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init
+- Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init
+
+
+## Introduction
+
+The aim of the timestamp library is to make it easier for different boards
+to  save timestamps in cbmem / stash (until cbmem is brought up) by
+providing a simple API to initialize, add and sync timestamps. In order
+to make the timestamps persistent and accessible from the kernel, we
+need to ensure that all the saved timestamps end up in cbmem under
+the CBMEM_ID_TIMESTAMP tag. However, until the cbmem area is available,
+the timestamps can be saved to a SoC-defined \_timestamp region or in a
+local stage-specific stash. The work of identifying the right location for
+storing timestamps is done by the library and is not exposed to the user.
+
+Working of timestamp library from a user perspective can be outlined in
+the following steps:
+1. Initialize the base time and reset cbmem timestamp area
+2. Start adding timestamps
+
+Behind the scenes, the timestamp library takes care of:
+1. Identifying the correct location for storing timestamps (cbmem or timestamp
+   region or local stash).
+2. Once cbmem is up, ensure that all timestamps are synced from timestamp
+   region or local stash into the cbmem area.
+3. Add a new cbmem timestamp area based on whether a reset of the cbmem
+   timestamp region is required or not.
+
+### Transition from cache to cbmem
+
+To move timestamps from the cache to cbmem (and initialize the cbmem area in
+the first place), we use the CBMEM_INIT_HOOK infrastructure of coreboot.
+
+When cbmem is initialized, the hook is called, which creates the area,
+copies all timestamps to cbmem and disables the cache.
+
+After such a transition, timestamp_init() must not be run again.
+
+
+## Data structures used
+
+The main structure that maintains information about the timestamp cache is:
+
+```
+struct __packed timestamp_cache {
+        uint16_t cache_state;
+        struct timestamp_table table;
+        struct timestamp_entry entries[MAX_TIMESTAMP_CACHE];
+};
+```
+
+### cache_state
+
+The state of the cache is maintained by `cache_state` attribute which can
+be any one of the following:
+
+```
+enum {
+        TIMESTAMP_CACHE_UNINITIALIZED = 0,
+        TIMESTAMP_CACHE_INITIALIZED,
+        TIMESTAMP_CACHE_NOT_NEEDED,
+};
+```
+
+By default, if the cache is stored in local stash (bss area), then
+it will be reset to uninitialized state. However, if the cache is
+stored in timestamp region, then it might have garbage in any of the
+attributes. Thus, if the timestamp region is being used by any board, it is
+initialized to default values by the library.
+
+Once the cache is initialized, its state is set to
+`CACHE_INITIALIZED`. Henceforth, the calls to cache i.e. `timestamp_add`
+know that the state reflected is valid and timestamps can be directly
+saved in the cache.
+
+Once the cbmem area is up (i.e. call to `timestamp_sync_cache_to_cbmem`),
+we do not need to store the timestamps in local stash / timestamp area
+anymore. Thus, the cache state is set to `CACHE_NOT_NEEDED`, which allows
+`timestamp_add` to store all timestamps directly into the cbmem area.
+
+
+### table
+
+This field is represented by a structure which provides overall
+information about the entries in the timestamp area:
+
+```
+struct timestamp_table {
+        uint64_t        base_time;
+        uint32_t        max_entries;
+        uint32_t        num_entries;
+        struct timestamp_entry entries[0]; /* Variable number of entries */
+} __packed;
+```
+
+It indicates the base time for all timestamp entries, maximum number
+of entries that can be stored, total number of entries that currently
+exist and an entry structure to hold variable number of entries.
+
+
+### entries
+
+This field holds the details of each timestamp entry, upto a maximum
+of `MAX_TIMESTAMP_CACHE` which is defined as 16 entries. Each entry is
+defined by:
+
+```
+struct timestamp_entry {
+        uint32_t        entry_id;
+        uint64_t        entry_stamp;
+} __packed;
+```
+
+`entry_id` holds the timestamp id corresponding to this entry and
+`entry_stamp` holds the actual timestamp.
+
+
+For timestamps stored in the cbmem area, a `timestamp_table` is allocated
+with space for `MAX_TIMESTAMPS` equal to 30. Thus, the cbmem area holds
+`base_time`, `max_entries` (which is 30), current number of entries and the
+actual entries represented by `timestamp_entry`.
+
+
+## Function APIs
+
+### timestamp_init
+
+This function initializes the timestamp cache and should be run as early
+as possible. On platforms with SRAM, this might mean in bootblock, on
+x86 with its CAR backed memory in romstage, this means romstage before
+memory init.
+
+### timestamp_add
+
+This function accepts from user a timestamp id and time to record in the
+timestamp table. It stores the entry in the appropriate table in cbmem
+or `_timestamp` region or local stash.
+
+
+### timestamp_add_now
+
+This function calls `timestamp_add` with user-provided id and current time.
+
+
+## Use / Test Cases
+
+The following cases have been considered while designing the timestamp
+library. It is important to ensure that any changes made to this library satisfy
+each of the following use cases:
+
+### Case 1: Timestamp Region Exists (Fresh Boot / Resume)
+
+In this case, the library needs to call `timestamp_init` as early as possible to
+enable the timestamp cache. Once cbmem is available, the values will be
+transferred automatically.
+
+All regions are automatically reset on initialization.
+
+### Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init
+
+`timestamp_init` will set up a local cache. cbmem must be initialized before that
+cache vanishes - as happens when jumping to the next stage.
+
+### Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init
+
+This case is not supported right now, just don't call `timestamp_init` after
+`cbmem_initialize`. (Patches to make this more robust are welcome.)
+
+### Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init
+
+We always reset the cbmem region before using it, so pre-suspend timestamps
+will be gone.
+
+### Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init
+
+We always reset the cbmem region before using it, so pre-suspend timestamps
+will be gone.

firmware/coreboot/MAINTAINERS

@@ -0,0 +1,583 @@
+
+
+	List of maintainers and how to submit coreboot changes
+
+Please try to follow the guidelines below.  This will make things
+easier on the maintainers.  Not all of these guidelines matter for every
+trivial patch so apply some common sense.
+
+1.	Always _test_ your changes, however small, on at least 1 or
+	2 people, preferably many more.
+
+2.	Try to release a few ALPHA test versions to gerrit. Announce
+	them onto the coreboot mailing list and IRC channel and await
+	results. This is especially important on coreboot core changes,
+	but also for device drivers, because often that's the only way
+	you will find things like the fact revision 3 chipset needs
+	a magic fix you didn't know about, or some clown changed the
+	chips on a board and not its name.  (Don't laugh!)
+
+3.	Make sure your changes compile correctly in multiple
+	configurations. In particular check that changes work for all
+	boards in the tree (use abuild!)
+
+4.	When you are happy with a change make it generally available for
+	testing in gerrit and await feedback.
+
+5.	Make your patch available through coreboot's gerrit code review
+	system, and add the relevant maintainer from this list as a code
+	reviewer. Be prepared to get your changes sent back with seemingly
+	silly requests about formatting and variable names.  These aren't
+	as silly as they seem. One job the maintainers do is to keep
+	things looking the same.  Sometimes this means that the clever
+	hack in your mainboard or chipset to get around a problem actually
+	needs to become a generalized coreboot feature ready for next time.
+
+	PLEASE check your patch with the automated style checker
+	(util/lint/checkpatch.pl) to catch trival style violations.
+	See https://www.coreboot.org/Coding_Style for guidance here.
+
+	PLEASE add the maintainers that are generated by
+	util/scripts/get_maintainer.pl as reviewers.  The results returned
+	by the script will be best if you have git installed and are
+	making your changes in a branch derived from coreboot.org's latest
+	git tree.
+
+	PLEASE try to include any credit lines you want added with the
+	patch. It avoids people being missed off by mistake and makes
+	it easier to know who wants adding and who doesn't.
+
+	PLEASE document known bugs. If it doesn't work for everything
+	or does something very odd once a month document it.
+
+	PLEASE remember that submissions must be made under the terms
+	of the OSDL certificate of contribution and should include a
+	Signed-off-by: line.  The current version of this "Developer's
+	Certificate of Origin" (DCO) is listed at
+	https://www.coreboot.org/Development_Guidelines#Sign-off_Procedure.
+
+6.	Make sure you have the right to send any changes you make. If you
+	do changes at work you may find your employer owns the patch
+	not you.
+
+7.	Happy hacking.
+
+Descriptions of section entries:
+
+	M: Maintainer: FullName <address@domain>
+	R: Designated reviewer: FullName <address@domain>
+	   These reviewers should be CCed on patches.
+	L: Mailing list that is relevant to this area
+	W: Web-page with status/info
+	Q: Patchwork web based patch tracking system site
+	T: SCM tree type and location.
+	   Type is one of: git, hg, quilt, stgit, topgit
+	S: Status, one of the following:
+	   Supported:	Someone is actually paid to look after this.
+	   Maintained:	Someone actually looks after it.
+	   Odd Fixes:	It has a maintainer but they don't have time to do
+			much other than throw the odd patch in. See below..
+	   Orphan:	No current maintainer [but maybe you could take the
+			role as you write your new code].
+	   Obsolete:	Old code. Something tagged obsolete generally means
+			it has been replaced by a better system and you
+			should be using that.
+	F: Files and directories with wildcard patterns.
+	   A trailing slash includes all files and subdirectory files.
+	   F:	drivers/net/	all files in and below drivers/net
+	   F:	drivers/net/*	all files in drivers/net, but not below
+	   F:	*/net/*		all files in "any top level directory"/net
+	   One pattern per line.  Multiple F: lines acceptable.
+	N: Files and directories with regex patterns.
+	   N:	[^a-z]tegra	all files whose path contains the word tegra
+	   One pattern per line.  Multiple N: lines acceptable.
+	   scripts/get_maintainer.pl has different behavior for files that
+	   match F: pattern and matches of N: patterns.  By default,
+	   get_maintainer will not look at git log history when an F: pattern
+	   match occurs.  When an N: match occurs, git log history is used
+	   to also notify the people that have git commit signatures.
+	X: Files and directories that are NOT maintained, same rules as F:
+	   Files exclusions are tested before file matches.
+	   Can be useful for excluding a specific subdirectory, for instance:
+	   F:	net/
+	   X:	net/ipv6/
+	   matches all files in and below net excluding net/ipv6/
+	K: Keyword perl extended regex pattern to match content in a
+	   patch or file.  For instance:
+	   K: of_get_profile
+	      matches patches or files that contain "of_get_profile"
+	   K: \b(printk|pr_(info|err))\b
+	      matches patches or files that contain one or more of the words
+	      printk, pr_info or pr_err
+	   One regex pattern per line.  Multiple K: lines acceptable.
+
+Note: For the hard of thinking, this list is meant to remain in alphabetical
+order. If you could add yourselves to it in alphabetical order that would be
+so much easier [Ed]
+
+Maintainers List (try to look for most precise areas first)
+
+		-----------------------------------
+
+RISC-V ARCHITECTURE
+M:	Ronald Minnich <rminnich@gmail.com>
+M:	Jonathan Neuschäfer <j.neuschaefer@gmx.net>
+S:	Maintained
+F:	src/arch/riscv/
+F:	src/soc/lowrisc
+F:	src/soc/ucb/
+F:	src/mainboard/emulation/*-riscv/
+F:	src/mainboard/lowrisc
+
+POWER8 ARCHITECTURE
+M:	Ronald Minnich <rminnich@gmail.com>
+M:	Timothy Pearson <tpearson@raptorengineeringinc.com>
+S:	Maintained
+F:	src/arch/power8/
+F:	src/cpu/qemu-power8/
+F:	src/mainboard/emulation/qemu-power8/
+
+LENOVO EC
+M:	Alexander Couzens <lynxis@fe80.eu>
+S:	Maintained
+F:	src/ec/lenovo/
+
+LENOVO MAINBOARDS
+M:	Alexander Couzens <lynxis@fe80.eu>
+M:	Patrick Rudolph <siro@das-labor.org>
+S:	Maintained
+F:	src/mainboard/lenovo/
+
+INTEL PINEVIEW CHIPSET
+M:	Damien Zammit <damien@zamaudio.com>
+S:	Odd Fixes
+F:	src/northbridge/intel/pineview/
+
+INTEL D510MO MAINBOARD
+M:	Damien Zammit <damien@zamaudio.com>
+S:	Odd Fixes
+F:	src/mainboard/intel/d510mo
+
+INTEL X4X CHIPSET
+M:	Damien Zammit <damien@zamaudio.com>
+S:	Odd Fixes
+F:	src/northbridge/intel/x4x/
+
+GIGABYTE GA-G41M-ES2L MAINBOARD
+M:	Damien Zammit <damien@zamaudio.com>
+S:	Odd Fixes
+F:	src/mainboard/gigabyte/ga-g41m-es2l
+
+GOOGLE PANTHER MAINBOARD
+M:	Stefan Reinauer <stefan.reinauer@coreboot.org>
+S:	Supported
+F:	src/mainboard/google/panther/
+
+INTEL MINNOWBOARD MAX MAINBOARD
+M:	Huang Jin <huang.jin@intel.com>
+M:	York Yang <york.yang@intel.com>
+S:	Supported
+F:	src/mainboard/intel/minnowmax/
+
+INTEL FSP BAYTRAIL CHIP & CRBs
+M:	Huang Jin <huang.jin@intel.com>
+M:	York Yang <york.yang@intel.com>
+S:	Supported
+F:	src/soc/intel/fsp_baytrail/
+F:	src/vendorcode/intel/fsp1_0/baytrail/
+F:	src/mainboard/intel/bakersport_fsp/
+F:	src/mainboard/intel/bayleybay_fsp/
+
+INTEL FSP BROADWELL-DE SOC & CRB
+M:	York Yang <york.yang@intel.com>
+S:	Supported
+F:	src/soc/intel/fsp_broadwell_de/
+F:	src/vendorcode/intel/fsp1_0/broadwell_de/
+F:	src/mainboard/intel/camelbackmountain_fsp/
+
+INTEL FSP IVYBRIDGE/PANTHERPOINT/CAVECREEK & CRBs
+M:	York Yang <york.yang@intel.com>
+S:	Supported
+F:	src/cpu/intel/fsp_model_206ax/
+F:	src/northbridge/intel/fsp_sandybridge/
+F:	src/southbridge/intel/fsp_bd82x6x/
+F:	src/southbridge/intel/fsp_i89xx/
+F:	src/vendorcode/intel/fsp1_0/ivybridge_bd82x6x
+F:	src/vendorcode/intel/fsp1_0/ivybridge_i89xx
+F:	src/mainboard/intel/cougar_canyon2/
+F:	src/mainboard/intel/stargo2/
+
+INTEL FSP DENVERTON-NS SOC & HARCUVAR CRB
+M:	SweeHeng Wong <swee.heng.wong@intel.com>
+M:	Jeff Daly <jeffrey.daly@intel.com>
+M:	Vanessa Eusebio <vanessa.f.eusebio@intel.com>
+M:	David Guckian <david.guckian@intel.com>
+M:	Shine Liu <shine.liu@intel.com>
+S:	Supported
+F:	src/mainboard/intel/harcuvar/
+F:	src/soc/intel/denverton_ns/
+F:	src/vendorcode/intel/fsp/fsp2_0/denverton_ns/
+
+FSP 1.0 RANGELEY & CRB
+M:	David Guckian <david.guckian@intel.com>
+M:	Fei Wang <fei.z.wang@intel.com>
+S:	Supported
+F:	src/cpu/intel/fsp_model_406dx/
+F:	src/northbridge/intel/fsp_rangeley/
+F:	src/southbridge/intel/fsp_rangeley/
+F:	src/vendorcode/intel/fsp1_0/rangeley/
+F:	src/mainboard/intel/mohonpeak/
+
+INTEL FSP 1.0
+M:	Huang Jin <huang.jin@intel.com>
+M:	York Yang <york.yang@intel.com>
+S:	Supported
+F:	src/drivers/intel/fsp1_0/
+
+INTEL FSP 1.1
+M:	Lee Leahy <leroy.p.leahy@intel.com>
+M:	Huang Jin <huang.jin@intel.com>
+M:	York Yang <york.yang@intel.com>
+S:	Supported
+F:	src/drivers/intel/fsp1_1/
+
+INTEL FSP 2.0
+M:	Andrey Petrov <andrey.petrov@gmail.com>
+S:	Maintained
+F:	src/drivers/intel/fsp2_0/
+
+INTEL STRAGO MAINBOARD
+M:	Hannah Williams <hannah.williams@intel.com>
+S:	Supported
+F:	/src/mainboard/intel/strago/
+
+INTEL BRASWELL SOC
+M:	Hannah Williams <hannah.williams@intel.com>
+S:	Supported
+F:	/src/soc/intel/braswell
+F:	/src/vendorcode/intel/fsp/fsp1_1/braswell
+
+INTEL APOLLOLAKE_SOC
+M:	Andrey Petrov <andrey.petrov@gmail.com>
+S:	Maintained
+F:	src/soc/intel/apollolake/
+
+ASUS KFSN4-DRE & KFSN4-DRE_K8 MAINBOARDS
+M:	Timothy Pearson <tpearson@raptorengineeringinc.com>
+S:	Supported
+F:	src/mainboard/asus/kfsn4-dre/
+F:	src/mainboard/asus/kfsn4-dre_k8/
+
+ASUS KCMA-D8 MAINBOARD
+M:	Timothy Pearson <tpearson@raptorengineeringinc.com>
+S:	Supported
+F:	src/mainboard/asus/kcma-d8/
+
+ASUS KGPE-D16 MAINBOARD
+M:	Timothy Pearson <tpearson@raptorengineeringinc.com>
+S:	Supported
+F:	src/mainboard/asus/kgpe-d16/
+
+PC ENGINES ALL MAINBOARDS
+M:	Piotr Król <piotr.krol@3mdeb.com>
+M:	Michał Żygowski <michal.zygowski@3mdeb.com>
+S:	Supported
+F:	src/mainboard/pcengines/
+
+AMD FAMILY10H & FAMILY15H (NON-AGESA) CPUS & NORTHBRIDGE
+M:	Timothy Pearson <tpearson@raptorengineeringinc.com>
+S:	Supported
+F:	src/cpu/amd/family_10h-family_15h/
+F:	src/northbridge/amd/amdfam10/
+F:	src/northbridge/amd/amdmct/
+F:	src/northbridge/amd/amdht/
+
+AMD SB700 (NON-CIMX) SOUTHBRIDGE
+M:	Timothy Pearson <tpearson@raptorengineeringinc.com>
+S:	Supported
+F:	src/southbridge/amd/sb700/
+
+AMD SR5650 SOUTHBRIDGE
+M:	Timothy Pearson <tpearson@raptorengineeringinc.com>
+S:	Supported
+F:	src/southbridge/amd/sr5650/
+
+ASPEED AST2050 DRIVER & COMMON CODE
+M:	Timothy Pearson <tpearson@raptorengineeringinc.com>
+S:	Supported
+F:	src/drivers/aspeed/common/
+F:	src/drivers/aspeed/ast2050/
+
+ATI MACH64 Driver
+S:	Orphan
+F:	src/drivers/ati/mach64/
+
+ABUILD
+M:	Patrick Georgi <patrick@georgi-clan.de>
+M:	Martin Roth <gaumless@gmail.com>
+S:	Supported
+F:	util/abuild/
+
+ACPI
+F:	src/acpi/
+F:	src/arch/x86/acpi/
+F:	util/acpi/
+
+LZ4 COMPRESSION
+M:	Julius Werner <jwerner@chromium.org>
+S:	Supported
+F:	src/commonlib/lz4*
+F:	payloads/libpayload/liblz4/
+F:	util/cbfstool/lz4/
+
+ARM ARCHITECTURE
+M:	Julius Werner <jwerner@chromium.org>
+S:	Supported
+F:	src/arch/arm/
+F:	src/arch/arm64/
+F:	src/soc/mediatek/
+F:	src/soc/nvidia/
+F:	src/soc/rockchip/
+F:	util/nvidia/
+F:	util/rockchip/
+
+ORPHANED ARM SOCS
+S:	Orphaned
+F:	src/cpu/allwinner/
+F:	src/cpu/armltd/
+F:	src/cpu/ti/
+F:	src/soc/broadcom/
+F:	src/soc/marvell/
+F:	src/soc/qualcomm/
+F:	src/soc/samsung/
+F:	util/arm_boot_tools/
+F:	util/broadcom/
+F:	util/exynos/
+F:	util/ipqheader/
+
+MIPS ARCHITECTURE
+F:	src/arch/mips/
+F:	src/cpu/mips/
+F:	src/soc/imgtec/
+F:	util/bimgtool/
+
+X86 ARCHITECTURE
+F:	src/arch/x86/
+F:	src/cpu/x86/
+F:	src/drivers/pc80/
+F:	src/include/pc80/
+F:	src/include/cpu/x86/
+
+INTEL SUPPORT
+M:	Patrick Rudolph <siro@das-labor.org>
+S:	Maintained
+F:	src/vendorcode/intel/
+F:	src/cpu/intel/
+F:	src/northbridge/intel/
+F:	src/southbridge/intel/
+F:	src/soc/intel/
+F:	src/drivers/intel/
+F:	src/include/cpu/intel/
+
+AMD SUPPORT
+F:	src/vendorcode/amd/
+F:	src/cpu/amd/
+F:	src/northbridge/amd/
+F:	src/southbridge/amd/
+F:	src/include/cpu/amd/
+
+VIA SUPPORT
+F:	src/cpu/via/
+F:	src/northbridge/via/
+F:	src/southbridge/via/
+
+LINT SCRIPTS
+M:	Patrick Georgi <patrick@georgi-clan.de>
+M:	Martin Roth <gaumless@gmail.com>
+S:	Supported
+F:	util/lint/
+
+INTELTOOL
+M:	Stefan Reinauer <stefan.reinauer@coreboot.org>
+F:	util/inteltool/
+
+INTELMETOOL
+M:	Philipp Deppenwiese <zaolin.daisuki@gmail.com>
+F:	util/intelmetool/
+
+ME_CLEANER
+M:	Nicola Corna <nicola@corna.info>
+W:	https://github.com/corna/me_cleaner
+S:	Maintained
+F:	util/me_cleaner/
+
+IFDTOOL
+M:	Stefan Reinauer <stefan.reinauer@coreboot.org>
+F:	util/ifdtool/
+F:	util/ifdfake/
+
+BUILD SYSTEM
+M:	Patrick Georgi <patrick@georgi-clan.de>
+M:	Martin Roth <gaumless@gmail.com>
+S:	Supported
+F:	Makefile
+F:	*.inc
+F:	src/include/kconfig.h
+F:	util/kconfig/
+F:	util/sconfig/
+F:	util/xcompile/
+F:	util/genbuild_h/
+
+BOARD STATUS
+F:	util/board_status/
+
+BINARY OBJECTS
+F:	3rdparty/blobs/
+
+VERIFIED BOOT
+F:	3rdparty/vboot/
+F:	src/vendorcode/google/chromeos/
+F:	src/include/tpm.h
+F:	src/include/tpm_lite/
+
+RESOURCE ALLOCATOR
+F:	src/device/*
+F:	src/include/device/
+F:	src/include/cpu/cpu.h
+
+OPTION ROM EXECUTION & X86EMU
+F:	src/device/oprom/
+
+CBFS
+F:	src/include/cbfs.h
+F:	src/include/cbfs_serialized.h
+F:	util/cbfstool/
+
+CBMEM
+F:	src/include/cbmem.h
+F:	src/include/cbmem_id.h
+F:	util/cbmem/
+
+CONSOLE
+F:	src/console/
+F:	src/include/console/
+F:	src/drivers/uart/
+
+NVRAM
+F:	util/nvramtool/
+F:	util/optionlist/
+F:	payloads/nvramcui/
+
+LIBPAYLOAD
+F:	payloads/libpayload/
+
+BAYOU PAYLOAD
+F:	payloads/bayou/
+
+COREINFO PAYLOAD
+F:	payloads/coreinfo/
+
+EXTERNAL PAYLOADS INTEGRATION
+M:	Stefan Reinauer <stefan.reinauer@coreboot.org>
+M:	Martin Roth <gaumless@gmail.com>
+F:	payloads/external
+
+VERIFIED BOOT 2
+M:	Aaron Durbin <adurbin@chromium.org>
+F:	src/vendorcode/google/chromeos/vboot2/
+
+TPM SUPPORT
+M:	Philipp Deppenwiese <zaolin.daisuki@gmail.com>
+F:	src/drivers/*/tpm/
+F:	src/security/tpm12/
+F:	src/security/tpm20/
+F:	util/tss-generator/
+
+DOCKER
+M:	Martin Roth <gaumless@gmail.com>
+S:	Supported
+F:	util/docker/
+
+TOOLCHAIN
+F:	util/crossgcc/
+
+GIT
+F:	.git*
+F:	/util/gitconfig
+
+SUPERIOS & SUPERIOTOOL
+M:	Felix Held <felix-coreboot@felixheld.de>
+S:	Maintained
+F:	src/superio/
+F:	util/superiotool/
+
+MEMLAYOUT
+M:	Julius Werner <jwerner@chromium.org>
+S:	Supported
+F:	*/memlayout.h
+F:	*.ld
+
+MISSING: TIMERS / DELAYS
+
+MISSING: TIMESTAMPS
+
+MISSING: FMAP
+
+MISSING: GPIO
+
+MISSING: SMP
+
+MISSING: DMP / QEMU-X86
+
+MISSING: ELOG
+
+MISSING: SPI
+
+THE REST
+M:	Stefan Reinauer <stefan.reinauer@coreboot.org>
+T:	git https://review.coreboot.org/coreboot
+S:	Buried alive in mainboards
+F:	*
+F:	*/
+
+# *** Infrastructure Owners***
+# This is intended to let people know who they should contact for issues with various infrastructure pieces.
+# Hardware
+#	Owners: Stefan, Patrick
+#	Backups:
+
+# Web Server
+#	Owners: Stefan, Patrick
+#	Backups:
+
+# Website
+#	Owners: Martin, Philipp
+#	Backups: Patrick, Stefan
+
+# Documentation Website
+#	Owners: Patrick, Philipp
+#	Backups:
+
+# Wiki
+#	Owners: Stefan, Patrick
+#	Backups:
+
+# Gerrit
+#	Owners: Stefan, Patrick
+#	Backups: Martin
+
+# Jenkins
+#	Owners: Patrick, Martin
+#	Backups:
+
+# Bug Tracker
+#	Owners: Lynxis,
+#	Backups: Martin,
+
+# Mailing List
+#	Owners: Stefan, Patrick
+#	Backups: Martin,
+
+# Software Freedom Conservancy
+#	Main contact: Martin
+#	“Official” contact: Stefan

firmware/coreboot/Makefile

@@ -0,0 +1,450 @@
+##
+## This file is part of the coreboot project.
+##
+## Copyright (C) 2008 Advanced Micro Devices, Inc.
+## Copyright (C) 2008 Uwe Hermann <uwe@hermann-uwe.de>
+## Copyright (C) 2009-2010 coresystems GmbH
+## Copyright (C) 2011 secunet Security Networks AG
+##
+## Redistribution and use in source and binary forms, with or without
+## modification, are permitted provided that the following conditions
+## are met:
+## 1. Redistributions of source code must retain the above copyright
+##    notice, this list of conditions and the following disclaimer.
+## 2. Redistributions in binary form must reproduce the above copyright
+##    notice, this list of conditions and the following disclaimer in the
+##    documentation and/or other materials provided with the distribution.
+## 3. The name of the author may not be used to endorse or promote products
+##    derived from this software without specific prior written permission.
+##
+## THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+## ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+## IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+## ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+## FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+## DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+## OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+## HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+## LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+## OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+## SUCH DAMAGE.
+##
+
+top := $(CURDIR)
+src := src
+srck := $(top)/util/kconfig
+obj ?= build
+override obj := $(subst $(top)/,,$(abspath $(obj)))
+objutil ?= $(obj)/util
+objk := $(objutil)/kconfig
+absobj := $(abspath $(obj))
+
+COREBOOT_EXPORTS := COREBOOT_EXPORTS
+COREBOOT_EXPORTS += top src srck obj objutil objk
+
+DOTCONFIG ?= $(top)/.config
+KCONFIG_CONFIG = $(DOTCONFIG)
+KCONFIG_AUTOHEADER := $(obj)/config.h
+KCONFIG_AUTOCONFIG := $(obj)/auto.conf
+KCONFIG_DEPENDENCIES := $(obj)/auto.conf.cmd
+KCONFIG_SPLITCONFIG := $(obj)/config
+KCONFIG_TRISTATE := $(obj)/tristate.conf
+KCONFIG_NEGATIVES := 1
+KCONFIG_STRICT := 1
+
+COREBOOT_EXPORTS += KCONFIG_CONFIG KCONFIG_AUTOHEADER KCONFIG_AUTOCONFIG
+COREBOOT_EXPORTS += KCONFIG_DEPENDENCIES KCONFIG_SPLITCONFIG KCONFIG_TRISTATE
+COREBOOT_EXPORTS += KCONFIG_NEGATIVES KCONFIG_STRICT
+
+# directory containing the toplevel Makefile.inc
+TOPLEVEL := .
+
+CONFIG_SHELL := sh
+KBUILD_DEFCONFIG := configs/defconfig
+UNAME_RELEASE := $(shell uname -r)
+HAVE_DOTCONFIG := $(wildcard $(DOTCONFIG))
+MAKEFLAGS += -rR --no-print-directory
+
+# Make is silent per default, but 'make V=1' will show all compiler calls.
+Q:=@
+ifneq ($(V),1)
+ifneq ($(Q),)
+.SILENT:
+endif
+endif
+
+# Disable implicit/built-in rules to make Makefile errors fail fast.
+.SUFFIXES:
+
+HOSTCC := $(if $(shell type gcc 2>/dev/null),gcc,cc)
+HOSTCXX = g++
+HOSTCFLAGS := -g
+HOSTCXXFLAGS := -g
+
+PREPROCESS_ONLY := -E -P -x assembler-with-cpp -undef -I .
+
+DOXYGEN := doxygen
+DOXYGEN_OUTPUT_DIR := doxygen
+
+export $(COREBOOT_EXPORTS)
+
+all: real-all
+
+help_coreboot help::
+	@echo  '*** coreboot platform targets ***'
+	@echo  '  Use "make [target] V=1" for extra build debug information'
+	@echo  '  all                   - Build coreboot'
+	@echo  '  clean                 - Remove coreboot build artifacts'
+	@echo  '  distclean             - Remove build artifacts and config files'
+	@echo  '  doxygen               - Build doxygen documentation for coreboot'
+	@echo  '  doxyplatform          - Build doxygen documentation for the current platform'
+	@echo  '  filelist              - Show files used in current build'
+	@echo  '  printall              - print makefile info for debugging'
+	@echo  '  gitconfig             - set up git to submit patches to coreboot'
+	@echo  '  ctags / ctags-project - make ctags file for all of coreboot or current board'
+	@echo  '  cscope / cscope-project - make cscope.out file for coreboot or current board'
+	@echo
+
+# This include must come _before_ the pattern rules below!
+# Order _does_ matter for pattern rules.
+include $(srck)/Makefile
+
+# Three cases where we don't need fully populated $(obj) lists:
+# 1. when no .config exists
+# 2. when make config (in any flavour) is run
+# 3. when make distclean is run
+# Don't waste time on reading all Makefile.incs in these cases
+ifeq ($(strip $(HAVE_DOTCONFIG)),)
+NOCOMPILE:=1
+endif
+ifneq ($(MAKECMDGOALS),)
+ifneq ($(filter %config %clean cross% clang iasl gnumake lint% help% what-jenkins-does,$(MAKECMDGOALS)),)
+NOCOMPILE:=1
+endif
+ifeq ($(MAKECMDGOALS), %clean)
+NOMKDIR:=1
+endif
+endif
+
+ifeq ($(NOCOMPILE),1)
+include $(TOPLEVEL)/Makefile.inc
+include $(TOPLEVEL)/payloads/Makefile.inc
+include $(TOPLEVEL)/util/testing/Makefile.inc
+-include $(TOPLEVEL)/site-local/Makefile.inc
+real-all:
+	@echo "Error: Expected config file ($(DOTCONFIG)) not present." >&2
+	@echo "Please specify a config file or run 'make menuconfig' to" >&2
+	@echo "generate a new config file." >&2
+	@exit 1
+else
+
+include $(DOTCONFIG)
+
+# in addition to the dependency below, create the file if it doesn't exist
+# to silence stupid warnings about a file that would be generated anyway.
+$(if $(wildcard .xcompile)$(NOCOMPILE),,$(eval $(shell util/xcompile/xcompile $(XGCCPATH) > .xcompile || rm -f .xcompile)))
+
+.xcompile: util/xcompile/xcompile
+	rm -f $@
+	$< $(XGCCPATH) > $@.tmp
+	\mv -f $@.tmp $@ 2> /dev/null
+	rm -f $@.tmp
+
+-include .xcompile
+
+ifneq ($(XCOMPILE_COMPLETE),1)
+$(shell rm -f .xcompile)
+$(error .xcompile deleted because it's invalid. \
+	Restarting the build should fix that, or explain the problem)
+endif
+
+ifneq ($(CONFIG_MMX),y)
+CFLAGS_x86_32 += -mno-mmx
+endif
+
+include toolchain.inc
+
+strip_quotes = $(strip $(subst ",,$(subst \",,$(1))))
+# fix makefile syntax highlighting after strip macro \" "))
+
+# The primary target needs to be here before we include the
+# other files
+
+real-all: real-target
+
+# must come rather early
+.SECONDEXPANSION:
+
+$(KCONFIG_AUTOHEADER): $(KCONFIG_CONFIG)
+	+$(MAKE) oldconfig
+
+# Add a new class of source/object files to the build system
+add-class= \
+	$(eval $(1)-srcs:=) \
+	$(eval $(1)-objs:=) \
+	$(eval classes+=$(1))
+
+# Special classes are managed types with special behaviour
+# On parse time, for each entry in variable $(1)-y
+# a handler $(1)-handler is executed with the arguments:
+# * $(1): directory the parser is in
+# * $(2): current entry
+add-special-class= \
+	$(eval $(1):=) \
+	$(eval special-classes+=$(1))
+
+# Converts one or more source file paths to their corresponding build/ paths.
+# Only .ads, adb, .c and .S get converted to .o, other files (like .ld) keep
+# their name.
+# $1 stage name
+# $2 file path (list)
+src-to-obj=\
+	$(patsubst $(obj)/%,$(obj)/$(1)/%,\
+	$(patsubst $(obj)/$(1)/%,$(obj)/%,\
+	$(patsubst 3rdparty/%,$(obj)/%,\
+	$(patsubst src/%,$(obj)/%,\
+	$(patsubst %.ads,%.o,\
+	$(patsubst %.adb,%.o,\
+	$(patsubst %.c,%.o,\
+	$(patsubst %.S,%.o,\
+	$(subst .$(1),,$(2))))))))))
+
+# Converts one or more source file paths to the corresponding build/ paths
+# of their Ada library information (.ali) files.
+# $1 stage name
+# $2 file path (list)
+src-to-ali=\
+	$(patsubst $(obj)/%,$(obj)/$(1)/%,\
+	$(patsubst $(obj)/$(1)/%,$(obj)/%,\
+	$(patsubst 3rdparty/%,$(obj)/%,\
+	$(patsubst src/%,$(obj)/%,\
+	$(patsubst %.ads,%.ali,\
+	$(patsubst %.adb,%.ali,\
+	$(subst .$(1),,\
+	$(filter %.ads %.adb,$(2)))))))))
+
+# Clean -y variables, include Makefile.inc
+# Add paths to files in X-y to X-srcs
+# Add subdirs-y to subdirs
+includemakefiles= \
+	$(foreach class,classes subdirs $(classes) $(special-classes), $(eval $(class)-y:=)) \
+	$(eval -include $(1)) \
+	$(foreach class,$(classes-y), $(call add-class,$(class))) \
+	$(foreach class,$(classes), \
+		$(eval $(class)-srcs+= \
+			$$(subst $(absobj)/,$(obj)/, \
+			$$(subst $(top)/,, \
+			$$(abspath $$(subst $(dir $(1))/,/,$$(addprefix $(dir $(1)),$$($(class)-y)))))))) \
+	$(foreach special,$(special-classes), \
+		$(foreach item,$($(special)-y), $(call $(special)-handler,$(dir $(1)),$(item)))) \
+	$(eval subdirs+=$$(subst $(CURDIR)/,,$$(wildcard $$(abspath $$(addprefix $(dir $(1)),$$(subdirs-y))))))
+
+# For each path in $(subdirs) call includemakefiles
+# Repeat until subdirs is empty
+evaluate_subdirs= \
+	$(eval cursubdirs:=$(subdirs)) \
+	$(eval subdirs:=) \
+	$(foreach dir,$(cursubdirs), \
+		$(eval $(call includemakefiles,$(dir)/Makefile.inc))) \
+	$(if $(subdirs),$(eval $(call evaluate_subdirs)))
+
+# collect all object files eligible for building
+subdirs:=$(TOPLEVEL)
+postinclude-hooks :=
+$(eval $(call evaluate_subdirs))
+ifeq ($(FAILBUILD),1)
+$(error cannot continue build)
+endif
+
+# Run hooks registered by subdirectories that need to be evaluated after all files have been parsed
+$(eval $(postinclude-hooks))
+
+# Eliminate duplicate mentions of source files in a class
+$(foreach class,$(classes),$(eval $(class)-srcs:=$(sort $($(class)-srcs))))
+
+# To track dependencies, we need all Ada specification (.ads) files in
+# *-srcs. Extract / filter all specification files that have a matching
+# body (.adb) file here (specifications without a body are valid sources
+# in Ada).
+$(foreach class,$(classes),$(eval $(class)-extra-specs := \
+	$(filter \
+		$(addprefix %/,$(patsubst %.adb,%.ads,$(notdir $(filter %.adb,$($(class)-srcs))))), \
+		$(filter %.ads,$($(class)-srcs)))))
+$(foreach class,$(classes),$(eval $(class)-srcs := \
+	$(filter-out $($(class)-extra-specs),$($(class)-srcs))))
+
+$(foreach class,$(classes),$(eval $(class)-objs:=$(call src-to-obj,$(class),$($(class)-srcs))))
+$(foreach class,$(classes),$(eval $(class)-alis:=$(call src-to-ali,$(class),$($(class)-srcs))))
+
+# For Ada includes
+$(foreach class,$(classes),$(eval $(class)-ada-dirs:=$(sort $(dir $(filter %.ads %.adb,$($(class)-srcs)) $($(class)-extra-specs)))))
+
+# Save all objs before processing them (for dependency inclusion)
+originalobjs:=$(foreach var, $(addsuffix -objs,$(classes)), $($(var)))
+
+# Call post-processors if they're defined
+$(foreach class,$(classes),\
+	$(if $(value $(class)-postprocess),$(eval $(call $(class)-postprocess,$($(class)-objs)))))
+
+allsrcs:=$(foreach var, $(addsuffix -srcs,$(classes)), $($(var)))
+allobjs:=$(foreach var, $(addsuffix -objs,$(classes)), $($(var)))
+alldirs:=$(sort $(abspath $(dir $(allobjs))))
+
+# Reads dependencies from an Ada library information (.ali) file
+# Only basenames (with suffix) are preserved so we have to look the
+# paths up in $($(stage)-srcs).
+# $1 stage name
+# $2 ali file
+create_ada_deps=$$(if $(2),\
+	gnat.adc \
+	$$(filter \
+		$$(addprefix %/,$$(shell sed -ne's/^D \([^\t]\+\).*$$$$/\1/p' $(2) 2>/dev/null)), \
+		$$($(1)-srcs) $$($(1)-extra-specs)))
+
+# macro to define template macros that are used by use_template macro
+define create_cc_template
+# $1 obj class
+# $2 source suffix (c, S, ld, ...)
+# $3 additional compiler flags
+# $4 additional dependencies
+ifn$(EMPTY)def $(1)-objs_$(2)_template
+de$(EMPTY)fine $(1)-objs_$(2)_template
+ifn$(EMPTY)eq ($(filter ads adb,$(2)),)
+$$(call src-to-obj,$1,$$(1).$2): $$(1).$2 $$(call create_ada_deps,$1,$$(call src-to-ali,$1,$$(1).$2)) $(KCONFIG_AUTOHEADER) $(4)
+	@printf "    GCC        $$$$(subst $$$$(obj)/,,$$$$(@))\n"
+	$(GCC_$(1)) \
+		$$$$(ADAFLAGS_$(1)) $$$$(addprefix -I,$$$$($(1)-ada-dirs)) \
+		$(3) -c -o $$$$@ $$$$<
+el$(EMPTY)se
+$$(call src-to-obj,$1,$$(1).$2): $$(1).$2 $(KCONFIG_AUTOHEADER) $(4)
+	@printf "    CC         $$$$(subst $$$$(obj)/,,$$$$(@))\n"
+	$(CC_$(1)) \
+		-MMD $$$$(CPPFLAGS_$(1)) $$$$(CFLAGS_$(1)) -MT $$$$(@) \
+		$(3) -c -o $$$$@ $$$$<
+end$(EMPTY)if
+en$(EMPTY)def
+end$(EMPTY)if
+endef
+
+filetypes-of-class=$(subst .,,$(sort $(suffix $($(1)-srcs))))
+$(foreach class,$(classes), \
+	$(foreach type,$(call filetypes-of-class,$(class)), \
+		$(eval $(class)-$(type)-ccopts += $(generic-$(type)-ccopts) $($(class)-generic-ccopts)) \
+		$(if $(generic-objs_$(type)_template_gen),$(eval $(call generic-objs_$(type)_template_gen,$(class))),\
+		$(eval $(call create_cc_template,$(class),$(type),$($(class)-$(type)-ccopts),$($(class)-$(type)-deps))))))
+
+foreach-src=$(foreach file,$($(1)-srcs),$(eval $(call $(1)-objs_$(subst .,,$(suffix $(file)))_template,$(basename $(file)))))
+$(eval $(foreach class,$(classes),$(call foreach-src,$(class))))
+
+# To supported complex package initializations, we need to call the
+# emitted code explicitly. gnatbind gathers all the calls for us
+# and exports them as a procedure $(stage)_adainit(). Every stage that
+# uses Ada code has to call it!
+define gnatbind_template
+# $1 class
+$$(obj)/$(1)/b__$(1).adb: $$$$(filter-out $$(obj)/$(1)/b__$(1).ali,$$$$($(1)-alis))
+	@printf "    BIND       $$(subst $$(obj)/,,$$@)\n"
+	# We have to give gnatbind a simple filename (without leading
+	# path components) so just cd there.
+	cd $$(dir $$@) && \
+		$$(GNATBIND_$(1)) -a -n \
+			--RTS=$$(absobj)/libgnat-$$(ARCH-$(1)-y)/ \
+			-L$(1)_ada -o $$(notdir $$@) \
+			$$(subst $$(dir $$@),,$$^)
+$$(obj)/$(1)/b__$(1).o: $$(obj)/$(1)/b__$(1).adb
+	@printf "    GCC        $$(subst $$(obj)/,,$$@)\n"
+	$(GCC_$(1)) $$(ADAFLAGS_$(1)) -c -o $$@ $$<
+$(1)-objs += $$(obj)/$(1)/b__$(1).o
+$($(1)-alis): %.ali: %.o ;
+endef
+
+$(eval $(foreach class,$(filter-out libgnat-%,$(classes)), \
+	$(if $($(class)-alis),$(call gnatbind_template,$(class)))))
+
+DEPENDENCIES += $(addsuffix .d,$(basename $(allobjs)))
+-include $(DEPENDENCIES)
+
+printall:
+	@$(foreach class,$(classes), echo $(class)-objs: $($(class)-objs) | tr ' ' '\n'; echo; )
+	@echo alldirs: $(alldirs) | tr ' ' '\n'; echo
+	@echo allsrcs: $(allsrcs) | tr ' ' '\n'; echo
+	@echo DEPENDENCIES: $(DEPENDENCIES) | tr ' ' '\n'; echo
+	@$(foreach class,$(special-classes),echo $(class):'$($(class))' | tr ' ' '\n'; echo; )
+endif
+
+ifndef NOMKDIR
+$(shell mkdir -p $(KCONFIG_SPLITCONFIG) $(objk)/lxdialog $(additional-dirs) $(alldirs))
+endif
+
+$(obj)/project_filelist.txt:
+	if [ -z "$(wildcard $(obj)/coreboot.rom)" ]; then \
+		echo "*** Error: Project must be built before generating file list ***"; \
+		exit 1; \
+	fi
+	find $(obj) -path "$(obj)/util" -prune -o -name "*.d" -exec cat {} \; | \
+	  sed "s|$(top)/||" | sed 's/[:\\]/ /g' | sed 's/ /\n/g' | sort | uniq | \
+	  grep -v '\.o$$' > $(obj)/project_filelist.txt
+
+filelist: $(obj)/project_filelist.txt
+	printf "\nFiles used in build:\n"
+	cat $(obj)/project_filelist.txt
+
+#works with either exuberant ctags or ctags.emacs
+ctags-project: clean-ctags $(obj)/project_filelist.txt
+	cat $(obj)/project_filelist.txt | \
+	  xargs ctags -o tags
+
+cscope-project: clean-cscope $(obj)/project_filelist.txt
+	cat $(obj)/project_filelist.txt | xargs cscope -b
+
+cscope:
+	cscope -bR
+
+doxy: doxygen
+doxygen:
+	$(DOXYGEN) Documentation/Doxyfile.coreboot
+
+doxygen_simple:
+	$(DOXYGEN) Documentation/Doxyfile.coreboot_simple
+
+doxyplatform doxygen_platform: $(obj)/project_filelist.txt
+	echo
+	echo "Building doxygen documentation for $(CONFIG_MAINBOARD_PART_NUMBER)"
+	export DOXYGEN_OUTPUT_DIR="$(DOXYGEN_OUTPUT_DIR)/$(CONFIG_MAINBOARD_VENDOR)/$(CONFIG_MAINBOARD_PART_NUMBER)"; \
+	mkdir -p "$$DOXYGEN_OUTPUT_DIR"; \
+	export DOXYFILES="$$(cat $(obj)/project_filelist.txt | grep -v '\.ld$$' | sed 's/\.aml/\.dsl/' | tr '\n' ' ')"; \
+	export DOXYGEN_PLATFORM="$(CONFIG_MAINBOARD_DIR) ($(CONFIG_MAINBOARD_PART_NUMBER)) version $(KERNELVERSION)"; \
+	$(DOXYGEN) Documentation/doxygen/Doxyfile.coreboot_platform
+
+doxyclean: doxygen-clean
+doxygen-clean:
+	rm -rf $(DOXYGEN_OUTPUT_DIR)
+
+clean-for-update: doxygen-clean clean-for-update-target
+	rm -rf $(obj) .xcompile
+
+clean: clean-for-update clean-target clean-utils
+	rm -f .ccwrap
+
+clean-cscope:
+	rm -f cscope.out
+
+clean-ctags:
+	rm -f tags
+
+clean-utils:
+	$(foreach tool, $(TOOLLIST), \
+		$(MAKE) -C util/$(tool) clean MFLAGS= MAKEFLAGS= ;)
+
+distclean-utils:
+	$(foreach tool, $(TOOLLIST), \
+		$(MAKE) -C util/$(tool) distclean MFLAGS= MAKEFLAGS= ; \
+		rm -f /util/$(tool)/junit.xml;)
+
+distclean: clean clean-ctags clean-cscope distclean-payloads distclean-utils
+	rm -f .config .config.old ..config.tmp* .kconfig.d .tmpconfig* .ccwrap .xcompile
+	rm -rf coreboot-builds coreboot-builds-chromeos
+	rm -f abuild*.xml junit.xml* util/lint/junit.xml
+
+.PHONY: $(PHONY) clean clean-for-update clean-cscope cscope distclean doxygen doxy doxygen_simple
+.PHONY: ctags-project cscope-project clean-ctags

firmware/coreboot/README

@@ -0,0 +1,106 @@
+-------------------------------------------------------------------------------
+coreboot README
+-------------------------------------------------------------------------------
+
+coreboot is a Free Software project aimed at replacing the proprietary BIOS
+(firmware) found in most computers.  coreboot performs a little bit of
+hardware initialization and then executes additional boot logic, called a
+payload.
+
+With the separation of hardware initialization and later boot logic,
+coreboot can scale from specialized applications that run directly
+firmware, run operating systems in flash, load custom
+bootloaders, or implement firmware standards, like PC BIOS services or
+UEFI. This allows for systems to only include the features necessary
+in the target application, reducing the amount of code and flash space
+required.
+
+coreboot was formerly known as LinuxBIOS.
+
+
+Payloads
+--------
+
+After the basic initialization of the hardware has been performed, any
+desired "payload" can be started by coreboot.
+
+See https://www.coreboot.org/Payloads for a list of supported payloads.
+
+
+Supported Hardware
+------------------
+
+coreboot supports a wide range of chipsets, devices, and mainboards.
+
+For details please consult:
+
+ * https://www.coreboot.org/Supported_Motherboards
+ * https://www.coreboot.org/Supported_Chipsets_and_Devices
+
+
+Build Requirements
+------------------
+
+ * make
+ * gcc / g++
+   Because Linux distribution compilers tend to use lots of patches. coreboot
+   does lots of "unusual" things in its build system, some of which break due
+   to those patches, sometimes by gcc aborting, sometimes - and that's worse -
+   by generating broken object code.
+   Two options: use our toolchain (eg. make crosstools-i386) or enable the
+   ANY_TOOLCHAIN Kconfig option if you're feeling lucky (no support in this
+   case).
+ * iasl (for targets with ACPI support)
+ * pkg-config
+ * libssl-dev (openssl)
+
+Optional:
+
+ * doxygen (for generating/viewing documentation)
+ * gdb (for better debugging facilities on some targets)
+ * ncurses (for 'make menuconfig' and 'make nconfig')
+ * flex and bison (for regenerating parsers)
+
+
+Building coreboot
+-----------------
+
+Please consult https://www.coreboot.org/Build_HOWTO for details.
+
+
+Testing coreboot Without Modifying Your Hardware
+------------------------------------------------
+
+If you want to test coreboot without any risks before you really decide
+to use it on your hardware, you can use the QEMU system emulator to run
+coreboot virtually in QEMU.
+
+Please see https://www.coreboot.org/QEMU for details.
+
+
+Website and Mailing List
+------------------------
+
+Further details on the project, a FAQ, many HOWTOs, news, development
+guidelines and more can be found on the coreboot website:
+
+  https://www.coreboot.org
+
+You can contact us directly on the coreboot mailing list:
+
+  https://www.coreboot.org/Mailinglist
+
+
+Copyright and License
+---------------------
+
+The copyright on coreboot is owned by quite a large number of individual
+developers and companies. Please check the individual source files for details.
+
+coreboot is licensed under the terms of the GNU General Public License (GPL).
+Some files are licensed under the "GPL (version 2, or any later version)",
+and some files are licensed under the "GPL, version 2". For some parts, which
+were derived from other projects, other (GPL-compatible) licenses may apply.
+Please check the individual source files for details.
+
+This makes the resulting coreboot images licensed under the GPL, version 2.