Skip to content

IP_LIBRARY.md

Latest commit

 

History

History
71 lines (55 loc) · 3.15 KB

IP_LIBRARY.md

File metadata and controls

71 lines (55 loc) · 3.15 KB
Raw

ACE-2 Open IP Library

中文 | Machine-readable catalog

The Open IP Library packages the existing, verified ACE-2 Qwen2.5-0.5B W4A8 RTL into discoverable reuse units. It references the canonical files in rtl/; it does not fork or copy the certified implementations.

Catalog

Package Reuse boundary Public proof
w4a8_projection Standalone projection core; shell schedules matrix roles Q-projection shell mode
rmsnorm Standalone streaming core Isolated RTL testbench
rope Standalone core Paired Q/K shell mode
kv_cache Shared shell write path, not an isolated cache core KV-write shell mode
attention Standalone score/compose cores plus shell integration Score and value modes
softmax Standalone bounded-context core Softmax shell mode
silu_swiglu Standalone activation/gating core SiLU shell mode
mlp Integration bundle, not one standalone core Gate/up/SiLU/down/residual modes
qwen25_transformer_layer Shell integration bundle, not one drop-in layer Selected residual/norm integration modes

The 18 existing operator demos establish support across the ACE-2 data path, but several names share a core or shell proof. Package manifests therefore label each item as a standalone core, a shared shell path, or an integration bundle.

Discover and run

make ip-list
make ip-validate
make ip-demo IP=rmsnorm
make ip-softmax                 # shortcut
make ip-demo-all                # includes the slow MLP-up proof

Results are written to build/ip_library/<package>/result.json. A package is reported PASS only when every mapped run_single_operator_demo.py proof returns successfully and its required RTL marker is present.

Integration example

Consume canonical sources directly. For a projection-core integration:

ace2_w4a8_proj_core #(
    .K_SIZE(896), .MAC_LANES(4), .ACT_WIDTH(8),
    .WGT_WIDTH(4), .ACC_WIDTH(32)
) u_q_projection (/* connect the documented ready/valid ports */);

Compile from the repository root with rtl/ace2_w4a8_proj_core.sv; do not copy the source into an ip/ package. Matrix traversal, memory addressing, weight and scale delivery, and Q/K/V/O/MLP role scheduling remain integration responsibilities implemented by ace2_shell.

Scope and non-claims

This library is compatible with the demonstrated Qwen2.5-0.5B W4A8 fixed-point path (hidden size 896, intermediate size 4864, head dimension 64). It does not claim arbitrary Transformer support, a stable full-model inference API, arbitrary-text chat completion, model weights, or FPGA deployment.

Contributing

Public contributions are welcome for portable wrappers, independent oracles, redistribution-safe vectors, documentation, and integrations that preserve the evidence boundary. Add a package only when its canonical sources, interfaces, dependencies, proof mapping, limitations, and Apache-2.0 inheritance are explicit. See CONTRIBUTING.md.