72298ae964
PMP (Physical Memory Protection) is a feature of the RISC-V Privileged Architecture spec, that allows defining region(s) of the address space to be protected in a variety of ways: ranges for M mode can be protected against access from lower privilege levels, and M mode can be locked out of accessig to memory reserved for lower privilege levels. Limits on Read, Write, and Execute are allowed. In coreboot, we protect against Write and Execute of PMP code from lower levels, but allow Reading, so as to ease data structure access. PMP is not a security boundary, it is an accident prevention device. PMP is used here to protect persistent ramstage code that is used to support SBI, e.g. printk and some data structures. It also protects the SBI stacks. Note that there is one stack per hart. There are 512- and 1024-hart SoC's being built today, so the stack should be kept small. PMP is not a general purpose protection mechanism and it is easy to get around it. For example, S mode can stage a DMA that overwrites all the M mode code. PMP is, rather, a way to avoid simple accidents. It is understood that PMP depends on proper OS behavior to implement true SBI security (personal conversation with a RISC-V architect). Think of PMP as "Protection Minus Protection". PMP is also a very limited resource, as defined in the architecture. This language is instructive: "PMP entries are described by an 8-bit configuration register and one XLEN-bit address register. Some PMP settings additionally use the address register associated with the preceding PMP entry. Up to 16 PMP entries are supported. If any PMP entries are implemented, then all PMP CSRs must be implemented, but all PMP CSR fields are WARL and may be hardwired to zero. PMP CSRs are only accessible to M-mode." In other words if you implement PMP even a little, you have to impelement it all; but you can implement it in part by simply returning 0 for a pmpcfg. Also, PMP address registers (pmpaddr) don't have to implement all the bits. On a SiFive FU740, for example, PMP only implements bits 33:0, i.e. a 34 bit address. PMPs are just packed with all kinds of special cases. There are no requirements that you read back what you wrote to the pmpaddr registers. The earlier PMP code would die if the read did not match the write, but, since pmpaddr are WARL, that was not correct. An SoC can just decide it only does 4096-byte granularity, on TOR PMP types, and that is your problem if you wanted finer granulatiry. SoC's don't have to implement all the high order bits either. And, to reiterate, there is no requirement about which of the pmpcfg are implemented. Implementing just pmpcfg15 is allowed. The coreboot SBI code was written before PMP existed. In order for coreboot SBI code to work, this patch is necessary. With this change, a simple S-mode payload that calls SBI putchar works: 1: li a7, 1 li a0, 48 ecall j 1b Without this change, it will not work. Getting this to build on RV32 required changes to the API, as it was incorrect. In RV32, PMP entries are 34 bits. Hence, the setup_pmp needed to accept u64. So, uinptr_t can not be used, as on 32 bits they are only 32 bit numbers. The internal API uses uintptr_t, but the exported API uses u64, so external code does not have to think about right shifts on base and size. Errors are detected: an error in base and size will result in a BIOS_EMERG print, but not a panic. Boots not bricks if possible. There are small changes to the internal API to reduce stack pressure: there's no need to have two pmpcfg_t on the stack when one will do. TEST: Linux now boots partly on the SiFive unmatched. There are changes in flight on the coreboot SBI that will allow Linux to boot further, but they are out of scope for this patch. Currently, clk_ignore_unused is required, this requires a separate patch. Change-Id: I6edce139d340783148cbb446cde004ba96e67944 Signed-off-by: Ronald G Minnich <rminnich@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/81153 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Philipp Hug <philipp@hug.cx>
coreboot README
coreboot is a Free Software project aimed at replacing the proprietary firmware (BIOS/UEFI) found in most computers. coreboot performs the required hardware initialization to configure the system, then passes control to a different executable, referred to in coreboot as the payload. Most often, the primary function of the payload is to boot the operating system (OS).
With the separation of hardware initialization and later boot logic, coreboot is perfect for a wide variety of situations. It can be used for specialized applications that run directly in the firmware, running operating systems from flash, loading custom bootloaders, or implementing firmware standards, like PC BIOS services or UEFI. This flexibility allows coreboot systems to include only the features necessary in the target application, reducing the amount of code and flash space required.
Source code
All source code for coreboot is stored in git. It is downloaded with the command:
git clone https://review.coreboot.org/coreboot.git.
Code reviews are done in the project's Gerrit instance.
The code may be browsed via coreboot's Gitiles instance.
The coreboot project also maintains a mirror of the project on github. This is read-only, as coreboot does not accept github pull requests, but allows browsing and downloading the coreboot source.
Payloads
After the basic initialization of the hardware has been performed, any desired "payload" can be started by coreboot.
See https://doc.coreboot.org/payloads.html for a list of some of coreboot's supported payloads.
Supported Hardware
The coreboot project supports a wide range of architectures, chipsets, devices, and mainboards. While not all of these are documented, you can find some information in the Architecture-specific documentation or the SOC-specific documentation.
For details about the specific mainboard devices that coreboot supports, please consult the Mainboard-specific documentation or the Board Status pages.
Releases
Releases are currently done by coreboot every quarter. The release archives contain the entire coreboot codebase from the time of the release, along with any external submodules. The submodules containing binaries are separated from the general release archives. All of the packages required to build the coreboot toolchains are also kept at coreboot.org in case the websites change, or those specific packages become unavailable in the future.
All releases are available on the coreboot download page.
Please note that the coreboot releases are best considered as snapshots of the codebase, and do not currently guarantee any sort of extra stability.
Build Requirements and building coreboot
The coreboot build, associated utilities and payloads require many additional tools and packages to build. The actual coreboot binary is typically built using a coreboot-controlled toolchain to provide reproducibility across various platforms. It is also possible, though not recommended, to make it directly with your system toolchain. Operating systems and distributions come with an unknown variety of system tools and utilities installed. Because of this, it isn't reasonable to list all the required packages to do a build, but the documentation lists the requirements for a few different Linux distributions.
To see the list of tools and libraries, along with a list of instructions to get started building coreboot, go to the Starting from scratch tutorial page.
That same page goes through how to use QEMU to boot the build and see the output.
Website and Mailing List
Further details on the project, as well as links to documentation and more can be found on the coreboot website:
You can contact us directly on the coreboot mailing list:
https://doc.coreboot.org/community/forums.html
Copyrights and Licenses
Uncopyrightable files
There are many files in the coreboot tree that we feel are not copyrightable due to a lack of creative content.
"In order to qualify for copyright protection in the United States, a work must satisfy the originality requirement, which has two parts. The work must have “at least a modicum” of creativity, and it must be the independent creation of its author."
https://guides.lib.umich.edu/copyrightbasics/copyrightability
Similar terms apply to other locations.
These uncopyrightable files include:
- Empty files or files with only a comment explaining their existence. These may be required to exist as part of the build process but are not needed for the particular project.
- Configuration files either in binary or text form. Examples would be files such as .vbt files describing graphics configuration, .apcb files containing configuration parameters for AMD firmware binaries, and spd files as binary .spd or text *spd*.hex representing memory chip configuration.
- Machine-generated files containing version numbers, dates, hash values or other "non-creative" content.
As non-creative content, these files are in the public domain by default. As such, the coreboot project excludes them from the project's general license even though they may be included in a final binary.
If there are questions or concerns about this policy, please get in touch with the coreboot project via the mailing list.
Copyrights
The copyright on coreboot is owned by quite a large number of individual developers and companies. A list of companies and individuals with known copyright claims is present at the top level of the coreboot source tree in the 'AUTHORS' file. Please check the git history of each of the source files for details.
Licenses
Because of the way coreboot began, using a significant amount of source code from the Linux kernel, it's licensed the same way as the Linux Kernel, with GNU General Public License (GPL) Version 2. Individual files are licensed under various licenses, though all are compatible with GPLv2. The resulting coreboot image is licensed under the GPL, version 2. All source files should have an SPDX license identifier at the top for clarification.
Files under coreboot/Documentation/ are licensed under CC-BY 4.0 terms. As an exception, files under Documentation/ with a history older than 2017-05-24 might be under different licenses.
Files in the coreboot/src/commonlib/bsd directory are all licensed with the BSD-3-clause license. Many are also dual-licensed GPL-2.0-only or GPL-2.0-or-later. These files are intended to be shared with libpayload or other BSD licensed projects.
The libpayload project contained in coreboot/payloads/libpayload may be licensed as BSD or GPL, depending on the code pulled in during the build process. All GPL source code should be excluded unless the Kconfig option to include it is set.
The Software Freedom Conservancy
Since 2017, coreboot has been a member of The Software Freedom Conservancy, a nonprofit organization devoted to ethical technology and driving initiatives to make technology more inclusive. The conservancy acts as coreboot's fiscal sponsor and legal advisor.