API Validation Suite
Design Specification
Version: 2.0
Save Date: 2017-07-31
Author: Thomas E. Gauger
File Name: APIVS Design Specification.doc
API Validation Suite
Design Specification, v2.0
Revision History
Date: 2017-07-31
Revision History
Date
Version
Description
Author
2010/12/30
2.0
Accepted all changes to revision 1.3. Improvements
based upon actual implementation of VSE.
Accepted all changes to revision 1.2. Fixed formatting
issues. Make sure & are listed in XML documents as
&.
Corrections based upon development, improve VSE
block-diagram
Thomas E. Gauger
nFocal
2010/08/18
1.3
2010/08/13
1.2
2010/08/06
1.1
Improvements following design review with WG
2010/07/30
1.0
Initial Released Version
ITE, 2017
Thomas E. Gauger
nFocal
Thomas E. Gauger
nFocal
Thomas E. Gauger
nFocal
Thomas E. Gauger
nFocal
Page 2/35
API Validation Suite
Design Specification, v2.0
Table of Contents
Date: 2017-07-31
Table of Contents
1.
INTRODUCTION ...............................................................................................................................................6
1.1
PURPOSE .........................................................................................................................................................6
1.2
INTENDED AUDIENCE .....................................................................................................................................6
1.3
SCOPE .............................................................................................................................................................6
1.4
CONVENTIONS ................................................................................................................................................6
1.5
DEFINITIONS, ACRONYMS, AND ABBREVIATIONS ...........................................................................................7
1.6
REFERENCES...................................................................................................................................................8
2.
RESPONSE TO APIVS SRS ..............................................................................................................................9
3.
THE VALIDATION SUITE ENGINE (VSE) ................................................................................................. 12
4.
3.1
EXPECTED VSE ENVIRONMENT.................................................................................................................... 12
3.2
VSE SOFTWARE ARCHITECTURE .................................................................................................................. 14
3.3
DEFINING A VALIDATION SUITE WITH THE APIVSXML .............................................................................. 15
3.4
RUNNING A VALIDATION SUITE ................................................................................................................... 15
3.5
CONFIGURATION FILE................................................................................................................................... 15
3.6
BOOLEAN EXPRESSION HANDLING FOR VALIDATION ................................................................................... 17
3.7
HUMAN-READABLE FLAT FILES ................................................................................................................... 18
3.8
OUTPUT ........................................................................................................................................................ 18
3.8.1
Return codes ........................................................................................................................................ 18
3.8.2
Output XML ......................................................................................................................................... 18
3.8.3
Results Captured .................................................................................................................................. 19
TOD VALIDATION .......................................................................................................................................... 19
4.1
5.
6.
TOD API FUNCTION VERIFICATION ............................................................................................................. 20
FPUI VALIDATION ......................................................................................................................................... 21
5.1
FPUI LOOPBACK CABLE .............................................................................................................................. 21
5.2
VT100 EMULATOR ....................................................................................................................................... 21
5.3
INPUT GENERATION ...................................................................................................................................... 21
5.4
MULTIPLE FPUI PROCESSES......................................................................................................................... 21
5.5
FPUI API FUNCTION VERIFICATION ............................................................................................................ 22
FIO VALIDATION ........................................................................................................................................... 26
6.1
FIO LOOPBACK CABLE................................................................................................................................. 26
6.2
SDLC COMMAND MESSAGE PROCESSING / EMULATING .............................................................................. 26
6.3
SDLC RESPONSE MESSAGE PROCESSING ..................................................................................................... 26
ITE, 2017
Page 3/35
API Validation Suite
Design Specification, v2.0
7.
Table of Contents
Date: 2017-07-31
6.4
MULTIPLE FIO PROCESSES ........................................................................................................................... 26
6.5
FIO API FUNCTION VERIFICATION ............................................................................................................... 27
ADD AND REMOVE API FUNCTIONS ........................................................................................................ 34
7.1
ADDING A NEW FUNCTION ........................................................................................................................... 34
7.2
REMOVING AN EXISTING FUNCTION ............................................................................................................. 35
7.3
ADDING NEW, APIVSXML-CALLABLE, FUNCTIONALITY TO THE VSE ....................................................... 35
ITE, 2017
Page 4/35
API Validation Suite
Design Specification, v2.0
Table of Figures/Tables
Date: 2017-07-31
List of Figures
Figure 1. Layered organization of ATC software ........................................................................................................ 12
Figure 2. API test environment uses a test fixture with crossover cables and a personal computer ............................ 12
Figure 3. VSE Software Architecture .......................................................................................................................... 14
List of Tables
Table 1. Definitions ....................................................................................................................................................... 7
Table 2. Reference Documents ...................................................................................................................................... 8
Table 3. SRS Compliance Matrix ................................................................................................................................ 11
Table 4 Configuration Elements .................................................................................................................................. 16
Table 5 Boolean Expressions ....................................................................................................................................... 17
Table 6 Expression Arguments .................................................................................................................................... 17
Table 7. TOD API Function Verification .................................................................................................................... 20
Table 8. FPUI API Function Verification .................................................................................................................... 25
Table 9. FIO API Function Verification ...................................................................................................................... 33
ITE, 2017
Page 5/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
1. Introduction
1.1
Purpose
This document contains the high level design of the API Validation Suite Engine (VSE).
1.2
Intended Audience
This document is of a technical nature. It is intended for members of the cross-functional project team involved in
the design, implementation, maintenance, and testing of the API Validation Suite project.
1.3
Scope
This document defines the high level design of the API Validation Suite Engine (VSE). This document is a
response to the API Validation Suite SRS and discussion of the technical issues of developing the VSE.
1.4
Conventions

Square brackets ( [ ] ) indicate to-be-determined information which will be resolved before this document is
finalized. For example, “The minimum hard disk space is [TBD] MB.”

Mono-spaced type indicates functions, variables, parameters, statements, commands, and other
operating system or programming language constructs. For example, “Use the dir command to list the
files and directories.”

Italicized text (substitution) indicates a substitution parameter. For example, “Use the dir path
command to list the files and directories in the given path.”

Bold type indicates user interface elements or APIVSXML syntax (windows, dialog boxes, menus, and
controls). For example, “Press the OK button.” or “the print attribute …”

Vertical bars (|) are used to indicate a path through a hierarchical user interface. For example, “Select File |
Open… to open a file."
ITE, 2017
Page 6/35
API Validation Suite
Design Specification, v2.0
1.5
Date: 2017-07-31
Definitions, Acronyms, and Abbreviations
The following terms are defined in this document.
Term
Definition
API
Application Programming Interface
APIVSXML
Application Programming Interface Validation Suite eXtensible Markup Language
The XML language that the VSE uses to process a Test Case (TC) for the ATC API.
ATC
Advanced Traffic Controller
FIO
Field I/O. A library of the ATC API.
FIOD
Field I/O Device.
FIOM
Field I/O Manager. API Software that is responsible for controlling all FIODs.
FP
Front Panel. The actual physical display on an ATC.
FPM
Front Panel Manager. API Software that is responsible for controlling the Front Panel.
FPUI
Front Panel User Interface. A library of the ATC API.
I/O, IO
Input / Output
IPC
Inter-Process Communications
SRS
Software Requirements Specification
TC
Test Case
TCS
Test Case Specification
TOD
Time Of Day. A library of the ATC API.
VS
Validation Suite
VSE
Validation Suite Engine
Software that utilizes the APIVSXML to validate a manufacturers API.
XML
eXtensible Markup Language
XSD
XML Schema Definition
Table 1. Definitions
ITE, 2017
Page 7/35
API Validation Suite
Design Specification, v2.0
1.6
Date: 2017-07-31
References
The following may be referenced in this document. These documents, of the issue in effect on the date of this
specification, form a part of this specification to the extent specified herein. In the event of a conflict between the
documents referenced herein and the contents of this specification, the contents of this specification shall be
considered a superseding requirement.
Source Document
ID Tag
Author
Date
Document Number
20100521
APIValSuiteSRS010
1_100521
http://en.wikipedia.org/wiki/XML
A simple explanation and examples of XML
Wikipedia
Application Programming Interface (API)
Validation Suite Software Requirements
Specification (SRS)
Ralph Boaz
APIVSXML.doc
This document contains a textual description
of the APIVSXML.
Thomas E. Gauger 20101231
APIVSXML.xsd
This document contains the XSD for the
APIVSXML
Thomas E. Gauger 20101231
“ISO/IEC 9899:1999 Programming Language
C.”
ISO
Available from the
International
Organization for
Standardization(ISO)
Table 2. Reference Documents
ITE, 2017
Page 8/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
2. Response to APIVS SRS
This section maps Section 3, SPECIFIC REQUIREMENTS, of the SRS against the actual handling of this
requirement by the design presented herein.
SRS Requirement
Proposed handling of requirement
3.1 No Cost
nFocal has ensured that no 3rd party or open source software is used in
the manufacture and production of the VSE that would require a cost
in order to copy, distribute and use the VSE.
3.2 Uses an ITE Approved License
nFocal has ensured that 3rd party and open source software used in the
manufacture and production of the VSE will only use approved ITE
License Models in order to copy, distribute and use the VSE.
3.3 Operational and Consistent with API
Test Plan
nFocal has ensured that the VSE is consistent with the API Test Plan
and operates within the test environment design in section 2.1 of the
SRS.
3.4 GNU Coding Standard
nFocal has ensured that all code is written in adherence to the GNU
Coding Standard (see Section 1.6 References)
3.5 Conformance / Nonconformance
Indications
The VSE returns, to the calling environment, 0 to indicate
conformance and -1 to indicate nonconformance of the API Software
to the API Standard; based upon the test cases run. In this way shell
scripts may be written to run a series of TCs.
The VSE and APIVSXML provides the ability to log the tests
performed, according to the text included in TCs, including:


3.6 Detailed Logs and Traces




3.7 Summary Result
The library, function and arguments on an API function call
and the return values;
If the function fails, guidance may be provided to the user on
the cause of the failure (depending upon the contents of the
APIVSXML document being executed);
The Test Case Specification (TCS) being executed;
The line # in the APIVSXML document
The step in the TCS will be provided, and as much
information as has been documented in the APIVSXML for
the offending TC and function will be provided, when a
failure occurs; and
Time stamps for each step in the TCS will be provided.
The VSE provides a summary of the results of the testing including
TCSs performed and their pass/fail result, based upon the contents of
the APIVSXML document being executed.
ITE, 2017
Page 9/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
The VSE provides the user with the ability to specify the output
options, using the –L command line option (see section 3.4 Running a
Validation Suite), as follows:
3.8 Output Options



1) Conformance / nonconformance indication only;
2) Conformance / nonconformance indication and summary
results;
3) Conformance / nonconformance indication, summary
results and all logs and traces.
3.9 XML Output Files
The VSE outputs any summary, log or traces into a file or stdout, as
indicated by the –o command line option (see Section 3.4 Running a
Validation Suite), in an XML (eXtensible Markup Language) format.
The VSE also includes conformance / nonconformance indication in
this output.
3.10 Automated Use of APIVSXML
Defined Test Cases
The VSE will read TCSs written in APIVSXML (see Section 1.6
References) and will perform the testing steps identified therein. The
APIVSXML file to be used is identified using the –i command line
option (see Section 3.4 Running a Validation Suite).
3.11 Function Present
The VSE is able to validate that each API function defined in the API
Standard Section 4 Application Programming Interface and its
subsections is present in the API Software using the APIVSXML. It
is up to the constructor of the APIVSXML to ensure that all API
functions have been referenced at least once in a TC specified by the
APIVSXML.
3.12 Conforming Arguments
The VSE is able to validate that all arguments of each API function
conform to the API Standard, using the APIVSXML. It is up to the
constructor of the APIVSXML to ensure that all arguments desired to
be tested are referenced at least once in a TC specified by the
APIVSXML.
3.13 Integrated Tests
It is up to the constructor of the APIVSXML to ensure that each API
function is part of at least one integrated test that validates that the
behavior of the API function conforms to the API Standard. The
APIVSXML and VSE are defined in such a way as to make this
possible.
3.14 Front Panel Manager Operation
The VSE is able to validate that the API Software meets the
requirements of the window system defined in the API Standard
Section 3.1.1 Front Panel Manager Requirements and its subsections,
using the APIVSXML. The VSE contains a VT100 emulator to
ensure that expected displays, as defined in the APIVSXML, match
the actual virtual display, as constructed by the VT100 emulator from
the Front Panel Manager (FPM) output. It is up to the constructor of
the APIVSXML to ensure what expected displays are to be compared
to the actual virtual display and when.
ITE, 2017
Page 10/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
3.15 ATC Configuration Window Operation
The VSE is able to validate that the API Software meets the
requirements of the ATC Configuration Window defined in the API
Standard Section 3.2.1 ATC Configuration Window Requirements,
using the APIVSXML. The VSE contains a VT100 emulator to
ensure that expected displays, as defined in the APIVSXML, match
the actual virtual display, as constructed by the VT100 emulator from
the Front Panel Manager (FPM) output. It is up to the constructor of
the APIVSXML to ensure what expected displays are to be compared
to the actual virtual display and when.
3.16 Field I/O Manager Operation
The VSE is able to validate that the API Software meets the
requirements of the Field I/O system defined in the API Standard
Section 3.1.2 Field I/O Manager Requirements, using the
APIVSXML. The VSE contains a SDLC Command and Response
Message Processor / Emulator to ensure that expected Command
Messages, as defined in the APIVSXML, match the actual Command
Messages, as received and processed by the SDLC Command and
Response Message Processor / Emulator from the Field I/O Manager
(FIOM) output. It is up to the constructor of the APIVSXML to
ensure what expected Command Messages are to be compared to the
actual Command Messages received and when. The APIVSXML is
defined to be able to produce Response Messages. It is up to the
constructor of the APIVSXML to enable this feature, at the
appropriate times, as well.
3.17 Multiple and Simultaneous
Applications
The VSE is able to validate that 16 application programs, running
concurrently, can exercise the window system, the FPM functions and
the FIOM function simultaneously. This is accomplished by starting
multiple independent VSE processes simultaneously and executing
appropriate APIVSXML documents. It is recommended that this be
done using shell scripts to coordinate processing and timing of these
processes.
3.18 C Programming Language
The VSE is written using the C Programming Language as described
by “ISO/IEC 9899:1999”, commonly referred to as the C99 Standard.
3.19 Incorporated New Functions
The VSE has constructs and documentation with specific directions
on how new API functions can added in the future. See Section 7
Add and Remove API Functions, below, for details.
Table 3. SRS Compliance Matrix
ITE, 2017
Page 11/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
3. The Validation Suite Engine (VSE)
This section describes the high-level design of the Validation Suite Engine (VSE) and the processing that it
performs.
3.1
Expected VSE Environment
The VSE will run in a test environment as if it is an “Application SW”, as depicted by Figure 1 below:
USER
DEVELOPER
OPERATIONAL
USER
APPLICATION SW
INTERFACE
AND BEHAVIOR
DEFINED BY ATC
API STANDARD
USER
LAYER
APPLICATION
LAYER
API
SOFTWARE
LAYER
API
LINUX OS & DEVICE DRIVERS
HW & OS
DEFINED BY ATC
CONTROLLER
STANDARD
ATC BOARD
SUPPORT
PACKAGE
LAYER
HARDWARE
LAYER
Figure 1. Layered organization of ATC software
The physical environment that the VSE will be operating in is depicted by Figure 2 below:
CROSSOVER
CABLE
CONSOLE
CABLE
POWER
CABLE
TEST FIXTURE
Figure 2. API test environment uses a test fixture with crossover cables and a personal computer
There will be two (2) cross over cables. One crossover cable will be used for serial port FPUI VT100 validation, the
other will used for serial port FIO SDLC validation. The connection to the PC is used to gain console access of the
ATC Engine Board and to initiate running of the VSE and retrieve results produced by the VSE. The VSE itself
runs directly on the ATC Engine Board.
ITE, 2017
Page 12/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
The following is also true about the VSE Environment:

FPUI loopback cable – There is a loopback cable going from the FPUI managed serial port (that would
normally be connected to a VT100 Front Panel display) back to a serial port that the Validation Suite
Engine (VSE) opens for read / write.

FPUI VSE port – The FPUI VSE port is configurable by the VSE.

FPUI VT100 emulator – The VSE reads data from the FPUI VSE port and processes this data using a
VT100 emulator to construct a virtual display based upon the VT100 commands received. The
APIVSXML allows for this virtual display to be compared against a flat file that specifies what the virtual
display should look like at any given point in time. This is the method that is used to validate FPUI output
commands. The APIVSXML supports an unlimited number of flat files for comparison.

FPUI input – The APIVSXML allows for specifying FPUI input that the VSE is able to write to the FPUI
VSE port. This data can then be read using FPUI input functions. In this way, we are able to simulate user
input at the front panel. This input is defined in flat files. An unlimited number of flat input files are
supported. The APIVSXML also supports executing FPUI input (read) functions and is able to validate the
data returned by these functions.

TOD validation – The TOD library is self-contained with regards to being able to validate set interfaces
through the use of get interfaces and vice versus.

FIO loopback cable – There is a loopback cable going from a FIO managed SDLC serial port (that would
normally be connected to an FIOD) back to a SDLC serial port that the VSE opens for read / write.

FIO VSE port – The FIO VSE port is configurable by the VSE.

FIO SDLC / FIOD command processing – The VSE reads SDLC command messages from the FIO VSE
port and processes this data using SDLC / FIOD processing functionality in the form of a FIOD emulator.
The APIVSXML allows for the ability to compare these processed SDLC command messages against an
expected message and contained data. The compared data is contained in flat files.

FIO SDLC / FIOD response generation – The APIVSXML allows for specifying SDLC responses that the
VSE is able to write to the FIO VSE port – in response to an SDLC command message. Flat files are used.
The APIVSXML also supports executing FIO input (read) functions and is able to validate the data
returned by these functions.
ITE, 2017
Page 13/35
API Validation Suite
Design Specification, v2.0
3.2
Date: 2017-07-31
VSE Software Architecture
The VSE runs as an application, as specified in section 3.1 Expected VSE Environment above. The VSE application
is structured, as indicated in Figure 3. VSE Software Architecture, diagram below.
APIVSXML
Expected Result
Flat Files
XML Results
VSE
APIVSXML
Parser
Results
Generator
Validator
CMDMSG
SDLC
Processor
FIOM
VD
APIVSXML
Interpreter
VT100
Emulator
API Libraries
TOD, FPUI, FIO
FPM
Figure 3. VSE Software Architecture
ITE, 2017
Page 14/35
API Validation Suite
Design Specification, v2.0
3.3
Date: 2017-07-31
Defining a Validation Suite with the APIVSXML
A Validation Suite (VS) is defined using the API Validation Suite XML (APIVSXML) language that is defined in
the list of referenced documents. The APIVSXML offers a flexible and powerful method by which to define a VS.
The APIVSXML is a “programming language” that allows for new tests / validations to be added as they are
defined.
A single VS consists of one (1) or more test cases. A test case is defined in a programming language like fashion to
accomplish and validate the ATC API functionality desired. This is done using the well known and documented
syntax of XML.
The APIVSXML defines the processing that the VSE will perform. The VSE loads and interprets the VS, described
using the APIVSXML, and performs the processing described therein.
3.4
Running a Validation Suite
A VS is run by executing an instance of the VSE using the follow command line options:
vse -L [1-3]
[-c configuration-file]
[-i APIVSXML-file]
[-o output-file]
[-n test_suite_name]
[-C]
Where:
3.5

vse – Is the name of the VSE executable

-L [1-3] – (required) Is the conformance level of the output desired. 1 – Conformance / nonconformance
indication only, 2 – Conformance / nonconformance indication and summary results, 3 – Conformance /
nonconformance indication, summary result and all logs and traces.

-c configuration-file – (optional) Is a file that specifies a series of VSE run configurable items. See 3.5
Configuration File below. If this file is omitted, default values are used.

-i APIVSXML-file – (optional) Is the path to the VS APIVSXML to use. If –i is not present the input will
be read from stdin.

-o output-file – (optional) Is the path of where to place the generated output XML file. If –o is not present,
the output will be placed on stdout.

-n test_suite_name – (optional) Is a specific test suite named in the APIVSXML-file that is to be run. If
omitted, all test suites contained in the APIVSXML-file will be run.

-C – (optional) If present, this command line argument indicates that this run of the VSE is to “capture” the
Virtual Displays (VD) and the SDLC Command Messages (CMDMSG) to be used by future VSE
Validation runs. This information, VD and CMDMSG, are captured into flat flats as specified by the
configuration-file.
Configuration File
The configuration file is used to specify file paths and other parameters to be used by the VSE during processing.
The configuration file is a simple ASCII flat file. All lines in the configuration file that begin with a ‘#’ are ignored
as comment lines. Blank lines are allowed for easy of reading. All configuration lines are of the form:
“configurable-item = configuration-value”
White space is supported in the definition of a configuration line. All paths must be terminated by a “/”.
ITE, 2017
Page 15/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
The following table specifies the configuration values supported in the configuration file:
Configuration Item
XMLInputFilePath
XMLOutputFilePath
SetFilePath
Configuration Value
Specifies the path to the APIVSXML input file.
Default: ./
Specifies the path of where to place the output XML file.
Default: ./
Specifies the path to the <Set file=”file” /> file path.
Default: ./
ScreenHeight
Specifies the screen height. The configured value is available to the APIVSXML as
the named constant “#ROWS”.
Default: 8
ScreenWidth
Specifies the screen width. The configured value is available to the APIVSXML as
the named constant “#COLUMNS”.
Default: 40
FPUICompareFilePath
Specifies the path to the !VDCompare(file) file path.
Default: ./
FPUIInputFilePath
Specifies the path to the <FPUIInput file=”file /> file path.
Default: ./
FPUIDumpFilePath
Specifies the path to the <Dump dump=”VD” file=”file” /> and
<Load load=”VD” file=”file” /> file path.
Default: ./
FPUILoopbackDevice
Specifies the path to the VSE FPUI port to be used as the loop back port.
Default: NULL – This indicates perform no VT100 loopback emulation.
FIOCompareFilePath
Specifies the path to the !CMDMSG(file,frame) file path.
Default: ./
FIOResponseFilePath
Specifies the path to the <FIOResponse file=”file /> file path.
Default: ./
FIODumpFilePath
Specifies the path to the <Dump dump=”CMDMSG” file=”file /> and
<Load load=”CMDMSG” file=”file” /> file path.
Default: ./
FIOLoopbackDevice
Specifies the path to the VSE FIO port to be used as the loop back port.
Default: NULL – This indicates perform no FIO emulation.
Table 4 Configuration Elements
ITE, 2017
Page 16/35
API Validation Suite
Design Specification, v2.0
3.6
Date: 2017-07-31
Boolean Expression Handling for Validation
The APIVSXML defines a series of API functions to be called and the validations to be performed in the course of
processing these API functions. The validation is done using boolean expressions. Validation is done against
function return codes, returned errno values, function output parameters, the Virtual Display (VD) – in the case of
FPUI processing, the SDLC command message – in the case of FIO processing, or the results from subsequent
function calls – such as in a set / get scenario. Both numeric and string comparisons are supported.
Boolean expression processing support includes:
Operation
Usage
EQ
Logical equality
NE
Logical inequality
LT
Logical less than
LE
Logical less than or equal to
GT
Logical greater than
GE
Logical greater than or equal to
Table 5 Boolean Expressions
Comparison values:
Operation
Usage
$var
Variable, as defined in the APIVSXML.
#constant
A named constant, as defined by the APIVSXML.
%number
A numeric constant, as defined by the APIVSXML.
@string
A string constant, as defined by the APIVSXML.
A macro (returning a numeric value for comparison), as defined by
the APIVSXML. Supported macros are listed below.
!macro(args)
!VDCompare(@file)
Compares the file against an the current state of the VD.
!CMDMSGCompare(@file,%frame_number)
!FIO_BIT_TEST($array,%bit)
!strlen(@string)
!sizeof($var)
Compare a SDLC command message against an expected command
message.
See if a bit is turned on in an array of bits.
Returns the length of the string.
Returns the number of elements of that variable.
Table 6 Expression Arguments
ITE, 2017
Page 17/35
API Validation Suite
Design Specification, v2.0
3.7
Date: 2017-07-31
Human-Readable Flat Files
The VSE supports human-readable, and modifiable, input and output files. For input VSE variable set files, SDLC
Command Message Load files, VD Load files, SDLC Response Message Files, and FP Input Files are supported.
For output VSE variable dumps, SDLC Command Message dumps, and VD dumps are supported.
For human-readable FP Input Files, the following is supported:

All lines starting with ‘#’ are ignored as comments,

The sequence “<ESC>” is translated as a single 0x1b (escape) character,

The sequence “<NL>” is translated as a single 0x0a (new-line) character,

The sequence “<CR>” is translated as a single 0x0d (carriage-return) character,

The sequence “<TAB>” is translated as a single 0x09 (tab) character,

The sequence “\\” is translated as a single 0x5c (backslash) character,

The sequence “\<” is translated as a single 0x3c (<) character,

The sequence “\>” is translated as a single 0x3e (>) character,

The sequence “0xNN” is translated as a sign 0xNN character, such as “0xFF” for a (DEL) character.
All other human-readable flat files allow for the use of ‘#’ as a comment line. All other human-readable flat files
support the input of binary hexadecimal data as a sequence such as:

0x2a 0x55 0x8f – A space must be present between values
Upon reading and input to the VSE, this information is translated into the appropriate binary format internally. If
the value converted to binary form is shorter than the destination, the destination is padded with 0x00. If the
destination is shorter than the converted binary form, the converted binary form is truncated to fit the destination
size.
3.8
Output
This section describes the output captured by the VSE.
3.8.1
Return codes
The VSE returns, to the calling environment, 0 to indicate conformance and -1 to indicate nonconformance of the
API Software to the API Standard; as according to the test cases run. In this way, Linux shell scripts may be written
to invoke and control the VS processing that should occur.
3.8.2
Output XML
The VSE outputs any summary, log or traces into a file, as indicated by the –o command line option (see Section 3.4
Running a Validation Suite), in an XML (eXtensible Markup Language) format. The VSE also includes
conformance / nonconformance indication in this output.
Since this output is in XML format, it may be post processed by many third party XML tools, including Microsoft
Excel.
ITE, 2017
Page 18/35
API Validation Suite
Design Specification, v2.0
3.8.3
Date: 2017-07-31
Results Captured
The VSE provides a log of the tests performed, as according to the text in test cases, including:






The library, function and arguments on an API function call and the return values;
If the function fails, guidance can be provided to the user on the cause of the failure;
The Test Case Specification (TCS) being executed;
The line # in the APIVSXML;
The step in the TCS will be provided, and as much information as has been documented in the APIVSXML
for the offending Test Case (TC) and function will be provided, when a failure occurs; and
Time stamps for each step in the TCS will be provided.
The VSE provides a summary of the results of the testing including TCSs performed and their pass/fail result. A
single test is an “all or nothing” processing; from the VSE’s prospective. This means that if any failure occurs along
the way, the entire test case fails and processing terminates at the point of the test failure. If it is desired to run
multiple tests, regardless if a single test fails, this must be done by running separate sequential VSE processes. This
can be done by the creation of a Linux shell script that does just this.
The VSE provides the user with the ability to specify the output options, using the –L command line option (see
section 3.4 Running a Validation Suite), as follows:



1) Conformance / nonconformance indication only;
2) Conformance / nonconformance indication and summary results;
3) Conformance / nonconformance indication, summary results and all logs and traces.
In addition and in order to facilitate the above, the APIVSXML has been defined with the ability to specify context
“description” XML attributes. It is up to the constructor of the APIVSXML to enable these APIVSXML features as
appropriate.
4. TOD Validation
This section describes how the various functions of the TOD library may and will be verified by the VSE using the
APIVSXML. Not all possible methods are listed.
Validation of TOD API functions does not require any special hardware – loopback cables – or additional set up
considerations. The TOD library and its validation are self-contained.
ITE, 2017
Page 19/35
API Validation Suite
Design Specification, v2.0
4.1
Date: 2017-07-31
TOD API Function Verification
This table illustrates how the various functions of the TOD library may and will be verified by the VSE using the
APIVSXML. Not all possible methods are listed.
TOD Function Name
Possible Verification Technique
tod_cancel_onchange_signal()
Validated by return values and ensuring SIGNAL
specified by tod_request_onchange_signal() does not
occur when day light savings time changes the local
time, or tod_set() is called.
tod_cancel_tick_signal()
Validated by return values and ensuring SIGNAL
specified by tod_request_tick_signal() no longer occurs.
tod_get()
Validated by return values and ensuring that the time
returned is within a few "ticks" of the time set by
tod_set(). Need to allow for the clock "ticking" between
calls.
tod_get_dst_info()
Validated by return values and verifying that the values
set using tod_set_dst_info() is what is returned.
tod_get_dst_state()
Validated by return codes and using tod_set_dst_state().
tod_get_timesrc()
Validated by return codes and using tod_set_timesrc().
tod_get_timesrc_freq()
Validated using expected return values.
tod_request_onchange_signal()
Validated by return values and ensuring that SIGNAL
occurs when tod_set() is called.
tod_request_tick_signal()
Validated by return codes and ensuring that the SIGNAL
occurs and counting expected SIGNALS following a
<Sleep> operation.
tod_set()
Validated by return codes and ensuring tod_get() returns
value that was set.
tod_set_dst_info()
Validated by return codes and calling tod_get_dst_info()
data returned should be what was set.
tod_set_dst_state()
Validated by return codes and tod_get_dst_state() should
return what was set.
tod_set_timesrc()
Validated by return codes and tod_get_timesrc()
returning what was set.
Table 7. TOD API Function Verification
ITE, 2017
Page 20/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
5. FPUI Validation
This section describes how the various functions of the FPUI library may and will be verified by the VSE using the
APIVSXML. Not all possible methods are listed.
5.1
FPUI Loopback Cable
The APIVS employs a loopback cable for FPUI validation. This loopback cable will connect the FPUI VT100
display port to a serial port that the VSE will open. The VSE will receive VT100 commands on this port and will
feed these commands to a VT100 emulator, described below. The VSE will also have the ability, as instructed by
the APIVSXML, to generate input that will be sent to the FPM. This is described in greater detail below.
5.2
VT100 Emulator
The VSE supports a VT100 emulator to interpret the VT100 commands, sent by the FPM, and will construct a
Virtual Display (VD). This VD may be interrogated and compared against the expected contents of the FP at any
point in time, as specified by the APIVSXML. Expected displays are kept in human-readable flat files that may be
referenced by the APIVSXML.
5.3
Input Generation
The VSE supports the ability to generate input to the FPM as if the user had actually pressed a function key on the
FP. The generation of this input is under the control of the APIVSXML. The input to be “generated” and passed to
the FPM is stored in human-readable flat files that may be referenced by the APIVSXML.
5.4
Multiple FPUI Processes
Multiple FPUI processes are supported by allowing multiple instances of the VSE to be run simultaneously. 17 VSE
processes may be thusly invoked, to allow for all 16 concurrent displays to be active at one time, and an extra
process so that the behavior of the API can be seen when this 16 concurrent display limit is exceeded. The VSE
itself does not do anything “special” to support this functionality. These processes should be started up and staged
using a Linux shell script. Only one (1) of the VSE multiple processes must open the loopback device and process
the FPM commands.
ITE, 2017
Page 21/35
API Validation Suite
Design Specification, v2.0
5.5
Date: 2017-07-31
FPUI API Function Verification
This table illustrates how the various functions of the FPUI library may and will be verified by the VSE using the
APIVSXML. Not all possible methods are listed.
FPUI Function Name
Possible Verification Technique
fpui_apiver
Validated by return codes and comparing the returned
string against expected value.
fpui_clear
Validated by return codes and comparing the current VD
against a blank display.
fpui_clear_tab
Validated by return codes and examining VD after
setting tab stops, using the tab stops and then clearing
tab stops and advancing by a tab stop to see if the tab
stop is still present. Also possibly use
fpui_get_cursor_pos().
fpui_close
Validated by return codes and attempting a fpui_ call
after close is performed.
fpui_close_aux_switch
Validated by return codes and trying to
fpui_read_aux_switch() after closing switch.
fpui_compose_special_char
Validated by return codes and by calling
fpui_display_special_character() and looking at the VD
to see the character at the position that the special
character was written.
fpui_del_keymap
Validated by return codes and by sending input into the
VSE that would have mapped to the keymap sequence
that was just deleted and verifying that the sequence is
no longer mapped.
fpui_display_special_char
Validated by return codes and looking at VD to see if the
special character indicated was displayed.
fpui_get_auto_repeat
Validated by return codes and calling
fpui_set_auto_repeat().
fpui_get_auto_scroll
Validated by return codes and calling
fpui_set_auto_scroll().
fpui_get_auto_wrap
Validated by return codes and calling
fpui_set_auto_wrap().
fpui_get_backlight
Validated by return codes and calling
fpui_set_backlight().
fpui_get_character_blink
Validated by return codes and calling
fpui_set_character_blink().
ITE, 2017
Page 22/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
fpui_get_cursor
Validated by return codes and calling fpui_set_cursor().
fpui_get_cursor_blink
Validated by return codes and calling
fpui_set_cursor_blink().
fpui_get_cursor_pos
Validated by return codes and calling
fpui_set_cursor_pos().
fpui_get_focus
Validated by return codes and calling fpui_set_focus().
fpui_get_keymap
Validated by return codes and calling
fpui_set_keymap().
fpui_get_led
Validated by return codes and calling fpui_set_led().
fpui_get_reverse_video
Validated by return codes and calling
fpui_set_reverse_video().
fpui_get_underline
Validated by return codes and calling
fpui_set_underline().
fpui_get_window_attr
Validated by return codes and calling
fpui_set_auto_wrap(), fpui_set_auto_scroll(),
fpui_set_auto_repeat(), fpui_set_backlight(), and
fpui_set_backlight_timeout().
fpui_get_window_size
Validated by return codes and comparing the return
values to expected values.
fpui_home
Validated by return codes and calling fpui_get_cursor()
and writing characters and looking at the VD.
fpui_open
Validated by return codes and calling any other FPUI
function.
fpui_open_aux_switch
Validated by return codes and calling
fpui_read_aux_switch() and fpui_close_aux_switch().
fpui_poll
Validated by return codes and placing data on the FPUI
loopback port. The VSE will be able to run as separate
threads to be able to call fpui_poll() that blocks and then
write data to port.
fpui_read
Validated by return codes and need to be able to place
data on loopback port and be able to compare what was
returned with what was placed on port.
fpui_read_aux_switch
Validated by return codes and calling
fpui_open_aux_switch() and fpui_close_aux_switch().
The VSE will send the appropriate VT100 sequence on
the loopback port to make it "look" like the switch was
flipped.
ITE, 2017
Page 23/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
fpui_read_char
Validated by return codes and the VSE will be able to
place data on loopback port and will be able to compare
what was returned with what was placed on port.
fpui_read_string
Validated by return codes and the VSE will be able to
place data on loopback port and will be able to compare
what was returned with what was placed on port.
fpui_refresh
Validated by return codes and the VSE will be able to
compare VD against the expected contents.
fpui_reset_all_attributes
Validated by return codes and calling
fpui_get_window_attr().
fpui_reset_keymap
Validated by return codes and calling
fpui_get_keymap().
fpui_set_auto_repeat
Validated by return codes and calling
fpui_get_auto_repeat().
fpui_set_auto_scroll
Validated by return codes and calling
fpui_get_auto_scroll().
fpui_set_auto_wrap
Validated by return codes and calling
fpui_get_auto_wrap().
fpui_set_backlight
Validated by return codes and calling
fpui_get_backlight().
fpui_set_backlight_timeout
Validated by return codes and calling
fpui_get_window_attr().
fpui_set_character_blink
Validated by return codes and calling
fpui_get_character_blink().
fpui_set_cursor
Validated by return codes and calling fpui_get_cursor().
fpui_set_cursor_blink
Validated by return codes and calling
fpui_get_cursor_blink().
fpui_set_cursor_pos
Validated by return codes and calling
fpui_get_cursor_pos() and by writing characters and
then looking at the VD.
fpui_set_emergency
Validated by return codes and verify that the API starts
sending backlight on/off commands. Then the VSE will
be able a context switch and look for the reverse video
and character blink commands and verify the affected
text string matches the name of the VSE application.
ITE, 2017
Page 24/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
fpui_set_keymap
Validated by return codes and calling
fpui_get_keymap() and also sending input in and see
that it is mapped by reading the resulting mapped string
using fpui_read_string().
fpui_set_led
Validated by return codes and calling fpui_get_led().
fpui_set_reverse_video
Validated by return codes and calling
fpui_get_reverse_video().
fpui_set_tab
Validated by return codes and calling fpui_clear_tab()
and by setting tabs, and trying to display a table and then
comparing the VD against expected display.
fpui_set_underline
Validated by return codes and calling
fpui_get_underline().
fpui_set_window_attr
Validated by return codes and calling
fpui_get_window_attr().
fpui_write
Validated by return codes and then comparing VD
against expected display.
fpui_write_at
Validated by return codes and then comparing VD
against expected display.
fpui_write_char
Validated by return codes and then comparing VD
against expected display.
fpui_write_char_at
Validated by return codes and then comparing VD
against expected display.
fpui_write_string
Validated by return codes and then comparing VD
against expected display.
fpui_write_string_at
Validated by return codes and then comparing VD
against expected display.
Table 8. FPUI API Function Verification
ITE, 2017
Page 25/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
6. FIO Validation
This section describes how the various functions of the FIO library may and will be verified by the VSE using the
APIVSXML. Not all possible methods are listed.
6.1
FIO Loopback Cable
The VSE employs a loopback cable for FIO validation. This loopback cable connects a FIOD port to a serial port
that the VSE will open. This serial port must support SDLC. The VSE adjusts the baud rate of this appropriately.
The VSE will receive FIOD SDLC Command Messages on this port and will feed these messages to a SDLC
Command Message Processor / Emulator, described below. The VSE also has the ability, as instructed by the
APIVSXML, to generate SDLC Response Messages that will be sent to the FIOM. This is described in greater
detail below.
6.2
SDLC Command Message Processing / Emulating
The VSE supports a SDLC Command Message Processor / Emulator to interpret and process Command Messages
sent by the FIOM. This processor maintains the last Command Message received, of each Command Message
Frame type, so that comparison and validation can be performed by the VSE as instructed by the APIVSXML. This
Command Message Frame may be interrogated and compared against the expected Command Message Frame at
any point in time, as specified by the APIVSXML. Expected Command Message Frames are kept in humanreadable flat files that may be referenced by the APIVSXML.
6.3
SDLC Response Message Processing
The VSE supports the ability to generate SDLC Response Messages to the FIOM as if an FIOD was actually
attached to the system. The generation of this input is under the control of the APIVSXML. The input to be
“generated” and passed to the FIOM is stored in human-readable flat files that may be referenced by the
APIVSXML.
6.4
Multiple FIO Processes
Multiple FIO processes are supported by allowing multiple instances of the VSE to be run simultaneously. Multiple
VSE processes may be thusly invoked, to allow for all 16 concurrent FPUI and FIOD accesses to be active at one
time, and an extra process so that the behavior of the API can be seen when the 16 concurrent FPUI limit is
exceeded. The VSE itself does not do anything “special” to support this functionality. These processes should be
started up and staged using a Linux shell script. Only one (1) of the VSE multiple processes must open the loopback
device and process the FIOM commands.
ITE, 2017
Page 26/35
API Validation Suite
Design Specification, v2.0
6.5
Date: 2017-07-31
FIO API Function Verification
This table illustrates how the various functions of the FIO library may and will be verified by the VSE using the
APIVSXML. Not all possible methods are listed.
FIO Function Name
Possible Verification Technique
fio_apiver
Validated by return codes and comparing the returned
string against expected value.
fio_deregister
Validated by return codes and calling a fio_ function
afterwards and verifying it fails. In addition, it will be
desirable to have multiple fio_ accessing VSE processes
that allocate resources, such as FIODs, and then ensure
that the precedence levels for various resources, such as
message frequency, are dropped to the next subsequent
level upon calling fio_deregister() by the allocating VSE
process. This precedence level may be observed using
FIO_VIEW argument on many fio_ system resource
functions. It may be useful to look at SDLC Command
messages, if any, as well.
fio_fiod_channel_map_count
Validated by return codes and calling
fio_fiod_channel_map_get() using the returned value.
fio_fiod_channel_map_get
Validated by return codes and calling
fio_fiod_channel_map_set() and ensuring what was set
is what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function.
fio_fiod_channel_map_set
Validated by return codes and calling
fio_fiod_channel_map_get() and ensuring what was set
is what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_fiod_channel_reservation_get
Validated by return codes and calling
fio_fiod_channel_reservation_set() and ensuring what
was set is what was returned. Multiple VSE processes
will be desirable to test the FIO_VIEW_SYSTEM
feature of this API function. Also, to test and ensure that
a channel can only be reserved by one application.
fio_fiod_channel_reservation_set
Validated by return codes and calling
fio_fiod_channel_reservation_get() and ensuring what
was set is what was returned. Multiple VSE processes
will be desirable to test the FIO_VIEW_SYSTEM
feature of this API function. Also, to test and ensure that
a channel can only be reserved by one application. It
may be useful to look at SDLC Command messages, if
any, as well.
ITE, 2017
Page 27/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
fio_fiod_cmu_dark_channel_get
Validated by return codes and calling
fio_fiod_cmu_dark_channel_set() and ensuring what
was set is what was returned. Multiple VSE processes
will be desirable to test the FIO_VIEW_SYSTEM
feature of this API function.
fio_fiod_cmu_dark_channel_set
Validated by return codes and calling
fio_fiod_cmu_dark_channel_get() and ensuring what
was set is what was returned. Multiple VSE processes
will be desirable to test the FIO_VIEW_SYSTEM
feature of this API function. It may be useful to look at
SDLC Command messages, if any, as well.
fio_fiod_cmu_fault_get
Validated by return codes and calling
fio_fiod_cmu_fault_set() and ensuring what was set is
what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function.
fio_fiod_cmu_fault_set
Validated by return codes and calling
fio_fiod_cmu_fault_get() and ensuring what was set is
what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_fiod_deregister
Validated by return codes and calling a fio_fiod_
function afterwards and verifying it fails. In addition, it
will be desirable to have multiple fio_fiod_ accessing
VSE processes that allocate resources and then ensure
that the precedence levels for various resources, such as
message frequency, are dropped to the next subsequent
level upon calling fio_fiod_deregister() by the allocating
VSE process. This precedence level may be observed
using FIO_VIEW argument on many fio_ system
resource functions. It may be useful to look at SDLC
Command messages, if any, as well.
fio_fiod_disable
Validated by return codes and calling fio_fiod_enable()
and ensuring that requesting a message be sent results in
no messages being sent. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function.
fio_fiod_enable
Validated by return codes and calling fio_fiod_disable()
and ensuring that a command message that was
scheduled to be sent is actually sent. Multiple VSE
processes will be desirable to test the
FIO_VIEW_SYSTEM feature of this API function.
Also, it is desirable to look for Command Module Status
frame messages. It will be necessary to queue up a
response message when the fio_fiod_enable() is called.
ITE, 2017
Page 28/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
fio_fiod_frame_notify_deregister
Validated by return codes and calling
fio_fiod_frame_notify_register () a verifying that it is
possible to deregister the notify. The VSE will be able
to queue up response frames for which notifies have
been registered; to ensure that notifications for this
frame is no longer given.
fio_fiod_frame_notify_register
Validated by return codes and calling
fio_fiod_frame_notify_deregister() a verifying that it is
possible to deregister the notify. The VSE will be able
to queue up response frames for which notifies have
been registered; to ensure that notifications for this
frame is received.
fio_fiod_frame_read
Validated by return codes and comparing a response
frame read against what was passed as by response
frame by the VSE.
fio_fiod_frame_schedule_get
Validated by return codes and calling
fio_fiod_frame_schedule_set() and ensuring what was
set is what was returned. Multiple VSE processes will
be desirable to test the FIO_VIEW_SYSTEM feature of
this API function.
fio_fiod_frame_schedule_set
Validated by return codes and calling
fio_fiod_frame_schedule_get() and ensuring what was
set is what was returned. Multiple VSE processes will
be desirable to test the FIO_VIEW_SYSTEM feature of
this API function.
fio_fiod_frame_size
Validated by return codes and having the VSE, via the
APIVSXML, queue up response frames and ensuring
what was queued is what was received.
fio_fiod_inputs_filter_get
Validated by return codes and calling
fio_fiod_inputs_filter_set() to ensure what was set is
what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function.
fio_fiod_inputs_filter_set
Validated by return codes and calling
fio_fiod_inputs_filter_get() to ensure what was set is
what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function.
fio_fiod_inputs_get
Validated by return codes and looking at the SDLC
Command Message generated. The VSE will, as
commanded by the APIVSXML, send a response
message. The input points that this API function says
are set must match what the VSE sent as a response.
ITE, 2017
Page 29/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
fio_fiod_inputs_trans_get
Validated by return codes and calling
fio_fiod_inputs_trans_set() to ensure what was set is
what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function.
fio_fiod_inputs_trans_read
Validated by return codes and calling
fio_fiod_inputs_trans_set(). Also, the VSE will be able,
via the APIVSXML, to send many point transitions so as
to be able to test the handling of the
FIO_TRANS_STATUS argument.
fio_fiod_inputs_trans_set
Validated by return codes and calling
fio_fiod_inputs_trans_get() to ensure what was set is
what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_fiod_mmu_flash_bit_get
Validated by return codes and calling
fio_fiod_mmu_flash_bit_set() to ensure what was set is
what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function.
fio_fiod_mmu_flash_bit_set
Validated by return codes and calling
fio_fiod_mmu_flash_bit_get() to ensure what was set is
what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_fiod_outputs_get
Validated by return codes and calling
fio_fiod_outputs_set() to ensure what was set is what
was returned. Multiple VSE processes will be desirable
to test the FIO_VIEW_SYSTEM feature of this API
function.
fio_fiod_outputs_reservation_get
Validated by return codes and calling
fio_fiod_outputs_reservation_set() to ensure what was
set is what was returned. Multiple VSE processes will
be desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_fiod_outputs_reservation_set
Validated by return codes and calling
fio_fiod_outputs_reservation_get() to ensure what was
set is what was returned. Multiple VSE processes will
be desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
ITE, 2017
Page 30/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
fio_fiod_outputs_set
Validated by return codes and calling
fio_fiod_outputs_get() to ensure what was set is what
was returned. Multiple VSE processes will be desirable
to test the FIO_VIEW_SYSTEM feature of this API
function. It may be useful to look at SDLC Command
messages, if any, as well.
fio_fiod_register
Validated by return codes and calling a fio_fiod_
function afterwards and verifying they succeed. In
addition, it will be desirable to have multiple fio_fiod_
accessing VSE processes that allocate resources and then
ensure that the precedence levels for various resources,
such as message frequency, are adhered to as FIOD
resources are utilized. This precedence level may be
observed using FIO_VIEW argument on many fio_
system resource functions. It may be useful to look at
SDLC Command messages, if any, as well. Finally,
ensure that no command messages are received, since
fio_fiod_enable() has not yet been called.
fio_fiod_status_get
Validated by return codes, calling
fio_fiod_status_reset(), sending a known number of
response messages and ensuring the counts returned
match what was sent and finally verifying the
information returned in FIO_FRAME_INFO against
expected values.
fio_fiod_status_reset
Validated by return codes and calling
fio_fiod_status_get() to ensure all counts have been reset
to 0.
fio_fiod_ts_fault_monitor_get
Validated by return codes and calling
fio_fiod_ts_fault_monitor_set() to ensure what was set is
what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_fiod_ts_fault_monitor_set
Validated by return codes and calling
fio_fiod_ts_fault_monitor_get() to ensure what was set
is what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_fiod_ts1_volt_monitor_get
Validated by return codes and calling
fio_fiod_ts1_volt_monitor_set() to ensure what was set
is what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
ITE, 2017
Page 31/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
fio_fiod_ts1_volt_monitor_set
Validated by return codes and calling
fio_fiod_ts1_volt_monitor_get() to ensure what was set
is what was returned. Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_fiod_wd_deregister
Validated by return codes and calling
fio_fiod_wd_reservation_get(),
fio_fiod_wd_reservation_set(), fio_fiod_wd_heartbeat()
and fio_fiod_wd_register(). Multiple VSE processes
will be desirable to test the FIO_VIEW_SYSTEM
feature of this API function. It may be useful to look at
SDLC Command messages, if any, as well.
fio_fiod_wd_heartbeat
Validated by return codes and calling
fio_fiod_wd_reservation_get(),
fio_fiod_wd_reservation_set(), fio_fiod_wd_deregister
() and fio_fiod_wd_register(). Multiple VSE processes
will be desirable to test the FIO_VIEW_SYSTEM
feature of this API function. It may be useful to look at
SDLC Command messages, if any, as well.
fio_fiod_wd_register
Validated by return codes and calling
fio_fiod_wd_reservation_get(),
fio_fiod_wd_reservation_set(), fio_fiod_wd_heartbeat()
and fio_fiod_wd_deregister(). Multiple VSE processes
will be desirable to test the FIO_VIEW_SYSTEM
feature of this API function. It may be useful to look at
SDLC Command messages, if any, as well.
fio_fiod_wd_reservation_get
Validated by return codes and calling
fio_fiod_wd_reservation_set(), fio_fiod_wd_register(),
fio_fiod_wd_heartbeat() and fio_fiod_wd_deregister().
Multiple VSE processes will be desirable to test the
FIO_VIEW_SYSTEM feature of this API function. It
may be useful to look at SDLC Command messages, if
any, as well.
fio_fiod_wd_reservation_set
Validated by return codes and calling
fio_fiod_wd_reservation_get(), fio_fiod_wd_register(),
fio_fiod_wd_heartbeat() and fio_fiod_wd_deregister().
Multiple VSE processes will be desirable to test the
FIO_VIEW_SYSTEM feature of this API function. It
may be useful to look at SDLC Command messages, if
any, as well.
fio_hm_deregister
Validated by return codes and calling
fio_hm_fault_reset(), fio_hm_heartbeat() and
fio_hm_register(). Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
ITE, 2017
Page 32/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
fio_hm_fault_reset
Validated by return codes and calling
fio_hm_deregister(), fio_hm_heartbeat() and
fio_hm_register(). Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_hm_heartbeat
Validated by return codes and calling
fio_hm_deregister(), fio_hm_fault_reset() and
fio_hm_register(). Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_hm_register
Validated by return codes and calling
fio_hm_deregister(), fio_hm_fault_reset() and
fio_hm_heartbeat (). Multiple VSE processes will be
desirable to test the FIO_VIEW_SYSTEM feature of
this API function. It may be useful to look at SDLC
Command messages, if any, as well.
fio_query_fiod
Validated by return codes. The VSE will be able to
generate a SDLC response message to the query for the
FIOD. Based upon if a response was sent or not, the
return code should be set accordingly.
fio_query_frame_notify_status
Validated by return codes and calling
fio_fiod_frame_notify_register() and
fio_fiod_frame_notify_deregister(). The VSE will be
able to send response frames that can be notified and
then use this function, via the APIVSXML, to see why a
notify was performed.
fio_register
Validated by return codes and calling any subsequent
fio_ function.
Table 9. FIO API Function Verification
ITE, 2017
Page 33/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31
7. Add and Remove API Functions
The VSE has been designed in such a way as to allow the addition (or subtraction) of new (or the removal of
depreciated) API functions, as needed. In addition, if it is determined that a special sequence of API function calls
needs to occur, as might be the case if special timing considerations are needed (the VSE currently does NOT
support timing related functionality), a special “function” may be written in C code and added to the VSE function
tables; and thus may be invoked and called via the APIVSXML.
7.1
Adding a New Function
In order to add a new API function to the VSE, the following steps must be taken:

In the file “function.c” is a table named s_funcTable[]. This table contains the mapping of function names,
as referenced by the APIVSXML, the physical API handler / interface function in the VSE code to call, the
API function return type, API function arguments, API function argument types, and API function
argument input / output designations.

The VSE developer should study this table and become familiar with its content and structure. The
structure of this table is defined in “function.h”.

Once the VSE developer is familiar with this table and structure, the developer may add a new row to this
table for the particular function being added. This table is not sorted, so no consideration for sorting needs
to be made.

The added table element must specify a unique APIVSXML string to a specific VSE API handler /
interface function to be called. The added table element must also specify the API function return type, the
API function arguments, the API function argument types, and the API function argument input / output
designations. API functions currently allow up to 6 arguments to be defined. As such, the new function
can support up to 6 arguments. If more arguments are required for the new API function, the #define
ARG_MAX(6) must be modified in “argument.h” and all associated places where ARG_MAX is
referenced or used must be checked to see if any additional modification are needed. If the number of
arguments to the new API function is 6 or less, no additional considerations are required.

If a new variable type is required (such as a new typedef value) then this new type must be added to
“argument.h” and all associated code in “argument.c” must be changed or added; including all type casting
operations, output formatting operations, named constant definitions, named constant string tables, type
parsing operations, variable definitions of the new type, and variable set operations.

For every new API function, a corresponding VSE handler / interface function must be written. This VSE
function handles the interface between the VSE variables and the actual call to the API function. The best
way to write one of these functions is to use an existing function as a template. A good template to use is
either the API function fio_fiod_channel_reservation_get VSE handler / interface function
funcFioFiodChannelReservationGet or API function fio_fiod_channel_reservation_set VSE handler /
interface function funcFioFiodChannelReservationSet.

All VSE handler / interface functions have a common interface when called by the VSE. This interface is
the line number in the APIVSXML file of the line currently being executed and a pointer to a C_FUNC
structure as defined in “function.h”. The line number is used for error reporting, if the VSE handler /
interface function encounters a fatal error during processing; a malloc() failure, a NULL pointer exists
when not expected, for example. The API function failing is NOT a fatal error in this context. This type of
failure is handled and processed by the APIVSXML language interpreter. The C_FUNC structure specifies
the arguments to be passed to the API function and how to access them. Assuming that the function table
entry added above was done correctly, the VSE handler / interface function can assume that all VSE items
are set correctly in this structure and act accordingly.
ITE, 2017
Page 34/35
API Validation Suite
Design Specification, v2.0
Date: 2017-07-31

The VSE handler / interface function must not allow the API function to actually access data structures
controlled by the VSE. Instead, the VSE handler / interface function must make copies of both input and
output arguments and copy them from / to the VSE data space as needed; very similar to what the Linux
operating system does between kernel and user space. This is done to protect the VSE space from possible
corruption by an API function call.
The funcFioFiodChannelReservationGet and
funcFioFiodChannelReservationSet VSE handler / interface calls are good examples of this.

Finally, the VSE must be recompiled for the change to take effect.

New functions must not write directly to stdout or stderr. All error reporting and output must be done using
routines provided in outputXML.c.
7.2
Removing an Existing Function
In order to remove an API function from the VSE, the following steps must be taken:
7.3

In the file “function.c” is a table named s_funcTable[]. This table contains the mapping of function names,
as referenced by the APIVSXML, the physical function in the VSE code to call, the API function return
type, API function arguments, API function argument types, and API function argument input / output
designations.

The VSE developer should study this table and become familiar with its content and structure. The
structure of this table is defined in “function.h”.

Once the VSE developer is familiar with this table and structure, the developer may remove the desired row
from this table for the particular function being removed. This table is not sorted, so no consideration for
sorting needs to be made. nFocal recommends not removing a variable type, even if they are no longer
required. Removing a variable and ensuring that all bases associated with its removal have been covered is
a long and meticulous process, if done correctly. Leaving the no longer used variable type will not cause
any problems.

Once an API function has been removed from the table, all APIVSXML files that reference that API
function name will be invalidated.

Finally, the VSE must be recompiled for the change to take effect.
Adding New, APIVSXML-Callable, Functionality to the VSE
The VSE has been designed in such a way as to allow new VSE functionality to be added that may be invoked by
the APIVSXML. An example of such potential functionality would be a timing specific routine to do a sequence of
functionality in a time critical real-time fashion. To add this type of functionality to the VSE, follow the instructions
laid out in Section 7.1 Adding a New Function, above. The specific VSE functionality would then be written in C as
a VSE API handler / interface function.
ITE, 2017
Page 35/35