# krypteia-memory — TLSF allocator for the krypteia workspace

[![Crates.io](https://img.shields.io/crates/v/krypteia-memory.svg)](https://crates.io/crates/krypteia-memory)
[![Docs.rs](https://docs.rs/krypteia-memory/badge.svg)](https://docs.rs/krypteia-memory)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)

Memory allocator for the [krypteia](https://codeberg.org/cslashm/krypteia)
cryptographic workspace, configurable between two backends:

- **`os-alloc`** (default) — forward `alloc` / `dealloc` to the
  platform `malloc` / `free`. Initialisation is a no-op. Suitable
  for hosted targets (Linux, macOS, Windows) where the C runtime
  is already there.
- **`self-alloc`** — a [TLSF](https://www.gii.upv.es/tlsf/)
  (Two-Level Segregated Fit) allocator running over a caller-
  provided RAM block. Single-init, no `std`, no `OsRng`,
  predictable O(1) `alloc` / `dealloc`. Suitable for bare-metal
  targets (STM32 M0 / M4 / M33, ESP32-C3 RISC-V) where no OS
  heap exists and crypto allocations need to come from a known,
  bounded region.

## Cargo features

| Feature        | Default | Effect                                                          |
|----------------|:-------:|-----------------------------------------------------------------|
| `os-alloc`     |   yes   | Use the platform malloc/free. Init is a no-op.                  |
| `self-alloc`   |   no    | TLSF allocator over a caller-provided RAM block (`no_std`).     |
| `global-alloc` |   no    | Implies `self-alloc` and registers as `#[global_allocator]` for FFI consumers (`arcana_ffi`, `quantica_ffi`). |

Enable **exactly one** allocator backend per build. `os-alloc`
is the default; `self-alloc` and `global-alloc` are mutually
exclusive with it.

## 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 ...
}
```

## License

Apache-2.0