# quic/fastrpc architecture

> Architecture diagram of the GitHub repository quic/fastrpc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quic/fastrpc
- Repository: https://github.com/quic/fastrpc

## Overview

##### Project type and purpose
- FastRPC is a cross-processor RPC framework written in C for Qualcomm devices. It lets a CPU process call functions on a DSP by hiding all the marshalling, transport, and dispatch logic.
- It comprises stub code (for CPU), skeleton code (for DSP), plus a lightweight FastRPC framework on both sides to queue, send, receive, and dispatch RPC messages.

##### File structure
- Top level:
- .github/ – CI workflows (Linux, Android builds, CodeQL, PR checks)
- inc/ – all public and internal headers for stubs, skels, FastRPC core, utilities
- src/ – C implementations: generated stubs/skels, FastRPC core modules (async, perf, mem, notif, procbuf, log, pm), transport (dspqueue, dspsignal), platform shims, RPC memory, atomic, std libs
- test/ – unit tests and platform-specific test drivers (android, linux, v68, v75)
- Autotools files: autogen.sh, configure.ac, Makefile.am, gitcompile
- This is a monolithic C library with a clear separation between CPU side and DSP side code, generated code vs. core framework modules.

##### Main components
a. Build‐time / Toolchain layer
- IDL compiler (QAIC) → generates stub (.c/.h) and skeleton (.c/.h) code
- Autotools wrapper (gitcompile, configure, Makefiles) for native/ARM/Android cross-compilation
b. CPU side
- Application process (user mode)
- Stub library (generated code linked into the app)
- FastRPC CPU framework modules (e.g., fastrpc_async, fastrpc_mem, fastrpc_notif, fastrpc_log, fastrpc_pm)
- Underlying transport: dspqueue and dspsignal CPU drivers or platform shims
c. Interconnect / Transport
- Shared memory buffers (rpcmem) + signaling (DSP interrupts or mailbox)
- dspqueue for message queuing and notification
d. DSP side
- FastRPC DSP framework modules (counterparts to CPU modules)
- Skeleton library (generated code linked into DSP binary)
- Algorithm implementations or DSP services invoked by skeletons
e. Hardware
- CPU (ARM/AArch64) with OS user process
- DSP subsystem with its own firmware/RTOS
f. External dependencies
- Hexagon SDK (for DSP services and HVX)
- Platform libraries (mutex, atomics, pthread-rw, std utilities)

##### Relationships and interactions (work flow)
1. CPU app calls stub function
2. Stub marshals parameters → RPC message
3. Stub invokes CPU FastRPC framework → enqueues message via dspqueue
4. Transport layer sends message to DSP (shared memory + interrupt)
5. DSP FastRPC framework dequeues message → dispatches to skeleton
6. Skeleton unmarshals → calls DSP implementation
7. Skeleton marshals return value → enqueues return message via DSP framework
8. Transport layer notifies CPU framework
9. CPU FastRPC framework dequeues return message → delivers to stub
10. Stub unmarshals return data → returns to calling process

##### Architectural patterns and design principles
- Layered architecture: build/toolchain → CPU framework → transport → DSP framework → implementation
- Modular C design: each fastrpc_* module handles one concern (memory, async, perf, power management)
- Code generation (IDL → stub/skel) to keep API contracts in-sync
- Shared-memory + signaling transport abstraction (dspqueue / dspsignal) to isolate hardware details

##### Detail checklist
- Major modules (fastrpc_mem, fastrpc_notif, dspqueue, dspsignal, rpcmem, atomics, logging, perf)
- Relationship between IDL, stub, skeleton, and actual DSP function implementations
- OS or driver boundary on CPU (user vs. kernel/driver for dspqueue) if desired

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build & Toolchain"
        IDL["IDL Compiler (QAIC)"]:::gray
        Autotools["Autotools & Scripts"]:::gray
    end

    subgraph "CPU Side"
        Apps["Application Process"]:::yellow
        UserShim["User API Shim"]:::green
        Stubs["CPU Stub Library"]:::blue
        subgraph "CPU Framework Modules"
            async["fastrpc_async"]:::green
            mem["fastrpc_mem"]:::green
            notif["fastrpc_notif"]:::green
            log["fastrpc_log"]:::green
            pm["fastrpc_pm"]:::green
            perf["fastrpc_perf"]:::green
        end
        subgraph "CPU Transport Drivers"
            dspq_cpu["dspqueue_cpu"]:::orange
            dspq_rpc["dspqueue_rpc_stub"]:::orange
            dspsig["dspsignal"]:::orange
        end
    end

    rpcmemBuf(("RPC Memory")):::orange

    subgraph "DSP Side"
        subgraph "DSP Framework Modules"
            dsp_async["fastrpc_async"]:::green
            dsp_mem["fastrpc_mem"]:::green
            dsp_notif["fastrpc_notif"]:::green
        end
        Skeletons["DSP Skeleton Library"]:::blue
        subgraph "DSP Implementations"
            impl_mem["apps_mem_imp"]:::yellow
            impl_std["apps_std_imp"]:::yellow
        end
    end

    Hardware_Cpu["CPU (ARM/AArch64)"]:::gray
    Hardware_Dsp["DSP Subsystem"]:::gray

    Apps -->|1 call| UserShim
    UserShim -->|2 marshal| Stubs
    Stubs -->|3 invoke| async
    async -->|via| dspq_cpu
    dspq_cpu -->|4 send| rpcmemBuf
    rpcmemBuf -->|interrupt/mailbox| dspsig
    dspsig -->|5 notify| dsp_notif
    dsp_notif -->|5 dequeue| Skeletons
    Skeletons -->|6 unmarshall| impl_mem
    impl_mem -->|7 marshal return| dsp_async
    dsp_async -->|7 enqueue| dspq_rpc
    dspq_rpc -->|8 notify| rpcmemBuf
    rpcmemBuf -->|9 dequeue| notif
    notif -->|10 deliver| Stubs

    click UserShim "https://github.com/quic/fastrpc/blob/development/src/fastrpc_apps_user.c"
    click Stubs "https://github.com/quic/fastrpc/blob/development/src/adsp_current_process_stub.c"
    click async "https://github.com/quic/fastrpc/blob/development/src/fastrpc_async.c"
    click dspq_cpu "https://github.com/quic/fastrpc/blob/development/src/dspqueue/dspqueue_cpu.c"
    click dspsig "https://github.com/quic/fastrpc/blob/development/src/dspsignal.c"
    click rpcmemBuf "https://github.com/quic/fastrpc/blob/development/src/rpcmem_linux.c"
    click Skeletons "https://github.com/quic/fastrpc/blob/development/src/apps_mem_skel.c"
    click impl_mem "https://github.com/quic/fastrpc/blob/development/src/apps_mem_imp.c"

    classDef gray fill:#d3d3d3;
    classDef blue fill:#add8e6;
    classDef green fill:#90ee90;
    classDef orange fill:#ffa500;
    classDef yellow fill:#ffffe0;
```
