:orphan:
.. raw:: html
.. dtcompatible:: nxp,imx-ccm-rev3-root
.. _dtbinding_nxp_imx_ccm_rev3_root:
nxp,imx-ccm-rev3-root
#####################
.. sidebar:: Overview
:Name: ``nxp,imx-ccm-rev3-root``
:Vendor: :ref:`NXP Semiconductors N.V. `
:Used in: :zephyr:board-catalog:`List of boards <#compatibles=nxp,imx-ccm-rev3-root>` using
this compatible
Description
***********
.. code-block:: none
One configurable clock root of an NXP i.MX CCM rev3 controller.
A clock root is the part of the CCM that selects a source and divides it, so
it is what determines the frequency a peripheral receives. Declaring roots as
devicetree nodes puts the clock tree where a board or application overlay can
change it, instead of in a board C file.
The controller programs every enabled root child at initialization, in
devicetree order. Order matters when one root feeds another, and a root whose
selected source is not running yet delivers no clock.
/* CLOCK_ROOT40 */
peri3_rootclk: clock-root@280 {
compatible = "nxp,imx-ccm-rev3-root";
reg = <0x280 0x10>;
nxp,root-id = ;
clock-mux = ;
clock-div = <1>;
};
Mux values are per-root: each root has its own source list, so use the
IMX_CCM_MUX__ identifier that belongs to this root.
Properties
**********
.. tabs::
.. group-tab:: Node specific properties
Properties not inherited from the base binding file.
.. list-table::
:widths: 1 1 4
:header-rows: 1
* - Name
- Type
- Details
* - ``nxp,root-id``
- ``int``
- .. code-block:: none
The flat clock-root identifier the HAL dispatches on -- the clock_root_t
value CLOCK_SetRootClock() takes -- written with the SoC's IMX_CCM_ROOT_*
macro.
This is stated rather than derived from reg on purpose. The two numbers are
two different facts about one slice: reg is the register block the reference
manual lays out, nxp,root-id is the number the HAL uses. Recovering one from
the other needs a per-SoC rule (the instance's identifier start plus the
offset divided by the slice stride), and a rule in a driver shared across
SoCs is a rule the next SoC can invalidate -- silently, since every value
still looks plausible. It is required rather than defaulted because no value
is safe to assume: a wrong identifier programs a different slice.
This property is **required**.
* - ``clock-mux``
- ``int``
- .. code-block:: none
Source selector for this root, from the SoC's IMX_CCM_MUX__
definitions. Mux numbering is per-root; a value belonging to a different
root selects an unrelated source.
This property is **required**.
* - ``clock-div``
- ``int``
- .. code-block:: none
Divider applied to the selected source, as an actual divide value rather
than an encoded field.
Default value: ``1``
* - ``clock-second-div``
- ``int``
- .. code-block:: none
Second divider, for roots that have one; ignored on SoCs whose root
configuration has only one divider.
The default is 1 rather than 0 because 1 is the honest way to say
"divide by one": these properties carry actual divide values, not encoded
register fields, and a divider of 0 is meaningless.
It also avoids a HAL hazard that is real but version-dependent. The HAL
programs the hardware field as (value - 1), so an unguarded implementation
turns 0 into an all-ones field, which the rate calculation then reads back
as the peripheral's frequency. This bit the RT266x bring-up on silicon.
Current RT266x HAL revisions special-case 0 and program divide-by-one, but
this binding is SoC-agnostic and cannot assume every HAL it serves does.
Default value: ``1``
* - ``clock-shutdown``
- ``boolean``
- .. code-block:: none
Leave this root gated off after configuring its mux and dividers, instead
of running it.
* - ``nxp,preconfigured``
- ``boolean``
- .. code-block:: none
This root MUST NOT be programmed by the controller: its value was
established before Zephyr ran, and re-applying even an identical value
would break something. The mux and dividers are still declared on this
node so the value stays devicetree-owned and get_rate can report it, but
the controller's initialization loop skips it.
The property means "must not be touched". It does NOT mean "something else
also programs this". A root that the SoC bring-up programs by reading this
same node is not marked: when the controller later re-applies the value it
writes what is already there, which is idempotent and needs no protection.
Marking such a root would drain the property of meaning and hide the ones
that genuinely cannot be touched.
The case that qualifies is a root on the BOOT MEDIUM's clock path:
- The functional root of the memory this image executes from. The
controller's loop runs from XIP flash and calls a HAL function that also
lives in XIP flash, so re-programming that root cuts the clock feeding
the very fetch in progress. Bringing it up safely requires quiescing and
disabling the controller, parking the clock on a free-running source and
executing from on-chip RAM -- none of which a PRE_KERNEL_1 device init
can do.
- A root whose frequency the boot ROM calibrated against, which must be
preserved bit-for-bit rather than recomputed. On i.MX RT266x the
XSPI1/PSRAM root is anchored to the ROM's dividers because the ROM's DLL
calibration point is tied to that frequency; re-programming it, even to
an apparently equivalent value, leaves the DDR read strobe the ROM DLL
locked to no longer aligned.
- Any root that is a SOURCE of one of the above, since changing it moves
the derived frequency just the same.
Whether a root is on the boot-medium path is a BOARD fact, not a SoC fact.
An SoC devicetree marks the roots for the usual boot configuration; a board
that boots from a different medium removes the marker with
/delete-property/ in its own DTS. It cannot be driven from Kconfig:
devicetree is processed before Kconfig (cmake/modules/zephyr_default.cmake
appends `dts` ahead of `kconfig`, and the devicetree pass generates
Kconfig.dts for Kconfig to consume), so no CONFIG_ symbol is visible here.
One limitation to be aware of: for the XSPI functional roots the SoC
programs the hardware by direct register writes from RAM-resident code that
runs with flash parked. The node makes the rate reportable and the target
mux/div a visible declaration, but editing these properties does not yet
change what that code writes, because it cannot read devicetree at run
time. Driving it from devicetree would require precomputing the derived
register images into on-chip RAM first, which is a separate change.
A root with none of the above does not get this property: it belongs in the
controller's initialization loop, or it is owned by a peripheral that
configures it itself through clock_control_configure().
.. group-tab:: Deprecated node specific properties
Deprecated properties not inherited from the base binding file.
(None)
.. group-tab:: Base properties
Properties inherited from the base binding file, which defines
common properties that may be set on many nodes. Not all of these
may apply to the "nxp,imx-ccm-rev3-root" compatible.
.. list-table::
:widths: 1 1 4
:header-rows: 1
* - Name
- Type
- Details
* - ``reg``
- ``array``
- .. code-block:: none
The slice's register block inside its parent CCM instance: offset
N * and size , for the CLOCK_ROOT the reference manual
gives that instance. The stride is SoC-specific -- 0x10 on RT266x, 0x80 on
RT1170, 0x40 on RT1180 -- and is the step of that SoC's CLOCK_ROOT
register array.
This property is **required**.
See :ref:`zephyr:dt-important-props` for more information.
* - ``status``
- ``string``
- .. code-block:: none
Indicates the operational status of the hardware or other
resource that the node represents. In particular:
- "okay" means the resource is operational and, for example,
can be used by device drivers
- "disabled" means the resource is not operational and the system
should treat it as if it is not present
For details, see "2.3.4 status" in Devicetree Specification v0.4.
Legal values: ``okay``, ``disabled``, ``reserved``, ``fail``, ``fail-sss``
See :ref:`zephyr:dt-important-props` for more information.
* - ``compatible``
- ``string-array``
- .. code-block:: none
This property is a list of strings that essentially define what
type of hardware or other resource this devicetree node
represents. Each device driver checks for specific compatible
property values to find the devicetree nodes that represent
resources that the driver should manage.
The recommended format is "vendor,device", The "vendor" part is
an abbreviated name of the vendor. The "device" is usually from
the datasheet.
The compatible property can have multiple values, ordered from
most- to least-specific. Having additional values is useful when the
device is a specific instance of a more general family, to allow the
system to match the most specific driver available.
For details, see "2.3.1 compatible" in Devicetree Specification v0.4.
This property is **required**.
See :ref:`zephyr:dt-important-props` for more information.
* - ``reg-names``
- ``string-array``
- .. code-block:: none
Optional names given to each register block in the "reg" property.
For example:
/ {
soc {
#address-cells = <1>;
#size-cells = <1>;
uart@1000 {
reg = <0x1000 0x2000>, <0x3000 0x4000>;
reg-names = "foo", "bar";
};
};
};
The uart@1000 node has two register blocks:
- one with base address 0x1000, size 0x2000, and name "foo"
- another with base address 0x3000, size 0x4000, and name "bar"
* - ``ranges``
- ``compound``
- .. code-block:: none
Information used to define a mapping (or translation) between the address
space of a bus (the "child address space") and the address space of the
bus node's parent (the "parent address space").
The "ranges" property is typically empty, or a sequence of triplets
(child bus address, parent bus address, length).
If the "ranges" property is empty, it specifies that the parent and child
address spaces are identical and no address translation is required.
If the "ranges" property is not present in a bus node, it is assumed that
no mapping exists between children of the node and the parent address space.
For details, see "2.3.8 ranges" in Devicetree Specification v0.4.
* - ``interrupts``
- ``array``
- .. code-block:: none
Information about interrupts generated by the device, encoded as an array
of one or more interrupt specifiers. The format of the data in this property
varies by where the device appears in the interrupt tree. Devices with the same
"interrupt-parent" will use the same format in their interrupts properties.
For details, see "2.4 Interrupts and Interrupt Mapping" in
Devicetree Specification v0.4.
See :ref:`zephyr:dt-important-props` for more information.
* - ``interrupts-extended``
- ``compound``
- .. code-block:: none
Extended interrupt specifier for device, used as an alternative to
the "interrupts" property.
For details, see "2.4 Interrupts and Interrupt Mapping" in
Devicetree Specification v0.4.
* - ``interrupt-names``
- ``string-array``
- .. code-block:: none
Optional names given to each interrupt generated by a device.
The interrupts themselves are defined in either "interrupts" or
"interrupts-extended" properties.
For details, see "2.4 Interrupts and Interrupt Mapping" in
Devicetree Specification v0.4.
* - ``interrupt-parent``
- ``phandle``
- .. code-block:: none
If present, this refers to the node which handles interrupts generated
by this device.
For details, see "2.4 Interrupts and Interrupt Mapping" in
Devicetree Specification v0.4.
* - ``label``
- ``string``
- .. code-block:: none
Human readable string describing the device. Use of this property is
deprecated except as needed on a case-by-case basis.
For details, see "4.1.2 Miscellaneous Properties" in Devicetree
Specification v0.4.
See :ref:`zephyr:dt-important-props` for more information.
* - ``clocks``
- ``phandle-array``
- .. code-block:: none
Information about the device's clock providers. In general, this property
should follow conventions established in the dt-schema binding:
https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/clock/clock.yaml
* - ``clock-names``
- ``string-array``
- .. code-block:: none
Optional names given to each clock provider in the "clocks" property.
* - ``#address-cells``
- ``int``
- .. code-block:: none
This property encodes the number of cells used by address fields
in "reg" properties in this node's children.
For details, see "2.3.5 #address-cells and #size-cells" in Devicetree
Specification v0.4.
* - ``#size-cells``
- ``int``
- .. code-block:: none
This property encodes the number of cells used by size fields in
"reg" properties in this node's children.
For details, see "2.3.5 #address-cells and #size-cells" in Devicetree
Specification v0.4.
* - ``dma-coherent``
- ``boolean``
- .. code-block:: none
Indicates that the device is capable of coherent DMA operations.
For details, see "2.3.10 dma-coherent" in Devicetree Specification v0.4.
* - ``dmas``
- ``phandle-array``
- .. code-block:: none
DMA channel specifiers relevant to the device.
* - ``dma-names``
- ``string-array``
- .. code-block:: none
Optional names given to the DMA channel specifiers in the "dmas" property.
* - ``dma-ranges``
- ``compound``
- .. code-block:: none
The dma-ranges provides a means of defining a mapping or translation between the
physical address space of the bus and the physical address space of the parent of the bus.
For details, see "2.3.9 dma-ranges" in Devicetree Specification v0.4.
* - ``io-channels``
- ``phandle-array``
- .. code-block:: none
IO channel specifiers relevant to the device.
* - ``io-channel-names``
- ``string-array``
- .. code-block:: none
Optional names given to the IO channel specifiers in the "io-channels" property.
* - ``mboxes``
- ``phandle-array``
- .. code-block:: none
Mailbox / IPM channel specifiers relevant to the device.
* - ``mbox-names``
- ``string-array``
- .. code-block:: none
Optional names given to the mbox specifiers in the "mboxes" property.
* - ``power-domains``
- ``phandle-array``
- .. code-block:: none
Power domain specifiers relevant to the device.
* - ``power-domain-names``
- ``string-array``
- .. code-block:: none
Optional names given to the power domain specifiers in the "power-domains" property.
* - ``#power-domain-cells``
- ``int``
- .. code-block:: none
Number of cells in power-domains property
* - ``hwlocks``
- ``phandle-array``
- .. code-block:: none
HW spinlock id relevant to the device.
* - ``hwlock-names``
- ``string-array``
- .. code-block:: none
Optional names given to the hwlock specifiers in the "hwlocks" property.
* - ``zephyr,deferred-init``
- ``boolean``
- .. code-block:: none
Do not initialize device automatically on boot. Device should be manually
initialized using device_init().
* - ``wakeup-source``
- ``boolean``
- .. code-block:: none
Property to identify that a device can be used as wake up source.
When this property is provided a specific flag is set into the
device that tells the system that the device is capable of
wake up the system.
Wake up capable devices are disabled (interruptions will not wake up
the system) by default but they can be enabled at runtime if necessary.
* - ``zephyr,pm-device-runtime-auto``
- ``boolean``
- .. code-block:: none
Automatically configure the device for runtime power management after the
init function runs.
* - ``zephyr,disabling-power-states``
- ``phandles``
- .. code-block:: none
List of power states that will disable this device power.