Draft P. Marheine August 9, 2010 TI Serial Data Interchange Protocol Abstract This RFC defines a simple protocol layer (the TI-SDIP) suitable for use as a data interchange among TI graphing calculators and associated devices in a link- and software-independent manner. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 2 1.2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Data formatting . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Figures . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.2. Byte and bit ordering . . . . . . . . . . . . . . . . . . 3 2.3. Strings . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.4. Reserved fields . . . . . . . . . . . . . . . . . . . . . 4 3. Protocol description . . . . . . . . . . . . . . . . . . . . . 4 3.1. Packet format . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Packet types . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.1. ACK . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.2. NAK . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.2.3. VTN . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.2.4. VTP . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.2.5. PING . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.2.6. LST . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.2.7. LSTR . . . . . . . . . . . . . . . . . . . . . . . . . 11 4. Conversation examples . . . . . . . . . . . . . . . . . . . . 11 4.1. Protocol errors . . . . . . . . . . . . . . . . . . . . . 11 4.2. VTN/VTP usage . . . . . . . . . . . . . . . . . . . . . . 12 4.3. LST/LSTR . . . . . . . . . . . . . . . . . . . . . . . . . 13 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Appendix A. Defined hashfiles . . . . . . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 Marheine [Page 1] TI Serial Data Interchange Protocol August 2010 1. Introduction The graphing calculators produced by Texas Instruments (TI) are very flexible bits of commodity hardware, well-suited to customization. However, the proprietary serial link protocol used by the devices is needlessly complex for most purposes as well as being implemented in an incredubly arcane manner despite the valiant reverse-engineering efforts of several developers, resulting in such documents as the TI Link Protocol & File Format Guide [TILPFFG], which, while useful, remains a pain to implement. For the sanity of developers targeting such platforms, this document specifies a data interchange protocol suitable for use on all TI calculators and associated peripherals or devices. 1.1. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. 1.2. Objectives The designer has sought to meet certain objectives in the design of the protocol, as outlined in this section. Ease of implementation The proposal seeks to replace a proprietary and difficult-to- implement protocol, so ease of implementation is very much desirable. Robustness Linking between devices is usually done across noisy links and in the presence of potentially careless users, so the protocol should be able to handle data errors and unexpected loss of connection. Speed Data transfers are typically done in the presence of users and in an interactive manner, so a reasonably high effective data rate is desired in order to impose less upon the user's time. As this document makes no claims about the link layer in use, the specification should seek only to minimize protocol overhead. Marheine [Page 2] TI Serial Data Interchange Protocol August 2010 2. Data formatting The TI-SDIP is byte-oriented, and expects to receive data from the link layer in 8-bit bytes. This section outlines the terminology used to refer to bytes and subdivisions thereof. 2.1. Figures In illustrations, a '+' is used to delimit individual bits of a field, while '|' delimits fields, and '][' denotes a byte boundary. 2.2. Byte and bit ordering Byte values are represented in this specification as groupings of 8 bits, numbered right to left from 0 to 7. When bit groupings are used to represent integers, bit 0 is the least significant bit, with significance increasing in order with bit number. Byte 1 Byte 2 +-+-+-+-+-+-+-+-][-+-+-+-+-+-+-+-+ |7 6 5 4 3 2 1 0][7 6 5 4 3 2 1 0| |_______________][_______________| Figure 1: Bit numbering within bytes When multi-byte integers are used, the value is transmitted LSB- first, followed by additional bytes in order of increasing significance. Multi-byte integer transmission Time --> +----+----+----+----+ | 78 | 56 | 34 | 12 | |____|____|____|____| Figure 2: Sending 0x12345678 2.3. Strings Text strings in the protocol are expected to be 7-bit ASCII with the high-order bit reset. Strings contained within packet payloads do not have null terminators- string length is determined only by the size of the payload. Marheine [Page 3] TI Serial Data Interchange Protocol August 2010 2.4. Reserved fields Fields marked as reserved MUST be both read and written as zero (all bits reset). Reserved values MUST NOT be written to the corresponding field and packets containing such reserved values SHOULD be rejected by a receiver. 3. Protocol description The protocol is based on the concept of a 'conversation', with only one device transmitting at once. Each conversation consists of a packet transferred from the sender followed by a response from the receiver, repeating until an implicit end to the conversation. 3.1. Packet format Header Payload Checksum +-+-+-+-+-+-+-+-][-+-+-+-+-+-+-+-][- - - - - - -][-------][--------+ | P |R| P | P ][ ][ ][ | | R |E| I | S ][ PSL ][ DATA ][ CKSUM | | V |S| D | H ][ ][ ][ | |___|_|_____|___][_______________][_ _ _ _ _ _ _][_______][________| Figure 3: Packet format Every packet consists of a short header, payload of up to 1023 bytes, and checksum, as outlined in Figure 3, with the header containing several subfields. Each field is detailed below. PSIZE (PSH/PSL) 10-bit unsigned value giving the size of the packet's payload, in bytes, in the range of 0 to 1023. PSH is the two high-order bits of the value and PSL is the lower eight. DATA PSIZE-byte block containing the payload. Meaning is context- specific for conversation and PID. CKSUM Two's complement Fletcher-16 checksum (as described in RFC1146 [RFC1146]) of the packet header and payload, stored as a 16-bit integer with the simple checksum in the upper byte and the second component in the low byte. For example, a simple component of 0x1F and secondary part of 0x82 would yield a CKSUM of 0x1F82. A Z80 assembly implementation of the two's complement Fletcher-16 is provided in Figure 4. Marheine [Page 4] TI Serial Data Interchange Protocol August 2010 00 | fletcher_verify: 01 | ld a,(hl) 02 | ld d,a ;Simple checksum 03 | ld e,a ;Fletcher component 04 | and 3 05 | ld b,a ;PSH 06 | inc hl 07 | ld c,(hl) ;PSL 08 | fletcher_verify_loop: ;PSIZE iterations 09 | inc hl ;Next word 10 | ld a,b 11 | or c ;Check counter 12 | jr z,fletcher_done ;End if 0 13 | ld a,(hl) 14 | add a,d 15 | ld d,a ;Update simple sum 16 | add a,e 17 | ld e,a ;Fletcher component 18 | dec bc ;Update counter 19 | jr fletcher_verify_loop 20 | fletcher_done: HL points to a buffer containing a complete packet, returns CKSUM in DE. Figure 4: Packet checksum verification for Z80 PRV The PRV field indicates which protocol version is in use. Compliant implementations MUST write as 0 and reject any packets in which PRV is non-zero, as the meaning of this value will change in future protocol revisions. RES Reserved. See Section 2.4 for details. PID Packet ID, which identifies the message type contained in the packet. Legal PID symbols and the corresponding values are listed in Table 1, while symbol meanings are defined in Section 3.2. Marheine [Page 5] TI Serial Data Interchange Protocol August 2010 +-------+------+-------+----------+ | Value | Type | Value | Type | +-------+------+-------+----------+ | 0000 | ACK | 1000 | Reserved | | 0001 | NAK | | | | | | 0010 | VTN | | | | | | 0011 | VTP | | | | | | 0100 | PING | | | | | | 0101 | LST | v | v | | 0111 | LSTR | 1111 | Reserved | +-------+------+-------+----------+ Table 1: PID values 3.2. Packet types A conversation is initiated by the sending of any non-ACK and non-NAK packet, which is responded to with either an ACK or NAK from the device on the other end of the link, indicating either successful reception or some failure, respectively. Implementations MUST NOT respond to ACK or NAK under any circumstances, as such behaviour could easily result in an ACK or NAK storm, flooding the link. The conversation initiator MUST wait for some acknowledgement of reception (ACK or NAK) before continuing, and MAY attempt retransmission of a packet if no such response arrives, up to a defined retransmission limit. This allows additional robustness in cases where unstable links prevent packet delivery. Packets are differentiated by the PID field, and this section of the specification uses the PID symbols defined in Table 1 to refer to each of those. 3.2.1. ACK The ACK packet is sent as an affirmative in response to any other packet, indicating successful reception. An ACK SHOULD NOT have any payload, except in specific cases defined elsewhere. 3.2.2. NAK NAK (Negative Acknowledgement) is sent in response to any packet when a. Packet fails integrity checks (invalid CKSUM) b. A malformed packet arrives Marheine [Page 6] TI Serial Data Interchange Protocol August 2010 c. Packet does not make sense in the conversational context d. Receiver is not ready or unable to handle a request Every NAK must have a payload of at least one byte, the value of which indicates the reason for NAK. Table 2 lists the values defined for the reason byte. Any additional payload beyond the reason byte is an optional string describing the error in more detail, formatted as in Section 2.3. +-------+--------------------+-------+------------------------+ | Value | Description | Value | Description | +-------+--------------------+-------+------------------------+ | 000 | Nonsense packet | 128 | Integrity check failed | | 001 | Receiver not ready | 129 | Malformed packet | | 002 | File DNE | 130 | Reserved | | | | | | | | | | | v | v | | | | | | 126 | Reserved | v | v | | 127 | Misc error | 255 | Reserved | +-------+--------------------+-------+------------------------+ Table 2: NAK reasons All of the NAK types listed in Table 2 are intended to be reasonably self-explanitory. Type 2, however, requires some extra explanation. Specifically, it should only be used in response to a VTN with RWF set, in the case where the requested file does not exist. While no NAK type requires that a string payload be included, it is strongly recommended that type 127 include a payload describing the error in some detail. Bit 7 of the reason byte is used as a flag hinting at the utility of retransmission. When reset, retransmission is not likely to succeed, while setting the bit indicates the converse, that retransmitting the last packet is likely to succeed. Of the listed reasons, then, 0-127 are those unlikely to be caused by link errors and instead by either conditions on the receiver or a buggy sender implementation, while 128-255 are those conditions likely to be caused only by link errors. In the case of type 129, the set retransmission flag was chosen such that cases where the packet header is corrupted may be handled gracefully. Readers should note that the retransmission bit only constitutes a hint regarding retransmission and not an absolute requirement. Ignoring a negative hint (flag reset) will only results in retransmitting until the limit is reached, while ignoring a positive Marheine [Page 7] TI Serial Data Interchange Protocol August 2010 hint causes a protocol-layer error on the initial sender rather than any real problem. 3.2.3. VTN VTN is used in conjunction with multiple VTP packets to effect bulk data transfers between devices. Usage of both types is demonstrated in Section 4.2 A VTN (Variable Transfer Negotiation) packet marks the beginning of a bulk transfer, typically some data stored on the device (a "variable" in common calculator parlance, or a "file" on most other systems). The VTN payload consists of several fields which define the requested transfer, outlined in Figure 5. +-+-+------][--------][--------][--------][- - - - - - - -+ |R| ][ ][ | |W| RES ][ VSZ ][ VARID | |F| ][ ][ | |_|________][________][________][________][_ _ _ _ _ _ _ _| Figure 5: VTN payload RWF The Read/Write Flag (RWF) indicates whether the conversation initiator wishes to send or receive data. When set, receive is sought, while reset means send. RES Reserved. VSZ VSZ is a 24-bit integer indicating the size of the transfer. When RWF is set, VSZ SHOULD be set to zero. Receivers SHOULD ignore the value of VSZ when RWF is set. VARID VARID is a string identifying the variable to be transferred. The string's length is determined from the packet's payload size, by subtracting the combined sizes of RWF, RES, OOR and VSZ from the total payload size. Devices MUST allow variable names of up to 8 characters, but may allow any length. It is recommended that a device reject transfer (with a type 2 NAK) if a name is too long to be used without modification. VARID may contain null characters, but the first instance of null in the string is taken to mark the string's end. Any characters Marheine [Page 8] TI Serial Data Interchange Protocol August 2010 following that MUST be ignored. A VTN with RWF reset is followed by the initial sender transmitting a series of VTPs containing the variable data. When RWF is set, the receiver instead begins a new conversation with another VTN, requesting transmission of the same VARID as given in the initial VTN. For examples of the variable transmission process, see Section 4.2 3.2.3.1. Hashfiles The TI-SDIP defines several special files (hashfiles) which allow retrieval of device meta-information such as platform, version number, and file listing. All special file names are prefixed with a '#' (hash) character. Use of a hash as the first character of a regular file ID is permitted but not recommended. Senders SHOULD NOT attempt to write hashfiles by sending a VTN with RWF reset and VARID as a special file, but receivers MAY choose to honor such requests rather than NAKing. The exact behaviour in such a case is implementation-defined, but it is suggested that hashfile writes (as in the response VTN following a read request) be treated purely as advisory information. Although this specification defines a set of hashfiles (enumerated in Appendix A), implementors are free to define additional ones as desired. 3.2.4. VTP A series of VTP (Variable Transfer Payload) always follows a VTN. While VTN requests that a transfer be made, the VTPs contain the actual data as it is transferred. A VTP is illegal as the first message in a conversation, so should be NAKed in such cases. Each VTP packet's payload consists of a file offset and zero or more bytes of raw data, shown in Figure 6. +--------][--------][--------][- - - - - - | ][ | FOFS ][ Data | ][ |________][________][________][_ _ _ _ _ _ Figure 6: VTP payload In the payload, the FOFS field is a 24-bit integer identifying the file offset of the data section contained within the packet. Valid Marheine [Page 9] TI Serial Data Interchange Protocol August 2010 values are 0 to FSZ-1. The FOFS field SHOULD NOT be used for random access of files, such as by sending a VTP with FOFS=64 then another with FOFS=8. However, receivers MAY choose to accept such constructs, in which case the exact behaviour is implementation-defined. The intended purpose of FOFS, however, is to provide additional error-checking for file contents, for example in the case of link interruption causing the silent loss of one or more VTPs, in which case those lost packets will be detected, causing an error. Therefore, it is recommended that most devices NAK (type 0) when an out-of-sequence FOFS arrives except in well-defined situations. The exact number of VTPs that are sent for any particular transfer is dependent on both the payload size used and the total transfer size. Reception of VTP is valid until the receiver has gotten a total of VSZ bytes of data, at which point the conversation implicitly ends. All VTNs MUST be followed by at least one VTP, even when VSZ equals 0x000000, in which case a single VTP with no data should be sent. 3.2.5. PING The PING packet may be used to elicit an ACK from a connected device, thus ascertaining what manner of device (if any) is connected to the link. It is RECOMMENDED that the payload of a PING packet contain a string identifying the device sending the packet. In addition, the payload of any ACK sent in response to a PING SHOULD contain similar identifying information about the corresponding device. Identifying strings SHOULD take the form "NAME,VERSION", such as "TILP 2,1.41.4" or "Giant Olm,r247" for ease of identification. An identifying payload in PING and the corresponding ACK packets allows devices to ascertain what sort of device is on the other end of a link. For example, an implementor might choose to behave in a slightly different manner given the presence of a certain known-buggy implementation on the other end of a link. 3.2.6. LST LST (LiST variables) is a request for a connected device to enumerate its files and return a list in a series of LSTR responses. See Section 3.2.7 for details on the process. Marheine [Page 10] TI Serial Data Interchange Protocol August 2010 3.2.7. LSTR LiST Response. Upon reception of a LST, a device responds with a series of LSTRs. Each LSTR contains a series of tuples of a variable name as a null-terminated string and a 24-bit integer representing the variable's size. Every LSTR begins with a 16-bit integer which indicates the total number of variables present. Figure 7 illustrates the format for LSTR payloads. Note that there may be multiple VSIZE/VNAME pairs within a single packet, up to the value of VCNT. LSTRs are valid until a total of VCNT VSIZE/VNAME pairs have arrived. +--------][--------][--------][--------][- - - - - - - -+- - - - - | ][ ][ | VSIZE / | VCNT ][ VSIZE ][ VNAME | VNAME | ][ ][ | may repeat |________][________][________][________][_ _ _ _ _ _ _ _|_ _ _ _ _ Figure 7: LSTR payload 4. Conversation examples This section provides a variety of examples illustrating valid exchanges in the TI-SDIP between two devices. In all figures in this section, --> and <-- indicate packet transmission from left-to-right and right-to-left, respectively, with packet type and payload given on either side. For example, in Figure 8, device A (on the left) sends a PING packet to device B (on the right) and receives an ACK in return, where the payloads are the strings "TILP2 1.0" and "VXLink 0.1" (in this case those being the version strings of each device). A B Time PING --> "TILP2 1.0" | <-- ACK "VXLink 0.1" v Figure 8: Ping and ACK 4.1. Protocol errors A variety of situations are possible in which one device is not behaving as another expects, possibly due to link errors or a buggy implementation on one end. What follows are some example scenarios demonstrating the expected behavious in some such erroneous cases. Marheine [Page 11] TI Serial Data Interchange Protocol August 2010 A B Time PING --> "TILP2 1.0" | <-- NAK 128 | PING --> "TILP2 1.0" | <-- ACK "LIFOS 0.0.2a" v A link error causes a checksum failure for device B on the PING packet, so it responds with a type-128 NAK. A retransmits the PING, which is then positively acknowledged by B. Figure 9: PING with checksum failure A B Time VTP --> datadatadata | [no response] | VTP --> datadatadata | <-- NAK 0,"No active VTP" v Device A attempts a VTP, but gets no acknowledgement. Device B NAKs (type 0) a retransmission of VTP, complaining it doesn't make sense. Figure 10: Erroneous VTP 4.2. VTN/VTP usage Figure 11 and Figure 12 illustrate the combined usage of VTN and VTP messages to effect data transfer between devices as specified in Section 3.2.3. A B Time _ A B VTN --> 0x80,0x000000, | / \ <-- ACK "UltraCarp" | | | VTP --> 0,"Dwarven " <-- NAK 2 | | | <-- ACK VTN --> 0x00,0x000012, | | | VTP --> 8,"ingenuity",0 "UltraCarp" \_/ v <-- ACK Device A asks to receive file 'UltraCarp', which is denied by the receiver, stating "file DNE". Device A then transmits a file of the same name, which is 18 bytes long and contains the null-terminated string "Dwarven ingenuity". The contents of the file are transmitted split across two packets. Figure 11: Variable send Marheine [Page 12] TI Serial Data Interchange Protocol August 2010 A B Time _ A B VTN --> 0x80,0x000000, | / \ ACK --> <-- ACK | | | <-- VTP 0,[empty] <-- VTN 0x00,0x000000, | | v ACK --> "A" \_/ Device A requests and gets file 'A', which is zero bytes in length. Figure 12: Variable reception Note that in Figure 12, device A does not count reception complete until at least one VTP has arrived. 4.3. LST/LSTR Usage of LST and LSTR is similar to that of VTN and VTP, and is demonstrated in Figure 13. Note that as with VTP, the response stream must be at least one LSTR. A B Time _ A B LST --> | / \ ACK --> <-- ACK | | | <-- LSTR 0x0002, <-- LSTR 0x0002, | | | 0x000E4A,"NERV" 0x008000,"SEELE" \_/ v ACK --> Device A requests a file listing from B, which responds with a series of LSTR saying it contains files "SEELE" and "NERV", which are 32k and 3658 bytes, respectively. Figure 13: Usage of LST 5. Acknowledgements This document was generated with xml2rfc and is based on a template by Elwyn Davies. 6. Security Considerations This protocol provides no considerations for data security, due to the insensitive nature of most data contained on the target devices. For sensitive applications, it is recommended that users either implement a further layer of data security above the protocol or use a different protocol with better inherent security. Due to the expectation of a response from most packets, it could be possible for a malicious implementation to cause other devices to Marheine [Page 13] TI Serial Data Interchange Protocol August 2010 stop responding to user input, such as by sending a VTN to receive but never ACKing the following VTP, thus locking the sending device in a loop. To avoid such a possibility, implementations should include an ACK timeout (and retransmission limit if applicable) such that a conversation in progress will be aborted if either the timeout or retransmission limit are reached. 7. References [RFC1146] Zweig, J. and C. Partridge, "TCP alternate checksum options", RFC 1146, March 1990. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [TILPFFG] Lievin, R. and T. Singer, "TI Link Protocol & File Format Guide", September 2006, . Appendix A. Defined hashfiles This appendix lists the specification-defined hashfiles as described in Section 3.2.3.1. There are currently no officially-defined hashfiles. Author's Address Peter Marheine Email: peter at-domain taricorp dot-net URI: http://taricorp.net/ Marheine [Page 14]