RTC memory on ESP32 with Moddable HostBuffer

RtcMemory.c

/*
 * Copyright (c) 2022 Chris Midgley
 *
 *   This work is licensed under the
 *       Creative Commons Attribution 4.0 International License.
 *   To view a copy of this license, visit
 *       <http://creativecommons.org/licenses/by/4.0>.
 *   or send a letter to Creative Commons, PO Box 1866,
 *   Mountain View, CA 94042, USA.
 */
 
#include <stdbool.h>
#include <string.h>
#include "xsmc.h"
#include "mc.xs.h"
#include "esp_sleep.h"

#define MEMORY_TYPE_ARG 0       // argument index for memoryType argument on the map method

// define the physical size of fast and slow memory
#define FAST_MEMORY_SIZE (8 * 1024)
#define SLOW_MEMORY_SIZE (8 * 1024)

// define space that we don't consume to allow for other modules to use this memory space
// (note that ESP-IDF pre-consumes 0x10 on both memory spaces)
#define FAST_MEMORY_UNALLOCATED_SIZE 0x40  // use nearly all available fast memory
#define SLOW_MEMORY_UNALLOCATED_SIZE 0x200 // slow memory also holds ULP program space

// define the size of allocations we make in fast and slow memory
#define FAST_MEMORY_ALLOCATED_SIZE (FAST_MEMORY_SIZE - FAST_MEMORY_UNALLOCATED_SIZE)
#define SLOW_MEMORY_ALLOCATED_SIZE (SLOW_MEMORY_SIZE - SLOW_MEMORY_UNALLOCATED_SIZE)

// allocate storage in fast and slow memory
RTC_FAST_ATTR static uint8_t fastMemory[FAST_MEMORY_ALLOCATED_SIZE];
RTC_SLOW_ATTR static uint8_t slowMemory[SLOW_MEMORY_ALLOCATED_SIZE];

/**
 * Gets a HostBuffer mapped on the ESP32 RTC Fast Memory.  There are two types of memory on the ESP32 that can retain
 * values across deep sleep operations, each are 8KB in size:
 *
 * - fast: This memory is accessible only from the "fast" main processor, and only core 0 ("PRO")
 * - slow: This memory is accessible fro the "slow" ULP co-processor, and and from either core
 *
 * Unless you are running on a single-core ESP32, or have changed `main.c` to use pin to core 0 (for the main task), you
 * should not use `fast` memory.  `slow` is safe on any core.
 *
 * @param memoryType - The region of memory to access, fast (CPU core 0 only) or slow (either core and ULP access)
 * @returns HostBuffer with the data region mapped directly into the buffer space, with a size of 8KB.
 */
void xs_rtcmemory_map(xsMachine *the)
{
    uint8_t *rtcMemory;
    uint16_t rtcMemorySize;

    // get the string parameter, telling us which named memory to get
    xsStringValue memoryType = xsmcToString(xsArg(MEMORY_TYPE_ARG));
    if (strcmp(memoryType, "slow") == 0) {
        rtcMemory = slowMemory;
        rtcMemorySize = FAST_MEMORY_ALLOCATED_SIZE;
    } else if (strcmp(memoryType, "fast") == 0) {
        rtcMemory = fastMemory;
        rtcMemorySize = SLOW_MEMORY_ALLOCATED_SIZE;
    } else
        xsTypeError("Type not slow|fast");

    // define the return value as a HostBuffer containing the RTC memory
    xsResult = xsNewHostObject(NULL);
    xsmcSetHostBuffer(xsResult, rtcMemory, rtcMemorySize);
    
    // set property 'byteLength'
    xsSlot byteLength;
    xsmcSetInteger(byteLength, rtcMemorySize);
    xsmcDefine(xsResult, xsID_byteLength, byteLength, xsDontDelete | xsDontSet);
}

RtcMemory.d.ts

/*
 * Copyright (c) 2022 Chris Midgley
 *
 *   This work is licensed under the
 *       Creative Commons Attribution 4.0 International License.
 *   To view a copy of this license, visit
 *       <http://creativecommons.org/licenses/by/4.0>.
 *   or send a letter to Creative Commons, PO Box 1866,
 *   Mountain View, CA 94042, USA.
 */
 
import { RtcMemoryBase, RtcMemoryType } from "../RtcMemoryBase";

/**
 * Provides access to the ESP32 RTC memory, which are two small segments of RAM that retain values during deep sleep.
 */
export class RtcMemory implements RtcMemoryBase {
	/**
	 * Gets a HostBuffer mapped on the ESP32 RTC Fast Memory.  There are two types of memory on the ESP32 that can
	 * retain values across deep sleep operations, each are 8KB in size:
	 *
	 * - fast: This memory is accessible only from the "fast" main processor, and only core 0 ("PRO")
	 * - slow: This memory is accessible fro the "slow" ULP co-processor, and and from either core
	 *
	 * Unless you are running on a single-core ESP32, or have changed `main.c` to use pin to core 0 (for the main task),
	 * you should not use `fast` memory.  `slow` is safe on any core.
	 *
	 * @param memoryType - The region of memory to access, fast (CPU core 0 only) or slow (core 0 and ULP access)
	 * @returns HostBuffer with the data region mapped directly into the buffer space, with a size of 8KB.
	 */
	map(_memoryType: RtcMemoryType): HostBuffer;
}

RtcMemory.js

/*
 * Copyright (c) 2022 Chris Midgley
 *
 *   This work is licensed under the
 *       Creative Commons Attribution 4.0 International License.
 *   To view a copy of this license, visit
 *       <http://creativecommons.org/licenses/by/4.0>.
 *   or send a letter to Creative Commons, PO Box 1866,
 *   Mountain View, CA 94042, USA.
 */

/**
 * Mapping to the C implementation for the ESP32 RtcMemory class.
 */

export class RtcMemory {
	map(_memoryType) @ "xs_rtcmemory_map";
}