Update docs for new power control extension

doc/sections/configuration_and_integration.adoc

@@ -105,13 +105,6 @@ Requires: <<param-EXTENSION_ZBB>>. (Since Zbb and Zbkb have a large overlap, thi
 
 Default value: 1
 
-[[param-EXTENSION_XH3B]]
-===== EXTENSION_XH3B
-
-Custom bit manipulation instructions for Hazard3: `h3.bextm` and `h3.bextmi`.
-
-Default value: 1
-
 [[param-EXTENSION_ZIFENCEI]]
 ===== EXTENSION_ZIFENCEI
 
@@ -122,6 +115,20 @@ flush the instruction prefetch queue. When the branch predictor is enabled
 
 Default value: 1
 
+[[param-EXTENSION_XH3BEXTM]]
+===== EXTENSION_XH3BEXTM
+
+Custom bit manipulation instructions for Hazard3: `h3.bextm` and `h3.bextmi`. See <<extension-xh3bextm-section>>.
+
+Default value: 1
+
+[[param-EXTENSION_XH3POWER]]
+===== EXTENSION_XH3POWER
+
+Custom power management controls for Hazard3. This adds the <<reg-msleep>> CSR, and the `h3.block` and `h3.unblock` hint instructions. See <<extension-xh3power-section>>
+
+Default value: 1
+
 ==== CSR support
 
 NOTE: the Zicsr extension is implied by any of <<param-CSR_M_MANDATORY>>, <<param-CSR_M_TRAP>>,

doc/sections/csr.adoc

@@ -681,11 +681,15 @@ Note also that this is not the same as the "rule locking bypass" bit in the ePMP
 
 Address: `0xbf0`
 
-M-mode sleep control register.
+M-mode sleep control register. Resets to all-zeroes.
 
 [cols="10h,20h,~", options="header"]
 |===
 | Bits | Name | Description
 | 31:3 | - | RES0
-| 2    | `deepsleep` | Deassert the clock request signal when entering the block or WFI state, and wait for clock acknowledge to reassert before leaving the block or WFI state.
+| 2    | `sleeponblock` | Enter the deep sleep state on a `h3.block` instruction as well as a standard `wfi`. If this bit is clear, a `h3.block` is always implemented as a simple pipeline stall.
+| 1    | `powerdown`    | Release the external power request when going to sleep. The function of this is platform-defined -- it may do nothing, it may do something simple like clock-gating the fabric, or it may be tied to some complex system-level power controller.
+
+When waking, the processor reasserts its external power-up request, and will not fetch any instructions until the request is acknowledged. This may add considerable latency to the wakeup.
+| 0   | `deepsleep` | Deassert the processor clock enable when entering the sleep state. If a clock gate is instantiated, this allows most of the processor (everything except the power state machine and the interrupt and halt input registers) to be clock gated whilst asleep, which may reduce the sleep current. This adds one cycle to the wakeup latency.
 |===

doc/sections/custom_extensions.adoc

@@ -4,11 +4,14 @@ Hazard3 implements a small number of custom extensions. All are optional: custom
 
 If any one of these extensions is enabled, the `x` bit in <<reg-misa>> is set to indicate the presence of a nonstandard extension.
 
+[[extension-xh3power-section]]
 === Xh3power: Hazard3 power management
 
 This extension adds a new M-mode CSR (<<reg-msleep>>), and two new hint instructions, `h3.block` and `h3.unblock`, in the `slt` nop-compatible custom hint space.
 
-The hints are used to allow processors to sleep until woken by other processors in a multiprocessor environment. The `msleep` CSR is used to control some of the details of the processor's WFI sleep state, to trade off sleep power consumption against wakeup latency.
+The `msleep` CSR controls how deeply the processor sleeps in the WFI sleep state. By default, a WFI is implemented as a normal pipeline stall. By configuring `msleep` appropriately, the processor can gate its own clock when asleep or, with a simple 4-phase req/ack handshake, negotiate power up/down of external hardware with an external power controller. These options can improve the sleep current at the cost of greater wakeup latency.
+
+The hints allow processors to sleep until woken by other processors in a multiprocessor environment. They are implemented on top of the standard WFI state, which means they interact in the same way with external debug, and benefit from the same deep sleep states in `msleep`.
 
 ==== h3.block
 
@@ -58,6 +61,7 @@ Example assembly macro:
 .endm
 ----
 
+[[extension-xh3bextm-section]]
 === Xh3bextm: Hazard3 bit extract multiple
 
 This is a small extension with multi-bit versions of the "bit extract" instructions from Zbs, used for extracting small, contiguous bit fields.