.. _SD.Bootloader.PmicConfig:

.. include:: /content/swdocs.rsts

.. spelling::
   pad
   init
   DTS
   sdmmc
   hv
   eqos
   io
   ao
   ufs
   qspi
   DTSI
   SoC
   PMC
   IMPL
   bct
   GPIO
   pinmux
   dtsi
   pinctrl
   lpdr
   tristate
   ps
   PADCTL
   i2c
   I2C
   DRAM
   FPS
   PWM
   MMIO
   PMIC
   Vout
   SOC
   Hz
   pwm
   mmio
   memio
   addr
   frq
   hz
   ns

PMIC Configuration
!!!!!!!!!!!!!!!!!!

During the system boot, MB1 enables system power rails for CPU, CORE, and DRAM and completes some system PMIC configurations. The typical configurations are:

- Enabling rails
- Setting rail voltages
- Configuring FPS

Enabling and setting of voltages of rails might require the following platform-specific configurations:

- I2C commands to devices
- PWM commands to devices
- MMIO accesses to Tegra registers, read-modify-write or write-only
- Delay after the commands

The entries in PMIC configuration files are common or rail-specific.

Common Configuration
@@@@@@@@@@@@@@@@@@@@

The common configuration parameters apply to all rails.

Each PMIC common configuration is of the following form:

.. code-block:: none

   / {
       pmic {
         <parameter> = <value>;
         };
     };

where ``<parameter>`` is one of the following:

.. list-table::
   :widths: auto
   :header-rows: 1

   * - <parameter>
     - Description
   * - rail-count
     - Number of rails in the configuration file.
   * - command-retries-count
     - The number of allowed command attempts.
   * - wait-before-start-bus-clear-us
     - Wait timeout in microseconds before issuing the bus clear command.
       - The wait time is calculated as 1 <<n microseconds where n is provided by this parameter.

Rail-Specific Configuration
@@@@@@@@@@@@@@@@@@@@@@@@@@@
The rail-specific configuration are divided into blocks:

- Each rail can have one or more blocks.
- Each block can have only one command type:
  - I2C
  - PWM
  - MMIO

Each PMIC rail-specific configuration is of the following form:

.. code-block:: none

   / {
       pmic {
         <rail-name> {
           block@<index> {
             <parameter> = <value>;
           };
         };
      };
   };


where:

- ``<rail-name>`` identifies the rail and is one of the following:

.. list-table::
   :widths: auto
   :header-rows: 1

   * - Name
     - Description
   * - system
     - System PMIC configuration.
   * - cpu/cpu0
     - CPU rail configuration.
   * - cpu1
     - CPU rail configuration.
   * - core
     - Core/SOC rail configuration.
   * - memio
     - DRAM-related rail configuration.
   * - thermal
     - External thermal sensor configuration.
   * - platform
     - Platform's other 12C configuration.
	 
- ``block-<index>``: The rail-specific commands are divided into blocks. 
  
  Each rail can have multiple blocks, and each block of rails is indexed starting from 0.
	
- ``<parameter>`` is one of the following:

.. list-table::
   :widths: auto
   :header-rows: 1
   
   * - <parameter>
     - Description
   * - ``<type>``
     - Type of commands in the block. Valid properties are i2c-controller, pwm or mmio.
   * -

          .. code-block:: none
       
           commands {
            <group-name> {
            command@N {
            reg-addr = <reg-address>; mask = <reg-mask>;
            value = <reg-value>;
            };
            };
           };

     - ``<group-name>`` node is the logical command group name and it is optional. 

       N is the sequential number for the command starting from 0. MMIO or I2C commands (based on type).

        - ``mmio``
        - MMIO command (valid only if block has mmio property), where the following applies:
           - ``<address>`` is absolute address of MMIO register.
           - ``<mask>`` is the 32-bit mask that is applied to the value read from the MMIO address to facilitate the read-modify-write operation.
           - ``<value>`` value written into the register.

        - i2c controller		
        - 12c command, where the following applies:
           - ``<address>`` is the I2c slave register address.
           - ``<mask>`` is I2C slave mask that is applied to the value read from the I2C slave register, to facilitate read-modify-write operation.
           - ``<value>`` value written into the register.                                                           
   * - ``<12c-parameter>``
     - 12C parameter (valid only if the block has the i2c-controller property).

        - block-delay
           - Delay (in microseconds), after each command in the block.
              - ``<index>`` is the block index (starting from 0).
        - i2c-controller-id
           - i2c-controller instance.
        - slave-addr
           - 7-bit i2C slave address.
        - reg-data-size
           - Register size in bits.
           - Valid values are 0 (1 byte) and 16 (2-byte).
           - reg-addr-size
              - Register address size in bits. 
              - Valid values are 0 (1-byte), 8 (1-byte), and 16 (2-byte).
   * - ``pwm``
     - PWM parameter (valid only if the block has the pwm property).

        - controller-id
           - PWM controller instance (0-7)
        - source-frq-hz
           - PWM clock source frequency (in Hz)
        - period-ns
           - PWM period (in nanoseconds)
        - min-microvolts
           - Vout from the PWM regulator if duty cycle is 100.
        - max-microvolts
           - Vout from the PWM regulator if duty cycle is 100.
        - init-microvolts
           - Vout from the PWM regulator after initialization.
        - enable
           - 0 (configures PWM, but does not enable).
           - 1 (enable PWM after configuration).
