rust/bt-ascs: Add presentation delay range helpers A client has to request one Presentation_Delay per direction for all the ASEs in a CIG (BAP v1.0.2 Section 7.1.3), but each ASE publishes its own range. Add helpers on PresentationDelayRange that combine those ranges and pick a delay from the result. BAP v1.0.2 Section 5.6.2 makes the supported range a shall and the preferred range only a should, so the helpers treat them differently. If the supported ranges have no value in common, combining fails. Preferred bounds never cause a failure. A bound outside the supported range moves to the nearest supported bound, preferred bounds that cross are dropped, and a zero bound (ASCS v1.0.1 Table 4.3) means no preference. Combining normalizes the preferred bounds once, after merging every range, because normalizing pair by pair gives an answer that depends on the order of the ASEs. Decoding now rejects a range whose min is above its max, since no value in it can satisfy the shall. Test: cargo test -p bt-ascs Change-Id: I01e07e74ecac123bf3f4aa25d455f8136a6a6964 Reviewed-on: https://bluetooth-review.googlesource.com/c/bluetooth/+/4123
diff --git a/rust/bt-ascs/src/types.rs b/rust/bt-ascs/src/types.rs index 8107a5e..e39d943 100644 --- a/rust/bt-ascs/src/types.rs +++ b/rust/bt-ascs/src/types.rs
@@ -1428,6 +1428,100 @@ }; Ok(self) } + + /// Combines a set of ranges into a single range that satisfies all of them. + /// + /// BAP v1.0.2 Section 7.1.3 requires one Presentation_Delay for all the + /// ASEs of a direction, and Section 5.6.2 says that value shall be inside + /// the supported range of each ASE. So the result's supported range is the + /// intersection of the inputs. Returns None if `ranges` is empty or if the + /// supported ranges have no value in common. + /// + /// The preferred bounds combine the same way, except that an absent bound + /// means no preference and doesn't constrain the result. A + /// Preferred_Presentation_Delay of 0x000000 decodes as absent (ASCS v1.0.1 + /// Table 4.3). The preferred range is only a "should" in BAP v1.0.2 Section + /// 5.6.2, so it never causes an error. A combined preferred bound outside + /// the supported range moves to the nearest supported bound, and preferred + /// bounds that cross are dropped. This happens once, after combining every + /// range, so the result doesn't depend on the order of `ranges`. + pub fn intersect_all<'a>(ranges: impl IntoIterator<Item = &'a Self>) -> Option<Self> { + let mut ranges = ranges.into_iter(); + let first = ranges.next()?; + let mut min = first.min.clone(); + let mut max = first.max.clone(); + let mut preferred_min = first.preferred_min.clone(); + let mut preferred_max = first.preferred_max.clone(); + + for range in ranges { + min = core::cmp::max(min, range.min.clone()); + max = core::cmp::min(max, range.max.clone()); + preferred_min = match (preferred_min, range.preferred_min.clone()) { + (Some(a), Some(b)) => Some(core::cmp::max(a, b)), + (Some(only), None) | (None, Some(only)) => Some(only), + (None, None) => None, + }; + preferred_max = match (preferred_max, range.preferred_max.clone()) { + (Some(a), Some(b)) => Some(core::cmp::min(a, b)), + (Some(only), None) | (None, Some(only)) => Some(only), + (None, None) => None, + }; + } + + if min > max { + return None; + } + + // Move the preferred bounds inside the supported range and drop them if + // they cross, the same way `preferred_range` does when selecting a + // value. + let clamp_into_supported = |bound: PresentationDelay| bound.clamp(min.clone(), max.clone()); + let mut preferred_min = preferred_min.map(clamp_into_supported); + let mut preferred_max = preferred_max.map(clamp_into_supported); + let crossed = matches!( + (&preferred_min, &preferred_max), + (Some(pref_min), Some(pref_max)) if pref_min > pref_max + ); + if crossed { + preferred_min = None; + preferred_max = None; + } + Some(Self { min, max, preferred_min, preferred_max }) + } + + /// The window of Presentation_Delay values that the peer prefers, as + /// inclusive bounds. + /// + /// An absent preferred bound means no preference (ASCS v1.0.1 Table 4.3) + /// and becomes the matching supported bound. A preferred bound outside the + /// supported range moves to the nearest supported bound, so a peer that + /// prefers more delay than it supports gets the closest value it can + /// accept. The window can shrink to a single point this way. If the + /// preferred bounds cross, no value is preferred and this returns the whole + /// supported range. That is still compliant, because BAP v1.0.2 Section + /// 5.6.2 makes the preferred range a "should" and the supported range a + /// "shall". + pub fn preferred_range(&self) -> (PresentationDelay, PresentationDelay) { + let lo = self.preferred_min.clone().unwrap_or_else(|| self.min.clone()); + let hi = self.preferred_max.clone().unwrap_or_else(|| self.max.clone()); + let lo = lo.clamp(self.min.clone(), self.max.clone()); + let hi = hi.clamp(self.min.clone(), self.max.clone()); + if lo > hi { + return (self.min.clone(), self.max.clone()); + } + (lo, hi) + } + + /// Picks the Presentation_Delay to request, given the `desired` value. + /// + /// Returns `desired` if it is inside [`Self::preferred_range`], otherwise + /// the nearer edge of that window. The result is always inside the + /// supported range, as BAP v1.0.2 Section 5.6.2 requires, and inside the + /// peer's preferred window when it has one, as the same section recommends. + pub fn clamp_to_preferred(&self, desired: PresentationDelay) -> PresentationDelay { + let (lo, hi) = self.preferred_range(); + desired.clamp(lo, hi) + } } impl Encodable for PresentationDelayRange { @@ -1555,6 +1649,14 @@ Ok(max) => max, Err(e) => return (Err(e), buf.len()), }; + // If Presentation_Delay_Min is above Presentation_Delay_Max, the + // supported range is empty and every value would break the "shall" in + // BAP v1.0.2 Section 5.6.2. Reject it here so no caller selects a delay + // from it. Preferred bounds outside the supported range are fine, since + // selecting a delay clamps them. + if min > max { + return (Err(ResponseCode::invalid_length()), buf.len()); + } let pref_min_val = u32::from_le_bytes([buf[6], buf[7], buf[8], 0]); let preferred_min = if pref_min_val == 0 { None @@ -2048,6 +2150,247 @@ assert_eq!(&encoded, expected); } + fn pd(microseconds: u32) -> PresentationDelay { + PresentationDelay { microseconds } + } + + fn pd_range( + min_us: u32, + max_us: u32, + pref_min_us: Option<u32>, + pref_max_us: Option<u32>, + ) -> PresentationDelayRange { + let mut range = PresentationDelayRange::build(min_us, max_us).unwrap(); + range.with_preferred(pref_min_us, pref_max_us).expect("preferred range should be valid"); + range + } + + #[test] + fn presentation_delay_range_intersect_all() { + // A single range is returned as-is. + let only = pd_range(1000, 3000, Some(1500), None); + assert_eq!(PresentationDelayRange::intersect_all([&only]), Some(only)); + + // Nothing to intersect at all. + assert_eq!(PresentationDelayRange::intersect_all([]), None); + + // Overlapping supported ranges narrow to the overlap. + let first = pd_range(1000, 3000, None, None); + let second = pd_range(2000, 4000, None, None); + let both = PresentationDelayRange::intersect_all([&first, &second]).expect("overlapping"); + assert_eq!(both.min, pd(2000)); + assert_eq!(both.max, pd(3000)); + assert_eq!(both.preferred_min, None); + assert_eq!(both.preferred_max, None); + assert_eq!(PresentationDelayRange::intersect_all([&second, &first]), Some(both)); + + // Ranges that touch at a single point still have that point in common. + let first = pd_range(1000, 2000, None, None); + let second = pd_range(2000, 3000, None, None); + let both = + PresentationDelayRange::intersect_all([&first, &second]).expect("touching at 2000"); + assert_eq!(both.min, pd(2000)); + assert_eq!(both.max, pd(2000)); + + // Disjoint ranges have no common value at all. + let first = pd_range(1000, 1999, None, None); + let second = pd_range(2000, 3000, None, None); + assert_eq!(PresentationDelayRange::intersect_all([&first, &second]), None); + assert_eq!(PresentationDelayRange::intersect_all([&second, &first]), None); + + // A preferred bound set on only one range is kept, because the others + // have no preference. + let first = pd_range(1000, 3000, Some(1500), None); + let second = pd_range(1000, 3000, None, Some(2500)); + let both = PresentationDelayRange::intersect_all([&first, &second]).expect("overlapping"); + assert_eq!(both.preferred_min, Some(pd(1500))); + assert_eq!(both.preferred_max, Some(pd(2500))); + let flipped = + PresentationDelayRange::intersect_all([&second, &first]).expect("overlapping"); + assert_eq!(flipped.preferred_min, Some(pd(1500))); + assert_eq!(flipped.preferred_max, Some(pd(2500))); + + // Preferred bounds set on several ranges take the more restrictive + // value. + let first = pd_range(1000, 3000, Some(1500), Some(2800)); + let second = pd_range(1000, 3000, Some(1700), Some(2500)); + let both = PresentationDelayRange::intersect_all([&first, &second]).expect("overlapping"); + assert_eq!(both.preferred_min, Some(pd(1700))); + assert_eq!(both.preferred_max, Some(pd(2500))); + + // A preferred bound outside the narrowed supported range moves to the + // nearest supported bound rather than making the intersection fail. + let first = pd_range(1000, 3000, Some(2800), None); + let second = pd_range(1000, 2000, None, None); + let both = PresentationDelayRange::intersect_all([&first, &second]).expect("overlapping"); + assert_eq!(both.min, pd(1000)); + assert_eq!(both.max, pd(2000)); + assert_eq!(both.preferred_min, Some(pd(2000))); + + let first = pd_range(1000, 3000, None, Some(1200)); + let second = pd_range(2000, 3000, None, None); + let both = PresentationDelayRange::intersect_all([&first, &second]).expect("overlapping"); + assert_eq!(both.min, pd(2000)); + assert_eq!(both.max, pd(3000)); + assert_eq!(both.preferred_max, Some(pd(2000))); + + // Preferred bounds that cross each other leave no preference at all. + let first = pd_range(1000, 3000, Some(2500), None); + let second = pd_range(1000, 3000, None, Some(1500)); + let both = PresentationDelayRange::intersect_all([&first, &second]).expect("overlapping"); + assert_eq!(both.preferred_min, None); + assert_eq!(both.preferred_max, None); + } + + #[test] + fn presentation_delay_range_intersect_all_ignores_order() { + // Normalizing after each pair would give an answer that depends on the + // order of the ASEs. The bounds have to be combined first and + // normalized once. + let ranges = [ + pd_range(1000, 5000, Some(4000), None), + pd_range(1000, 5000, None, Some(2000)), + pd_range(1000, 3000, Some(3000), None), + ]; + + let permutations = [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]]; + let expected = PresentationDelayRange::intersect_all(&ranges).expect("overlapping"); + // The preferred bounds cross (4000 > 2000), so no preference remains. + assert_eq!(expected.preferred_min, None); + assert_eq!(expected.preferred_max, None); + assert_eq!(expected.clamp_to_preferred(pd(2500)), pd(2500)); + + for permutation in permutations { + let ordered = permutation.map(|index| &ranges[index]); + assert_eq!( + PresentationDelayRange::intersect_all(ordered), + Some(expected.clone()), + "order {permutation:?} changed the result" + ); + } + } + + #[test] + fn presentation_delay_preferred_range() { + // With no preference, the whole supported range is preferred. + let range = pd_range(1000, 2000, None, None); + assert_eq!(range.preferred_range(), (pd(1000), pd(2000))); + + // A missing bound collapses to the supported bound. + let range = pd_range(1000, 2000, Some(1500), None); + assert_eq!(range.preferred_range(), (pd(1500), pd(2000))); + let range = pd_range(1000, 2000, None, Some(1800)); + assert_eq!(range.preferred_range(), (pd(1000), pd(1800))); + + let range = pd_range(1000, 2000, Some(1200), Some(1800)); + assert_eq!(range.preferred_range(), (pd(1200), pd(1800))); + + // A preferred bound below min or above max moves to the supported edge. + let range = PresentationDelayRange { + min: pd(1000), + max: pd(2000), + preferred_min: Some(pd(500)), + preferred_max: Some(pd(2500)), + }; + assert_eq!(range.preferred_range(), (pd(1000), pd(2000))); + + // A preferred bound outside the supported range is moved to the nearest + // supported bound, which can leave a single-point window. + let range = PresentationDelayRange { + min: pd(1000), + max: pd(2000), + preferred_min: Some(pd(2800)), + preferred_max: None, + }; + assert_eq!(range.preferred_range(), (pd(2000), pd(2000))); + + let range = PresentationDelayRange { + min: pd(1000), + max: pd(2000), + preferred_min: None, + preferred_max: Some(pd(500)), + }; + assert_eq!(range.preferred_range(), (pd(1000), pd(1000))); + + // Crossed preferred bounds leave no preferred value, so the whole + // supported range is used. + let range = PresentationDelayRange { + min: pd(1000), + max: pd(2000), + preferred_min: Some(pd(1800)), + preferred_max: Some(pd(1200)), + }; + assert_eq!(range.preferred_range(), (pd(1000), pd(2000))); + } + + #[test] + fn presentation_delay_range_clamp_to_preferred() { + let range = pd_range(1000, 5000, Some(2000), Some(3000)); + // Below, inside, and above the preferred window. + assert_eq!(range.clamp_to_preferred(pd(1500)), pd(2000)); + assert_eq!(range.clamp_to_preferred(pd(2500)), pd(2500)); + assert_eq!(range.clamp_to_preferred(pd(4000)), pd(3000)); + // The window bounds themselves are preferred values. + assert_eq!(range.clamp_to_preferred(pd(2000)), pd(2000)); + assert_eq!(range.clamp_to_preferred(pd(3000)), pd(3000)); + + // With no preference expressed, only the supported range constrains, + // and its edges are selectable. + let range = pd_range(1000, 5000, None, None); + assert_eq!(range.clamp_to_preferred(pd(500)), pd(1000)); + assert_eq!(range.clamp_to_preferred(pd(1000)), pd(1000)); + assert_eq!(range.clamp_to_preferred(pd(4000)), pd(4000)); + assert_eq!(range.clamp_to_preferred(pd(5000)), pd(5000)); + assert_eq!(range.clamp_to_preferred(pd(40000)), pd(5000)); + + // A single-point preferred window leaves exactly one value. + let range = pd_range(1000, 5000, Some(2000), Some(2000)); + assert_eq!(range.clamp_to_preferred(pd(1500)), pd(2000)); + assert_eq!(range.clamp_to_preferred(pd(2000)), pd(2000)); + assert_eq!(range.clamp_to_preferred(pd(4000)), pd(2000)); + + // Crossed preferred bounds fall back to the supported range. + let range = PresentationDelayRange { + min: pd(1000), + max: pd(2000), + preferred_min: Some(pd(1800)), + preferred_max: Some(pd(1200)), + }; + assert_eq!(range.clamp_to_preferred(pd(40000)), pd(2000)); + assert_eq!(range.clamp_to_preferred(pd(1500)), pd(1500)); + } + + #[test] + fn presentation_delay_range_decoded_from_a_peer() { + // A peer may publish a preferred bound outside its own supported range. + // Decoding accepts it, and the selected delay stays inside the + // supported range as BAP v1.0.2 Section 5.6.2 requires. + #[rustfmt::skip] + let out_of_range_preferred: &[u8; 12] = &[ + 0xE8, 0x03, 0x00, // min 1000 + 0xD0, 0x07, 0x00, // max 2000 + 0x00, 0x00, 0x00, // preferred min: no preference + 0x88, 0x13, 0x00, // preferred max 5000, above the supported max + ]; + let (decoded, consumed) = PresentationDelayRange::decode(out_of_range_preferred); + let range = decoded.expect("preferred bounds are not validated"); + assert_eq!(consumed, PresentationDelayRange::BYTE_SIZE); + assert_eq!(range.preferred_range(), (pd(1000), pd(2000))); + assert_eq!(range.clamp_to_preferred(pd(40000)), pd(2000)); + assert!(range.clamp_to_preferred(pd(40000)) <= *range.max()); + + // A supported range with min above max has no compliant value at all. + #[rustfmt::skip] + let inverted: &[u8; 12] = &[ + 0xD0, 0x07, 0x00, // min 2000 + 0xE8, 0x03, 0x00, // max 1000 + 0x00, 0x00, 0x00, + 0x00, 0x00, 0x00, + ]; + let (decoded, _) = PresentationDelayRange::decode(inverted); + assert!(decoded.is_err(), "an inverted supported range should not decode"); + } + #[test] fn test_ase_endpoint_roundtrip() { use bt_gatt::types::Handle;