Skip to content

docs: author detailed server architecture internals for explanations/architecture #84

Description

@coretl

Target page

explanations/architecture

A skeleton has been written covering the two TCP sockets, the config/data thread
split, and the block model at a high level. The depth items are deferred:
locking strategy, DMA pipeline, persistence state machine.

Category: author-from-scratch

What a human must do (~4–6 hours)

Expand the skeleton in explanations/architecture.md to cover the internals
that matter to contributors and extension developers:

  1. **Thread model** — which threads exist, what each does, how they communicate
    (queues, mutexes, condition variables).
  2. **Locking strategy** — what lock(s) protect shared state; any lock ordering
    rules; known contention points.
  3. **DMA pipeline** — how captured data flows from FPGA registers through the
    DMA ring buffer to the data socket.
  4. **Persistence / state machine** — how the server saves and restores block
    configuration; when config is written to hardware vs held in memory.
  5. **Extension server integration** — how extension modules register and receive
    injected values (link to reference/extension).

A diagram (ASCII or SVG) of the thread/data-flow architecture would be very
helpful.

Post as a PR against docs/explanations/architecture.md on the docs branch.

Source

docs/explanations/architecture.md — existing skeleton.
Server source code (C) is the primary reference.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions