docs: Clarify set/get_gpio_attr() and GPIO banks

This adds a section on GPIO bank names to multi_usrp.hpp, and clarifies
the difference between the multi_usrp and RFNoC APIs regarding GPIO
control.

1 files changed, 48 insertions, 10 deletions

diff --git a/host/include/uhd/usrp/multi_usrp.hpp b/host/include/uhd/usrp/multi_usrp.hpp
index c11d78950..ddeb7ac73 100644
--- a/host/include/uhd/usrp/multi_usrp.hpp
+++ b/host/include/uhd/usrp/multi_usrp.hpp
@@ -1704,8 +1704,8 @@ public:
      * GPIO methods
      ******************************************************************/
 
-    /*!
-     * Enumerate gpio banks on the specified device.
+    /*! Enumerate GPIO banks on the specified device.
+     *
      * \param mboard the motherboard index 0 to M-1
      * \return a list of string for each bank name
      */
@@ -1714,15 +1714,50 @@ public:
     /*! Set a GPIO attribute on a particular GPIO bank.
      *
      * Possible attribute names:
-     *  - CTRL - 1 for ATR mode 0 for GPIO mode
-     *  - DDR - 1 for output 0 for input
+     *  - CTRL - 1 for ATR mode, 0 for GPIO mode
+     *  - DDR - 1 for output, 0 for input
      *  - OUT - GPIO output level (not ATR mode)
      *  - ATR_0X - ATR idle state
      *  - ATR_RX - ATR receive only state
      *  - ATR_TX - ATR transmit only state
      *  - ATR_XX - ATR full duplex state
+     *
+     * A note on bank names: Query get_gpio_banks() for a valid list of arguments
+     * for bank names. Note that RFNoC devices (E3xx, N3xx, X3x0, X410) behave
+     * slightly differently when using this API vs. using the
+     * radio_control::set_gpio_attr() API. For backward-compatibility reasons,
+     * this API does not have a dedicated argument to address a specific radio,
+     * although the aforementioned devices have separate GPIO banks for each
+     * radio. This API thus allows appending the slot name (typically "A" or "B")
+     * to the GPIO bank to differentiate between radios. The following example
+     * shows the difference between the RFNoC and multi_usrp APIs on a USRP N310:
+     * ~~~{.py}
+     * my_usrp = uhd.usrp.MultiUSRP("type=n3xx")
+     * print(my_usrp.get_gpio_banks()) # Will print: FP0A, FP0B
+     * # Now set all pins to GPIO for Radio 1 (note the 'B' in 'FP0B'):
+     * my_usrp.set_gpio_attr("FP0B", "CTRL", 0x000)
+     * # For backwards compatibility, you can omit the 'A', but that will default
+     * # to radio 0. The following lines thus do the same:
+     * my_usrp.set_gpio_attr("FP0", "CTRL", 0x000)
+     * my_usrp.set_gpio_attr("FP0A", "CTRL", 0x000)
+     * ### This is how you do the same thing with RFNoC API:
+     * print(my_usrp.get_radio_control(0).get_gpio_banks()) # Will print: FP0
+     * print(my_usrp.get_radio_control(1).get_gpio_banks()) # Will print: FP0
+     * # Note how the radio controller only has a single bank!
+     * # When accessing the radio directly, we thus can't specify any other bank
+     * # than FP0:
+     * my_usrp.get_radio_control(1).set_gpio_attr("FP0", "CTRL", 0x000)
+     * ~~~
+     *
+     * The \p mask argument can be used to apply \p value only to select pins,
+     * and retain the existing value on the rest. Because of this feature, this
+     * API call will incur two register transactions (one read, one write).
+     *
+     * Note that this API call alone may not be sufficient to configure the
+     * physical GPIO pins. See set_gpio_src() for more details.
+     *
      * \param bank the name of a GPIO bank
-     * \param attr the name of a GPIO attribute
+     * \param attr the name of a GPIO attribute (see list above)
      * \param value the new value for this GPIO bank
      * \param mask the bit mask to effect which pins are changed
      * \param mboard the motherboard index 0 to M-1
@@ -1734,19 +1769,22 @@ public:
         const uint32_t mask = 0xffffffff,
         const size_t mboard = 0) = 0;
 
-    /*!
-     * Get a GPIO attribute on a particular GPIO bank.
+    /*! Get a GPIO attribute on a particular GPIO bank.
+     *
      * Possible attribute names:
-     *  - CTRL - 1 for ATR mode 0 for GPIO mode
-     *  - DDR - 1 for output 0 for input
+     *  - CTRL - 1 for ATR mode, 0 for GPIO mode
+     *  - DDR - 1 for output, 0 for input
      *  - OUT - GPIO output level (not ATR mode)
      *  - ATR_0X - ATR idle state
      *  - ATR_RX - ATR receive only state
      *  - ATR_TX - ATR transmit only state
      *  - ATR_XX - ATR full duplex state
      *  - READBACK - readback input GPIOs
+     *
+     * For bank names, refer to set_gpio_attr().
+     *
      * \param bank the name of a GPIO bank
-     * \param attr the name of a GPIO attribute
+     * \param attr the name of a GPIO attribute (see list above)
      * \param mboard the motherboard index 0 to M-1
      * \return the value set for this attribute
      */