API_1.2.2_20080331_EthernetDevice__JTRS Standards API Release 1.3.3
Total Pages 82 Joint Tactical Radio System (JTRS) Standard
Ethernet Device
Application Program Interface (API)
Version: 1.2.2
31 March 2008
Statement A- Approved for public release; distribution is unlimited (29 March 2007)
REVISION HISTORY
Version Authorization Description Last Modified Date
23-January-2006
1.0 Initial release
ICWG Approved
1.1 Update outline format
26-January-2006
ICWG Approved
1.1.1 Preparation for public release 29-March-2007
24-August-2007 1.2
-Removed Valid Ranges from
Provides Services
-Added Section B, Mode
Configuration Extension
-Added Section C, Multicast Mode
Extension
-Added Section D, Promiscuous
Mode Extension
-Added Section E, Header
Configuration Extension
-Added Section F, MAC Address
Extension
1.2 Updates based on ICWG review 01-October-2007
11-October-2007
1.2.1 Updates based on ICWG:
Added “WF TX and RX
directions” clarification in Header
Configuration Extension
ICWG Approved
31 March 2008
1.2.2 Corrected document redlines for
public release
A.ETHERNET DEVICE (10)
B.MODE CONFIGURATION EXTENSION (31)
C.MULTICAST MODE EXTENSION (44)
D.PROMISCUOUS MODE EXTENSION (51)
E.HEADER CONFIGURATION EXTENSION (58)
F.MAC ADDRESS EXTENSION (71)
A.ETHERNET DEVICE (10)
A.1Introduction (10)
A.1.1 Overview (10)
A.1.2 Service Layer Description (11)
A.1.2.1 Ethernet Device Port Connections (11)
A.1.3 Modes of Service (12)
A.1.4 Service States (12)
A.1.4.1 Ethernet Device State Diagram (12)
A.1.5 Referenced Documents (13)
A.1.5.1 Government Documents (13)
A.1.5.2 Commercial Standards (13)
A.2Services (14)
A.2.1 Provide Services (14)
A.2.2 Use Services (16)
A.2.3 Interface Modules (18)
A.2.3.1 Ethernet (18)
A.2.4 Sequence Diagrams (19)
A.2.4.1 Transfer Data (19)
A.3Service Primitives and Attributes (23)
A.3.1 Ethernet::EthernetPacketConsumer (24)
A.3.1.1 pushPacket Operation (24)
A.4IDL (25)
A.4.1 Ethernet (25)
A.5UML (26)
A.5.1 Data Types (27)
A.5.2 Enumerations (27)
A.5.3 Exceptions (27)
A.5.4 Structures (27)
Appendix A.A Abbreviations and Acronyms (28)
Appendix A.B Performance Specification (29)
Appendix A.C Payload Size Specification (30)
B.MODE CONFIGURATION EXTENSION (31)
B.1Introduction (31)
B.1.1 Overview (31)
B.1.2 Service Layer Description (32)
B.1.2.1 Mode Configuration Extension Port Connections (32)
B.1.3 Modes of Service (33)
B.1.4 Service States (33)
B.1.5 Referenced Documents (33)
B.2Services (34)
B.2.1 Provide Services (34)
B.2.2 Use Services (34)
B.2.3 Interface Modules (35)
B.2.3.1 Ethernet (35)
B.2.4 Sequence Diagrams (35)
B.3Service Primitives and Attributes (36)
B.3.1 Ethernet::EthernetModeConfig (37)
B.3.1.1 getMode Operation (37)
B.3.1.2 setMode Operation (38)
B.4IDL (39)
B.4.1 EthernetModeConfigExt (39)
B.5UML (40)
B.5.1 Data Types (41)
B.5.2 Enumerations (41)
B.5.2.1 Ethernet::EthernetMode (41)
B.5.3 Exceptions (41)
B.5.4 Structures (41)
Appendix B.A Abbreviations and Acronyms (42)
Appendix B.B Performance Specification (43)
C.MULTICAST MODE EXTENSION (44)
C.1Introduction (44)
C.1.1 Overview (44)
C.1.2 Service Layer Description (44)
C.1.3 Modes of Service (44)
C.1.4 Service States (44)
C.1.5 Referenced Documents (44)
C.2Services (45)
C.3Service Primitives and Attributes (45)
C.4IDL (46)
C.4.1 EthernetMulticastConfigExt (46)
C.5UML (47)
C.5.1 Data Types (48)
C.5.2 Enumerations (48)
C.5.3 Exceptions (48)
C.5.4 Structures (48)
Appendix C.A Abbreviations and Acronyms (49)
Appendix C.B Performance Specification (50)
D.PROMISCUOUS MODE EXTENSION (51)
D.1Introduction (51)
D.1.1 Overview (51)
D.1.2 Service Layer Description (51)
D.1.3 Modes of Service (51)
D.1.4 Service States (51)
D.1.5 Referenced Documents (51)
D.2Services (52)
D.3Service Primitives and Attributes (52)
D.4IDL (53)
D.4.1 EthernetPromiscuousConfigExt (53)
D.5UML (54)
D.5.1 Data Types (55)
D.5.2 Enumerations (55)
D.5.3 Exceptions (55)
D.5.4 Structures (55)
Appendix D.A Abbreviations and Acronyms (56)
Appendix D.B Performance Specification (57)
E.HEADER CONFIGURATION EXTENSION (58)
E.1Introduction (58)
E.1.1 Overview (58)
E.1.2 Service Layer Description (59)
E.1.2.1 Header Configuration Extension Port Connections (59)
E.1.3 Modes of Service (60)
E.1.4 Service States (60)
E.1.5 Referenced Documents (60)
E.2Services (61)
E.2.1 Provide Services (61)
E.2.2 Use Services (61)
E.2.3 Interface Modules (62)
E.2.3.1 Ethernet (62)
E.2.4 Sequence Diagrams (62)
E.3Service Primitives and Attributes (63)
E.3.1 Ethernet::EthernetHeaderConfig (64)
E.3.1.1 getRetainHeader Operation (64)
E.3.1.2 setRetainHeader Operation (65)
E.4IDL (66)
E.4.1 EthernetHeaderConfigExt (66)
E.5UML (67)
E.5.1 Data Types (68)
E.5.2 Enumerations (68)
E.5.3 Exceptions (68)
E.5.4 Structures (68)
Appendix E.A Abbreviations and Acronyms (69)
Appendix E.B Performance Specification (70)
F.MAC ADDRESS EXTENSION (71)
F.1Introduction (71)
F.1.1 Overview (71)
F.1.2 Service Layer Description (72)
F.1.2.1 MAC Address Extension Port Connections (72)
F.1.3 Modes of Service (73)
F.1.4 Service States (73)
F.1.5 Referenced Documents (73)
F.2Services (74)
F.2.1 Provide Services (74)
F.2.2 Use Services (74)
F.2.3 Interface Modules (75)
F.2.3.1 Ethernet (75)
F.2.3.2 Sequence Diagrams (75)
F.3Service Primitives and Attributes (76)
F.3.1 Ethernet::EthernetAddress (77)
F.3.1.1 getMacAddress Operation (77)
F.4IDL (78)
F.4.1 EthernetMacAddressExt (78)
F.5UML (79)
F.5.1 Data Types (80)
F.5.2 Enumerations (80)
F.5.3 Exceptions (80)
F.5.4 Structures (80)
Appendix F.A Abbreviations and Acronyms (81)
Appendix F.B Performance Specification (82)
F IGURE 1–E THERNET D EVICE P ORT D IAGRAM (11)
F IGURE 2–E THERNET D EVICE S TATE D IAGRAM (12)
F IGURE 3–E THERNET D EVICE C LASS D IAGRAM (18)
F IGURE 4–D EVICE P ROVIDES D ATA S EQUENCE D IAGRAM (20)
F IGURE 5–D EVICE C ONSUMES D ATA S EQUENCE D IAGRAM (22)
F IGURE 6–E THERNET D EVICE C OMPONENT D IAGRAM (26)
F IGURE 7-M ODE C ONFIGURATION E XTENSION P ORT D IAGRAM (32)
F IGURE 8–E THERNET M ODE C ONFIG I NTERFACE D IAGRAM (35)
F IGURE 9–M ODE C ONFIGURATION E XTENSION C OMPONENT D IAGRAM (40)
F IGURE 10–M ULTICAST C ONFIGURATION E XTENSION C OMPONENT D IAGRAM (47)
F IGURE 11–P ROMISCUOUS M ODE C ONFIGURATION E XTENSION C OMPONENT D IAGRAM (54)
F IGURE 12-H EADER C ONFIGURATION E XTENSION P ORT D IAGRAM (59)
F IGURE 13–E THERNET H EADER C ONFIG I NTERFACE D IAGRAM (62)
F IGURE 14–H EADER C ONFIGURATION E XTENSION C OMPONENT D IAGRAM (67)
F IGURE 15-MAC A DDRESS E XTENSION P ORT D IAGRAM (72)
F IGURE 16–E THERNET A DDRESS I NTERFACE D IAGRAM (75)
F IGURE 17–MAC A DDRESS E XTENSION C OMPONENT D IAGRAM (79)
T ABLE 1–E THERNET D EVICE P ROVIDE S ERVICE I NTERFACE (14)
T ABLE 2–E THERNET D EVICE P ROVIDE S ERVICE A GGREGATE I NTERFACE (15)
T ABLE 3–E THERNET D EVICE U SE S ERVICE I NTERFACE (16)
T ABLE 4–E THERNET D EVICE P ERFORMANCE S PECIFICATION (29)
T ABLE 5–P AYLOAD S IZE P ROVIDE S ERVICE I NTERFACE (30)
T ABLE 6–M ODE C ONFIGURATION E XTENSION P ROVIDE S ERVICE I NTERFACE (34)
T ABLE 7–M ODE C ONFIGURATION E XTENSION P ERFORMANCE S PECIFICATION (43)
T ABLE 8–H EADER C ONFIGURATION E XTENSION P ROVIDE S ERVICE I NTERFACE (61)
T ABLE 9–H EADER C ONFIGURATION E XTENSION P ERFORMANCE S PECIFICATION (70)
T ABLE 10–MAC A DDRESS E XTENSION P ROVIDE S ERVICE I NTERFACE (74)
T ABLE 11–MAC A DDRESS E XTENSION P ERFORMANCE S PECIFICATION (82)
A.ETHERNET DEVICE
A.1INTRODUCTION
The Ethernet Device supports methods and attributes that are specific to the Ethernet hardware (HW) device it represents.
This document defines a common set of Ethernet Device provide services and interfaces required by most Joint Tactical Radio (JTR) Sets.
The Ethernet Device acts as “device adapter”. It is used by Common Object Request Broker Architecture (CORBA) components (e.g., waveform application components) to access JTR Set Ethernet HW.
A.1.1Overview
This base contains as follows:
a.Section A.1, Introduction, contains the introductory material regarding the overview, service layer
description, modes, states and referenced documents of this document.
b.Section A.2, Services, provides summary of service interface uses, interface for each device
component, port connections, and sequence diagrams.
c.Section A.3, Service Primitives and Attributes, specifies the operations that are provided by the
Ethernet Device.
d.Section A.4, IDL.
e.Section A.5, UML.
f.Appendix A.A, Abbreviations and Acronyms.
g.Appendix A.B, Performance Specification.
h.Appendix A.C, Payload Size Specification.
A.1.2Service Layer Description
A.1.2.1Ethernet Device Port Connections
Figure 1 shows the port connections for the Ethernet Device which is an aggregation of the Ethernet and the Device Message Control IDL [1].
Note: All port names are for reference only.
A.1.3Modes of Service
Not applicable.
A.1.4Service States
A.1.4.1Ethernet Device State Diagram
The Ethernet Device states are illustrated in the following diagram. The Ethernet Device states ensure that received operations are only executed when the Ethernet Device is in the proper state. The five states of the Ethernet Device are as follow:
?CONSTRUCTED - The state transitioned to upon successful creation.
?INITIALIZED - The state transitioned to upon successful initialization.
?ENABLED - The state transitioned to upon successful start.
?DISABLED - The state transitioned to upon successful stop.
?RELEASED - The state transitioned to upon successful release.
The Ethernet Device transitions between states in response to the initialize, start, stop and releaseObject operations [6].
Figure 2 – Ethernet Device State Diagram
A.1.5Referenced Documents
The following documents of the exact issue shown form a part of this specification to the extent specified herein.
A.1.5.1Government Documents
The following documents are part of this specification as specified herein.
A.1.5.1.1Specifications
A.1.5.1.1.1Federal Specifications
None
A.1.5.1.1.2Military Specifications
None
A.1.5.1.2Other Government Agency Documents
[1] JTRS Standard, “Device Message Control API,” JPEO, Version 1.1.2.
[2] JTRS Standard, “Device Packet Signals API,” JPEO, Version 1.2.2.
[3] JTRS Standard, “Device IO Signals API,” JPEO, Version 1.1.1.
[4] JTRS Standard, “Device Packet API,” JPEO, Version 1.1.1.
[5] JTRS Standard, “Device IO Control API,” JPEO, Version 1.1.1.
[6] JTRS Standard, “Software Communications Architecture (SCA),” JPEO, Version 2.2.2.
[7] JTRS Standard, “JTRS CORBA Types,” JPEO, Version 1.0.2.
A.1.5.2Commercial Standards
None
A.2.3Interface Modules A.2.3.1Ethernet
pushPacket()getMaxPayloadSize() getMinPayloadSize() getNumOfPriorities() setNumOfPriorities() enableFlowResumeSignals() enableEmptySignals() spaceAvailable() getDesiredPayloadSize() getMinOverrideTimeout()
setMaxPayloadSize() setMinPayloadSize() setDesiredPayloadSize() setMinOverrideTimeout()
signalEmpty() signalFlowResume()
enableRTSCTS()
setRTS()
setCTS()
rxActive()
txActive()
abortTx()
Figure 3 – Ethernet Device Class Diagram
A.2.3.1.1EthernetPacketConsumer Interface Description
The interface design of the EthernetPacketConsumer is shown in Figure 3. It extends the DeviceIOControl [5] and DevicePacket [4] interfaces to provide the ability to transfer data packets to Ethernet HW with flow control.
A.2.3.1.2EthernetPacketProducer Interface Description
The interface design of the EthernetPacketProducer is shown in Figure 3. It extends the DeviceIOSignals [3] and DevicePacketSignals [2] interfaces to provide the ability to transfer data packets from Ethernet HW with flow control.
A.2.4Sequence Diagrams
A.2.4.1Transfer Data
The Transfer Device Use Case covers scenarios in which data is transferred to or from a Radio Device. The scenarios are dependent on whether the Device needs to provide or consume data.
A.2.4.1.1Device Provides Data Sequence
Description
A Device provides data as shown in Figure 4. The Device in this sequence is the Ethernet Device. The Device User in the sequence is the EthernetPacketConsumer.
Upon connection to the Device User, the Device issues enableRTSCTS and enableFlowResumeSignal commands to the Device User. When data is available, the Device pushes it to the Device User using the pushPacket method. In this diagram, the flow control mechanism that can be used by the Device User to halt pushPacket(s) is demonstrated when the pushPacket returns FALSE. Ordinarily this is issued if the Device User cannot hold at least one more packet of maxPayloadSize. Once the Device User is ready to receive more packets, it issues a signalFlowResume to the Device. Once this is received, the Device resumes pushing data to the Device User using the pushPacket method.
Pre-conditions
The Device is in the ENABLED state.
Post-conditions
The Device is pushing incoming data to the Device User and responding to flow control as needed.
Figure 4 – Device Provides Data Sequence Diagram