Macintosh-SW
/
tashtalk
mirror of https://github.com/lampmerchant/tashtalk.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
tashtalk/documentation/protocol.md

6.5 KiB
Raw Permalink Blame History

TashTalk UART Protocol

Host to TashTalk

Flow Control

The firmware accepts bytes over its UART receiver at all times, including while actively transmitting or receiving LocalTalk frames. When its 128-byte buffer is half-full, it deasserts the CTS (Clear To Send) line to request that the host suspend transmission of data. When the buffer falls below half-full, it reasserts CTS to request that the host resume transmission of data. The host must stop transmission soon after the CTS line is deasserted to prevent overflow of the queue. Because the firmware does not keep an entire frame to transmit in memory at once, the host must also promptly resume transmission once the CTS line is reasserted to prevent underflow of the queue. Overflow or underflow of the queue will result in undefined behavior.

Commands

0x00 - No Operation

This command byte does nothing. As such, the host can send it as many times as it likes to no ill effect. A sequence of 1024 0x00 bytes will be certain to return the chip's UART receiver to the state where it awaits a command byte.

0x01 - Transmit Frame

This command byte prepares the firmware to accept a frame to transmit over LocalTalk. It is simply followed by the frame to be transmitted, byte for byte with no escape sequences.

  • The host must calculate and provide the two-byte CRC sequence for the payload frame.
  • The end of the frame is not explicitly marked and will be inferred from the frame data.
    • Control frames, where the high bit of the third (LLAP type) byte is set, consist of five bytes.
    • Data frames, where the high bit of the third (LLAP type) byte is clear, are variable length.
      • The length of a data frame is defined in its fifth byte and the two least significant bits of its fourth byte.
      • This number includes the length field, but not the three LLAP header bytes or the two CRC bytes.
      • LocalTalk specifies that this number may not exceed 600, but the firmware does not enforce this limit.
  • Data frames will be preceded by an RTS frame (generated by the firmware) and non-broadcast data frames will be transmitted in response to a CTS frame, following the algorithm as detailed in Inside AppleTalk.
  • The firmware will await the next command byte after the transmission completes or after 32 failed attempts at transmission.

0x02 - Set Node IDs

This command byte determines on which node IDs' behalf the firmware will respond to ENQ and RTS frames. It is followed by a 256-bit (32-byte) bit field, with each bit corresponding to one of the 256 possible node IDs on the LocalTalk network.

The first byte following the 0x02 command byte determines whether the firmware will respond on behalf of node IDs 0 through 7, with a 1 in the least significant bit causing the firmware to respond on behalf of node ID 0, and a 1 in the most significant bit causing it to respond on behalf of node ID 7. Likewise, the next byte determines whether the firmware will respond on behalf of node IDs 8 through 15, with the least significant bit corresponding to 8 and the most significant bit corresponding to 15, and so on up to the 32nd byte following the 0x02 command byte.

Note that 0x00 and 0xFF are not valid for use as node IDs on a LocalTalk network; the bits corresponding to these node IDs should never be set. The former may not cause any problems, but the latter will prevent any broadcast data frames from being transmitted.

0x03 - Set Features

This command requires version 2.1.0 of the firmware or later.

This command byte determines which optional features are active. It is followed by a single-byte bit field, the bits of which have the following significance:

Bit 7: CRC Calculation

When this bit is set, TashTalk will calculate CRCs for all outbound frames, not just for the control frames that it sends automatically. When transmitting the frame to TashTalk over the UART, the two CRC bytes at the end of the frame must still be present, but they will be overwritten with the correct CRC for the frame.

Bit 6: CRC Checking

When this bit is set, TashTalk will check the CRCs for all inbound frames, not just for the control frames that it responds to automatically. The frame data will be relayed to the host regardless of the CRC status, but if the CRC is incorrect, a different escape sequence (see Escape Sequences below) will follow the end of the frame.

Bits 5-0: Reserved

These bits are reserved for future optional features and should be maintained clear to ensure compatibility.

TashTalk to Host

The firmware retransmits over its UART all frames going over the LocalTalk bus, regardless of source, type, or destination, excepting those that it transmits itself. It will also transmit frames that it responds to itself; it is important to bear this in mind so that, for example, duplicate responses to ENQ frames are not transmitted.

Escape Sequences

In order to accomplish in-band signalling, the firmware uses an 0x00 byte as the first half of an escape sequence. The character following the 0x00 byte determines its meaning.

0x00 0xFF - Literal 0x00

This sequence signifies a literal 0x00 byte in the frame being received.

0x00 0xFD - Frame Done

This sequence signifies the end of a frame where no exceptional conditions occurred. The host should regard the data preceding it as an incoming frame, process it if its CRC is correct, and await the start of a new frame.

If the CRC Checking feature is enabled, this sequence also signifies that the frame's CRC was correct.

0x00 0xFE - Framing Error

This sequence signifies a framing error - a condition in which six consecutive '1' bits are received but cannot be interpreted as a flag byte. The host should discard the data preceding it and await the start of a new frame.

0x00 0xFA - Frame Aborted

This sequence signifies an aborted frame - a condition where a host had been transmitting a frame but unexpectedly stopped without a concluding flag byte. The host should discard the data preceding it and await the start of a new frame.

0x00 0xFC - Frame CRC Check Failed

This sequence was introduced in version 2.1.0 of the firmware.

This sequence, which is only used when the CRC Checking feature is enabled (see Set Features command above), signifies the end of a frame which was structurally correct but had an incorrect CRC. The host should discard the data preceding it and await the start of a new frame.