61 lines
2.4 KiB
Markdown
61 lines
2.4 KiB
Markdown
# Mailbox / semaphore (Tier A #5)
|
||
|
||
Status: **partial** — compiler builtins for Accellera-style IPC (int messages).
|
||
|
||
## Choice: compiler builtins (not library classes)
|
||
|
||
IEEE `mailbox` / `semaphore` are built-in classes. A pure SV library cannot implement the required API here because:
|
||
|
||
- Functions cannot take `output`/`ref` ports (`try_get(v)` needs a side-effecting write).
|
||
- Class `event` properties are not supported yet (needed for efficient wait/wakeup).
|
||
|
||
This fork therefore implements **native builtins**, similar in shape to `string` / queue method sfuncs: empty `netclass_t` types named `mailbox` / `semaphore`, methods lowered to `$ivl_mailbox$*` / `$ivl_semaphore$*`, and vvp opcodes (`%mbx/*`, `%sem/*`) with real thread suspend/resume.
|
||
|
||
The older IVL_UVM “poor-man’s” classes (`ivl_uvm_mbx`, `ivl_uvm_semaphore`) remain in `uvm/` for that library’s own tests; new Accellera-shaped code should use the builtins.
|
||
|
||
## Supported in this slice
|
||
|
||
```systemverilog
|
||
mailbox #(int) mb = new(); // #(T) accepted; element type is int/vec for v1
|
||
mb.put(7);
|
||
mb.get(v); // blocking
|
||
ok = mb.try_put(8);
|
||
ok = mb.try_get(v); // nonblocking; writes v on success
|
||
n = mb.num();
|
||
|
||
semaphore sem = new(1);
|
||
sem.get(1); // blocking
|
||
sem.put(1);
|
||
ok = sem.try_get(1);
|
||
```
|
||
|
||
Also: unbounded `new()` / `new(0)`, bounded mailbox `new(N)`, blocking put when full, `peek` / `try_peek`.
|
||
|
||
## Encoding
|
||
|
||
| Layer | Role |
|
||
|-------|------|
|
||
| Parse / pform | Builtin typedefs `mailbox` / `semaphore`; `mailbox #(T) x` as var decl (T ignored for now) |
|
||
| Netlist | Empty `netclass_t` “mailbox” / “semaphore” |
|
||
| Elab | `$ivl_mailbox$new/put/get/...`, `$ivl_semaphore$new/get/put/try_get` |
|
||
| Codegen | `%mbx/*`, `%sem/*`, `%box/vec4` / `%unbox/vec4` for int payloads |
|
||
| Runtime | `vvp_mailbox` / `vvp_semaphore` (`vvp/vvp_mailbox.{h,cc}`) |
|
||
|
||
## Deferred (do not claim)
|
||
|
||
- True parameterized element types (`mailbox #(string)`, class handles) beyond boxing ints
|
||
- Explicit specialization of user param-classes interacting with mailbox
|
||
- `peek` stress / priority / typed message checking
|
||
- Replacing IVL_UVM’s `ivl_uvm_mbx` usages with the builtin
|
||
|
||
## Example
|
||
|
||
[`examples/mailbox_sem/mbx_sem_basic.sv`](../examples/mailbox_sem/mbx_sem_basic.sv) — prints `PASSED`.
|
||
|
||
```bash
|
||
./install/bin/iverilog -g2012 -o /tmp/mbx_sem.vvp examples/mailbox_sem/mbx_sem_basic.sv
|
||
./install/bin/vvp /tmp/mbx_sem.vvp
|
||
```
|
||
|
||
See also [STATUS.md](STATUS.md) and [ROADMAP.md](ROADMAP.md).
|