Technical Documentation: General Design of the PA
From Go4IT project
[edit]
Introduction
- This document intends to provide a preliminary introduction to the design of the Platform Adaptor (hereafter, PA) entity whithin a TTCN-3 test system. This entity is responsible for implementing TTCN-3 external functions and provides a TTCN-3 test system with a single notion of time. In this entity, external functions are to be implemented as well as all timers. Notice that timer instances are created in the TE. A timer in the PA can only be distinguished by its Timer IDentification (TID). Therefore, the PA treats both explicit and implicit timers in the same manner.
- The interface with the TE enables the invocation of external functions and the starting, reading, and stopping of timers as well as the inquiring of the status of timers using their timer ID. The PA notifies the TE of expired timers.
- The design of this PA module has been performed according to two different ATSs: IPv6 Core protocol (See [8]) and RIPng protocol(See [6]).
[edit]
Use Cases
- This section contains a set of use cases that describe the external behavior of this PA module. A use case is a description of a specific interaction that a user (or another module) may have with this module. Use cases are deceptively simple tools for describing the functionality of the software.
- A use case is a simple, straightforward tool that can be used to completely describe all the behavior of a piece of software. It contains a textual description of all the ways that the intended users could work with the software through its interface. Use cases do not describe any internal workings of the software, nor do they explain how that software will be implemented. They simply show the steps that the user follows to use the software to do his work. All the ways that the users interact with the software can be described in this manner.
- This section will contain multiple use cases, enough to define all of the interactions the users will have with the module.
- In the following figure, a general overview of defined use cases and relationships between the different actors (i.e., users) which have been defined in this section is shown.
[edit]
UC-1: Starting the timer
Summary
- To indicate that a timer starts running.
Rationale
- TE needs a timer to start an incremental count.
Actors
- TE
Preconditions
- There is not preconditions because this is the initial use case.
Basic Course of Events
- Step1: TE requires to PA to start a timer.
- Step2: PA starts the indicated timer with the specified duration.
- Step3: The timer runs from the initial value (0) up to the maximum specified by TE on invocation.
Alternative Paths
- If the timer indicated by TE is already running, then it has to be restarted.
Postconditions
- PA indicates TE if the timer has been started successfully, error otherwise.
[edit]
UC-2: Reading the timer
Summary
- To retrieve the remaining time to finish the count.
Rationale
- TE retrieves the time that has elapsed time since the specified timer was started (UC-1) and to store it for any later purpose.
Actors
- TE
Preconditions
- See UC-1. The timer is started to retrieve the elapsed time.
Basic Course of Events
- Step1: TE requires reading the elapsed time since the specific timer was started.
- Step2: PA indicates the elapsed time in seconds.
Alternative Paths
- If the timer is not running, then returned value is zero.
Postconditions
- Timer is not stopped.
[edit]
UC-3: Stopping the timer
Summary
- To stop a specific timer.
Rationale
- TE requires that a specific timer must be stopped.
Actors
- TE
Preconditions
- The timer to be stopped has been started. See UC-1.
Basic Course of Events
- Step1: TE requires stopping a specific timer.
- Step2: PA stops the specific timer. The timer is not erased, i.e., the count is not set to the value zero.
- Step3: If the timer is correctly stopped, then PA notifies TE the successful operation
- Step4: If an active timer is not stopped, then PA notifies TE the unsuccessful operation
Alternative Paths
- If the timer is has stopped, then the returned value is a correct operation.
Postconditions
- Timer is stopped.
[edit]
UC-4: Timeout notification
Summary
- To report that the timer has expired.
Rationale
- The counter has just become zero value. PA notifies TE that the timer has expired.
Actors
- TE
Preconditions
- The timer needs to be started in order to expire. See UC-1.
Basic Course of Events
- Step1: TE is ready to listening timer notifications.
- Step2: Counter of the timer becomes zero value.
- Step3: PA notifies to the TE that a specific timer has expired
- Step4: TE listens the notification and continue executing
Alternative Paths
- The order of steps 1 and 2 depends on particular test execution and it is not relevant for this use case.
Postconditions
- Timer remains in idle state with its set to value zero.
[edit]
UC-5: Checksum for sending ICMPv6 or UDP packets
Summary
- To assess the checksum for any ICMPv6 or UDP packet to be sent.
Rationale
- When an ICMPv6 or UDP packet is ready to be sent, the computation of associated checksum is needed in order to provide integrity.
Actors
- TE
Preconditions
- TE implements ICMPv6 or UDP protocol test cases.
Basic Course of Events
- Step1: TE fills the different IPv6 packet fields according to the protocol (ICMPv6 or UDP).
- Step2: TE requests PA the computation of the checksum of the packet.
- Step3: PA calculates the checksum and sends the result to the TE.
Alternative Paths
- No alternative paths.
Postconditions
- TE fills the checksum field into packet using the value computed by PA.
[edit]
UC-6: Checksum for receiving ICMPv6 or UDP packet
Summary
- To assess and verify the checksum for any ICMPv6 or UDP packet received from IUT.
Rationale
- When an ICMPv6 or UDP packet is received from the IUT, TE needs to verify the integrity of the packet comparing the checksum field received and a new checksum value calculated using the packet received as input.
Actors
- TE
Preconditions
- TE implements ICMPv6 or UDP protocol.
Basic Course of Events
- Step1: TE receives a ICMPv6 or UDP packet.
- Step2: TE requests to PA compute the checksum of the packet.
- Step3: PA calculates the checksum and sends the result to the TE.
Alternative Paths
- No alternative paths.
Postconditions
- TE compares the value calculated in step 3 with the value extracted and calculated from the packet received in step 1.
[edit]
Specific Use Cases for RIPng ATS (See [6]))
[edit]
UC-7: Frame length
Summary
- To assess the length of the frame to be sent.
Rationale
- When a frame is going to be sent or is going to be analyzed by TE, the frame length is required for these operations.
Actors
- TE
Preconditions
- TE wants to send a frame to the IUT. As well, TE may want to analyze a frame.
Basic Course of Events
- Step1: TE wants to send a frame to the IUT or analyze it during a reception operation.
- Step2: TE requests to PA compute the frame length.
- Step3: PA calculates the frame length and sends the final result to the TE.
Alternative Paths
- The order of steps 1, 2 and 3 is out of scope of PA.
Postconditions
- TE has the frame length and is ready to send the packet or other type of operation.
[edit]
UC-8: Get timestamp of a test case
Summary
- To retrieve the timestamp of a test case.
Rationale
- When a test case is ready to be executed, the computation of timestamp may be needed for logging operations.
Actors
- TE
Preconditions
- TE executes a test case.
Basic Course of Events
- Step1: TE creates a message to be sent via SA.
- Step2: TE creates a message to be sent via SA.
- Step3: TE saves the timestamp and stores it for subsequent operations (e.g., logging operations).
Alternative Paths
- The order of steps 1, 2 and 3 is out of scope of PA.
Postconditions
- TE obtains the timestamp of the execution of the test case.
[edit]
Specific Use Cases for Core Protocol ATS (See [8])
[edit]
UC-9: Payload Length
Summary
- To assess the payload length of an IPv6 Packet.
Rationale
- When the payload length of an IPv6 packet is larger than MTU (PMTU discovery process), then, IPv6 packet must be fragmented. Therefore, the TE needs to determine the length of the IPv6 packet before sending it to the IUT.
Actors
- TE
Preconditions
- TE implements ICMPv6 protocol test cases.
Basic Course of Events
- Step1: Path MTU Discovery process is performed.
- Step2: To send a message to the IUT with MUT of the link.
- Step3: If an ICMP error message is received, then resend the message with the new MTU.
- Step4: Step 2 and 3 until response from destination is received.
- Step5: If new packets have to be sent, the packets need to be fragmented and therefore to compute the length of the payload is need for this purpose.
Alternative Paths
- Step 3 is performed only if the first tentative fails.
Postconditions
- The length of the payload is available to be used to compute the fragmentation procedure.
[edit]
Functional Requirements
[edit]
FR-1: Timer accuracy
Summary
- The capability of the timer for finishing the count in a time near to the real magnitude.
Rationale
- TE relies on PA to achieve a good data quality concerning on the timing features.
Requirements
- The accuracy must be 500 millisecond.
References
[edit]
FR-2: Timer precision
Summary
- The capability of the different instances of the timer for finishing the count in the same time, under the same conditions.
Rationale
- TE relies on PA to achieve a determinist test case execution. The same test case must be given always the same verdict under the same conditions.
Requirements
- The precision must be parameterized according to the PIXIT value: PX_TIMER_PRECISION.
References
[edit]
FR-3: Timer resolution
Summary
- The granularity of the value to be set on the timer.
Rationale
- The quality of the timer must be aligned with the IPv6 protocol needs.
Requirements
- The resolution must be 500 milisecond.
References
[edit]
FR-4: Group of timers
Summary
- Several timers must be active at the same time.
Rationale
- IPv6 TTCN-3 specification makes possible the management of several timers. PA must support this functionality.
Requirements
- The number of active timers must not affect quality parameters of other timers (FR-1, FR-2 and FR-3).
Each timer must be uniquely identified with an one-to-one identifier. References
[edit]
FR-5: PA (timer part) compliant with TRI specification
Summary
- Capability for each timer to start, to read the time elapsed, to stop a timer, to check the state and timeout notification.
Rationale
- Upper boundary interface of PA must be compliant with TRI specification so that timer functionalities specified for this interface must be supported by the PA implementation.
Requirements
- On invocation of triStartTimer the PA shall start the indicated timer with the indicated duration.
- On invocation of triStopTimer the PA shall use the unique identifier to stop only the indicated timer instance.
- On invocation of triReadTimer the PA shall use the unique identifier to access the time that elapsed since this timer was started. The value must return in seconds. If the timer is not active, the returned value must be zero.
- On invocation of triTimerRunning the PA shall use the unique identifier to access the status of the timer.
- After a timer, which has previously been started, has expired the PA must call triTimeout indicating the unique identifier of the timer.
References
[edit]
FR-6: ICMPv6 Checksum
Summary
Rationale
- To calculate the checksum of a ICMPv6 message is needed. To fill the checksum field when TE sends an ICMPv6 message (UC-5) and to verify the checksum when TE receives ICMPv6 messages (UC-6).
Requirements
- See RFC 2463. Section 2.3
- “The checksum is the 16-bit one's complement of the one's complement sum of the entire ICMPv6 message starting with the ICMPv6 message type field, prepended with a "pseudo-header" of IPv6 header fields, as specified in [IPv6, section 8.1]. The Next Header value used in the pseudo-header is 58.
- (NOTE: the inclusion of a pseudo-header in the ICMPv6 checksum is a change from IPv4; see [IPv6] for the rationale for this change.) For computing the checksum, the checksum field is set to zero.”.
References
[edit]
FR-7: Safety shutdown of timer
Summary
- To assure a safety removal of active timers when the TE finishes.
Rationale
- When TE finishes unexpectedly, it is possible that timers are already running. Spurious timers must be avoided.
Requirements
- PA must release all the resources allocated to manage the instances of the timers.
References
[edit]
FR-8: PA (external functions part) compliant with TRI specification
Summary
- To implement the external functions defined to be TTCN-3 external in IPv6 test suite.
Rationale
- Upper boundary interface of PA must be compliant with TRI specification so that the external functions must be supported by the PA implementation.
Requirements
- To implement the common routine triExternalFunction invoked by TE when it calls any external function.
- triExternalFunction must be capable to manage the parameters received from the TE when it invokes an external function.
- To execute the appropriate external function (functionId).
- To extract the incoming parameters (parameterList).
- To fill with the appropriate values the outcoming parameters (parameterList).
- To return the appropriate value (returnValue).
- triExternalFunction must support all the external functions declared by the different TTCN-3 IPv6 Test suites:
References
[edit]
Nonfunctional Requirements
[edit]
NF-1: Documentation
Summary
- Detailed description of developed software.
Rationale
- Documentation is a communicable material needed to describe the structure and components implemented. It also includes the programmer manual.
Requirements
- The documentation will consist of:
- Software architecture of PA.
- Dependency with other parties (using a relationship or flow diagrams).
- Flow diagrams for each TRI routine implemented (or functions using TRI routines)
- The documentation will be divided into component parts and for each one the following documentation will be provided:
- Component description.
- Reference to the specification (this document).
- Component peculiarities.
- Component documentation.
- API documented in detail: parameters return value and behavioral description.
- Configuration and installation guidelines.
- Component distribution.
- Source code must be documented according to the rules established to edit Java code (i.e., javadocs). See also Developer's_Guide.
References
[edit]
NF-2: Maintainability
Summary
- This feature allows to measure the PA´s ability to be modified at low cost possible.
Rationale
- Ease with which the PA can be modified in order to correct faults, to improve performance, or other attributes, or to adapt to a changed environment (e.g., TE implements new test configuration or test cases).
Requirements
- It is needed to provide the measurement of the time period necessary to restore a normal functionality of the system following a failure. The implementation must be oriented to minimize the MTTR (Mean Time To Repair).
- PA capability to require the minimum changes when TE or IUT evolve including new external functions.
References
[edit]
NF-3: Reliability
Summary
- Reliability allows to measure the ability of the PA to perform and maintain its functionality in routine and also in different unexpected circumstances.
Rationale
- The establishment of good requirements and making a good design and implementation of the PA implies high software reliability. In this way an anticipation and design against unexpected consequences is achieved.
Requirements
- It is needed to provide the measurement of the time period between two consecutive failures of the system. The implementation must be oriented to minimize the MTBF (Mean Time Between Failure).
- It is needed to optimize:
- The capacity of the PA to perform as designed.
- The resistance to failure of the PA.
- The ability of the PA to perform the functional requirements under stated condition for a specified period of time.
- A reliability block diagram and a fault tree (diagram showing the relationship between faults: causes and consequence) must be included.
References
[edit]
NF-4: Extensibility
Summary
- Capacity to add new external functions to the PA without affecting functionalities already implemented.
Rationale
- New features for the IPv6 test system may appear, for example, to add new test cases, new networks interfaces, new test configurations.
Requirements
- PA implementation must offer the possibility to upgrade its programming code and static data according to changes agreed by the new versions of test specifications for IPv6 protocol.
- TTCN-3 Specification (TRI part) may be also updated in the future and therefore PA implementation must make easier a possible migration process.
- PA is able to implement new external function without affecting the functionality the external function already supported.
References
[edit]
NF-5: Performance
Summary
- PA temporary restrictions for run time.
Rationale
- PA is a subpart of a whole test system consisting of several software layers. PA is the lowest layer in the Test System and therefore the performance capabilities are a remarkable ability for PA. The performance of timers implemented must be considered.
Requirements
- PA must not cause 100% CPU usage (e.g. poll mechanism for multiple timer management must be avoided).
- TTCN-3 test system is not a real time environment. PA has not real time restrictions.
- The tolerance (respect to FR-1, FR-2 and FR-3) allowed for the implementation of the timers is:
- Resolution: ±10%
- Accuracy: ±10%
- Precision: ±10%
References
[edit]
NF-6: Efficiency
Summary
- Efficiency determines the amount of resources (such as time and storage) necessary to execute PA.
Rationale
- PA will consist of a set of algorithms which solve a given computational problem. Algorithms analysis is an important part which provides theoretical estimation of resources needed by any algorithm.
Requirements
- Each algorithm conforming the external functions (FR-6) will be analyzed.
- A document with an analytic analysis of the algorithms will be provided by the implementer.
- A document with an empirical analysis of the algorithms (execution) will be provided by the implementer.
- A document comparing analytic and empirical analysis will be provided by the implementer. Strong deviations between analytic and empirical results will be justified.
References
- FR-6.
[edit]
NF-7: Platform Compatibility
Summary
- Platform requirement to execute PA.
Rationale
- PA subsystem is part of test system that it will be complied and linked jointly in order to get the executable entity. All of them must be according to the same platform requirement.
Requirements
- Operating System: Linux, kernel 2.6.
- Compiler: gcc 3.4.
- Additional compiler features: POSIX library.
- They will be based on a design that focuses on C/C++ / Java interoperability:
- Detailed study on interoperability issues.
- Proposition of solution for interoperability problems.
- T3RTS (TTCN-3 Runtime System) will be implemented in C language. However, T3RTS on Java are currently put on the market and therefore it will be needed to develop an initial study to migrate a PA implemented in C to Java implementation (e.g. using JNI, Java Native Interface).
References
- See [3].
[edit]
NF-8: Dependency on other parties
Summary
- Dependency of PA with the other software elements conforming the test system.
Rationale
- PA interworks with other software entities to be clearly identified.
Requirements
- The dependencies must be clearly identified:
- Upper boundary of PA interface: T3RTS libraries.
- Lower boundary of PA interface: not present.
References
