| Simon Glass | fb237b5 | 2023-02-13 08:56:31 -0700 | [diff] [blame] | 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 | |
| 8 | title: Boot-phase-specific device nodes |
| 9 | |
| 10 | maintainers: |
| 11 | - Simon Glass <sjg@chromium.org> |
| 12 | |
| 13 | description: | |
| 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 | |
| 54 | select: true |
| 55 | |
| 56 | properties: |
| 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 | |
| 88 | additionalProperties: true |