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