From e76700b03d84acde223f4bcdf79db764e7ed1039 Mon Sep 17 00:00:00 2001 From: Mengqi Guo Date: Fri, 10 Aug 2018 11:47:50 -0700 Subject: sweetberry: format README, clarify details Changing powerlog.README.md(orginally board.README) format to md. Adding details, making clarifications. BRANCH=None BUG=b:111318462 TEST=None Change-Id: Ic617d3da9518708560501be2786031dbd432ffe4 Signed-off-by: Mengqi Guo Reviewed-on: https://chromium-review.googlesource.com/1171503 Reviewed-by: Nick Sanders --- extra/usb_power/powerlog.README.md | 230 ++++++++++++++++++++++--------------- 1 file changed, 138 insertions(+), 92 deletions(-) (limited to 'extra') diff --git a/extra/usb_power/powerlog.README.md b/extra/usb_power/powerlog.README.md index 5ebfb382ca..a5ce379670 100644 --- a/extra/usb_power/powerlog.README.md +++ b/extra/usb_power/powerlog.README.md @@ -1,71 +1,93 @@ -Sweetberry USB power monitoring +# Sweetberry USB power monitoring This tool allows high speed monitoring of power rails via a special USB -endpoint. Currently this is implemented for the sweetberry board. +endpoint. Currently this is implemented for the Sweetberry board. -To use on a board, you'll need two config files, one describing the board, -a ".board" file, and one describing the particular rails you want to -monitor in this session, a ".scenario" file. +To use on a board, you'll need two config files, one describing the board, a +`.board` file, and one describing the particular rails you want to monitor in +this session, a `.scenario` file. +## Converting from servo_ina configs -Converting from servo_ina configs: +- Method 1 (not limited to chroot) -Method 1 - + Many configs can be found for the servo_ina_board in `hdctools/servo/data/`. + Sweetberry is plug compatible with servo_ina headers, and config files can be + converted with the following tool: -Many configs can be found for the servo_ina_board in hdctools/servo/data/. -Sweetberry is plug compatible with servo_ina headers, and config files -can be converted with the following tool: + ``` + ./convert_servo_ina.py _r0_loc.py + ``` -./convert_servo_ina.py _r0_loc.py + This will generate `_r0_loc.board` and `_r0_loc.scenario` + locally, which can be used with `powerlog.py`. -This will produce _r0_loc.board and _r0_loc.scenario which -can be used with powerlog.py. +- Method 2 (recommended for Chrome OS developers, requires chroot) -Method 2 (preferred) - + If you are using `powerlog.py` within the chroot, copy `_r0_loc.py` to + `src/third_party/hdctools/servo/data`, then add this line to file: -If you are using powerlog.py within the chroot, copy _r0_loc.py to -src/third_party/hdctools/servo/data, then add line to file: -config_type = 'sweetberry' -and run command in terminal: -sudo emerge hdctools -The command will install the corresponding .board and .scenario file in the -chroot. To use powerlog.py use the command: -./powerlog.py -b _r0_loc.board -c _r0_loc.scenario -There is no need to specify the absolute path to the .board and .scenario file, -once they are installed into the chroot. If there is any changes to -_r0_loc.py, you need to emerge hdctools again. + ```python + config_type = 'sweetberry' + ``` + And run command in chroot: -Board files: + ``` + (Anywhere in chroot, just ONCE) cros_workon --host start dev-util/hdctools + ``` + + Then every time you make a change to `_r0_loc.py`, run: + + ``` + (Anywhere in chroot) sudo emerge dev-util/hdctools + ``` + + The command will install the corresponding `.board` and `.scenario` file in + the chroot. To use `powerlog.py` use the command: + + ``` + (Anywhere in chroot) powerlog -b _r0_loc.board -c _r0_loc.scenario + ``` + + There is no need to specify the absolute path to the `.board` and `.scenario` + file, once they are installed into the chroot. If there is any changes to + `_r0_loc.py`, you need to `sudo emerge dev-util/hdctools` again. + +## Board files Board files contain a list of rails, supporting 48 channels each on up to two -sweetberries. For each rail you must specify a name, sense resistor value, -and channel number. You can optionally list expected voltage and net name. +Sweetberries. For each rail you must specify a name, sense resistor value, and +channel number. You can optionally list expected voltage and net name. The format is as follows, in json: example.board: + +```json [ { "name": "railname", "rs": , - "sweetberry": <"A" for main sweetberry, "B" for a secondary sweetberry>, + "sweetberry": <"A" for main Sweetberry, "B" for a secondary Sweetberry>, "channel": <0-47 according to board schematic>, "v": , "net": }, {...} ] +``` +## Scenario files -Scenario files: - -Scenario files contain the set of rails to monitor in this session. The -file format is simply a list of rail names from the board file. +Scenario files contain the set of rails to monitor in this session. The file +format is simply a list of rail names from the board file. Optionally, you can specify the type of measurement, from the set of -"POWER", "BUSV", "CURRENT", "SHUNTV". If not specified, the default is +`"POWER"`, `"BUSV"`, `"CURRENT"`, `"SHUNTV"`. If not specified, the default is power. example.scenario: + +```json [ "railname", "another_railname", @@ -73,95 +95,119 @@ example.scenario: ["railname", "CURRENT"], ... ] +``` +## Output -Output: - -powerlog.py will output a csv formatted log to stdout, at timing intervals -specified on the command line. Currently values below "-t 10000" do not work +`powerlog.py` will output a csv formatted log to stdout, at timing intervals +specified on the command line. Currently values below `-t 10000` do not work reliably but further updates should allow faster updating. An example run of: + +``` ./powerlog.py -b board/marlin/marlin.board -c board/marlin/marlin_short.scenario -t 100000 +``` Will result in: +``` ts:32976us, VBAT uW, VDD_MEM uW, VDD_CORE uW, VDD_GFX uW, VDD_1V8_PANEL uW 0.033004, 12207.03, 4882.81, 9155.27, 2441.41, 0.00 0.066008, 12207.03, 3662.11, 9155.27, 2441.41, 0.00 0.099012, 12207.03, 3662.11, 9155.27, 2441.41, 0.00 ... +``` The output format is as follows: -ts:32976us: Timestamps either zero based or synced to system clock, - in seconds. The column header indicates the selected - sampling interval. Since the INA231 has specific - hardware defines sampling options, this will be the - closest supported option lower than the requested "-t" - value on the command line. -VBAT uW: microwatt reading from this rail, generated on the INA - by integrating the voltage/amperage on the sense resistor - over the sampling time, and multiplying by the sampled bus - voltage. -... uW: Further microwatt entry columns for each rail specified in - your scenario file. -... xX: Measurement in uW, mW, mV, uA, uV as per config. - - -Calculate stats and store data and stats: + +- `ts:32976us` + + Timestamps either zero based or synced to system clock, in seconds. The column + header indicates the selected sampling interval. Since the INA231 has specific + hardware defines sampling options, this will be the closest supported option + lower than the requested `-t` value on the command line. + +- `VBAT uW` + + Microwatt reading from this rail, generated on the INA by integrating the + voltage/amperage on the sense resistor over the sampling time, and multiplying + by the sampled bus voltage. + +- `... uW` + + Further microwatt entry columns for each rail specified in your scenario file. + +- `... xX` + + Measurement in uW, mW, mV, uA, uV as per config. + +## Calculate stats and store data and stats When appropriate flag is set, powerlog.py is capable of calculating statistics and storing statistics and raw data. -Example 1: -./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_stats [] +- Example 1 + + ``` + ./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_stats [] + ``` + + If `` is specified, this will save stats as: + `/sweetberry/summary.txt`. + If `` does not exist, it will be created. + + If `` is not specified but the flag is set, this will save stats + under the directory which `powerlog.py` is in: + `/sweetberry/summary.txt`. + + If `--save_stats` flag is not set, stats will not be saved. -If is specified, this will save stats as: -/sweetberry/summary.txt -If does not exist, it will be created. +- Example 2 -If is not specified but the flag is set, this will save stats under -the directory which powerlog.py is in: -/sweetberry/summary.txt + ``` + ./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_raw_data [] + ``` -If --save_stats flag is not set, stats will not be saved. + If `` is specified, this will save raw data in: + `/sweetberry/raw_data/`. + If `` does not exist, it will be created. -Example 2: -./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_raw_data [] + If `` is not specified but the flag is set, this will save raw data + under the directory which `powerlog.py` is in: + `/sweetberry/raw_data/`. -If is specified, this will save raw data in: -/sweetberry/raw_data/ -If does not exist, it will be created. + If `--save_raw_data` flag is not set, raw data will not be saved. -If is not specified but the flag is set, this will save raw data -under the directory which powerlog.py is in: -/sweetberry/raw_data/ +- Example 3: -If --save_raw_data flag is not set, raw data will not be saved. + ``` + ./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_stats_json [] + ``` -Example 3: -./powerlog.py -b board/eve_dvt2_loc/eve_dvt2_loc.board -c board/eve_dvt2_loc/eve_dvt2_loc.scenario --save_stats_json [] + If `` is specified, this will save MEANS in json as: + `/sweetberry/summary.json`. + If `` does not exist, it will be created. -If is specified, this will save MEANS in json as: -/sweetberry/summary.json -If does not exist, it will be created. + If `` is not specified but the flag is set, this will save MEANS in + json under the directory which `powerlog.py` is in: + `/sweetberry/summary.json`. -If is not specified but the flag is set, this will save MEANS in -json under the directory which powerlog.py is in: -/sweetberry/summary.json + If `--save_stats` flag is not set, stats will not be saved. -If --save_stats flag is not set, stats will not be saved. + `--save_stats_json` is designed for `power_telemetry_logger` for easy reading + and writing. ---save_stats_json is designed for power_telemetry_logger for easy reading and -writing. +## Making developer changes to `powerlog.py` +`powerlog.py` is installed in chroot, and the developer can import `powerlog` or +use `powerlog` directly anywhere within chroot. Anytime the developer makes a +change to `powerlog.py`, the developer needs to re-install `powerlog.py` so that +anything that imports `powerlog` does not break. The following is how the +developer installs `powerlog.py` during development. -Making developer changes to powerlog.py: +Run command in chroot: -powerlog.py is installed in chroot, and the developer can import powerlog or use -powerlog directly anywhere within chroot. Anytime the developer makes a change -to powerlog.py, the developer needs to re-install powerlog.py so that anything -that imports powerlog does not break. The following is how the developer -installs powerlog.py during development. -Run command in the terminal: -cros_workon --host start ec-devutils # just the first time -sudo emerge ec-devutils # everytime powerlog gets changed +``` +(Anywhere in chroot, just ONCE) cros_workon --host start chromeos-base/ec-devutils +(Anywhere in chroot, every time powerlog.py is changed) sudo emerge chromeos-base/ec-devutils +``` -- cgit v1.2.1