GPIO

The amaranth_soc.gpio module provides a basic GPIO peripheral.

Introduction

GPIO 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 CSR bus.

Example

This example shows a GPIO peripheral being used to drive four LEDs:

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

class amaranth_soc.gpio.PinMode

GPIO pin mode.

The 2-bit values of this enumeration can be written to a Peripheral.Mode field to configure the pins of a Peripheral.

INPUT_ONLY = 0

Input-only mode.

The pin output is disabled but remains connected to its Peripheral.Output field. Its Peripheral.alt_mode bit is wired to 0.

PUSH_PULL = 1

Push-pull mode.

The pin output is enabled and connected to its Peripheral.Output field. Its Peripheral.alt_mode bit is wired to 0.

OPEN_DRAIN = 2

Open-drain mode.

The pin output is enabled when the value of its Peripheral.Output field is 0, and is itself wired to 0. Its Peripheral.alt_mode bit is wired to 0.

ALTERNATE = 3

Alternate mode.

The pin output is disabled but remains connected to its Peripheral.Output field. Its Peripheral.alt_mode bit is wired to 1.

Pin interface

class amaranth_soc.gpio.PinSignature

GPIO pin signature.

Interface attributes

iSignal

Input.

oSignal

Output.

oeSignal

Output enable.

Peripheral

class Peripheral.Mode

A CSR register.

Parameters:

fields (dict or list or Field) – Collection of register fields. If None (default), a dict is populated from Python variable annotations. fields is used to create a FieldActionMap, FieldActionArray, or FieldAction, depending on its type (dict, list, or Field).

Interface attributes

elementElement

Interface between this register and a CSR bus primitive.

Attributes:

• field (FieldActionMap or FieldActionArray or FieldAction) – Collection of field instances.

• f (FieldActionMap or FieldActionArray or FieldAction) – Shorthand for Register.field.

raises TypeError:

If fields is neither None, a dict, a list, or a Field.

raises ValueError:

If fields is not None and at least one variable annotation is a Field.

raises ValueError:

If element.access is not readable and at least one field is readable.

raises ValueError:

If element.access is not writable and at least one field is writable.

class Peripheral.Input

A CSR register.

Parameters:

fields (dict or list or Field) – Collection of register fields. If None (default), a dict is populated from Python variable annotations. fields is used to create a FieldActionMap, FieldActionArray, or FieldAction, depending on its type (dict, list, or Field).

Interface attributes

elementElement

Interface between this register and a CSR bus primitive.

Attributes:

• field (FieldActionMap or FieldActionArray or FieldAction) – Collection of field instances.

• f (FieldActionMap or FieldActionArray or FieldAction) – Shorthand for Register.field.

raises TypeError:

If fields is neither None, a dict, a list, or a Field.

raises ValueError:

If fields is not None and at least one variable annotation is a Field.

raises ValueError:

If element.access is not readable and at least one field is readable.

raises ValueError:

If element.access is not writable and at least one field is writable.

class Peripheral.Output

A CSR register.

Parameters:

fields (dict or list or Field) – Collection of register fields. If None (default), a dict is populated from Python variable annotations. fields is used to create a FieldActionMap, FieldActionArray, or FieldAction, depending on its type (dict, list, or Field).

Interface attributes

elementElement

Interface between this register and a CSR bus primitive.

Attributes:

• field (FieldActionMap or FieldActionArray or FieldAction) – Collection of field instances.

• f (FieldActionMap or FieldActionArray or FieldAction) – Shorthand for Register.field.

raises TypeError:

If fields is neither None, a dict, a list, or a Field.

raises ValueError:

If fields is not None and at least one variable annotation is a Field.

raises ValueError:

If element.access is not readable and at least one field is readable.

raises ValueError:

If element.access is not writable and at least one field is writable.

class Peripheral.SetClr

A CSR register.

Parameters:

fields (dict or list or Field) – Collection of register fields. If None (default), a dict is populated from Python variable annotations. fields is used to create a FieldActionMap, FieldActionArray, or FieldAction, depending on its type (dict, list, or Field).

Interface attributes

elementElement

Interface between this register and a CSR bus primitive.

Attributes:

• field (FieldActionMap or FieldActionArray or FieldAction) – Collection of field instances.

• f (FieldActionMap or FieldActionArray or FieldAction) – Shorthand for Register.field.

raises TypeError:

If fields is neither None, a dict, a list, or a Field.

raises ValueError:

If fields is not None and at least one variable annotation is a Field.

raises ValueError:

If element.access is not readable and at least one field is readable.

raises ValueError:

If element.access is not writable and at least one field is writable.

class amaranth_soc.gpio.Peripheral