1# SPDX-License-Identifier: BSD-2-Clause
2# Copyright 2022 Google LLC
3%YAML 1.2
4---
5$id: http://devicetree.org/schemas/bootph.yaml#
6$schema: http://devicetree.org/meta-schemas/core.yaml#
7
8title: Boot-phase-specific device nodes
9
10maintainers:
11  - Simon Glass <sjg@chromium.org>
12
13description: |
14  Some programs run in memory-constrained environments yet want to make use
15  of device tree.
16
17  The full device tree is often quite large relative to the available memory
18  of a boot phase, so cannot fit into every phase of the boot process. Even
19  when memory is not a problem, some phases may wish to limit which device
20  nodes are present, so as to reduce execution time.
21
22  This binding supports adding tags to device tree nodes to allow them to be
23  marked according to the phases where they should be included.
24
25  Without any tags, nodes are included only in the final phase, where all
26  memory is available. Any untagged nodes are dropped from previous phases
27  and are ignored before the final phase is reached.
28
29  The build process produces a separate executable for each phase. It can
30  use fdtgrep to drop any nodes which are not needed for a particular build.
31  For example, the pre-sram build will drop any nodes which are not marked
32  with bootph-pre-sram or bootph-all tags.
33
34  Note that phase builds may drop the tags, since they have served their
35  purpose by that point. So when looking at phase-specific device tree files
36  you may not see these tags.
37
38  Multiple tags can be used in the same node.
39
40  Tags in a child node are implied to be present in all parent nodes as well.
41  This is important, since some missing properties (such as "ranges", or
42  "compatible") can cause the child node to be ignored or incorrectly
43  parsed.
44
45  That said, at present, fdtgrep applies tags only to the node they are
46  added to, not to any parents. This means U-Boot device tree files often
47  add the same tag to parent nodes, rather than relying on tooling to do
48  this. This is a limitation of fdtgrep and it will be addressed so that
49  'Linux DTs' do not need to do this.
50
51  The available tags are described as properties below, in order of phase
52  execution.
53
54select: true
55
56properties:
57  bootph-pre-sram:
58    type: boolean
59    description:
60      Enable this node when SRAM is not available. This phase must set up
61      some SRAM or cache-as-RAM so it can obtain data/BSS space to use
62      during execution.
63
64  bootph-verify:
65    type: boolean
66    description:
67      Enable this node in the verification step, which decides which of the
68      available images should be run next.
69
70  bootph-pre-ram:
71    type: boolean
72    description:
73      Enable this node in the phase that sets up SDRAM.
74
75  bootph-some-ram:
76    type: boolean
77    description:
78      Enable this node in the phase that is run after SDRAM is working but
79      before all of it is available. Some RAM is available but it is limited
80      (e.g. it may be split into two pieces by the location of the running
81      program) because the program code is not yet relocated out of the way.
82
83  bootph-all:
84    type: boolean
85    description:
86      Include this node in all phases (for U-Boot see enum u_boot_phase).
87
88additionalProperties: true
89