From cfdd0abeceb1f009bd3f54b91217b95233981d70 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jean-Fran=C3=A7ois=20Nguyen?= <jf@jfng.fr>
Date: Tue, 27 Aug 2024 14:39:10 +0200
Subject: [PATCH] docs/gpio: add documentation.

---
 amaranth_soc/gpio.py |  8 +++---
 docs/gpio.rst        | 61 +++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 61 insertions(+), 8 deletions(-)

diff --git a/amaranth_soc/gpio.py b/amaranth_soc/gpio.py
index 666724a..47c2541 100644
--- a/amaranth_soc/gpio.py
+++ b/amaranth_soc/gpio.py
@@ -128,8 +128,8 @@ class Input(csr.Register, access="r"):
         """Input register.
 
         This :class:`~.csr.reg.Register` contains an array of ``pin_count`` read-only fields. Each
-        field is 1-bit wide and is driven by the input of its associated pin in the
-        :attr:`Peripheral.pins` array.
+        field is 1-bit wide and is driven by the input of its associated pin in the ``pins`` array
+        of the peripheral.
 
         Values sampled from pin inputs go through :attr:`Peripheral.input_stages` synchronization
         stages (on a rising edge of ``ClockSignal("sync")``) before reaching the register.
@@ -170,8 +170,8 @@ class Output(csr.Register, access="rw"):
         """Output register.
 
         This :class:`~.csr.reg.Register` contains an array of ``pin_count`` read/write fields. Each
-        field is 1-bit wide and drives the output of its associated pin in the
-        :attr:`Peripheral.pins` array, depending on its associated :class:`~Peripheral.Mode` field.
+        field is 1-bit wide and drives the output of its associated pin in the ``pins`` array of the
+        peripheral, depending on its associated :class:`~Peripheral.Mode` field.
 
         ----
 
diff --git a/docs/gpio.rst b/docs/gpio.rst
index c393de3..9fb6e6a 100644
--- a/docs/gpio.rst
+++ b/docs/gpio.rst
@@ -1,14 +1,67 @@
 GPIO
 ====
 
-.. warning::
-
-   This manual is a work in progress and is seriously incomplete!
-
 .. py:module:: amaranth_soc.gpio
 
 The :mod:`amaranth_soc.gpio` module provides a basic GPIO peripheral.
 
+.. testsetup::
+
+   from amaranth import *
+   from amaranth.lib import io, wiring
+   from amaranth.lib.wiring import In, Out, flipped, connect
+
+   from amaranth_soc import csr, gpio
+
+
+Introduction
+------------
+
+`GPIO <https://en.wikipedia.org/wiki/General-purpose_input/output>`_ peripherals are commonly used
+to interface a SoC (usually a microcontroller) with a variety of external circuitry. This module contains a GPIO peripheral which can be connected to a :ref:`CSR bus<csr-bus-introduction>`.
+
+Example
++++++++
+
+This example shows a GPIO peripheral being used to drive four LEDs:
+
+.. testcode::
+
+   class MySoC(wiring.Component):
+       def elaborate(self, platform):
+           m = Module()
+
+           m.submodules.led_gpio = led_gpio = gpio.Peripheral(pin_count=4, addr_width=8,
+                                                              data_width=8)
+
+           for n in range(4):
+               led = io.Buffer("o", platform.request("led", n, dir="-"))
+               connect(m, led_gpio.pins[n], led)
+
+           m.submodules.csr_decoder = csr_decoder = csr.Decoder(addr_width=31, data_width=8)
+           csr_decoder.add(led_gpio.bus, addr=0x1000, name="led_gpio")
+
+           # ...
+
+           return m
+
+Pin modes
+---------
+
 .. autoclass:: PinMode()
+
+Pin interface
+-------------
+
 .. autoclass:: PinSignature()
+
+Peripheral
+----------
+
+.. autoclass:: amaranth_soc.gpio::Peripheral.Mode()
+.. autoclass:: amaranth_soc.gpio::Peripheral.Input()
+.. autoclass:: amaranth_soc.gpio::Peripheral.Output()
+.. autoclass:: amaranth_soc.gpio::Peripheral.SetClr()
+
 .. autoclass:: Peripheral()
+   :no-members: