1FWTS(1)                     General Commands Manual                    FWTS(1)
2
3
4

NAME

6       fwts - a firmware test suite to identify firmware bugs.
7
8

SYNOPSIS

10       fwts [options] [test(s)]
11
12

DESCRIPTION

14       This  manual  page documents briefly the fwts firmware test suite.  The
15       tool fwts is comprised of over fifty tests that are designed to examine
16       and  test  different  aspects of PC firmware.  Many of these tests need
17       super user access to extract tables and interact with the firmware  and
18       ACPI, so running fwts using sudo is required.
19       Running  fwts with no options will run through all the batch tests that
20       require no user interaction.  However, one  can  select  just  specific
21       tests to run if required.
22
23       By  default fwts outputs the test results into the log file results.log
24       however a different log file name can be  specified  and  if  required,
25       output to stderr or stdout can be selected.
26
27       Note  that  there  a  variety of tests, including tests that can poten‐
28       tially hang a machine (such as a suspend/hibernate/resume).
29
30

OPTIONS

32       fwts options are as follow:
33
34       -      output results to stdout.
35
36       --acpica
37              enable ACPICA execution mode options. These can be specified  as
38              a comma separated list of one or more options.  Avaiable options
39              are: serialized (serialized execution of  AML),  slack  (run  in
40              less  pedeantic  mode),  ignore-errors  (ignore ACPICA exception
41              errors), disable-auto-repair (disable ACPICA from  automatically
42              fixing  broken  ACPICA controls).  Note that the slack mode will
43              turn on implicit returns of zero on control methods  to  attempt
44              to allow buggy AML to work on non-Windows systems.
45
46       --acpica-debug
47              enable ACPICA debug warning and error messages when invoking the
48              ACPICA subsystem. This is mainly for  fwts  developers  to  help
49              track down any ACPICA interfacing issues with fwts.
50
51       --acpicompliance
52              run only those tests that specifically check for compliance with
53              the ACPI specifications.  This may  be  a  subset  of  the  ACPI
54              tests.
55
56       --acpitests
57              run all general ACPI tests.
58
59       -a, --all
60              run all the tests.
61
62       --arch=name
63              specify  the target architecture whose firmware is being tested.
64              This allows fwts to run on one architecture (the host) but  per‐
65              form  tests  for  a  different architecture (the target).  Known
66              architecture strings are: x86, x86_32, or x86_64 for Intel; ia64
67              for  Itanium; arm64 or aarch64 for ARMv8.  Unless this option is
68              specified, the target is assumed to be the same as the host.
69
70       -b, --batch
71              run the non-interactive batch tests. Batch tests require no user
72              interaction.
73
74       --batch-experimental
75              run only batch experimental tests.
76
77       --clog specify a coreboot logfile dump.
78
79       --disassemble-aml
80              disassemble AML (ACPI machine language) byte code. This attempts
81              to disassemble  AML  in  DSDT  and  SSDT  tables  and  generates
82              DSDT.dsl and SSDTx.dsl sources.
83
84       -d, --dump
85              extracts  firmware data and dumps it into log files. This gener‐
86              ates:
87              acpidump.log - containing a hex dump of the ACPI  tables  (which
88              can be read using acpixtract).
89              dmesg.log - containing the current kernel log messages.
90              dmidecode.log - containing the output from dmidecode.
91              lspci.log - containing the output from lspci -vv -nn
92              cpuinfo.log - containing the output from cat /proc/cpuinfo
93              README.txt  - containing a timestamp and kernel version informa‐
94              tion.
95
96       --dumpfile=acpidump.log
97              load ACPI tables from output generated  from  acpidump  or  from
98              sudo  fwts  --dump.   The  latter is preferred as fwts --dump is
99              able to dump more tables than acpidump. This allows one to  dump
100              tables  from one machine and processes them with fwts on another
101              machine.
102
103       --ebbr run ARM EBBR tests.
104
105       --uefi-get-var-multiple
106              specifies the number of times to get a variable in  the  uefirt‐
107              variable get variable stress test.
108
109       --uefi-set-var-multiple
110              specifies  the  number of times to set a variable in the uefirt‐
111              variable set variable stress test.
112
113       --uefi-query-var-multiple
114              specifies the number of times to query a variable in the uefirt‐
115              variable query variable stress test.
116
117       --uefitests
118              run all general UEFI tests.
119
120       --filter-error-discard
121              specifies  the  errors  that  one wants to silently ignore.  One
122              supplies a comma sperated list of fwts error message labels that
123              one  wants  fwts to not report as errors. fwts will run the test
124              but if there is a test failure and the  label  matches  the  one
125              supplied  in  this  list  fwts will then just ignore this error.
126              This cannot be used with --filter-error-keep.
127
128       --filter-error-keep
129              specifies the errors that one wants to keep,  all  other  errors
130              are  silently  ignored.   One  supplies a comma sperated list of
131              fwts error message labels that one wants fwts report as  errors,
132              other  test  failures will be not reported and silently ignored.
133              This cannot be used with --filter-error-discard.
134
135       -f, --force-clean
136              creates a new results log file, rather than  just  appending  to
137              any existing one (default).
138
139       -h, --help
140              outputs the internal help page.
141
142       -i, --interactive
143              run the interactive tests. These tests require user interaction.
144
145       --ifv  run tests in firmware-vendor modes.
146
147       --interactive-experimental
148              run only interactive experimental tests.
149
150       -j, --json-data-path
151              specifies the path to the fwts json data files. These files con‐
152              tain json formatted configuration tables, for example klog scan‐
153              ning patterns.
154
155       -k, --klog=file
156              read the kernel log from the specified file rather than from the
157              kernel log ring buffer. This allows one to run  the  kernel  log
158              scanning tests such as klog against pre-gathered log data.
159
160       --log-fields
161              show the available log filtering fields. Specifying these fields
162              with --log-filter to select which fields one wants to log.
163
164       --log-filter
165              specify which particular types of log data to be output into the
166              log  file. Each line of log data is tagged with a special marker
167              depending on what type of log information is being  output.  The
168              available  types  can  be see by using --log-fields. Specify the
169              desired log types with comma separated list. To disable a field,
170              prefix the name with ~, for example:
171              --log-filter=RES,SUM  logs just the results and summary lines.
172              --log-filter=ALL,~INF  logs all lines except for the information
173              lines.
174
175       --log-format
176              specify the information in each log line. The  following  speci‐
177              fiers are available:
178              %date  - date
179              %time  - time
180              %field - log-filter fields
181              %owner - name of the test routine
182              %level - test failure level
183              %line  - log line
184              e.g. --log-format="%date %time [%field] (%owner): "
185
186       --log-level [critical|high|medium|low|info|all]
187              specify the test failure level to log. Test failure levels equal
188              to and higher than the specified  are  logged  and  recorded  as
189              failures.  The  default is 'all' (which is identical to 'info').
190              For example, a log level of 'medium' will just log test failures
191              of  level  'medium', 'high' and 'critical', where as a log level
192              of 'critical' will just log 'critical' level failures.
193
194       --log-type
195              specify the log type. Currently  plaintext,  json  and  xml  log
196              types are available and the default is plaintext.
197
198       --lspci=path
199              specify the full path and filename to the the lspci binary.
200
201       -P, --power-states
202              run S3 and S4 power state tests (s3, s4 tests)
203
204       --results-no-separators
205              no  pretty  printing of horizontal separators in the results log
206              file.
207
208       -r, --results-output=filename
209              specify the results output log file.  One can also specify  std‐
210              out and stderr to redirect to these output streams.
211
212       -R, --rsdp=physaddr
213              specify  the  physical  address  of ACPI RSDP. This is useful on
214              some systems where it cannot be automatically detected.
215
216       --pm-method=method
217              specify the power method to use to enter S3 or S4 (or autodetec‐
218              tion will be used). The following specifiers are available:
219              logind    -  the  default method, where available (requires dbus
220              and logind).
221              pm-utils - the previous default method, now deprecated.
222              sysfs    - the fallback, used when logind is not available.
223              e.g. --pm-method=sysfs
224
225       --s3-delay-delta=N
226              time to be added onto delay between each S3 iteration.
227
228       --s3-device-check
229              check differences between device configurations over a S3 cycle.
230              Note  this  adds  15 seconds delay after each s3 resume to allow
231              wifi to re-associate.
232
233       --s3-device-check-delay
234              specify the time to wait while devices re-configure  (e.g.  wifi
235              to re-associate, ethernet to connect..)  before a device config‐
236              uration check is run. The default is 15 seconds.  If this option
237              is used the device checking is assumed so one does not also need
238              to use the --s3-device-check flag.
239
240       --s3-hybrid
241              enables fwts to run Hybrid Sleep.
242
243       --s3-min-delay=N
244              minimum time between S3 iterations.
245
246       --s3-max-delay=N
247              maximum time between S3 iterations.
248
249       --s3-multiple=N
250              specified the number of multiple S3 suspend/resume tests to run.
251              The default is 2 tests.
252
253       --s3-resume-hook=hookscript
254              specifies  a  script or program to run after each S3 resume. The
255              hookscript must return 0 to indicate  success,  or  non-zero  to
256              indicate failure.  Failures will abort subsequent S3 test itera‐
257              tions.
258
259       --s3-quirks=--quirk[,--quirk]
260              specify a comma separated list of quirk arguments to pass to pm-
261              suspend,                       for                      example:
262              --s3-quirks=--quirk-s3-bios,--quirk-save-pci
263
264       --s3-sleep-delay=N
265              sleep N seconds from the start of  the  suspend  to  the  wakeup
266              time.  Note that this time MUST be longer than the time it takes
267              to suspend the machine otherwise the wakeup timer will fire dur‐
268              ing the suspend state. The default is 30 seconds.
269
270       --s3-suspend-time=N
271              specify  the maximum allowed suspend time in seconds. If suspend
272              takes longer than this then an error is logged.
273
274       --s3-resume-time=N
275              specify the maximum allowed resume time in  seconds.  If  resume
276              takes longer than this then an error is logged.
277
278       --s3power-sleep-delay=N
279              specify  the  suspend duration in seconds.  The higher the value
280              the more accurate the s3power test result.  Durations less  than
281              10 minutes are not recommended.
282
283       --s4-delay-delta=N
284              time to be added onto delay between each S4 iteration.
285
286       --s4-device-check
287              check differences between device configurations over a S4 cycle.
288              Note this adds 15 seconds delay after each s3  resume  to  allow
289              wifi to re-associate.
290
291       --s4-device-check-delay
292              specify  the  time to wait while devices re-configure (e.g. wifi
293              to re-associate, ethernet to connect..)  before a device config‐
294              uration check is run. The default is 15 seconds.  If this option
295              is used the device checking is assumed so one does not also need
296              to use the --s4-device-check flag.
297
298       --s4-min-delay=N
299              minimum time between S4 iterations.
300
301       --s4-max-delay=N
302              maximum time between S4 iterations.
303
304       --s4-multiple=N
305              specified  the  number  of multiple S4 hibernate/resume tests to
306              run. The default is 2 tests.
307
308       --s4-quirks=--quirk[,--quirk]
309              specify a comma separated list of quirk arguments to pass to pm-
310              hibernate, for example: --s4-quirks=--quirk-save-pci
311
312       --s4-sleep-delay=N
313              sleep  N  seconds  from the start of the hibernate to the wakeup
314              time. Note that this time MUST be longer than the time it  takes
315              to  hibernate  the  machine otherwise the wakeup timer will fire
316              during the hibernate state. The default is currently 90 seconds.
317
318       --sbbr run ARM SBBR tests
319
320       -p, --show-progress
321              show the progress of the tests being run. Each test will identi‐
322              fied as it is being run. For long tests, a percentage of comple‐
323              tion time will be displayed. As of fwts 0.19.06 this is  enabled
324              by default and can be disabled with --quiet (or -q).
325
326       -q, --quiet
327              run quietly with no output to stdout.
328
329       -D, --show-progress-dialog
330              output  the  progress  of  tests being run in a form that can be
331              piped into the dialog tool with the --gauge option.
332
333       -s, --show-tests
334              show the names of available tests.  By  default  will  show  all
335              tests.  Use  the  --batch,  --interactive, --batch-experimental,
336              --interactive-experimental, --utils options to show  these  spe‐
337              cific tests.
338
339       --show-tests-full
340              show  all  the available tests listed by minor test description.
341              By default will show all tests. Use the --batch,  --interactive,
342              --batch-experimental, --interactive-experimental options to show
343              these specific tests.
344
345       --show-tests-categories
346              show all the available tests and the categories they belong to.
347
348       --skip-test=test[,test..]
349              specify tests to skip over and not run. List must be comma sepa‐
350              rated.
351
352       --stdout-summary
353              output SUCCESS or FAILED to stdout at end of tests.
354
355       -t, --table-path=path
356              specify the path containing ACPI tables. These tables need to be
357              named in the format: tablename.dat, for  example  DSDT.dat,  for
358              example,  as  extracted  using  acpidump or fwts --dump and then
359              acpixtract.
360
361       -u, --utils
362              run utilities. Designed to  dump  system  information,  such  as
363              annotated  ACPI  tables,  CMOS  memory,  Int 15 E820 memory map,
364              firmware ROM data.
365
366       -v, --version
367              output version number and build date of the fwts tool.
368
369       -w, --width=N
370              specify the width in  characters  of  the  output  logfile.  The
371              default is 130.
372
373

EXAMPLES

375       Run  all  the  batch  tests and append the results into the default log
376       results.log:
377               sudo fwts
378
379       Run all the interactive tests and start  a  clean  results  log  called
380       interactive.log:
381               sudo fwts -i -f -r interactive.log
382
383       Run all the tests, interactive and batch:
384               sudo fwts -i -b
385
386       Run just the battery and cpufreq tests:
387               sudo fwts battery cpufreq
388
389       Run all the batch tests and define a new log format using just the date
390       and line number:
391               sudo fwts --log-format="%date %line: "
392
393       Run all the interative tests and log just the results, info and summary
394       data:
395               sudo fwts -i --log-filter=RES,INF,SUM
396
397       Dump all the interesting firmware information into log files for analy‐
398       sis later:
399               sudo fwts --dump
400
401       View kernel and ACPI driver version and BIOS information:
402               sudo fwts  -w 80 -r stdout  version bios_info  --log-filter=INF
403               --log-format=""
404
405       Show the batch and batch experimental tests:
406               fwts --show-tests --batch --batch-experimental
407
408       Run  multiple S3 tests with delay between each test ranging from 1 sec‐
409       ond to 10 seconds with a delay delta per test of 0.2 seconds
410               sudo     fwts     s3     --s3-multiple=100     --s3-min-delay=1
411               --s3-max-delay=10 --s3-delay-delta=0.2
412
413

SEE ALSO

415       iasl(1), acpixtract(1), acpidump(1), dtc(1), dmidecode(8), lspci(8)
416

AUTHOR

418       fwts  was  originally  written  by Colin King with much of the original
419       test code derived from the Intel Linux Firmware test kit.  Many  thanks
420       also  for  contributions  from  (in  alpabetical order): AceLan Kao, Al
421       Stone, Alberto Milone, Alex  Hung,  Anthony  Wong,  Chris  Goldsworthy,
422       Chris  Van Hoof, David Ward, Deb McLemore, Erico Nunes, Fan Wu, Fu Wei,
423       Heyi Guo, Ivan Hu, Jeffrey  Hugo,  Jeremy  Kerr,  Jiri  Vohanka,  Kamal
424       Mostafa,  Keng-Yu  Lin, Mahesh Bireddy, Matt Flemimg, Naresh Bhat, Paul
425       Menzel, Phidias Chiang, Pradeep Gaddam, Prarit Bhargava,  Rajat  Goyal,
426       Ricardo  Neri,  Robert Hooker, Rudolf Marek, Sakar Arora, Seth Forshee,
427       Yang Kun, Yi Li and Zhang Rui.
428
429       This manual page was written by Colin King for the Ubuntu project  (but
430       may be used by others).
431
432       This is free software; see the source for copying conditions.  There is
433       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
434       PURPOSE.
435
436
437
438                                24 August, 2017                        FWTS(1)
Impressum