wip: doc

Author: AkiyukiOkayasu

ADAT_SPEC.md

@@ -0,0 +1,111 @@
+# ADAT基本仕様メモ
+
+このドキュメントは、ADAT（Alesis Digital Audio Tape optical interface）の受信実装で必要になる基礎仕様を、実装寄りに整理したものです。
+
+## 1. ADATの基本
+
+- 物理層はTOSLINK光（本IPへの入力は光電変換後のデジタル信号 `i_adat`）
+- 1フレームあたり8スロット（8ch相当）を送る
+- 各スロットは24bitオーディオ語を運ぶ
+- ライン符号化はNRZI
+
+## 2. フレーム構造（通常ADAT）
+
+この実装では1フレームを **256bit** として扱います。
+
+- SYNC部: 11bit（`0000000000 + separator(1)`）
+- User部: 5bit（`U3..U0 + separator(1)`）
+- Audio部: 8ch × 30bit = 240bit
+
+合計: `11 + 5 + 240 = 256bit`
+
+### 2.1 5bitニブル構造
+
+オーディオデータは5bitニブルで送られます。
+
+- 1ニブル = `[4bit data][1bit separator=1]`
+- 24bit語は6ニブルで表現（`24 / 4 = 6`）
+- 1chあたり `6 × 5 = 30bit`
+
+### 2.2 ビット順序
+
+本プロジェクトでの定義:
+
+- シリアル伝送順: フレーム先頭から `build_frame[255] -> build_frame[0]`
+- nibble内のdata部: MSB-first（例: `D23..D20`）
+- PCMの有意性: `o_channels[x][23]` がMSB、`o_channels[x][0]` がLSB
+
+つまり、`D23..D20, D19..D16, ..., D3..D0` がそのまま `23:20, 19:16, ..., 3:0` に対応します。
+
+### 2.3 separator bitの意味
+
+各5bitニブル末尾の `separator=1` は、NRZI上で定期的に遷移を作る役割があります。
+
+- 連続無遷移区間が長くなりすぎるのを抑える
+- 受信側のタイミング復元・同期維持を助ける
+
+## 3. フレーム周期とサンプルレート
+
+ADATの「フレーム周期」はベースレート（44.1k/48k系）で進みます。
+
+- 48k系: フレーム周期は約 `20.83us`（= `1 / 48,000`）
+- 44.1k系: フレーム周期は約 `22.68us`（= `1 / 44,100`）
+
+このIPの `o_frame_clk` はフレーム周期クロックです。
+
+- 通常モード: `o_frame_clk` と実サンプルレートは一致
+- S/MUX有効時: 実サンプルレートは `o_frame_clk` の2倍または4倍
+
+## 4. User bits
+
+フレーム先頭付近に4bitのUser nibble（`U3..U0`）があります。
+
+本IPではこのうち User Bit 2（実装上は `i_user_bits[1]`）をS/MUX有効判定に使います。
+
+- `0`: S/MUX無効
+- `1`: S/MUX有効
+
+<a id="smux"></a>
+## 5. S/MUX（Sample Multiplexing）
+
+高サンプルレートをADATフレームに載せるために、1つの論理チャンネルを複数の物理スロットに分割して運ぶ方式です。
+
+<a id="smux-modes"></a>
+### 5.1 モード対応
+
+- 通常ADAT（S/MUX無効）: 48k/44.1k, 8ch
+- S/MUX2: 96k/88.2k, 4ch
+- S/MUX4: 192k/176.4k, 2ch
+
+<a id="smux-channel-mapping"></a>
+### 5.2 物理スロットと論理チャンネルの関係
+
+本IPの `o_channels[8]` は常に「ADATの物理スロット順」で出力されます（`[0] -> [1] -> ... -> [7]`）。
+
+論理チャンネル再構成は利用側で実装します。
+
+- S/MUX2
+  - Logical CH0 <= `o_channels[0] + o_channels[1]`
+  - Logical CH1 <= `o_channels[2] + o_channels[3]`
+  - Logical CH2 <= `o_channels[4] + o_channels[5]`
+  - Logical CH3 <= `o_channels[6] + o_channels[7]`
+- S/MUX4
+  - Logical CH0 <= `o_channels[0] + o_channels[1] + o_channels[2] + o_channels[3]`
+  - Logical CH1 <= `o_channels[4] + o_channels[5] + o_channels[6] + o_channels[7]`
+
+時間順は、各Logical CH内で添字の小さいスロットが先のサンプルです。
+
+<a id="smux-limitations"></a>
+## 6. 重要な制約（実装時の注意）
+
+- User bitsだけで分かるのは「S/MUX有効/無効」まで
+- **S/MUX2 と S/MUX4 はUser bitsのみでは判別不能**
+- 判別には外部WordClock、上位設定、または別系統のメタ情報が必要
+- 本IPはS/MUX時の論理チャンネル再配置を行わない
+
+## 7. 本リポジトリ実装との対応
+
+- フレーム/ビット構造: `src/adat_rx.veryl`
+- S/MUX有効検出（User Bit 2）: `src/output_interface.veryl`
+- 同期/フレーム時間追跡: `src/timing_tracker.veryl`
+- 5bitニブルから24bit復元: `src/bit_decoder.veryl`, `src/frame_parser.veryl`

README.md

@@ -2,68 +2,49 @@
 
 [![Docs](https://img.shields.io/badge/Docs-GitHub%20Pages-2ea44f?logo=github)](https://akiyukiokayasu.github.io/adat_rx/)
 
-ADAT信号を受信し、PCM信号を出力するRTL。クロックはADAT信号から作る。  
-Verylによる実装。  
+ADAT光入力をデコードして、24bit PCMを出力するVeryl RTL。  
+クロックは入力ADATから復元します（外部PLL不要）。
 
-## プロジェクト状況
+## できること
 
-### 現在のステータス
+- ADAT受信と8ch 24bit PCMデコード
+- 44.1kHz / 48kHz 系での動作
+- 96kHz / 88.2kHz 入力（S/MUX有効）の受信テスト済み
+- UserBitに基づくS/MUX有効検出（`o_smux_active`）
 
-- ✅ PCMデータの受信・デコード完了
-- ✅ S/MUX有効検出: UserBitによるS/MUX有効/無効の自動検出
-- ✅ 厳密比較テストパス（`veryl test`）: ビットパーフェクトな伝送可能
-- ✅ 44.1kHz, 48kHz, 88.2kHz, 96kHzでテスト
+## 導入前に知るべきこと
 
-## ADAT基本仕様
+- `o_frame_clk` はADATフレーム周期であり、再生サンプルレートそのものではありません。  
+  例: 通常モードでは `o_frame_clk` と実サンプルレートは一致しますが、S/MUX有効時は一致しません。
+- S/MUXの基本、モード（S/MUX2/S/MUX4）、制約は [`ADAT_SPEC.md` の「5. S/MUX」](ADAT_SPEC.md#smux) を参照
+- `S/MUX2`/`S/MUX4` のモード対応は [`ADAT_SPEC.md` の「5.1 モード対応」](ADAT_SPEC.md#smux-modes) を参照
+- S/MUX時の論理チャンネル割り当ては [`ADAT_SPEC.md` の「5.2 物理スロットと論理チャンネルの関係」](ADAT_SPEC.md#smux-channel-mapping) を参照
+- S/MUX判別の制約（UserBitのみではS/MUX2/4を判別不可）は [`ADAT_SPEC.md` の「6. 重要な制約」](ADAT_SPEC.md#smux-limitations) を参照
 
-48kHzか44.1kHzが基本サンプルレートであり、8ch伝送できる。
+## I/O要点
 
-### フレーム仕様
+- 入力: `i_clk`（推奨50MHz）, `i_rst`, `i_adat`
+- 出力: `o_channels[8]`, `o_valid`, `o_locked`, `o_frame_clk`, `o_smux_active`
 
-1フレームは256bitで構成される。  
-[ADATフレーム構造の詳細](https://akiyukiokayasu.github.io/adat_rx/adat_rx.html#%E3%82%B7%E3%83%AA%E3%82%A2%E3%83%AB%E4%BC%9D%E9%80%81%E9%A0%86%E3%81%A8%E3%83%93%E3%83%83%E3%83%88%E6%9C%89%E6%84%8F%E6%80%A7%E3%81%AE%E5%AE%9A%E7%BE%A9)
+## 開発者向け（任意）
 
-### エンコード
+Verylには組み込みテスト実行機能があり、RTL変更時の回帰確認に使えます。
 
-4B5B→NRZI
-
-### S/MUX
-
-チャンネル数を減らす代わりに基本サンプルレートより高い周波数を使うことができる。  
-
-- S/MUX2: 96kHz or 88.2kHz, 4ch
-- S/MUX4: 192kHz or 176.4kHz, 2ch
-
-UserBitで判定できるのはS/MUXが有効かどうかまでで、S/MUX2かS/MUX4かの自動判別は原理的に不可能。  
-外部から供給されたwordclockを用いて判別するか、エンドユーザーが明示的に切り替えるしかない。  
-
-### ADAT物理ビットレート
-
-- 48kHz系: 12.288Mbps
-- 44.1kHz系: 11.2896Mbps
-
-S/MUX2もしくはS/MUX4になっても物理ビットレートは変わらないことに注意。  
-S/MUX2では1フレームあたり2サンプル分が格納される。  
-
-## クロック仕様
-
-- システムクロック: 50MHz推奨
-- 1bitあたりのクロック:
-  - 48kHz時: 約4.07クロック (50MHz / 12.288MHz)
-  - 44.1kHz時: 約4.43クロック (50MHz / 11.2896MHz)
-- 1フレーム: 256bit
-
-## Test
+### テスト実行
 
 ```sh
 veryl test
 ```
 
-### 波形出力付き
-
-FSTファイルで出力  
+### 波形確認
 
 ```sh
 veryl test --wave
 surfer src/tb_adat_rx.fst
 ```
+
+## ドキュメント
+
+- API/設計ドキュメント: <https://akiyukiokayasu.github.io/adat_rx/>
+- ADAT基本仕様メモ（本リポジトリ）: [`ADAT_SPEC.md`](ADAT_SPEC.md)
+- ADATフレーム構造の詳細: <https://akiyukiokayasu.github.io/adat_rx/adat_rx.html#%E3%82%B7%E3%83%AA%E3%82%A2%E3%83%AB%E4%BC%9D%E9%80%81%E9%A0%86%E3%81%A8%E3%83%93%E3%83%83%E3%83%88%E6%9C%89%E6%84%8F%E6%80%A7%E3%81%AE%E5%AE%9A%E7%BE%A9>