Technical Reference Chapter 4 is confusing

[clarkster]

I am trying to understand how the GPIO Matrix and the IO_Mux work. I've spent several hours studying Chapter 4 but I still don't understand. One reason is that Chapter 4 has several errors in it (I think).

1. The chapter often refers to bits and fields of registers but doesn't say what register the bit or field is in.
2. Register names, bit names, and field names often don't match the names in the Tech Ref. They are close but because they are not exact it causes me to wonder if I am looking at the right register.
3. I can't find some of the registers. bit, and field names.
4. Examples would greatly help us understand this section.

Here are some specific sections that have these problems:

Section 4.2.2

Figure 8 - GPIO_SIG_xx_IN_SEL possibly should be IO_x_MCU_SEL?, what is GPIOx_MCU_SEL?, what is GPIOx_FUN_IE?
What is GPIO_ENABLE_DATA[x] in step 2?
In step 3, it says "Set function field to GPIO". Should say this is in register IO_x_MCU_SEL.

Section 4.2.3

Talks about the xx_FUN_IE register. I think this is the IO_X_FUN_IE register. I know this is picky but it is better to be consistent in naming, especially when the document is intended to teach new people about the operation of the chip.

Section 4.3.2

What is GPIO_ENABLE_DATA[x] in step 1?
Figure 9 - GPIOx_MCU_SEL is a field of the IO_MUX_X_REG, what is GPIOx_FUN_OE?

Other things:

It would be very helpful to have an example. For example, provide an example to make GPIO23 be an output for RMT channel 1. Show all the changes to all the registers, field, and bits. Provide another example showing input configuration. Provide another example showing configuration of direct I/O using the IO_Mux. Provide another example showing how to route an output from the RMT to the PCNT as well as to a GPIO.

Here is a big one. I am looking at the tech ref manual on a Mac (OS X). I don't know about the PC, but on the Mac I can search the PDF for certain text. I had hoped that I could search for "FUN_IE" and possibly determine if it was part of a register name or the name of a field in a register. Unfortunately it found it only in Figure 8...no where else. This make me think the label is wrong in Figure 8. However when I do another search for "IN_SEL" it finds that text in two places in Figure 8, but also no where else. In this case I know the search is wrong because "IN_SEL" is part of the name of several registers. Here's another search failure....if I search for "IN_INV_SEL" it finds nothing even though it is a bit in the GPIO_FUNCm_IN_SEL_REG. This may be a defect in the OS X PDF viewer but I think searching works well in other PDFs.

[WiFive]

Figure 8 - GPIO_SIG_xx_IN_SEL possibly should be IO_x_MCU_SEL?, what is GPIOx_MCU_SEL?, what is GPIOx_FUN_IE?
What is GPIO_ENABLE_DATA[x] in step 2?

GPIO_SIG_xx_IN_SEL = GPIO_SIGm_IN_SEL. GPIOx_MCU_SEL = IO_x_MCU_SEL. GPIOx_FUN_IE = IO_x_FUN_IE.
GPIO_ENABLE_DATA[x] is a set of bits that spans 2 registers GPIO_ENABLE_REG GPIO_ENABLE1_REG

[ESP_Angus]

Hi clarkster,

Thanks for pointing all this out.

1. The chapter often refers to bits and fields of registers but doesn't say what register the bit or field is in.

This should be able to be found by searching the 4.13 Registers section.

2. Register names, bit names, and field names often don't match the names in the Tech Ref. They are close but because they are not exact it causes me to wonder if I am looking at the right register.

Do you mean names used in code, or names used elsewhere in the TRM?

Section 4.2.2

Figure 8 - GPIO_SIG_xx_IN_SEL possibly should be IO_x_MCU_SEL?, what is GPIOx_MCU_SEL?, what is GPIOx_FUN_IE?
What is GPIO_ENABLE_DATA[x] in step 2?
In step 3, it says "Set function field to GPIO". Should say this is in register IO_x_MCU_SEL.

WiFive gave a summary of the changes here. Here's a rewritten version of the steps for an Input pad given under Figure 7 (will also talk to the documentation team about these edits):

To read GPIO pad X into peripheral signal Y, follow the steps below:

1. Configure the GPIO_FUNCy_IN_SEL_CFG register corresponding to peripheral signal Y in the GPIO Matrix:
   • Set the GPIO_FUNCx_IN_SEL field in this register, corresponding to the GPIO pad X to read from. Clear all other fields corresponding to other GPIO pads.
2. Configure the GPIO_FUNCx_OUT_SEL_CFG register and clear the GPIO_ENABLE_DATA[x] field corresponding to GPIO pad X in the GPIO
   Matrix:
   • Set the GPIO_FUNCx_OEN_SEL bit in the GPIO_FUNCx_OUT_SEL_CFG register to force the pin's output state to be determined always by the GPIO_ENABLE_DATA[x] field.
   • The GPIO_ENABLE_DATA[x] field is a bit in either GPIO_ENABLE_REG (GPIOs 0-31) or GPIO_ENABLE1_REG (GPIOs 32-39). Clear this bit to disable the output driver for the GPIO pad.
3. Configure the IO_MUX to select the GPIO Matrix. Set the IO_MUX_x_REG register corresponding to GPIO pad X as follows:
   • Set the function field (IO_x_MCU_SEL) to the IO_MUX function corresponding to GPIO X (this is function #2 for all pins).
   • Enable the input by setting the FUN_IE bit.
   • Set or clear the FUN_WPU and FUN_WPD bits, as desired, to enable/disable internal pull-up/pull-down resistors.

Let me know if anything there still doesn't follow.

Section 4.2.3

Talks about the xx_FUN_IE register. I think this is the IO_X_FUN_IE register. I know this is picky but it is better to be consistent in naming, especially when the document is intended to teach new people about the operation of the chip.

Yes, this should be something like "However, it is necessary to enable the input in the IO_MUX by setting the configure the FUN_IE bit in the IO_MUX_x_REG register corresponding to pad X, as mentioned in Section 4.2.2."

Section 4.3.2

What is GPIO_ENABLE_DATA[x] in step 1?
Figure 9 - GPIOx_MCU_SEL is a field of the IO_MUX_X_REG, what is GPIOx_FUN_OE?

For outputs, some rewording (as above):

To output peripheral signal Y to particular GPIO pad X, follow these steps:

1. Configure the GPIO_FUNCx_OUT_SEL_CFG register and GPIO_ENABLE_DATA[x] corresponding to GPIO pad X:
   • Set the GPIO_FUNCx_OUT_SEL field in GPIO_FUNCx_OUT_SEL_CFG to the numeric index (Y) of desired peripheral output signal Y.
   • If the signal should always be enabled as an output, set the GPIO_FUNCx_OEN_SEL bit in the GPIO_FUNCx_OUT_SEL_CFG register corresponding to GPIO pad X. To have the output enable signal decided by internal logic, clear the GPIO_FUNCx_OEN_SEL bit instead.
   • The GPIO_ENABLE_DATA[x] field is a bit in either GPIO_ENABLE_REG (GPIOs 0-31) or GPIO_ENABLE1_REG (GPIOs 32-39). Set this bit to disable the output driver for the GPIO pad.
2. For an open drain output, set the GPIO_PINx_PAD_DRIVER bit in the GPIO_PINx register corresponding to GPIO pad X. For push/pull mode (default), clear this bit.
3. Configure the IO_MUX to select the GPIO Matrix. Set the IO_MUX_x_REG register corresponding to GPIO pad X as follows:
   • Set the function field (IO_x_MCU_SEL) to the IO_MUX function corresponding to GPIO X (this is function #2 for all pins).
   • Set the FUN_DRV field to the desired value for output strength (1-3). The higher the drive strength, the more current can be sourced/sunk from the pin.
   • If using open drain mode, set/clear the FUNC_WPU and FUNC_WPD bits to enable/disable the internal pull-up/down resistors.

It would be very helpful to have an example. For example, provide an example to make GPIO23 be an output for RMT channel 1. Show all the changes to all the registers, field, and bits. Provide another example showing input configuration. Provide another example showing configuration of direct I/O using the IO_Mux. Provide another example showing how to route an output from the RMT to the PCNT as well as to a GPIO.

Good suggestion, thanks. I will pass this on to the documentation team.

I am looking at the tech ref manual on a Mac (OS X). I don't know about the PC, but on the Mac I can search the PDF for certain text. I had hoped that I could search for "FUN_IE" and possibly determine if it was part of a register name or the name of a field in a register. Unfortunately it found it only in Figure 8...no where else. This make me think the label is wrong in Figure 8. However when I do another search for "IN_SEL" it finds that text in two places in Figure 8, but also no where else. In this case I know the search is wrong because "IN_SEL" is part of the name of several registers. Here's another search failure....if I search for "IN_INV_SEL" it finds nothing even though it is a bit in the GPIO_FUNCm_IN_SEL_REG. This may be a defect in the OS X PDF viewer but I think searching works well in other PDFs.

What version of the TRM do you have? There were a couple of older versions with PDF generation issues a bit like this, although I think they've been resolved. When I search for (for example) for IN_INV_SEL I found two references on pages 47 & 68, in TRM V2.8 (Jan 2018).

I will check with the documentation team as they all use macOS (I don't).

[clarkster]

Thank you both for your comments. I will annotate my version of TRM with your information. Additionally, I hope the documentation team will spend a little more time on this chapter and include your comments.

Do you mean names used in code, or names used elsewhere in the TRM?

I mean names used elsewhere in the TRM.

Regarding my TRM version, I keep my TRM up to date. I have V2.8.

Clark

[ESP_Angus]

Additionally, I hope the documentation team will spend a little more time on this chapter and include your comments.

For the record, I also edited this chapter (from the technical perspective) back in 2016 so this qualifies as me fixing my own mistakes.

[clarkster]

Additionally, I hope the documentation team will spend a little more time on this chapter and include your comments.

For the record, I also edited this chapter (from the technical perspective) back in 2016 so this qualifies as me fixing my own mistakes.

Nobody's perfect. You guys do excellent work.

The problem here is that you are probably too knowledgeable. What seems clear to you is not necessarily clear to us newbies.

[fhng11214]

This helps a lot, thx.