xref: /aosp_15_r20/external/toolchain-utils/crosperf/help.py (revision 760c253c1ed00ce9abd48f8546f08516e57485fe)
1*760c253cSXin Li# -*- coding: utf-8 -*-
2*760c253cSXin Li# Copyright 2011 The ChromiumOS Authors
3*760c253cSXin Li# Use of this source code is governed by a BSD-style license that can be
4*760c253cSXin Li# found in the LICENSE file.
5*760c253cSXin Li
6*760c253cSXin Li"""Module to print help message."""
7*760c253cSXin Li
8*760c253cSXin Li
9*760c253cSXin Liimport sys
10*760c253cSXin Liimport textwrap
11*760c253cSXin Li
12*760c253cSXin Lifrom settings_factory import BenchmarkSettings
13*760c253cSXin Lifrom settings_factory import GlobalSettings
14*760c253cSXin Lifrom settings_factory import LabelSettings
15*760c253cSXin Li
16*760c253cSXin Li
17*760c253cSXin Liclass Help(object):
18*760c253cSXin Li    """The help class."""
19*760c253cSXin Li
20*760c253cSXin Li    def GetUsage(self):
21*760c253cSXin Li        return """%s [OPTIONS] EXPERIMENT_FILE""" % (sys.argv[0])
22*760c253cSXin Li
23*760c253cSXin Li    def _WrapLine(self, line):
24*760c253cSXin Li        return "\n".join(textwrap.wrap(line, 80))
25*760c253cSXin Li
26*760c253cSXin Li    def _GetFieldDescriptions(self, fields):
27*760c253cSXin Li        res = ""
28*760c253cSXin Li        for field_name in fields:
29*760c253cSXin Li            field = fields[field_name]
30*760c253cSXin Li            res += "Field:\t\t%s\n" % field.name
31*760c253cSXin Li            res += self._WrapLine("Description:\t%s" % field.description) + "\n"
32*760c253cSXin Li            res += "Type:\t\t%s\n" % type(field).__name__.replace("Field", "")
33*760c253cSXin Li            res += "Required:\t%s\n" % field.required
34*760c253cSXin Li            if field.default:
35*760c253cSXin Li                res += "Default:\t%s\n" % field.default
36*760c253cSXin Li            res += "\n"
37*760c253cSXin Li        return res
38*760c253cSXin Li
39*760c253cSXin Li    def GetHelp(self):
40*760c253cSXin Li        global_fields = self._GetFieldDescriptions(GlobalSettings("").fields)
41*760c253cSXin Li        benchmark_fields = self._GetFieldDescriptions(
42*760c253cSXin Li            BenchmarkSettings("").fields
43*760c253cSXin Li        )
44*760c253cSXin Li        label_fields = self._GetFieldDescriptions(LabelSettings("").fields)
45*760c253cSXin Li
46*760c253cSXin Li        return """%s is a script for running performance experiments on
47*760c253cSXin LiChromeOS. It allows one to run ChromeOS Autotest benchmarks over
48*760c253cSXin Liseveral images and compare the results to determine whether there
49*760c253cSXin Liis a performance difference.
50*760c253cSXin Li
51*760c253cSXin LiComparing several images using %s is referred to as running an
52*760c253cSXin Li"experiment". An "experiment file" is a configuration file which holds
53*760c253cSXin Liall the information that describes the experiment and how it should be
54*760c253cSXin Lirun. An example of a simple experiment file is below:
55*760c253cSXin Li
56*760c253cSXin Li--------------------------------- test.exp ---------------------------------
57*760c253cSXin Liname: my_experiment
58*760c253cSXin Liboard: x86-alex
59*760c253cSXin Liremote: chromeos2-row1-rack4-host7.cros 172.18.122.132
60*760c253cSXin Li
61*760c253cSXin Libenchmark: page_cycler_v2.morejs {
62*760c253cSXin Li  suite: telemetry_Crosperf
63*760c253cSXin Li  iterations: 3
64*760c253cSXin Li}
65*760c253cSXin Li
66*760c253cSXin Limy_first_image {
67*760c253cSXin Li  chromeos_image: /usr/local/chromeos-1/chromiumos_image.bin
68*760c253cSXin Li}
69*760c253cSXin Li
70*760c253cSXin Limy_second_image {
71*760c253cSXin Li  chromeos_image:  /usr/local/chromeos-2/chromiumos_image.bin
72*760c253cSXin Li}
73*760c253cSXin Li----------------------------------------------------------------------------
74*760c253cSXin Li
75*760c253cSXin LiThis experiment file names the experiment "my_experiment". It will be
76*760c253cSXin Lirun on the board x86-alex. Benchmarks will be run using two remote
77*760c253cSXin Lidevices, one is a device specified by a hostname and the other is a
78*760c253cSXin Lidevice specified by it's IP address. Benchmarks will be run in
79*760c253cSXin Liparallel across these devices.  There is currently no way to specify
80*760c253cSXin Liwhich benchmark will run on each device.
81*760c253cSXin Li
82*760c253cSXin LiWe define one "benchmark" that will be run, page_cycler_v2.morejs. This
83*760c253cSXin Libenchmark has two "fields", one which specifies that this benchmark is
84*760c253cSXin Lipart of the telemetry_Crosperf suite (this is the common way to run
85*760c253cSXin Limost Telemetry benchmarks), and the other which specifies how many
86*760c253cSXin Liiterations it will run for.
87*760c253cSXin Li
88*760c253cSXin LiWe specify one or more "labels" or images which will be compared. The
89*760c253cSXin Lipage_cycler_v2.morejs benchmark will be run on each of these images 3
90*760c253cSXin Litimes and a result table will be output which compares them for all
91*760c253cSXin Lithe images specified.
92*760c253cSXin Li
93*760c253cSXin LiThe full list of fields that can be specified in the experiment file
94*760c253cSXin Liare as follows:
95*760c253cSXin Li=================
96*760c253cSXin LiGlobal Fields
97*760c253cSXin Li=================
98*760c253cSXin Li%s
99*760c253cSXin Li=================
100*760c253cSXin LiBenchmark Fields
101*760c253cSXin Li=================
102*760c253cSXin Li%s
103*760c253cSXin Li=================
104*760c253cSXin LiLabel Fields
105*760c253cSXin Li=================
106*760c253cSXin Li%s
107*760c253cSXin Li
108*760c253cSXin LiNote that global fields are overidden by label or benchmark fields, if
109*760c253cSXin Lithey can be specified in both places. Fields that are specified as
110*760c253cSXin Liarguments override fields specified in experiment files.
111*760c253cSXin Li
112*760c253cSXin Li%s is invoked by passing it a path to an experiment file,
113*760c253cSXin Lias well as any options (in addition to those specified in the
114*760c253cSXin Liexperiment file).  Crosperf runs the experiment and caches the results
115*760c253cSXin Li(or reads the previously cached experiment results out of the cache),
116*760c253cSXin Ligenerates and displays a report based on the run, and emails the
117*760c253cSXin Lireport to the user.  If the results were all read out of the cache,
118*760c253cSXin Lithen by default no email is generated.
119*760c253cSXin Li""" % (
120*760c253cSXin Li            sys.argv[0],
121*760c253cSXin Li            sys.argv[0],
122*760c253cSXin Li            global_fields,
123*760c253cSXin Li            benchmark_fields,
124*760c253cSXin Li            label_fields,
125*760c253cSXin Li            sys.argv[0],
126*760c253cSXin Li        )
127