Add opus C++ template library documentation and unit tests

[sunway513]

Summary

• Add comprehensive documentation guide for the opus single-header C++ template library (csrc/include/opus/opus.hpp)
• Covers type system, compile-time constants, containers (seq/tuple/array/vector), layout system, vectorized gmem/smem access, MFMA operations, tiled MMA, distributed tensor views (p_dim/y_dim), and utility functions
• Includes real usage examples from AITER kernels (topk, rmsnorm_quant, cache, quant)
• All function names, type names, file paths, and MFMA aliases verified against the actual source code
• 16 CPU unit tests (compile-time constexpr/static_assert): number, seq, array, tuple, vector, slice, layout, static_for, type_traits, underscore, embed, packed_types, adaptor, mfma_types, warp_size, functional
• 16 GPU unit tests (device-side kernel execution on gfx942): type conversions (fp16/bf16/fp8), math ops, DPP warp operations, GMEM buffer load/store, SMEM/LDS load/store, MFMA intrinsics (16x16x16, 32x32x8, accumulator, scaled), mfma_adaptor shapes/layouts, swap_ab, tiled MMA, FP8 pack/unpack, container folding, s_waitcnt

Test plan

• All 16 CPU tests pass (hipcc -std=c++20 -O2)
• All 16 GPU tests pass on MI300X (gfx942)
• Build and run: bash csrc/include/opus/run_test.sh
• Verify doc guide accuracy against opus source

[Copilot]

Pull request overview

Adds a comprehensive Markdown guide documenting the opus single-header C++ template library (used by AITER HIP kernels) with sections covering types, compile-time constants, containers, layouts, gmem/smem access, MFMA/tiled MMA, distributed tensor views, and utilities.

Changes:

• Introduces a new docs/opus_guide.md documentation guide for opus.
• Adds usage examples and API references for gmem/smem, MFMA, tiled MMA, and partition/layout utilities.
• Documents how Opus is used in several AITER kernels and helper utilities.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

In the Quick Reference snippet, auto s is first used for seq<2, 4, 8>{} but later reused for make_smem(...) in the same code block, which makes the snippet fail to compile as-written. Rename one of the variables or split these examples into separate scopes/snippets so readers can copy/paste reliably.

Suggested change

	auto s = seq<2, 4, 8>{}; // Compile-time integer sequence
	auto seq_vals = seq<2, 4, 8>{}; // Compile-time integer sequence

[Copilot]

In the Quick Reference snippet, val is declared earlier as fp16_t val; and then redeclared here as auto val = s.load<4>(offset);, which will not compile in a single scope. Use distinct names (e.g., val0 / smem_val) or separate the examples into different snippets/scopes.

Suggested change

	auto s = make_smem(smem);
	auto val = s.load<4>(offset);
	auto smem_view = make_smem(smem);
	auto smem_val = smem_view.load<4>(offset);

[Copilot]

The aux section references constants RT and GROUP_NT, but these identifiers are not defined in opus/opus.hpp (they appear to be defined in csrc/include/aiter_opus_plus.h under namespace aiter). Consider either removing the constant-name column, qualifying them as aiter::RT / aiter::GROUP_NT, or documenting aux purely as a numeric immediate passed to the underlying buffer intrinsic.

Suggested change

	| Value | Constant | Meaning |
	|-------|----------|---------|
	| 0 | `RT` | Default (return temporal) |
	| 3 | `GROUP_NT` | Group non-temporal — hints that data won't be reused |
	| Value | Meaning |
	|-------|---------|
	| 0 | Default (temporal) load/store behavior |
	| 3 | Group non-temporal — hints that data won't be reused |

[Copilot]

The scalar-type table implies u16_t is always available, but in opus.hpp it is only registered when __clang_major__ >= 20 (ROCm 7+). Please note this conditional availability (or avoid listing u16_t as a guaranteed type) so users on older toolchains don’t get compile errors.

Suggested change

	| `i16_t` / `u16_t` | `int16_t` / `uint16_t` | 16-bit integers |
	| `i8_t` / `u8_t` | `int8_t` / `uint8_t` | 8-bit integers |
	| `i16_t` | `int16_t` | 16-bit signed integer |
	| `u16_t`* | `uint16_t` | 16-bit unsigned integer (only when `__clang_major__ >= 20`, e.g. ROCm 7+) |
	| `i8_t` / `u8_t` | `int8_t` / `uint8_t` | 8-bit integers |
	\* `u16_t` is conditionally registered in `opus.hpp` and is only available on toolchains with `__clang_major__ >= 20` (ROCm 7+). On older ROCm/Clang versions, `u16_t` is not provided.

[carlushuang]

#2017 => refactored here :)