To measure power on a board, the power measurement sources (be it on-board ADCs, or by using a sweetberry device) need to be properly configured. They need to be given human-readable names, and told the sense resistor sizes in addition to some other information.
This is a small introduction on how those configurations are generated, to facilitate creating new configurations.
Servo uses python to write human-readable INA configuration templates, that then generate slightly-less-but-still human readable configuration files.
There are up to 5 variables inside the configuration file needed.
inas
: A list of tuples that describe which INAs to configure. Each tuple consists of
(type, addr, name, nom, sense, location, calib)
*
type
: one of ina3221
, ina219
, ina231
, sweetberry
addr
: i2c child address (see sweetberry below for note)name
: human readable name used to control measurements laternom
: nominal voltage of power railsense
: sense resistor value in Ohmlocation
: loc string for docstring generationcalib
: True
if the rail should be configured for power measurements (usually, this means r-sense is non zero)* order matters since this is a tuple
config_type
(optional): either servod
or sweetberry
If config_type
is servod
, then a set of servod
controls for each rail will be generated, in a servod
.xml
configuration file. This file then can be sourced when starting servod. Use this configuration type for on-board INAs.
If config_type
is sweetberry
, a set of servod controls for each rail will be generated, similar to the servod
config, but specifically to use sweetberry through servod
. Additionally, a .board
and .scenario
configuration file for usage with powerlog.py
will be generated. See below for sweetberry details. Use this configuration type when creating a sweetberry config.
If config_type
is not defined, it will default to servod
.
revs
(optional): A list of integers describing what hardware revisions this configuration is valid for.
These are used to generate configurations using a standard naming scheme (see below).
interface
(optional): If the board/device does not use the standard i2c_interface (2) this can be used to overwrite this
params
(optional): If the board/device requires specific servod params to be fed into the register controls that will be generated, the user can define a dictionary that will be passed to the register control generation to define/overwrite params.
The filename of the .py
configuration template should be board_[suffix].py
.
If revs
(see above) is defined, then the output configuration files after building hdctools
will be named
board_rev[rev].[filetype]
filetype
is either .xml
or .board
/.scenario
depending on the configuration being for servod
or powerlog
usage.rev
being the revision numbers specified in the revs
variable[rev]
also matches the output from crossystem board_id
in AP consoleEach rev
in revs
produces the same configuration. For example if revs = [0,1]
then the ina generation will create board_rev0.[filetype]
- board_rev1.[filetype]
.
If revs
is not defined, then the output configuration file after building hdctools
will be named identical to its .py
template:
board_[suffix].[filetype]
The suffix
matters in cases where no revs
are defined, and it will be thrown out, when revs
are defined.
For more details, see generate_ina_controls.py
.
The output is a servod
-style .xml
control file, where the driver is ina231.py
, and a powerlog config file pair (.board
and .scenario
files). See below at servod
for the controls exposed by the .xml
file.
Sweetberry is not trivial to manually configure properly with i2c child address and the i2c port. This is due to each physical bank using multiple ports, and a child address subset. To facilitate this, on config_type='sweetberry'
one can write the .py
template also by setting:
(1,3))
j
bank: j2,j3,j4
(see marks on board)To summarize here are two equivalent rail configurations:
('ina231', (1,3), 'sample_rail_mw' , 5.0, 0.010, 'j2', False) ('ina231', '0x40:3', 'sample_rail_mw' , 5.0, 0.010, 'j2', False)
as the first line will be converted into the 2nd line in preprocessing. Same below.
('ina231', (1,3), 'sample_rail_mw' , 5.0, 0.010, 'j3', False) ('ina231', '0x44:3', 'sample_rail_mw' , 5.0, 0.010, 'j3', False)
See sweetberry for the details on banks, ports, and i2c addresses.
See servo_sweetberry_rails.py
for a full list of sweetberry controls using the i2c address space.
See servo_sweetberry_rails_pins.py
for a full list of sweetberry controls using the pin + jbank address space.
The .board
file that is a list of dictionaries, where each dictionary defines:
and a .scenario
file that lists all the inas names again, so that powerlog.py collects measurements from all of them. See powerlog.py for details.
For servod
, the output is a .xml
servod
configuration file that defines servod
controls for:
config_register
calib_register
(if available)