WULT-START(1)

💖 START(1) — wult start 💖

okay bestie, welcome to the wult start page — this is the main character of the whole wult situation, no cap. The manual name is START, and this is the wult start command. Let's get into it 🫶

✨ SYNOPSIS ✨

usage: wult start [-h] [-q] [-d] [-H HOSTNAME] [-U USERNAME] [-K
       PRIVKEY] [-T TIMEOUT] [-c COUNT] [--time-limit LIMIT] [--exclude
       EXCLUDE] [--include INCLUDE] [--keep-filtered] [-o OUTDIR] [--reportid
       REPORTID] [--stats STATS] [--stats-intervals STATS_INTERVALS]
       [--list-stats] [-l LDIST] [--cpu CPU] [--tsc-cal-time TSC_CAL_TIME]
       [--keep-raw-data] [--no-unload] [--report] [--force] [--freq-noise
       FREQ_NOISE] [--freq-noise-sleep FREQ_NOISE_SLEEP] devid

🌸 DESCRIPTION 🌸

Start measuring and recording C-state latency. That's literally the whole vibe — you run this, it does the latency measurements, and it writes everything down for you. Obsessed. 💅

🎀 ARGUMENTS 🎀

• devid — the ID of the device you're using to measure the latency, bestie. For example, it can be a PCI address of the Intel I210 device, or "tdt" for the TSC deadline timer block of the CPU. Not sure which devices you even have?? Run the scan command to get supported devices. Slay. ✨

🧚 that's the end of part 1 — more parts are coming, don't go anywhere 💖

💅 OPTIONS 'wult start' 💅

okay bestie, buckle up, this is the part where we go through EVERY single flag. yes, all of them. no skipping. 🫶

• -h — shows you this very help message and then dips out. that's it, that's the flag. ✨
• -q — be quiet. 🤫 like, no chatter.
• -d — print debugging info. for when you're nosy (affectionately). 🐛
• -H HOSTNAME, --host HOSTNAME — the name of the host you want the command to run on. 🌐
• -U USERNAME, --username USERNAME — the username you'll log into the remote host with over SSH. the default user name is root. 👑
• -K PRIVKEY, --priv-key PRIVKEY — path to the private SSH key used to log into the remote host. by default the key is automatically found from standard paths like ~/.ssh. 🔑✨
• -T TIMEOUT, --timeout TIMEOUT — SSH connect timeout, in seconds. default is 8. ⏱️
• -c COUNT, --datapoints COUNT — how many datapoints the test result should include. default is 1000000. heads up though: unless you use the --start-over option, the pre-existing datapoints are taken into account. "For example, if the test result already has 6000 datapoints and memory." 📊
• --time-limit LIMIT — the measurement time limit, aka how long the SUT should be measured for. the default unit is minute, but you can use the following handy specifiers as well: d - days, h - hours, m - minutes, s -seconds. so like 1h25m would be 1 hour and 25 minutes, or 10m5s would be 10 minutes and 5 seconds. the value 0 means "no time limit", and that is the default. and if you use this option along with the --datapoints option, then measurements will stop as when either the time limit is reached, or the required amount of datapoints is collected. ⏳
• --exclude EXCLUDE — datapoints to exclude: removes all the datapoints satisfying the expression EXCLUDE. here's an example expression: (WakeLatency < 10000) | (PC6% < 1). this filter expression will remove all datapoints with WakeLatency smaller than 10000 nanoseconds or package C6 residency smaller than 1%. you can use any metrics in the expression. 🚫✨
• --include INCLUDE — datapoints to include: removes all datapoints except the ones satisfying the expression INCLUDE. in other words, this option is the inverse of --exclude. meaning --include expr is the same as --exclude "not (expr)". 🎀
• --keep-filtered — if the --exclude / --include options are used, then the datapoints not matching the selector or matching the filter are discarded. that's the default behavior, and this option changes it. if --keep-filtered has been specified, then all datapoints are saved in result. here's an example: suppose you want to collect 100000 datapoints where PC6 residency is greater than 0. in that case you can use these options: -c 100000 --exclude="PC6% == 0". the result will contain 100000 datapoints, all of them with non-zero PC6 residency. but what if you don't want to simply discard the other datapoints, because they're also interesting? well, add the --keep-filtered option. the result will contain, say, 150000 datapoints, 100000 of which will have non-zero PC6 residency. 🧚💖
• -o OUTDIR, --outdir OUTDIR — path to the directory where the results get stored. 📁
• --reportid REPORTID — any string that can serve as an identifier of this run. by default the report ID is the current date, prefixed with the remote host name in case the -H option was used: [hostname-]YYYYMMDD. for example, "20150323" is a report ID for a run made on March 23, 2015. the allowed characters are: ACSII alphanumeric, -, ., ,, _, ~, and :. 🏷️
• --stats STATS — comma-separated list of statistics to collect. the statistics are collected in parallel with measuring C-state latency, and they're stored in the the "stats" sub-directory of the output directory. by default, only turbostat, sysinfo statistics are collected. use all to collect all possible statistics. use --stats="" or --stats="none" to disable statistics collection. if you know exactly what statistics you need, specify the comma-separated list of statistics to collect — for example, use turbostat,acpower if you need only turbostat and AC power meter statistics. you can also specify the statistics you do not want collected by pre-pending the ! symbol: for example, all,!turbostat would mean collect all the statistics supported by the SUT, except for turbostat. use the --list-stats option to get more information about available statistics. 📈
• --stats-intervals STATS_INTERVALS — the intervals for statistics. statistics collection is based on doing periodic snapshots of data. for example, by default the acpower statistics collector reads SUT power consumption for the last second every second, and turbostat default interval is 5 seconds. use acpower:5,turbostat:10 to increase the intervals to 5 and 10 seconds correspondingly. use the --list-stats to get the default interval values. ⏲️
• --list-stats — prints information about the statistics wult can collect, and exits. 🖨️✨
• -l LDIST, --ldist LDIST — this tool works by scheduling a delayed event, then sleeping and waiting for it to happen. this step is referred to as a "measurement cycle" and it's usually repeated many times. the launch distance defines how far in the future the delayed event is scheduled. by default this tool randomly selects launch distance within a range. the default range is [0,4ms], but you can override it with this option. specify a comma-separated range (e.g --ldist 10,5000), or a single value if you want the launch distance to be precisely that value all the time. the default unit is microseconds, but you can use the following specifiers as well: ms - milliseconds, us - microseconds, ns - nanoseconds. for example, --ldist 10us,5ms would be a [10,5000] microseconds range. too small values may cause failures or prevent the SUT from reaching deep C-states. if the range starts with 0, the minimum possible launch distance value allowed by the delayed event source will be used. the optimal launch distance range is system-specific. 🚀
• --cpu CPU — the logical CPU number to measure, default is CPU 0. 🧠
• --tsc-cal-time TSC_CAL_TIME — wult receives raw datapoints from the driver, then processes them, and then saves the processed datapoint in the datapoints.csv file. the processing involves converting TSC cycles to microseconds, so wult needs the SUT's TSC rate. TSC rate is calculated from the datapoints, which come with TSC counters and timestamps, so TSC rate can be calculated as "delta TSC / delta timestamp". in other words, wult needs two datapoints to calculate TSC rate. however, the datapoints have to be far enough apart, and this option defines the distance between the datapoints (in seconds). the default distance is 10 seconds, which means that wult will keep collecting and buffering datapoints for 10s without processing them (because processing requires TSC rate to be known). after 10s, wult will start processing all the buffered datapoints, and then the newly collected datapoints. generally, longer TSC calculation time translates to better accuracy. ⏰🔬
• --keep-raw-data — wult receives raw datapoints from the driver, then processes them, and then saves the processed datapoint in the datapoints.csv file. in order to keep the CSV file smaller, wult keeps only the essential information, and drops the rest — for example, raw timestamps are dropped. with this option, however, wult saves all the raw data to the CSV file, along with the processed data. 💾
• --no-unload — this option exists for debugging and troubleshooting purposes. please, do not use for other reasons. if wult loads kernel modules, they get unloaded after the measurements are done. but with this option wult will not unload the modules. 🙈
• --report — generate an HTML report for collected results (same as calling report command with default arguments). 📄✨
• --force — by default a network card is not accepted as a measurement device if it is used by a Linux network interface and the interface is in an active state, such as "up". use --force to disable this safety mechanism.

use it with caution. ⚠️

• --freq-noise FREQ_NOISE — add frequency scaling noise to the measured system. this runs a background process that repeatedly modifies CPU or uncore frequencies for given domains. the reason for doing this is because frequency scaling is generally an expensive operation and is known to impact system latency. FREQ_NOISE is specified as TYPE:ID:MIN:MAX, where: TYPE should be cpu or uncore, and specifies whether CPU or uncore frequency should be modified; ID is either CPU number or uncore domain ID to modify the frequency for (e.g. cpu:12:... would target CPU12); MIN is the minimum CPU/uncore frequency value; MAX is the maximum CPU/uncore frequency value. for example, to add frequency scaling noise for CPU0, add -- freq-noise cpu:0:min:max. to add uncore frequency noise for uncore domain 0, add --freq-noise uncore:0:min:max. the parameter can be added multiple times to specify multiple frequency noise domains. 🔊🔥
• --freq-noise-sleep FREQ_NOISE_SLEEP — sleep between frequency noise operations. this time is added between every frequency scaling operation executed by the freq-noise feature. the default time unit is microseconds, but it's possible to use time specifiers as well, ms - milliseconds, us - microseconds, ns - nanoseconds. default sleep time is 50ms. 😴💤

and that's the whole page bestie, you made it 🎉💖 this one's from 2024-03-08, and yeah, it's the START() page — slay, periodt. go measure something. 👑🦋