dvb_t2mi/payload/
fef_subpart.rs

1//! T2-MI payload type 0x33: FEF sub-part — §5.2.12.
2//!
3//! Carries individual sub-parts of a composite FEF part.
4//! Sub-part variety determines the body format:
5//! - 0x0000: Null (reserved_for_future_use 32 bits)
6//! - 0x0001: IQ (reserved 32 bits + iq_data variable)
7//! - 0x0002: PRBS (prbs_type 8 bits + reserved 96 bits)
8//! - 0x0003: TX-SIG FEF (reserved 32 bits)
9//! - 0x0004..0xFFFF: Reserved for future use
10
11use core::fmt;
12
13use num_enum::TryFromPrimitive;
14
15use dvb_common::{Parse, Serialize};
16
17/// Sub-part variety per §5.2.12 Table 13.
18#[derive(Debug, Clone, Copy, PartialEq, Eq, TryFromPrimitive)]
19#[cfg_attr(feature = "serde", derive(serde::Serialize))]
20#[repr(u16)]
21#[non_exhaustive]
22pub enum SubpartVariety {
23    /// Null — `reserved_for_future_use(32)` = 0.
24    Null = 0x0000,
25    /// IQ — `reserved_for_future_use(32)` + `iq_data`.
26    Iq = 0x0001,
27    /// PRBS — `prbs_type(8)` + `reserved_for_future_use(96)`.
28    Prbs = 0x0002,
29    /// TX-SIG FEF — `reserved_for_future_use(32)`.
30    TxSigFef = 0x0003,
31}
32
33impl From<SubpartVariety> for u16 {
34    fn from(sv: SubpartVariety) -> Self {
35        sv as u16
36    }
37}
38
39impl From<num_enum::TryFromPrimitiveError<SubpartVariety>> for crate::error::Error {
40    fn from(_: num_enum::TryFromPrimitiveError<SubpartVariety>) -> Self {
41        // subpart_variety is a 16-bit field — casting the offending value to u8
42        // would truncate it, and InvalidPacketType is the wrong category anyway.
43        crate::error::Error::ReservedBitsViolation {
44            field: "subpart_variety",
45            reason: "Must be 0x0000..=0x0003 per ETSI TS 102 773 §5.2.12 Table 13",
46        }
47    }
48}
49
50impl SubpartVariety {
51    /// Human-readable spec label (ETSI TS 102 773 §5.2.12 Table 13).
52    #[must_use]
53    pub fn name(&self) -> &'static str {
54        match self {
55            Self::Null => "Null",
56            Self::Iq => "IQ",
57            Self::Prbs => "PRBS",
58            Self::TxSigFef => "TX-SIG FEF",
59        }
60    }
61}
62dvb_common::impl_spec_display!(SubpartVariety);
63
64/// PRBS type for SubpartVariety::Prbs.
65#[derive(Debug, Clone, Copy, PartialEq, Eq, TryFromPrimitive)]
66#[cfg_attr(feature = "serde", derive(serde::Serialize))]
67#[repr(u8)]
68#[non_exhaustive]
69pub enum PrbsType {
70    /// User-defined test/measurement.
71    UserDefined = 0x00,
72}
73
74impl From<PrbsType> for u8 {
75    fn from(pt: PrbsType) -> Self {
76        pt as u8
77    }
78}
79
80impl PrbsType {
81    /// Human-readable spec label (ETSI TS 102 773 §5.2.12).
82    #[must_use]
83    pub fn name(&self) -> &'static str {
84        match self {
85            Self::UserDefined => "user-defined",
86        }
87    }
88}
89dvb_common::impl_spec_display!(PrbsType);
90
91/// FEF sub-part payload (type 0x33) per ETSI TS 102 773 §5.2.12.
92///
93/// Layout (Figure 16):
94/// - byte 0: fef_idx (8 bits)
95/// - bytes 1-2: tx_identifier (16 bits)
96/// - bytes 3-6: rfu1 (32 bits) — must be 0
97/// - bytes 7-8: subpart_idx (16 bits)
98/// - bytes 9-10: subpart_variety (16 bits)
99/// - bytes 11-14: rfu2 (10 bits) + subpart_length (22 bits)
100/// - bytes 15..: subpart data (variable, format per variety)
101#[derive(Debug, Clone, PartialEq, Eq)]
102#[cfg_attr(feature = "serde", derive(serde::Serialize))]
103#[cfg_attr(feature = "yoke", derive(yoke::Yokeable))]
104pub struct FefSubPartPayload<'a> {
105    /// FEF index within super-frame.
106    pub fef_idx: u8,
107    /// Transmitter identifier (0x0000 = broadcast).
108    pub tx_identifier: u16,
109    /// Sub-part index p.
110    pub subpart_idx: u16,
111    /// Sub-part variety (Null/IQ/PRBS/TX-SIG).
112    pub subpart_variety: SubpartVariety,
113    /// Length in elementary time periods.
114    pub subpart_length: u32,
115    /// Raw sub-part data (format depends on variety).
116    pub subpart_data: &'a [u8],
117}
118
119/// Total header bytes before subpart_data: fef_idx(1) + tx_id(2) + rfu1(4) +
120/// subpart_idx(2) + variety(2) + rfu2+subpart_len(4) = 15.
121const FEF_SUBPART_HEADER_LEN: usize = 15;
122
123/// Mask for 22-bit subpart_length field.
124const SUBPART_LENGTH_MASK: u32 = 0x003F_FFFF;
125
126impl<'a> Parse<'a> for FefSubPartPayload<'a> {
127    type Error = crate::error::Error;
128
129    fn parse(bytes: &'a [u8]) -> Result<Self, crate::error::Error> {
130        let (hdr, rest) = bytes.split_first_chunk::<FEF_SUBPART_HEADER_LEN>().ok_or(
131            crate::Error::BufferTooShort {
132                need: FEF_SUBPART_HEADER_LEN,
133                have: bytes.len(),
134                what: "FefSubPartPayload header",
135            },
136        )?;
137
138        // rfu1: bytes 3-6 (32 bits) — must be 0
139        if hdr[3] != 0 || hdr[4] != 0 || hdr[5] != 0 || hdr[6] != 0 {
140            return Err(crate::Error::ReservedBitsViolation {
141                field: "32-bit RFU (rfu1)",
142                reason: "Must be zero (ETSI TS 102 773 §5.2.12)",
143            });
144        }
145
146        let variety = SubpartVariety::try_from(u16::from_be_bytes([hdr[9], hdr[10]]))?;
147
148        // rfu2: byte 11 (8 bits) + byte 12 [7:6] (2 bits) = 10 bits — must be 0
149        if hdr[11] != 0 || (hdr[12] & 0xC0 != 0) {
150            return Err(crate::Error::ReservedBitsViolation {
151                field: "10-bit RFU (rfu2)",
152                reason: "Must be zero (ETSI TS 102 773 §5.2.12)",
153            });
154        }
155
156        // subpart_length: byte 12 [5:0] (6 bits) + byte 13 (8 bits) + byte 14 (8 bits) = 22 bits
157        let subpart_length =
158            ((hdr[12] & 0x3F) as u32) << 16 | (hdr[13] as u32) << 8 | (hdr[14] as u32);
159
160        Ok(FefSubPartPayload {
161            fef_idx: hdr[0],
162            tx_identifier: u16::from_be_bytes([hdr[1], hdr[2]]),
163            subpart_idx: u16::from_be_bytes([hdr[7], hdr[8]]),
164            subpart_variety: variety,
165            subpart_length,
166            subpart_data: rest,
167        })
168    }
169}
170
171impl<'a> crate::traits::PayloadDef<'a> for FefSubPartPayload<'a> {
172    const PACKET_TYPE: u8 = 0x33;
173    const NAME: &'static str = "FEF_SUBPART";
174}
175
176impl Serialize for FefSubPartPayload<'_> {
177    type Error = crate::error::Error;
178
179    fn serialized_len(&self) -> usize {
180        FEF_SUBPART_HEADER_LEN + self.subpart_data.len()
181    }
182
183    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize, crate::error::Error> {
184        if buf.len() < self.serialized_len() {
185            return Err(crate::Error::OutputBufferTooSmall {
186                need: self.serialized_len(),
187                have: buf.len(),
188            });
189        }
190
191        if self.subpart_length > SUBPART_LENGTH_MASK {
192            return Err(crate::Error::ReservedBitsViolation {
193                field: "subpart_length",
194                reason: "Must fit in 22 bits",
195            });
196        }
197
198        buf[0] = self.fef_idx;
199        let tx_id = self.tx_identifier.to_be_bytes();
200        buf[1] = tx_id[0];
201        buf[2] = tx_id[1];
202        // rfu1 = 0
203        buf[3] = 0;
204        buf[4] = 0;
205        buf[5] = 0;
206        buf[6] = 0;
207        let sub_idx = self.subpart_idx.to_be_bytes();
208        buf[7] = sub_idx[0];
209        buf[8] = sub_idx[1];
210        let variety = u16::from(self.subpart_variety);
211        buf[9] = (variety >> 8) as u8;
212        buf[10] = (variety & 0xFF) as u8;
213        // rfu2 = 0 (top 2 bits byte 12) + rfu2 = 0 (byte 11)
214        buf[11] = 0;
215        // subpart_length: 22 bits → byte 12 [5:0] = top 6, byte 13 = mid 8, byte 14 = bot 8
216        buf[12] = ((self.subpart_length >> 16) & 0x3F) as u8;
217        buf[13] = (self.subpart_length >> 8) as u8;
218        buf[14] = (self.subpart_length & 0xFF) as u8;
219
220        if !self.subpart_data.is_empty() {
221            buf[FEF_SUBPART_HEADER_LEN..FEF_SUBPART_HEADER_LEN + self.subpart_data.len()]
222                .copy_from_slice(self.subpart_data);
223        }
224
225        Ok(self.serialized_len())
226    }
227}
228
229impl fmt::Display for FefSubPartPayload<'_> {
230    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
231        write!(
232            f,
233            "FEF SubPart {{ fef_idx: {}, tx_id: 0x{:04X}, subpart_idx: {}, variety: {:?}, length: {} }}",
234            self.fef_idx, self.tx_identifier, self.subpart_idx, self.subpart_variety, self.subpart_length
235        )
236    }
237}
238
239#[cfg(test)]
240mod tests {
241    use super::*;
242
243    #[test]
244    fn parse_extracts_fields() {
245        // subpart_length = 4096 = 0x1000.
246        // 22-bit: byte 12 [5:0] = (0x1000 >> 16) & 0x3F = 0,
247        //         byte 13 = (0x1000 >> 8) & 0xFF = 0x10,
248        //         byte 14 = 0x1000 & 0xFF = 0x00.
249        let mut buf = [0u8; 15];
250        buf[0] = 0x02; // fef_idx
251        buf[1] = 0x00;
252        buf[2] = 0x01; // tx_id = 1
253                       // bytes 3-6 = rfu1 = 0
254        buf[7] = 0x00;
255        buf[8] = 0x05; // subpart_idx = 5
256        buf[9] = 0x00;
257        buf[10] = 0x01; // variety = IQ
258                        // byte 11 = rfu2 = 0
259                        // byte 12 top 2 = rfu2 = 0, bottom 6 = subpart top = 0
260                        // byte 13 = subpart mid = 0x10
261        buf[13] = 0x10;
262        // byte 14 = subpart bot = 0
263        // subpart_data starts at offset 15
264
265        let result = FefSubPartPayload::parse(&buf).unwrap();
266        assert_eq!(result.fef_idx, 2);
267        assert_eq!(result.tx_identifier, 0x0001);
268        assert_eq!(result.subpart_idx, 5);
269        assert_eq!(result.subpart_variety, SubpartVariety::Iq);
270        assert_eq!(result.subpart_length, 0x1000);
271    }
272
273    #[test]
274    fn parse_rejects_invalid_variety() {
275        let mut buf = [0u8; 15];
276        buf[9] = 0x00;
277        buf[10] = 0x04; // variety = 0x0004 (reserved)
278        assert!(FefSubPartPayload::parse(&buf).is_err());
279    }
280
281    #[test]
282    fn parse_rejects_nonzero_rfu1() {
283        let mut buf = [0u8; 15];
284        buf[3] = 0x01;
285        assert!(FefSubPartPayload::parse(&buf).is_err());
286    }
287
288    #[test]
289    fn parse_rejects_nonzero_rfu2_byte11() {
290        let mut buf = [0u8; 15];
291        buf[11] = 0x01;
292        assert!(FefSubPartPayload::parse(&buf).is_err());
293    }
294
295    #[test]
296    fn parse_rejects_nonzero_rfu2_byte12_top() {
297        let mut buf = [0u8; 15];
298        buf[12] = 0xC0;
299        assert!(FefSubPartPayload::parse(&buf).is_err());
300    }
301
302    #[test]
303    fn parse_rejects_short_buffer() {
304        let buf = [0u8; 14];
305        assert!(FefSubPartPayload::parse(&buf).is_err());
306    }
307
308    #[test]
309    fn serialize_round_trip() {
310        let orig = FefSubPartPayload {
311            fef_idx: 1,
312            tx_identifier: 0x0000,
313            subpart_idx: 3,
314            subpart_variety: SubpartVariety::Null,
315            subpart_length: 2048,
316            subpart_data: &[],
317        };
318        let mut buf = vec![0u8; orig.serialized_len()];
319        orig.serialize_into(&mut buf).unwrap();
320        let parsed = FefSubPartPayload::parse(&buf).unwrap();
321        assert_eq!(orig, parsed);
322    }
323
324    #[test]
325    fn broadcast_tx_identifier() {
326        let buf = [0u8; 15];
327        let result = FefSubPartPayload::parse(&buf).unwrap();
328        assert_eq!(result.tx_identifier, 0x0000);
329    }
330
331    #[test]
332    fn subpart_variety_try_from_all() {
333        assert_eq!(SubpartVariety::try_from(0x0000), Ok(SubpartVariety::Null));
334        assert_eq!(SubpartVariety::try_from(0x0001), Ok(SubpartVariety::Iq));
335        assert_eq!(SubpartVariety::try_from(0x0002), Ok(SubpartVariety::Prbs));
336        assert_eq!(
337            SubpartVariety::try_from(0x0003),
338            Ok(SubpartVariety::TxSigFef)
339        );
340    }
341
342    #[test]
343    fn subpart_variety_try_from_reserved() {
344        assert!(SubpartVariety::try_from(0x0004).is_err());
345        assert!(SubpartVariety::try_from(0xFFFF).is_err());
346    }
347
348    #[test]
349    fn exhaustive_subpart_variety_sweep() {
350        let mut matched = 0u32;
351        for value in 0u16..=0xFFFF {
352            if let Ok(v) = SubpartVariety::try_from(value) {
353                assert_eq!(v as u16, value, "round-trip failed for {value:#06x}");
354                matched += 1;
355            }
356        }
357        assert_eq!(matched, 4, "expected 4 matched variants");
358    }
359
360    #[test]
361    fn exhaustive_prbs_type_sweep() {
362        let mut matched = 0u16;
363        for byte in 0u8..=0xFF {
364            if let Ok(v) = PrbsType::try_from(byte) {
365                assert_eq!(v as u8, byte, "round-trip failed for {byte:#04x}");
366                matched += 1;
367            }
368        }
369        assert_eq!(matched, 1, "expected 1 matched variant");
370    }
371}
dvb_t2mi/payload/fef_subpart.rs

dvb_t2mi/payload/
fef_subpart.rs
