[PATCH] README_SOURCE: Reformat to make it 80 char width friendly, minor changes.
Keng-Yu Lin
kengyu at canonical.com
Tue Dec 18 02:57:04 UTC 2012
On Thu, Dec 13, 2012 at 11:01 PM, Colin King <colin.king at canonical.com> wrote:
> 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
>
>
Acked-by: Keng-Yu Lin <kengyu at canonical.com>
More information about the fwts-devel
mailing list