krypteia-memory 0.1.0

//! Shared memory allocator for the krypteia cryptographic workspace.
//!
//! This crate provides a single `GlobalAlloc` that both `arcana_ffi`
//! and `quantica_ffi` use when running on targets without an OS
//! heap.
//!
//! # Feature flags
//!
//! | Feature      | Behaviour                                              |
//! |-------------|--------------------------------------------------------|
//! | `os-alloc`  | The platform provides `malloc`/`free`. Init is a no-op.|
//! | `self-alloc`| TLSF allocator over a caller-provided RAM block.       |
//!
//! Enable **exactly one** of the two features. `os-alloc` is the
//! default.
//!
//! # Usage from C (bare-metal)
//!
//! ```c
//! #include "krypteia.h"
//!
//! static uint8_t heap[8192];
//!
//! int main(void) {
//!     krypteia_init(heap, sizeof(heap));
//!     // … use arcana or quantica APIs …
//! }
//! ```

#![cfg_attr(feature = "self-alloc", no_std)]

#[cfg(all(feature = "self-alloc", feature = "os-alloc"))]
compile_error!("features `os-alloc` and `self-alloc` are mutually exclusive");

// ====================================================================
// os-alloc: the platform already has malloc/free — nothing to do
// ====================================================================

#[cfg(feature = "os-alloc")]
mod os_alloc {
    /// Memory allocation statistics.
    #[derive(Clone, Copy, Debug, Default)]
    pub struct MemStats {
        /// Bytes currently allocated.
        pub used: usize,
        /// Bytes still available.
        pub free: usize,
        /// High-water mark since init.
        pub peak: usize,
    }

    /// No-op when the OS provides its own allocator.
    ///
    /// # Safety
    ///
    /// Always safe; arguments are ignored.
    pub unsafe fn krypteia_init(_base: *mut u8, _size: usize) -> i32 {
        0
    }

    /// Returns zeroed stats in `os-alloc` mode (the OS tracks its
    /// own heap; we have no visibility).
    pub fn memory_stats() -> MemStats {
        MemStats::default()
    }
}

#[cfg(feature = "os-alloc")]
pub use os_alloc::*;

// ====================================================================
// self-alloc: TLSF allocator over a caller-provided RAM block
// ====================================================================

#[cfg(feature = "self-alloc")]
mod self_alloc;

#[cfg(feature = "self-alloc")]
pub use self_alloc::*;