diff options
| author | jasplin <qt-info@nokia.com> | 2009-10-15 09:04:36 +0200 |
|---|---|---|
| committer | jasplin <qt-info@nokia.com> | 2009-10-15 09:04:36 +0200 |
| commit | f900112901f93d3e8bd4e3b2e0d0e0f19ef88fff (patch) | |
| tree | b96ea0cac58b57d60038d738bdde37db2bae8f7c /doc | |
| parent | 5828b5d9831dcfdc3d8cee2b1582dd991c841aa4 (diff) | |
Updates to doc ++.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/architecture3.odp | bin | 0 -> 15688 bytes | |||
| -rw-r--r-- | doc/bmclient.html | 20 | ||||
| -rw-r--r-- | doc/bmproto.html | 6 | ||||
| -rw-r--r-- | doc/bmrunner.html | 163 | ||||
| -rw-r--r-- | doc/bmserver.html | 44 | ||||
| -rw-r--r-- | doc/index.html | 14 |
6 files changed, 235 insertions, 12 deletions
diff --git a/doc/architecture3.odp b/doc/architecture3.odp Binary files differnew file mode 100644 index 0000000..13fecf7 --- /dev/null +++ b/doc/architecture3.odp diff --git a/doc/bmclient.html b/doc/bmclient.html index 5228a36..85fbfc1 100644 --- a/doc/bmclient.html +++ b/doc/bmclient.html @@ -17,14 +17,16 @@ td {vertical-align:top; padding:5px} <h2>BM Client Program</h2> <h3>Overview</h3> -The BM client program (<code>bmclient</code>) is a program that communicates with -a BM server via the BM protocol (described elsewhere). The program accepts -input via command-line arguments, environment variables, or standard input. -The program writes output (if any) to standard output or standard error. + +The BM client (<code>bmclient</code>) sends requests to a <a +href="bmserver.html">BM server</a> via the <a href="bmproto.html">BM +protocol</a>. The bmclient accepts input via command-line arguments, +environment variables, or standard input, and writes any output to standard +output or standard error. <h3>Modes</h3> -If the program is run without any command-line arguments it is run in <i>CGI -mode</i>. In this case, the program is assumed to be launched by a web server +If the bmclient is run without any command-line arguments, it is run in <i>CGI +mode</i>. In this case, the bmclient is assumed to be launched by a web server in response to a request from a web client. Arguments are extracted from the QUERY_STRING environment variable or from the standard input depending on whether the HTTP request method was GET or POST respectively. The output is @@ -32,10 +34,10 @@ written to standard output in a format suitable for being sent back to and processed by the web client (typically JSON - see below). <p /> -If command-line arguments are present the program is run in <i>raw mode</i>. +If command-line arguments are present, the bmclient is run in <i>raw mode</i>. <h3>Help (raw mode only)</h3> -In raw mode, passing <code>help</code> to the program prints out a usage summary: +In raw mode, passing <code>help</code> to the bmclient prints out a usage summary: <pre> ./bmclient help @@ -98,7 +100,7 @@ The file is assumed to have the same XML structure as the one produced by QTestLib. <br /><br /> The git directory must be accessible from the local file system and the git -command needs to be installed (i.e. the program needs to run the git command +command needs to be installed (i.e. the bmclient needs to run the git command from the git directory). By default, the git directory is the current directory. <br /><br /> diff --git a/doc/bmproto.html b/doc/bmproto.html index 41cea65..e6a96e3 100644 --- a/doc/bmproto.html +++ b/doc/bmproto.html @@ -19,9 +19,9 @@ td {vertical-align:top; padding:5px} <h3>Overview</h3> The BM protocol is a simple protocol that assumes a reliable byte channel -(like TCP) between a client and a server. Requests are sent from the client to -the server. Each request is followed by a reply sent from the server to the -client. +(like TCP) between a client and a <a href="bmserver.html">BM +server</a>. Requests are sent from the client to the server. Each request is +followed by a reply sent from the server to the client. <h3>General Message Structure</h3> diff --git a/doc/bmrunner.html b/doc/bmrunner.html new file mode 100644 index 0000000..e51a6e5 --- /dev/null +++ b/doc/bmrunner.html @@ -0,0 +1,163 @@ +<html> + +<head> + +<style type="text/css"> +table {background-color:#f5f5f5; text-align:left} +th {vertical-align:top; padding:5px} +td {vertical-align:top; padding:5px} +.code {color:#a0291b; font-family:courier} +.codeDescr {color:#117711; min-width:200px} +</style> + +</head> + +<body> + +<h2>BM Runner Program</h2> + +<h3>Overview</h3> + +The BM runner (<code>bmrunner</code>) runs benchmark programs and reports +results to a <a href="bmserver.html">BM server</a> via the <a +href="bmclient.html">BM client</a>. The benchmark programs are assumed to be +based on QTestLib (i.e. accepting the same command-line arguments and +producing the same output). + +<br /><br /> + +The following table describes the command-line arguments to be passed to +bmrunner: + +<br /><br /> + +<table border=1> +<tr> + <th colspan="2">Argument</th> + <th>Description</th> +</tr> + +<!-- -metric ----------------------------------- --> +<tr> +<td><pre class="code">-metric</pre></td> +<td></td> +<td class="codeDescr"> +The resource to be used for measuring benchmark performance. Must be one of +<span class="code">walltime</span>, <span +class="code">tickcounter</span>, <span class="code">callgrind</span>, +or <span class="code">eventcounter</span>. Note that not all metrics are +supported everywhere. +</td> +</tr> + +<!-- -median ----------------------------------- --> +<tr> +<td><pre class="code">-median</pre></td> +<td>Optional</td> +<td class="codeDescr"> +The number of "median iterations" used for increasing the statistical +confidence. Each benchmark result is recomputed this many times and the final +result is the median of all recomputations. The median argument is +optional and the default value is 1. Note that specifying a median +value (> 1) only makes sense in situations where the results are expected to +be significantly unstable for successive runs (of the same code). As a rule of +thumb, the walltime and tickcounter metrics generate unstable results, while +the callgrind and eventcounter metrics do not. +</td> +</tr> + +<!-- -platform ----------------------------------- --> +<tr> +<td><pre class="code">-platform</pre></td> +<td></td> +<td class="codeDescr"> +The general build environment (most importantly, the compiler) used for +building the product being measured (like <i>linux-g++</i>, +<i>solaris-cc-64</i> etc.). A.k.a. <i>makespec</i>. +</td> +</tr> + +<!-- -host ----------------------------------- --> +<tr> +<td><pre class="code">-host</pre></td> +<td></td> +<td class="codeDescr"> +The name of the physical computer. Two benchmark results that are associated +with the same host are (ideally!) guaranteed to be produced under identical +hardware and (system) software environments/versions. +</td> +</tr> + +<!-- -gitdir ----------------------------------- --> +<tr> +<td><pre class="code">-gitdir</pre></td> +<td></td> +<td class="codeDescr"> +The toplevel git directory of the product to be benchmarked. The benchmark +programs are assumed to produce results based on a clean checkout of the +current head commit of the current branch in the git directory. The git +command needs to be installed and invokable in the default environment. +</td> +</tr> + +<!-- -gitrepo ----------------------------------- --> +<tr> +<td><pre class="code">-gitrepo</pre></td> +<td></td> +<td class="codeDescr"> +The name of the repository to which the product to be benchmarked +belongs. Note that this must be passed explicitly since it cannot in general +be derived from the git directory (e.g. in case of a local stand-alone +repository). +</td> +</tr> + +<!-- -bmserver ----------------------------------- --> +<tr> +<td><pre class="code">-bmserver</pre></td> +<td></td> +<td class="codeDescr"> +The location of the bmserver: <host>:<port>. +</td> +</tr> + +<!-- -bmdir ----------------------------------- --> +<tr> +<td><pre class="code">-bmdir</pre></td> +<td></td> +<td class="codeDescr"> +The directory containing the benchmark programs. The bmrunner will assume that +any file in this directory tree that is readable, executable, prefixed with +'<i>tst_</i>', and not containing the substring '<i>.debug</i>' is a +(potential) benchmark program and will attempt to execute it as such. +</td> +</tr> + +<!-- -display ----------------------------------- --> +<tr> +<td><pre class="code">-display</pre></td> +<td>Optional</td> +<td class="codeDescr"> +The value to pass as the DISPLAY environment variable when running benchmark +programs. If omitted, the DISPLAY variable is not (explicitly) set. +</td> +</tr> + +<!-- -timeout ----------------------------------- --> +<tr> +<td><pre class="code">-timeout</pre></td> +<td>Optional</td> +<td class="codeDescr"> +The timeout (in seconds) to apply when running benchmark programs. The default +value is 300 secs (5 mins). Specifying a negative value disables the timeout +(and the bmrunner then waits for each benchmark program to either terminate +successfully or with due to an error condition (other than a timeout)). +</td> +</tr> + + +</table> + + +</body> +</html> diff --git a/doc/bmserver.html b/doc/bmserver.html new file mode 100644 index 0000000..4457750 --- /dev/null +++ b/doc/bmserver.html @@ -0,0 +1,44 @@ +<html> + +<head> + +<style type="text/css"> +</style> + +</head> + +<body> + +<h2>BM Server Program</h2> + +<h3>Overview</h3> + +The BM server (<code>bmserver</code>) accesses a SQLite database of benchmark +results on behalf of a <a href="bmclient.html">BM client</a> (or any client +that speaks the <a href="bmproto.html">BM protocol</a>). + +<br /><br /> + +Normally, the bmserver is passed a port number an an existing database file +upon startup: + +<pre> + ./bmserver 1104 results.db +</pre> + +It then enters a loop serving client requests via the <a +href="bmproto.html">BM protocol</a>. + +<br /><br /> + +The bmserver may also be used for creating and initializing a new database file: + +<pre> + ./bmserver initdb results.db +</pre> + +In this case, the bmserver terminates as soon as the database file has been +created and initialized with the appropriate schema (and no data). + +</body> +</html> diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..1a37cec --- /dev/null +++ b/doc/index.html @@ -0,0 +1,14 @@ +<html> +<head /> +<body> + +<a href="bmclient.html">bmclient</a> +<br /> +<a href="bmserver.html">bmserver</a> +<br /> +<a href="bmproto.html">client-server protocol</a> +<br /> +<a href="bmrunner.html">bmrunner</a> + +</body> +</html>
\ No newline at end of file |