From 2b3592f9d97b42e7fabf4ff7256c60372b8bb810 Mon Sep 17 00:00:00 2001
From: Christos Gentsos <christos.gentsos@cern.ch>
Date: Mon, 25 Oct 2021 16:07:13 +0200
Subject: [PATCH] Doc: add in-page links to the firmware section
---
doc/source/firmware.rst | 215 +++++++++++++++++++++++++---------------
1 file changed, 137 insertions(+), 78 deletions(-)
diff --git a/doc/source/firmware.rst b/doc/source/firmware.rst
index a3ad9c4..5a3d4e8 100644
--- a/doc/source/firmware.rst
+++ b/doc/source/firmware.rst
@@ -93,92 +93,94 @@ returned by READ_VOUT_.
.. table:: PMBus commands implemented by the MoniMod
- +--------------+--------------------+------------------------+-------------+----------------------+
- | Command code | Command name | Transaction type | Data length | Description |
- +==============+====================+========================+=============+======================+
- | 00 | PAGE | Byte write / read | 1 | set get page |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 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 |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 3C | FAN_COMMAND_2 | Word write / read | 2 | set fan 2 speed |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 3D | FAN_CONFIG_3_4 | Byte write / read | 1 | config fan 3 |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 3E | FAN_COMMAND_3 | Word write / read | 2 | set fan 3 speed |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 8B | READ_VOUT | Word read | 2 | read voltage |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 8C | READ_IOUT | Word read | 2 | read current |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 8D | READ_TEMPERATURE_1 | Word read | 2 | read temp. sensor 1 |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 8E | READ_TEMPERATURE_2 | Word read | 2 | read temp. sensor 2 |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 8F | READ_TEMPERATURE_3 | Word read | 2 | read temp. sensor 3 |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 90 | READ_FAN_SPEED_1 | Word read | 2 | read fan 1 speed |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 91 | READ_FAN_SPEED_2 | Word read | 2 | read fan 2 speed |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 92 | READ_FAN_SPEED_3 | Word read | 2 | read fan 3 speed |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 96 | READ_POUT | Word read | 2 | read power |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 99 | MFR_ID | Block read | var | manufacturer ID |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 9A | MFR_MODEL | Block read | var | model |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 9B | MFR_REVISION | Block read | var | revision |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 9C | MFR_LOCATION | Block read | var | location |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 9D | MFR_DATE | Block read | var | date |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | 9E | MFR_SERIAL | Block read | var | serial number |
- +--------------+--------------------+------------------------+-------------+----------------------+
- | FF | PMBUS_COMMAND_EXT | Extended command | var | access extended cmds |
- +--------------+--------------------+------------------------+-------------+----------------------+
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | Command code | Command name | Transaction type | Data length | Description |
+ +==============+=====================+========================+=============+======================+
+ | 00 | PAGE_ | Byte write / read | 1 | set get page |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 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 |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 3C | FAN_COMMAND_2_ | Word write / read | 2 | set fan 2 speed |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 3D | FAN_CONFIG_3_4_ | Byte write / read | 1 | config fan 3 |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 3E | FAN_COMMAND_3_ | Word write / read | 2 | set fan 3 speed |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 8B | READ_VOUT_ | Word read | 2 | read voltage |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 8C | READ_IOUT_ | Word read | 2 | read current |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 8D | READ_TEMPERATURE_1_ | Word read | 2 | read temp. sensor 1 |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 8E | READ_TEMPERATURE_2_ | Word read | 2 | read temp. sensor 2 |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 8F | READ_TEMPERATURE_3_ | Word read | 2 | read temp. sensor 3 |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 90 | READ_FAN_SPEED_1_ | Word read | 2 | read fan 1 speed |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 91 | READ_FAN_SPEED_2_ | Word read | 2 | read fan 2 speed |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 92 | READ_FAN_SPEED_3_ | Word read | 2 | read fan 3 speed |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 96 | READ_POUT_ | Word read | 2 | read power |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 99 | MFR_ID_ | Block read | var | manufacturer ID |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 9A | MFR_MODEL_ | Block read | var | model |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 9B | MFR_REVISION_ | Block read | var | revision |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 9C | MFR_LOCATION_ | Block read | var | location |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 9D | MFR_DATE_ | Block read | var | date |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | 9E | MFR_SERIAL_ | Block read | var | serial number |
+ +--------------+---------------------+------------------------+-------------+----------------------+
+ | FF | PMBUS_COMMAND_EXT_ | Extended command | var | access extended cmds |
+ +--------------+---------------------+------------------------+-------------+----------------------+
.. _ext_cmds:
.. table:: Extended commands implemented by the MoniMod
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | Command code | Command name | Transaction type | Data length | Description |
- +==============+===================+========================+=============+===============================+
- | 01 | WRITTEN_FW_SIZE | Word write | 2 | size of the FW to be written |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | 02 | WRITTEN_FW_BLOCK | MultiByte write | 8 | FW block to be written |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | 03 | WRITTEN_FW_CHKSUM | Word write | 2 | checksum of the written FW |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | 05 | BOOT_NEW_FW | Byte write | 1 | turn on btldr pgm mode, reset |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | 06 | UC_RESET | Byte write | 1 | reset the uC |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | 10 | UPTIME_SECS | Word read | 4 | get the uptime in seconds |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | A0 | TMR_ERROR_CNT | Word read | 4 | get TMR error count |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | B0 | USE_PEC | Byte write / read | 1 | turn PEC on / off |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | C0 | TEMP_CURVE_POINTS | MultiByte write / read | 13 | set / get temp. curve points |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | C1 | TEMP_MATRIX_ROW | MultiByte write / read | 7 | set / get temp. matrix points |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
- | C4 | TC_ONOFF | Byte write / read | 1 | turn temp. control on / off |
- +--------------+-------------------+------------------------+-------------+-------------------------------+
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | Command code | Command name | Transaction type | Data length | Description |
+ +==============+====================+========================+=============+===============================+
+ | 01 | WRITTEN_FW_SIZE_ | Word write | 2 | size of the FW to be written |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | 02 | WRITTEN_FW_BLOCK_ | MultiByte write | 8 | FW block to be written |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | 03 | WRITTEN_FW_CHKSUM_ | Word write | 2 | checksum of the written FW |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | 05 | BOOT_NEW_FW_ | Byte write | 1 | turn on btldr pgm mode, reset |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | 06 | UC_RESET_ | Byte write | 1 | reset the uC |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | 10 | UPTIME_SECS_ | Word read | 4 | get the uptime in seconds |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | A0 | TMR_ERROR_CNT_ | Word read | 4 | get TMR error count |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | B0 | USE_PEC_ | Byte write / read | 1 | turn PEC on / off |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | C0 | TEMP_CURVE_POINTS_ | MultiByte write / read | 13 | set / get temp. curve points |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | C1 | TEMP_MATRIX_ROW_ | MultiByte write / read | 7 | set / get temp. matrix points |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
+ | C4 | TC_ONOFF_ | Byte write / read | 1 | turn temp. control on / off |
+ +--------------+--------------------+------------------------+-------------+-------------------------------+
Detailed list of PMBus and extended commands
--------------------------------------------
+.. _PAGE:
+
PAGE
~~~~
@@ -186,12 +188,14 @@ PAGE
| Transaction type: **Byte write / read**
| Data length: **1**
-The PAGE command is used to select a power rail for the READ_VOUT,
-READ_IOUT and READ_POUT commands. Allowed values for the page
+The PAGE command is used to select a power rail for the READ_VOUT_,
+READ_IOUT_ and READ_POUT_ commands. Allowed values for the page
parameter are :math:`0 \leq N \leq 3` for the DI/OT Rad-Tol System
Board revision and :math:`0 \leq N \leq 2` for the fan-tray, RaToPUS
and generic prototype revisions.
+.. _QUERY:
+
QUERY
~~~~~
@@ -221,6 +225,9 @@ LINEAR16 format used (fully PMBus-compliant operation, fixed
for COTS PSUs). See Linear_ for more details on the specifics of these
formats.
+.. _FAN_CONFIG_1_2:
+.. _FAN_CONFIG_3_4:
+
FAN_CONFIG_n_m
~~~~~~~~~~~~~~
@@ -263,6 +270,10 @@ correspond to 1--4 pulses per revolution.
+--------+-----------+-----------------------------------+
+.. _FAN_COMMAND_1:
+.. _FAN_COMMAND_2:
+.. _FAN_COMMAND_3:
+
FAN_COMMAND_n
~~~~~~~~~~~~~
@@ -287,6 +298,8 @@ The READ_VOUT command is used to get the measured voltage of the rail
indicated by the last PAGE command (by default that would be the first
one).
+.. _READ_IOUT:
+
READ_IOUT
~~~~~~~~~
@@ -298,6 +311,10 @@ The READ_IOUT command is used to get the measured current of the rail
indicated by the last PAGE command (by default that would be the first
one).
+.. _READ_TEMPERATURE_1:
+.. _READ_TEMPERATURE_2:
+.. _READ_TEMPERATURE_3:
+
READ_TEMPERATURE_N
~~~~~~~~~~~~~~~~~~
@@ -308,6 +325,10 @@ READ_TEMPERATURE_N
The READ_TEMPERATURE_n commands return the measured temperature from
the three installed temperature sensors.
+.. _READ_FAN_SPEED_1:
+.. _READ_FAN_SPEED_2:
+.. _READ_FAN_SPEED_3:
+
READ_FAN_SPEED_N
~~~~~~~~~~~~~~~~
@@ -318,6 +339,8 @@ READ_FAN_SPEED_N
The READ_FAN_SPEED_n return the fan speed of an installed fan, or 0 in
case no fan is installed in the pertinent location.
+.. _READ_POUT:
+
READ_POUT
~~~~~~~~~
@@ -329,6 +352,8 @@ The READ_POUT command is used to get the measured power of the rail
indicated by the last PAGE command (by default that would be the first
one).
+.. _MFR_ID:
+
MFR_ID
~~~~~~
@@ -338,6 +363,8 @@ MFR_ID
This returns the manufacturer ID string, "CERN (BE/CO)".
+.. _MFR_MODEL:
+
MFR_MODEL
~~~~~~~~~
@@ -347,6 +374,8 @@ MFR_MODEL
This returns the manufacturer model string, "DI/OT MoniMod".
+.. _MFR_REVISION:
+
MFR_REVISION
~~~~~~~~~~~~
@@ -356,6 +385,8 @@ MFR_REVISION
This returns the manufacturer revision string.
+.. _MFR_LOCATION:
+
MFR_LOCATION
~~~~~~~~~~~~
@@ -365,6 +396,8 @@ MFR_LOCATION
This returns the manufacturer ID string, "Geneva".
+.. _MFR_DATE:
+
MFR_DATE
~~~~~~~~
@@ -375,6 +408,8 @@ MFR_DATE
This returns the manufacturer date string, which currently corresponds
to the date of the last release (and not the build used, for example).
+.. _MFR_SERIAL:
+
MFR_SERIAL
~~~~~~~~~~
@@ -385,6 +420,8 @@ MFR_SERIAL
This returns a manufacturer serial string (currently unused, returns
"123456789").
+.. _PMBUS_COMMAND_EXT:
+
PMBUS_COMMAND_EXT
~~~~~~~~~~~~~~~~~
@@ -397,6 +434,8 @@ PMBUS_COMMAND_EXT is used: the command code of the extended command is
passed as the next data byte and the rest of the transaction continues
like a regular command.
+.. _WRITTEN_FW_SIZE:
+
(ext.) WRITTEN_FW_SIZE
~~~~~~~~~~~~~~~~~~~~~~
@@ -407,6 +446,8 @@ like a regular command.
Before writing a new FW binary through the bootloader, its size in
bytes has to be given using this command.
+.. _WRITTEN_FW_BLOCK:
+
(ext.) WRITTEN_FW_BLOCK
~~~~~~~~~~~~~~~~~~~~~~~
@@ -417,6 +458,8 @@ bytes has to be given using this command.
A new binary is written to the bootloader in consecutive chunks of 8
bytes, using this command.
+.. _WRITTEN_FW_CHKSUM:
+
(ext.) WRITTEN_FW_CHKSUM
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -429,6 +472,8 @@ writing it with the WRITTEN_FW_BLOCK command, its SYS-V checksum
should be checked with this command. This command also resets the
write pointers.
+.. _BOOT_NEW_FW:
+
(ext.) BOOT_NEW_FW
~~~~~~~~~~~~~~~~~~
@@ -442,6 +487,8 @@ to PMBus mode, supporting extended commands. When already in
bootloader mode, this clears the special code and boots to the main
FW, instead.
+.. _UC_RESET:
+
(ext.) UC_RESET
~~~~~~~~~~~~~~~
@@ -451,6 +498,8 @@ FW, instead.
Writing any byte to this command triggers a uC reset.
+.. _UPTIME_SECS:
+
(ext.) UPTIME_SECS
~~~~~~~~~~~~~~~
@@ -460,6 +509,8 @@ Writing any byte to this command triggers a uC reset.
Get the uptime of the MoniMod (in seconds).
+.. _TMR_ERROR_CNT:
+
(ext.) TMR_ERROR_CNT
~~~~~~~~~~~~~~~~~~~~
@@ -471,6 +522,8 @@ When software mitigation through COAST is enabled (see
:ref:`coast_sec`), one can access the TMR_ERROR_CNT counter using
this command.
+.. _USE_PEC:
+
(ext.) USE_PEC
~~~~~~~~~~~~~~
@@ -484,6 +537,8 @@ disables PEC; any non-zero value enables it. The command itself is
used without a PEC byte appended, no matter whether the function is
enabled or not.
+.. _TEMP_CURVE_POINTS:
+
(ext.) TEMP_CURVE_POINTS
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -503,6 +558,8 @@ curve can be set separately for each fan. To do this, the format in
Temperature curve data frame
+.. _TEMP_MATRIX_ROW:
+
(ext.) TEMP_MATRIX_ROW
~~~~~~~~~~~~~~~~~~~~~~
@@ -522,6 +579,8 @@ operation is illustrated in :numref:`temp_matrix_fmt`.
Temperature matrix data frame
+.. _TC_ONOFF:
+
(ext.) TC_ONOFF
~~~~~~~~~~~~~~~
--
GitLab