confusing PWM terminology: overloading of the word `channel`

[dhalbert]

The PWM terminology is somewhat confusing: there are are 8 slices, and each slice has two output channels. However, elsewhere, the total of 2*8 whatevers are called channels as well. And sometimes the 8 slices are called channels.

I'm bringing this up because this overloading of the word channel, and channel vs slice, was apparently confusing enough that some of our code mistakenly used an A/B channel number when we meant to use a slice number.

Some quotes from the datasheet (emphases mine)

4.5.1. Overview ... The RP2040 PWM block has 8 identical slices. Each slice can drive two PWM output signals...

Each PWM slice is equipped with the following: ...

• Two independent output channels, ...

4.5.2. Programmer’s Model ... Table 525. Mapping of PWM channels to GPIO pins on RP2040. ...

• The 16 PWM channels (8 2-channel slices) appear on GPIO0 to GPIO15, ...

4.5.3 List of Registers

• Registers include CHn_CSV, CHn_DIV, CHn_CTR, CHn_CC, CHn_TOP, where n ranges from 0 to 7 and is the slice number, even though CH stands for channel.
• The EN, INTR, INTE, INTF, and INTS register bits are described in terms of channels, CH7 through CH0, but the bits correspond to slices.

In the SDK, there are functions:

• static uint pwm_gpio_to_slice_num (uint gpio): gets slice number for the given gpio
• static uint pwm_gpio_to_channel (uint gpio): gets one of two channels (A or B, 0 or 1) for the given gpio
• static void pwm_set_chan_level (uint slice_num, uint chan, uint16_t level): takes a slice and an A/B channel number

It's probably too late to change the SDK API and the #define names, but perhaps some warnings could be add to datasheet and the SDK documentation. I don't really have a good suggestion, but maybe the A/B channels could be called slice channels, or just outputs, and the API documentation could clarify and warn what is taken and what is being returned. The CHn constants could in the long run be aliased by SLn constants.

[aallan]

@nathan-contino You should chat with @kilograham about this one before proceeding.