diff options
Diffstat (limited to 'host/docs')
| -rw-r--r-- | host/docs/rd_testing.dox | 95 | ||||
| -rw-r--r-- | host/docs/uhd.dox | 2 | ||||
| -rw-r--r-- | host/docs/uhd_semvar.dox | 143 |
3 files changed, 240 insertions, 0 deletions
diff --git a/host/docs/rd_testing.dox b/host/docs/rd_testing.dox new file mode 100644 index 000000000..9c712b084 --- /dev/null +++ b/host/docs/rd_testing.dox @@ -0,0 +1,95 @@ +/*! \page page_rdtesting R&D Testing Procedures + +All defined R&D test procedures are listed here. These tests are meant as a tool +for Ettus R&D to enable faster and more reliable development. Note these tests +are no replacement for manufacturing or production tests, and should not be +treated as such. Instead, they are meant to catch common failure modes during +development. As a result, test definitions are fairly light-weight. + +\section rdtesting_phase Phase Alignment Tests + +tbd + +\section rdtesting_gpsdo GPSDO Tests + +| Test Code | Device | Peripherals | Manual Test Procedure | Automatic Test Procedure | +|------------------|-----------|-------------------|------------------------------|---------------------------| +| GPS-X310-TCXO-v1 | USRP X310 | Jackson Labs TCXO | \ref rdtesting_gpsdo_manual | \ref rdtesting_gpsdo_auto | +| GPS-X310-OCXO-v1 | USRP X310 | Jackson Labs OCXO | \ref rdtesting_gpsdo_manual | \ref rdtesting_gpsdo_auto | +| GPS-X300-TCXO-v1 | USRP X300 | Jackson Labs TCXO | \ref rdtesting_gpsdo_manual | \ref rdtesting_gpsdo_auto | +| GPS-X300-OCXO-v1 | USRP X300 | Jackson Labs OCXO | \ref rdtesting_gpsdo_manual | \ref rdtesting_gpsdo_auto | +| GPS-B200-TCXO-v1 | USRP B200 | Jackson Labs TCXO | \ref rdtesting_gpsdo_manual | \ref rdtesting_gpsdo_auto | +| GPS-B210-TCXO-v1 | USRP B210 | Jackson Labs TCXO | \ref rdtesting_gpsdo_manual | \ref rdtesting_gpsdo_auto | + + +\subsection rdtesting_gpsdo_recommendations Recommendations + +For cursory testing, not all tests within a device family are required (e.g., +only testing the OCXO on any X-Series, and testing the TCXO on any B-Series is +sufficient). + +The following tests are recommended for a minimum test (N stands for the latest +version of this test): +- One of GPS-X310-OCXO-vN or GPS-X300-OCXO-vN +- One of GPS-B210-TCXO-vN or GPS-B200-TCXO-vN + +\subsection rdtesting_gpsdo_requirements Requirements + +All of these tests require a device that is GPSDO capable (e.g., X3x0, B2x0, +N2x0). For those devices that have a separate GPS component (such as the Jackson +Labs GPSDOs), this component is also required (called the "peripheral" in the +following). + +\subsection rdtesting_gpsdo_manual GPSDO: Manual Test Procedure + +1. Without connecting the peripheral to the device, run `uhd_usrp_probe` on the + device and verify that the lack of GPSDO is correctly reported. No warning + or error must be printed. +2. This and the following tests are run with the peripheral connected: Run + `uhd_usrp_probe` and verify that the GPSDO is correctly reported. Power down + the device before connecting the peripheral. The GPSDO must be reported + found, and no error or warning must be printed. +3. Without connecting the GPS antenna input, run `query_gpsdo_sensors`. To pass, + it must report the GPSDO as found, lock to the external reference, but then + report not being locked to GPS. The tool will report a valid GPS time, and + a string such as "GPS and UHD Device time are aligned" in case of success. +4. Connect a GPS antenna to the input and make sure it is in a position to + receive GPS satellite data. Confirm that GPS lock is reported using + `query_gpsdo_sensors` within 20 minutes of connecting the antenna. + The tool `query_gpsdo_sensors` will print a string such as "GPS Locked" in + case of success. + +All of these tests must pass for a 'pass' validation. + +\subsection rdtesting_gpsdo_auto GPSDO: Automatic Test Procedure + +tbd + +\section rdtesting_defining Defining R&D Tests + +Tests can be added any time to define procedures for pass/fail validation. Any +test must include the following: + +- An unambiguous test code. This code consists of three characters that + identify the test, a short description of the devices required, and a version + suffix. Example: `GPS-X310-OCXO-v1` is a GPS-related test, requires an X310 + and an OCXO to run, and is version 1 of this test. +- A manual testing procedure. This must unambiguously define a set of tasks, + and clearly identify whether or not a test has failed or passed. Tests do not + require any other defined outcome other than 'pass' and 'fail'. +- Optional, but highly recommended: An automatic test procedure. This must + consist of a command, or a script, or a set of commands that can be + automatically executed, and that will report a failure condition by means of + returning a non-zero return value. + +Basic understanding of the operation of USRPs by the test operator should be +assumed when authoring test procedures. The descriptions should be as short as +possible to fully describe, unambiguously, how to reach a pass/fail conclusion. + +Test procedures may be updated at any time. If this happens, a new test code +must be generated, with the version number increased. Old test codes are +considered deprecated (if there exists a version 2 of a test, version 1 should +not be run any more). + +*/ +// vim:ft=doxygen: diff --git a/host/docs/uhd.dox b/host/docs/uhd.dox index fcd0a25b0..5474d42e2 100644 --- a/host/docs/uhd.dox +++ b/host/docs/uhd.dox @@ -13,6 +13,8 @@ Some additional pages on developing UHD are also available here: \li \subpage page_converters \li \subpage page_stream \li \subpage page_rtp +\li \subpage page_semver +\li \subpage page_rdtesting */ // vim:ft=doxygen: diff --git a/host/docs/uhd_semvar.dox b/host/docs/uhd_semvar.dox new file mode 100644 index 000000000..2a43b92f1 --- /dev/null +++ b/host/docs/uhd_semvar.dox @@ -0,0 +1,143 @@ +/*! \page page_semver UHD Semantic Versioning + +\section semver_summary Summary + +Given a version number MAJOR.API.ABI.PATCH, increment the: + +1. MAJOR version as necessitated by product generation & architecture. +2. API version when you make incompatible API changes, +3. ABI version when you make incompatible ABI changes, +4. PATCH version when you make backwards-compatible bug fixes. + +Additional labels for other metadata may be appended to the version +number as ``extensions``. + +\section semver_intro Introduction + +Version numbers play an important role in communicating the +compatibility and restrictions of particular releases of software +libraries. By defining formal semantics for the library versioning, +users of the library can immediately and precisely comprehend the +implications of updating that particular library in their application or +system. This information is especially important to developers in +environments where a very high degree of Reliability, Availability, +Serviceability, and Manageability (\ref footnote_rasm "1") are operational +requirements. + +Additionally, without strict versioning semantics, version numbers are +effectively useless for dependency management. By adhering to a +versioning specification, application developers can easily specify +which existing & future versions of the library their software is +compatible with. As a dependency, this makes the library easier to use, +integrate, maintain, and plan around. + +The [*Semantic Versioning*](http://semver.org/) (SemVer) specification +was introduced in 2009 and is now a requirement of the Linux +Foundation's +[*Core Infrastructure Initiative's*](https://www.coreinfrastructure.org/) +[*Best Practices Badge*](https://www.coreinfrastructure.org/programs/badge-program). +The UHD Semantic Versioning (UHD-SemVer) specification is based on SemVer, +but has been modified to better reflect the requirements of the Ettus +Research user-space device driver workflow, project history, and +application ecosystem. + +\section semver_spec UHD-SemVer Specification + +The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, +“SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this +document are to be interpreted as described in [*RFC +2119*](http://tools.ietf.org/html/rfc2119). + +1. Software using Semantic Versioning MUST declare a public API. This + API could be declared in the code itself or exist strictly + in documentation. However it is done, it should be precise + and comprehensive. + +2. A normal version number MUST take the form W.X.Y.Z where W, X, Y, + and Z are non-negative integers, and MUST NOT contain + leading zeroes. W is the major version, X is the API version, Y + is the ABI version, and Z is the patch version. Each element + MUST increase numerically. For instance: 3.1.9.0 -> 3.1.10.0 + -> 3.1.11.0. + +3. Once a versioned package has been released, the contents of that + version MUST NOT be modified. Any modifications MUST be released + as a new version. + +4. Patch version Z (w.x.y.Z) MUST be incremented if only backwards + API-compatible & ABI-compatible changes are introduced. + +5. ABI version Y (w.x.Y.z) MUST be incremented if changes break ABI + compatibility with the previous release. + +6. API version X (w.X.y.z) MUST be incremented if changes break public + API compatibility with the previous release. It MAY include ABI + and patch level changes. It MAY be incremented if substantial new + functionality or improvements are introduced within private code. + ABI and PATCH version MUST be reset to 0 when API version + is incremented. An API breakage is defined as the case where + recompiling software against UHD without modifications may yield + different results. The following cases, for example, are typically + not API-breaking, but are ABI-breaking: adding new public methods, + adding new default parameters to public methods if the default + case is identical to the previous case. + +7. MAJOR version W (W.x.y.z) MAY be incremented if significant + architectural or technological changes are made that warrant + identifying the software as a new generation of product. + +8. A pre-release version MAY be denoted by appending a hyphen and a + series of dot separated identifiers immediately following the + patch version. Identifiers MUST comprise only ASCII alphanumerics + and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric + identifiers MUST NOT include leading zeroes. Pre-release versions + have a lower precedence than the associated normal version. A + pre-release version indicates that the version is unstable and + might not satisfy the intended compatibility requirements as + denoted by its associated normal version. Examples: 3.1.0.0-alpha, + 3.1.0.0-alpha.1, 3.1.0.0-0.3.7, 3.1.0.0-x.7.z.92. + +9. Build metadata MAY be denoted by appending a plus sign and a series + of dot separated identifiers immediately following the patch or + pre-release version. Identifiers MUST comprise only ASCII + alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT + be empty. Build metadata SHOULD be ignored when determining + version precedence. Thus two versions that differ only in the + build metadata, have the same precedence. Examples: + 3.1.0.0-alpha+001, 3.1.0.0+20130313144700, 3.1.0.0-beta+exp.sha.5114f85. + +10. Precedence refers to how versions are compared to each other + when ordered. Precedence MUST be calculated by separating the + version into major, API, ABI, patch and pre-release + identifiers in that order (Build metadata does not figure + into precedence). Precedence is determined by the first difference + when comparing each of these identifiers from left to right as + follows: Major, API, ABI, and patch versions are always + compared numerically. Example: 3.1.0.0 < 3.2.0.0 < 3.2.1.0 + < 3.2.1.1. When major, API, ABI, and patch are equal, a + pre-release version has lower precedence than a normal version. + Example: 3.1.0.0-alpha < 3.1.0.0. Precedence for two + pre-release versions with the same major, API ABI, and patch + version MUST be determined by comparing each dot separated + identifier from left to right until a difference is found as + follows: identifiers consisting of only digits are compared + numerically and identifiers with letters or hyphens are compared + lexically in ASCII sort order. Numeric identifiers always have + lower precedence than non-numeric identifiers. A larger set of + pre-release fields has a higher precedence than a smaller set, if + all of the preceding identifiers are equal. Example: 3.1.0.0-alpha + < 3.1.0.0-alpha.1 < 3.1.0.0-alpha.beta < 3.1.0.0-beta + < 4.1.0.0-beta.2 < 3.1.0.0-beta.11 < 3.1.0.0-rc.1 < 3.1.0.0. + +\section semver_license License + +Based on [*SemVer 2.0.0*](http://semver.org/). +[*Creative Commons - CC BY 3.0*](http://creativecommons.org/licenses/by/3.0/) + +\anchor footnote_rasm 1. For more information on enterprise RASM, see +[*Wikipedia’s article on RAS*](https://en.wikipedia.org/wiki/Reliability,_availability_and_serviceability_(computing)) +and [*National Instrument’s whitepaper*](http://www.ni.com/white-paper/14410/en/) +[*on RASM*](http://www.ni.com/white-paper/14410/en/). + +*/ +// vim:ft=doxygen: |