[PATCH] README_SOURCE: Reformat to make it 80 char width friendly, minor changes.
Colin King
colin.king at canonical.com
Thu Dec 13 15:01:27 UTC 2012
From: Colin Ian King <colin.king at canonical.com>
Reformat to make it fit into an 80 char width terminal. Update to make it
in sync with latest version of fwts.
Signed-off-by: Colin Ian King <colin.king at canonical.com>
---
README_SOURCE.txt | 122 ++++++++++++++++++++++++++++++------------------------
1 file changed, 69 insertions(+), 53 deletions(-)
diff --git a/README_SOURCE.txt b/README_SOURCE.txt
index a801646..535bace 100644
--- a/README_SOURCE.txt
+++ b/README_SOURCE.txt
@@ -1,13 +1,14 @@
== FWTS Source Structure ==
-FWTS comprises of a core fwts library, two special builds of the ACPICA source and the fwts
-tests themselves.
+FWTS comprises of a core fwts library, two special builds of the ACPICA source
+and the fwts tests themselves.
== Core FWTS library libfwts.so ==
-The core fwts library, libfwts.so, contains the fwts test framework to drive fwts tests and
-a support library that provides the tests with commonly used functionality, such as list
-handling, log scanning, port I/O, ACPI table handling, etc.
+The core fwts library, libfwts.so, contains the fwts test framework to drive
+fwts tests and a support library that provides the tests with commonly used
+functionality, such as list handling, log scanning, port I/O, ACPI table
+handling, etc.
Source:
fwts/src/lib/src
@@ -15,7 +16,8 @@ Source:
Conventions:
All fwts core library functions should start with fwts_ prefix
- C source that provides an API should have a corresponding header in fwts/src/lib/include
+ C source that provides an API should have a corresponding header in
+ fwts/src/lib/include
We include all exported headers in fwts/src/lib/include/fwts.h
Declare variables and functions as static if they are not to be exported
@@ -40,14 +42,16 @@ Conventions:
== ACPICA libraries ==
-The ACPICA source is built in two modes for fwts, one for the run-time execution of AML
-(acpiexec mode) and one for the assembly/dis-assembly of AML (compile mode). This makes life
-a bit complex since both modes are not compatible, so fwts builds these as differenty libraries
-and exports a thin shim interface that libfwts and fwts tests can use. It's quite ugly.
+The ACPICA source is built in two modes for fwts, one for the run-time
+execution of AML (acpiexec mode) and one for the assembly/dis-assembly of AML
+(compile mode). This makes life a bit complex since both modes are not
+compatible, so fwts builds these as differenty libraries and exports a thin
+shim interface that libfwts and fwts tests can use. It's quite ugly.
-The intention is to regularly pick up the latest ACPICA sources every release cycle and
-drop these into fwts. Note that we only incorporate the minimal subset of ACPICA source that
-is required for the execution and assembly/disassembly functionality required by fwts.
+The intention is to regularly pick up the latest ACPICA sources every release
+cycle and drop these into fwts. Note that we only incorporate the minimal
+subset of ACPICA source that is required for the execution and
+assembly/disassembly functionality required by fwts.
=== acpiexec mode ===
@@ -69,15 +73,17 @@ Interface:
=== Notes ===
-Whenever we update the ACPICA core we need to update README_ACPICA.txt to reflect any additional
-ACPIC sources we include into fwts.
+Whenever we update the ACPICA core we need to update README_ACPICA.txt to
+reflect any additional ACPIC sources we include into fwts.
-DO NOT modify any of the ACPICA sources - we use the original sources and should not modify
-them in fwts. Note that some on-the-fly source tweaking is performed to stop name clashes.
+DO NOT modify any of the ACPICA sources - we use the original sources and
+should not modify them in fwts. Note that some on-the-fly source tweaking is
+performed to stop name clashes.
== fwts tests ==
-The fwts tests are grouped in several sub-directories depending on the type of testing:
+The fwts tests are grouped in several sub-directories depending on the type of
+testing:
src/acpi - ACPI specific tests (methods, AML, tables, etc)
src/apic - APIC tests
@@ -92,13 +98,16 @@ src/kernel - kernel specific
src/pci - PCI
src/uefi - UEFI
-When writing new tests use the blank sketch of a test in src/example/blank/blank.c.
+When writing new tests use the blank sketch of a test in
+src/example/blank/blank.c.
Test Conventions:
- All code must be static, no exporting of functions to other parts of fwts
- If we have common code in multiple tests then refactor it into the fwts core library
- DO NOT call exit() from a test
- DO NOT call printf() from a test - use the fwts logging functions
+ All code must be static, no exporting of functions to other parts of
+ fwts.
+ If we have common code in multiple tests then refactor it into the
+ fwts core library.
+ DO NOT call exit() from a test.
+ DO NOT call printf() from a test - use the fwts logging functions.
Tests are registered with fwts using the FWTS_REGISTER macro:
@@ -106,31 +115,34 @@ Tests are registered with fwts using the FWTS_REGISTER macro:
fwts_framework_ops *example_ops, priority, flags);
where:
- example - is the name of the test, no spaces in this name as it is stringified
+ example - is the name of the test, no spaces in this name as it is
+ stringified.
example_ops - fwts_framework_ops to configure test, with:
- .description - const char * name of the test
- .init - optional function to call before running the test(s)
- .deinit - optional function to call after running the test(s)
- .minor_tests - array of fwts_framework_minor_test describing minor tests to run
-
- .minor_tests is an array of functions + text description tuples of minor tests to
- run and must be NULL terminated. One can have one or more minor tests
- registered to run.
-
- priority ranking - when to run the test when we have many tests to run, can be:
- 0..100, where 0 = first, 100 = last
-
- We advise using one of the following macros:
- FWTS_TEST_FIRST - schedule to run as first test(s)
- FWTS_TEST_EARLY - schedule to run fairly soon at start
- FWTS_TEST_ANYTIME - medium priority
- FWTS_TEST_LATE - schedule to run close to the end
- FWTS_TEST_LAST - run at the end
+ .description - const char * name of the test.
+ .init - optional function to call before running the
+ test(s).
+ .deinit - optional function to call after running the
+ test(s).
+ .minor_tests - array of fwts_framework_minor_test describing
+ minor tests to run.
+
+ .minor_tests is an array of functions + text description
+ tuples of minor tests to run and must be NULL
+ terminated. One can have one or more minor
+ tests registered to run.
+
+ priority ranking - when to run the test when we have many tests to run
+ and can be:
+ FWTS_TEST_FIRST - schedule to run as first test(s)
+ FWTS_TEST_EARLY - schedule to run fairly soon at start
+ FWTS_TEST_ANYTIME - medium priority
+ FWTS_TEST_LATE - schedule to run close to the end
+ FWTS_TEST_LAST - run at the end
- Tests of the same priority are will run in an order chosen at link time,
- but will run before tests of higher priory ranking and after tests of
- lower priory ranking.
+ Tests of the same priority are will run in an order chosen at
+ link time, but will run before tests of higher priory ranking
+ and after tests of lower priory ranking.
flags - indicates the type of test - where appropriate these can be
logically OR'd together, can be:
@@ -147,16 +159,20 @@ where:
FWTS_TEST_ACPI ACPI specific
so, we can have FWTS_BATCH | FWTS_ROOT_PRIV | FWTS_ACPI
- for a batch test that requires root privilege and is an ACPI test
+ for a batch test that requires root privilege and is an ACPI
+ test.
test init/deinit callbacks.
- These are intended to do pre and post test setup and close down, for example
- loading in tables, checking for resources, sanity checking capabilities.
+ These are intended to do pre and post test setup and close
+ down, for example loading in tables, checking for resources,
+ sanity checking capabilities.
- They return FWTS_OK (all OK) or FWTS_ERROR (something went wrong, abort!)
+ They return FWTS_OK (all OK) or FWTS_ERROR (something went
+ wrong, abort!).
minor tests.
- These do the specific tests, can have one or more per test harness. Must
- return FWTS_OK (all OK) or FWTS_ERROR (something went wrong). FWTS_ERROR
- does not mean a test failed, but the test could not be run because of
- some external factor, e.g. memory allocation failure, I/O issue, etc.
+ These do the specific tests, can have one or more per test
+ harness. Must return FWTS_OK (all OK) or FWTS_ERROR (something
+ went wrong). FWTS_ERROR does not mean a test failed, but the
+ test could not be run because of some external factor, e.g.
+ memory allocation failure, I/O issue, etc.
--
1.8.0
More information about the fwts-devel
mailing list