memoria_externa.h File Reference

Placement between internal and external memory, and a two-buffer index. More...

#include "mmgr.h"

Go to the source code of this file.

Data Structures
struct	PingPong
	A pair of buffers, one being filled while the other is drained. More...
struct	ExternaCfg
	Arguments for every exter call, where each call reads only the members it needs. More...
struct	MemoriaExternaNs
	Type of the exter dispatch table. More...

Enumerations
enum	mmgr_place {   PLACE_DRAM ,   PLACE_PSRAM ,   PLACE_FAIL }
	Where a request should be placed. More...

Functions
mmgr_place	mmgr_extern_place (const ExternaCfg *args)
	Decides whether a request belongs in internal or external memory.
void	mmgr_pingpong_init (const ExternaCfg *args)
	Points the pair at buffer 0.
uint8_t	mmgr_pingpong_fill_index (const ExternaCfg *args)
	Returns the index of the buffer being filled.
uint8_t	mmgr_pingpong_drain_index (const ExternaCfg *args)
	Returns the index of the buffer being drained.
uint8_t	mmgr_pingpong_swap (const ExternaCfg *args)
	Swaps which buffer is filled and which is drained.

Variables
static const MemoriaExternaNs	exter
	Dispatch table instance named exter.

Detailed Description

Placement between internal and external memory, and a two-buffer index.

Author

dstroy0 (Douglas Quigg) dquig.nosp@m.g123.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

Date

2026-08-29

Warning

Everything below is declared only when MMGR_ENABLE_EXTRAM is set.

Definition in file memoria_externa.h.

Enumeration Type Documentation

mmgr_place

enum mmgr_place

Where a request should be placed.

Note

One byte on every compiler, through EMBED_ENUM_BYTE.

Enumerator
PLACE_DRAM	Internal memory.
PLACE_PSRAM	External memory.
PLACE_FAIL	Neither will take it.

Definition at line 32 of file memoria_externa.h.

Function Documentation

mmgr_extern_place()

mmgr_place mmgr_extern_place

(

const ExternaCfg *

args

)

Decides whether a request belongs in internal or external memory.

Parameters

[in]

args

Request size, the DMA requirement and both memory figures [BORROWS].

Returns

PLACE_DRAM, PLACE_PSRAM, or PLACE_FAIL when neither will take it.

Note

A size of 0 gives PLACE_FAIL.

A DMA request only ever gives PLACE_DRAM or PLACE_FAIL, never external memory.

At or above psram_threshold external memory is preferred, below it internal is.

Warning

The two tests are not the same shape. Internal placement must also leave dram_reserve free, where the external one is a size comparison alone.

References mmgr_extern_place().

Referenced by mmgr_extern_place().

mmgr_pingpong_init()

void mmgr_pingpong_init

(

const ExternaCfg *

args

)

Points the pair at buffer 0.

Parameters

[in,out]

args

Pair to reset, as args->pingpong [BORROWS].

Note

The other three pingpong entries read a pair this call has set.

Warning

args->pingpong must not be null. Nothing checks it and no assertion covers it, and this call writes through it at once.

mmgr_pingpong_fill_index()

uint8_t mmgr_pingpong_fill_index

(

const ExternaCfg *

args

)

Returns the index of the buffer being filled.

Parameters

[in]

args

Pair to read, as args->pingpong [BORROWS].

Returns

0 or 1.

Note

Does not modify args->pingpong.

Warning

args->pingpong must not be null. Nothing checks it and no assertion covers it.

Reports fill_index as it stands. On a pair that has not been through mmgr_pingpong_init that is whatever its storage contained, and this call does not bound it to 0 or 1.

mmgr_pingpong_drain_index()

uint8_t mmgr_pingpong_drain_index

(

const ExternaCfg *

args

)

Returns the index of the buffer being drained.

Parameters

[in]

args

Pair to read, as args->pingpong [BORROWS].

Returns

The other index, 0 or 1.

Note

The answer is fill_index with its low bit flipped, and so the two indexes always disagree.

Does not modify args->pingpong.

Warning

args->pingpong must not be null. Nothing checks it and no assertion covers it.

The answer is an index only while fill_index is 0 or 1. On a pair that has not been through mmgr_pingpong_init it is the flip of whatever its storage contained.

mmgr_pingpong_swap()

uint8_t mmgr_pingpong_swap

(

const ExternaCfg *

args

)

Swaps which buffer is filled and which is drained.

Parameters

[in,out]

args

Pair to flip, as args->pingpong [BORROWS].

Returns

The index now being filled, 0 or 1.

Note

Flips the low bit. A swap of a swap is where it started.

Warning

args->pingpong must not be null. Nothing checks it and no assertion covers it.

One caller at a time. The flip and the read that follows it are two steps on a plain byte, with no atomic and no lock, and so two callers swapping the same pair can come away holding the same index.

Variable Documentation

exter

const MemoriaExternaNs exter

static

Dispatch table instance named exter.

Note

pingpong_fill calls mmgr_pingpong_fill_index and pingpong_drain calls mmgr_pingpong_drain_index.

Definition at line 149 of file memoria_externa.h.