Documentation/index.md

   1 # Welcome to the coreboot documentation
   2
   3 This is the developer documentation for [coreboot](https://coreboot.org).
   4 It is built from Markdown files in the [Documentation] directory in the
   5 source code.
   6
   7 ## Spelling of coreboot
   8
   9 The correct spelling of coreboot is completely in lower case characters and in
  10 one word without a space between the two parts.
  11
  12 ## Purpose of coreboot
  13
  14 coreboot is a project to develop open source boot firmware for various
  15 architectures. Its design philosophy is to do the bare minimum necessary to
  16 ensure that hardware is usable and then pass control to a different program
  17 called the _payload_.
  18
  19 ### Separation of concerns
  20
  21 The payload can then provide user interfaces, file system drivers,
  22 various policies etc. to load the OS. Through this separation of concerns
  23 coreboot maximizes reusability of the complicated and fundamental hardware
  24 initialization routines across many different use cases, no matter if
  25 they provide standard interfaces or entirely custom boot flows.
  26
  27 Popular [payloads](payloads.md) in use with coreboot are SeaBIOS,
  28 which provides PCBIOS services, edk2, which provides UEFI services,
  29 GRUB2, the bootloader used by many Linux distributions, or depthcharge,
  30 a custom boot loader used on Chromebooks.
  31
  32 ### No resident services (if possible)
  33
  34 Ideally coreboot completely hands over control to the payload with no
  35 piece of coreboot remaining resident in the system, or even available
  36 for callback.  Given the reality of contemporary computer design,
  37 there's often a small piece that survives for the whole runtime of
  38 the computer. It runs in a highly privileged CPU mode (e.g. SMM on x86)
  39 and provides some limited amount of services to the OS. But here, too,
  40 coreboot aims to keep everything at the minimum possible, both in scope
  41 (e.g. services provided) and code size.
  42
  43 ### No specification of its own
  44
  45 coreboot uses a very minimal interface to the payload, and otherwise
  46 doesn't impose any standards on the ecosystem. This is made possible by
  47 separating out concerns (interfaces and resident services are delegated
  48 to the payload), but it's also a value that is deeply ingrained in the
  49 project. We fearlessly rip out parts of the architecture and remodel it
  50 when a better way of doing the same was identified.
  51
  52 That said, since there are attempts to coerce coreboot to move in various
  53 directions by outside "standardization", long-established practices of
  54 coreboot as well as aligned projects can be documented as best practices,
  55 making them standards in their own right. However we reserve the right to
  56 retire them as the landscape shifts around us.
  57
  58 ### One tree for everything
  59
  60 Another difference to various other firmware projects is that we try
  61 to avoid fragmentation: the traditional development model of firmware
  62 is one of "set and forget" in which some code base is copied, adapted
  63 for the purpose at hands, shipped and only touched again if there's an
  64 important fix to do.
  65
  66 All newer development happens on another copy of some code base without
  67 flowing back to any older copy, and so normally there's a huge amount
  68 of fragmentation.
  69
  70 In coreboot, we try to keep everything in a single source tree, and
  71 lift up older devices when we change something fundamentally. That way,
  72 new and old devices benefit alike from new development in the common parts.
  73
  74 There's a downside to that: Some devices might have no maintainer anymore
  75 who could ensure that coreboot is still functional for them after a big
  76 rework, or maybe a rework even requires knowledge that doesn't exist
  77 anymore within the project (for example because the developer moved on
  78 to do something else).
  79
  80 In this case, we announce the deprecation of the device and defer the big
  81 rework until the deprecation period passed, typically 6-12 months. This
  82 gives interested developers a chance to step in and bring devices up to
  83 latest standards.
  84
  85 While without this deprecation mechanism we could inflate the number
  86 of supported devices (probably 300+), only a tiny fraction of them
  87 would even work, which helps nobody.
  88
  89 ## Scope of the coreboot project
  90
  91 coreboot as a project is closer to the Linux kernel than to most
  92 user level programs. One place where this becomes apparent is the
  93 distribution mechanism: The project itself only provides source code
  94 and does not ship ready-to-install coreboot-based firmware binaries.
  95
  96 What the project distributes, even if - strictly speaking - it's not
  97 part of the project, is a collection of vendor binaries (that we call
  98 "blobs") that are redistributable. They cover the parts of hardware init
  99 that we haven't managed to open up, and while some hardware requires them,
 100 there's still hardware that can boot without any such binary components.
 101
 102 The build system can integrate them into the build automatically if
 103 required, but that requires explicit opt-in and downloads a separate
 104 repository to ensure that the distinction remains clear.
 105
 106 There are various [distributions](distributions.md), some shipping
 107 coreboot with their hardware (e.g. Purism or Chromebooks), others
 108 providing after-market images for various devices (e.g. Libreboot,
 109 MrChromebox).
 110
 111 If you want to use coreboot on your system, that's great!
 112
 113 Please note that the infrastructure around coreboot.org is built for
 114 development purposes. We gladly help out users through our communication
 115 channels, but we also expect a "firmware developer mindset": If compiling
 116 your own firmware and, at some point, recovering from a bad flash by
 117 hooking wires onto chips in your computer sounds scary to you, you're
 118 right, as it is.
 119
 120 If that's _way_ beyond your comfort zone, consider looking into the
 121 various distributions, as they typically provide pre-tested binaries
 122 which massively reduces the risk that the binary you write to flash is
 123 one that won't boot the system (with the consequence that to get it to work
 124 again, you'll need to attach various tools to various chips)
 125
 126 ## The coreboot community
 127
 128 If you're interested in getting your hands dirty (incl. potentially wiring
 129 up an external flasher to your computer), you've come to the right place!
 130
 131 We have various [forums](community/forums.md) where we discuss and coordinate
 132 our activities, review patches, and help out each other. To
 133 help promote a positive atmosphere, we established a [Code of
 134 Conduct](community/code_of_conduct.md). We invested a lot of time
 135 to balance it out, so please keep it in mind when engaging with the
 136 coreboot community.
 137
 138 Every now and then, coreboot is present in one way or another at
 139 [conferences](community/conferences.md). If you're around, come and
 140 say hello!
 141
 142 ## Getting the source code
 143
 144 coreboot is primarily developed in the
 145 [git](https://review.coreboot.org/plugins/gitiles/coreboot) version control
 146 system, using [Gerrit](https://review.coreboot.org) to manage
 147 contributions and code review.
 148
 149 In general we try to keep the `main` branch in the repository functional
 150 for all hardware we support. So far, the only guarantee we can make is
 151 that the main branch will (nearly) always build for all boards in a
 152 standard configuration.
 153
 154 However, we're continually working on improvements to our infrastructure to
 155 get better in that respect, e.g. by setting up boot testing facilities. This
 156 is obviously more complex than regular integration testing, so progress
 157 is slow.
 158
 159 ### What our releases mean
 160
 161 We also schedule two source code releases every year, around April and
 162 October. These releases see some very limited testing and mostly serve
 163 as synchronization points for deprecation notices and for other projects
 164 such as external distributions.
 165
 166 This approach and terminology differs somewhat from how other projects handle
 167 releases where releases are well-tested artifacts and the development
 168 repository tends to be unstable. The "rolling release" model of some projects,
 169 for example OpenBSD, is probably the closest cousin of our approach.
 170
 171 Contents:
 172
 173 ```{toctree}
 174 :maxdepth: 1
 175
 176 Getting Started <getting_started/index.md>
 177 Tutorial <tutorial/index.md>
 178 Contributing <contributing/index.md>
 179 Community <community/index.md>
 180 Payloads <payloads.md>
 181 Distributions <distributions.md>
 182 Technotes <technotes/index.md>
 183 ACPI <acpi/index.md>
 184 Native Graphics Initialization with libgfxinit <gfx/libgfxinit.md>
 185 Display panel <gfx/display-panel.md>
 186 CPU Architecture <arch/index.md>
 187 Platform independent drivers <drivers/index.md>
 188 Northbridge <northbridge/index.md>
 189 System on Chip <soc/index.md>
 190 Mainboard <mainboard/index.md>
 191 Payloads <lib/payloads/index.md>
 192 Libraries <lib/index.md>
 193 Options <lib/option.md>
 194 Security <security/index.md>
 195 SuperIO <superio/index.md>
 196 Vendorcode <vendorcode/index.md>
 197 Utilities <util.md>
 198 Software Bill of Materials <sbom/sbom.md>
 199 Project infrastructure & services <infrastructure/index.md>
 200 Boards supported in each release directory <releases/boards_supported_on_branches.md>
 201 Release notes <releases/index.md>
 202 Acronyms & Definitions <acronyms.md>
 203 External Resources <external_docs.md>
 204 Documentation License <documentation_license.md>
 205 ```
 206
 207 [Documentation]: https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/main/Documentation/