Interprocess Message Formats

347 views

Published on

This Technical Note describes the Message formats used in PathMATE Multi-Process
deployments when communicating between any two process instances.

Section 2 provides an overview of the different message protocol layers involved during
transmission defining basic terminology and the basic concepts.

Section 3 describes in the detail the PathMATE Application Messaging Protocol and all supported message formats, as defined for the CPP Transformation Maps in 8.2.0 software releases.

Appendix A lists sources for referenced information for Ethernet and TCPIP protocols.

Published in: Technology, Business
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
347
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
6
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Interprocess Message Formats

  1. 1. Interprocess Message Formats Version 0.2 March 21, 2011PathMATE Technical Notes Pathfinder Solutions www.pathfindermdd.com +1 508-568-0068 Copyright 1995-2011 Pathfinder Solutions LLC – all rights reserved
  2. 2. Table Of Contents1 Introduction .......................................................................................... 12 Overview............................................................................................... 1 2.1 Terminology.................................................................................. 1 2.1.1 The TCP/IP Network model ....................................................... 1 2.1.2 Ethernet Link Protocol - Layer 1 ................................................ 1 2.1.3 Internet Protocol(IP)- Layer 2 ................................................... 2 2.1.4 TCP Transport Protocol - Layer 3 ............................................... 3 2.1.5 PathMATE Application Protocol - Layer 4 ..................................... 33 PathMATE Application Messaging Protocol ............................................ 5 3.1 Incident Message Type ................................................................... 5 3.1.1 Service Handle Incident Type.................................................... 5 3.1.1.1 32bit Signed Integer(INTEGER_VALUE) ...................................... 6 3.1.1.2 64bit Signed Integer(LONG_LONG_VALUE) ................................. 6 3.1.1.3 64bit Floating Point Value(REAL_VALUE)..................................... 6 3.1.1.4 32bit/64bit Pointer Value(POINTER_VALUE) ................................ 7 3.1.1.5 String Value(STRING_VALUE) ................................................... 7 3.1.1.6 Service Handle(SVCHANDLE_VALUE) ......................................... 7 3.1.1.7 Fine Grained Time Value(TIME_VALUE) ...................................... 7 3.1.1.8 Groups and External Serialized Types (SERIAL_VALUE or RC_SERIAL_VALUE) ............................................................................... 8 3.2 Init Connection Message Type ......................................................... 9 3.3 External Realized Message Type......................................................10 3.4 Shutdown Notification Message Type ...............................................10A. Appendix - References ........................................................................ 10 Table Of FiguresFigure 1 - Ethernet Protocol............................................................................. 1Figure 2 - IP Header and Data within an Ethernet Packet ..................................... 2Figure 3 - IP Header Definition ......................................................................... 2Figure 4 - TCP Header and Data within an IP Packet............................................ 3Figure 5 - TCP Header Definition ...................................................................... 3Figure 6 - PathMATE Application Message Definition ............................................ 3Figure 7 - Depiction PathMATE messages transmitted over Ethernet packets .......... 5 ii
  3. 3. Interprocess Message Formats1 IntroductionThis Technical Note describes the Message formats used in PathMATE Multi-Processdeployments when communicating between any two process instances.Section 2 provides an overview of the different message protocol layers involved duringtransmission defining basic terminology and the basic concepts.Section 3 describes in the detail the PathMATE Application Messaging Protocol and allsupported message formats, as defined for the CPP Transformation Maps in 8.2.0 softwarereleases.Appendix A lists sources for referenced information for Ethernet and TCPIP protocols.2 Overview2.1 TerminologyIn the document we first present the various network protocol layers used in sendingPathMATE messages using the TCPIP protocol suite and over an Ethernet based network.2.1.1 The TCP/IP Network modelThe TCP/IP Network model defines four layers to define the combination of protocols used forcommunication:  Layer 1 - Link - The Link layer defines the device driver and network hardware(network interface card). Ethernet/IEEE 802.3 is handles the link layer.  Layer 2 - Internet(aka Network) - The Internet layer handles basic communication, addressing and routing. IP, ICMP, ARP and IGMP protocols are at the network layer.  Layer 3 - Transport Layer - The Transport layer handles flow of data among applications. It segments data into packets for transport over the network. TCP and UDP operate at the transport layer.  Layer 4 - Application - The Application layer handles details of the particular end-user applications. Commonly used TCP/IP applications include Telnet, FTP, SMTP, SNMP, DNS, RIP, NFS, NTP, Traceroute. In this document we will define the PathMATE application layer message protocol in detail.2.1.2 Ethernet Link Protocol - Layer 1Ethernet protocols refer to the family of local-area network (LAN) covered by the IEEE 802.3.Below is the basic IEEE 802.e Ethernet MAC Data Frame for 10/100Mbps Ethernet: 6 4 7 1 6 byte 2 bytes 46-1500 bytes bytebytes bytes Bytes s s Pre SFD DA SA Length Type Data unit + pad FCS Figure 1 - Ethernet Protocol  Preamble (PRE)- 7 bytes. The PRE is an alternating pattern of ones and zeros that tells receiving stations that a frame is coming, and that provides a means to 1
  4. 4. Interprocess Message Formats synchronize the frame-reception portions of receiving physical layers with the incoming bit stream.  Start-of-frame delimiter (SFD)- 1 byte. The SOF is an alternating pattern of ones and zeros, ending with two consecutive 1-bits indicating that the next bit is the left- most bit in the left-most byte of the destination address.  Destination address (DA)- 6 bytes. The DA field identifies which station(s) should receive the frame..  Source addresses (SA)- 6 bytes. The SA field identifies the sending station.  Length/Type- 2 bytes. This field indicates either the number of MAC-client data bytes that are contained in the data field of the frame, or the frame type ID if the frame is assembled using an optional format.  Data- Is a sequence of n bytes (46=< n =<1500) of any value. (The total frame minimum is 64bytes.)  Frame check sequence (FCS)- 4 bytes. This sequence contains a 32-bit cyclic redundancy check (CRC) value, which is created by the sending MAC and is recalculated by the receiving MAC to check for damaged frames. 2.1.3 Internet Protocol(IP)- Layer 2 The Internet Protocol (IP) is the principal communications protocol used for relaying datagrams (packets) across an internetwork using the Internet Protocol Suite. Responsible for routing packets across network boundaries, it is the primary protocol that establishes the Internet. MAC MAC IP Header IP Data Header FCS Figure 2 - IP Header and Data within an Ethernet Packet00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 Version IHL Differentiated Services Total length Identification Flags Fragment offset TTL Protocol Header checksum Source IP address Destination IP address Options and padding ::: Figure 3 - IP Header Definition Specific field information is as follows: Version - Set to 4 for IP Protocol Protocol - Set to 6 when the next encapsulated protocol is TCP Padding - used to ensure that the IP Data starts at a 32-bit boundary. For more detailed IP Header information refer to the following link: http://www.networksorcery.com/enp/protocol/ip.htm 2
  5. 5. Interprocess Message Formats 2.1.4 TCP Transport Protocol - Layer 3 TCP is a transport layer protocol used by applications that require guaranteed delivery. It is a sliding window protocol that provides handling for both timeouts and retransmissions. TCP establishes a full duplex virtual connection between two endpoints. Each endpoint is defined by an IP address and a TCP port number. The operation of TCP is implemented as a finite state machine. The byte stream is transferred in segments. The window size determines the number of bytes of data that can be sent before an acknowledgement from the receiver is necessary. MAC IP MAC TCP Header TCP Byte Stream Data Header Header FCS Figure 4 - TCP Header and Data within an IP Packet00 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 Source Port Destination Port Sequence Number Acknowledgment NumberData Offset reserved ECN Control Bits Window Checksum Urgent Pointer Options and padding ::: Figure 5 - TCP Header Definition For more detailed TCP Header information refer to the following link: http://www.networksorcery.com/enp/protocol/tcp.htm 2.1.5 PathMATE Application Protocol - Layer 4 All PathMATE messages conform to format specified in the following figure. 1-2147483639 bytes (The actual Message Size Dependent on Type and will 4 bytes 4 bytes be limited to heap memory allocation restrictions on each process) Message Length Message Type Message Data Figure 6 - PathMATE Application Message Definition  Message Length - 4 bytes. Indicates the number of bytes for the next message in the byte stream, including the Message Type (4 bytes) and the Message Data. 3
  6. 6. Interprocess Message Formats  Message Type - 4 bytes. The message type indicates the specific contents of the Message Data. Currently there are four defined message types: 1. SW_SOCK_MSG_INIT_CONN = 18 - Message sent to remote process after a new connection is established. 2. SW_SOCK_MSG_INTERPROCESS_INCIDENT_HANDLE = 353 - Message used to send messages containing an incident, which currently can only be a service incident type (used to send domain service handles and class service handles). 3. SW_SOCK_MSG_INTERPROCESS_SHUTDOWN = 355 - When a process is shutdown, it send this message to remote processes on all active connections to notify that it is shutting down. 4. SW_SOCK_MSG_REALIZED_EXTERNAL = 777 - Message type used to allow sharing of PathMATE socket connections with external realized code. This allows communications between realized code integrated with PathMATE and external processes executing realized code developed independently of PathMATE.  Message Data - Contains the message type specific data. See section 3 for more detail regarding each message type. As with all TCPIP standard based protocols, PathMATE adheres to serializing and transmitting all multi-byte data types in Network Byte Order (which is also the same as Big Endian). That is, the Most Significant Byte is transmitted first. For example, the Message Length is sent as a 32-bit word, byte offset 0 contains the most significant byte and byte offset 3 contains the least significant byte. On a 0x86 PC data is stored natively in Little Endian format, where the Least Significant Byte(LSB) is stored in offset 0, and the Most Significant Byte(MSB) is stored in byte offset 3. When transmitting a message from a little endian based processor, all multi-byte data types are converted to match Network Byte Order. Vice-Versa, when receiving data the data is converted to the native little endian format. On Big Endian based processors no conversion is necessary. PathMATE messages are sent on an established TCP/IP based socket, which is a guaranteed delivery based protocol. A PathMATE message is inserted into the socket byte stream. A TCP packet can contain a single or multiple PathMATE messages, and on the Process receiving the byte stream the PathMATE messages are distinguished with the following procedure: 1. After a socket is established, the Transmitting process sends the complete PathMATE message over the socket. The number of bytes transmitted MUST match the number of bytes comprising the message length (4 bytes) + the message type (4 bytes) + the message data (the actual message data length + the message type MUST match exactly the length indicated in the message length field. Any deviation from this will prevent the receiver process to achieve message synchronization. 2. The receiving process will first read ONLY 4 bytes, which contain the message length of the remaining bytes to read. Once the Message length is read, it then can read the remaining message using the received message length. 3. Subsequent messages can be read following the previous step. As TCP sends data as a byte stream, each TCP packet can contain multiple PathMATE messages or a portion of a single large PathMATE message. The figure on the next page shows a depiction of how messages can appear on TCP/IP packets over Ethernet. The 4
  7. 7. Interprocess Message Formats number within the TCP Data field indicates distinct PathMATE messages. The figure shows 3 complete messages and a partial message (the 4th message). Data Packet 1 MAC IP TCP TCP Byte Stream Data MAC Header Header Header 1 1 2 2 FCS Data Packet 2 MAC IP TCP TCP Byte Stream Data MAC Header Header Header 2 3 3 FCS Data Packet 3 MAC IP TCP TCP Byte Stream Data MAC Header Header Header 3 FCS Data Packet 4 MAC IP TCP TCP Byte Stream Data MAC Header Header Header 3 4 4 FCS Figure 7 - Depiction PathMATE messages transmitted over Ethernet packets 3 PathMATE Application Messaging Protocol The following sections describe more detail for each PathMATE message types. 3.1 Incident Message Type 3.1.1 Service Handle Incident Type The following figure shows the fixed portion of service handle incident message.Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 Message Length Length of Message Type + Message Data 04 4 Message Type 00 00 01 61 (353) 08 4 Incident Type 00 00 00 00 (0) 0C 4 Process Type Deployment value index for Process Type 10 4 Sentinel Value DE AD FA CE 14 4 Message Version 00 00 00 01 18 4 Process ID Unique Process Identifier 1C 4 Domain Index Deployment value index for Domain 20 4 Service Index Deployment value index for Domain or Class Service 24 4 Task Index Deployment value index for Task ID 28 2 Destination(not used) 2 byte string -> "0," 2A 4 Priority (not set) 00 00 00 00 2E 4 Sender Process (not set) 00 00 00 00 5
  8. 8. Interprocess Message FormatsRelative Byte Size Data Name Data Values Offset (bytes) (in Hex) 32 4 Sender Task (not set) 00 00 00 00 36 4 Parameter Count # of parameters for domain or class service 3A 4 Provided Parameter Count # of of provided parameters for domain or class serviceThe following Parameter fields are provided for each parameter value specified forthis service handle. 3E 4 Parameter "name" index Deployment value index for parameter name 42 4 Parameter native data type value index for native data type 46 Based on Parameter Value Based on data type native data type The following sub sections describes the various PathMATE native data types. 3.1.1.1 32bit Signed Integer(INTEGER_VALUE)Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 INTEGER_VALUE 00 00 00 01 04 4 32bit Signed Integer Value -2147483648 (80 00 00 00) to 2147483647(7F FF FF FF) 3.1.1.2 64bit Signed Integer(LONG_LONG_VALUE)Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 LONG_LONG_VALUE 00 00 00 0A 04 8 64bit Signed Integer Value -9223372036854775808 (80 00 00 00 00 00 00 00) to 9223372036854775807 (7F FF FF FF FF FF FF FF) 3.1.1.3 64bit Floating Point Value(REAL_VALUE)Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 REAL_VALUE 00 00 00 02 04 8 64bit IEEE-754 Floating BIT63: Sign Bit Point Value BITS[62-52]:Exponent BITS[51-0]:Fraction 6
  9. 9. Interprocess Message Formats 3.1.1.4 32bit/64bit Pointer Value(POINTER_VALUE)Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 POINTER_VALUE 00 00 00 04 04 8 Native Host Pointer Value. Any Pointer Value Warning: Only relevant on Source Process or Shared Memory Map Address. On 32 bit processors the pointer is stored in the first most significant 32 bits. 3.1.1.5 String Value(STRING_VALUE)Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 STRING_VALUE 00 00 00 03 04 String Length Null Terminated String The last byte is a NULL character. +1 3.1.1.6 Service Handle(SVCHANDLE_VALUE)Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 SVCHANDLE_VALUE 00 00 00 05 The rest of the message is exactly as shown in section 3.1.1 - Service Handle Incident Type. 04 4 Incident Type 00 00 00 00 (0) 08 4 Process Type Deployment value index for Process Type 0C 4 Sentinel Value DE AD FA CE 10 4 Message Version 00 00 00 01 ... 3.1.1.7 Fine Grained Time Value(TIME_VALUE) NOTE: Currently Fine Grained time is not implemented. If an attempt to send a Fine Grain Time is attempted it will first be converted into a double floating point variable, then into a string representation of the value. The receiving process will have no way of knowing that it is a time variable. The current serialized output is shown here:Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 STRING_VALUE 00 00 00 03 04 String Length Null Terminated String The last byte is a NULL character. +1 representing the fine Examples: grained time in "1259009.0023" <- (in milliseconds. milliseconds) 7
  10. 10. Interprocess Message Formats In the future we may represent it natively as follows:Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 TIME_VALUE 00 00 00 09 04 4 Seconds Number of seconds since the process started 08 4 Nanoseconds Number of fractional nano- seconds in the current second 3.1.1.8 Groups and External Serialized Types (SERIAL_VALUE or RC_SERIAL_VALUE) PathMATE provides the ability to serialize/de-serialize externally defined types; to learn more about how to do this please refer to the advanced realized types technical note. There are two types of serialized data types: SERIAL_VALUE & RC_SERIAL_VALUE. They are serialized/de- serialized exactly the same, the difference being that the RC_SERIAL_VALUE provides an indication to the receiving process that the data type container class needs to have pointer reference counting. Here we will show the format for groups of specific native data types. Relative Size Data Name Data ValuesByte Offset (bytes) (in Hex) 00 4 SERIAL_VALUE 00 00 00 07 RC_SERIAL_VALUE 00 00 00 08 04 4 SERIAL_TYPE_[groupname] Deployment value index for the Group of Integer Example: group data type. This will not SERIAL_TYPE_GroupListInteger vary on the same deployment The remainder of the information provided for realized types is specified within the type’s serialization code itself. Generally this is a combination of PathMATE native data types specified in sections 3.1.1.1 through 3.1.1.7. The format for groups of generic data types is as follows:Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 SERIAL_VALUE 00 00 00 07 RC_SERIAL_VALUE 00 00 00 08 04 4 One of the following: Deployment value index SERIAL_TYPE_ListGroupGeneric for the generic group SERIAL_TYPE_ArrayGroupGeneric type. This will not vary SERIAL_TYPE_HashGroupGeneric on the same deployment 08 4 Number of Items(N) 1 or higher 0C 4 Native Data Type for value 1 One of the following: INTEGER_VALUE, LONG_LONG_VALUE, REAL_VALUE, POINTER_VALUE SVCHANDLE_VALUE, STRING_VALUE, 8
  11. 11. Interprocess Message FormatsRelative Byte Size Data Name Data Values Offset (bytes) (in Hex) SERIAL_VALUE, RC_SERIAL_VALUE 10 Datasize_item1 Value 1 Dependent on native data type 10 + 4 Native Data Type for value 2 One of the following:datasize_item1 INTEGER_VALUE, LONG_LONG_VALUE, REAL_VALUE, POINTER_VALUE SVCHANDLE_VALUE, STRING_VALUE, SERIAL_VALUE, RC_SERIAL_VALUE 10 + Datasize_item2 Value 2 Dependent on nativedatasize_item1 data type + 04 ... 0C + 4 Native Data Type for value N One of the following: SUM[N-1] INTEGER_VALUE, (04 + LONG_LONG_VALUE,datasize_itemx) REAL_VALUE, POINTER_VALUE SVCHANDLE_VALUE, STRING_VALUE, SERIAL_VALUE, RC_SERIAL_VALUE 0C + Datasize_itemN Value N Dependent on native SUM[N-1] data type (04 +datasize_itemx) + 04 3.2 Init Connection Message Type The following message is sent on the transmit socket after the Sender process establishes a socket with a process listening on a port. All of the provided data is from the Sender process.Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 Message Length 00 00 00 14 (20) 04 4 Message Type 00 00 01 12 (18) 08 4 Process Type Deployment index value for process type 0C 4 OS Process Id Runtime and OS dependent 10 4 Process ID Unique Process Identifier 14 4 Connection Count prior to 0 and higher this connection. 9
  12. 12. Interprocess Message Formats 3.3 External Realized Message Type External realized message types are simply defined by setting the message type field to 777, which over the network will be sent (shown in hex) as 00 00 03 09. The message data contents are user defined based on the external realized codeRelative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 Message Length Length of Message Type + user defined size 04 4 Message Type 00 00 03 09 (777) 08 User defined User Data Contains data defined by external size software 3.4 Shutdown Notification Message Type This message is sent to all connected remote processes to notify when the local process will close all connections and shut down.Relative Byte Size Data Name Data Values Offset (bytes) (in Hex) 00 4 Message Length 00 00 00 04 ( 4) 04 4 Message Type 00 00 01 63 (355) A. Appendix - References The following references where used in creating this document 1. PathMATE CPP Mechanisms 8.2.0 source code 2. http://en.wikipedia.org/wiki/IP_Protocol 3. http://en.wikipedia.org/wiki/IP 4. http://www.networksorcery.com/enp/protocol/ip.htm 5. http://www.networksorcery.com/enp/protocol/tcp.htm 6. http://www.speedguide.net/articles/the-tcpip-and-osi-network-models-120 10

×