1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
//! Parse data emitted by the linux `perf_event_open` syscall.
//!
//! # Important Types
//! - [`Record`] is an enum that can parse any known record type emitted by
//! [`perf_event_open`]. You will likely want to start here.
//! - The [`parse`] module has the [`Parser`] and [`ParseConfig`] types which
//! you will need in order to parse anything.
//!
//! [`perf_event_open`]: https://man7.org/linux/man-pages/man2/perf_event_open.2.html
//!
//! [mod]: crate::parse
//! [`Parse`]: crate::parse::Parse
//! [`Parser`]: crate::parse::Parser
//! [`ParseConfig`]: crate::parse::ParseConfig
//!
//! # Example
//! Parsing a mmap record directly from its raw byte format.
//! ```
//! # fn main() -> perf_event_data::parse::ParseResult<()> {
//! use perf_event_data::endian::Little;
//! use perf_event_data::parse::{ParseConfig, Parser};
//! use perf_event_data::Record;
//!
//! let data: &[u8] = &[
//! 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x00, 0x16, 0x4C, 0x01, 0x00, 0x17, 0x4C, 0x01,
//! 0x00, 0x00, 0xA0, 0x48, 0x96, 0x4F, 0x7F, 0x00, 0x00, 0x00, 0x10, 0x00, 0x00, 0x00, 0x00,
//! 0x00, 0x00, 0x00, 0xA0, 0x48, 0x96, 0x4F, 0x7F, 0x00, 0x00, 0x2F, 0x2F, 0x61, 0x6E, 0x6F,
//! 0x6E, 0x00, 0x00,
//! ];
//!
//! let config = ParseConfig::<Little>::default();
//! let mut parser = Parser::new(data, config);
//! let record: Record = parser.parse()?;
//!
//! let mmap = match record {
//! Record::Mmap(mmap) => mmap,
//! _ => panic!("expected a MMAP record"),
//! };
//! # Ok(())
//! # }
//! ```
//!
//! # Crate Orginization
//! This crate is organized like this:
//! - The root contains all the data types that records can be parsed into. This
//! includes not only the types corresponding to the perf records but also
//! those that make up their fields, and so on.
//! - The [`parse`][mod] module contains types and traits needed to implement
//! parsing support. Most types exposed in the root implement [`Parse`] but to
//! actually make use of that you will need the [`Parser`] and [`ParseConfig`]
//! types from the [`parse`][mod] module.
//! - The [`endian`] module contains some types for converting values to the
//! native endian. You likely won't have to interact with it other than
//! picking one type to use when creating a [`ParseConfig`].
//!
//! # Parsing `perf.data` files
//! This crate doesn't yet have support for this, although it could be used as
//! part of implementing a larger parser. If you would like to do this please
//! open an issue!
// bitflags generates this all over the place so better to silence it.
// Needs to be first so other modules can see the macros.
pub use crate*;
pub use crate*;
pub use crate;
/// Common data used in doctests.
///
/// This way it doesn't need to be repeated multiple times unless we want to
/// show it as part of the doc test.
///
/// It is also used to verify that the examples within the README work.