Add GitHub co-pilot instructions

Author: martijnbastiaan

.github/copilot-instructions.md

@@ -0,0 +1,52 @@
+<!--
+SPDX-FileCopyrightText: 2025 Google LLC
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Bittide Hardware Repository - Copilot Instructions
+
+Run in docker container. See .github/workflows/copilot-setup-steps.yml for reference. The
+container has all dependencies installed to build the project. Always run within a Nix shell:
+
+```bash
+nix develop --extra-experimental-features "nix-command flakes" --command bash -c "echo OK"
+```
+
+## Overview
+
+This repository implements a **hardware-software co-design system** for a Bittide FPGA-based architecture. Here's how everything fits together:
+
+### **1. Hardware Build Flow (Clash HDL → Verilog → FPGA)**
+
+**Hardware is written in Clash HDL** (a Haskell-based hardware description language):
+
+1. **Clash Compilation** (`bittide/`, `bittide-instances/`)
+   - Write hardware designs in Clash (Haskell)
+   - Build with: `cabal build bittide-instances`
+   - Generates **Verilog** output to `_build/clash/`
+   - Generates **memory maps** (JSON) to `_build/memory_maps/`
+
+**Firmware is written in Rust** for RISC-V processors embedded in the FPGA:
+
+**The CPU**: VexRiscv (RV32IMC) - a soft RISC-V core synthesized in the FPGA
+- Lives in `clash-vexriscv/`
+- Generated from Scala → Verilog
+- Integrated into Clash designs via **C++ FFI** for simulation
+- Interfaces: Wishbone buses for instruction/data memory and peripherals
+
+**Firmware Structure**:
+- `firmware-support/` - Hardware Abstraction Layer (HAL)
+  - `bittide-hal/` - Device drivers generated from memory maps
+  - `bittide-sys/` - System libraries (networking via smoltcp)
+  - `bittide-macros/` - Rust macros
+  - `memmap-generate/` - **Code generator** (see below)
+
+- `firmware-binaries/` - Actual programs
+  - `examples/` - Hello world, networking demos
+  - `test-cases/` - Hardware tests
+  - `clock-control/`, `management-unit/` - System firmware
+
+**Build Process**:
+```bash
+./cargo.sh build --release  # Builds for both workspaces

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,28 @@
+# SPDX-FileCopyrightText: 2025 Google LLC
+#
+# SPDX-License-Identifier: Apache-2.0
+
+name: "Copilot Setup Steps"
+
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    container:
+      image: ghcr.io/clash-lang/nixos-bittide-hardware:2025-10-06
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4