diff --git a/README.md b/README.md index 5f2960e..44ece5b 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,10 @@ This project provides Rust bindings for DLT and a tracing subscriber that allows ## 📖 Documentation -[DLT Sys documentation](https://htmlpreview.github.io/?https://github.com/eclipse-opensovd/dlt-tracing-lib/blob/main/docs/dlt_sys/index.html) +* [tracing-dlt](https://eclipse-opensovd.github.io/dlt-tracing-lib/tracing_dlt/index.html) +* [dlt_rs](https://eclipse-opensovd.github.io/dlt-tracing-lib/dlt_rs/index.html) +* [dlr_sys](https://eclipse-opensovd.github.io/dlt-tracing-lib/dlt_sys/index.html) -[DLT Trace Appender documentation](https://htmlpreview.github.io/?https://github.com/eclipse-opensovd/dlt-tracing-lib/blob/main/docs/dlt_tracing_appender/index.html) - - -The documentation includes detailed examples, usage patterns, and API reference for all crates. -Get it by running: -```bash - cargo doc --no-deps --all-features -``` ## Overview diff --git a/dlt-sys/src/lib.rs b/dlt-sys/src/lib.rs index beef2de..2db4e1a 100644 --- a/dlt-sys/src/lib.rs +++ b/dlt-sys/src/lib.rs @@ -11,6 +11,53 @@ * SPDX-License-Identifier: Apache-2.0 */ +//! Low-level FFI bindings to the COVESA DLT (Diagnostic Log and Trace) C library (`libdlt`). +//! +//! # Overview +//! +//! `dlt-sys` provides unsafe Rust bindings to the +//! [COVESA DLT daemon](https://github.com/COVESA/dlt-daemon) C library. +//! This crate is intended to be used as a foundation for higher-level safe +//! Rust abstractions (see [`dlt-rs`](https://crates.io/crates/dlt-rs)). +//! +//! **Note:** This crate only implements functionality required for `dlt-rs` and does not cover +//! the entire `libdlt` API. +//! +//! # Features +//! +//! - Direct FFI bindings to `libdlt` functions +//! - Custom C wrapper for improved API ergonomics +//! - Support for all DLT log levels and message types +//! - Optional `trace_load_ctrl` feature for load control support +//! +//! # Prerequisites +//! +//! **libdlt** and its development headers must be installed on your system. +//! +//! # Usage +//! +//! This is a low-level crate with unsafe APIs. Most users should use +//! [`dlt-rs`](https://crates.io/crates/dlt-rs) instead for a safe, idiomatic Rust API. +//! +//! # Cargo Features +//! +//! - `trace_load_ctrl` - Enable DLT load control support +//! - `generate-bindings` - Regenerate bindings from C headers (development only) +//! +//! # Safety +//! +//! All functions in this crate are `unsafe` as they directly call C library functions. +//! Proper usage requires understanding of: +//! - DLT library initialization and cleanup +//! - Memory management across FFI boundaries +//! - Thread safety considerations +//! +//! For safe abstractions, use the [`dlt-rs`](https://crates.io/crates/dlt-rs) crate. +//! +//! # References +//! +//! - [COVESA DLT Daemon](https://github.com/COVESA/dlt-daemon) + #[rustfmt::skip] #[allow(clippy::all, dead_code,