# Low Dropout Voltage Regulator (LDO)

[中文]

## Introduction

The ESP32-P4 chip internally integrates 4 channels of low-dropout voltage regulators (LDOs). Each channel's voltage is programmable. In our hardware reference designs, some of these LDO outputs are typically used to power the internal Flash and PSRAM, while the remaining LDOs can be used to supply external devices.

Note

It's essential to read the manual first and ensure that the required current does not exceed the chip's specifications.

## Functional Overview

The description of the LDO driver is divided into the following sections:

- LDO Channel Acquisition - Introduces the types of LDO channels and how to apply for LDO channel resources.

- LDO Voltage Adjustment - Describes how to adjust the voltage of the LDO channel.

### LDO Channel Acquisition

LDO channels can be classified into two types: fixed voltage and adjustable voltage. For a fixed voltage channel, it allows multiple users to simultaneously use it (in software, we allow a variable to have multiple immutable references ). However, for an adjustable voltage channel, only one user is allowed to use it at a time (in software, we don't allow a variable to have multiple mutable references or coexistence of mutable and immutable references).

In the driver, the LDO channel is represented by the `esp_ldo_channel_handle_t`. You can use the `esp_ldo_acquire_channel()` function to request LDO channel resources. Upon successful acquisition, a handle for the LDO channel will be returned, which can be used for subsequent voltage adjustment operations. When applying for a channel, the `esp_ldo_channel_config_t` structure is used to specify the basic information of the LDO channel, including the channel ID, the desired output voltage, and whether the voltage can be dynamically adjusted.

- `esp_ldo_channel_config_t::chan_id` - LDO channels are uniquely identified by a label, which is used to distinguish different LDO channels. Please note that this information needs to be determined based on the circuit schematic and chip datasheet. For example, an LDO channel labeled as `LDO_VO3` corresponds to an ID of `3`.

- `esp_ldo_channel_config_t::voltage_mv` - The desired output voltage of the LDO channel, in millivolts.

- `esp_ldo_channel_config_t::ldo_extra_flags::adjustable` - Whether the LDO channel's output voltage can be dynamically adjusted. Only when it is set to true, can the `esp_ldo_channel_adjust_voltage()` function be used to dynamically adjust the output voltage.

Since multiple users are allowed to use a fixed voltage LDO channel simultaneously, the driver internally maintains a reference counter. The LDO channel will be automatically closed when the last user releases the LDO channel resources. The function to release LDO channel resources is `esp_ldo_release_channel()`. Additionally, it is important to note that the acquisition and release of LDO channels should appear in pairs during usage.

### LDO Voltage Adjustment

`esp_ldo_channel_adjust_voltage()` function is used to adjust the output voltage of an LDO channel at runtime. However, please note that this function can only be used for LDO channels with adjustable voltage. Attempting to use this function on a fixed voltage LDO channel will result in an error.

Also, it is important to keep in mind that due to hardware limitations, the LDO channel voltage may have a deviation of approximately 50-100mV. Therefore, it is not advisable to rely on the LDO channel's output voltage for precise analog control.

## Application Examples

- Use the internal LDO channel to power up the MIPI DPHY: peripherals/lcd/mipi_dsi

## API Reference

### Header File

- components/esp_hw_support/ldo/include/esp_ldo_regulator.h

- This header file can be included with:

  >     #include "esp_ldo_regulator.h"

### Functions

esp_err_t esp_ldo_acquire_channel(const esp_ldo_channel_config_t *config, esp_ldo_channel_handle_t *out_handle)

  Acquire an LDO channel with the specified configuration.

  Note

  This function can't automatically search a LDO channel for you, you must specify a LDO channel ID manually, based on your schematic.

  Note

  The same channel can be acquired multiple times in different places of the application code, however, if the LDO channel is adjustable, you can't acquire it multiple times, in case user A changes the voltage and breaks the voltage setting of user B.

  Note

  You should release the channel by `esp_ldo_release_channel` when it's no longer needed.

  Parameters:

    - config -- [in] The configuration of the LDO channel

    - out_handle -- [out] The returned LDO channel handle

  Returns:

    - ESP_OK: Acquire the LDO channel successfully

    - ESP_ERR_INVALID_ARG: Acquire the LDO channel failed due to invalid arguments

    - ESP_FAIL: Acquire the LDO channel failed due to other reasons

esp_err_t esp_ldo_release_channel(esp_ldo_channel_handle_t chan)

  Release the LDO channel.

  Parameters:

    chan -- [in] The LDO channel handle returned from `esp_ldo_acquire_channel`

  Returns:

    - ESP_OK: Release the LDO channel successfully

    - ESP_ERR_INVALID_ARG: Release the LDO channel failed due to invalid arguments

    - ESP_ERR_INVALID_STATE: Release the LDO channel failed due to invalid state, e.g., the channel handle is double released

    - ESP_FAIL: Release the LDO channel failed due to other reasons

esp_err_t esp_ldo_channel_adjust_voltage(esp_ldo_channel_handle_t chan, int voltage_mv)

  Adjust the voltage of the LDO channel.

  Parameters:

    - chan -- [in] The LDO channel handle returned from `esp_ldo_acquire_channel`

    - voltage_mv -- [in] The voltage value to be set to the LDO channel, in millivolts

  Returns:

    - ESP_OK: Adjust the voltage of the LDO channel successfully

    - ESP_ERR_INVALID_ARG: Adjust the voltage of the LDO channel failed due to invalid arguments

    - ESP_ERR_NOT_SUPPORTED: Adjust the voltage of the LDO channel failed due to the channel is not adjustable

    - ESP_FAIL: Adjust the voltage of the LDO channel failed due to other reasons

esp_err_t esp_ldo_dump(FILE *stream)

  Dump LDO channel status to the specified stream.

  Parameters:

    stream -- [in] IO stream. Can be stdout, stderr, or a file/string stream.

  Returns:

    - ESP_OK: Dump the LDO channel status successfully

    - ESP_FAIL: Dump the LDO channel status failed

### Structures

struct esp_ldo_channel_config_t

  LDO channel configurations.

  Public Members

  int chan_id

    You must set the LDO channel ID according to the datasheet, e.g., set it to 1 for LDO_VO1

  int voltage_mv

    The voltage value to be set to the LDO channel

  struct esp_ldo_channel_config_t::ldo_extra_flags flags

    Flags for the LDO channel

  struct ldo_extra_flags

    Extra flags of a LDO channel.

    Public Members

    uint32_t adjustable

      Whether the LDO channel is adjustable, and the voltage can be updated by `esp_ldo_channel_adjust_voltage`

    uint32_t owned_by_hw

      If the LDO channel is owned by hardware, then software configurations can be overridden by hardware (e.g. eFuse)

    uint32_t bypass

      Whether to bypass the regulator, i.e., the input voltage is sourced directly to the output

### Type Definitions

typedef struct ldo_regulator_channel_t *esp_ldo_channel_handle_t

  Type of LDO regulator channel handle.

Provide feedback about this document