How to use the Gowin PSRAM interface?

[mobilinkd]

I see the PSRAM interfaced defined in chip database. How would one instantiate this interface within, for example, Amaranth, and have all of the IOBs properly mapped? Does this need to be added to the board file somehow?

What does sip_cst mean in this context?

Did I miss where this is documented?

Python 3.13.3 (main, Apr 22 2025, 00:00:00) [GCC 14.2.1 20250110 (Red Hat 14.2.1-7)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import gzip,pickle,json
>>> with gzip.open(f"GW1N-9C.pickle", 'rb') as f:
...     db = pickle.load(f)
...     
>>> print(json.dumps(db.sip_cst, indent=2))
{
  "GW1NR-9C": {
    "QFN88P": [
      [
        "O_psram_ck[0]",
        7,
        0,
        "A",
        null
      ],
      [
        "O_psram_ck[1]",
        22,
        0,
        "B",
        null
      ],
      [
        "O_psram_ck_n[0]",
        6,
        0,
        "A",
        null
      ],
      [
        "O_psram_ck_n[1]",
        22,
        0,
        "A",
        null
      ],
      [
        "O_psram_cs_n[0]",
        5,
        0,
        "B",
        null
      ],
      [
        "O_psram_cs_n[1]",
        21,
        0,
        "A",
        null
      ],
      [
        "O_psram_reset_n[0]",
        1,
        0,
        "A",
        null
      ],
      [
        "O_psram_reset_n[1]",
        17,
        0,
        "A",
        null
      ],
      [
        "IO_psram_dq[0]",
        1,
        0,
        "B",
        null
      ],
      [
        "IO_psram_dq[1]",
        2,
        0,
        "A",
        null
      ],
      [
        "IO_psram_dq[2]",
        2,
        0,
        "B",
        null
      ],
      [
        "IO_psram_dq[3]",
        3,
        0,
        "A",
        null
      ],
      [
        "IO_psram_dq[4]",
        8,
        0,
        "A",
        null
      ],
      [
        "IO_psram_dq[5]",
        13,
        0,
        "A",
        null
      ],
      [
        "IO_psram_dq[6]",
        15,
        0,
        "A",
        null
      ],
      [
        "IO_psram_dq[7]",
        16,
        0,
        "B",
        null
      ],
      [
        "IO_psram_dq[8]",
        17,
        0,
        "B",
        null
      ],
      [
        "IO_psram_dq[9]",
        19,
        0,
        "A",
        null
      ],
      [
        "IO_psram_dq[10]",
        19,
        0,
        "B",
        null
      ],
      [
        "IO_psram_dq[11]",
        20,
        0,
        "A",
        null
      ],
      [
        "IO_psram_dq[12]",
        23,
        0,
        "B",
        null
      ],
      [
        "IO_psram_dq[13]",
        24,
        0,
        "A",
        null
      ],
      [
        "IO_psram_dq[14]",
        25,
        0,
        "A",
        null
      ],
      [
        "IO_psram_dq[15]",
        26,
        0,
        "A",
        null
      ],
      [
        "IO_psram_rwds[0]",
        16,
        0,
        "A",
        null
      ],
      [
        "IO_psram_rwds[1]",
        26,
        0,
        "B",
        null
      ]
    ]
  }
}

[pepijndevos]

The best reference is probably LiteX: https://github.com/litex-hub/litex-boards/blob/master/litex_boards/targets/sipeed_tang_nano_9k.py https://github.com/litex-hub/litex-boards/blob/master/litex_boards/platforms/sipeed_tang_nano_9k.py

sip_cst stands for "system in package constraints" and maps the internal FPGA connections to the SPRAM to the correct physical FPGA pads.

Fundamentally how it works is inside the FPGA package there is a physical ram chip bonded to regular FPGA IO pads, so just like you write a constraint file for external pins, we include constraints for the internal pins.

This matches vendor behavior where ports with these "magic" names get mapped to the correct internal pins.

[mobilinkd]

Thank you. I see that it matches the vendor behavior. This is not possible to do in Amaranth.

  File "tang_nano_9k/amaranth_boards/tang_nano_9k.py", line 56, in TangNano9kPlatform
    Resource("IO_psram_ck", 0, Pins(2, dir="o")),
                               ~~~~^^^^^^^^^^^^
  File ".local/lib/python3.13/site-packages/amaranth/build/dsl.py", line 14, in __init__
    raise TypeError("Names must be a whitespace-separated string, not {!r}"
                    .format(names))
TypeError: Names must be a whitespace-separated string, not 2

As soon as I add pin names, however, these cause Amaranth to add these to the constraints file. And since there are no real pins associated with these, I have to just use bogus pin names. This, of course, does not work during synthesis as the constraints are invalid.

Amaranth also mangles the resource names that it uses for top-level interfaces, assuming that the actual wire/reg names are irrelevant. That is certainly not the case for this PSRAM interface. These are "magic" names that have to match exactly.

I raised this issue a year ago with @whitequark as an Amaranth issue, but this is not a priority to implement.

@pepijndevos It would be a bit easier to use these pins with other tools if Apicula added pin names for this interface to the pinout. Is that possible to do?

[pepijndevos]

I would suggest adding a verilog peripheral to amaranth to expose the pins.

It is technically possible to manually assign the pins to the correct location but not recommended.

I think the pinout thing you're talking about might be an amaranth feature. You could presumably teach amaranth the correct constraint for these internal pins. I think inside the legacy folder we have an example that does that.