M/S Terminology cleanup

[jepler]

I think this corrects most of the M/S terminology that does not depend on upstream libs such as asf4, softdevice, etc., renaming things.

Note that there is an incompatible new name for the i2csecondary module and its contents, with no backwards compatibility alias. Technically, semver says that this requires a major version bump. Just sayin'.

[dhalbert]

Are there some commits here that were already merged? DTCM and ITCM support, etc.? Maybe do a merge from upstream and push again?

[jepler]

@dhalbert check again? I think I rebased against a wrong branch due to muscle memory.

[dhalbert]

@dhalbert check again? I think I rebased against a wrong branch due to muscle memory.

Yes, looks good now. Re API I2CSecondary change: we could advance the beta to 6.0.0, or we could alias the old name for now. I don't think it's that big a deal to advance to 6.0, because the sleep stuff is a major inflection point anyway, and it's going to be a while before this beta stops being beta. This would give us the opportunity to make some other breaking changes that are on hold for 6.0.0 also.

[tannewt]

Mind adding a section on the renaming to the design guide here? https://github.com/adafruit/circuitpython/blob/main/docs/design_guide.rst

Thanks for kicking this off!

[tannewt]

Want to reduce this to one definition?

[tannewt]

This looks good to me! Thank you!

[tannewt]

Thinking about this more, I don't really like the main/secondary name for SPI. I think "host" and "device" or "peripheral" are more descriptive. (The latter matches the name SPI.) It matches our existing model for bus devices as well. We can keep the MOSI and MISO names where we have them and simply document them in host and device terms.

There is a bit of weirdness around whether the code is the device or is talking to a device. The BLE apis have this challenge as well where a Characteristic can be remote or local.

In some cases, I also think ignorelist could be more fitting than denylist.

I know this PR is close in that it has my own approval but I think it's worth thinking hard about. Renaming long existing terminology is a big change and we should make sure we're picking the best terms.

[hierophect]

My preference is for the existing terminology as suggested. I've seen main/secondary gaining traction for SPI online following Github's main transition, and I strongly value the compatibility with existing acronyms, especially when considering 3rd party boards and libraries. I don't feel that Host and Peripheral are as beginner friendly terms as I think they are mostly familiar to people of a technical background.

For AllowList/DenyList, there's already a more concrete precedent, as Gitlab and Rails have already swapped to these terms. I think that following the pack here is both less confusing and carries more momentum for this topic overall.

[tannewt]

My preference is for the existing terminology as suggested. I've seen main/secondary gaining traction for SPI online following Github's main transition

Where? Are there examples of other hardware projects switching to it?

I don't feel that Host and Peripheral are as beginner friendly terms as I think they are mostly familiar to people of a technical background.

Why not? Main and Secondary feel like they could apply to anything.

For AllowList/DenyList, there's already a more concrete precedent, as Gitlab and Rails have already swapped to these terms. I think that following the pack here is both less confusing and carries more momentum for this topic overall.

I think we should match these in cases where the use is the same. What I'm pushing back against is the idea that these single terms should be replaced by a single terms. For example, denylist makes sense if a reply is sent to requester saying it was denied. If a reply isn't sent back, then ignorelist makes more sense.

[jepler]

I'm happy to rework this PR to reflect whatever the consensus terms are.

[FoamyGuy]

I found this recently updated Microsoft docs page: https://docs.microsoft.com/en-us/uwp/api/windows.devices.spi?view=winrt-19041

SPI terminology arose in the 1980s, and so some of the language used in the standard is anachronistic. In this documentation we use the term host to refer to a device from which the clock signal originates; and peripheral to refer to a device that may use and forward the clock signal, but that doesn't originate it. Other documentation resources for SPI might use different terms for those device types, but now that you know the host's and the peripheral's relationship to the clock signal, you'll be able to easily translate between the equivalent terms.

If I understand the note correctly it looks like they are going with host and peripheral and their usage specifically relates to the clock signal.

[FoamyGuy]

I also found a small/medium, sized project here that looks to have gone with main/secondary: noopkat/oled-js@20f7d8d

[FoamyGuy]

I poked around a bit more but have not really run across any other projects that have made the move yet within the context of SPI / I2C. It seems at this point there is lots of discussion ongoing, but not a lot of actual precedent set.

Personally I probably lean toward using main/secondary in order to reduce confusion with acronyms (MI, MO, MISO, and MOSI) that are printed as pin labels on some devices. However I do also agree they are somewhat vague so I am not staunchly opposed to host/peripheral or something different.

[hierophect]

I'm going to condense my opinion down here and say that what I really care about is not breaking acronyms that appear on silkscreens - I think it's a significant obstacle to both new users and 3rd party developers. I would weigh the accessibility of the terms over their technical precision in this case, since the exact roles of SPI devices vary a lot anyway, so my preference is for main/secondary.

[dhalbert]

We could put "Main (host)" and "Secondary (peripheral)" in the docs as explanatory comments (or the other way around, depending on the actual API args, etc.)

[tannewt]

What if we split the name of the device roles (host / peripheral or device) and come up with a new acronyms for MOSI and MISO? "Main output, shared input" and "Main input, shared output" Those acronyms explain that the lines are an output to one device and shared inputs to others and vice versa.

[tannewt]

Rob_Fenwitch on Discord recommended "Main *, Selected *" which makes sense in the context of have a chip select line.

[dhalbert]

"SPI" is an acronym for Serial Peripheral Interface, so it could be
Main
SPI Device

[tannewt]

Ok, so we just discussed this in the weekly meeting. The conclusion is:

• I2CSlave -> I2CPeripheral
• "Master *, Slave *" -> "Main *, Selected (peripheral) *" Guides already use some other terms so we should focus on the MOSI and MISO acronyms.

[tannewt]

Please rerun make translate to get the latest file move info in the file. Thanks for sticking this out. I think it's close.

[jepler]

Thanks for the review! I especially appreciate you finding the things I just overlooked in the repeated renamings.

[fede2cr]

This is how some of the words that have been discussed translate to spanish.

main -> principal (we loose the M initial)
manager -> administrador (same)
host and device -> dispositivo (host and device and normally interchangeable)
peripheral -> periférico (ok)
selected -> seleccionado (ok)

[tannewt]

Thank you!

[jepler]

@tannewt after your merge of main the CI passed. What's left?

[tannewt]

I just got distracted and didn't merge. Now it needs a merge again.

[jepler]

I'll rebase it and rerequest your review.

[tannewt]

GitHub is still showing merge conflicts.

[jepler]

Merge conflicts resolved again, I had rebased against an older main ref by accident.

[tannewt]

Thank you!

[deshipu]

In related news: https://hackaday.com/2020/06/29/updating-the-language-of-spi-pin-labels-to-remove-casual-references-to-slavery/

[dhalbert]

Thanks @deshipu. The article above points to an OSHWA resolution: https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names

The essence is (qouting)

New signal names:

• SDO – Serial Data Out. An output signal on a device where data is sent out to another SPI device.
• SDI – Serial Data In. An input signal on a device where data is received from another SPI device.
• CS – Chip Select. Activated by the controller to initiate communication with a given peripheral.
• COPI (controller out / peripheral in). For devices that can be either a controller or a peripheral; the signal on which the device sends output when acting as the controller, and receives input when acting as the peripheral.
• CIPO (controller in / peripheral out). For devices that can be either a controller or a peripheral; the signal on which the device receives input when acting as the controller, and sends output when acting as the peripheral.
• SDIO – Serial Data In/Out. A bi-directional serial signal.

Deprecated signal names:

• MOSI – Master Out Slave In
• MISO – Master In Slave Out
• SS – Slave Select
• MOMI – Master Out Master In
• SOSI – Slave Out Slave In

Signal names unchanged:

• SCK – Serial Clock. The clock for the bus generated by the controller.

Also