1//=============================================================================
2//! @file
3//! @author GEMS
4//! @date 7 October 2026
5//! @brief Bounded access to explicitly registered model-owned memory.
6//=============================================================================
7// (c) Copyright 2026 General Engine Management Systems (GEMS) Ltd
8//=============================================================================
9
10#ifndef CDX_MEMORY_H_INCLUDED
11#define CDX_MEMORY_H_INCLUDED
12//=============================================================================
13
14//=============================================================================
15// Includes
16//=============================================================================
17
18#if defined(CDX_USER_HEADER) && !defined(CDX_USER_H_INCLUDED)
19#include CDX_USER_HEADER
20#endif
21
22#include "cdx_status.h"
23
24#ifdef __cplusplus
25extern "C" {
26#endif
27
28//! @defgroup CDX_MEMORY CDX Model Memory Access
29//! @brief Foreground-only access to at most eight registered model regions.
30//! @details Register only model-owned storage, not peripherals or IPC buffers.
31//! The caller is responsible for pointer validity and storage lifetime.
32//! Registration is reset when the runtime is bound, not by model stepping.
33//! @{
34//=============================================================================
35// Prototypes
36//=============================================================================
37
38//-----------------------------------------------------------------------------
39//! @brief Register a non-overlapping model memory region during initialization.
40//! @param address Logical 32-bit base address exposed through this API.
41//! @param data Backing storage; must remain valid until runtime rebinding.
42//! @param size Region length in bytes; must be nonzero and not overflow address.
43//! @param writable Nonzero permits writes; zero makes the region read-only.
44//! @retval CDX_STATUS_OK Region registered.
45//! @retval CDX_STATUS_BAD_PARAM Null storage, zero size, overlap or address overflow.
46//! @retval CDX_STATUS_QUEUE_FULL All eight registration slots are in use.
47CDX_STATUS CDX_memory_region_register(uint32_t address, void* data, uint32_t size, int writable);
48
49//-----------------------------------------------------------------------------
50//! @brief Copy bytes from one registered region to caller-owned storage.
51//! @param address Logical starting address of the bytes to read.
52//! @param extension Address extension; only zero is supported.
53//! @param size Byte count; the entire range must fit in a single region.
54//! @param data Nonnull destination with room for size bytes; overlap is permitted.
55//! @retval CDX_STATUS_OK Bytes copied.
56//! @retval CDX_STATUS_BAD_PARAM Unsupported extension, null data or invalid range.
57CDX_STATUS CDX_memory_read(uint32_t address, uint8_t extension, uint32_t size, void* data);
58
59//-----------------------------------------------------------------------------
60//! @brief Copy bytes into one registered, writable model region.
61//! @param address Logical starting address of the bytes to write.
62//! @param extension Address extension; only zero is supported.
63//! @param size Byte count; the entire range must fit in a single region.
64//! @param data Nonnull source containing size bytes; overlap is permitted.
65//! @retval CDX_STATUS_OK Bytes copied.
66//! @retval CDX_STATUS_BAD_PARAM Invalid extension, source, range or write permission.
67CDX_STATUS CDX_memory_write(uint32_t address, uint8_t extension, uint32_t size, void const* data);
68
69//-----------------------------------------------------------------------------
70//! @brief Read an 8-bit scalar through address extension zero.
71//! @param address Logical address in a registered region; no alignment required.
72//! @return Native-endian value, or zero on failure; use CDX_memory_read for status.
73uint8_t CDX_memory_read_u8(uint32_t address);
74
75//-----------------------------------------------------------------------------
76//! @brief Read a 16-bit scalar through address extension zero.
77//! @param address Logical address in a registered region; no alignment required.
78//! @return Native-endian value, or zero on failure; use CDX_memory_read for status.
79uint16_t CDX_memory_read_u16(uint32_t address);
80
81//-----------------------------------------------------------------------------
82//! @brief Read a 32-bit scalar through address extension zero.
83//! @param address Logical address in a registered region; no alignment required.
84//! @return Native-endian value, or zero on failure; use CDX_memory_read for status.
85uint32_t CDX_memory_read_u32(uint32_t address);
86
87//-----------------------------------------------------------------------------
88//! @brief Read a 64-bit scalar through address extension zero.
89//! @param address Logical address in a registered region; no alignment required.
90//! @return Native-endian value, or zero on failure; use CDX_memory_read for status.
91uint64_t CDX_memory_read_u64(uint32_t address);
92
93//-----------------------------------------------------------------------------
94//! @brief Write an 8-bit scalar through address extension zero.
95//! @param address Logical address in a registered writable region.
96//! @param value Native-endian value to store; no alignment is required.
97//! @return CDX_STATUS_OK on success, CDX_STATUS_BAD_PARAM on invalid range/permission.
98CDX_STATUS CDX_memory_write_u8(uint32_t address, uint8_t value);
99
100//-----------------------------------------------------------------------------
101//! @brief Write a 16-bit scalar through address extension zero.
102//! @param address Logical address in a registered writable region.
103//! @param value Native-endian value to store; no alignment is required.
104//! @return CDX_STATUS_OK on success, CDX_STATUS_BAD_PARAM on invalid range/permission.
105CDX_STATUS CDX_memory_write_u16(uint32_t address, uint16_t value);
106
107//-----------------------------------------------------------------------------
108//! @brief Write a 32-bit scalar through address extension zero.
109//! @param address Logical address in a registered writable region.
110//! @param value Native-endian value to store; no alignment is required.
111//! @return CDX_STATUS_OK on success, CDX_STATUS_BAD_PARAM on invalid range/permission.
112CDX_STATUS CDX_memory_write_u32(uint32_t address, uint32_t value);
113
114//-----------------------------------------------------------------------------
115//! @brief Write a 64-bit scalar through address extension zero.
116//! @param address Logical address in a registered writable region.
117//! @param value Native-endian value to store; no alignment is required.
118//! @return CDX_STATUS_OK on success, CDX_STATUS_BAD_PARAM on invalid range/permission.
119CDX_STATUS CDX_memory_write_u64(uint32_t address, uint64_t value);
120
121//! @}
122#ifdef __cplusplus
123} // extern "C"
124#endif
125
126//=============================================================================
127#endif // CDX_MEMORY_H_INCLUDED
128//=============================================================================
129// End of File
130//=============================================================================