1# Copyright 2020 The Pigweed Authors
2#
3# Licensed under the Apache License, Version 2.0 (the "License"); you may not
4# use this file except in compliance with the License. You may obtain a copy of
5# the License at
6#
7#     https://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12# License for the specific language governing permissions and limitations under
13# the License.
14"""Module for low-level HDLC protocol features."""
15
16from typing import Tuple
17
18import zlib
19
20# Special flag character for delimiting HDLC frames.
21FLAG = 0x7E
22
23# Special character for escaping other special characters in a frame.
24ESCAPE = 0x7D
25
26# Characters allowed after a 0x7d escape character.
27VALID_ESCAPED_BYTES = 0x5D, 0x5E
28
29# Maximum allowed HDLC address (uint64_t in C++).
30MAX_ADDRESS = 2**64 - 1
31
32
33def escape(byte: int) -> int:
34    """Escapes or unescapes a byte, which should have been preceeded by 0x7d."""
35    return byte ^ 0x20
36
37
38def frame_check_sequence(data: bytes) -> bytes:
39    return zlib.crc32(data).to_bytes(4, 'little')
40
41
42def encode_address(address: int) -> bytes:
43    """Encodes an HDLC address as a one-terminated LSB varint."""
44    result = bytearray()
45
46    while True:
47        result += bytes([(address & 0x7f) << 1])
48
49        address >>= 7
50        if address == 0:
51            break
52
53    result[-1] |= 0x1
54    return result
55
56
57def decode_address(frame: bytes) -> Tuple[int, int]:
58    """Decodes an HDLC address from a frame, returning it and its size."""
59    result = 0
60    length = 0
61
62    while length < len(frame):
63        byte = frame[length]
64        result |= (byte >> 1) << (length * 7)
65        length += 1
66
67        if byte & 0x1 == 0x1:
68            break
69
70    if result > MAX_ADDRESS:
71        return -1, 0
72
73    return result, length
74
75
76class UFrameControl:
77    def __init__(self, frame_type: int):
78        self._data: bytes = bytes([0x03 | frame_type])
79
80    @property
81    def data(self):
82        return self._data
83
84    @classmethod
85    def unnumbered_information(cls):
86        return UFrameControl(0x00)
87