1# Copyright 2024 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 15# This file contains Emboss definitions for Host Controller Interface packets 16# and types found in the Bluetooth Core Specification. The Emboss compiler is 17# used to generate a C++ header from this file. 18 19[$default byte_order: "LittleEndian"] 20[(cpp) namespace: "pw::bluetooth::emboss"] 21# =========================== HCI Data Definitions =========================== 22 23 24enum AclDataPacketBoundaryFlag: 25 -- Options for the Packet_Boundary_Flag field in an ACL Data frame header. 26 27 [maximum_bits: 2] 28 29 FIRST_NON_FLUSHABLE = 0b00 30 -- First non-automatically-flushable packet of a higher layer message (start 31 -- of a nonautomatically-flushable L2CAP PDU) from Host to Controller. 32 33 CONTINUING_FRAGMENT = 0b01 34 -- Continuing fragment of a higher layer message. 35 36 FIRST_FLUSHABLE = 0b10 37 -- First automatically flushable packet of a higher layer message (start of 38 -- an automatically-flushable L2CAP PDU). 39 40 41enum AclDataPacketBroadcastFlag: 42 -- Options for the Broadcast_Flag field in an ACL Data frame header. 43 [maximum_bits: 2] 44 POINT_TO_POINT = 0b00 45 -- ACL-U or LE-U 46 47 BROADCAST = 0b01 48 -- BR/EDR broadcast (APB-U) 49 50 51struct AclDataFrameHeader: 52 -- HCI ACL Data packet frame header 53 -- Core Spec v5.4, Vol 4, Part E, Section 5.4.2 54 0 [+2] bits: 55 0 [+12] UInt handle 56 -- Connection_Handle to be used for transmitting a data packet or segment 57 -- over a Controller. 58 -- [requires: 0x0000 <= this <= 0x0EFF] 59 60 $next [+2] AclDataPacketBoundaryFlag packet_boundary_flag 61 $next [+2] AclDataPacketBroadcastFlag broadcast_flag 62 63 $next [+2] UInt data_total_length 64 -- Length of data measured in octets. 65 66 67struct AclDataFrame: 68 -- HCI ACL Data packet frame 69 -- Core Spec v5.4, Vol 4, Part E, Section 5.4.2 70 0 [+AclDataFrameHeader.$size_in_bytes] AclDataFrameHeader header 71 let data_total_length = header.data_total_length 72 $next [+data_total_length] UInt:8[data_total_length] payload 73 74 75enum TsFlag: 76 -- Options for the ts_flag field in an Isochronous Data packet header. 77 [maximum_bits: 1] 78 TIMESTAMP_NOT_PRESENT = 0b0 79 -- The Time_Stamp field is not present in the packet. 80 81 TIMESTAMP_PRESENT = 0b1 82 -- The Time_Stamp field is present in the packet. 83 84 85enum IsoDataPbFlag: 86 -- Options for the pb_flag field in an Isochronous Data packet header. 87 88 [maximum_bits: 2] 89 90 FIRST_FRAGMENT = 0b00 91 -- The ISO_SDU_Fragment field contains the first fragment of a 92 -- fragmented SDU. 93 94 INTERMEDIATE_FRAGMENT = 0b01 95 -- The ISO_SDU_Fragment field contains an intermediate fragment of an 96 -- SDU. 97 98 COMPLETE_SDU = 0b10 99 -- The ISO_SDU_Fragment field contains a complete SDU. 100 101 LAST_FRAGMENT = 0b11 102 -- The ISO_SDU_Fragment field contains the last fragment of an SDU. 103 104 105enum IsoDataPacketStatus: 106 -- Options for the packet_status_flag field in an Isochronous Data packet header. 107 108 [maximum_bits: 2] 109 110 VALID_DATA = 0b00 111 -- Valid data. The complete SDU was received correctly. 112 113 POSSIBLY_INVALID_DATA = 0b01 114 -- The contents of the ISO_SDU_Fragment may contain errors or part of 115 -- the SDU may be missing. This is reported as "data with possible 116 -- errors". 117 118 LOST_DATA = 0b10 119 -- Part(s) of the SDU were not received correctly. This is reported 120 -- as "lost data". 121 122 123struct IsoDataFrameHeader: 124 -- HCI Iso Data Packet Header 125 -- Core Spec v5.4, Vol 4, Part E, Section 5.4.5 126 -- Bits 15, 30, and 31 are reserved for future use (RFU) 127 0 [+4] bits: 128 0 [+12] UInt connection_handle 129 -- Connection handle to be used for transmitting an ISO SUD or fragment. 130 [requires: 0x0000 <= this <= 0x0EFF] 131 132 12 [+2] IsoDataPbFlag pb_flag 133 -- Describes packet fragmentation 134 135 14 [+1] TsFlag ts_flag 136 -- Describes whether or not a timestamp is present 137 138 16 [+14] UInt data_total_length 139 -- Length of the packet, excluding the packet header, in octets. 140 141 142struct IsoDataFramePacket: 143 -- HCI Iso Data Packet 144 -- Core Spec v5.4, Vol 4, Part E, Section 5.4.5 145 -- Bits 28, and 29 are reserved for future use (RFU) 146 let hdr_size = IsoDataFrameHeader.$size_in_bytes 147 0 [+hdr_size] IsoDataFrameHeader header 148 if header.ts_flag == TsFlag.TIMESTAMP_PRESENT: 149 hdr_size [+4] UInt time_stamp 150 -- A time in microseconds. 151 152 let ts_size = (header.ts_flag == TsFlag.TIMESTAMP_PRESENT) ? 4 : 0 153 let sdu_hdr_offset = hdr_size+ts_size 154 if header.pb_flag == IsoDataPbFlag.FIRST_FRAGMENT || header.pb_flag == IsoDataPbFlag.COMPLETE_SDU: 155 sdu_hdr_offset [+4] bits: 156 0 [+16] UInt packet_sequence_number 157 -- The sequence number of the SDU. 158 159 16 [+12] UInt iso_sdu_length 160 -- The total length of the SDU (and not of any individual fragments), 161 -- in octets. 162 163 30 [+2] IsoDataPacketStatus packet_status_flag 164 -- Packet status, only for frames sent by the controller. 165 166 let sdu_hdr_size = (header.pb_flag == IsoDataPbFlag.FIRST_FRAGMENT || header.pb_flag == IsoDataPbFlag.COMPLETE_SDU) ? 4 : 0 167 let sdu_fragment_offset = hdr_size+ts_size+sdu_hdr_size 168 let sdu_fragment_size = header.data_total_length-(ts_size+sdu_hdr_size) 169 sdu_fragment_offset [+sdu_fragment_size] UInt:8[sdu_fragment_size] iso_sdu_fragment 170 -- Isochronous data (the SDU or fragment of the SDU) 171 172 173enum ScoDataPacketStatus: 174 -- Options for the packet_status_flag field in an Synchronous Data packet 175 -- header. 176 177 [maximum_bits: 2] 178 179 CORRECTLY_RECEIVED_DATA = 0b00 180 -- The payload data belongs to received eSCO or SCO packets that the 181 -- Baseband marked as “good data”. 182 183 POSSIBLY_INVALID_DATA = 0b01 184 -- At least one eSCO packet has been marked by the Baseband as “data with 185 -- possible errors” and all others have been marked as “good data” in the 186 -- eSCO interval(s) corresponding to the HCI Synchronous Data packet. 187 188 NO_DATA_RECEIVE = 0b10 189 -- All data from the Baseband received during the (e)SCO interval(s) 190 -- corresponding to the HCI Synchronous Data packet have been marked as 191 -- "lost data" by the Baseband. The Payload data octets shall be set to 0. 192 193 DATA_PARTIALLY_LOST = 0b11 194 -- Not all, but at least one (e)SCO packet has been marked as “lost data” 195 -- by the Baseband in the (e)SCO intervals corresponding to the HCI 196 -- Synchronous Data packet. The payload data octets corresponding to the 197 -- missing (e)SCO packets shall be set to 0. 198 199 200struct ScoDataHeader: 201 -- HCI Synchronous Data packets 202 -- Core Spec v5.4, Vol 4, Part E, Section 5.4.3 203 -- Bits 14, and 15 are reserved for future use (RFU) 204 0 [+3] bits: 205 0 [+12] UInt connection_handle 206 -- Connection handle to be used for transmitting an ISO SUD or fragment. 207 [requires: 0x0000 <= this <= 0x0EFF] 208 209 12 [+2] ScoDataPacketStatus packet_status_flag 210 -- Packet status, only for frames sent by the controller. 211 212 16 [+8] UInt data_total_length 213 -- Length of the packet, excluding the packet header, in octets. 214