Doc: document the LINEAR16 format (implemented for VOUT in 00dc1498)

doc/source/firmware.rst

@@ -63,13 +63,14 @@ The full list of PMBus and extended commands implemented by the
 MoniMod can be found in :numref:`Tables %s <pmbus_cmds>` and
 :numref:`%s <ext_cmds>`.
 
-All physical quantities are expressed in the 16-bit PMBus Linear data
-format (:numref:`linear_fmt`), instead of the Direct format PMBus also
-supports, (which is somewhat more complex). An 11-bit mantissa (Y) and
-a 5-bit exponent (N), expressed in 2's complement, form a
-floating-point number X according to :math:`X = Y \cdot 2^N`.
+All physical quantities (except output voltage, which is discussed
+below) are expressed in the 16-bit PMBus Linear data format (LINEAR11,
+:numref:`Linear`), instead of the (somewhat more complex) Direct
+format PMBus also supports. An 11-bit mantissa (Y) and a 5-bit
+exponent (N), expressed in 2's complement, form a floating-point
+number X according to :math:`X = Y \cdot 2^N`.
 
-.. _linear_fmt:
+.. _Linear:
 
 .. figure:: figures/latex/linear.png
    :align: center
@@ -77,6 +78,17 @@ floating-point number X according to :math:`X = Y \cdot 2^N`.
 
    The PMBus Linear data format
 
+The output voltages use a different, 21-bit format, called LINEAR16
+(in contrast to the 16-bit LINEAR11, the names are derived from the
+mantissa width). This format comprises a 5-bit 2's complement
+exponent, reported by the 5 MSBs of the VOUT_MODE_ command; and a
+16-bit unsigned mantissa, reported by READ_VOUT_. Many COTS PSUs use
+LINEAR11 for everything, and this behavior is also possible using a
+compile-time switch. In the MoniMod, the exponential factor for the
+LINEAR16 format is fixed to -10, so the voltages reported can be
+obtained with :math:`X = Y \cdot 2^-10`, where Y is the 16-bit value
+returned by READ_VOUT_.
+
 .. _pmbus_cmds:
 
 .. table:: PMBus commands implemented by the MoniMod
@@ -88,6 +100,8 @@ floating-point number X according to :math:`X = Y \cdot 2^N`.
    +--------------+--------------------+------------------------+-------------+----------------------+
    |           1A | QUERY              | Block w / r proc. call |           1 | query cmd props      |
    +--------------+--------------------+------------------------+-------------+----------------------+
+   |           20 | VOUT_MODE          | Byte read              |           1 | read voltage format  |
+   +--------------+--------------------+------------------------+-------------+----------------------+
    |           3A | FAN_CONFIG_1_2     | Byte write / read      |           1 | config fans 1&2      |
    +--------------+--------------------+------------------------+-------------+----------------------+
    |           3B | FAN_COMMAND_1      | Word write / read      |           2 | set fan 1 speed      |
@@ -189,6 +203,24 @@ The QUERY command takes a command code as an argument and replies with
 information on the command: whether it is supported, if read or write
 is supported, and what data format it works with.
 
+.. _VOUT_MODE:
+
+VOUT_MODE
+~~~~~~~~~
+
+| Command code: **20**
+| Transaction type: **Byte read**
+| Data length: **1**
+
+The VOUT_MODE command reports the format the device uses for measured
+voltage related data. The 3 MSBs indicate whether that's Linear_
+(0b000), VID (0b001) or Direct (0b010), and in the Monimod's case it's
+always 0b000 for Linear format. The 5 MSBs return either 0x16, for
+LINEAR16 format used (fully PMBus-compliant operation, fixed
+:math:`2^-10` exponential); or 0x00, for LINEAR11 format used (common
+for COTS PSUs). See Linear_ for more details on the specifics of these
+formats.
+
 FAN_CONFIG_n_m
 ~~~~~~~~~~~~~~
 
@@ -242,6 +274,8 @@ The FAN_COMMAND_n commands set the desired speed of the attached
 fans. The value set is either in RPMs (when the fan is configured to
 be controlled like that) or duty cycle, in the range 0--1000.
 
+.. _READ_VOUT:
+
 READ_VOUT
 ~~~~~~~~~