zx/
debuglog.rs

1// Copyright 2019 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! Type-safe bindings for Zircon resources.
6
7use crate::{
8    ok, sys, AsHandleRef, BootInstant, Handle, HandleBased, HandleRef, Koid, Resource, Status,
9};
10use bitflags::bitflags;
11use bstr::BStr;
12
13/// An object representing a Zircon 'debuglog' object.
14///
15/// As essentially a subtype of `Handle`, it can be freely interconverted.
16#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash)]
17#[repr(transparent)]
18pub struct DebugLog(Handle);
19impl_handle_based!(DebugLog);
20
21bitflags! {
22    #[repr(transparent)]
23    #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
24    pub struct DebugLogOpts: u32 {
25        const READABLE = sys::ZX_LOG_FLAG_READABLE;
26    }
27}
28
29impl DebugLog {
30    /// Create a debug log object that allows access to read from and write to the kernel debug
31    /// logging facility.
32    ///
33    /// Wraps the
34    /// [zx_debuglog_create]((https://fuchsia.dev/fuchsia-src/reference/syscalls/debuglog_create.md)
35    /// syscall.
36    pub fn create(resource: &Resource, opts: DebugLogOpts) -> Result<DebugLog, Status> {
37        let mut handle = 0;
38        let status =
39            unsafe { sys::zx_debuglog_create(resource.raw_handle(), opts.bits(), &mut handle) };
40        ok(status)?;
41        unsafe { Ok(DebugLog::from(Handle::from_raw(handle))) }
42    }
43
44    /// Write a message to the kernel debug log.
45    ///
46    /// Wraps the
47    /// [zx_debuglog_write]((https://fuchsia.dev/fuchsia-src/reference/syscalls/debuglog_write.md)
48    /// syscall.
49    pub fn write(&self, message: &[u8]) -> Result<(), Status> {
50        // TODO(https://fxbug.dev/42108144): Discussion ongoing over whether debuglog levels are supported, so no
51        // options parameter for now.
52        let status = unsafe {
53            sys::zx_debuglog_write(self.raw_handle(), 0, message.as_ptr(), message.len())
54        };
55        ok(status)
56    }
57
58    /// Read a single log record from the kernel debug log.
59    ///
60    /// The DebugLog object must have been created with DebugLogOpts::READABLE, or this will return
61    /// an error.
62    ///
63    /// Wraps the
64    /// [zx_debuglog_read]((https://fuchsia.dev/fuchsia-src/reference/syscalls/debuglog_read.md)
65    /// syscall.
66    pub fn read(&self) -> Result<DebugLogRecord, Status> {
67        let mut record = sys::zx_log_record_t::default();
68        let bytes_written = unsafe {
69            sys::zx_debuglog_read(
70                self.raw_handle(),
71                0, /* options are unused, must be 0 */
72                std::ptr::from_mut(&mut record).cast::<u8>(),
73                std::mem::size_of_val(&record),
74            )
75        };
76        // On error, zx_debuglog_read returns a negative value. All other values indicate success.
77        if bytes_written < 0 {
78            Err(Status::from_raw(bytes_written))
79        } else {
80            DebugLogRecord::from_raw(&record)
81        }
82    }
83}
84
85/// A record from the kernel's debuglog.
86#[derive(Debug, Copy, Clone, Eq, PartialEq)]
87pub struct DebugLogRecord {
88    pub sequence: u64,
89    pub timestamp: BootInstant,
90    pub severity: DebugLogSeverity,
91    pub pid: Koid,
92    pub tid: Koid,
93    pub flags: u8,
94    data: [u8; sys::ZX_LOG_RECORD_DATA_MAX],
95    datalen: u16,
96}
97
98impl DebugLogRecord {
99    /// Convert a raw debuglog record into this typed wrapper.
100    pub fn from_raw(raw: &sys::zx_log_record_t) -> Result<Self, Status> {
101        if raw.datalen <= sys::ZX_LOG_RECORD_DATA_MAX as u16 {
102            Ok(Self {
103                timestamp: BootInstant::from_nanos(raw.timestamp),
104                sequence: raw.sequence,
105                severity: DebugLogSeverity::from_raw(raw.severity),
106                pid: Koid::from_raw(raw.pid),
107                tid: Koid::from_raw(raw.tid),
108                flags: raw.flags,
109                data: raw.data,
110                datalen: raw.datalen,
111            })
112        } else {
113            Err(Status::INTERNAL)
114        }
115    }
116
117    /// Returns the message data for the record.
118    pub fn data(&self) -> &BStr {
119        BStr::new(&self.data[..self.datalen as usize])
120    }
121}
122
123/// The severity a kernel log message can have.
124#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
125pub enum DebugLogSeverity {
126    /// Record was written without a known severity.
127    Unknown,
128    /// Trace records include detailed information about program execution.
129    Trace,
130    /// Debug records include development-facing information about program execution.
131    Debug,
132    /// Info records include general information about program execution. (default)
133    Info,
134    /// Warning records include information about potentially problematic operations.
135    Warn,
136    /// Error records include information about failed operations.
137    Error,
138    /// Fatal records convey information about operations which cause a program's termination.
139    Fatal,
140}
141
142impl DebugLogSeverity {
143    fn from_raw(raw: u8) -> Self {
144        match raw {
145            sys::DEBUGLOG_TRACE => Self::Trace,
146            sys::DEBUGLOG_DEBUG => Self::Debug,
147            sys::DEBUGLOG_INFO => Self::Info,
148            sys::DEBUGLOG_WARNING => Self::Warn,
149            sys::DEBUGLOG_ERROR => Self::Error,
150            sys::DEBUGLOG_FATAL => Self::Fatal,
151            _ => Self::Unknown,
152        }
153    }
154}
155
156#[cfg(test)]
157mod tests {
158    use super::*;
159    use crate::{cprng_draw, Instant, Signals};
160    use fidl_fuchsia_kernel as fkernel;
161    use fuchsia_component::client::connect_channel_to_protocol;
162
163    // expect_message_in_debuglog will read the last 10000 messages in zircon's debuglog, looking
164    // for a message that equals `sent_msg`. If found, the function returns. If the first 10,000
165    // messages doesn't contain `sent_msg`, it will panic.
166    fn expect_message_in_debuglog(sent_msg: String) {
167        use zx::{Channel, HandleBased};
168        let (client_end, server_end) = Channel::create();
169        connect_channel_to_protocol::<fkernel::DebuglogResourceMarker>(server_end).unwrap();
170        let service = fkernel::DebuglogResourceSynchronousProxy::new(client_end);
171        let resource =
172            service.get(zx::MonotonicInstant::INFINITE).expect("couldn't get debuglog resource");
173        // This test and fuchsia-zircon are different crates, so we need
174        // to use from_raw to convert between the zx handle and this test handle.
175        // See https://fxbug.dev/42173139 for details.
176        let resource = unsafe { Resource::from(Handle::from_raw(resource.into_raw())) };
177        let debuglog = DebugLog::create(&resource, DebugLogOpts::READABLE).unwrap();
178        for _ in 0..10000 {
179            match debuglog.read() {
180                Ok(record) => {
181                    if record.data() == sent_msg.as_bytes() {
182                        // We found our log!
183                        return;
184                    }
185                }
186                Err(status) if status == Status::SHOULD_WAIT => {
187                    debuglog
188                        .wait_handle(Signals::LOG_READABLE, Instant::INFINITE)
189                        .expect("Failed to wait for log readable");
190                    continue;
191                }
192                Err(status) => {
193                    panic!("Unexpected error from zx_debuglog_read: {}", status);
194                }
195            }
196        }
197        panic!("first 10000 log messages didn't include the one we sent!");
198    }
199
200    #[test]
201    fn read_from_nonreadable() {
202        let resource = Resource::from(Handle::invalid());
203        let debuglog = DebugLog::create(&resource, DebugLogOpts::empty()).unwrap();
204        assert!(debuglog.read().err() == Some(Status::ACCESS_DENIED));
205    }
206
207    #[test]
208    fn write_and_read_back() {
209        let mut bytes = [0; 8];
210        cprng_draw(&mut bytes);
211        let message = format!("log message {:?}", bytes);
212
213        let resource = Resource::from(Handle::invalid());
214        let debuglog = DebugLog::create(&resource, DebugLogOpts::empty()).unwrap();
215        debuglog.write(message.as_bytes()).unwrap();
216        expect_message_in_debuglog(message);
217    }
218}
zx/debuglog.rs

zx/
debuglog.rs
