dvb_ci_runtime/
lib.rs

1//! Pure-Rust EN 50221 DVB Common Interface **runtime** — the driver loop over
2//! the [`dvb_ci`] codecs.
3//!
4//! [`dvb_ci`] is `no_std` and owns the *wire* layer (TPDU / SPDU / APDU
5//! parse+serialize, CA_PMT building, CI Plus extensions). This crate adds the
6//! *runtime*: device I/O, the TPDU poll loop, SPDU session management, and the
7//! per-resource state machines that together drive a physical CAM, per
8//! ETSI EN 50221 and TS 101 699.
9//!
10//! # Design
11//!
12//! The whole runtime is written against the [`CaDevice`] trait (the
13//! hardware-abstraction boundary), so it runs against either:
14//! - a real Linux CA device (`/dev/dvb/adapterN/caM`, the `linux` feature), or
15//! - the in-memory [`MockCaDevice`], which makes the state machines testable
16//!   without hardware and enables differential testing against an external
17//!   reference (drive both with the same scripted mock CAM and assert the
18//!   emitted `write`/ioctl byte sequences match).
19//!
20//! Implemented from the EN 50221 specification.
21//!
22//! # What's implemented
23//!
24//! - **Transport** (TPDU, §A.4): `Create_T_C` handshake, empty-`T_Data_Last`
25//!   poll cadence, `T_SB` data-available → `T_RCV`, `T_Data_More/Last`
26//!   reassembly, reply timeout.
27//! - **Session** (SPDU, §7.2): session table; `open_session_request`/response,
28//!   host-initiated `create_session`, `close_session`; `session_number` + APDU
29//!   routing.
30//! - **Resources** (§8): Resource Manager handshake (profile exchange →
31//!   [`Notification::CamReady`], then opens module resources),
32//!   application_information, conditional_access (`ca_pmt`/`ca_pmt_reply`),
33//!   date_time (MJD + BCD), and mmi (surfaces module menus/enquiries as
34//!   [`Notification::Mmi`]).
35//! - **Descramble helper**: [`Driver::descramble`](crate::driver::Driver::descramble)
36//!   / [`HostRequest::Descramble`] runs the full `ca_pmt` query → reply →
37//!   ok_descrambling sequence, CAID-filtered to the CAM's `ca_info`.
38//! - **Devices**: the in-memory [`MockCaDevice`] + [`MockCiDataDevice`], and the
39//!   Linux `/dev/dvb/adapterN/caM` (control) + `ciM` (TS data-plane) devices
40//!   behind the `linux` feature. The data plane ([`CiDataDevice`]) carries the
41//!   scrambled-in / descrambled-out TS for separate-CI hardware.
42//!
43//! - **Diagnostics**: [`RecordingCaDevice`] captures the link in both directions;
44//!   [`trace::decode_frame`]/[`decode_log`](crate::trace::decode_log) annotate a
45//!   capture (TPDU → SPDU → APDU) for live-CAM debugging.
46//!
47//! Roadmap: the `host_control` resource, MMI answering (`menu_answ`/`answ`), and
48//! a differential test harness against an external reference.
49//!
50//! # Example
51//!
52//! Drive a CAM with the [`MockCaDevice`] — the same `Driver` API works against
53//! the real Linux device:
54//!
55//! ```
56//! use std::time::Duration;
57//! use dvb_ci_runtime::{Driver, MockCaDevice, Notification};
58//! use dvb_ci_runtime::dvb_ci::tpdu::tags;
59//!
60//! # fn main() -> std::io::Result<()> {
61//! // Script a module that accepts the transport connection.
62//! let dev = MockCaDevice::new([vec![tags::C_T_C_REPLY, 0x01, 0x01]]);
63//! let mut driver = Driver::new(dev);
64//!
65//! driver.init()?; // reset + open the transport connection
66//!
67//! // Pump the device: reads frames when readable, otherwise advances the
68//! // EN 50221 poll cadence by the timeout.
69//! for _ in 0..4 {
70//!     driver.pump(Duration::from_millis(100))?;
71//! }
72//!
73//! // Host-facing events (CamReady, ApplicationInfo, CaInfo, Mmi, …) surface here.
74//! for note in driver.take_notifications() {
75//!     match note {
76//!         Notification::CamReady => { /* now safe to send a ca_pmt */ }
77//!         other => { let _ = other; }
78//!     }
79//! }
80//! # Ok(())
81//! # }
82//! ```
83
84// The portable core is unsafe-free; only the optional Linux device leaf
85// (`#[allow(unsafe_code)]` in `linux`) uses ioctls, so this is `deny`, not
86// `forbid`.
87#![deny(unsafe_code)]
88#![warn(missing_docs)]
89
90pub mod dataplane;
91pub mod device;
92pub mod driver;
93pub mod event;
94pub mod resource;
95pub mod session;
96pub mod stack;
97pub mod trace;
98pub mod transport;
99
100#[cfg(all(feature = "linux", target_os = "linux"))]
101pub mod linux;
102
103pub use dataplane::{CiDataDevice, MockCiDataDevice, TS_PACKET_LEN};
104pub use device::{CaDevice, DeviceOp, LinkEvent, MockCaDevice, RecordingCaDevice, SlotInfo};
105pub use driver::Driver;
106pub use event::{Action, Event, HostRequest, Notification};
107#[cfg(all(feature = "linux", target_os = "linux"))]
108pub use linux::{LinuxCaDevice, LinuxCiDataDevice};
109pub use stack::CiStack;
110
111/// Re-export of the wire-codec crate this runtime drives.
112pub use dvb_ci;
dvb_ci_runtime/lib.rs

dvb_ci_runtime/
lib.rs
