Skip to content
Snippets Groups Projects
Commit 6ab0ebab authored by Christos Gentsos's avatar Christos Gentsos
Browse files

Doc: add detailed command documentation

parent fc3a5906
No related branches found
Tags v1_proto
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/source/figures/latex/temp_curve_format.png 0 → 100644
+ 0
− 0
View file @ 6ab0ebab
doc/source/figures/latex/temp_curve_format.png

10.4 KiB

doc/source/figures/latex/temp_curve_format.tex 0 → 100644
+ 59
− 0
View file @ 6ab0ebab
\documentclass[border={.5 .5 .5 2mm}]{standalone}
\usepackage{graphicx}
\usepackage[usenames,dvipsnames,svgnames,table]{xcolor}
\usepackage{libertine}
\usepackage[endianness=big]{bytefield}
\usepackage{rotating}
\usepackage[none]{hyphenat}
\definecolor{light-gray}{gray}{0.93}
\definecolor{light-green}{rgb}{0.9,1.0,0.9}
\newcommand{\colorbitbox}[3]{%
\rlap{\bitbox{#2}{\color{#1}\rule{\width}{\height}}}%
\bitbox{#2}{#3}}
\newlength{\maxheight}\setlength{\maxheight}{\heightof{W}}
\newcommand{\baselinealign}[1]{%
\centering\raisebox{0pt}[\maxheight][0pt]{#1}}
\newcommand{\bitlabel}[2]{%
\bitbox[]{#1}{%
\raisebox{-7pt}[4ex][0pt]{%
\turnbox{45}{\fontsize{5}{5}\selectfont#2}}}}
\begin{document}
\begin{bytefield}[boxformatting=\baselinealign]{3}
\bitbox[]{3}{0}%
\bitbox[]{3}{1}%
\bitbox[]{3}{2}%
\bitbox[]{3}{3}%
\bitbox[]{3}{4}%
\bitbox[]{3}{5}%
\bitbox[]{3}{6}%
\bitbox[]{3}{7}%
\bitbox[]{3}{8}%
\bitbox[]{3}{9}%
\bitbox[]{3}{10}%
\bitbox[]{3}{11}%
\bitbox[]{3}{12}\\
\wordbox{1}{FAN\textsubscript{N}}%
\wordbox{1}{T\textsubscript{0,L}}%
\wordbox{1}{T\textsubscript{0,H}}%
\wordbox{1}{S\textsubscript{0,L}}%
\wordbox{1}{S\textsubscript{0,H}}%
\wordbox{1}{T\textsubscript{1,L}}%
\wordbox{1}{T\textsubscript{1,H}}%
\wordbox{1}{S\textsubscript{1,L}}%
\wordbox{1}{S\textsubscript{1,H}}%
\wordbox{1}{T\textsubscript{2,L}}%
\wordbox{1}{T\textsubscript{2,H}}%
\wordbox{1}{S\textsubscript{2,L}}%
\wordbox{1}{S\textsubscript{2,H}}%
\end{bytefield}
\end{document}
doc/source/figures/latex/temp_matrix_format.png 0 → 100644
+ 0
− 0
View file @ 6ab0ebab
doc/source/figures/latex/temp_matrix_format.png

8 KiB

doc/source/figures/latex/temp_matrix_format.tex 0 → 100644
+ 47
− 0
View file @ 6ab0ebab
\documentclass[border={.5 .5 .5 2mm}]{standalone}
\usepackage{graphicx}
\usepackage[usenames,dvipsnames,svgnames,table]{xcolor}
\usepackage{libertine}
\usepackage[endianness=big]{bytefield}
\usepackage{rotating}
\usepackage[none]{hyphenat}
\definecolor{light-gray}{gray}{0.93}
\definecolor{light-green}{rgb}{0.9,1.0,0.9}
\newcommand{\colorbitbox}[3]{%
\rlap{\bitbox{#2}{\color{#1}\rule{\width}{\height}}}%
\bitbox{#2}{#3}}
\newlength{\maxheight}\setlength{\maxheight}{\heightof{W}}
\newcommand{\baselinealign}[1]{%
\centering\raisebox{0pt}[\maxheight][0pt]{#1}}
\newcommand{\bitlabel}[2]{%
\bitbox[]{#1}{%
\raisebox{-7pt}[4ex][0pt]{%
\turnbox{45}{\fontsize{5}{5}\selectfont#2}}}}
\begin{document}
\begin{bytefield}[boxformatting=\baselinealign]{3}
\bitbox[]{3}{0}%
\bitbox[]{3}{1}%
\bitbox[]{3}{2}%
\bitbox[]{3}{3}%
\bitbox[]{3}{4}%
\bitbox[]{3}{5}%
\bitbox[]{3}{6}\\
\wordbox{1}{FAN\textsubscript{N}}%
\wordbox{1}{m\textsubscript{0N,L}}%
\wordbox{1}{m\textsubscript{0N,H}}%
\wordbox{1}{m\textsubscript{1N,L}}%
\wordbox{1}{m\textsubscript{1N,H}}%
\wordbox{1}{m\textsubscript{2N,L}}%
\wordbox{1}{m\textsubscript{2N,H}}%
\end{bytefield}
\end{document}
doc/source/firmware.rst
+ 166
− 43
View file @ 6ab0ebab
......@@ -73,7 +73,7 @@ floating-point number X according to :math:`X = Y \cdot 2^N`.
.. figure:: figures/latex/linear.png
:align: center
:width: 35%
:scale: 50%
The PMBus Linear data format
......@@ -135,23 +135,29 @@ floating-point number X according to :math:`X = Y \cdot 2^N`.
.. table:: Extended commands implemented by the MoniMod
+--------------+-------------------+--------------------+-------------+-------------------------------+
| Command code | Command name | Transaction type | Data length | Description |
+==============+===================+====================+=============+===============================+
| 05 | BOOT_NEW_FW | Byte write | 1 | turn on btldr pgm mode, reset |
+--------------+-------------------+--------------------+-------------+-------------------------------+
| 06 | UC_RESET | Byte write | 1 | reset the uC |
+--------------+-------------------+--------------------+-------------+-------------------------------+
| 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 | Block write / read | 13 | set / get temp. curve points |
+--------------+-------------------+--------------------+-------------+-------------------------------+
| C1 | TEMP_MATRIX_ROW | Block 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 |
+--------------+-------------------+------------------------+-------------+-------------------------------+
| A0 | TMR_ERROR_CNT | MultiByte 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
......@@ -164,7 +170,9 @@ PAGE
| Transaction type: **Byte write / read**
| Data length: **1**
PAGE description.
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 2`.
QUERY
~~~~~
......@@ -173,7 +181,9 @@ QUERY
| Transaction type: **Block w / r proc. call**
| Data length: **1**
QUERY description.
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.
FAN_CONFIG_n_m
~~~~~~~~~~~~~~
......@@ -182,7 +192,40 @@ FAN_CONFIG_n_m
| Transaction type: **Byte write / read**
| Data length: **1**
FAN_CONFIG_1_2 and FAN_CONFIG_3_4 description.
The FAN_CONFIG_1_2 and FAN_CONFIG_3_4 commands are used to configure
the fans at positions 1, 2, and 3. The format of the configuration
byte can be seen in :numref:`fan_config_cmd`. The two bits that set
the tachometer pulses / revolution, which take the values 0--3,
correspond to 1--4 pulses per revolution.
.. _fan_config_cmd:
.. table:: FAN_CONFIG_1_2 and FAN_CONFIG_3_4 data byte format
+--------+-----------+-----------------------------------+
| Bit(s) | Value | Meaning |
+--------+-----------+-----------------------------------+
| 7 | 1 | Fan 1 / 3 installed |
+ +-----------+-----------------------------------+
| | 0 | Fan 1 / 3 not installed |
+--------+-----------+-----------------------------------+
| 6 | 1 | Fan 1 / 3 commanded in RPM |
+ +-----------+-----------------------------------+
| | 0 | Fan 1 / 3 commanded in duty cycle |
+--------+-----------+-----------------------------------+
| 5:4 | 0--3 | Fan 1 / 3 tachometer pulses / rev |
+--------+-----------+-----------------------------------+
| 3 | 1 | Fan 2 installed |
+ +-----------+-----------------------------------+
| | 0 | Fan 2 not installed |
+--------+-----------+-----------------------------------+
| 2 | 1 | Fan 2 commanded in RPM |
+ +-----------+-----------------------------------+
| | 0 | Fan 2 commanded in duty cycle |
+--------+-----------+-----------------------------------+
| 1:0 | 0--3 | Fan 2 tachometer pulses / rev |
+--------+-----------+-----------------------------------+
FAN_COMMAND_n
~~~~~~~~~~~~~
......@@ -191,7 +234,9 @@ FAN_COMMAND_n
| Transaction type: **Word write / read**
| Data length: **2**
FAN_COMMAND_1, FAN_COMMAND_2, and FAN_COMMAND_3 description.
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
~~~~~~~~~
......@@ -200,7 +245,9 @@ READ_VOUT
| Transaction type: **Word read**
| Data length: **2**
READ_VOUT description.
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
~~~~~~~~~
......@@ -209,7 +256,9 @@ READ_IOUT
| Transaction type: **Word read**
| Data length: **2**
READ_IOUT description.
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_N
~~~~~~~~~~~~~~~~~~
......@@ -218,8 +267,8 @@ READ_TEMPERATURE_N
| Transaction type: **Word read**
| Data length: **2**
READ_TEMPERATURE_1, READ_TEMPERATURE_2, READ_TEMPERATURE_3
description.
The READ_TEMPERATURE_n commands return the measured temperature from
the three installed temperature sensors.
READ_FAN_SPEED_N
~~~~~~~~~~~~~~~~
......@@ -228,8 +277,8 @@ READ_FAN_SPEED_N
| Transaction type: **Word read**
| Data length: **2**
READ_FAN_SPEED_1, READ_FAN_SPEED_2, READ_FAN_SPEED_3
description.
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
~~~~~~~~~
......@@ -238,7 +287,9 @@ READ_POUT
| Transaction type: **Word read**
| Data length: **2**
READ_POUT description.
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
~~~~~~
......@@ -247,7 +298,7 @@ MFR_ID
| Transaction type: **Block read**
| Data length: **var**
MFR_ID description.
This returns the manufacturer ID string, "CERN (BE/CO)".
MFR_MODEL
~~~~~~~~~
......@@ -256,7 +307,7 @@ MFR_MODEL
| Transaction type: **Block read**
| Data length: **var**
MFR_MODEL description.
This returns the manufacturer model string, "DI/OT MoniMod".
MFR_REVISION
~~~~~~~~~~~~
......@@ -265,7 +316,7 @@ MFR_REVISION
| Transaction type: **Block read**
| Data length: **var**
MFR_REVISION description.
This returns the manufacturer revision string.
MFR_LOCATION
~~~~~~~~~~~~
......@@ -274,7 +325,7 @@ MFR_LOCATION
| Transaction type: **Block read**
| Data length: **var**
MFR_LOCATION description.
This returns the manufacturer ID string, "Geneva".
MFR_DATE
~~~~~~~~
......@@ -283,7 +334,8 @@ MFR_DATE
| Transaction type: **Block read**
| Data length: **var**
MFR_DATE description.
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
~~~~~~~~~~
......@@ -292,7 +344,8 @@ MFR_SERIAL
| Transaction type: **Block read**
| Data length: **var**
MFR_SERIAL description.
This returns a manufacturer serial string (currently unused, returns
"123456789").
PMBUS_COMMAND_EXT
~~~~~~~~~~~~~~~~~
......@@ -301,7 +354,42 @@ PMBUS_COMMAND_EXT
| Transaction type: **Extended command**
| Data length: **var**
PMBUS_COMMAND_EXT description.
To access the extended commands, described below, the
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.
(ext.) WRITTEN_FW_SIZE
~~~~~~~~~~~~~~~~~~~~~~
| Ext. Command code: **01**
| Transaction type: **Word write**
| Data length: **2**
Before writing a new FW binary through the bootloader, its size in
bytes has to be given using this command.
(ext.) WRITTEN_FW_BLOCK
~~~~~~~~~~~~~~~~~~~~~~~
| Ext. Command code: **02**
| Transaction type: **MultiByte write**
| Data length: **8**
A new binary is written to the bootloader in consecutive chunks of 8
bytes, using this command.
(ext.) WRITTEN_FW_CHKSUM
~~~~~~~~~~~~~~~~~~~~~~~~
| Ext. Command code: **03**
| Transaction type: **Word write**
| Data length: **2**
After setting the size of the FW binary with WRITTEN_FW_SIZE and
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.
(ext.) BOOT_NEW_FW
~~~~~~~~~~~~~~~~~~
......@@ -310,7 +398,11 @@ PMBUS_COMMAND_EXT description.
| Transaction type: **Byte write**
| Data length: **1**
BOOT_NEW_FW description.
The BOOT_NEW_FW command passes execution to the bootloader. A special
code is written to the flash memory to direct the bootloader to switch
to PMBus mode, supporting extended commands. When already in
bootloader mode, this clears the special code and boots to the main
FW, instead.
(ext.) UC_RESET
~~~~~~~~~~~~~~~
......@@ -319,7 +411,7 @@ BOOT_NEW_FW description.
| Transaction type: **Byte write**
| Data length: **1**
UC_RESET description.
Writing any byte to this command triggers a uC reset.
(ext.) TMR_ERROR_CNT
~~~~~~~~~~~~~~~~~~~~
......@@ -328,7 +420,9 @@ UC_RESET description.
| Transaction type: **Word read**
| Data length: **4**
TMR_ERROR_CNT description.
When software mitigation through COAST is enabled (see
:numref:`coast_sec`), one can access the TMR_ERROR_CNT counter using
this command.
(ext.) USE_PEC
~~~~~~~~~~~~~~
......@@ -337,7 +431,11 @@ TMR_ERROR_CNT description.
| Transaction type: **Byte write / read**
| Data length: **1**
USE_PEC description.
The SMBus specification indicates that a device's PEC support could be
enabled or disabled at will. Using this command with a zero byte
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.
(ext.) TEMP_CURVE_POINTS
~~~~~~~~~~~~~~~~~~~~~~~~
......@@ -346,7 +444,17 @@ USE_PEC description.
| Transaction type: **Block write / read**
| Data length: **13**
TEMP_CURVE_POINTS description.
As described in the :ref:`temp_control_sec` section, the temperature
curve can be set separately for each fan. To do this, the format in
:numref:`temp_curve_fmt` has to be used.
.. _temp_curve_fmt:
.. figure:: figures/latex/temp_curve_format.png
:align: center
:scale: 33%
Temperature curve data frame
(ext.) TEMP_MATRIX_ROW
~~~~~~~~~~~~~~~~~~~~~~
......@@ -355,7 +463,17 @@ TEMP_CURVE_POINTS description.
| Transaction type: **Block write / read**
| Data length: **7**
TEMP_MATRIX_ROW description.
As described in the :ref:`temp_control_sec` section, the temperature
matrix can be set separately for each fan. The data format for the
operation is illustrated in :numref:`temp_matrix_fmt`.
.. _temp_matrix_fmt:
.. figure:: figures/latex/temp_matrix_format.png
:align: center
:scale: 33%
Temperature matrix data frame
(ext.) TC_ONOFF
~~~~~~~~~~~~~~~
......@@ -364,7 +482,8 @@ TEMP_MATRIX_ROW description.
| Transaction type: **Byte write / read**
| Data length: **1**
TC_ONOFF description.
Using the TC_ONOFF command with a zero argument disables Temperature
Control, while any non-zero value enables it.
Fan control PID
......@@ -385,6 +504,8 @@ be called every timestep is described below:
.. doxygenfunction:: pid_compute
.. _temp_control_sec:
Temperature control
-------------------
......@@ -439,6 +560,8 @@ communication, some measures have been taken to minimize interruptions
and data corruption, leading to an improved QoS.
.. _coast_sec:
TMR using COAST
~~~~~~~~~~~~~~~
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment