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//! Roadmap: the `host_control` resource, MMI answering (`menu_answ`/`answ`), and
44//! a differential test harness against an external reference.
45//!
46//! # Example
47//!
48//! Drive a CAM with the [`MockCaDevice`] — the same `Driver` API works against
49//! the real Linux device:
50//!
51//! ```
52//! use std::time::Duration;
53//! use dvb_ci_runtime::{Driver, MockCaDevice, Notification};
54//! use dvb_ci_runtime::dvb_ci::tpdu::tags;
55//!
56//! # fn main() -> std::io::Result<()> {
57//! // Script a module that accepts the transport connection.
58//! let dev = MockCaDevice::new([vec![tags::C_T_C_REPLY, 0x01, 0x01]]);
59//! let mut driver = Driver::new(dev);
60//!
61//! driver.init()?; // reset + open the transport connection
62//!
63//! // Pump the device: reads frames when readable, otherwise advances the
64//! // EN 50221 poll cadence by the timeout.
65//! for _ in 0..4 {
66//!     driver.pump(Duration::from_millis(100))?;
67//! }
68//!
69//! // Host-facing events (CamReady, ApplicationInfo, CaInfo, Mmi, …) surface here.
70//! for note in driver.take_notifications() {
71//!     match note {
72//!         Notification::CamReady => { /* now safe to send a ca_pmt */ }
73//!         other => { let _ = other; }
74//!     }
75//! }
76//! # Ok(())
77//! # }
78//! ```
79
80// The portable core is unsafe-free; only the optional Linux device leaf
81// (`#[allow(unsafe_code)]` in `linux`) uses ioctls, so this is `deny`, not
82// `forbid`.
83#![deny(unsafe_code)]
84#![warn(missing_docs)]
85
86pub mod dataplane;
87pub mod device;
88pub mod driver;
89pub mod event;
90pub mod resource;
91pub mod session;
92pub mod stack;
93pub mod transport;
94
95#[cfg(all(feature = "linux", target_os = "linux"))]
96pub mod linux;
97
98pub use dataplane::{CiDataDevice, MockCiDataDevice, TS_PACKET_LEN};
99pub use device::{CaDevice, DeviceOp, MockCaDevice, SlotInfo};
100pub use driver::Driver;
101pub use event::{Action, Event, HostRequest, Notification};
102#[cfg(all(feature = "linux", target_os = "linux"))]
103pub use linux::{LinuxCaDevice, LinuxCiDataDevice};
104pub use stack::CiStack;
105
106/// Re-export of the wire-codec crate this runtime drives.
107pub use dvb_ci;
dvb_ci_runtime/lib.rs

dvb_ci_runtime/
lib.rs
