1 // Copyright 2023 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 #pragma once
16 // clang-format off
17
18 #include <chrono>
19 #include <cstdint>
20 #include <limits>
21 #include <string>
22
23 #include <pw_chrono/system_clock.h>
24
25 #include "pw_bluetooth_sapphire/internal/host/common/macros.h"
26 #include "pw_bluetooth_sapphire/internal/host/l2cap/frame_headers.h"
27
28 namespace bt::l2cap {
29
30 // See Core Spec v5.0, Volume 3, Part A, Sec 8.6.2.1. Note that we assume there is no flush timeout
31 // on the underlying logical link.
32 static constexpr auto kErtmReceiverReadyPollTimerDuration = std::chrono::seconds(2);
33 static_assert(kErtmReceiverReadyPollTimerDuration <= std::chrono::milliseconds(std::numeric_limits<uint16_t>::max()));
34 static constexpr uint16_t kErtmReceiverReadyPollTimerMsecs = static_cast<uint16_t>(std::chrono::duration_cast<std::chrono::milliseconds>(kErtmReceiverReadyPollTimerDuration).count());
35
36 // See Core Spec v5.0, Volume 3, Part A, Sec 8.6.2.1. Note that we assume there is no flush timeout
37 // on the underlying logical link. If the link _does_ have a flush timeout, then our implementation
38 // will be slower to trigger the monitor timeout than the specification recommends.
39 static constexpr auto kErtmMonitorTimerDuration = std::chrono::seconds(12);
40 static_assert(kErtmMonitorTimerDuration <= std::chrono::milliseconds(std::numeric_limits<uint16_t>::max()));
41 static constexpr uint16_t kErtmMonitorTimerMsecs = static_cast<uint16_t>(std::chrono::duration_cast<std::chrono::milliseconds>(kErtmMonitorTimerDuration).count());
42
43 // See Core Spec v5.0, Volume 3, Part A, Sec 6.2.1. This is the initial value of the timeout duration.
44 // Although Signaling Channel packets are not sent as automatically flushable, Signaling Channel packets
45 // may not receive a response for reasons other than packet loss (e.g. peer is slow to respond due to pairing).
46 // As such, L2CAP uses the "at least double" back-off scheme to increase this timeout after retransmissions.
47 static constexpr auto kSignalingChannelResponseTimeout = std::chrono::seconds(1);
48 static_assert(kSignalingChannelResponseTimeout >= std::chrono::seconds(1));
49 static_assert(kSignalingChannelResponseTimeout <= std::chrono::seconds(60));
50
51 // Selected so that total time between initial transmission and last retransmission timout is less
52 // than 60 seconds when using the exponential back-off scheme.
53 static constexpr size_t kMaxSignalingChannelTransmissions = 5;
54
55 // See Core Spec v5.0, Volume 3, Part A, Sec 6.2.2. This initial value is the only timeout duration
56 // used because Signaling Channel packets are not to be sent as automatically flushable and thus
57 // requests will not be retransmitted at the L2CAP level per its "at least double" back-off scheme.
58 static constexpr auto kSignalingChannelExtendedResponseTimeout = std::chrono::seconds(60);
59 static_assert(kSignalingChannelExtendedResponseTimeout >= std::chrono::seconds(60));
60 static_assert(kSignalingChannelExtendedResponseTimeout <= std::chrono::seconds(300));
61 static constexpr pw::chrono::SystemClock::duration kPwSignalingChannelExtendedResponseTimeout = std::chrono::seconds(60);
62
63 // L2CAP channel identifier uniquely identifies fixed and connection-oriented
64 // channels over a logical link.
65 // (see Core Spec v5.0, Vol 3, Part A, Section 2.1)
66 using ChannelId = uint16_t;
67
68 // Null ID, "never be used as a destination endpoint"
69 constexpr ChannelId kInvalidChannelId = 0x0000;
70
71 // Fixed channel identifiers used in BR/EDR & AMP (i.e. ACL-U, ASB-U, and AMP-U
72 // logical links)
73 constexpr ChannelId kSignalingChannelId = 0x0001;
74 constexpr ChannelId kConnectionlessChannelId = 0x0002;
75 constexpr ChannelId kAMPManagerChannelId = 0x0003;
76 constexpr ChannelId kSMPChannelId = 0x0007;
77 constexpr ChannelId kAMPTestManagerChannelId = 0x003F;
78
79 // Fixed channel identifiers used in LE
80 constexpr ChannelId kATTChannelId = 0x0004;
81 constexpr ChannelId kLESignalingChannelId = 0x0005;
82 constexpr ChannelId kLESMPChannelId = 0x0006;
83
84 // Range of dynamic channel identifiers; each logical link has its own set of
85 // channel IDs (except for ACL-U and AMP-U, which share a namespace)
86 // (see Tables 2.1 and 2.2 in v5.0, Vol 3, Part A, Section 2.1)
87 constexpr ChannelId kFirstDynamicChannelId = 0x0040;
88 constexpr ChannelId kLastACLDynamicChannelId = 0xFFFF;
89 constexpr ChannelId kLastLEDynamicChannelId = 0x007F;
90
91 // Basic L2CAP header. This corresponds to the header used in a B-frame (Basic Information Frame)
92 // and is the basis of all other frame types.
93 struct BasicHeader {
94 uint16_t length;
95 ChannelId channel_id;
96 } __attribute__((packed));
97
98 // Frame Check Sequence (FCS) footer. This is computed for S- and I-frames per Core Spec v5.0, Vol
99 // 3, Part A, Section 3.3.5.
100 struct FrameCheckSequence {
101 uint16_t fcs;
102 } __attribute__((packed));
103
104 // Initial state of the FCS generating circuit is all zeroes per v5.0, Vol 3, Part A, Section 3.3.5,
105 // Figure 3.5.
106 constexpr FrameCheckSequence kInitialFcsValue = {0};
107
108 // The L2CAP MTU defines the maximum SDU size and is asymmetric. The following are the minimum and
109 // default MTU sizes that a L2CAP implementation must support (see Core Spec v5.0, Vol 3, Part A,
110 // Section 5.1).
111 constexpr uint16_t kDefaultMTU = 672;
112 constexpr uint16_t kMinACLMTU = 48;
113 constexpr uint16_t kMinLEMTU = 23;
114 constexpr uint16_t kMaxMTU = 0xFFFF;
115
116 // The maximum length of a L2CAP B-frame information payload.
117 constexpr uint16_t kMaxBasicFramePayloadSize = 65535;
118
119 // See Core Spec v5.0, Volume 3, Part A, Sec 8.6.2.1. This is the minimum permissible value of
120 // "TxWindow size" in the Retransmission & Flow Control Configuration Option.
121 static constexpr uint8_t kErtmMinUnackedInboundFrames = 1;
122
123 // See Core Spec v5.0, Volume 3, Part A, Sec 8.6.2.1. We do not have a limit on inbound data that we
124 // can receive in bursts based on memory constraints or other considerations, so this is simply the
125 // maximum permissible value.
126 static constexpr uint8_t kErtmMaxUnackedInboundFrames = 63;
127
128 // See Core Spec v5.0, Volume 3, Part A, Sec 8.6.2.1. We rely on the ERTM Monitor Timeout and the
129 // ACL-U Link Supervision Timeout to terminate links based on data loss rather than rely on the peer
130 // to handle unacked ERTM frames in the peer-to-local direction.
131 static constexpr uint8_t kErtmMaxInboundRetransmissions = 0; // Infinite retransmissions
132
133 // See Core Spec v5.0, Volume 3, Part A, Sec 8.6.2.1. We can receive as large of a PDU as the peer
134 // can encode and transmit. However, this value is for the information payload field of an I-Frame,
135 // which is bounded by the 16-bit length field together with frame header and footer overhead.
136 static constexpr uint16_t kMaxInboundPduPayloadSize = std::numeric_limits<uint16_t>::max() -
137 sizeof(internal::EnhancedControlField) -
138 sizeof(FrameCheckSequence);
139
140 // Channel configuration option type field (Core Spec v5.1, Vol 3, Part A, Section 5):
141 enum class OptionType : uint8_t {
142 kMTU = 0x01,
143 kFlushTimeout = 0x02,
144 kQoS = 0x03,
145 kRetransmissionAndFlowControl = 0x04,
146 kFCS = 0x05,
147 kExtendedFlowSpecification = 0x06,
148 kExtendedWindowSize = 0x07,
149 };
150
151 // Defines the state of A2DP offloading to the controller.
152 enum class A2dpOffloadStatus : uint8_t {
153 // The A2DP offload command was received and successfully started.
154 kStarted,
155 // The A2DP offload command was sent and the L2CAP channel is waiting for a
156 // response.
157 kStarting,
158 // The A2DP offload stop command was sent and the L2CAP channel is waiting
159 // for a response.
160 kStopping,
161 // Either an error or an A2DP offload command stopped offloading to the
162 // controller.
163 kStopped,
164 };
165
166 // Signaling packet formats (Core Spec v5.0, Vol 3, Part A, Section 4):
167
168 using CommandCode = uint8_t;
169
170 enum class RejectReason : uint16_t {
171 kNotUnderstood = 0x0000,
172 kSignalingMTUExceeded = 0x0001,
173 kInvalidCID = 0x0002,
174 };
175
176 // Results field in Connection Response and Create Channel Response
177 enum class ConnectionResult : uint16_t {
178 kSuccess = 0x0000,
179 kPending = 0x0001,
180 kPsmNotSupported = 0x0002,
181 kSecurityBlock = 0x0003,
182 kNoResources = 0x0004,
183 kControllerNotSupported = 0x0005, // for Create Channel only
184 kInvalidSourceCID = 0x0006,
185 kSourceCIDAlreadyAllocated = 0x0007,
186 };
187
188 enum class ConnectionStatus : uint16_t {
189 kNoInfoAvailable = 0x0000,
190 kAuthenticationPending = 0x0001,
191 kAuthorizationPending = 0x0002,
192 };
193
194 // Flags field in Configuration request and response, continuation bit mask
195 constexpr uint16_t kConfigurationContinuation = 0x0001;
196
197 enum class ConfigurationResult : uint16_t {
198 kSuccess = 0x0000,
199 kUnacceptableParameters = 0x0001,
200 kRejected = 0x0002,
201 kUnknownOptions = 0x0003,
202 kPending = 0x0004,
203 kFlowSpecRejected = 0x0005,
204 };
205
206 // Channel modes available in a L2CAP_CONFIGURATION_REQ packet. These are not
207 // the full set of possible channel modes, see CreditBasedFlowControlMode.
208 enum class RetransmissionAndFlowControlMode : uint8_t {
209 kBasic = 0x00,
210 kRetransmission = 0x01,
211 kFlowControl = 0x02,
212 kEnhancedRetransmission = 0x03,
213 kStreaming = 0x04,
214 };
215
216 // FCS Types defined by the specification
217 enum class FcsType : uint8_t {
218 kNoFcs = 0x00,
219 kSixteenBitFcs = 0x01,
220 };
221
222 // Channel modes defined by an associated channel establishment packet rather
223 // than an L2CAP_CONFIGURATION_REQ packet. The values here are the signaling
224 // packet code of the connection establishment request packet associated with
225 // the mode. These are not the full set of possible channel modes, see
226 // RetransmissionAndFlowControlMode.
227 enum class CreditBasedFlowControlMode : uint8_t {
228 kLeCreditBasedFlowControl = 0x14,
229 kEnhancedCreditBasedFlowControl = 0x17,
230 };
231
232 enum class InformationType : uint16_t {
233 kConnectionlessMTU = 0x0001,
234 kExtendedFeaturesSupported = 0x0002,
235 kFixedChannelsSupported = 0x0003,
236 };
237
238 enum class InformationResult : uint16_t {
239 kSuccess = 0x0000,
240 kNotSupported = 0x0001,
241 };
242
243 // Type and bit masks for Extended Features Supported in the Information
244 // Response data field (Vol 3, Part A, Section 4.12)
245 using ExtendedFeatures = uint32_t;
246 constexpr ExtendedFeatures kExtendedFeaturesBitFlowControl = 1 << 0;
247 constexpr ExtendedFeatures kExtendedFeaturesBitRetransmission = 1 << 1;
248 constexpr ExtendedFeatures kExtendedFeaturesBitBidirectionalQoS = 1 << 2;
249 constexpr ExtendedFeatures kExtendedFeaturesBitEnhancedRetransmission = 1 << 3;
250 constexpr ExtendedFeatures kExtendedFeaturesBitStreaming = 1 << 4;
251 constexpr ExtendedFeatures kExtendedFeaturesBitFCSOption = 1 << 5;
252 constexpr ExtendedFeatures kExtendedFeaturesBitExtendedFlowSpecification = 1 << 6;
253 constexpr ExtendedFeatures kExtendedFeaturesBitFixedChannels = 1 << 7;
254 constexpr ExtendedFeatures kExtendedFeaturesBitExtendedWindowSize = 1 << 8;
255 constexpr ExtendedFeatures kExtendedFeaturesBitUnicastConnectionlessDataRx = 1 << 9;
256
257 // Type and bit masks for Fixed Channels Supported in the Information Response
258 // data field (Vol 3, Part A, Section 4.12)
259 using FixedChannelsSupported = uint64_t;
260 constexpr FixedChannelsSupported kFixedChannelsSupportedBitNull = 1ULL << 0;
261 constexpr FixedChannelsSupported kFixedChannelsSupportedBitSignaling = 1ULL << 1;
262 constexpr FixedChannelsSupported kFixedChannelsSupportedBitConnectionless = 1ULL << 2;
263 constexpr FixedChannelsSupported kFixedChannelsSupportedBitAMPManager = 1ULL << 3;
264 constexpr FixedChannelsSupported kFixedChannelsSupportedBitATT = 1ULL << 4;
265 constexpr FixedChannelsSupported kFixedChannelsSupportedBitLESignaling = 1ULL << 5;
266 constexpr FixedChannelsSupported kFixedChannelsSupportedBitSMP = 1ULL << 6;
267 constexpr FixedChannelsSupported kFixedChannelsSupportedBitSM = 1ULL << 7;
268 constexpr FixedChannelsSupported kFixedChannelsSupportedBitAMPTestManager = 1ULL << 63;
269
270 enum class ConnectionParameterUpdateResult : uint16_t {
271 kAccepted = 0x0000,
272 kRejected = 0x0001,
273 };
274
275 enum class LECreditBasedConnectionResult : uint16_t {
276 kSuccess = 0x0000,
277 kPsmNotSupported = 0x0002,
278 kNoResources = 0x0004,
279 kInsufficientAuthentication = 0x0005,
280 kInsufficientAuthorization = 0x0006,
281 kInsufficientEncryptionKeySize = 0x0007,
282 kInsufficientEncryption = 0x0008,
283 kInvalidSourceCID = 0x0009,
284 kSourceCIDAlreadyAllocated = 0x000A,
285 kUnacceptableParameters = 0x000B,
286 };
287
288 // Type used for all Protocol and Service Multiplexer (PSM) identifiers,
289 // including those dynamically-assigned/-obtained
290 using Psm = uint16_t;
291 constexpr Psm kInvalidPsm = 0x0000;
292 // The minimum PSM value in the dynamic range of PSMs.
293 // Defined in 5.2, Vol 3, Part A, 4.2.
294 constexpr Psm kMinDynamicPsm = 0x1001;
295
296 // Well-known Protocol and Service Multiplexer values defined by the Bluetooth
297 // SIG in Logical Link Control Assigned Numbers
298 // https://www.bluetooth.com/specifications/assigned-numbers/logical-link-control
299 constexpr Psm kSDP = 0x0001;
300 constexpr Psm kRFCOMM = 0x0003;
301 constexpr Psm kTCSBIN = 0x0005; // Telephony Control Specification
302 constexpr Psm kTCSBINCordless = 0x0007;
303 constexpr Psm kBNEP = 0x0009; // Bluetooth Network Encapsulation Protocol
304 constexpr Psm kHIDControl = 0x0011; // Human Interface Device
305 constexpr Psm kHIDInteerup = 0x0013; // Human Interface Device
306 constexpr Psm kAVCTP = 0x0017; // Audio/Video Control Transport Protocol
307 constexpr Psm kAVDTP = 0x0019; // Audio/Video Distribution Transport Protocol
308 constexpr Psm kAVCTP_Browse = 0x001B; // Audio/Video Remote Control Profile (Browsing)
309 constexpr Psm kATT = 0x001F; // ATT
310 constexpr Psm k3DSP = 0x0021; // 3D Synchronization Profile
311 constexpr Psm kLE_IPSP = 0x0023; // Internet Protocol Support Profile
312 constexpr Psm kOTS = 0x0025; // Object Transfer Service
313
314 // Convenience function for visualizing a PSM. Used for Inspect and logging.
315 // Returns string formatted |psm| if not recognized.
PsmToString(l2cap::Psm psm)316 inline std::string PsmToString(l2cap::Psm psm) {
317 switch (psm) {
318 case kInvalidPsm:
319 return "InvalidPsm";
320 case kSDP:
321 return "SDP";
322 case kRFCOMM:
323 return "RFCOMM";
324 case kTCSBIN:
325 return "TCSBIN";
326 case kTCSBINCordless:
327 return "TCSBINCordless";
328 case kBNEP:
329 return "BNEP";
330 case kHIDControl:
331 return "HIDControl";
332 case kHIDInteerup:
333 return "HIDInteerup";
334 case kAVCTP:
335 return "AVCTP";
336 case kAVDTP:
337 return "AVDTP";
338 case kAVCTP_Browse:
339 return "AVCTP_Browse";
340 case kATT:
341 return "ATT";
342 case k3DSP:
343 return "3DSP";
344 case kLE_IPSP:
345 return "LE_IPSP";
346 case kOTS:
347 return "OTS";
348 }
349 return "PSM:" + std::to_string(psm);
350 }
351
352 // Identifier assigned to each signaling transaction. This is used to match each
353 // signaling channel request with a response.
354 using CommandId = uint8_t;
355
356 constexpr CommandId kInvalidCommandId = 0x00;
357
358 // Signaling command header.
359 struct CommandHeader {
360 CommandCode code;
361 CommandId id;
362 uint16_t length; // Length of the remaining payload
363 } __attribute__((packed));
364
365 // ACL-U & LE-U
366 constexpr CommandCode kCommandRejectCode = 0x01;
367 constexpr size_t kCommandRejectMaxDataLength = 4;
368 struct CommandRejectPayload {
369 // See RejectReason for possible values.
370 uint16_t reason;
371
372 // Followed by up to 4 octets of optional data (see Vol 3, Part A, Section 4.1)
373 } __attribute__((packed));
374
375 // Payload of Command Reject (see Vol 3, Part A, Section 4.1).
376 struct InvalidCIDPayload {
377 // Source CID (relative to rejecter)
378 ChannelId src_cid;
379
380 // Destination CID (relative to rejecter)
381 ChannelId dst_cid;
382 } __attribute__((packed));
383
384 // ACL-U
385 constexpr CommandCode kConnectionRequest = 0x02;
386 struct ConnectionRequestPayload {
387 uint16_t psm;
388 ChannelId src_cid;
389 } __attribute__((packed));
390
391 // ACL-U
392 constexpr CommandCode kConnectionResponse = 0x03;
393 struct ConnectionResponsePayload {
394 ChannelId dst_cid;
395 ChannelId src_cid;
396 ConnectionResult result;
397 ConnectionStatus status;
398 } __attribute__((packed));
399
400 // ACL-U
401 constexpr CommandCode kConfigurationRequest = 0x04;
402 constexpr size_t kConfigurationOptionMaxDataLength = 22;
403
404 // Element of configuration payload data (see Vol 3, Part A, Section 5)
405 struct ConfigurationOption {
406 OptionType type;
407 uint8_t length;
408
409 // Followed by configuration option-specific data
410 } __attribute__((packed));
411
412 // Payload of Configuration Option (see Vol 3, Part A, Section 5.1)
413 struct MtuOptionPayload {
414 uint16_t mtu;
415 } __attribute__((packed));
416
417
418 // Payload of Configuration Option (see Vol 3, Part A, Section 5.2)
419 struct FlushTimeoutOptionPayload {
420 uint16_t flush_timeout;
421 } __attribute__((packed));
422
423 // Payload of Configuration Option (see Vol 3, Part A, Section 5.4)
424 struct RetransmissionAndFlowControlOptionPayload {
425 RetransmissionAndFlowControlMode mode;
426 uint8_t tx_window_size;
427 uint8_t max_transmit;
428 uint16_t rtx_timeout;
429 uint16_t monitor_timeout;
430 uint16_t mps;
431 } __attribute__((packed));
432
433 // Payload of the FCS Option (see Vol 3, Part A, Section 5.5)
434 struct FrameCheckSequenceOptionPayload {
435 FcsType fcs_type;
436 } __attribute__((packed));
437
438 struct ConfigurationRequestPayload {
439 ChannelId dst_cid;
440 uint16_t flags;
441
442 // Followed by zero or more configuration options of varying length
443 } __attribute__((packed));
444
445 // ACL-U
446 constexpr CommandCode kConfigurationResponse = 0x05;
447 struct ConfigurationResponsePayload {
448 ChannelId src_cid;
449 uint16_t flags;
450 ConfigurationResult result;
451
452 // Followed by zero or more configuration options of varying length
453 } __attribute__((packed));
454
455 // ACL-U & LE-U
456 constexpr CommandCode kDisconnectionRequest = 0x06;
457 struct DisconnectionRequestPayload {
458 ChannelId dst_cid;
459 ChannelId src_cid;
460 } __attribute__((packed));
461
462 // ACL-U & LE-U
463 constexpr CommandCode kDisconnectionResponse = 0x07;
464 struct DisconnectionResponsePayload {
465 ChannelId dst_cid;
466 ChannelId src_cid;
467 } __attribute__((packed));
468
469 // ACL-U
470 constexpr CommandCode kEchoRequest = 0x08;
471
472 // ACL-U
473 constexpr CommandCode kEchoResponse = 0x09;
474
475 // ACL-U
476 constexpr CommandCode kInformationRequest = 0x0A;
477 struct InformationRequestPayload {
478 InformationType type;
479 } __attribute__((packed));
480
481 // ACL-U
482 constexpr CommandCode kInformationResponse = 0x0B;
483 constexpr size_t kInformationResponseMaxDataLength = 8;
484 struct InformationResponsePayload {
485 InformationType type;
486 InformationResult result;
487
488 // Up to 8 octets of optional data (see Vol 3, Part A, Section 4.11)
489 } __attribute__((packed));
490
491 // LE-U
492 constexpr CommandCode kConnectionParameterUpdateRequest = 0x12;
493 struct ConnectionParameterUpdateRequestPayload {
494 uint16_t interval_min;
495 uint16_t interval_max;
496 uint16_t peripheral_latency;
497 uint16_t timeout_multiplier;
498 } __attribute__((packed));
499
500 // LE-U
501 constexpr CommandCode kConnectionParameterUpdateResponse = 0x13;
502 struct ConnectionParameterUpdateResponsePayload {
503 ConnectionParameterUpdateResult result;
504 } __attribute__((packed));
505
506 // LE-U
507 constexpr CommandCode kLECreditBasedConnectionRequest = 0x14;
508 struct LECreditBasedConnectionRequestPayload {
509 uint16_t le_psm;
510 ChannelId src_cid;
511 uint16_t mtu; // Max. SDU size
512 uint16_t mps; // Max. PDU size
513 uint16_t initial_credits;
514 } __attribute__((packed));
515
516 // LE-U
517 constexpr CommandCode kLECreditBasedConnectionResponse = 0x15;
518 struct LECreditBasedConnectionResponsePayload {
519 ChannelId dst_cid;
520 uint16_t mtu; // Max. SDU size
521 uint16_t mps; // Max. PDU size
522 uint16_t initial_credits;
523 LECreditBasedConnectionResult result;
524 } __attribute__((packed));
525
526 // LE-U
527 constexpr CommandCode kLEFlowControlCredit = 0x16;
528 struct LEFlowControlCreditParams {
529 ChannelId cid;
530 uint16_t credits;
531 } __attribute__((packed));
532
533 } // namespace bt::l2cap
534
535