**********************************************************************
TITH                                              THIS ISN'T THAT HARD
**********************************************************************

Publication:  TTS‑0002
Revision:     1
Title:        Type Length Value Encoding
Author(s):    Stephen Hurd
Date:         2025‑11‑14
══════════════════════════════════════════════════════════════════════

Status of this document
───────────────────────

  This document is a TITH Technical Standard (TTS) — it specifies
  the current technical requirements and recommendations for TITH
  software developers, coordinators and sysops of the Fidonet network
  and other networks using FTN technology.

  This document is released to the public domain, and may be used,
  copied or modified for any purpose whatever.

Abstract
────────

  Many TITH packages use binary encoding of data.  When this is done,
  The encoding will conform to this document.

Contents
────────

  1.  Introduction
  2.  Purpose
  3.  Limitations
  4.  Decoding
  5.  Encoding

  A. References
  B. History

══════════════════════════════════════════════════════════════════════


1. Introduction
───────────────

  In many cases, a binary format is used for transferring data.  While
  with text, there's a generally understood set of formatting concepts
  (lines, paragraphs, etc.), binary data has no such concepts.

  There are many ways of organizing binary data, but one of the most
  pervasive is the Type Length Value (TLV) encodings.  This family of
  encodings preceeds each conceptually separate chunk of binary data
  with a value indicating how the contents should be interpreted (the
  Type), then a value indicating how many bytes it take up (the
  Length), and finally followed the the data itself.

  This allows easy extensibility since more types can always be added,
  and software that doesn't know about a specific type can easily skip
  past it and see if it understands the next chunk of data.

  The types themselves can also allow varying levels of abstraction,
  everything from "A single byte" to "A FidoNet packet" could be
  indicated by a type.


2. Purpose
──────────

  This document defines how the Type and Length is encoded in TLV
  values as used by TITH software.  Because all TITH software that
  deals in binary data uses the same encoding, this allows for a small
  reusable library to exist.


3. Limitations
──────────────

  The encoding described in this document does not limit the values at
  all, 2052‑bit values can be encoded using these rules.  However, it
  is convenient to put a "reasonable" limit on values so software can
  more efficiently deal with them.

  To this end, any software that parses TLV values MUST be capable of
  parsing at least 32‑bit values, and SHOULD parse at least 63‑bit
  values.


4. Decoding
───────────

  Values are decoded by taking the seven least significant bits of the
  number and adding them to the running value.  If the high bit is
  one, the running value is multiplied by 128 (ie: shifted left 7) and
  the next byte receives the same treatment.

  As an example, if we have the bytes 130 and 122, we would decode the
  value as follows:
     ________
  0b1000'0010 (130)

  The low seven bits represent the number 2, so we would add two to
  our running total (which starts as zero), giving us 2.  Since the
  high bit is set, we then multiply it by 128, resulting in 256 and
  parse the next byte:
     ________
  0b0111'1010 (122)

  Adding 122 to 256 results in 378.  Since the high bit is not set, we
  are done, and the decoded value is 378.


5. Encoding
───────────

  Encoding is a bit trickier because the most significant seven byte
  group is encoded first.  The easiest is to find the position of the
  most significant set bit in the value and divide it by seven
  rounding up:

  0b0000'0001'0111'1010 (378)
    1111 111
    6543 2109 8765 4321

  The most significant bit here is in position number nine.  Nine
  divided by seven is one and two sevenths (1²⁄₇, or 1.29) which,
  rounded up, is two indicating that it will take two bytes to encode.

  For each byte, we can take the original number, and divide it by 128
  times the number of bytes that will follow it (ie: right shift seven
  times times the number of following bytes), take the lowest seven
  bits of the result and, if there are any bytes after it, set the
  high bit to one.

  So 378 divided by 128 is 2, and there's an additional byte left,
  so the first encoded byte would be 130. For the next byte, there's
  no need to divide anymore and we just take the low seven bits as‐is
  and our second byte is 122.


A. References
─────────────

  [FTA‑1006] "Keywords to indicate requirement levels"
  FTSC, 2000‑01‑17.


B. History
──────────

   Rev.1, 2025‑11‑14: Initial Release.

**********************************************************************
