1/* @ajax/mesh-mailbox: host views of the mailbox words (mesh-host mailbox.rs).
2 * The GPU (and workers, and lanes) write the same memory concurrently, so
3 * every access is an atomic of the word's size: release stores publish,
4 * acquire loads observe completion.  An offset out of range or misaligned is
5 * a bug: it aborts with the offset, as the Rust's assert panics. */
6#ifndef MESH_MAILBOX_H
7#define MESH_MAILBOX_H
8
9#include "mesh/abi/words.h"
10
11#include <stdbool.h>
12#include <stddef.h>
13#include <stdint.h>
14
15/* The mailbox: host address and the device address the kernel receives. */
16typedef struct {
17    uint8_t *base;
18    uint64_t dev;
19} mesh_mailbox;
20
21/* base must point to MAILBOX_BYTES of 8-aligned memory that outlives every use. */
22static inline mesh_mailbox mesh_mailbox_new(uint8_t *base, uint64_t dev) {
23    mesh_mailbox m = {base, dev};
24    return m;
25}
26
27uint32_t mesh_mailbox_get(mesh_mailbox m, size_t off);                 /* acquire load */
28void mesh_mailbox_set(mesh_mailbox m, size_t off, uint32_t v);         /* payload store (relaxed) */
29void mesh_mailbox_publish(mesh_mailbox m, size_t off, uint32_t v);     /* release store */
30uint32_t mesh_mailbox_fetch_add(mesh_mailbox m, size_t off, uint32_t v); /* AcqRel, returns the old value */
31/* Compare-and-swap (AcqRel); returns the value seen (== cur on success). */
32uint32_t mesh_mailbox_cas(mesh_mailbox m, size_t off, uint32_t cur, uint32_t desired);
33uint64_t mesh_mailbox_fetch_add64(mesh_mailbox m, size_t off, uint64_t v);
34uint8_t mesh_mailbox_get8(mesh_mailbox m, size_t off);
35void mesh_mailbox_set8(mesh_mailbox m, size_t off, uint8_t v);
36uint64_t mesh_mailbox_get64(mesh_mailbox m, size_t off);
37void mesh_mailbox_set64(mesh_mailbox m, size_t off, uint64_t v);
38void mesh_mailbox_publish64(mesh_mailbox m, size_t off, uint64_t v);
39/* len bytes at off (word reads; off 4-aligned) into out. */
40void mesh_mailbox_read(mesh_mailbox m, size_t off, uint8_t *out, size_t len);
41/* Writes bytes at off, zero padding to span bytes (word stores). */
42void mesh_mailbox_write(mesh_mailbox m, size_t off, const uint8_t *bytes, size_t n, size_t span);
43void mesh_mailbox_zero(mesh_mailbox m, size_t off, size_t len);
44/* The pipe words over it (mesh-abi pipe): absolute mailbox offsets. */
45mesh_words mesh_mailbox_words(mesh_mailbox m);
46
47/* A heap mailbox for tests (no GPU): MAILBOX_BYTES zeroed, 8-aligned. Free its base. */
48mesh_mailbox mesh_mailbox_test(void);
49
50#endif