From bbb6c792ad5f4f35f31069bd59ec842b1c1ef59f Mon Sep 17 00:00:00 2001 From: Manivannan Sadhasivam Date: Wed, 13 Dec 2023 13:35:41 +0530 Subject: [PATCH 1/8] Add UFS Host Controller to the list of generic node names UFS Host Controller (ufshc) is reponsible for managing the interface between host SW stack and UFS device. In a lot of places, 'ufs' is used as the node name to identify the host controller, but it is wrong since 'ufs' denotes 'UFS device'. Signed-off-by: Manivannan Sadhasivam --- source/chapter2-devicetree-basics.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index 5ab9e6e..86ebc08 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -292,6 +292,7 @@ name should be one of the following choices: * timer * touchscreen * tpm + * ufshc * usb * usb-hub * usb-phy From 2697c66a59b9177f8ff7813c355cc7aa05f6e40a Mon Sep 17 00:00:00 2001 From: Reda Maher Date: Thu, 4 Jan 2024 14:22:48 +0200 Subject: [PATCH 2/8] Fixing some typos and adding missing dots, commas, and hyphens Signed-off-by: Reda Maher --- source/chapter2-devicetree-basics.rst | 6 ++--- source/chapter3-devicenodes.rst | 10 ++++---- source/chapter4-device-bindings.rst | 34 +++++++++++++-------------- source/chapter5-flattened-format.rst | 8 +++---- 4 files changed, 29 insertions(+), 29 deletions(-) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index 86ebc08..b2088fc 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -50,7 +50,7 @@ of its scan, for passing to the Operating System. :numref:`example-simple-devicetree` shows an example representation of a simple devicetree that is nearly complete enough to boot a simple operating system, with the platform -type, CPU, memory and a single UART described. Device nodes are shown +type, CPU, memory, and a single UART described. Device nodes are shown with properties and values inside each node. .. _example-simple-devicetree: @@ -488,7 +488,7 @@ Description: The *compatible* property value consists of one or more strings that define the specific programming model for the device. This list of strings should be used by a client program for device driver selection. - The property value consists of a concatenated list of null terminated + The property value consists of a concatenated list of null-terminated strings, from most specific to most general. They allow a device to express its compatibility with a family of similar devices, potentially allowing a single device driver to match against several devices. @@ -498,7 +498,7 @@ Description: (such as a stock ticker symbol), and ``model`` specifies the model number. - The compatible string should consist only of lowercase letters, digits and + The compatible string should consist only of lowercase letters, digits, and dashes, and should start with a letter. A single comma is typically only used following a vendor prefix. Underscores should not be used. diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index 958257e..5610a78 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -81,7 +81,7 @@ specifies the alias name. The property value specifies the full path to a node in the devicetree. For example, the property serial0 = ``"/simple-bus@fe000000/serial@llc500"`` defines the alias ``serial0``. -Alias names shall be a lowercase text strings of 1 to 31 characters from +Alias names shall be lowercase text strings of 1 to 31 characters from the following set of characters. .. tabularcolumns:: | c p{8cm} | @@ -582,7 +582,7 @@ standard properties with specific applicable detail. If a CPU/thread cannot be the target of an external interrupt, then *reg* must be unique and out of bounds of the range addressed by - the interrupt controller + the interrupt controller. If a CPU/thread's PIR (pending interrupt register) is modifiable, a client @@ -811,12 +811,12 @@ The following properties of a cpu node describe the processor’s internal (combined instructions and data). ``cache-sets`` SD ```` Specifies the number of associativity sets in a unified cache. Required if the cache is - unified (combined instructions and data) + unified (combined instructions and data). ``cache-block-size`` SD ```` Specifies the block size in bytes of a unified cache. Required if the processor has a unified - cache (combined instructions and data) + cache (combined instructions and data). ``cache-line-size`` SD ```` Specifies the line size in bytes of a unified - cache, if different than the cache block size + cache, if different than the cache block size. Required if the processor has a unified cache (combined instructions and data). ``i-cache-size`` SD ```` Specifies the size in bytes of the instruction diff --git a/source/chapter4-device-bindings.rst b/source/chapter4-device-bindings.rst index 02a8fa0..3d93a67 100644 --- a/source/chapter4-device-bindings.rst +++ b/source/chapter4-device-bindings.rst @@ -10,7 +10,7 @@ types and classes of devices are represented in the devicetree. The compatible property of a device node describes the specific binding (or bindings) to which the node complies. -Bindings may be defined as extensions of other each. For example a new +Bindings may be defined as extensions of each other. For example, a new bus type could be defined as an extension of the simple-bus binding. In this case, the compatible property would contain several strings identifying each binding—from the most specific to the most general (see @@ -75,10 +75,10 @@ here to facilitate standardization of names and usage. ```` in one of two forms: a 32-bit integer consisting of one ```` specifying the - frequency + frequency. a 64-bit integer represented as a ```` specifying the - frequency + frequency. =========== ============================================================== ``reg-shift`` Property @@ -115,7 +115,7 @@ here to facilitate standardization of names and usage. Property ``label`` =========== ============================================================== Value type ```` - Description The label property defines a human readable string describing + Description The label property defines a human-readable string describing a device. The binding for a given device specifies the exact meaning of the property for that device. =========== ============================================================== @@ -126,10 +126,10 @@ Serial devices Serial Class Binding ~~~~~~~~~~~~~~~~~~~~ -The class of serial devices consists of various types of point to point +The class of serial devices consists of various types of point-to-point serial line devices. Examples of serial line devices include the 8250 -UART, 16550 UART, HDLC device, and BISYNC device. In most cases hardware -compatible with the RS-232 standard fit into the serial device class. +UART, 16550 UART, HDLC device, and BISYNC device. In most cases, hardware +compatible with the RS-232 standard fits into the serial device class. I\ :sup:`2`\ C and SPI (Serial Peripheral Interface) devices shall not be represented as serial port devices because they have their own @@ -181,12 +181,12 @@ the devicetree using following properties. ======================= ===== ===================== =============================================== ``compatible`` R Value shall include "ns16550". ``clock-frequency`` R ```` Specifies the frequency (in Hz) of the baud - rate generator’s input clock + rate generator’s input clock. ``current-speed`` OR ```` Specifies current serial device speed in bits - per second + per second. ``reg`` R ```` registers device within the address space of - the parent bus + the parent bus. ``interrupts`` OR ```` device. The value of the interrupts property consists of one or more interrupt specifiers. @@ -248,7 +248,7 @@ Network Class Binding =========== ============================================================== Property ``local-mac-address`` =========== ============================================================== - Value type ```` encoded as an array of hex numbers + Value type ```` encoded as an array of hex numbers. Description Specifies MAC address that was assigned to the network device described by the node containing this property. Example ``local-mac-address = [ 00 00 12 34 56 78 ];`` @@ -263,7 +263,7 @@ Network Class Binding =========== ============================================================== Property ``mac-address`` =========== ============================================================== - Value type ```` encoded as an array of hex numbers + Value type ```` encoded as an array of hex numbers. Description Specifies the MAC address that was last used by the boot program. This property should be used in cases where the MAC address assigned to the device by the boot program is @@ -368,8 +368,8 @@ the network device class. Value type ```` Description Specifies a reference to a node representing a physical layer (PHY) device connected to this Ethernet device. This property - is required in case where the Ethernet device is connected a - physical layer device. + is required in case where the Ethernet device is connected to + a physical layer device. Example ``phy-handle = <&PHY0>;`` =========== ============================================================== @@ -402,11 +402,11 @@ specifiers: ======================== ===== ===================== =============================================== Property Name Usage Value Type Definition ======================== ===== ===================== =============================================== - ``compatible`` R ```` Value shall include ``"open-pic"`` + ``compatible`` R ```` Value shall include ``"open-pic"``. ``reg`` R ```` registers device within the address space of - the parent bus - ``interrupt-controller`` R ```` Specifies that this node is an interrupt controller + the parent bus. + ``interrupt-controller`` R ```` Specifies that this node is an interrupt controller. ``#interrupt-cells`` R ```` Shall be 2. ``#address-cells`` R ```` Shall be 0. Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition diff --git a/source/chapter5-flattened-format.rst b/source/chapter5-flattened-format.rst index c7f7a48..03d1217 100644 --- a/source/chapter5-flattened-format.rst +++ b/source/chapter5-flattened-format.rst @@ -6,7 +6,7 @@ Flattened Devicetree (DTB) Format ================================== The Devicetree Blob (DTB) format is a flat binary encoding of devicetree data. -It used to exchange devicetree data between software programs. +It is used to exchange devicetree data between software programs. For example, when booting an operating system, firmware will pass a DTB to the OS kernel. .. note:: @@ -60,10 +60,10 @@ the original definition of the format. Fields in the header give the version, so that the client program can determine if the devicetree is encoded in a compatible format. -This document describes only version 17 of the format. |spec| compliant boot +This document describes only version 17 of the format. |spec|-compliant boot programs shall provide a devicetree of version 17 or later, and should provide a devicetree of a version that is backwards compatible with version 16. -|spec| compliant client programs shall accept devicetrees of any version +|spec|-compliant client programs shall accept devicetrees of any version backwards compatible with version 17 and may accept other versions as well. .. note:: The version is with respect to the binary structure of the device @@ -408,7 +408,7 @@ shall have aligned offsets from the beginning of the devicetree blob. To ensure the in-memory alignment of the blocks, it is sufficient to ensure that the devicetree as a whole is loaded at an address aligned to the largest alignment of any of the subblocks, that is, to an 8-byte -boundary. A |spec| compliant boot +boundary. A |spec|-compliant boot program shall load the devicetree blob at such an aligned address before passing it to the client program. If an |spec| client program relocates the devicetree blob in memory, it should only do so to From 44809f6417cb2410c90588dff18af4dba45942fe Mon Sep 17 00:00:00 2001 From: m0veax Date: Mon, 26 Aug 2024 21:25:56 +0200 Subject: [PATCH 3/8] chapter2: fix example for open_pic - rename open-pic to open_pic to be syntactically valid - add name@addr to nodes - add reg properties Co-authored-by: Daniel Maslowski Signed-off-by: m0veax Signed-off-by: Daniel Maslowski --- source/chapter2-devicetree-basics.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index b2088fc..bc9b2d4 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -1251,29 +1251,31 @@ interrupt controller. #address-cells = <1>; #size-cells = <1>; - open-pic { + open_pic: interrupt-controller@13370000 { + reg = <0x13370000 0x100>; clock-frequency = <0>; interrupt-controller; #address-cells = <0>; #interrupt-cells = <2>; }; - pci { + pci: pci@47110000 { + reg = <0x47110000 0x100>; #interrupt-cells = <1>; #size-cells = <2>; #address-cells = <3>; interrupt-map-mask = <0xf800 0 0 7>; interrupt-map = < /* IDSEL 0x11 - PCI slot 1 */ - 0x8800 0 0 1 &open-pic 2 1 /* INTA */ - 0x8800 0 0 2 &open-pic 3 1 /* INTB */ - 0x8800 0 0 3 &open-pic 4 1 /* INTC */ - 0x8800 0 0 4 &open-pic 1 1 /* INTD */ + 0x8800 0 0 1 &open_pic 2 1 /* INTA */ + 0x8800 0 0 2 &open_pic 3 1 /* INTB */ + 0x8800 0 0 3 &open_pic 4 1 /* INTC */ + 0x8800 0 0 4 &open_pic 1 1 /* INTD */ /* IDSEL 0x12 - PCI slot 2 */ - 0x9000 0 0 1 &open-pic 3 1 /* INTA */ - 0x9000 0 0 2 &open-pic 4 1 /* INTB */ - 0x9000 0 0 3 &open-pic 1 1 /* INTC */ - 0x9000 0 0 4 &open-pic 2 1 /* INTD */ + 0x9000 0 0 1 &open_pic 3 1 /* INTA */ + 0x9000 0 0 2 &open_pic 4 1 /* INTB */ + 0x9000 0 0 3 &open_pic 1 1 /* INTC */ + 0x9000 0 0 4 &open_pic 2 1 /* INTD */ >; }; }; From e57cb794f5d5776bdb76a8f15ff8d04a5499f684 Mon Sep 17 00:00:00 2001 From: Nick Chan Date: Wed, 11 Sep 2024 23:01:36 +0800 Subject: [PATCH 4/8] Add 'television' chassis type The 'television' chassis type includes Smart TVs and set-top boxes, or any remote-controlled displays in general. Signed-off-by: Nick Chan --- source/chapter3-devicenodes.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index 5610a78..948481d 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -63,6 +63,7 @@ are descendants. The full path to the root node is ``/``. * ``"handset"`` * ``"watch"`` * ``"embedded"`` + * ``"television"`` Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition =========================================================================================== From 5688e1c0b961d2ca5a32e3b624a9f4a9b433184f Mon Sep 17 00:00:00 2001 From: Dmitry Baryshkov Date: Sat, 26 Oct 2024 21:52:13 +0300 Subject: [PATCH 5/8] Add 'spectacles' chassis type With the growing interest in the AR/VR/XR devices, it is expected that more and more devices will have the spectacles or eyeglasses-like form factor. Allow documenting such devices by specifying the 'spectacles' chassis-type. Signed-off-by: Dmitry Baryshkov --- source/chapter3-devicenodes.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/chapter3-devicenodes.rst b/source/chapter3-devicenodes.rst index 948481d..8080321 100644 --- a/source/chapter3-devicenodes.rst +++ b/source/chapter3-devicenodes.rst @@ -64,6 +64,7 @@ are descendants. The full path to the root node is ``/``. * ``"watch"`` * ``"embedded"`` * ``"television"`` + * ``"spectacles"`` Usage legend: R=Required, O=Optional, OR=Optional but Recommended, SD=See Definition =========================================================================================== From 4b98097c7897f6de813fd7b244751e2fc5ffebcb Mon Sep 17 00:00:00 2001 From: Raphael Gallais-Pou Date: Mon, 31 Mar 2025 22:02:24 +0200 Subject: [PATCH 6/8] Add display-controller to list of generic node names The device-tree specification does not present a generic node name for hardware compositors. Several names are used, but 'display-controller' is the most straight-forward name to describe such device. Signed-off-by: Raphael Gallais-Pou Link: https://lore.kernel.org/r/20250331200224.41184-1-rgallaispou@gmail.com Signed-off-by: Rob Herring (Arm) --- source/chapter2-devicetree-basics.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index bc9b2d4..7658b19 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -221,6 +221,7 @@ name should be one of the following choices: * crypto * disk * display + * display-controller * dma-controller * dsi * dsp From 3bfe4b67ad59be5f7a41cb5b97b44956958004a7 Mon Sep 17 00:00:00 2001 From: "Rob Herring (Arm)" Date: Tue, 1 Apr 2025 09:19:20 -0500 Subject: [PATCH 7/8] github: Update action to upload-artifact@v4 upload-artifact@v2 is gone now, so update to v4. Signed-off-by: Rob Herring (Arm) --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0b21191..e46cb1d 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -39,7 +39,7 @@ jobs: run: make singlehtml - name: upload - uses: actions/upload-artifact@v2 + uses: actions/upload-artifact@v4 with: name: artifacts path: | From 4e3c31e1ec43a4cb1e3cb0d40138e362f48f7ff8 Mon Sep 17 00:00:00 2001 From: Raphael Gallais-Pou Date: Tue, 1 Apr 2025 13:47:36 +0200 Subject: [PATCH 8/8] chapter2: fix reference to chapter6 Appendix 6 is now chapter 6. Closes #73 Signed-off-by: Raphael Gallais-Pou Link: https://lore.kernel.org/r/20250401114736.56670-1-rgallaispou@gmail.com Signed-off-by: Rob Herring (Arm) --- source/chapter2-devicetree-basics.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/chapter2-devicetree-basics.rst b/source/chapter2-devicetree-basics.rst index 7658b19..ca716a1 100644 --- a/source/chapter2-devicetree-basics.rst +++ b/source/chapter2-devicetree-basics.rst @@ -575,10 +575,10 @@ Example: if a ``phandle`` property is not present. The meaning and use of the two properties is identical. -.. note:: Most devicetrees in :abbr:`DTS (Device Tree Syntax)` (see Appendix A) will not - contain explicit phandle properties. The DTC tool automatically inserts - the ``phandle`` properties when the DTS is compiled into the binary DTB - format. +.. note:: Most devicetrees in :abbr:`DTS (Device Tree Syntax)` (see + :numref:`Chapter %s `) will not contain + explicit phandle properties. The DTC tool automatically inserts the + ``phandle`` properties when the DTS is compiled into the binary DTB format. status ~~~~~~