[proposal] Create a reusable APB GPIO controller IP

[briann-bui]

Summary

Create a reusable apb-gpio-core for MCU, SoC, and RISC-V systems. This issue is the design discussion and contributor coordination point; implementation should begin only after the interface and register map are agreed.

Proposed v1 scope

• Synthesizable SystemVerilog with a 32-bit APB interface.
• Parameterized GPIO width, default 32 pins.
• Per-pin input, output, and output-enable control.
• Atomic output set, clear, and toggle registers.
• Per-pin interrupt enable and status.
• Rising-edge, falling-edge, high-level, and low-level interrupt modes.
• Write-one-to-clear interrupt status and one aggregated IRQ output.
• Portable RTL with no vendor-specific primitives in the core.

Proposed register map

The contributor should include a reviewed register specification covering at least DATA_IN, DATA_OUT, DATA_SET, DATA_CLR, DATA_TOGGLE, DIR, IRQ_EN, IRQ_TYPE, IRQ_POLARITY, and IRQ_STATUS. Addresses, reset values, access types, reserved bits, and side effects must be documented before RTL is finalized.

Out of scope for v1

• Pin multiplexing or pad-ring integration.
• Analog I/O.
• Clock-domain crossing between APB and GPIO inputs.
• Debounce/filtering; this can be proposed as a later feature.

Deliverables

• Architecture and register-map documentation.
• Synthesizable RTL and top-level wrapper.
• Self-checking UVM environment with APB agent, GPIO stimulus/monitoring, scoreboard, assertions, and functional coverage.
• Tests for reset, register access, input sampling, output/direction control, atomic writes, all interrupt modes, W1C behavior, and simultaneous events.
• Verilator lint and reproducible simulation targets in the Makefile.
• User-facing README with integration and verification instructions.

Acceptance criteria

• Maintainers approve the external interface and register map before implementation.
• RTL passes make lint with no new warnings.
• The complete UVM regression is deterministic and self-checking.
• Functional coverage exercises all supported GPIO and interrupt modes.
• Documentation matches the implemented ports, parameters, and registers.
• The pull request links this issue and reports exact lint/simulation commands and results.

How to contribute

Comment with the part you want to own: specification, RTL, UVM environment, assertions/coverage, or documentation. Large work should be split into reviewable pull requests. Please read the organization contribution rules first.