When looking at Figure 2 in
https://github.com/GlasgowEmbedded/archive/raw/main/G00079/Using_Differential_IOLVDS_Sub-LVDS_in_iCE40_Devices_Revision_1.5.pdf
it seems like IOL_nA is non-inverting and IOL_nB is inverting. The document explicitly mentions LP/HX devices and not UP. It is also explained in the text on page 3:

Connect the positive or true polarity side of the differential pair to the DPxxA input and the negative or complemen-
tary side of the pair to the DPxxB input.

This doesn't match the above mentioned nMigen comment.

I couldn't quickly find another document from Lattice confirming this.

The ball numbers in our symbol and the IOL_nA / IOL_nB description matches the pinout description from Lattice.

We always call the *_A from the FPGA _P (positive, non-inverting) and the *_B _N (negative, inverting). This matches the LVDS document I linked above.

When comparing the LVDS pinout on revC0, revC1 and revC2 I couldn't see a difference.

I'm trying to understand where the issue actually occurs. Could it be that the nMigen comment is wrong? Or is the error in the Lattice documentation?

from IRC discussion https://freenode.irclog.whitequark.org/glasgow/2021-03-29#29552047 :

@adamgreig found that Lattice changed the _A and _B designators in the revision history of the tech note linked above. This suggests that there are some inconsistencies in the Lattice documentation about this detail. So it is not unlikely that the nMigen comment is correct.

Could it be that the nMigen comment is wrong? Or is the error in the Lattice documentation?

If you try to synthesize a design with the pins assigned as they are right now, you get a placement error.

Further progress from IRC:

@smunaut saw that inverting and non-inverting is swapped between input and output pairs.

Naming in the Glasgow schematics currently matches output pairs.

Figure 9 in the tech note shows that the input pair has a fixed polarity, while for the output pair LUTs are used, so inverting is free. This would mean that naming the pins in the schematics would be better done according to input pairs.

Now the best course of action is still to be determined: Swapping pin names now could lead to confusion with existing addons/documents/code. OTOH, getting a placement error with the names from the schematics will lead to confusion too.

Swapping pin names now could lead to confusion with existing addons/documents/code. OTOH, getting a placement error with the names from the schematics will lead to confusion too.

Fix it. The LVDS connector is supported on a best-effort basis so I am not concerned about downstream fallout. Also, barely anyone has ever used it.

I assume we mean swapping the labels, not the traces. If so, agreed. Whatever fallout exists right now can be mitigated, let's make the docs sane from here on.

Yes, the labels of course.

As this just affects the labeling and not the traces, I don't consider it urgent. I'm currently busy with other stuff, so it will take me 3 weeks or so until I'll work on it.

If someone else wants to work on this, feel free to take over this issue and send a pull request or questions.

@esden some notes here on the lvds connector that might affect the rampak (but likely not since the only differential signal is the clock which is an output from the fpga).

@esden Could you please check the latest revC schematic to see if that's still a problem?