Space Telecommunications Interface (STI) Requirements
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Down to Acronyms
Table of Contents
12. Normative Requirements
12.1 Hardware
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Up to top, or Down to Acronyms
Document hardware and interfaces.
12.1.1 Provide GPM
STI-1 An STI platform shall have a GPM that contains and executes the STI OE and the control portions of the STI applications and services software.
12.1.2 Diagnostic Information Availability
STI-2 A module’s diagnostic information shall be available via the STI APIs.
12.1.3 Document RF
STI-3 The STI platform provider shall describe, in the HID document, the behavior and performance of the RF modular component(s).
12.1.4 Document Power-Up State
STI-4 The STI platform provider shall describe, in the HID document, the state of all hardware devices after completion of power-up process.
12.1.5 Document Hardware Capability
STI-5 The STI platform provider shall describe, in the HID document, the behavior and capability of each major module or component available for use by a waveform, service, or other application (e.g., FPGA, GPP, DSP, or memory), noting any operational limitations.
12.1.6 Document Hardware Limitations
STI-6 The STI platform provider shall describe, in the HID document, the various capabilities, capacities, and any limitations of each reconfigurable component.
12.1.7 Document Interfaces
STI-7 The STI platform provider shall describe, in the HID document, the interfaces that are provided to and from each modular component of the STI platform.
12.1.8 Document the Control and Data Mechanisms
STI-8 The STI platform provider shall describe, in the HID document, the control, telemetry, and data mechanisms of each modular component (i.e., how to program or control each modular component of the platform, and how to use or access each device or software component, noting any proprietary and nonstandard aspects).
12.1.9 Document Power Supply
STI-9 The STI platform provider shall describe, in the HID document, the behavior and performance of any power supply or power converter modular component(s).
12.1.10 Document Thermal and Power Limits
STI-10 The STI platform provider shall describe, in the HID document, the thermal and power limits of the hardware at the smallest modular level to which power is controlled.
12.1.11 Controllable From OE
STI-11 If the STI application has a component resident outside the GPM (e.g., in configurable hardware design), then the component shall be controllable from the STI OE.
12.2 Configurable Hardware Design
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, ]12.7, 12.8, 12.9, or Up to top, or Down to Acronyms
12.2.1 Platform Specific Wrapper
STI-12 The STI SPM developer shall provide a platform specific wrapper for each FPGA, which performs the following functions:
- Provides an interface for command and data from the GPM to the waveform application.
- Provides the platform-specific pinout for the STI application developer. This may be a complete abstraction of the actual FPGA pinouts with only waveform application signal names provided.
12.2.2 Document FPGA Interfaces
STI-13 The STI SPM developer shall provide documentation on the configurable hardware design interfaces of the platform-specific wrapper for each FPGA, which describes the following:
- Signal names and descriptions.
- Signal polarity, format, and data type.
- Signal direction.
- Signal-timing constraints.
- Clock generation and synchronization methods.
- Signal-registering methods.
- Identification of development tool set used.
- Any included non-interface functionality.
12.3 Software
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Up to top, or Down to Acronyms
12.3.1 Document System Library Interfaces Provided
STI-14 The STI infrastructure provider shall document the supported system library interface(s) that are provided by the infrastructure, specifying any relevant standards or revisions.
12.3.2 Document System Library Interfaces Used
STI-15 The STI application provider shall document the supported system library interface(s) that are required by the application, specifying any relevant standards or revisions.
12.3.3 Document Language Interfaces Provided
STI-16 The STI infrastructure provider shall document the supported language interface(s) that are provided by the infrastructure, specifying any relevant standards or language revisions.
12.3.4 STI Infrastructure Uses APP API
STI-17 The STI infrastructure shall use the STI Application-provided Application Control Interfaces to control STI applications.
12.3.5 Use Language Specific Facilities Specified in Annex A
STI-18 Applications shall use the respective programming language’s designated facilities, such as a package, module, or header file(s), to refer to all STI infrastructure-provided entities as prescribed in Annex A: Language Translations.
12.3.6 Use Language Specific Inheritance
STI-19 Application object definitions shall use the programming language’s inheritance mechanisms to specify the set of STI interfaces that are implemented by the application (for object-oriented languages only).
12.3.7 Document STI Interfaces
STI-106 The STI infrastructure provider shall document the set of interfaces provided by the infrastructure.
12.3.8 Document Application’s System Library Interfaces
STI-107 The STI application developer shall document the set of operating system interfaces required by the application.
12.4 STI Infrastructure-Provided Software
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Up to top, or Down to Acronyms
The following items in section 12.4 are expected to appear in module STI.
12.4.1 STI Infrastructure-Provided Data Types
STI-20 The STI infrastructure shall define the basic data types as specified in Table 5.
Table 5: STI Variable TypesN | Type Name | Semantics | Usage/Description |
---|---|---|---|
1 | Access | Enumeration | Indicates desired access to a file. The specific possible values are described in Table 6. |
2 | CalendarKind | Enumeration | Identifies a specific method of time representation, such as TAI or UTC. The specific possible values are described in Table 7, CalendarKind Values. Because some time representations apply to space, date and time may be defined beyond the ISO standard for Date and Time [8601] on Earth. |
3 | CalendarTime | Abstract Structure or Class | An abstract object that identifies a specific time for a particular CalendarKind. All possible CalendarTime values are representable as a pointer or reference to this type. |
4 | FileSize | Integer | Represents a file size in bytes. The variable type should be able to represent the maximum file size among all the filesystems in the system, as well as uniquely identifiable values to indicate error conditions |
5 | HandleID | Integer | A handle ID is a single value that represents an STI application, device, file, or queue. It may be an index into a table or a pointer to more information for the item. The infrastructure defines the set of valid values for this type. |
6 | Instance | Structure or Class (base type) | The base type of all application and device context objects. All STI components have a corresponding object of this type stored by the infrastructure, although the object itself is not exposed to other applications. |
7 | Message | Abstract Structure or Class | The base type of all data exchange (Read, Write) buffers. All STI data exchange messages are representable as a pointer or reference to this type. |
8 | Nanoseconds | Integer | Indicates the number of nanoseconds (fractional part) within a TimeWarp object. This type can represent at least the range of [0, 999999999], and may be implemented using an “unsigned” value type, if available. |
9 | Offset | Integer | Indicates an offset from the beginning of a file or device address space. This type has a range capable of representing the last position in the largest file or device in the system. May be implemented using an “unsigned” value type, if available. |
10 | PropertyName | Integer, Enumeration or String | Identifies properties by name. May be implemented as a numeric enumeration in languages which support this, or as a string value in other environments. |
11 | PropertyValue | Abstract Structure or Class | The base type of all property values used with the property set interface (Configure, Query). All STI property values are representable as a pointer or reference to this type. |
12 | QueueMaxMessages | Integer | Represents the maximum number of messages allowed in a FIFO queue. |
13 | Result | Integer | Represents a status value, returned by many STI API calls. Specific predefined values represent error conditions, which are distinct from the set of valid results. See predefined values defined in Table 9, Result Values. |
14 | Seconds | Integer | Indicates the number of seconds (whole number part) of a TimeWarp object. Negative values represent time intervals in the past, and positive values indicate time intervals in the future. |
15 | TestID | Integer | Represents the built-in test or ground test to be performed by APP_RunTest. |
16 | TimeRate | Integer | Indicates the adjustment factor of clock components during adaptive sync and drift compensation. Positive values represent increased clock frequency/tick rates, negative values represent decreased frequency/tick rates, and a value of zero represents the nominal or “free-run” clock frequency. Units are implementation defined. |
17 | TimeWarp | Integer or Aggregate value (non-abstract) | The representation of an arbitrary time interval. Logically, this is a single, large value of fixed-point precision. The value should be at least 64 bits in size. If the largest native integer size is less than 64 bits on a given architecture, this may be defined as a structure or array to achieve the necessary range and precision. Units are implementation defined but are convertible to seconds and nanoseconds using the STI methods GetSeconds and GetNanoseconds. |
12.4.2 Application based on Instance Object
STI-21 The application base object shall be convertible to an Instance object as defined by the STI infrastructure.
12.4.3 STI Infrastructure-Provided Access Values
STI-22 The STI infrastructure shall provide the Access values as specified in Table 6.
Table 6: Access ValuesDeclaration |
|
---|---|
Description | Enumerate types of access to a file. |
Usage |
|
Notes | Used exclusively by the FileOpen() API call. See Section 12.7.27. |
12.4.4 STI Infrastructure-Provided CalendarKind Values
STI-23 The STI infrastructure shall provide the CalendarKind values as specified in Table 7.
Table 7: CalendarKind ValuesDeclaration |
|
---|---|
Description | Enumerate several well-defined time and date representations. |
Usage |
|
Notes | Platforms do not need to implement every defined calendar system. For those that are implemented, they should be implemented in a manner consistent with the name and specification indicated. Implementations may also define custom CalendarKind values for application-specific needs. Use of the LOCAL_TIME time and date representation in applications is discouraged, due to the inherent ambiguity. This is intended only for a user interface or display purpose. For more information on the specific time structures associated with these time and date representations, see section 12.4.14. |
12.4.5 STI Infrastructure-Provided HandleID Values
STI-24 The STI infrastructure shall provide the HandleID values as specified in Table 8.
Table 8: HandleID ValuesDeclaration (values are examples) |
|
---|---|
Description | A set of predefined values of the HandleID type that will be constant after initialization. |
Usage |
|
Notes | The HANDLEID_INVALID value is intended for use as an initializer, to avoid ambiguity in locally instantiated HandleID values. For instance, this can be used within an initializer list in a C++ class constructor, before the member is set to a real handle ID, to avoid potential undefined behavior if the destructor is invoked before the value is set to an actual handle ID. The actual queues do not need to be defined as “const” as long as they are defined during initialization of the OE before the need arises to log messages and not changed thereafter. Note: Applications should never check for specifically for the HANDLEID_INVALID value, but rather use the ValidateHandleID() API call. |
12.4.6 STI Infrastructure-Provided Result Values
STI-25 The STI infrastructure shall provide the Result values as specified in Table 9.
Table 9: Result ValuesDeclaration (values are examples) |
|
---|---|
Description | A set of predefined values of the Result type used as return values. |
Usage |
|
Notes | Values other than OK may also indicate success. Applications should never check for this value specifically, but rather use IsOK() to determine if an operation succeeded. An ERROR indicates component is operational, but the request may not be applicable to the component or may not be valid per the current component state. The caller should take action to correct the underlying issue before attempting the call again. The UNIMPLEMENTED value is intended to differentiate between a request that was successfully sent to the target but failed to execute, versus a request that was not sent to the target because it does not implement an optional interface. This may be treated similarly to an ERROR response. On error, a corresponding HandleID may be obtained using GetErrorQueue() to use with the Log() API for context information. |
12.4.7 STI Infrastructure-Provided Handle Name Values
STI-26 The STI infrastructure shall provide the Handle Name values as specified in Table 10.
Table 10: Handle Name ValuesDeclaration (values are examples) |
|
---|---|
Description | A set of predefined handle names. |
Usage |
|
Notes | These names may be passed to HandleRequest() to find the corresponding handle ID, which can then be used to interact with the target component. |
12.4.8 STI Infrastructure-Provided Property Name Values
STI-27 The STI infrastructure shall provide the Property Name values as specified in Table 11.
Table 11: Property Name ValuesDeclaration (values are examples) |
|
---|---|
Description | A set of predefined property names. |
Usage |
|
Notes | All applications, as well as the operating environment, will implement these property names. Devices may also implement these property names, but it is not required; for any devices provided by the platform, the values would generally match that of the OE. The values associated with these property names should be free-form strings. The PROVIDER value is usually a company name or university, followed by a subsidiary, division, or department name. The VERSION value is implementation-specific and may be of the format MAJOR.MINOR.REVISION and may also include additional identification information, such as a baseline version control revision ID or tag/branch if relevant. The STATE value is implementation-specific, and the meaning should be indicated by the application developer. |
12.4.9 STI Infrastructure-Provided Size Limit Values
STI-28 The STI infrastructure shall provide the Size Limit values as specified in Table 12.
Table 12: Size Limit ValuesDeclaration (values are examples) |
|
---|---|
Description | Establish a set of predefined values of known maximum size limits for various items. |
Usage |
|
Notes | These values are mainly intended for use in languages such as C/C++ where application developers are responsible for buffer allocation. In other languages, buffer allocation may occur automatically and as such these size limits may not be relevant. In C/C++ environments, these values will evaluate at compile time, such that they may be used as array dimensions. Note that for string length sizes, the value reflects the maximum number of actual characters in the string and does not take into account any terminating NUL character (‘\0’). The value should always be increased by 1 if the value is used in the dimension of a char[] array. |
12.4.10 STI Infrastructure-Provided TimeWarp Values
STI-29 The STI infrastructure shall provide the TimeWarp values as specified in Table 13.
Table 13: TimeWarp ValuesDeclaration (values are examples) |
|
---|---|
Description | Values suitable for usage with functions accepting a TimeWarp value. |
Usage |
|
Notes | The TIME_INTERVAL_UNLIMITED value is intended be used with functions such as TimeSynch(). When this value is passed as the stepMax argument, it indicates that the infrastructure may directly step the clock to any value. |
12.4.11 STI Infrastructure-Provided CalendarValueCivil Structure
STI-97 The STI infrastructure shall provide the CalendarValueCivil Structure definition and implementation as specified in Table 14.
Table 14: CalendarValueCivil Structure DefinitionDeclaration |
|
---|---|
Description | Definition of time representation type for the common era / Gregorian calendar. Member details:
|
Notes | This format is applicable to UTC and, usually, the local time representations. For local time representations, the specific offset from UTC and daylight savings configuration should be configured or queried separately through the property set interface. The nanoseconds field is intended to support applications that require higher precision time values. This does not imply that the underlying clock has nanosecond precision. For clocks that do not support higher precision timing, this field should always be set as zero. |
12.4.12 STI Infrastructure-Provided CalendarValueGPS Structure
STI-98 The STI infrastructure shall provide the CalendarValueGPS Structure definition and implementation as specified in Table 15.
Table 15: CalendarValueGPS Structure DefinitionDeclaration |
|
---|---|
Description | Definition of time representation expressed in weeks and seconds, similar to the style used in GPS navigation messages. Member details:
|
Notes | This is not an exact representation of GPS time codes, but rather a method of expressing time in terms that facilitate easy conversion to/from actual GPS navigation code formats while also providing higher precision. Legacy GPS navigation signals express the week number as a 10-bit integer, which rolls over every 1024 weeks, with time of week expressed as a 19-bit integer with 1.5 second resolution. Other navigation signals have a different format, using 13-bit week number along with a 2-hour interval time of week and 18-second time of interval. This structure expresses the time of week value in units of milliseconds. Conversion from legacy GPS time of week values is accomplished via multiplication by 1500 (1.5 seconds), and conversion from 18-second time of interval codes is accomplished via multiplication by 18000. Likewise, a conversion to whole seconds can be achieved by dividing the tow by 1000, and the day of week can be determined by dividing by 86400000. |
12.4.13 STI Infrastructure-Provided CalendarValueDayNumber Structure
STI-99 The STI infrastructure shall provide the CalendarValueDayNumber Structure definition and implementation as specified in Table 16.
Table 16: CalendarValueDayNumber Structure DefinitionDeclaration |
|
---|---|
Description | Definition of time representation expressed as a fractional day number. Member details:
|
Notes | The whole number (integer portion) of the value expresses the number of Earth days since the epoch, and the fractional part expresses the time of day. |
12.4.14 STI Infrastructure-Provided CalendarTime Union
STI-100 The STI infrastructure shall provide the CalendarTime Union definition and implementation as specified in Table 17.
Table 17: CalendarTime Union DefinitionDeclaration |
|
---|---|
Description | Definition of CalendarTime type based on CalendarKind value. |
Notes |
12.5 STI Application-Provided Methods
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Up to top, or Down to Acronyms
“Provide a definition” implies supplying a consistent interface, which may be used or inherited by other methods. The implementation of such an interface may be supplied by others. For functions, an abstract method or class, a virtual method, or prototype is usually supplied.
Any apparent discrepancy between application-provided and infrastructure-provided of the titles and requirements is easily resolved by noting that the infrastructure provides the definition while the application inherits an implementation or provides the implementation directly.
12.5.1 STI Infrastructure-Provided APP_GetHandleID Method
STI-30 The STI infrastructure shall provide the APP_GetHandleID() definition and implementation as specified in Table 18.
Table 18: APP_GetHandleID() DefinitionDeclaration |
|
---|---|
Description | Obtain the handle ID for the application, stored by the STI Infrastructure. |
Return | The actual handle ID of the called application or predefined HANDLEID_INVALID on failure |
Notes | This call should never fail when invoked from a normal, fully constructed application or device context. If invoked from an application or device context that is not fully constructed, an invalid ID may be returned. Specifically, this condition may occur while the constructor or destructor are currently executing. If the infrastructure cannot obtain the correct handle ID, the infrastructure will return HANDLEID_INVALID that does not alias a valid handle ID. The caller should always validate the returned handle ID using ValidateHandleID() to determine success or failure. |
12.5.2 STI Infrastructure-Provided APP_GetHandleName Method
STI-31 The STI infrastructure shall provide the APP_GetHandleName() definition and implementation as specified in Table 19.
Table 19: APP_GetHandleName() DefinitionDeclaration |
|
---|---|
Description | Obtain the name for the application, stored by the STI Infrastructure. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The caller is responsible for preallocating the size of handleName to [MAX_HANDLE_NAME_SIZE+1]. This call should never fail when invoked from a normal, fully constructed application or device context. If invoked from an application or device context that is not fully constructed, this call may fail. Specifically, this condition may occur while the constructor or destructor are currently executing. |
12.5.3 STI Application-Provided APP_Instance Method
STI-32 The STI infrastructure shall provide the APP_Instance() definition as specified in Table 20.
Table 20: APP_Instance() DefinitionDeclaration |
|
---|---|
Description | Construct an instance of the application, identified by the id and name indicated in the parameters. |
Parameters |
|
Return | On success, return a reference to the constructed instance. On failure, return an invalid reference (i.e. NULL in C/C++, or the respective undefined value in other languages) |
Notes | The id and name values passed to this constructor become valid only after the constructor has completed successfully and returned a valid object reference/pointer. As such, other infrastructure calls should not be invoked from the constructor using these values. Use of the values during the construction of the object itself is not defined, as the infrastructure may still consider it an invalid ID or name. For statically allocated objects, a pointer to the pre-allocated structure may be returned, without performing any additional allocation. In all cases, the object returned will be of the Instance type, either directly or as a derivative type. In object-oriented languages, the instance object will inherit from the correct base object or class. In C, this can be done by ensuring the first member of the returned structure object is an Instance object as defined by the infrastructure. |
12.5.4 STI Application-Provided APP_Destroy Method
STI-33 The STI infrastructure shall provide the APP_Destroy() definition as specified in Table 21.
Table 21: APP_Destroy() DefinitionDeclaration |
|
---|---|
Description | Delete an instance of the application, identified by the inst parameter. |
Parameters |
|
Return | None |
Notes | This function will be defined but may be empty or a “no-op” for statically allocated entities. After this call completes, the object referred to by the inst parameter is considered invalid, and the infrastructure ensures that any internally stored references to the instance have been deleted. |
12.5.5 STI Application-Provided APP_Initialize Method
STI-34 The STI infrastructure shall provide the APP_Initialize() definition as specified in Table 22 to be implemented by an STI application or device.
Table 22: APP_Initialize() DefinitionDeclaration |
|
---|---|
Description | Initialize the application. Obtain any underlying system resources as required for further operation and set all internal variables to a known initial state. |
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | If initialization is unsuccessful for any reason, the implementation will ensure that any external system resources obtained before the failure are returned to their original state. There is no provision to permit “partial” initialization sequences to occur. If not successful, the implementation should log details of the failure to the log facility. |
12.5.6 STI Application-Provided APP_ReleaseObject Method
STI-35 The STI infrastructure shall provide the APP_ReleaseObject() definition as specified in Table 23 to be implemented by an STI application or device.
Table 23: APP_ReleaseObject() DefinitionDeclaration |
|
---|---|
Description | Release any system resources that were obtained during the initialization or normal operation. |
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This operation should be the inverse of the APP_Initialize() operation, returning the application or device to the same state as it was prior to initialization. After this operation, the infrastructure will either destroy the instance or initialize it again. |
12.5.7 STI Application-Provided APP_Query Method
STI-36 The STI infrastructure shall provide the APP_Query() definition as specified in Table 24 to be implemented by an STI application or device.
Table 24: APP_Query() DefinitionDeclaration |
|
---|---|
Description | Obtain or “get” the value for one property in the component. |
Parameters |
|
Return | On success, return the predefined Result value OK, which indicates that the property value has been retrieved in its entirety; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | If an error is returned by an implementation, a corresponding message indicating details of the failure should be written to the log facility for diagnostic purposes. Return Result values other than the predefined Result values are permissible for backward compatibility but are to be validated using the IsOK() function. Use of additional return values are not recommended; for maximum portability, custom return values or “partial success” return codes should be avoided. For C/C++ implementations, the abstract propValue parameter is translated to two parameters, a base object pointer and size. |
12.5.8 STI Application-Provided APP_Configure Method
STI-37 The STI infrastructure shall provide the APP_Configure() definition as specified in Table 25 to be implemented by an STI application or device.
Table 25: APP_Configure() DefinitionDeclaration |
|
---|---|
Description | Configure or “set” the value for one property in the component. |
Parameters |
|
Return | On success, return the predefined Result value OK, which indicates that the property value has been configured; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | If an error is returned by an implementation, a corresponding message indicating details of the failure should be written to the log facility for diagnostic purposes. Return Result values (other than the predefined Result values) are permissible for backward compatibility but are to be validated using the IsOK() function. Use of additional return Result values is not recommended; for maximum portability, custom Result values or “partial success” return codes should be avoided. For C/C++ implementations, the abstract propValue parameter is translated to two parameters, a base object pointer and size. |
12.5.9 STI Application-Provided APP_RunTest Method
STI-38 The STI infrastructure shall provide the APP_RunTest() definition as specified in Table 26 to be implemented by an STI application or device.
Table 26: APP_RunTest() DefinitionDeclaration |
|
---|---|
Description | Invoke the test of the target application as indicated by the test ID. |
Parameters |
|
Return | On success or if the test is running in the background, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | Tests which are not appropriate for a given system state, such as invoking a ground-specific test while in a flight operation mode, should generate an error status return and record the issue in the system log. |
12.5.10 STI Application-Provided APP_Start Method
STI-39 The STI infrastructure shall provide the APP_Start() definition as specified in Table 27 to be implemented by an STI application or device.
Table 27: APP_Start() DefinitionDeclaration |
|
---|---|
Description | Begin normal target component (application or device) processing. |
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | If the application is not in the appropriate internal state, then nothing is done and an error is returned. If an error is returned by an implementation, a corresponding message to indicate details of the failure should be written to the log facility for diagnostic purposes. |
12.5.11 STI Application-Provided APP_Stop Method
STI-40 The STI infrastructure shall provide the APP_Stop() definition as specified in Table 28 to be implemented by an STI application or device.
Table 28: APP_Stop() DefinitionDeclaration |
|
---|---|
Description | End normal target component (application or device) processing. |
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | If the application is not in the appropriate internal state, then nothing is done and an error is returned. If an error is returned by an implementation, a corresponding message to indicate details of the failure should be written to the log facility for diagnostic purposes. |
12.5.12 STI Application-Provided APP_Read Method
STI-47 The STI infrastructure shall provide the APP_Read() definition as specified in Table 29 to be implemented, as needed, by an STI application or device.
Table 29: APP_Read() DefinitionDeclaration |
|
---|---|
Description | The buffer is filled with data from the component. |
Parameters |
|
Return | On success, the return value indicates the number of units of data (records or bytes) actually obtained from the application or device, which may be less than the complete buffer size. Otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The actual storage for the buffer is allocated by the caller or infrastructure prior to invoking this function. The application should fill the buffer to the maximum extent possible and return the amount of buffer actually filled. The application developer defines the specific format and units for the buffer. In languages with direct memory access (e.g. C), it may be an arbitrary memory buffer with the units specified in bytes. In other languages, the units should reflect logical records, such as a number of characters, samples, or objects. The infrastructure makes no assumptions about the format of the message data, nor the presence or expectation of a terminating entity, such as a NUL character (‘\0’) as required for C-style strings. If a terminating character is required, the caller will ensure that sufficient space is available in the buffer to store the termination character. If an error is returned by an implementation, a corresponding message to indicate details of the failure should be written to the log facility for diagnostic purposes. For C/C++ implementations, the abstract buffer parameter is translated to two parameters, a base object pointer and size. |
12.5.13 STI Application-Provided APP_Write Method
STI-48 The STI infrastructure shall provide the APP_Write() definition as specified in Table 30 to be implemented, as needed, by an STI application or device.
Table 30: APP_Write() DefinitionDeclaration |
|
---|---|
Description | The buffer data is sent to the target component. |
Parameters |
|
Return | On success, the return value indicates the number of units of data (records or bytes) actually sent to the application or device, which may be less than the buffer size. Otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The actual storage for the buffer is allocated and filled by the caller or infrastructure prior to invoking this function. The application should transfer the data to the maximum extent possible and return the amount of buffer actually transferred to the device. The application developer defines the specific format and units for the buffer. In languages with direct memory access (e.g. C), it may be an arbitrary memory buffer with the units specified in bytes. In other languages, the units should reflect logical records, such as a number of characters, samples, or objects. The infrastructure makes no assumptions about the format of the message data, nor the presence or expectation of a terminating entity, such as a NUL character (‘\0’) as required for C-style strings. If a terminating character is required, the caller will ensure that it has been added to the buffer prior to invoking this operation. If an error is returned by an implementation, a corresponding message to indicate details of the failure should be written to the log facility for diagnostic purposes. For C/C++ implementations, the abstract buffer parameter is translated to two parameters, a base object pointer and size. |
12.5.14 STI Application-Provided APP_AddressRead Method
STI-49 The STI infrastructure shall provide the APP_AddressRead() definition as specified in Table 31 to be implemented, as needed, by an STI application or device.
Table 31: APP_AddressRead() DefinitionDeclaration |
|
---|---|
Description | The buffer is filled with data from the component at the specified location. |
Parameters |
|
Return | On success, the return value indicates the number of units of data (defined by the platform developer) actually obtained from the application or device, which may be less than the complete buffer size. Otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The actual storage for the buffer is allocated by the caller or infrastructure prior to invoking this function. The application should fill the buffer to the maximum extent possible and return the amount of buffer actually filled. The application developer defines the specific format and units for the buffer. In languages with direct memory access (e.g. C), it may be an arbitrary memory buffer with the units specified in bytes. In other languages, the units should reflect logical records, such as a number of characters, samples, or objects. The infrastructure makes no assumptions about the format of the message data, nor the presence or expectation of a terminating entity, such as a NUL character (‘\0’) as required for C-style strings. If a terminating character is required, the caller will ensure that sufficient space is available in the buffer to store the termination character. If an error is returned by an implementation, a corresponding message to indicate details of the failure should be written to the log facility for diagnostic purposes. For C/C++ implementations, the abstract buffer parameter is translated to two parameters, a base object pointer and size. |
12.5.15 STI Application-Provided APP_AddressWrite Method
STI-50 The STI infrastructure shall provide the APP_AddressWrite() definition as specified in Table 32 to be implemented, as needed, by an STI application or device.
Table 32: APP_AddressWrite() DefinitionDeclaration |
|
---|---|
Description | The buffer data is written to the target component at the specified location. |
Parameters |
|
Return | On success, the return value indicates the number of units of data (records or bytes) actually sent to the application or device, which may be less than the buffer size. Otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The actual storage for the buffer is allocated and filled by the caller or infrastructure prior to invoking this function. The application should transfer the data to the maximum extent possible and return the amount of buffer actually transferred to the device. The application developer defines the specific format and units for the buffer. In languages with direct memory access (e.g. C), it may be an arbitrary memory buffer with the units specified in bytes. In other languages, the units should reflect logical records, such as a number of characters, samples, or objects. The infrastructure makes no assumptions about the format of the message data, nor the presence or expectation of a terminating entity, such as a NUL character (‘\0’) as required for C-style strings. If a terminating character is required, the caller will ensure that it has been added to the buffer prior to invoking this operation. If an error is returned by an implementation, a corresponding message to indicate details of the failure should be written to the log facility for diagnostic purposes. For C/C++ implementations, the abstract buffer parameter is translated to two parameters, a base object pointer and size. |
12.6 STI Device-Provided Methods
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Up to top, or Down to Acronyms
“Provide a definition” implies supplying a consistent interface, which may be used or inherited by other methods. The implementation of such an interface may be supplied by others. For functions, an abstract method or class, a virtual method, or prototype is usually supplied.
Any apparent discrepancy between device-provided and infrastructure-provided of the titles and requirements is easily resolved by noting that the infrastructure provides the definition while the device inherits an implementation or provides the implementation directly.
12.6.1 STI Device-Provided DEV_Open Method
STI-41 The STI infrastructure shall provide the DEV_Open() definition as specified in Table 33 to be implemented by an STI device.
Table 33: DEV_Open() DefinitionDeclaration |
|
---|---|
Description | Open the device for command and control. |
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The implementation should obtain whatever operating system or HAL resources are necessary to initiate communication or data transfer with the hardware device. Depending on the underlying device and operating system driver infrastructure, use of a hardware device may be limited to one process at a time, so a successful call to this function may prevent other processes in the system from using the device. Likewise, if another process is using the device, or the device is otherwise not able to accept control requests, this operation may fail or block until the device becomes available. If no specific operating system resources are required for communication with the device, this implementation may be a no-op. In this case, this operation should return the predefined Result value OK to maintain compatibility. |
12.6.2 STI Device-Provided DEV_Load Method
STI-42 The STI infrastructure shall provide the DEV_Load() definition as specified in Table 34 to be implemented by an STI device.
Table 34: DEV_Load() DefinitionDeclaration |
|
---|---|
Description | Load a binary application image or configuration file to the device. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | If the device is an FPGA, this operation would load a specific hardware design image to the device. If the device represents a microcontroller or DSP, this should load a firmware or application image to the device. |
12.6.3 STI Device-Provided DEV_Reset Method
STI-43 The STI infrastructure shall provide the DEV_Reset() definition as specified in Table 35 to be implemented by an STI device.
Table 35: DEV_Reset() DefinitionDeclaration |
|
---|---|
Description | Initialize a device to a known state. |
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This operation should bring a device into a known clean state, if possible. This operation may utilize a hardware reset function if available, or it may reconfigure all internal registers to a known initial value. This function should not “unload” programming information from an FPGA device. If a hardware reset function is used and this clears the programming information, the implementation should ensure that previously loaded image is restored before returning. |
12.6.4 STI Device-Provided DEV_Flush Method
STI-44 The STI infrastructure shall provide the DEV_Flush() definition as specified in Table 36 to be implemented by an STI device.
Table 36: DEV_Flush() DefinitionDeclaration |
|
---|---|
Description | Clear any pending input/output buffers associated with the device. |
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This operation should ensure that any existing data that may be buffered within the hardware device or control software is cleared, such that subsequent read operations (for source devices) or write operations (for sink devices) only transfer new data. It is implementation-defined how existing data that has not yet been fully transferred is handled. On a sink device, the operation may wait until the data is transferred, or the data may be discarded, depending on what is more appropriate for the device and the system context. On a source device, any received but unread data should typically be discarded. The device developer or platform provider should document the behavior of this operation. |
12.6.5 STI Device-Provided DEV_Unload Method
STI-45 The STI infrastructure shall provide the DEV_Unload() definition as specified in Table 37 to be implemented by an STI device.
Table 37: DEV_Unload() DefinitionDeclaration |
|
---|---|
Description | Unload a binary image or configuration file from the device. |
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This operation clears any programming information from the device. Ideally this should be the inverse of the DEV_Load() operation. If the device does not support this operation, this may be implemented as a “no-op”. |
12.6.6 STI Device-Provided DEV_Close Method
STI-46 The STI infrastructure shall provide the DEV_Close() definition as specified in Table 38 to be implemented by an STI device.
Table 38: DEV_Close() DefinitionDeclaration |
|
---|---|
Description | Close the device. |
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This operation should be the inverse of the DEV_Open() operation. If the open operation was a no-op, this operation should also be empty and it should return the predefined Result value OK for compatibility. |
12.7 STI Infrastructure-Provided Methods
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Up to top, or Down to Acronyms
“Provide a definition” implies supplying a consistent interface, which may be used or inherited by other methods. The implementation of such an interface may be supplied by others. For functions, an abstract method or class, a virtual method, or prototype is usually supplied.
The following items in section 12.7 are expected to appear in module STI.
12.7.1 STI Infrastructure-Provided IsOK Method
STI-51 The STI infrastructure shall provide the IsOK() definition and implementation as specified in Table 39.
Table 39: IsOK() DefinitionDeclaration |
|
---|---|
Description | Determine if a Result value represents a successful response. |
Parameters |
|
Return | If the Result status value represents a successful result, evaluate as TRUE. If the Result status value represents a failure, evaluate as FALSE. |
Notes | Converts a Result value from any previous API call into a boolean value that can be used in conjunction with the programming language conditional statements. For efficiency reasons, this may be implemented as a macro or inline function in languages which support this concept. |
12.7.2 STI Infrastructure-Provided ValidateHandleID Method
STI-52 The STI infrastructure shall provide the ValidateHandleID() definition and implementation as specified in Table 40.
Table 40: ValidateHandleID() DefinitionDeclaration |
|
---|---|
Description | Determine if a HandleID value is valid. |
Parameters |
|
Return | If the handle ID value is valid, return the predefined Result value OK. Otherwise, return one of the predefined Result values indicating failure. |
Notes | This is used to check the result of any function returning a HandleID value. The result of this function should be passed to IsOK() for use in any conditional test. |
12.7.3 STI Infrastructure-Provided ValidateSize Method
STI-53 The STI infrastructure shall provide the ValidateSize() definition and implementation as specified in Table 41.
Table 41: ValidateSize() DefinitionDeclaration |
|
---|---|
Description | Determine if a FileSize value is valid. |
Parameters |
|
Return | If the size value is valid, return the predefined Result value OK. Otherwise, return one of the predefined Result values indicating failure. |
Notes | This is used to check the result of any function returning a FileSize value. The result of this function should be passed to IsOK() for use in any conditional test. |
12.7.4 STI Infrastructure-Provided InstantiateApp Method
STI-54 The STI infrastructure shall provide the InstantiateApp() definition and implementation as specified in Table 42.
Table 42: InstantiateApp() DefinitionDeclaration |
|
---|---|
Description | Instantiate an application or service. |
Parameters |
|
Return | On success, return a Handle ID value identifying the newly created instance. Otherwise, return the predefined HANDLEID_INVALID. |
Notes | The caller should validate the return HandleID value using ValidateHandleID() to determine success or failure. The handle name specified for the application, service, or device is to be unique within the scope of the current STI environment. The STI Infrastructure may also impose additional operations to be performed during instantiation, such as the loading of dynamic link libraries or shared objects, as documented by the platform provider. It is up to the STI Infrastructure to determine whether any additional resources are to be loaded to accomplish the instantiation. The configuration parameter will be a free-form string, defined by the platform provider, and intended as a generic means to pass additional instructions to the infrastructure as part of the instantiation process. This string may directly contain a set of encoded configuration data (e.g. XML), or it may refer to a filename on the system storage device containing additional information about the instance. |
12.7.5 STI Infrastructure-Provided GetErrorQueue Method
STI-55 The STI infrastructure shall provide the GetErrorQueue() definition and implementation as specified in Table 43.
Table 43: GetErrorQueue() DefinitionDeclaration |
|
---|---|
Description | Obtain the error queue associated with the given status value. |
Parameters |
|
Return | Return a handle ID value identifying the queue to which any associated log message should be written. |
Notes | This call is intended for use in conjunction with the Log() function for preserving error-related context information. The platform may direct different types of errors to different log queues to aid with diagnostics. For any given error response, this locates the proper queue for logging of any related information. In general, this should only be used for error Result values (i.e. those for which IsOK() returns FALSE). However, in all cases, the return value from this function will be passable directly to the Log() routine, without further validation, for any Result value. |
12.7.6 STI Infrastructure-Provided GetHandleName Method
STI-56 The STI infrastructure shall provide the GetHandleName() definition and implementation as specified in Table 44.
Table 44: GetHandleName() DefinitionDeclaration |
|
---|---|
Description | Obtain the handle name associated with the given handle ID (toID). |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The caller is responsible for preallocating the size of handleName to [MAX_HANDLE_NAME_SIZE+1]. |
12.7.7 STI Infrastructure-Provided HandleRequest Method
STI-57 The STI infrastructure shall provide the HandleRequest() definition and implementation as specified in Table 45.
Table 45: HandleRequest() DefinitionDeclaration |
|
---|---|
Description | Obtain the handle ID associated with the given handle name. |
Parameters |
|
Return | On success, return a Handle ID value identifying the component. Otherwise, return the predefined HandleID value HANDLEID_INVALID. |
Notes | The caller should validate the return HandleID value using ValidateHandleID() to determine success or failure. |
12.7.8 STI Infrastructure-Provided AbortApp Method
STI-58 The STI infrastructure shall provide the AbortApp() definition and implementation as specified in Table 46.
Table 46: AbortApp() DefinitionDeclaration |
|
---|---|
Description | Abort an application or service. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The target component will be removed from the environment and any system resources associated with it should be released. |
12.7.9 STI Infrastructure-Provided Initialize Method
STI-59 The STI infrastructure shall provide the Initialize() definition and implementation as specified in Table 47.
Table 47: Initialize() DefinitionDeclaration |
|
---|---|
Description | Initialize the target component. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This sets the component to a known initial state. The specific definition of this state is application-defined. This triggers the APP_Initialize() operation on the target interface. |
12.7.10 STI Infrastructure-Provided ReleaseObject Method
STI-60 The STI infrastructure shall provide the ReleaseObject() definition and implementation as specified in Table 48.
Table 48: ReleaseObject() DefinitionDeclaration |
|
---|---|
Description | Release any system resources held by the application or component. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This triggers the APP_ReleaseObject() operation on the target interface. |
12.7.11 STI Infrastructure-Provided Configure Method
STI-61 The STI infrastructure shall provide the Configure() definition and implementation as specified in Table 49.
Table 49: Configure() DefinitionDeclaration |
|
---|---|
Description | Configure or set a single property in the target component. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The caller manages the memory associated with the value buffer. This triggers the APP_Configure() operation in the target interface. |
12.7.12 STI Infrastructure-Provided Query Method
STI-62 The STI infrastructure shall provide the Query() definition and implementation as specified in Table 50.
Table 50: Query() DefinitionDeclaration |
|
---|---|
Description | Obtain or get a single property from the target component. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The caller manages the memory associated with the value buffer. This triggers the APP_Query() operation in the target interface. |
12.7.13 STI Infrastructure-Provided RunTest Method
STI-63 The STI infrastructure shall provide the RunTest() definition and implementation as specified in Table 51.
Table 51: RunTest() DefinitionDeclaration |
|
---|---|
Description | Obtain the handle ID associated with the given handle name. |
Parameters |
|
Return | On success or if the test is running in the background, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The specific values and meaning of the TestID parameter are application specific. This triggers the APP_RunTest() operation in the target interface. |
12.7.14 STI Infrastructure-Provided Start Method
STI-64 The STI infrastructure shall provide the Start() definition and implementation as specified in Table 52.
Table 52: Start() DefinitionDeclaration |
|
---|---|
Description | Begin normal application or device processing. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This triggers the APP_Start() operation in the target interface. |
12.7.15 STI Infrastructure-Provided Stop Method
STI-65 The STI infrastructure shall provide the Stop() definition and implementation as specified in Table 53.
Table 53: Stop() DefinitionDeclaration |
|
---|---|
Description | End normal application or device processing. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This triggers the APP_Stop() operation in the target interface. |
12.7.16 STI Infrastructure-Provided DeviceOpen Method
STI-66 The STI infrastructure shall provide the DeviceOpen() definition and implementation as specified in Table 54.
Table 54: DeviceOpen() DefinitionDeclaration |
|
---|---|
Description | Open the device. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This triggers the DEV_Open() operation in the target interface. This will be the first call issued before invoking any other device control operations. |
12.7.17 STI Infrastructure-Provided DeviceLoad Method
STI-67 The STI infrastructure shall provide the DeviceLoad() definition and implementation as specified in Table 55.
Table 55: DeviceLoad() DefinitionDeclaration |
|
---|---|
Description | Load an application, hardware design, or configuration file into the device. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This triggers the DEV_Load() operation in the target interface. |
12.7.18 STI Infrastructure-Provided DeviceReset Method
STI-68 The STI infrastructure shall provide the DeviceReset() definition and implementation as specified in Table 56.
Table 56: DeviceReset() DefinitionDeclaration |
|
---|---|
Description | Reset the device into a known state. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The specific state after reset is device-defined. This triggers the DEV_Reset() operation in the target interface. |
12.7.19 STI Infrastructure-Provided DeviceFlush Method
STI-69 The STI infrastructure shall provide the DeviceFlush() definition and implementation as specified in Table 57.
Table 57: DeviceFlush() DefinitionDeclaration |
|
---|---|
Description | Clear any pending input/output data buffers in the device. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This triggers the DEV_Flush() operation in the target interface. |
12.7.20 STI Infrastructure-Provided DeviceUnload Method
STI-70 The STI infrastructure shall provide the DeviceUnload() definition and implementation as specified in Table 58.
Table 58: DeviceUnload() DefinitionDeclaration |
|
---|---|
Description | Unload any previously loaded application, hardware design image, or configuration file. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This triggers the DEV_Unload() operation in the target interface. |
12.7.21 STI Infrastructure-Provided DeviceClose Method
STI-71 The STI infrastructure shall provide the DeviceClose() definition and implementation as specified in Table 59.
Table 59: DeviceClose() DefinitionDeclaration |
|
---|---|
Description | Close the device. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This triggers the DEV_Close() operation in the target interface. The device will not be used by the application after this call unless opened again. |
12.7.22 STI Infrastructure-Provided Read Method
STI-72 The STI infrastructure shall provide the Read() definition and implementation as specified in Table 60.
Table 60: Read() DefinitionDeclaration |
|
---|---|
Description | Read or “pull” arbitrary data from another application or device. |
Parameters |
|
Return | On success, return a status value indicating the actual number of records or bytes of data that was transferred into the supplied buffer. Otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The storage for the buffer will be managed by the caller. The target application defines the specific binary format for the data. In languages with direct memory access (e.g. C/C++), the buffer is an arbitrary memory location with the units specified in bytes. In other languages, the units should reflect logical records, such as a number of characters, samples, or objects. The infrastructure makes no assumptions about the format of the message data, nor the presence or expectation of a terminating entity, such as a NUL character (‘\0’) as required for C-style strings. If a terminating character is required, the caller will ensure that sufficient space is available in the buffer to store the termination character. |
12.7.23 STI Infrastructure-Provided Write Method
STI-73 The STI infrastructure shall provide the Write() definition and implementation as specified in Table 61.
Table 61: Write() DefinitionDeclaration |
|
---|---|
Description | Write or “push” arbitrary data to another application or device. |
Parameters |
|
Return | On success, return a status value indicating the actual number of records or bytes of data that was transferred from the supplied buffer. Otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The storage for the buffer will be managed by the caller. The target application defines the specific binary format for the data. In languages with direct memory access (e.g. C/C++), the buffer is an arbitrary memory location with the units specified in bytes. In other languages, the units should reflect logical records, such as a number of characters, samples, or objects. The infrastructure makes no assumptions about the format of the message data, nor the presence or expectation of a terminating entity, such as a NUL character (‘\0’) as required for C-style strings. If a terminating character is required, the caller will ensure that sufficient space is available in the buffer to store the termination character. |
12.7.24 STI Infrastructure-Provided AddressRead Method
STI-74 The STI infrastructure shall provide the AddressRead() definition and implementation as specified in Table 62.
Table 62: AddressRead() DefinitionDeclaration |
|
---|---|
Description | Read data from a specific offset or address within a device or file. |
Parameters |
|
Return | On success, return a status value indicating the actual number of records or bytes of data that was transferred into the supplied buffer. Otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The storage for the buffer will be managed by the caller. The target application defines the specific binary format for the data. In languages with direct memory access (e.g. C/C++), the buffer is an arbitrary memory location with the units specified in bytes. In other languages, the units should reflect logical records, such as a number of characters, samples, or objects. The infrastructure makes no assumptions about the format of the message data, nor the presence or expectation of a terminating entity, such as a NUL character (‘\0’) as required for C-style strings. If a terminating character is required, the caller will ensure that sufficient space is available in the buffer to store the termination character. |
12.7.25 STI Infrastructure-Provided AddressWrite Method
STI-75 The STI infrastructure shall provide the AddressWrite() definition and implementation as specified in Table 63.
Table 63: AddressWrite() DefinitionDeclaration |
|
---|---|
Description | Write data to a specific offset or address within a device or file. |
Parameters |
|
Return | On success, return a status value indicating the actual number of records or bytes of data that was transferred from the supplied buffer. Otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The storage for the buffer will be managed by the caller. The target application defines the specific binary format for the data. In languages with direct memory access (e.g. C/C++), the buffer is an arbitrary memory location with the units specified in bytes. In other languages, the units should reflect logical records, such as a number of characters, samples, or objects. The infrastructure makes no assumptions about the format of the message data, nor the presence or expectation of a terminating entity, such as a NUL character (‘\0’) as required for C-style strings. If a terminating character is required, the caller will ensure that sufficient space is available in the buffer to store the termination character. |
12.7.26 STI Infrastructure-Provided Log Method
STI-76 The STI infrastructure shall provide the Log() definition and implementation as specified in Table 64.
Table 64: Log() DefinitionDeclaration |
|
---|---|
Description | Send an information message to the specified log facility. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | When logging context information related to errors, the GetErrorQueue() function may be used to determine the proper value to use for the toID parameter. In other cases, the predefined error queue values may be used, as listed in Table 8, HandleID Values. Behavior is not specified if the toID parameter does not refer to a component capable of accepting log messages (i.e. one of the defined log facilities). |
12.7.27 STI Infrastructure-Provided FileOpen Method
STI-77 The STI infrastructure shall provide the FileOpen() definition and implementation as specified in Table 65.
Table 65: FileOpen() DefinitionDeclaration |
|
---|---|
Description | Open a file within the infrastructure file system. |
Parameters |
|
Return | On success, return a Handle ID value identifying the open file. Otherwise, return the predefined HandleID value HANDLEID_INVALID. |
Notes | The caller should always validate the return HandleID value using ValidateHandleID() to determine success or failure. After successfully opening a file, data transfer can be performed using the Read and/or Write functions described in sections 12.7.22 and 12.7.23. For the file access types, which provide the appropriate constraints, see Table 6, Access Values. |
12.7.28 STI Infrastructure-Provided FileClose Method
STI-78 The STI infrastructure shall provide the FileClose() definition and implementation as specified in Table 66.
Table 66: FileClose() DefinitionDeclaration |
|
---|---|
Description | Close a file handle. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The toID parameter should reflect a file handle that was previously obtained using FileOpen(). Behavior is undefined if this function is called with other types of handle IDs. |
12.7.29 STI Infrastructure-Provided FileGetSize Method
STI-79 The STI infrastructure shall provide the FileGetSize() definition and implementation as specified in Table 67.
Table 67: FileGetSize() DefinitionDeclaration |
|
---|---|
Description | Get the size of the specified file. |
Parameters |
|
Return | On success, return the size of the file. Otherwise, return an invalid size. |
Notes | The return value should be validated by the caller using the ValidateSize() operation as described in section 12.7.3. |
12.7.30 STI Infrastructure-Provided FileRemove Method
STI-80 The STI infrastructure shall provide the FileRemove() definition and implementation as specified in Table 68.
Table 68: FileRemove() DefinitionDeclaration |
|
---|---|
Description | Remove a specified file from the system. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | Behavior of this function is implementation-defined if the specified file is currently open within the infrastructure. Some systems may support this by “unlinking” the file name but deferring the actual removal (and recovery of space) until the file is closed. On other systems, the function may return an error if the file is currently open. Portable applications should ensure that a file has been closed prior to removal. |
12.7.31 STI Infrastructure-Provided FileRename Method
STI-81 The STI infrastructure shall provide the FileRename() definition and implementation as specified in Table 69.
Table 69: FileRename() DefinitionDeclaration |
|
---|---|
Description | Rename a specified file in the file system. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | Behavior of this function is implementation-defined if the specified file is currently open within the infrastructure. Some systems may support renaming an open file, but on other systems the function may return an error. Portable applications should ensure that a file has been closed prior to rename. |
12.7.32 STI Infrastructure-Provided FileGetFreeSpace Method
STI-82 The STI infrastructure shall provide the FileGetFreeSpace() definition and implementation as specified in Table 70.
Table 70: FileGetFreeSpace() DefinitionDeclaration |
|
---|---|
Description | Get the total free space available for file storage on the indicated file system. |
Parameters |
|
Return | On success, return the amount of free space. Otherwise, return an invalid size. |
Notes | The specific format and options for the fileSystem parameter will be defined by the platform provider. An invalid (undefined/NULL) or empty string value should always be interpreted to refer to the “default” or root storage device, if available. A non-empty string may refer to a physical device name, drive identifier, or a mount point, depending on the system. |
12.7.33 STI Infrastructure-Provided MessageQueueCreate Method
STI-83 The STI infrastructure shall provide the MessageQueueCreate() definition and implementation as specified in Table 71.
Table 71: MessageQueueCreate() DefinitionDeclaration |
|
---|---|
Description | Create a FIFO message queue. |
Parameters |
|
Return | On success, return a Handle ID value identifying the FIFO queue. Otherwise, return the predefined HandleID value HANDLEID_INVALID. |
Notes | The caller should validate the return HandleID value using ValidateHandleID() to determine success or failure. The queue name will be unique in within the current environment. Once a queue depth reaches its maximum (nmax), applications will be unable to write new data into the queue. Data does not “expire” from a FIFO queue; any data successfully written to the input side of a queue is removed only by reading the data from the output side of the queue, or by deleting the entire queue. If the nb parameter is omitted or specified as 0, the interpretation is implementation-defined. Specifically, this may be used for languages that employ automatic memory management and do not expose the size of objects in memory to applications. |
12.7.34 STI Infrastructure-Provided MessageQueueDelete Method
STI-84 The STI infrastructure shall provide the MessageQueueDelete() definition and implementation as specified in Table 72.
Table 72: MessageQueueDelete() DefinitionDeclaration |
|
---|---|
Description | Delete a FIFO queue. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | Any written but unread data messages in the queue are discarded. |
12.7.35 STI Infrastructure-Provided PubSubCreate Method
STI-85 The STI infrastructure shall provide the PubSubCreate() definition and implementation as specified in Table 73.
Table 73: PubSubCreate() DefinitionDeclaration |
|
---|---|
Description | Create a PubSub entity. |
Parameters |
|
Return | On success, return a Handle ID value identifying the PubSub entity. Otherwise, return the predefined HandleID value HANDLEID_INVALID. |
Notes | The caller should validate the return HandleID value using ValidateHandleID() to determine success or failure. The name will be unique in within the current environment. Unlike FIFO queues, PubSub entities do not store messages; any messages pushed to a PubSub entity are immediately distributed to all currently registered subscribers at the time the message is pushed. |
12.7.36 STI Infrastructure-Provided PubSubDelete Method
STI-86 The STI infrastructure shall provide the PubSubDelete() definition and implementation as specified in Table 74.
Table 74: PubSubDelete() DefinitionDeclaration |
|
---|---|
Description | Delete a PubSub entity. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | Any registered subscribers will be automatically unregistered upon deletion. |
12.7.37 STI Infrastructure-Provided Register Method
STI-87 The STI infrastructure shall provide the Register() definition and implementation as specified in Table 75.
Table 75: Register() DefinitionDeclaration |
|
---|---|
Description | Add a handle to the recipient list of the PubSub entity. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | A single recipient cannot be registered multiple times. If a recipient is already registered within the PubSub entity, this function returns a success code without making any change. |
12.7.38 STI Infrastructure-Provided Unregister Method
STI-88 The STI infrastructure shall provide the Unregister() definition and implementation as specified in Table 76.
Table 76: Unregister() DefinitionDeclaration |
|
---|---|
Description | Remove a handle from the recipient list of the PubSub entity. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes |
12.7.39 STI Infrastructure-Provided GetNanoseconds Method
STI-89 The STI infrastructure shall provide the GetNanoseconds() definition and implementation as specified in Table 77.
Table 77: GetNanoseconds() DefinitionDeclaration |
|
---|---|
Description | Get the number of nanoseconds (fractional quantity) from the TimeWarp object. |
Parameters |
|
Return | Return the number of nanoseconds |
Notes | The nanoseconds value is always non-negative, and reflects the difference between the actual interval time and the number of whole seconds in the interval as reported by GetSeconds() |
12.7.40 STI Infrastructure-Provided GetSeconds Method
STI-90 The STI infrastructure shall provide the GetSeconds() definition and implementation as specified in Table 78.
Table 78: GetSeconds() DefinitionDeclaration |
|
---|---|
Description | Get the number of seconds (whole number quantity) from the TimeWarp object. |
Parameters |
|
Return | Return the number of seconds |
Notes | The seconds value may be negative, which indicates an interval back in time. For fractional intervals, the seconds value reflects the largest integral value not greater than the interval length in seconds, similar to the POSIX floor() operation applied to a floating-point value. For example, given a TimeWarp interval corresponding to -1.1s, the GetSeconds() function will return -2, and the GetNanoseconds() function will return 900,000,000. |
12.7.41 STI Infrastructure-Provided GetTimeWarp Method
STI-91 The STI infrastructure shall provide the GetTimeWarp() definition and implementation as specified in Table 79.
Table 79: GetTimeWarp() DefinitionDeclaration |
|
---|---|
Description | Get the TimeWarp object value corresponding to the seconds and nanoseconds. |
Parameters |
|
Return | Return the corresponding time value as a TimeWarp value |
Notes | The nsec parameter value should be between 0 and 999,999,999, inclusive. If the nsec value is not within this range, the infrastructure should adjust the isec and nsec values by decrementing/incrementing nsec by 1,000,000,000 and incrementing/decrementing isec by 1, respectively, until the nsec value is within this range. |
12.7.42 STI Infrastructure-Provided TimeAdd Method
STI-92 The STI infrastructure shall provide the TimeAdd() definition and implementation as specified in Table 80.
Table 80: TimeAdd() DefinitionDeclaration |
|
---|---|
Description | Compute the sum of two TimeWarp values. |
Parameters |
|
Return | The sum (t1 + t2) expressed as a TimeWarp value |
Notes |
12.7.43 STI Infrastructure-Provided TimeSubtract Method
STI-93 The STI infrastructure shall provide the TimeSubtract() definition and implementation as specified in Table 81.
Table 81: TimeSubtract() DefinitionDeclaration |
|
---|---|
Description | Compute the difference between two TimeWarp values. |
Parameters |
|
Return | The difference (t1 – t2) expressed as a TimeWarp value |
Notes | This operation may be implemented as a macro or inline function for efficiency, on languages that offer this feature. This operation may be used by software to compute the elapsed time between two successive calls to GetTime(). The result can be converted back to engineering units via the GetSeconds() and GetNanoseconds() operations |
12.7.44 STI Infrastructure-Provided GetTime Method
STI-94 The STI infrastructure shall provide the GetTime() definition and implementation as specified in Table 82.
Table 82: GetTime() DefinitionDeclaration |
|
---|---|
Description | Obtain the current value of the clock. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The output value returned represents a direct measurement of elapsed time since its respective epoch according to the clock’s time scale and is not adjusted for nor dependent upon any locale-specific time representations (i.e. time zone, daylight savings time, etc.) or effects of relativity. |
12.7.45 STI Infrastructure-Provided SetTime Method
STI-95 The STI infrastructure shall provide the SetTime() definition and implementation as specified in Table 83.
Table 83: SetTime() DefinitionDeclaration |
|
---|---|
Description | Set the current value of the clock. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This function will “step” the base clock. Since the offset is applied against the base clock measurement, it affects all calendar representations of the clock accordingly. It may be used to synchronize a clock based on information obtained after start up. Not all clock components are required to support this operation. If a clock component is read-only and not settable from an application, this function should return UNIMPLEMENTED. Note that this is not intended for implementing the concept of a “time zone” or “local time” (i.e. the time as commonly expressed in a given geopolitical region). If the platform implements the concept of local time, then the specific local time offset or conversion rules should be configured using the Configure and Query methods as described in sections 12.7.11 and 12.7.12. The specific property name and value format for time zone configuration is platform-defined. On some systems, it may be directly configured as a number (i.e. minutes ahead of GMT) or it may be configured as a string reflecting a predefined rule (i.e. “US/Eastern”) if the system is capable of automatic daylight savings time adjustments. |
12.7.46 STI Infrastructure-Provided GetCalendarTime Method
STI-96 The STI infrastructure shall provide the GetCalendarTime() definition and implementation as specified in Table 84.
Table 84: GetCalendarTime() DefinitionDeclaration |
|
---|---|
Description | Convert the base clock time value to a defined calendar representation. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This call is used to convert a TimeWarp value (of which the definition is platform-specific) into a value in one of the defined calendar systems, such that portable applications can interpret it in a consistent manner. If the system or clock does not support the requested CalendarKind, the implementation should return UNIMPLEMENTED. If the referenceTime is zero, such as the result of a call to GetTimeWarp(0,0) then return the respective calendar representation of the clock epoch. |
12.7.47 STI Infrastructure-Provided SetTimeAdjust Method
STI-101 The STI infrastructure shall provide the SetTimeAdjust() definition and implementation as specified in Table 85.
Table 85: SetTimeAdjust() DefinitionDeclaration |
|
---|---|
Description | Adjust the tick rate of the clock component. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The rateAdjustment parameter is a signed integer, where the value of 0 represents the nominal or free-run rate of the clock without any adjustment applied. If any adjustment had been previously applied, calling this function with a value of 0 will restore a clock to its default rate. A positive value will cause the clock frequency to increase from the nominal rate, and a negative value will cause the clock frequency to decrease from the nominal rate. The specific unit of rate increase/decrease is platform defined, although typically might reflect a number of parts per million or parts per billion depending on clock design. If the underlying device does not support rate adjustment, then this function will return the predefined Result value UNIMPLEMENTED. A typical use-case of this function would periodically compute the difference between the reference clock and the local clock component, which is then multiplied by a feedback ratio (proportional coefficient) to compute the adjustment value to pass into this function. |
12.7.48 STI Infrastructure-Provided GetTimeAdjust Method
STI-102 The STI infrastructure shall provide the GetTimeAdjust() definition and implementation as specified in Table 86.
Table 86: GetTimeAdjust() DefinitionDeclaration |
|
---|---|
Description | Obtain the current tick rate adjustment value of the clock component. |
Parameters |
|
Return | Return the current tick rate adjustment value |
Notes | A return value of 0 indicates the clock is operating at its nominal or free-run frequency. If the underlying device does not support rate adjustment, then this function always returns 0. A positive value indicates the clock frequency is above nominal, and a negative value indicates the clock frequency is below nominal. The specific units of the TimeRate value are platform defined, although typically might reflect a number of parts per million or parts per billion depending on clock design. |
12.7.49 STI Infrastructure-Provided TimeSynch Method
STI-103 The STI infrastructure shall provide the TimeSynch() definition and implementation as specified in Table 87.
Table 87: TimeSynch() DefinitionDeclaration |
|
---|---|
Description | Synchronize a clock component with another clock component in the system. |
Parameters |
|
Return |
If the synchronization is successful with a single call to TimeSynch(), such that no further action is required, return the predefined Result value OK. If the synchronization is partially successful such that additional calls to TimeSynch() are required, due to constraints such as those imposed by stepMax, return a positive integer value indicating the anticipated number of calls required. If synchronization is not possible under the given constraints, return one of the predefined Result values indicating failure. |
Notes | This function is intended for use in systems where one clock component may be selectively synchronized with another clock component. Support for this function is implementation-defined and this function may return the predefined value UNIMPLEMENTED if the clock component does not support synchronization with any other clock component. The infrastructure provider will document the set of applications, devices, or services suitable for use as synchronizable clock components with a handle ID parameter. This reference device may be another infrastructure-provided clock/timer service, or it may be another form of timing reference, such as a software service implementing a protocol such as NTP or IEEE-1588, or a device capable of recovering timing signals from received bit streams. The stepMax parameter specifies the maximum amount that the target clock component may be modified in a single step change. The predefined value TIME_INTERVAL_UNLIMITED may be specified to indicate no limit to the step size, permitting the target clock component to be directly set to any value. |
12.7.50 STI Infrastructure-Provided Sleep Method
STI-104 The STI infrastructure shall provide the Sleep() definition and implementation as specified in Table 88.
Table 88: Sleep() DefinitionDeclaration |
|
---|---|
Description | Delay the caller until the specified interval has elapsed, as measured by the clock component. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The call may be interrupted under some circumstances, causing the infrastructure to return to the caller before the interval has elapsed. In these cases, the infrastructure should return the WARNING response. Note that the actual sleep time may be longer than requested due to the resolution of the clock component and operating system scheduling variances. Setting a clock using SetTime() while this operation is in progress has undefined effects on the delay operation. |
12.7.51 STI Infrastructure-Provided DelayUntil Method
STI-105 The STI infrastructure shall provide the DelayUntil() definition and implementation as specified in Table 89.
Table 89: DelayUntil() DefinitionDeclaration |
|
---|---|
Description | Delay the caller until the clock reaches the indicated value. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The call may be interrupted under some circumstances, causing the infrastructure to return to the caller before the end time has been reached. In these cases, the infrastructure should return the WARNING response. Note that the actual sleep time may be longer than requested due to the resolution of the clock component and operating system scheduling variances. Setting a clock using SetTime() while this operation is in progress has undefined effects on the delay operation. |
12.7.52 STI Infrastructure-Provided ConvertToTimeWarp Method
STI-112 The STI infrastructure shall provide the ConvertToTimeWarp() definition and implementation as specified in Table 90.
Table 90: ConvertToTimeWarp() DefinitionDeclaration |
|
---|---|
Description | Convert the defined calendar representation to a TimeWarp clock time value. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This call is used by applications to convert a value in one of the defined calendar systems into a TimeWarp value (of which the definition is platform-specific), such that portable applications can interpret it in a consistent manner. If the system or clock does not support the requested CalnedarKind, the implementation should return UNIMPLEMENTED. If the CalendarTime is prior to the epoch for TimeWarp, an error is returned. |
12.8 External Command and Telemetry
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Up to top, or Down to Acronyms
12.8.1 Respond to External Commands
STI-108 An STI platform shall accept, validate, and respond to external commands.
12.8.2 External Commands Use STI API
STI-109 An STI platform shall execute external application control commands using the standardized STI APIs.
12.8.3 Document External Commands
STI-110 An STI platform provider shall document any external commands describing their format, function, and any STI methods invoked.
12.8.4 Use STI Query for External Data
STI-111 The STI infrastructure shall use the STI Query method to service external system requests for information and to provide telemetry data about an STI application.
12.9 STI Clock-Provided Methods
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Up to top, or Down to Acronyms
“Provide a definition” implies supplying a consistent interface, which may be used or inherited by other methods. The implementation of such an interface may be supplied by others. For functions, an abstract method or class, a virtual method, or prototype is usually supplied.
Any apparent discrepancy between clock-provided and infrastructure-provided of the titles and requirements is easily resolved by noting that the infrastructure provides the definition while the clock inherits an implementation or provides the implementation directly.
Clock components must be STI applications or devices or services to be able to be accessed by a handle ID.
12.9.1 STI Infrastructure-Provided CLK_GetTime Method
STI-113 The STI infrastructure shall provide the CLK_GetTime() definition as specified in Table 90 to be implemented by an STI clock.
Table 91: CLK_GetTime() Definition
Declaration |
|
---|---|
Description | Obtain the current value of the clock. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The output value returned represents a direct measurement of elapsed time since its respective epoch according to the clock’s time scale and is not adjusted for nor dependent upon any locale-specific time representations (i.e. time zone, daylight savings time, etc.) or effects of relativity. |
12.9.2 STI Infrastructure-Provided CLK_SetTime Method
STI-114 The STI infrastructure shall provide the CLK_SetTime() definition as specified in Table 91 to be implemented by an STI clock.
Table 92: CLK_SetTime() Definition
Declaration |
|
---|---|
Description | Set the current value of the clock. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | This function will “step” the base clock. Since the offset is applied against the base clock measurement, it affects all calendar representations of the clock accordingly. It may be used to synchronize a clock based on information obtained after start up. Not all clock components are required to support this operation. If a clock component is read-only and not settable from an application, this function should return UNIMPLEMENTED. Note that this is not intended for implementing the concept of a “time zone” or “local time” (i.e. the time as commonly expressed in a given geopolitical region). If the platform implements the concept of local time, then the specific local time offset or conversion rules should be configured using the Configure and Query methods as described in sections 12.9.11 and 12.9.12. The specific property name and value format for time zone configuration is platform-defined. On some systems, it may be directly configured as a number (i.e. minutes ahead of GMT) or it may be configured as a string reflecting a predefined rule (i.e. “US/Eastern”) if the system is capable of automatic daylight savings time adjustments. |
12.9.3 STI Infrastructure-Provided CLK_SetTimeAdjust Method
STI-115 The STI infrastructure shall provide the CLK_SetTimeAdjust() definition as specified in Table 92 to be implemented by an STI clock.
Table 93: CLK_SetTimeAdjust() Definition
Declaration |
|
---|---|
Description | Adjust the tick rate of the clock component. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The rateAdjustment parameter is a signed integer, where the value of 0 represents the nominal or free-run rate of the clock without any adjustment applied. If any adjustment had been previously applied, calling this function with a value of 0 will restore a clock to its default rate. A positive value will cause the clock frequency to increase from the nominal rate, and a negative value will cause the clock frequency to decrease from the nominal rate. The specific unit of rate increase/decrease is platform defined, although typically might reflect a number of parts per million or parts per billion depending on clock design. If the underlying device does not support rate adjustment, then this function will return the UNIMPLEMENTED Result value. A typical use-case of this function would periodically compute the difference between the reference clock and the local clock component, which is then multiplied by a feedback ratio (proportional coefficient) to compute the adjustment value to pass into this function. |
12.9.4 STI Infrastructure-Provided CLK_GetTimeAdjust Method
STI-116 The STI infrastructure shall provide the CLK_GetTimeAdjust() definition as specified in Table 93 to be implemented by an STI clock.
Table 94: CLK_GetTimeAdjust() Definition
Declaration |
|
---|---|
Description | Obtain the current tick rate adjustment value of the clock component. |
Parameters | |
Return | Return the current tick rate adjustment value |
Notes | A return value of 0 indicates the clock is operating at its nominal or free-run frequency. If the underlying device does not support rate adjustment, then this function always returns 0. A positive value indicates the clock frequency is above nominal, and a negative value indicates the clock frequency is below nominal. The specific units of the TimeRate value are platform defined, although typically might reflect a number of parts per million or parts per billion depending on clock design. |
12.9.5 STI Infrastructure-Provided CLK_Sleep Method
STI-117 The STI infrastructure shall provide the CLK_Sleep() definition as specified in Table 94 to be implemented by an STI clock.
Table 95: CLK_Sleep() Definition
Declaration |
|
---|---|
Description | Delay the caller until the specified interval has elapsed, as measured by the clock component. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The call may be interrupted under some circumstances, causing the infrastructure to return to the caller before the interval has elapsed. In these cases, the infrastructure should return the WARNING response. Note that the actual Sleep time may be longer than requested due to the resolution of the clock component and operating system scheduling variances. Setting a clock using CLK_SetTime() while this operation is in progress has undefined effects on the delay operation. |
12.9.6 STI Infrastructure-Provided CLK_DelayUntil Method
STI-118 The STI infrastructure shall provide the CLK_DelayUntil() definition as specified in Table 95 to be implemented by an STI clock.
Table 96: CLK_DelayUntil() Definition
Declaration |
|
---|---|
Description | Delay the caller until the clock reaches the indicated value. |
Parameters |
|
Return | On success, return the predefined Result value OK; otherwise, return one of the predefined Result values indicating failure. See 12.4.6 STI Infrastructure-Provided Result Values. |
Notes | The call may be interrupted under some circumstances, causing the infrastructure to return to the caller before the end time has been reached. In these cases, the infrastructure should return the WARNING response. Note that the actual Sleep time may be longer than requested due to the resolution of the clock component and operating system scheduling variances. Setting a clock using CLK_SetTime() while this operation is in progress has undefined effects on the delay operation. |
Acronyms
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Up to top
Acronym | Description | Hoverable Version |
---|---|---|
DSP | Digital Signal Processor | DSP |
FIFO | First In, First Out | FIFO |
FPGA | Fixed Point Gate Array | FPGA |
GPP | General Purpose Processor | GPP |
GPS | Global Positioning System | GPS |
HAL | Hardware Abstraction Layer | HAL |
HID | Hardware Interface Description | HID |
ISO | International Organization for Standardization | ISO |
MJD | Modified Julian Date | MJD |
NASA | National Aeronautics and Space Administration | NASA |
NTP | Network Time Protocol | NTP |
OE | Operating Environment | OE |
OS | Operating System | OS |
STI | Space Telecommunications Interface | STI |
TAI | International Atomic Time | TAI |
UTC | Coordinated Universal Time | UTC |
Skip to Section 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, or Up to top