Address PR review comments on documentation clarity

- Enhance pin signature explanation to emphasize simulation model selection
- Clarify that signatures are generic and implementation-independent
- Improve terminology precision: "external interfaces of the IC" vs "IP blocks"
- Add clarification that SimInterface annotations describe interface types
- Remove unverified Custom Simulation Driver section from simulation-guide

Addresses review comments on PR #144

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: robtaylor

docs/architecture.rst

@@ -81,10 +81,10 @@ You write your design in Python using Amaranth HDL and ChipFlow signatures:
 
 ChipFlow signatures are decorated with ``@amaranth_annotate`` which adds JSON schema metadata:
 
-- **IOModel**: Direction, width, drive modes, trip points
-- **SimInterface**: UID for simulation models, parameters
-- **DriverModel**: C/H files, register structures
-- **Data**: Software binaries to load
+- **IOModel**: I/O configuration for external interfaces of the IC (direction, width, drive modes, trip points)
+- **SimInterface**: Interface type identification for matching simulation models (UID, parameters)
+- **DriverModel**: Software drivers for the IP block (C/H files, register structures)
+- **Data**: Software binaries to load into memory (flash images, bootloaders)
 
 This metadata is preserved through the entire flow.
 

docs/contributor-pin-signature-internals.rst

@@ -198,10 +198,12 @@ Core Module: ``chipflow_lib/platform/io/signatures.py``
 
 Concrete pin signatures (UART, GPIO, SPI, etc.) combine I/O signatures with simulation metadata.
 
+These signatures are annotations of the **type** of the external interface (UART, GPIO, SPI), allowing ChipFlow to select and typecheck suitable simulation models that match that interface type. The annotations are independent of any particular IP implementation - they describe the interface protocol, not the internal logic of peripherals.
+
 simulatable_interface() Decorator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This decorator adds simulation model metadata:
+This decorator adds simulation model metadata for interface type identification:
 
 .. code-block:: python
 

docs/simulation-guide.rst

@@ -422,39 +422,6 @@ To add a custom peripheral model:
        [chipflow.steps]
        sim = "my_design.steps.sim:MySimStep"
 
-Custom Simulation Driver
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For full control, create a custom ``main.cc``:
-
-.. code-block:: cpp
-
-    #include "sim_soc.h"
-    #include <iostream>
-
-    int main() {
-        p_sim__top top;
-
-        // Custom initialization
-        top.p_clk.set(false);
-        top.p_rst.set(true);
-
-        // Custom stimulus
-        for (int i = 0; i < 100; i++) {
-            top.p_clk.set(!top.p_clk.curr);
-            if (i == 10)
-                top.p_rst.set(false);
-
-            // Read outputs
-            if (top.p_uart__0____tx____o.curr)
-                std::cout << "UART TX high at cycle " << i << std::endl;
-        }
-
-        return 0;
-    }
-
-Place this in ``design/sim/main.cc`` and modify your SimStep to use it instead of the generated version.
-
 Performance Tips
 ----------------
 

docs/using-pin-signatures.rst

@@ -50,9 +50,12 @@ Pin signatures are used when defining your top-level component's interface:
 These signatures tell ChipFlow:
 
 - How to connect your design to the physical pins of your chip
-- How to select appropriate simulation models and test benches for each interface
+- How to select appropriate simulation models for each external interface type
+- How to simulate signals and test the interface in a virtual environment
 - Requirements for pad and package pin allocation (power domains, drive strength, etc.)
 
+Pin signatures are generic and independent of any particular IP implementation, allowing ChipFlow to match the interface type (UART, GPIO, SPI) to appropriate simulation models and test infrastructure.
+
 IO Model Options
 ~~~~~~~~~~~~~~~~