Message ID | 1355410887-23420-1-git-send-email-colin.king@canonical.com |
---|---|
State | Accepted |
Headers | show |
On Thu, Dec 13, 2012 at 11:01 PM, Colin King <colin.king@canonical.com> wrote: > From: Colin Ian King <colin.king@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@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@canonical.com>
On 12/13/2012 11:01 PM, Colin King wrote: > From: Colin Ian King <colin.king@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@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. > Acked-by: Ivan Hu <ivan.hu@canonical.com>
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.