GPIO Straps documentation changes

Signed-off-by: Marcelo Carvalho Faleiro de Almeida <[email protected]>
lowRISC · Jan 23, 2025 · 68f85e5 · 68f85e5
1 parent a94d9f0
commit 68f85e5
Show file tree

Hide file tree

Showing 7 changed files with 76 additions and 41 deletions.
diff --git a/hw/ip/gpio/data/gpio.hjson b/hw/ip/gpio/data/gpio.hjson
@@ -111,6 +111,7 @@
       package: "",
       desc:    '''
                This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+               It can only be pulsed high one-time after reset. The following pulses will not be taken into consideration.
                ''',
       default: "1'b0"
     },
@@ -390,7 +391,14 @@
       ],
     },
     { name: "HW_STRAPS_DATA_IN",
-      desc: "GPIO Input data sampled as straps during cold boot read value",
+      desc: '''
+        GPIO input data that was sampled as straps as the block came out of reset.
+
+        This register depends on the GpioAsHwStrapsEn parameter.
+        - If the parameter is false then the register reads as zero.
+        - If the parameter is true then GPIO input data is sampled on the first cycle after reset
+          where the strap_en_i input is high. That sampled data is stored in this register.
+      ''',
       swaccess: "ro",
       hwaccess: "hrw",
       tags: [// Value in the register is determined by GPIO pin values that are sampled

diff --git a/hw/ip/gpio/doc/interfaces.md b/hw/ip/gpio/doc/interfaces.md
@@ -15,11 +15,11 @@ Referring to the [Comportable guideline for peripheral device functionality](htt
 
 ## [Inter-Module Signals](https://opentitan.org/book/doc/contributing/hw/comportability/index.html#inter-signal-handling)
 
-| Port Name      | Package::Struct       | Type    | Act   |   Width | Description                                                                                   |
-|:---------------|:----------------------|:--------|:------|--------:|:----------------------------------------------------------------------------------------------|
-| strap_en       | logic                 | uni     | rcv   |       1 | This signal is pulsed high by the power manager after reset in order to sample the HW straps. |
-| sampled_straps | gpio_pkg::gpio_straps | uni     | req   |       1 | This vector contains the sampled strap values.                                                |
-| tl             | tlul_pkg::tl          | req_rsp | rsp   |       1 |                                                                                               |
+| Port Name      | Package::Struct       | Type    | Act   |   Width | Description                                                                                                                                                                                               |
+|:---------------|:----------------------|:--------|:------|--------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| strap_en       | logic                 | uni     | rcv   |       1 | This signal is pulsed high by the power manager after reset in order to sample the HW straps. It can only be pulsed high one-time after reset. The following pulses will not be taken into consideration. |
+| sampled_straps | gpio_pkg::gpio_straps | uni     | req   |       1 | This vector contains the sampled strap values.                                                                                                                                                            |
+| tl             | tlul_pkg::tl          | req_rsp | rsp   |       1 |                                                                                                                                                                                                           |
 
 ## Interrupts
 

diff --git a/hw/ip/gpio/doc/registers.md b/hw/ip/gpio/doc/registers.md
@@ -3,26 +3,26 @@
 <!-- BEGIN CMDGEN util/regtool.py -d ./hw/ip/gpio/data/gpio.hjson -->
 ## Summary
 
-| Name                                                       | Offset   |   Length | Description                                                   |
-|:-----------------------------------------------------------|:---------|---------:|:--------------------------------------------------------------|
-| gpio.[`INTR_STATE`](#intr_state)                           | 0x0      |        4 | Interrupt State Register                                      |
-| gpio.[`INTR_ENABLE`](#intr_enable)                         | 0x4      |        4 | Interrupt Enable Register                                     |
-| gpio.[`INTR_TEST`](#intr_test)                             | 0x8      |        4 | Interrupt Test Register                                       |
-| gpio.[`ALERT_TEST`](#alert_test)                           | 0xc      |        4 | Alert Test Register                                           |
-| gpio.[`DATA_IN`](#data_in)                                 | 0x10     |        4 | GPIO Input data read value                                    |
-| gpio.[`DIRECT_OUT`](#direct_out)                           | 0x14     |        4 | GPIO direct output data write value                           |
-| gpio.[`MASKED_OUT_LOWER`](#masked_out_lower)               | 0x18     |        4 | GPIO write data lower with mask.                              |
-| gpio.[`MASKED_OUT_UPPER`](#masked_out_upper)               | 0x1c     |        4 | GPIO write data upper with mask.                              |
-| gpio.[`DIRECT_OE`](#direct_oe)                             | 0x20     |        4 | GPIO Output Enable.                                           |
-| gpio.[`MASKED_OE_LOWER`](#masked_oe_lower)                 | 0x24     |        4 | GPIO write Output Enable lower with mask.                     |
-| gpio.[`MASKED_OE_UPPER`](#masked_oe_upper)                 | 0x28     |        4 | GPIO write Output Enable upper with mask.                     |
-| gpio.[`INTR_CTRL_EN_RISING`](#intr_ctrl_en_rising)         | 0x2c     |        4 | GPIO interrupt enable for GPIO, rising edge.                  |
-| gpio.[`INTR_CTRL_EN_FALLING`](#intr_ctrl_en_falling)       | 0x30     |        4 | GPIO interrupt enable for GPIO, falling edge.                 |
-| gpio.[`INTR_CTRL_EN_LVLHIGH`](#intr_ctrl_en_lvlhigh)       | 0x34     |        4 | GPIO interrupt enable for GPIO, level high.                   |
-| gpio.[`INTR_CTRL_EN_LVLLOW`](#intr_ctrl_en_lvllow)         | 0x38     |        4 | GPIO interrupt enable for GPIO, level low.                    |
-| gpio.[`CTRL_EN_INPUT_FILTER`](#ctrl_en_input_filter)       | 0x3c     |        4 | filter enable for GPIO input bits.                            |
-| gpio.[`HW_STRAPS_DATA_IN_VALID`](#hw_straps_data_in_valid) | 0x40     |        4 | Indicates whether the data in !!HW_STRAPS_DATA_IN is valid.   |
-| gpio.[`HW_STRAPS_DATA_IN`](#hw_straps_data_in)             | 0x44     |        4 | GPIO Input data sampled as straps during cold boot read value |
+| Name                                                       | Offset   |   Length | Description                                                                |
+|:-----------------------------------------------------------|:---------|---------:|:---------------------------------------------------------------------------|
+| gpio.[`INTR_STATE`](#intr_state)                           | 0x0      |        4 | Interrupt State Register                                                   |
+| gpio.[`INTR_ENABLE`](#intr_enable)                         | 0x4      |        4 | Interrupt Enable Register                                                  |
+| gpio.[`INTR_TEST`](#intr_test)                             | 0x8      |        4 | Interrupt Test Register                                                    |
+| gpio.[`ALERT_TEST`](#alert_test)                           | 0xc      |        4 | Alert Test Register                                                        |
+| gpio.[`DATA_IN`](#data_in)                                 | 0x10     |        4 | GPIO Input data read value                                                 |
+| gpio.[`DIRECT_OUT`](#direct_out)                           | 0x14     |        4 | GPIO direct output data write value                                        |
+| gpio.[`MASKED_OUT_LOWER`](#masked_out_lower)               | 0x18     |        4 | GPIO write data lower with mask.                                           |
+| gpio.[`MASKED_OUT_UPPER`](#masked_out_upper)               | 0x1c     |        4 | GPIO write data upper with mask.                                           |
+| gpio.[`DIRECT_OE`](#direct_oe)                             | 0x20     |        4 | GPIO Output Enable.                                                        |
+| gpio.[`MASKED_OE_LOWER`](#masked_oe_lower)                 | 0x24     |        4 | GPIO write Output Enable lower with mask.                                  |
+| gpio.[`MASKED_OE_UPPER`](#masked_oe_upper)                 | 0x28     |        4 | GPIO write Output Enable upper with mask.                                  |
+| gpio.[`INTR_CTRL_EN_RISING`](#intr_ctrl_en_rising)         | 0x2c     |        4 | GPIO interrupt enable for GPIO, rising edge.                               |
+| gpio.[`INTR_CTRL_EN_FALLING`](#intr_ctrl_en_falling)       | 0x30     |        4 | GPIO interrupt enable for GPIO, falling edge.                              |
+| gpio.[`INTR_CTRL_EN_LVLHIGH`](#intr_ctrl_en_lvlhigh)       | 0x34     |        4 | GPIO interrupt enable for GPIO, level high.                                |
+| gpio.[`INTR_CTRL_EN_LVLLOW`](#intr_ctrl_en_lvllow)         | 0x38     |        4 | GPIO interrupt enable for GPIO, level low.                                 |
+| gpio.[`CTRL_EN_INPUT_FILTER`](#ctrl_en_input_filter)       | 0x3c     |        4 | filter enable for GPIO input bits.                                         |
+| gpio.[`HW_STRAPS_DATA_IN_VALID`](#hw_straps_data_in_valid) | 0x40     |        4 | Indicates whether the data in !!HW_STRAPS_DATA_IN is valid.                |
+| gpio.[`HW_STRAPS_DATA_IN`](#hw_straps_data_in)             | 0x44     |        4 | GPIO input data that was sampled as straps as the block came out of reset. |
 
 ## INTR_STATE
 Interrupt State Register
@@ -358,7 +358,12 @@ Indicates whether the data in [`HW_STRAPS_DATA_IN`](#hw_straps_data_in) is valid
 |   0    |   ro   |   0x0   | HW_STRAPS_DATA_IN_VALID |               |
 
 ## HW_STRAPS_DATA_IN
-GPIO Input data sampled as straps during cold boot read value
+GPIO input data that was sampled as straps as the block came out of reset.
+
+This register depends on the GpioAsHwStrapsEn parameter.
+- If the parameter is false then the register reads as zero.
+- If the parameter is true then GPIO input data is sampled on the first cycle after reset
+where the strap_en_i input is high. That sampled data is stored in this register.
 - Offset: `0x44`
 - Reset default: `0x0`
 - Reset mask: `0xffffffff`

diff --git a/hw/ip/gpio/doc/theory_of_operation.md b/hw/ip/gpio/doc/theory_of_operation.md
@@ -73,14 +73,12 @@ the output driver is unable to switch the pin or during the delay imposed
 if the noise filter is enabled).
 
 #### GPIO Inputs as HW Straps
-The GPIO controller also provides an additional optional feature to sample the GPIO input values as hardware configuration straps
-These input values are sampled only at initial cold boot reset deassertion and is not sampled thereafter.
-Thus any change in the input configuration information after power on reset deassertion will not be captured.
-A strap_en signal driven by the pwrmgr is used for this sampling mechanism. The strap_en pulse is a single cycle pulse of the io div4 clock
-It is expected to toggle only once at cold boot.
-
-The snapshot value of the GPIO inputs is available in the [`HW_STRAPS_DATA_IN`](../data/gpio.hjson#hw_straps_data_in) register for firmware read out
-Note that all 32 bits of input data to the GPIO controller are sampled in this mode regardless of the gpio output enable status
+
+The GPIO controller includes an optional feature to sample GPIO input values as hardware configuration straps. After the reset (cold boot), when the strap_en signal is asserted, the GPIO detects the rising edge of the signal and triggers the sampling of GPIO input values one clock cycle later. These sampled values are stored in the HW_STRAPS_DATA_IN register.
+
+The strap_en signal is driven by the power manager (pwrmgr) and is expected to toggle only once after the reset process. Sampling occurs only during this period, and subsequent changes to the GPIO input configuration will not be captured.
+
+This mechanism samples all 32 bits of the GPIO input data, regardless of the GPIO output enable status, providing a snapshot of the input values for firmware access.
 
 ### Interrupts
 

diff --git a/hw/top_darjeeling/data/autogen/top_darjeeling.gen.hjson b/hw/top_darjeeling/data/autogen/top_darjeeling.gen.hjson
@@ -646,7 +646,11 @@
       [
         {
           name: strap_en
-          desc: This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+          desc:
+            '''
+            This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+            It can only be pulsed high one-time after reset. The following pulses will not be taken into consideration.
+            '''
           struct: logic
           type: uni
           act: rcv
@@ -18342,7 +18346,11 @@
       }
       {
         name: strap_en
-        desc: This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+        desc:
+          '''
+          This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+          It can only be pulsed high one-time after reset. The following pulses will not be taken into consideration.
+          '''
         struct: logic
         type: uni
         act: rcv

diff --git a/hw/top_earlgrey/data/autogen/top_earlgrey.gen.hjson b/hw/top_earlgrey/data/autogen/top_earlgrey.gen.hjson
@@ -902,7 +902,11 @@
       [
         {
           name: strap_en
-          desc: This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+          desc:
+            '''
+            This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+            It can only be pulsed high one-time after reset. The following pulses will not be taken into consideration.
+            '''
           struct: logic
           type: uni
           act: rcv
@@ -17549,7 +17553,11 @@
       }
       {
         name: strap_en
-        desc: This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+        desc:
+          '''
+          This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+          It can only be pulsed high one-time after reset. The following pulses will not be taken into consideration.
+          '''
         struct: logic
         type: uni
         act: rcv

diff --git a/hw/top_englishbreakfast/data/autogen/top_englishbreakfast.gen.hjson b/hw/top_englishbreakfast/data/autogen/top_englishbreakfast.gen.hjson
@@ -637,7 +637,11 @@
       [
         {
           name: strap_en
-          desc: This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+          desc:
+            '''
+            This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+            It can only be pulsed high one-time after reset. The following pulses will not be taken into consideration.
+            '''
           struct: logic
           type: uni
           act: rcv
@@ -8777,7 +8781,11 @@
       }
       {
         name: strap_en
-        desc: This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+        desc:
+          '''
+          This signal is pulsed high by the power manager after reset in order to sample the HW straps.
+          It can only be pulsed high one-time after reset. The following pulses will not be taken into consideration.
+          '''
         struct: logic
         type: uni
         act: rcv