docs: dt: convert booting-without-of.txt to ReST format

The boot loader must load a device tree image (dtb) into system ram

at a 64bit aligned address and initialize it with the boot data.  The

dtb format is documented in Documentation/devicetree/booting-without-of.txt.

dtb format is documented in Documentation/devicetree/booting-without-of.rst.

The kernel will look for the dtb magic value of 0xd00dfeed at the dtb

physical address to determine if a dtb has been passed instead of a

tagged list.

.. SPDX-License-Identifier: GPL-2.0

==================================================

Booting the Linux/ppc kernel without Open Firmware

           --------------------------------------------------

==================================================

(c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,

Copyright (c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,

IBM Corp.

(c) 2005 Becky Bruce <becky.bruce at freescale.com>,

Copyright (c) 2005 Becky Bruce <becky.bruce at freescale.com>,

Freescale Semiconductor, FSL SOC and 32-bit additions

(c) 2006 MontaVista Software, Inc.

Copyright (c) 2006 MontaVista Software, Inc.

Flash chip node definition

Table of Contents

=================

.. Table of Contents

  I - Introduction

    1) Entry point for arch/arm

Revision Information

====================

   May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.

   May 18, 2005: Rev 0.1

			 - Initial draft, no chapter III yet.

   May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or

   May 19, 2005: Rev 0.2

			 - Add chapter III and bits & pieces here or

                           clarifies the fact that a lot of things are

                           optional, the kernel only requires a very

                           small device tree, though it is encouraged

                           to provide an as complete one as possible.

   May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM

   May 24, 2005: Rev 0.3

			 - Precise that DT block has to be in RAM

			 - Misc fixes

			 - Define version 3 and new format version 16

			   for the DT block (version 16 needs kernel

			   "name" property is now automatically

			   deduced from the unit name

   June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and

   June 1, 2005: Rev 0.4

			 - Correct confusion between OF_DT_END and

                           OF_DT_END_NODE in structure definition.

                         - Change version 16 format to always align

                           property data to 4 bytes. Since tokens are

        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 CONFIG_

        to the Makefile under the condition of your ``CONFIG_``

        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

  with classic Powerpc architectures.

3) Entry point for arch/x86

-------------------------------

---------------------------

  There is one single 32bit entry point to the kernel at code32_start,

  the decompressor (the real mode entry point goes to the same  32bit

  Documentation/x86/boot.rst

  The physical pointer to the device-tree block (defined in chapter II)

  is passed via setup_data which requires at least boot protocol 2.09.

  The type filed is defined as

  The type filed is defined as::

    #define SETUP_DTB                      2

   The kernel is passed the physical address pointing to an area of memory

   that is roughly described in include/linux/of_fdt.h by the structure

   boot_param_header:

   boot_param_header:::

      struct boot_param_header {

        u32     magic;                  /* magic word OF_DT_HEADER */

        u32	size_dt_struct;		/* size of the DT structure block */

      };

   Along with the constants:

   Along with the constants::

    /* Definitions used by the flattened device tree */

    #define OF_DT_HEADER            0xd00dfeed      /* 4: version,

     way to avoid overriding critical things like, on Open Firmware

     capable machines, the RTAS instance, or on some pSeries, the TCE

     tables used for the iommu. Typically, the reserve map should

     contain _at least_ this DT block itself (header,total_size). If

     contain **at least** this DT block itself (header,total_size). If

     you are passing an initrd to the kernel, you should reserve it as

     well. You do not need to reserve the kernel image itself. The map

     should be 64-bit aligned.

   So the typical layout of a DT block (though the various parts don't

   need to be in that order) looks like this (addresses go from top to

   bottom):

   bottom)::

             ------------------------------

you a idea of what a device-tree looks like. I have purposefully kept

the "name" and "linux,phandle" properties which aren't necessary in

order to give you a better idea of what the tree looks like in

practice.

practice::

  / o device-tree

      |- name = "device-tree"

3) Device tree "structure" block

--------------------------------

The structure of the device tree is a linearized tree structure. The

"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE"

       root node)

     * [align gap to next 4 bytes boundary]

     * for each property:

        * token OF_DT_PROP (that is 0x00000003)

        * 32-bit value of property value size in bytes (or 0 if no

          value)

        * 32-bit value of offset in string block of property name

        * property value data if any

        * [align gap to next 4 bytes boundary]

     * [child nodes if any]

     * token OF_DT_END_NODE (that is 0x00000002)

constraint.

4) Device tree "strings" block

------------------------------

In order to save space, property names, which are generally redundant,

are stored separately in the "strings" block. This block is simply the

III - Required content of the device tree

=========================================

WARNING: All "linux,*" properties defined in this document apply only

.. Warning::

   All ``linux,*`` properties defined in this document apply only

   to a flattened device-tree. If your platform uses a real

   implementation of Open Firmware or an implementation compatible with

   the Open Firmware client interface, those properties will be created

"ranges" property is missing at a given level, it's assumed that

translation isn't possible, i.e., the registers are not visible on the

parent bus.  The format of the "ranges" property for a bus is a list

of:

of::

	bus address, parent bus address, size

  This node is the parent of all individual CPU nodes. It doesn't

  have any specific requirements, though it's generally good practice

  to have at least:

  to have at least::

               #address-cells = <00000001>

               #size-cells    = <00000000>

  that format when reading the "reg" properties of a CPU node, see

  below

  c) The /cpus/* nodes

  c) The ``/cpus/*`` nodes

  So under /cpus, you are supposed to create a node for every CPU on

  the machine. There is no specific restriction on the name of the

    - reg : This is the physical CPU number, it's a single 32-bit cell

      and is also used as-is as the unit number for constructing the

      unit name in the full path. For example, with 2 CPUs, you would

      have the full path:

      have the full path::

        /cpus/PowerPC,970FX@0

        /cpus/PowerPC,970FX@1

      (unit addresses do not require leading zeroes)

    - d-cache-block-size : one cell, L1 data cache block size in bytes (*)

    - d-cache-block-size : one cell, L1 data cache block size in bytes [#]_

    - i-cache-block-size : one cell, L1 instruction cache block size in

      bytes

    - d-cache-size : one cell, size of L1 data cache in bytes

    - i-cache-size : one cell, size of L1 instruction cache in bytes

(*) The cache "block" size is the size on which the cache management

    .. [#] The cache "block" size is the size on which the cache management

	   instructions operate. Historically, this document used the cache

	   "line" size here which is incorrect. The kernel will prefer the cache

	   block size and will fallback to cache line size for backward

      #address-cells and #size-cells of the root node. For example,

      with both of these properties being 2 like in the example given

      earlier, a 970 based machine with 6Gb of RAM could typically

      have a "reg" property here that looks like:

      have a "reg" property here that looks like::

        00000000 00000000 00000000 80000000

        00000001 00000000 00000001 00000000

  on the SOC but are not used by a particular platform. See chapter VI

  for more information on how to specify devices that are part of a SOC.

  Example SOC node for the MPC8540:

  Example SOC node for the MPC8540::

	soc8540@e0000000 {

		#address-cells = <1>;

dtc source code can be found at

<http://git.jdl.com/gitweb/?p=dtc.git>

WARNING: This version is still in early development stage; the

.. Warning::

   This version is still in early development stage; the

   resulting device-tree "blobs" have not yet been validated with the

   kernel. The current generated block lacks a useful reserve map (it will

   be fixed to generate an empty one, it's up to the bootloader to fill

dtc basically takes a device-tree in a given format and outputs a

device-tree in another format. The currently supported formats are:

  Input formats:

Input formats

-------------

     - "dtb": "blob" format, that is a flattened device-tree block

       output of /proc/device-tree, that is nodes are directories and

       properties are files

 Output formats:

 ---------------

Output formats

--------------

     - "dtb": "blob" format

     - "dts": "source" format

       assembly file exports some symbols that can be used.

The syntax of the dtc tool is

The syntax of the dtc tool is::

    dtc [-I <input-format>] [-O <output-format>]

        [-o output-filename] [-V output_version] input_filename

uniqueness of linux, phandle properties, validity of strings, etc...

The format of the .dts "source" file is "C" like, supports C and C++

style comments.

style comments::

    / {

    }

The above is the "device-tree" definition. It's the only statement

supported currently at the toplevel.

::

  / {

    property1 = "string_value";	   /* define a property containing a 0

				    * terminated string

If the interrupt-parent property is not defined for a node, its

interrupt parent is assumed to be an ancestor in the node's

_device tree_ hierarchy.

*device tree* hierarchy.

3) OpenPIC Interrupt Controllers

--------------------------------

Sense and level information should be encoded as follows:

	0 = low to high edge sensitive type enabled

	1 = active low level sensitive type enabled

	2 = active high level sensitive type enabled

	3 = high to low edge sensitive type enabled

	==  ========================================

	0   low to high edge sensitive type enabled

	1   active low level sensitive type enabled

	2   active high level sensitive type enabled

	3   high to low edge sensitive type enabled

	==  ========================================

4) ISA Interrupt Controllers

----------------------------

ISA PIC interrupt controllers should adhere to the ISA PIC

encodings listed below:

	0 =  active low level sensitive type enabled

	1 =  active high level sensitive type enabled

	2 =  high to low edge sensitive type enabled

	3 =  low to high edge sensitive type enabled

	==  ========================================

	0   active low level sensitive type enabled

	1   active high level sensitive type enabled

	2   high to low edge sensitive type enabled

	3   low to high edge sensitive type enabled

	==  ========================================

VIII - Specifying Device Power Management Information (sleep property)

===================================================================

======================================================================

Devices on SOCs often have mechanisms for placing devices into low-power

states that are decoupled from the devices' own register blocks.  Sometimes,

sleep-map should wait until its necessity is demonstrated).

IX - Specifying dma bus information

===================================

Some devices may have DMA memory range shifted relatively to the beginning of

RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC

for identifying devices supported coherent DMA operations in DT.

* DMA Bus master

Optional property:

- dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of

  (child-bus-address, parent-bus-address, length). Each triplet specified

  describes a contiguous DMA address range.

  (for more information see the Devicetree Specification)

* DMA Bus child

Optional property:

- dma-ranges: <empty> value. if present - It means that DMA addresses

  translation has to be enabled for this device.

- dma-coherent: Present if dma operations are coherent

Example:

Example::

	soc {

		compatible = "ti,keystone","simple-bus";

		ranges = <0x0 0x0 0x0 0xc0000000>;

Appendix A - Sample SOC node for MPC8540

========================================

::

	soc@e0000000 {

		#address-cells = <1>;

		#size-cells = <1>;

   overlay-notes

   bindings/index

   booting-without-of

bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统

RAM 中，并用启动数据初始化它。dtb 格式在文档

Documentation/devicetree/booting-without-of.txt 中。内核将会在

Documentation/devicetree/booting-without-of.rst 中。内核将会在

dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替

标签列表被传递进来。