<!DOCTYPE html>
<html lang="en" data-content_root="../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>DeviceTree Booting — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../_static/alabaster.css?v=3918102e" />
<script src="../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../_static/doctools.js?v=9bcbadda"></script>
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="The PowerPC boot wrapper" href="bootwrapper.html" />
<link rel="prev" title="NUMA resource associativity" href="associativity.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../index.html">
<img class="logo" src="../../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/index.html">All development-process docs</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../subsystem-apis.html">Subsystems</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">CPU architectures</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../arc/index.html">ARC architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../arm/index.html">ARM Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../arm64/index.html">ARM64 Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../loongarch/index.html">LoongArch Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../m68k/index.html">m68k Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../mips/index.html">MIPS-specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../nios2/index.html">Nios II Specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../openrisc/index.html">OpenRISC Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../parisc/index.html">PA-RISC Architecture</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">powerpc</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="associativity.html">NUMA resource associativity</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">DeviceTree Booting</a></li>
<li class="toctree-l3"><a class="reference internal" href="bootwrapper.html">The PowerPC boot wrapper</a></li>
<li class="toctree-l3"><a class="reference internal" href="cpu_families.html">CPU Families</a></li>
<li class="toctree-l3"><a class="reference internal" href="cpu_features.html">CPU Features</a></li>
<li class="toctree-l3"><a class="reference internal" href="dawr-power9.html">DAWR issues on POWER9</a></li>
<li class="toctree-l3"><a class="reference internal" href="dexcr.html">DEXCR (Dynamic Execution Control Register)</a></li>
<li class="toctree-l3"><a class="reference internal" href="dscr.html">DSCR (Data Stream Control Register)</a></li>
<li class="toctree-l3"><a class="reference internal" href="eeh-pci-error-recovery.html">PCI Bus EEH Error Recovery</a></li>
<li class="toctree-l3"><a class="reference internal" href="elf_hwcaps.html">POWERPC ELF HWCAPs</a></li>
<li class="toctree-l3"><a class="reference internal" href="elfnote.html">ELF Note PowerPC Namespace</a></li>
<li class="toctree-l3"><a class="reference internal" href="firmware-assisted-dump.html">Firmware-Assisted Dump</a></li>
<li class="toctree-l3"><a class="reference internal" href="htm.html">HTM (Hardware Trace Macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="hvcs.html">HVCS IBM “Hypervisor Virtual Console Server” Installation Guide</a></li>
<li class="toctree-l3"><a class="reference internal" href="imc.html">IMC (In-Memory Collection Counters)</a></li>
<li class="toctree-l3"><a class="reference internal" href="isa-versions.html">CPU to ISA Version Mapping</a></li>
<li class="toctree-l3"><a class="reference internal" href="kaslr-booke32.html">KASLR for Freescale BookE32</a></li>
<li class="toctree-l3"><a class="reference internal" href="mpc52xx.html">Linux 2.6.x on MPC52xx family</a></li>
<li class="toctree-l3"><a class="reference internal" href="kvm-nested.html">Nested KVM on POWER</a></li>
<li class="toctree-l3"><a class="reference internal" href="papr_hcalls.html">Hypercall Op-codes (hcalls)</a></li>
<li class="toctree-l3"><a class="reference internal" href="pci_iov_resource_on_powernv.html">PCI Express I/O Virtualization Resource on Powerenv</a></li>
<li class="toctree-l3"><a class="reference internal" href="pmu-ebb.html">PMU Event Based Branches</a></li>
<li class="toctree-l3"><a class="reference internal" href="ptrace.html">Ptrace</a></li>
<li class="toctree-l3"><a class="reference internal" href="qe_firmware.html">Freescale QUICC Engine Firmware Uploading</a></li>
<li class="toctree-l3"><a class="reference internal" href="syscall64-abi.html">Power Architecture 64-bit Linux system call ABI</a></li>
<li class="toctree-l3"><a class="reference internal" href="transactional_memory.html">Transactional Memory support</a></li>
<li class="toctree-l3"><a class="reference internal" href="ultravisor.html">Protected Execution Facility</a></li>
<li class="toctree-l3"><a class="reference internal" href="vas-api.html">Virtual Accelerator Switchboard (VAS) userspace API</a></li>
<li class="toctree-l3"><a class="reference internal" href="vcpudispatch_stats.html">VCPU Dispatch Statistics</a></li>
<li class="toctree-l3"><a class="reference internal" href="vmemmap_dedup.html">Device DAX</a></li>
<li class="toctree-l3"><a class="reference internal" href="vpa-dtl.html">DTL (Dispatch Trace Log)</a></li>
<li class="toctree-l3"><a class="reference internal" href="features.html">Feature status on powerpc architecture</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../riscv/index.html">RISC-V architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../s390/index.html">s390 Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sh/index.html">SuperH Interfaces Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../sparc/index.html">Sparc Architecture</a></li>
<li class="toctree-l2"><a class="reference internal" href="../x86/index.html">x86-specific Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../xtensa/index.html">Xtensa Architecture</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/arch/powerpc/booting.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="devicetree-booting">
<h1>DeviceTree Booting<a class="headerlink" href="#devicetree-booting" title="Link to this heading">¶</a></h1>
<p>During the development of the Linux/ppc64 kernel, and more specifically, the
addition of new platform types outside of the old IBM pSeries/iSeries pair, it
was decided to enforce some strict rules regarding the kernel entry and
bootloader <-> kernel interfaces, in order to avoid the degeneration that had
become the ppc32 kernel entry point and the way a new platform should be added
to the kernel. The legacy iSeries platform breaks those rules as it predates
this scheme, but no new board support will be accepted in the main tree that
doesn’t follow them properly. In addition, since the advent of the arch/powerpc
merged architecture for ppc32 and ppc64, new 32-bit platforms and 32-bit
platforms which move into arch/powerpc will be required to use these rules as
well.</p>
<p>The main requirement that will be defined in more detail below is the presence
of a device-tree whose format is defined after Open Firmware specification.
However, in order to make life easier to embedded board vendors, the kernel
doesn’t require the device-tree to represent every device in the system and only
requires some nodes and properties to be present. For example, the kernel does
not require you to create a node for every PCI device in the system. It is a
requirement to have a node for PCI host bridges in order to provide interrupt
routing information and memory/IO ranges, among others. It is also recommended
to define nodes for on chip devices and other buses that don’t specifically fit
in an existing OF specification. This creates a great flexibility in the way the
kernel can then probe those and match drivers to device, without having to hard
code all sorts of tables. It also makes it more flexible for board vendors to do
minor hardware upgrades without significantly impacting the kernel code or
cluttering it with special cases.</p>
<section id="entry-point">
<h2>Entry point<a class="headerlink" href="#entry-point" title="Link to this heading">¶</a></h2>
<p>There is one single entry point to the kernel, at the start
of the kernel image. That entry point supports two calling
conventions:</p>
<blockquote>
<div><p>a) Boot from Open Firmware. If your firmware is compatible
with Open Firmware (IEEE 1275) or provides an OF compatible
client interface API (support for “interpret” callback of
forth words isn’t required), you can enter the kernel with:</p>
<blockquote>
<div><p>r5 : OF callback pointer as defined by IEEE 1275
bindings to powerpc. Only the 32-bit client interface
is currently supported</p>
<p>r3, r4 : address & length of an initrd if any or 0</p>
<p>The MMU is either on or off; the kernel will run the
trampoline located in arch/powerpc/kernel/prom_init.c to
extract the device-tree and other information from open
firmware and build a flattened device-tree as described
in b). <code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">prom_init()</span></code> will then re-enter the kernel using
the second method. This trampoline code runs in the
context of the firmware, which is supposed to handle all
exceptions during that time.</p>
</div></blockquote>
<p>b) Direct entry with a flattened device-tree block. This entry
point is called by a) after the OF trampoline and can also be
called directly by a bootloader that does not support the Open
Firmware client interface. It is also used by “kexec” to
implement “hot” booting of a new kernel from a previous
running one. This method is what I will describe in more
details in this document, as method a) is simply standard Open
Firmware, and thus should be implemented according to the
various standard documents defining it and its binding to the
PowerPC platform. The entry point definition then becomes:</p>
<blockquote>
<div><p>r3 : physical pointer to the device-tree block
(defined in chapter II) in RAM</p>
<p>r4 : physical pointer to the kernel itself. This is
used by the assembly code to properly disable the MMU
in case you are entering the kernel with MMU enabled
and a non-1:1 mapping.</p>
<p>r5 : NULL (as to differentiate with method a)</p>
</div></blockquote>
</div></blockquote>
<p>Note about SMP entry: Either your firmware puts your other
CPUs in some sleep loop or spin loop in ROM where you can get
them out via a soft reset or some other means, in which case
you don’t need to care, or you’ll have to enter the kernel
with all CPUs. The way to do that with method b) will be
described in a later revision of this document.</p>
<p>Board supports (platforms) are not exclusive config options. An
arbitrary set of board supports can be built in a single kernel
image. The kernel will “know” what set of functions to use for a
given platform based on the content of the device-tree. Thus, you
should:</p>
<blockquote>
<div><p>a) add your platform support as a _boolean_ option in
arch/powerpc/Kconfig, following the example of PPC_PSERIES
and PPC_PMAC. The latter is probably a good
example of a board support to start from.</p>
<p>b) create your main platform file as
“arch/powerpc/platforms/myplatform/myboard_setup.c” and add it
to the Makefile under the condition of your <code class="docutils literal notranslate"><span class="pre">CONFIG_</span></code>
option. This file will define a structure of type “ppc_md”
containing the various callbacks that the generic code will
use to get to your platform specific code</p>
</div></blockquote>
<p>A kernel image may support multiple platforms, but only if the
platforms feature the same core architecture. A single kernel build
cannot support both configurations with Book E and configurations
with classic Powerpc architectures.</p>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../../_sources/arch/powerpc/booting.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>