cdx_memory.h Source

  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//=============================================================================