This is the documentation for the latest (main) development branch. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

PSRAM

Introduction

PSRAM (Pseudo-Static Random Access Memory) is a storage technology that combines the advantages of Dynamic RAM (DRAM) and Static RAM (SRAM). The W800 chip includes a PSRAM controller that supports both SPI and QSPI interfaces, allowing access to external PSRAM devices. It provides bus operations to read, write, and erase PSRAM, with a maximum read/write speed of up to 80MHz.

Function List

Initialization — Initialize the PSRAM driver.

Set Callback Function — Configure actions to be executed after data read/write completion.

IO Control — Set the PSRAM operating mode.

Get PSRAM Size — Get the total capacity of the PSRAM.

Memory Copy — Copy data from PSRAM memory to a specified address.

Function Overview

Operating Modes The built-in PSRAM of the W800 supports three operating modes, which are described as follows:

Operating Mode

Description

SPI Mode

Uses four signal pins: Chip Select (CS), Clock (CLK), Data Input (SI), and Data Output (SO) for standard serial data transmission.

QSPI Mode

QSPI adds two additional IO data lines (total four data lines: IO0, IO1, IO2, IO3) on top of traditional SPI, allowing four bits of data to be transmitted simultaneously for faster data transfer rates, suitable for high-performance data transmission needs.

Half Sleep Mode

In this mode, the device enters a low-power state and cannot read/write data stored in PSRAM, minimizing power consumption.

Transfer Speed The maximum transfer speed supported by PSRAM is 80MHz.

Capacity Configuration The capacity of PSRAM can be configured to auto, 2M, 4M, or 8M. The configuration can be set in menuconfig. Before using PSRAM, ensure that CONFIG_HEAP_USE_PSRAM is set to y in the prj.config file.

Memory Management Supports memory allocation and deallocation using the heap’s alloc and realloc functions.

Supports DMA Memory addresses for copying must be 4-byte aligned. For sizes exceeding 1K, DMA is used for copying to reduce CPU load.

PSRAM Configuration

Setting PSRAM Capacity

Before using PSRAM, set CONFIG_HEAP_USE_PSRAM to y in the project’s prj.config file. Alternatively, enable PSRAM and select the desired capacity size in the heap settings of menuconfig in the build environment. PSRAM memory can be allocated using the wm_heap_caps_alloc() function and deallocated using the wm_heap_caps_realloc() function.

Data Transfer Pin Configuration

PSRAM pins are pre-configured and currently configured in the device table.

Main Functions

Initialization

Before using PSRAM, wm_drv_psram_init() is called during wm_heap initialization. To use it, simply call wm_dt_get_device_by_name to obtain the wm_device_t device. Example:
wm_device_t *psram_dev;
psram_dev = wm_dt_get_device_by_name("psram0");
Currently, the W800 supports only one PSRAM, so the first parameter must be psram0.

Set Callback Function

After data transfer is complete, a callback function is called. To execute certain operations, use the wm_drv_psram_register_callback() function. Example:
wm_drv_psram_callback_t psram_callback_example(void){
    wm_log_info("this is psram callback func");
}

wm_device_t *psram_dev;
psram_dev = wm_dt_get_device_by_name("psram0");

wm_drv_psram_register_callback(psram_dev, psram_callback_example, NULL);
The first parameter is the PSRAM device identifier.

The second parameter is the callback function to be executed after the transfer is complete.

The third parameter is the argument to be passed to the callback function.

IO Control

When using PSRAM, configure the IO operating mode using the wm_drv_psram_ioctrl() function. This function requires four parameters: device, cmd, param, and *arg. The combinations of cmd and param correspond to the following operating modes:

cmd

param

Operating Mode

WM_DRV_PSRAM_CMD_SET_MODE

WM_DRV_PSRAM_MODE_SPI

SPI Mode

WM_DRV_PSRAM_CMD_SET_MODE

WM_DRV_PSRAM_MODE_QSPI

QSPI Mode

WM_DRV_PSRAM_CMD_ENABLE_HSM

NULL

Half Sleep Mode

WM_DRV_PSRAM_CMD_DISABLE_HSM

NULL

Standard Mode

After setting Half Sleep Mode, PSRAM will enter a low-power state and cannot perform read/write operations.

Example of IO control use:
wm_device_t *psram_dev;
psram_dev = wm_dt_get_device_by_name("psram0");

wm_drv_psram_ioctrl(psram_dev, WM_DRV_PSRAM_CMD_SET_MODE, WM_DRV_PSRAM_MODE_SPI, NULL);

Get PSRAM Size

To get the size of the PSRAM, call the wm_drv_psram_get_size() function. Example:
uint32_t size;
wm_device_t *psram_dev;
psram_dev = wm_dt_get_device_by_name("psram0");

wm_drv_psram_get_size(psram_dev, &size);
The value of size is the size configured for PSRAM at initialization.

Memory Copy

To transfer data from PSRAM, call the wm_drv_psram_memcpy_dma() function, passing the device identifier device, destination address dst, source address src, and data size size. Example:

#define PSRAM_COPY_SIZE 20
#define PSRAM_DMA_SIZE  1024

wm_device_t *psram_dev;
char *p;
const char *str = "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"
                "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"
                "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"
                "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"
                "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"
                "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"
                "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"
                "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"
                "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"
                "0123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789"
                "abcdefghijklmnopqrstuvwx";
psram_dev = wm_dt_get_device_by_name(PSRAM_DEVICE_NAME);
p = wm_heap_caps_alloc(PSRAM_DMA_SIZE, WM_HEAP_CAP_SPIRAM);

if (p) {
    wm_drv_psram_memcpy_dma(psram_dev, p, str, PSRAM_DMA_SIZE);
    wm_heap_caps_free(p);
} else {
    wm_log_error("alloc from psram fail.");
}

There are three conditions for using DMA copy:

Source and destination addresses must be 4-byte aligned.
Copy length must not be less than PSRAM_MIN_DMA_SIZE, default is 1024.
The device table is configured to use DMA with the PSRAM device. When calling the API, an idle DMA transfer channel will be requested.

Deinitialization

If you no longer need to use PSRAM for data storage, call wm_drv_psram_deinit() to delete the driver and release allocated resources.

Precautions

Note

DMA and CPU access PSRAM via SPI pins, so they cannot access PSRAM simultaneously. If the previous access is not completed, the interface will return WM_ERR_BUSY.

Application Example

For a basic example of using PSRAM, please refer to: examples/peripheral/psram

API Reference

To find PSRAM-related APIs, please refer to:

PSRAM API Reference