Imported WavFile, WavFileDisk and WavFileSimple. Dropped MemBuffer. Added examples.

CLAUDE.md

@@ -26,7 +26,15 @@ ctest --output-on-failure
 cpack -G DEB
 ```
 
-Alternatively, `libsmart_tools/run` provides a Docker-based build environment.
+When `cmake` is not installed locally, use `libsmart_tools/run` to build inside a Docker container. It wraps any command with the correct build environment:
+
+```bash
+# Build inside Docker
+libsmart_tools/run bash -c "cd build && cmake .. && cmake --build . -j4"
+
+# Build with tests inside Docker
+libsmart_tools/run bash -c "cd build && cmake -DBUILD_TESTS=ON .. && cmake --build . -j4 && ctest --output-on-failure"
+```
 
 ## Architecture
 
@@ -49,7 +57,17 @@ Alternatively, `libsmart_tools/run` provides a Docker-based build environment.
 - `smart::ends_with` - Suffix check (requires suffix strictly shorter than string)
 - `smart::Path::combine` - Path joining (always adds separator, doesn't normalize)
 
+### WAV File Components
+
+- **WavFile** (`smart/WavFile.h`) - Base WAV file writer producing standard RIFF/WAVE with `fmt` and `data` chunks. Supports `fillBuffer` (in-memory) and `writeFile` (to disk).
+- **WavFileDisk** (`smart/WavFileDisk.h`) - Streaming WAV writer for incremental sample output to disk.
+- **WavFileSimple** (`smart/WavFileSimple.h`) - Extended WAV writer supporting cue points and LIST/adtl metadata (labels, notes, files).
+- **wav_verify** (`tests/wav_verify.h`) - Header-only WAV structure validator. `wav_verify()` checks an in-memory buffer; `wav_verify_file()` reads from disk. Reports issues (errors/warnings/info) and parses fmt, data, cue, and LIST/adtl chunks.
+
+WAV format reference documentation is in `doc/` — see `doc/CLAUDE.md` for a guide to each document.
+
 ### Build Outputs
 
 - `libsmart.so` - Shared library
 - `uio` - CLI tool for UIO device interaction (links against libcrack2)
+- `wav-verify` - CLI tool for WAV file structure verification

CMakeLists.txt

@@ -45,10 +45,11 @@ set(CPACK_DEBIAN_TOOLS_DESCRIPTION¶ "Tools and sample programs based on libsmar
 find_package(PkgConfig)
 find_package(Threads)
 
+include(FetchContent)
+
 # Testing
 option(BUILD_TESTS "Build unit tests" OFF)
 if(BUILD_TESTS)
-    include(FetchContent)
     FetchContent_Declare(
         Catch2
         GIT_REPOSITORY https://github.com/catchorg/Catch2.git
@@ -102,16 +103,11 @@ INSTALL(
     COMPONENT smartdev
 )
 
-# uio
-file(GLOB uio_sources src_uio/*.cpp)
-add_executable(uio ${uio_sources} )
-target_compile_features(uio PUBLIC cxx_std_20)  # C++ 20 adds coroutines.
-if(CMAKE_COMPILER_IS_GNUCXX AND CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 10 AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 11)
-  target_compile_options(uio PUBLIC "-fcoroutines")
-endif()
-target_link_libraries(uio smart crack crypt m)
-target_compile_options(uio PUBLIC -I${CMAKE_CURRENT_SOURCE_DIR})
-install(TARGETS uio RUNTIME DESTINATION bin COMPONENT tools)
+# Apps
+add_subdirectory(apps)
+
+# Examples
+add_subdirectory(examples)
 
 # Debian packages
 include(CPack) # this must come after all install statements.

README.md

@@ -11,6 +11,12 @@ C++ routines for:
 
 This is in use in customer project firmware, both Petalinux and Debian.
 
+# Examples
+
+The `examples/` directory contains sample programs:
+
+* **uart_terminal** — Simple serial terminal for a 16550-compatible UART exposed via UIO. Multiplexes keyboard input and UART RX interrupts using `poll()`.
+* **gpio_blink** — Blinks the lowest bit of a Xilinx AXI GPIO at 1 Hz via UIO.
 
 # Building
 

apps/CMakeLists.txt

@@ -0,0 +1,2 @@
+add_subdirectory(uio)
+add_subdirectory(wav-verify)

apps/uio/CMakeLists.txt

@@ -0,0 +1,9 @@
+file(GLOB uio_sources *.cpp)
+add_executable(uio ${uio_sources})
+target_compile_features(uio PUBLIC cxx_std_20)
+if(CMAKE_COMPILER_IS_GNUCXX AND CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL 10 AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS 11)
+  target_compile_options(uio PUBLIC "-fcoroutines")
+endif()
+target_link_libraries(uio smart crack crypt m)
+target_compile_options(uio PUBLIC -I${CMAKE_SOURCE_DIR})
+install(TARGETS uio RUNTIME DESTINATION bin COMPONENT tools)

apps/wav-verify/CMakeLists.txt

@@ -0,0 +1,4 @@
+add_executable(wav-verify wav_verify_main.cpp)
+target_compile_features(wav-verify PUBLIC cxx_std_20)
+target_compile_options(wav-verify PUBLIC -I${CMAKE_SOURCE_DIR}/tests)
+install(TARGETS wav-verify RUNTIME DESTINATION bin COMPONENT tools)

apps/wav-verify/wav_verify_main.cpp

@@ -0,0 +1,20 @@
+#include <cstdio>
+#include "wav_verify.h"
+
+int main(int argc, char** argv) {
+    if (argc < 2) {
+        fprintf(stderr, "Usage: wav-verify FILE...\n");
+        return 1;
+    }
+
+    bool any_errors = false;
+    for (int i = 1; i < argc; ++i) {
+        auto r = wav_verify_file(argv[i]);
+        printf("%s: %s\n", argv[i], r.valid ? "OK" : "FAIL");
+        if (!r.valid) {
+            printf("%s", r.summary().c_str());
+            any_errors = true;
+        }
+    }
+    return any_errors ? 1 : 0;
+}

doc/CLAUDE.md

@@ -0,0 +1,13 @@
+# Introduction
+This directory holds reference documentation for file formats used by libsmart.
+
+# WAV / RIFF WAVE file format
+
+When working on WAV-related code (`smart/WavFile.h`, `smart/WavFileDisk.h`, `smart/WavFileSimple.h`, `tests/wav_verify.h`, `apps/wav-verify`), consult these references:
+
+- **WAVE_Specification.md** — Primary reference. Readable markdown covering the RIFF/WAVE structure, `fmt` chunk variants (PCM, non-PCM, extensible), `fact` chunk, `data` chunk, format codes, and full byte-layout examples. Start here for any WAV format question.
+- **riffmci.pdf** — Original Microsoft RIFF/WAVE specification v1.0 (1991). Pages 56-65 cover WAVE. Authoritative for base chunk definitions and RIFF container rules.
+- **RIFFNEW.pdf** — Microsoft Revision 3.0 update (1994). Pages 12-22 cover WAVE extensions including the `fact` chunk requirement for non-PCM formats and `cbSize` extension field.
+- **Multiple_channel_audio_data_and_WAVE_files.pdf** — Microsoft spec for `WAVE_FORMAT_EXTENSIBLE` (0xFFFE), multi-channel speaker masks, and `wValidBitsPerSample`.
+- **rfc2361.txt** — IANA registry of WAVE format codec codes (`wFormatTag` values).
+- **Pages_from_mmreg.h.pdf** - List of chunks, this document shows a huge number of (proprietary) compressed formats, most of which are now obsolete.