dof/
lib.rs

1//! Tools for extracting and parsing data in DTrace Object Format (DOF).
2//!
3//! The `dof` crate provides types and functions for reading and writing the DTrace Object Format,
4//! an ELF-like serialization format used to store information about DTrace providers and probes in
5//! object files. DOF sections are generated from source code at compile time, and used to
6//! communicate information to the in-kernel portions of DTrace about the providers and probes
7//! defined in the source.
8//!
9//! Low-level bindings to the DOF C structures are contained in the [`dof_bindings`] module,
10//! however most client code with interact with the more convenient stuctures defined in the crate
11//! root. The [`Section`] type describes a complete DOF section as contained in an object file. It
12//! contains one or more [`Provider`]s, each of which contains one or more [`Probe`]s.
13//!
14//! A [`Probe`] describes the names of the related components, such as the function in which it is
15//! called, the provider to which it belongs, and the probe name itself. It also contains
16//! information about the location of the probe callsite in the object file itself. This is used by
17//! DTrace to enable and disable the probe dynamically.
18//!
19//! Users of the crate will most likely be interested in deserializing existing DOF data from an
20//! object file. The function [`extract_dof_sections`] may be used to pull all sections (and all
21//! providers and probes) from either an ELF or Mach-O object file.
22//!
23//! The [`Section::from_bytes`] and [`Section::as_bytes`] methods can be used for ser/des of a
24//! section directly to DOF itself, i.e., ignoring the larger object file format.
25//!
26//! Most useful methods and types are exported in the crate root. However, the lower-level Rust
27//! bindings to the raw C-structs are also exposed in the [`dof_bindings`] module, and may be
28//! extracted from a DOF byte slice with the [`des::deserialize_raw_sections`] function.
29
30// Copyright 2021 Oxide Computer Company
31//
32// Licensed under the Apache License, Version 2.0 (the "License");
33// you may not use this file except in compliance with the License.
34// You may obtain a copy of the License at
35//
36//     http://www.apache.org/licenses/LICENSE-2.0
37//
38// Unless required by applicable law or agreed to in writing, software
39// distributed under the License is distributed on an "AS IS" BASIS,
40// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
41// See the License for the specific language governing permissions and
42// limitations under the License.
43
44#[cfg(feature = "des")]
45pub mod des;
46pub mod dof;
47pub mod dof_bindings;
48#[cfg(feature = "des")]
49pub mod fmt;
50pub mod ser;
51
52#[cfg(feature = "des")]
53pub use crate::des::{
54    collect_dof_sections, deserialize_section, extract_dof_sections, is_dof_section,
55};
56pub use crate::dof::*;
57pub use crate::ser::serialize_section;
dof/lib.rs

dof/
lib.rs
