dvb_si/tables/
mpe_fec.rs

1//! MPE-FEC section — ETSI EN 301 192 v1.7.1 §9.9 (table_id 0x78).
2//!
3//! Carries Reed-Solomon FEC data for a MPE-FEC frame in a DVB-H/IP datacast
4//! time-slice burst. Syntax per "Table 45 — MPE-FEC section"
5//! (`dvb-si/docs/en_301_192.md`, §9.9, PDF p. 57):
6//!
7//! ```text
8//! MPE-FEC_section() {
9//!   table_id                  8   (0x78)
10//!   section_syntax_indicator  1
11//!   private_indicator         1
12//!   reserved                  2
13//!   section_length           12
14//!   padding_columns           8
15//!   reserved_for_future_use   8
16//!   reserved                  2
17//!   reserved_for_future_use   5
18//!   current_next_indicator    1
19//!   section_number            8
20//!   last_section_number       8
21//!   real_time_parameters()   32
22//!   for (i=0; i<N; i++) { rs_data_byte 8 }
23//!   CRC_32                   32
24//! }
25//! ```
26//!
27//! Note the byte-3/4 "table_id_extension" slot is NOT a 16-bit identifier here:
28//! it is `padding_columns(8)` followed by an 8-bit `reserved_for_future_use`.
29//! There is no `version_number` field — byte 5 is reserved bits plus the
30//! `current_next_indicator`. `real_time_parameters` is the shared time-slice /
31//! MPE-FEC structure of "Table 46 — real time parameters" (§9.10): a 12-bit
32//! `delta_t`, two boundary flags, and an 18-bit `address`, packed into 4 bytes.
33//!
34//! MPE-FEC is a private section (byte-1 bit 6 = `private_indicator`), handled
35//! with the [`crate::tables::cit`] idiom. `rs_data` is a borrowed raw slice.
36//! No well-known PID — carriage is descriptor-signalled, so `PID = 0x0000`
37//! follows the [`crate::tables::dsmcc`] precedent.
38
39use crate::error::{Error, Result};
40use crate::traits::Table;
41use dvb_common::{Parse, Serialize};
42
43/// table_id for the MPE-FEC section.
44pub const TABLE_ID: u8 = 0x78;
45
46/// MPE-FEC has no well-known PID — its carriage is signalled via the
47/// time_slice_fec_identifier_descriptor. `0x0000` follows the DSM-CC precedent.
48pub const PID: u16 = 0x0000;
49
50/// Bytes 0-2: table_id (1) + flags + section_length (2).
51const HEADER_LEN: usize = 3;
52
53/// Bytes 3-7: padding_columns(1) + reserved_for_future_use(1)
54/// + reserved/rfu/cni byte(1) + section_number(1) + last_section_number(1).
55const EXTENSION_HEADER_LEN: usize = 5;
56
57/// Bytes 8-11: the 32-bit `real_time_parameters()`.
58const RTP_LEN: usize = 4;
59
60/// Bytes occupied by the trailing CRC-32 field.
61const CRC_LEN: usize = 4;
62
63/// Minimum total encoded length: header + extension + RTP + CRC.
64const MIN_LEN: usize = HEADER_LEN + EXTENSION_HEADER_LEN + RTP_LEN + CRC_LEN;
65
66/// Time-slicing / MPE-FEC real-time parameters (EN 301 192 §9.10, Table 46).
67///
68/// 32 bits: `delta_t(12)` | `table_boundary(1)` | `frame_boundary(1)`
69/// | `address(18)`.
70#[derive(Debug, Clone, Copy, PartialEq, Eq)]
71#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
72pub struct RealTimeParameters {
73    /// 12-bit `delta_t` — time until the start of the next burst (in units of
74    /// the MPE-FEC frame, see §9.10).
75    pub delta_t: u16,
76    /// `table_boundary` flag.
77    pub table_boundary: bool,
78    /// `frame_boundary` flag.
79    pub frame_boundary: bool,
80    /// 18-bit `address` — byte position of the first payload byte of this
81    /// section within the MPE-FEC frame table.
82    pub address: u32,
83}
84
85impl RealTimeParameters {
86    /// Decode the 4-byte real_time_parameters block.
87    fn from_bytes(b: [u8; RTP_LEN]) -> Self {
88        // delta_t(12) = b[0] | top 4 bits of b[1]
89        let delta_t = ((b[0] as u16) << 4) | ((b[1] >> 4) as u16);
90        let table_boundary = (b[1] & 0x08) != 0;
91        let frame_boundary = (b[1] & 0x04) != 0;
92        // address(18) = bottom 2 bits of b[1] | b[2] | b[3]
93        let address = (((b[1] & 0x03) as u32) << 16) | ((b[2] as u32) << 8) | (b[3] as u32);
94        RealTimeParameters {
95            delta_t,
96            table_boundary,
97            frame_boundary,
98            address,
99        }
100    }
101
102    /// Encode into the 4-byte real_time_parameters block.
103    fn to_bytes(self) -> [u8; RTP_LEN] {
104        let dt = self.delta_t & 0x0FFF;
105        let addr = self.address & 0x0003_FFFF;
106        [
107            (dt >> 4) as u8,
108            (((dt & 0x0F) as u8) << 4)
109                | (u8::from(self.table_boundary) << 3)
110                | (u8::from(self.frame_boundary) << 2)
111                | ((addr >> 16) as u8 & 0x03),
112            ((addr >> 8) & 0xFF) as u8,
113            (addr & 0xFF) as u8,
114        ]
115    }
116}
117
118/// MPE-FEC section (ETSI EN 301 192 v1.7.1 §9.9).
119#[derive(Debug, Clone, PartialEq, Eq)]
120#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
121pub struct MpeFec<'a> {
122    /// `private_indicator` bit from byte 1 (MPE-FEC is a private section).
123    pub private_indicator: bool,
124    /// `padding_columns` — number of padding RS columns (byte 3).
125    pub padding_columns: u8,
126    /// `current_next_indicator` bit.
127    pub current_next_indicator: bool,
128    /// section_number in the sub-table sequence.
129    pub section_number: u8,
130    /// last_section_number in the sub-table sequence.
131    pub last_section_number: u8,
132    /// The decoded real-time parameters block.
133    pub real_time_parameters: RealTimeParameters,
134    /// Raw Reed-Solomon data bytes (everything between the real_time_parameters
135    /// block and the CRC-32 trailer).
136    #[cfg_attr(feature = "serde", serde(borrow))]
137    pub rs_data: &'a [u8],
138}
139
140impl<'a> Parse<'a> for MpeFec<'a> {
141    type Error = crate::error::Error;
142
143    fn parse(bytes: &'a [u8]) -> Result<Self> {
144        if bytes.len() < MIN_LEN {
145            return Err(Error::BufferTooShort {
146                need: MIN_LEN,
147                have: bytes.len(),
148                what: "MpeFec",
149            });
150        }
151
152        if bytes[0] != TABLE_ID {
153            return Err(Error::UnexpectedTableId {
154                table_id: bytes[0],
155                what: "MpeFec",
156                expected: &[TABLE_ID],
157            });
158        }
159
160        let section_length = (((bytes[1] & 0x0F) as usize) << 8) | bytes[2] as usize;
161        let total = HEADER_LEN + section_length;
162        if bytes.len() < total {
163            return Err(Error::SectionLengthOverflow {
164                declared: section_length,
165                available: bytes.len() - HEADER_LEN,
166            });
167        }
168
169        let private_indicator = (bytes[1] & 0x40) != 0;
170        let padding_columns = bytes[3];
171        // bytes[4] = reserved_for_future_use(8) — ignored on parse.
172        // bytes[5] = reserved(2) | reserved_for_future_use(5) | current_next_indicator(1)
173        let current_next_indicator = (bytes[5] & 0x01) != 0;
174        let section_number = bytes[6];
175        let last_section_number = bytes[7];
176
177        let rtp_start = HEADER_LEN + EXTENSION_HEADER_LEN;
178        let real_time_parameters = RealTimeParameters::from_bytes([
179            bytes[rtp_start],
180            bytes[rtp_start + 1],
181            bytes[rtp_start + 2],
182            bytes[rtp_start + 3],
183        ]);
184
185        let data_start = rtp_start + RTP_LEN;
186        let data_end = total - CRC_LEN;
187        let rs_data = &bytes[data_start..data_end];
188
189        Ok(MpeFec {
190            private_indicator,
191            padding_columns,
192            current_next_indicator,
193            section_number,
194            last_section_number,
195            real_time_parameters,
196            rs_data,
197        })
198    }
199}
200
201impl Serialize for MpeFec<'_> {
202    type Error = crate::error::Error;
203
204    fn serialized_len(&self) -> usize {
205        HEADER_LEN + EXTENSION_HEADER_LEN + RTP_LEN + self.rs_data.len() + CRC_LEN
206    }
207
208    fn serialize_into(&self, buf: &mut [u8]) -> Result<usize> {
209        let len = self.serialized_len();
210        if buf.len() < len {
211            return Err(Error::OutputBufferTooSmall {
212                need: len,
213                have: buf.len(),
214            });
215        }
216
217        let section_length = (len - HEADER_LEN) as u16;
218
219        // Byte 0: table_id.
220        buf[0] = TABLE_ID;
221        // Byte 1: section_syntax_indicator(1)=1 | private_indicator(1)
222        //         | reserved(2)=11 | section_length[11:8](4).
223        buf[1] = 0x80
224            | (u8::from(self.private_indicator) << 6)
225            | 0x30
226            | ((section_length >> 8) as u8 & 0x0F);
227        buf[2] = (section_length & 0xFF) as u8;
228
229        // Extension header.
230        buf[3] = self.padding_columns;
231        buf[4] = 0xFF; // reserved_for_future_use(8) emitted as 1s.
232                       // reserved(2)=11 | reserved_for_future_use(5)=11111 | current_next_indicator(1)
233        buf[5] = 0xFE | u8::from(self.current_next_indicator);
234        buf[6] = self.section_number;
235        buf[7] = self.last_section_number;
236
237        // real_time_parameters.
238        let rtp_start = HEADER_LEN + EXTENSION_HEADER_LEN;
239        buf[rtp_start..rtp_start + RTP_LEN].copy_from_slice(&self.real_time_parameters.to_bytes());
240
241        // rs_data.
242        let data_start = rtp_start + RTP_LEN;
243        let data_end = data_start + self.rs_data.len();
244        buf[data_start..data_end].copy_from_slice(self.rs_data);
245
246        // CRC-32 over everything up to (but not including) the CRC slot.
247        let crc = dvb_common::crc32_mpeg2::compute(&buf[..data_end]);
248        buf[data_end..len].copy_from_slice(&crc.to_be_bytes());
249
250        Ok(len)
251    }
252}
253
254impl<'a> Table<'a> for MpeFec<'a> {
255    const TABLE_ID: u8 = TABLE_ID;
256    const PID: u16 = PID;
257}
258
259impl<'a> crate::traits::TableDef<'a> for MpeFec<'a> {
260    const TABLE_ID_RANGES: &'static [(u8, u8)] = &[(TABLE_ID, TABLE_ID)];
261    const NAME: &'static str = "MPE_FEC";
262}
263
264#[cfg(test)]
265mod tests {
266    use super::*;
267
268    fn build_mpe_fec(
269        padding_columns: u8,
270        current_next: bool,
271        section_number: u8,
272        last_section_number: u8,
273        rtp: RealTimeParameters,
274        rs_data: &[u8],
275    ) -> Vec<u8> {
276        let s = MpeFec {
277            private_indicator: true,
278            padding_columns,
279            current_next_indicator: current_next,
280            section_number,
281            last_section_number,
282            real_time_parameters: rtp,
283            rs_data,
284        };
285        let mut buf = vec![0u8; s.serialized_len()];
286        s.serialize_into(&mut buf).unwrap();
287        buf
288    }
289
290    fn sample_rtp() -> RealTimeParameters {
291        RealTimeParameters {
292            delta_t: 0x0ABC,
293            table_boundary: true,
294            frame_boundary: false,
295            address: 0x0001_2345,
296        }
297    }
298
299    #[test]
300    fn parse_happy_path() {
301        let rs = [0x11u8, 0x22, 0x33, 0x44];
302        let bytes = build_mpe_fec(7, true, 1, 3, sample_rtp(), &rs);
303        let s = MpeFec::parse(&bytes).unwrap();
304        assert!(s.private_indicator);
305        assert_eq!(s.padding_columns, 7);
306        assert!(s.current_next_indicator);
307        assert_eq!(s.section_number, 1);
308        assert_eq!(s.last_section_number, 3);
309        assert_eq!(s.real_time_parameters, sample_rtp());
310        assert_eq!(s.rs_data, &rs[..]);
311    }
312
313    #[test]
314    fn parse_empty_rs_data() {
315        let bytes = build_mpe_fec(0, false, 0, 0, sample_rtp(), &[]);
316        let s = MpeFec::parse(&bytes).unwrap();
317        assert_eq!(s.padding_columns, 0);
318        assert!(!s.current_next_indicator);
319        assert!(s.rs_data.is_empty());
320        assert_eq!(s.real_time_parameters, sample_rtp());
321    }
322
323    #[test]
324    fn rtp_bit_packing_round_trips_extremes() {
325        // Exercise full-width values to pin the 12/1/1/18 split.
326        let rtp = RealTimeParameters {
327            delta_t: 0x0FFF,
328            table_boundary: false,
329            frame_boundary: true,
330            address: 0x0003_FFFF,
331        };
332        assert_eq!(RealTimeParameters::from_bytes(rtp.to_bytes()), rtp);
333    }
334
335    #[test]
336    fn parse_rejects_wrong_tag() {
337        let mut bytes = build_mpe_fec(0, true, 0, 0, sample_rtp(), &[]);
338        bytes[0] = 0x70; // not 0x78
339        assert!(matches!(
340            MpeFec::parse(&bytes).unwrap_err(),
341            Error::UnexpectedTableId { table_id: 0x70, .. }
342        ));
343    }
344
345    #[test]
346    fn parse_rejects_short_buffer() {
347        assert!(matches!(
348            MpeFec::parse(&[0x78, 0x80]).unwrap_err(),
349            Error::BufferTooShort { .. }
350        ));
351    }
352
353    #[test]
354    fn parse_rejects_section_length_overflow() {
355        let mut bytes = build_mpe_fec(0, true, 0, 0, sample_rtp(), &[]);
356        let fake_sl: u16 = (bytes.len() as u16) + 100 - HEADER_LEN as u16;
357        bytes[1] = (bytes[1] & 0xF0) | ((fake_sl >> 8) as u8 & 0x0F);
358        bytes[2] = (fake_sl & 0xFF) as u8;
359        assert!(matches!(
360            MpeFec::parse(&bytes).unwrap_err(),
361            Error::SectionLengthOverflow { .. }
362        ));
363    }
364
365    #[test]
366    fn serialize_round_trip() {
367        let rs = [0xDEu8, 0xAD, 0xBE, 0xEF, 0x00];
368        let original = MpeFec {
369            private_indicator: false,
370            padding_columns: 191,
371            current_next_indicator: false,
372            section_number: 2,
373            last_section_number: 4,
374            real_time_parameters: sample_rtp(),
375            rs_data: &rs,
376        };
377        let mut buf = vec![0u8; original.serialized_len()];
378        original.serialize_into(&mut buf).unwrap();
379        assert_eq!(MpeFec::parse(&buf).unwrap(), original);
380    }
381
382    #[test]
383    fn serialize_rejects_output_buffer_too_small() {
384        let s = MpeFec {
385            private_indicator: false,
386            padding_columns: 0,
387            current_next_indicator: true,
388            section_number: 0,
389            last_section_number: 0,
390            real_time_parameters: sample_rtp(),
391            rs_data: &[],
392        };
393        let mut buf = vec![0u8; 2];
394        assert!(matches!(
395            s.serialize_into(&mut buf).unwrap_err(),
396            Error::OutputBufferTooSmall { .. }
397        ));
398    }
399
400    #[test]
401    fn table_trait_constants() {
402        assert_eq!(<MpeFec as Table>::TABLE_ID, 0x78);
403        assert_eq!(<MpeFec as Table>::PID, 0x0000);
404    }
405
406    #[cfg(feature = "serde")]
407    #[test]
408    fn serde_json_round_trip() {
409        // `rs_data` is a borrowed `&[u8]` (the rnt/cit idiom), so a deserialize
410        // round-trip is not possible. Mirror the borrowed tables by asserting
411        // serialization yields valid, field-bearing JSON. The typed
412        // RealTimeParameters struct DOES survive a full round-trip.
413        let rs = [0x01u8, 0x02];
414        let bytes = build_mpe_fec(12, true, 0, 0, sample_rtp(), &rs);
415        let s = MpeFec::parse(&bytes).unwrap();
416        let v: serde_json::Value = serde_json::to_value(&s).unwrap();
417        assert_eq!(v["padding_columns"], 12);
418        assert_eq!(v["current_next_indicator"], true);
419        assert_eq!(v["rs_data"], serde_json::json!([0x01, 0x02]));
420        assert_eq!(v["real_time_parameters"]["delta_t"], 0x0ABC);
421        assert_eq!(v["real_time_parameters"]["table_boundary"], true);
422        // RealTimeParameters is owned/Copy → full serde round-trip works.
423        let rtp_json = serde_json::to_string(&s.real_time_parameters).unwrap();
424        assert_eq!(
425            serde_json::from_str::<RealTimeParameters>(&rtp_json).unwrap(),
426            s.real_time_parameters
427        );
428    }
429}
dvb_si/tables/mpe_fec.rs

dvb_si/tables/
mpe_fec.rs
