# Memory API

Source: https://sh4zam.com/api/memory/

> Routines for copying memory, store queues, cache operations and prefetching

This API provides special instruction intrinsics, cache operations and `memcpy()`-type routines. `shz_memcpy()` is a generic drop-in `memcpy()` replacement; when you know and control the alignment and batch sizes, you can micro-optimize by calling the most specific specialization instead. `sq_` routines write through the SH4 store queues, and `_xmtrx` routines use the XMTRX register bank as a scratch buffer, clobbering it. `memcpy()`-like routines will typically always check for proper alignment and size increments of parameters using `assert()`, so make sure to build a release build (`-DNDEBUG`) for maximal gainz when not debugging. There is no `shz_memset()` yet; it is listed as a TODO in the header.

- **C header:** `#include <sh4zam/shz_mem.h>`
- **C++ header:** `#include <sh4zam/shz_mem.hpp>`
- **Symbols:** 23

## Suffixes

Suffixes used in this module. The full list is in [Naming and Suffixes](https://sh4zam.com/concepts/naming-and-suffixes/).

- `sq_`: Writes through the SH4 store queues (burst writes to memory or the PVR).
- `_xmtrx`: Uses the XMTRX register bank as a 64-byte scratch buffer. Clobbers XMTRX.
- `memcpyN`: A numeric suffix on `memcpy`/`memset` names the element granularity or count, e.g. `shz_memcpy32_1` copies exactly one 32-byte line.

## C stdlib Replacements

Routine replacing the C standard library copy/set API.

| Symbol | Description |
| --- | --- |
| [`shz_memcpy`](https://sh4zam.com/api/memory/shz_memcpy/) | Generic drop-in fast memcpy() replacement. |
| [`shz_memmove`](https://sh4zam.com/api/memory/shz_memmove/) | Generic drop-in fast memmove() replacement. |

## Specializations

Specialized routines for specific sizes + alignments.

| Symbol | Description |
| --- | --- |
| [`shz_memcpy1`](https://sh4zam.com/api/memory/shz_memcpy1/) | Copies an unaligned buffer to another one byte at a time. |
| [`shz_memcpy2`](https://sh4zam.com/api/memory/shz_memcpy2/) | Copies from one 2-byte aligned buffer to another two bytes at a time. |
| [`shz_memcpy4`](https://sh4zam.com/api/memory/shz_memcpy4/) | Copies a from one 4-byte aligned buffer to another 4 bytes at a time. |
| [`shz_memcpy8`](https://sh4zam.com/api/memory/shz_memcpy8/) | Copies a from one 8-byte aligned buffer to another 8 bytes at a time. |
| [`shz_memset8`](https://sh4zam.com/api/memory/shz_memset8/) | Assigns the given 8-byte `value` to the `bytes` in `dst`. |
| [`shz_memcpy32`](https://sh4zam.com/api/memory/shz_memcpy32/) | Copies `bytes` from the `src` to the `dst` buffer in 32-byte chunks. |
| [`shz_sq_memcpy32`](https://sh4zam.com/api/memory/shz_sq_memcpy32/) | Copies `bytes` from `src` to `dst` in 32-byte chunks, using the Store Queues. |
| [`shz_sq_memcpy32_xmtrx`](https://sh4zam.com/api/memory/shz_sq_memcpy32_xmtrx/) | Copies `bytes` from `src` to `dst` in 32-byte chunks, using the Store Queues and XMTRX. |
| [`shz_memcpy64`](https://sh4zam.com/api/memory/shz_memcpy64/) | Specialized memcpy() variant for copying multiples of 64-bytes. |
| [`shz_memcpy128`](https://sh4zam.com/api/memory/shz_memcpy128/) | Specialized memcpy() variant for copying multiples of 128 bytes. |

## Constant-sized Operations

Specialized routines for operating on statically sized buffers.

| Symbol | Description |
| --- | --- |
| [`shz_memcpy2_8`](https://sh4zam.com/api/memory/shz_memcpy2_8/) | Copies 8 shorts from `src` to `dst`. |
| [`shz_memcpy2_16`](https://sh4zam.com/api/memory/shz_memcpy2_16/) | Copies 16 shorts from `src` to `dst`. |
| [`shz_memset2_16`](https://sh4zam.com/api/memory/shz_memset2_16/) | Sets the values of the 16 shorts pointed to by `dst` to the given `value`. |
| [`shz_memcpy4_16`](https://sh4zam.com/api/memory/shz_memcpy4_16/) | Copies 16 4-byte, long values from `src` to `dst`. |
| [`shz_memcpy32_1`](https://sh4zam.com/api/memory/shz_memcpy32_1/) | Copies 32 bytes from `p1` to `p2` as a single chunk. |
| [`shz_memswap32_1`](https://sh4zam.com/api/memory/shz_memswap32_1/) | Swaps the values within the given 32-byte buffers. |
| [`shz_memswap32_1_xmtrx`](https://sh4zam.com/api/memory/shz_memswap32_1_xmtrx/) | Swaps the values within the given 32-byte buffers, using XMTRX. |
| [`shz_sq_memcpy32_1`](https://sh4zam.com/api/memory/shz_sq_memcpy32_1/) | Copies `src` to `dst` in a single 32-byte transaction using the Store Queues. |
| [`shz_sq_memcpy32_1_xmtrx`](https://sh4zam.com/api/memory/shz_sq_memcpy32_1_xmtrx/) | Copies `src` to `dst` in a single 32-byte transaction using the Store Queues and XMTRX. |
| [`shz_dcache_alloc_line`](https://sh4zam.com/api/memory/shz_dcache_alloc_line/) | Intrinsic around the SH4 `MOVCA.L` instruction. |

## Macros

| Symbol | Description |
| --- | --- |
| [`SHZ_PREFETCH`](https://sh4zam.com/api/memory/SHZ_PREFETCH/) | Used to prepopulate the cache line mapping to the given address, before it is used. |