[opentitanlib] SAM3X interface pin mappings

[jwnrt]

Description

There are some gaps in the config files for the cw310 interface which goes through the SAM3X.

• Some pin names are not recognised, leading to errors like Error: Invalid pin name IOR10.
• The dut UART is not configured correctly, so most UART tests fail.

[pamaury]

I would have to double-check the schematics but is it simply possible that OT's IOR10 is not routed to anything on the SAM3x? This could explain why it's not defined.

[a-will]

IOR10 is mapped to an LED. The SAM3X variant is not a fully-capable test platform like the hyperdebug platform; it supports only minimal connectivity.

Instead, the SAM3X variant largely is a platform for demos with blinking lights and human-interactive switches and buttons.

[jwnrt]

I wonder if we should remove the SAM3X interface environments from EARLGREY_TEST_ROMS. I think this interface is still valuable for running things without having to deal with HyperDebug, but it's adding a bit of a development burden to tests when it's used in the default set of test environments.

[pamaury]

I think we should at least discuss this in a software meeting. The only issue I see is that the SAM3x is not a good platform to test I/Os but otherwise is fine. We could introduce a EARLGREY_IO_TEST_ENS for tests that require nontrivial IOs setups. I expect the dichotomy between IO/non-IO boards will remain one in the future.

[jwnrt]

Hmm okay, I guess if a test isn't doing IO then it doesn't matter whether it's running with the HyperDebug or SAM3X apart from the BoB tests.

I think the ideal end state I would like to see is:

1. BoB tests refactored so they can run with the HyperDebug bitstream. @engdoreis had some ideas for how to do this.
2. CW310 + HyperDebug bitstreams merged into one.
   • This might be tricky. I would want either the SAM3X or HyperDebug to act as the SPI host or UART endpoint mutually exclusively depending on which you want to use.
   • They would both be connected to the pads, but only one would be configured at a time. The other would need to be configured to not disturb the wires.
3. All tests run with --hyper310 interface. This should be overridable for individual runs with something like bazel test //target_fpga_cw310_test_rom -- --interface sam3x or similar.

This way we only build one CW310 bitstream, only need to support HyperDebug for testing, and still allow running tests ad hoc if you don't have a HyperDebug.

[a-will]

Hmm okay, I guess if a test isn't doing IO then it doesn't matter whether it's running with the HyperDebug or SAM3X apart from the BoB tests.

I think the ideal end state I would like to see is:

1. BoB tests refactored so they can run with the HyperDebug bitstream. @engdoreis had some ideas for how to do this.

BoB SPI is unsupported and not pinned out, and I think it should remain that way (closed-source / unavailable chips and unnecessarily removes yet more interfaces from hyperdebug itself). The I2C tests should be able to run, though.

2. CW310 + HyperDebug bitstreams merged into one.

   • This might be tricky. I would want either the SAM3X or HyperDebug to act as the SPI host or UART endpoint mutually exclusively depending on which you want to use.
   • They would both be connected to the pads, but only one would be configured at a time. The other would need to be configured to not disturb the wires.

No, do not make the bitstreams more complicated for I/O. We have rejected this in the past for good reason--You can't just arbitrarily hook up pins. PD issues like timing closure apply to the FPGA as well.

3. All tests run with --hyper310 interface. This should be overridable for individual runs with something like bazel test //target_fpga_cw310_test_rom -- --interface sam3x or similar.

This way we only build one CW310 bitstream, only need to support HyperDebug for testing, and still allow running tests ad hoc if you don't have a HyperDebug.

Abandon BoB SPI, and all the tests should run, I believe.

However, you'll make the FPGA much less reliable to build and more complex to configure if you try to fit in all board features in a single bitstream. I strongly recommend against this, especially for CW310's highly impacted resources.

[jwnrt]

BoB SPI is unsupported and not pinned out, and I think it should remain that way (closed-source / unavailable chips and unnecessarily removes yet more interfaces from hyperdebug itself).

Oh, I didn't realise had forgotten the BoB was closed source. I thought it was just a collection of generic SPI and I2C devices. Maybe the part numbers are sensitive to somebody?

No, do not make the bitstreams more complicated for I/O. We have rejected this in the past for good reason--You can't just arbitrarily hook up pins. PD issues like timing closure apply to the FPGA as well.

Okay, point taken, this would be pretty complicated. Would you prefer to continue supporting both bitstreams or just drop the SAM3X compatibility entirely?

Abandon BoB SPI, and all the tests should run, I believe.

They will all run through the HyperDebug, yes. I think there was a way of still being able to access some of the SPI flashes with the limited pins available for the PMOD connectors.

Are you saying that once all tests run with HyperDebug we can drop SAM3X entirely?

[a-will]

BoB SPI is unsupported and not pinned out, and I think it should remain that way (closed-source / unavailable chips and unnecessarily removes yet more interfaces from hyperdebug itself).

Oh, I didn't realise the BoB was closed source. I thought it was just a collection of generic SPI and I2C devices. Maybe the part numbers are sensitive to somebody?

Apparently sensitive and/or difficult to procure on the open market. I wasn't involved in the BoB's creation, and its existence doesn't align with the original definition of the hyperdebug test platform (which itself has some problems). Planning for FPGA testing has tended to devolve into anarchy, unfortunately, with predictable results.

No, do not make the bitstreams more complicated for I/O. We have rejected this in the past for good reason--You can't just arbitrarily hook up pins. PD issues like timing closure apply to the FPGA as well.

Okay, point taken, this would be pretty complicated. Would you prefer to continue supporting both bitstreams or just drop the SAM3X compatibility entirely?

Ehh, I don't know. Someday, I would like to reduce the number of supported platform variants, but the options we have right now all have drawbacks.

For the moment, I would probably choose to avoid any extra work unless our development velocity were truly being hampered by the extra bitstream. If it is causing velocity problems, then I'd probably kick the SAM3X variant out of PR CI and call it unsupported, at least for now.

Abandon BoB SPI, and all the tests should run, I believe.

They will all run through the HyperDebug, yes. I think there was a way of still being able to access some of the SPI flashes with the limited pins available for the PMOD connectors.

Are you saying that once all tests run with HyperDebug we can drop SAM3X entirely?

That was our original intention, yes.

However... The final outcome of the board designs left us with this unreliable connection and a janky interface board that can be a pain to procure. It's not a great situation for newcomers to the project.

If the SAM3X variant goes away entirely, every partner that wants to do software development on a reasonably fast platform then needs to deal with manufacturing and assembly of the interface boards, even if they don't need more I/O than what the SAM3X variant provides for their use cases.

The problems start from what CW310 itself offers, though. The on-board devices can't provide all required test features, and the User I/O connectors on the board require a small pitch ribbon cable that can't be mechanically secured.

At this point, we're between a rock and a hard place. Do we make it easier to obtain parts to create the hyperdebug setup? Do we continue supporting so many bitstreams? etc.