diagnostics_log_encoding/
encode.rs

1// Copyright 2020 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//! Encoding diagnostic records using the Fuchsia Tracing format.
6
7use crate::{
8    constants, ArgType, Argument, Header, Metatag, RawSeverity, Record, Value, MAX_SIZE_WORDS,
9};
10use std::array::TryFromSliceError;
11use std::borrow::{Borrow, Cow};
12use std::fmt::Debug;
13use std::io::Cursor;
14use std::ops::Deref;
15use thiserror::Error;
16use zerocopy::{FromBytes, IntoBytes};
17
18#[cfg(fuchsia_api_level_less_than = "27")]
19use fidl_fuchsia_diagnostics::Severity;
20#[cfg(fuchsia_api_level_at_least = "27")]
21use fidl_fuchsia_diagnostics_types::Severity;
22
23/// An `Encoder` wraps any value implementing `MutableBuffer` and writes diagnostic stream records
24/// into it.
25pub struct Encoder<B> {
26    pub(crate) buf: B,
27    /// Encoder options
28    options: EncoderOpts,
29}
30
31/// Options for the encoder
32#[derive(Default)]
33pub struct EncoderOpts {
34    /// Whether or not to always log the line/file information
35    /// Defaults to false. If false, the line/file information
36    /// will only be logged for ERROR and above.
37    pub always_log_file_line: bool,
38}
39
40/// Parameters for `Encoder/write_event`.
41pub struct WriteEventParams<'a, E, T, MS> {
42    /// The event to write as a record.
43    pub event: E,
44    /// Tags associated with the log event.
45    pub tags: &'a [T],
46    /// Metatags associated with the log event.
47    pub metatags: MS,
48    /// The process that emitted the log.
49    pub pid: zx::Koid,
50    /// The thread that emitted the log.
51    pub tid: zx::Koid,
52    /// Number of events that were dropped before this one.
53    pub dropped: u64,
54}
55
56impl<B> Encoder<B>
57where
58    B: MutableBuffer,
59{
60    /// Create a new `Encoder` from the provided buffer.
61    pub fn new(buf: B, options: EncoderOpts) -> Self {
62        Self { buf, options }
63    }
64
65    /// Returns a reference to the underlying buffer being used for encoding.
66    pub fn inner(&self) -> &B {
67        &self.buf
68    }
69
70    /// Returns a reference to the underlying buffer being used for encoding.
71    pub fn take(self) -> B {
72        self.buf
73    }
74
75    /// Writes an event to to the buffer as a record.
76    ///
77    /// Fails if there is insufficient space in the buffer for encoding.
78    pub fn write_event<'a, E, MS, T>(
79        &mut self,
80        params: WriteEventParams<'a, E, T, MS>,
81    ) -> Result<(), EncodingError>
82    where
83        E: RecordEvent,
84        MS: Iterator<Item = &'a Metatag>,
85        T: AsRef<str>,
86    {
87        let WriteEventParams { event, tags, metatags, pid, tid, dropped } = params;
88        let severity = event.raw_severity();
89        self.write_inner(event.timestamp(), severity, |this| {
90            this.write_raw_argument(constants::PID, pid.raw_koid())?;
91            this.write_raw_argument(constants::TID, tid.raw_koid())?;
92            if dropped > 0 {
93                this.write_raw_argument(constants::NUM_DROPPED, dropped)?;
94            }
95            if this.options.always_log_file_line || severity >= Severity::Error.into_primitive() {
96                // If the severity is ERROR or higher, we add the file and line information.
97                if let Some(mut file) = event.file() {
98                    let split = file.split("../");
99                    file = split.last().unwrap();
100                    this.write_raw_argument(constants::FILE, Value::Text(Cow::Borrowed(file)))?;
101                }
102
103                if let Some(line) = event.line() {
104                    this.write_raw_argument(constants::LINE, line as u64)?;
105                }
106            }
107
108            // Write the metatags as tags (if any were given)
109            for metatag in metatags {
110                match metatag {
111                    Metatag::Target => this.write_raw_argument(constants::TAG, event.target())?,
112                }
113            }
114
115            event.write_arguments(this)?;
116
117            for tag in tags {
118                this.write_raw_argument(constants::TAG, tag.as_ref())?;
119            }
120            Ok(())
121        })?;
122        Ok(())
123    }
124
125    /// Writes a Record to the buffer.
126    pub fn write_record<R>(&mut self, record: R) -> Result<(), EncodingError>
127    where
128        R: RecordFields,
129    {
130        self.write_inner(record.timestamp(), record.raw_severity(), |this| {
131            record.write_arguments(this)
132        })
133    }
134
135    fn write_inner<F>(
136        &mut self,
137        timestamp: zx::BootInstant,
138        severity: RawSeverity,
139        write_args: F,
140    ) -> Result<(), EncodingError>
141    where
142        F: FnOnce(&mut Self) -> Result<(), EncodingError>,
143    {
144        // TODO(https://fxbug.dev/42138121): on failure, zero out the region we were using
145        let starting_idx = self.buf.cursor();
146        // Prepare the header, we'll finish writing once we know the full size of the record.
147        let header_slot = self.buf.put_slot(std::mem::size_of::<u64>())?;
148        self.write_i64(timestamp.into_nanos())?;
149
150        write_args(self)?;
151
152        let mut header = Header(0);
153        header.set_type(crate::TRACING_FORMAT_LOG_RECORD_TYPE);
154        header.set_severity(severity);
155
156        let length = self.buf.cursor() - starting_idx;
157        header.set_len(length);
158
159        assert_eq!(length % 8, 0, "all records must be written 8-byte aligned");
160        self.buf.fill_slot(header_slot, &header.0.to_le_bytes());
161        Ok(())
162    }
163
164    /// Writes an argument with this encoder with the given name and value.
165    pub fn write_raw_argument(
166        &mut self,
167        name: &str,
168        value: impl WriteArgumentValue<B>,
169    ) -> Result<(), EncodingError> {
170        self.inner_write_argument(move |header, encoder| {
171            encoder.write_argument_name(header, name)?;
172            value.write_value(header, encoder)?;
173            Ok(())
174        })
175    }
176
177    /// Writes an argument with this encoder.
178    pub fn write_argument<'a>(
179        &mut self,
180        argument: impl Borrow<Argument<'a>>,
181    ) -> Result<(), EncodingError> {
182        let argument = argument.borrow();
183        self.inner_write_argument(move |header, encoder| {
184            encoder.write_argument_name(header, argument.name())?;
185            argument.write_value(header, encoder)?;
186            Ok(())
187        })
188    }
189
190    fn write_argument_name(
191        &mut self,
192        header: &mut Header,
193        name: &str,
194    ) -> Result<(), EncodingError> {
195        self.write_string(name)?;
196        header.set_name_ref(string_mask(name));
197        Ok(())
198    }
199
200    fn inner_write_argument(
201        &mut self,
202        cb: impl FnOnce(&mut Header, &mut Self) -> Result<(), EncodingError>,
203    ) -> Result<(), EncodingError> {
204        let starting_idx = self.buf.cursor();
205        let header_slot = self.buf.put_slot(std::mem::size_of::<Header>())?;
206
207        let mut header = Header(0);
208        cb(&mut header, self)?;
209
210        let record_len = self.buf.cursor() - starting_idx;
211        assert_eq!(record_len % 8, 0, "arguments must be 8-byte aligned");
212
213        header.set_size_words((record_len / 8) as u16);
214        self.buf.fill_slot(header_slot, &header.0.to_le_bytes());
215
216        Ok(())
217    }
218
219    /// Write an unsigned integer.
220    fn write_u64(&mut self, n: u64) -> Result<(), EncodingError> {
221        self.buf.put_u64_le(n).map_err(|_| EncodingError::BufferTooSmall)
222    }
223
224    /// Write a signed integer.
225    fn write_i64(&mut self, n: i64) -> Result<(), EncodingError> {
226        self.buf.put_i64_le(n).map_err(|_| EncodingError::BufferTooSmall)
227    }
228
229    /// Write a floating-point number.
230    fn write_f64(&mut self, n: f64) -> Result<(), EncodingError> {
231        self.buf.put_f64(n).map_err(|_| EncodingError::BufferTooSmall)
232    }
233
234    /// Write a string padded to 8-byte alignment.
235    fn write_string(&mut self, src: &str) -> Result<(), EncodingError> {
236        self.write_bytes(src.as_bytes())
237    }
238
239    /// Write bytes padded to 8-byte alignment.
240    #[doc(hidden)]
241    pub fn write_bytes(&mut self, src: &[u8]) -> Result<(), EncodingError> {
242        self.buf.put_slice(src).map_err(|_| EncodingError::BufferTooSmall)?;
243        unsafe {
244            let align = std::mem::size_of::<u64>();
245            let num_padding_bytes = (align - src.len() % align) % align;
246            // TODO(https://fxbug.dev/42138122) need to enforce that the buffer is zeroed
247            self.buf.advance_cursor(num_padding_bytes);
248        }
249        Ok(())
250    }
251}
252
253mod private {
254    use super::*;
255
256    pub trait Sealed {}
257    impl Sealed for Value<'_> {}
258    impl Sealed for Argument<'_> {}
259    impl Sealed for u64 {}
260    impl Sealed for f64 {}
261    impl Sealed for i64 {}
262    impl Sealed for bool {}
263    impl Sealed for String {}
264    impl Sealed for &str {}
265    impl Sealed for Cow<'_, str> {}
266}
267
268/// Trait implemented by types which can be written to the encoder.
269pub trait WriteArgumentValue<B>: private::Sealed {
270    /// Writes the value of the argument.
271    fn write_value(
272        &self,
273        header: &mut Header,
274        encoder: &mut Encoder<B>,
275    ) -> Result<(), EncodingError>;
276}
277
278impl<B: MutableBuffer> WriteArgumentValue<B> for Argument<'_> {
279    fn write_value(
280        &self,
281        header: &mut Header,
282        encoder: &mut Encoder<B>,
283    ) -> Result<(), EncodingError> {
284        match self {
285            Self::Pid(value) | Self::Tid(value) => value.raw_koid().write_value(header, encoder),
286            Self::Line(value) | Self::Dropped(value) => value.write_value(header, encoder),
287            Self::Tag(value) | Self::File(value) | Self::Message(value) => {
288                value.write_value(header, encoder)
289            }
290            Self::Other { value, .. } => value.write_value(header, encoder),
291        }
292    }
293}
294
295impl<B: MutableBuffer> WriteArgumentValue<B> for i64 {
296    fn write_value(
297        &self,
298        header: &mut Header,
299        encoder: &mut Encoder<B>,
300    ) -> Result<(), EncodingError> {
301        header.set_type(ArgType::I64 as u8);
302        encoder.write_i64(*self)
303    }
304}
305
306impl<B: MutableBuffer> WriteArgumentValue<B> for u64 {
307    fn write_value(
308        &self,
309        header: &mut Header,
310        encoder: &mut Encoder<B>,
311    ) -> Result<(), EncodingError> {
312        header.set_type(ArgType::U64 as u8);
313        encoder.write_u64(*self)
314    }
315}
316
317impl<B: MutableBuffer> WriteArgumentValue<B> for f64 {
318    fn write_value(
319        &self,
320        header: &mut Header,
321        encoder: &mut Encoder<B>,
322    ) -> Result<(), EncodingError> {
323        header.set_type(ArgType::F64 as u8);
324        encoder.write_f64(*self)
325    }
326}
327
328impl<B: MutableBuffer> WriteArgumentValue<B> for bool {
329    fn write_value(
330        &self,
331        header: &mut Header,
332        _encoder: &mut Encoder<B>,
333    ) -> Result<(), EncodingError> {
334        header.set_type(ArgType::Bool as u8);
335        header.set_bool_val(*self);
336        Ok(())
337    }
338}
339
340impl<B: MutableBuffer> WriteArgumentValue<B> for &str {
341    fn write_value(
342        &self,
343        header: &mut Header,
344        encoder: &mut Encoder<B>,
345    ) -> Result<(), EncodingError> {
346        header.set_type(ArgType::String as u8);
347        header.set_value_ref(string_mask(self));
348        encoder.write_string(self)
349    }
350}
351
352impl<B: MutableBuffer> WriteArgumentValue<B> for String {
353    fn write_value(
354        &self,
355        header: &mut Header,
356        encoder: &mut Encoder<B>,
357    ) -> Result<(), EncodingError> {
358        self.as_str().write_value(header, encoder)
359    }
360}
361
362impl<B: MutableBuffer> WriteArgumentValue<B> for Cow<'_, str> {
363    fn write_value(
364        &self,
365        header: &mut Header,
366        encoder: &mut Encoder<B>,
367    ) -> Result<(), EncodingError> {
368        self.as_ref().write_value(header, encoder)
369    }
370}
371
372impl<B: MutableBuffer> WriteArgumentValue<B> for Value<'_> {
373    fn write_value(
374        &self,
375        header: &mut Header,
376        encoder: &mut Encoder<B>,
377    ) -> Result<(), EncodingError> {
378        match self {
379            Value::SignedInt(s) => s.write_value(header, encoder),
380            Value::UnsignedInt(u) => u.write_value(header, encoder),
381            Value::Floating(f) => f.write_value(header, encoder),
382            Value::Text(t) => t.write_value(header, encoder),
383            Value::Boolean(b) => b.write_value(header, encoder),
384        }
385    }
386}
387
388const fn string_mask(s: &str) -> u16 {
389    let len = s.len();
390    if len == 0 {
391        return 0;
392    }
393    (len as u16) | (1 << 15)
394}
395
396/// Trait implemented by types which can be written by the Encoder.
397pub trait RecordEvent {
398    /// Returns the record severity.
399    fn raw_severity(&self) -> RawSeverity;
400    /// Returns the name of the file where the record was emitted.
401    fn file(&self) -> Option<&str>;
402    /// Returns the number of the line in the file where the record was emitted.
403    fn line(&self) -> Option<u32>;
404    /// Returns the target of the record.
405    fn target(&self) -> &str;
406    /// Consumes this type and writes all the arguments.
407    fn write_arguments<B: MutableBuffer>(
408        self,
409        writer: &mut Encoder<B>,
410    ) -> Result<(), EncodingError>;
411    /// Returns the timestamp associated to this record.
412    fn timestamp(&self) -> zx::BootInstant;
413}
414
415/// Trait implemented by complete Records.
416pub trait RecordFields {
417    /// Returns the record severity.
418    fn raw_severity(&self) -> RawSeverity;
419
420    /// Returns the timestamp associated to this record.
421    fn timestamp(&self) -> zx::BootInstant;
422
423    /// Consumes this type and writes all the arguments.
424    fn write_arguments<B: MutableBuffer>(
425        self,
426        writer: &mut Encoder<B>,
427    ) -> Result<(), EncodingError>;
428}
429
430/// Arguments to create a record for testing purposes.
431pub struct TestRecord<'a> {
432    /// Severity of the log
433    pub severity: RawSeverity,
434    /// Timestamp of the test record.
435    pub timestamp: zx::BootInstant,
436    /// File that emitted the log.
437    pub file: Option<&'a str>,
438    /// Line in the file that emitted the log.
439    pub line: Option<u32>,
440    /// Additional record arguments.
441    pub record_arguments: Vec<Argument<'a>>,
442}
443
444impl TestRecord<'_> {
445    /// Creates a test record from a record.
446    pub fn from<'a>(file: &'a str, line: u32, record: &'a Record<'a>) -> TestRecord<'a> {
447        TestRecord {
448            severity: record.severity,
449            timestamp: record.timestamp,
450            file: Some(file),
451            line: Some(line),
452            record_arguments: record.arguments.clone(),
453        }
454    }
455}
456
457impl RecordEvent for TestRecord<'_> {
458    fn raw_severity(&self) -> RawSeverity {
459        self.severity
460    }
461
462    fn file(&self) -> Option<&str> {
463        self.file
464    }
465
466    fn line(&self) -> Option<u32> {
467        self.line
468    }
469
470    fn target(&self) -> &str {
471        unimplemented!("Unused at the moment");
472    }
473
474    fn timestamp(&self) -> zx::BootInstant {
475        self.timestamp
476    }
477
478    fn write_arguments<B: MutableBuffer>(
479        self,
480        writer: &mut Encoder<B>,
481    ) -> Result<(), EncodingError> {
482        for argument in self.record_arguments {
483            writer.write_argument(argument)?;
484        }
485        Ok(())
486    }
487}
488
489impl RecordFields for Record<'_> {
490    fn raw_severity(&self) -> RawSeverity {
491        self.severity
492    }
493
494    fn write_arguments<B: MutableBuffer>(
495        self,
496        writer: &mut Encoder<B>,
497    ) -> Result<(), EncodingError> {
498        for arg in self.arguments {
499            writer.write_argument(arg)?;
500        }
501        Ok(())
502    }
503
504    fn timestamp(&self) -> zx::BootInstant {
505        self.timestamp
506    }
507}
508
509#[cfg(test)]
510impl RecordFields for &Record<'_> {
511    fn raw_severity(&self) -> RawSeverity {
512        self.severity
513    }
514
515    fn write_arguments<B: MutableBuffer>(
516        self,
517        writer: &mut Encoder<B>,
518    ) -> Result<(), EncodingError> {
519        for arg in &self.arguments {
520            writer.write_argument(arg)?;
521        }
522        Ok(())
523    }
524
525    fn timestamp(&self) -> zx::BootInstant {
526        self.timestamp
527    }
528}
529
530/// Analogous to `bytes::BufMut` with some additions to be able to write at specific offsets.
531pub trait MutableBuffer {
532    /// Returns the number of total bytes this container can store. Shared memory buffers are not
533    /// expected to resize and this should return the same value during the entire lifetime of the
534    /// buffer.
535    fn capacity(&self) -> usize;
536
537    /// Returns the current position into which the next write is expected.
538    fn cursor(&self) -> usize;
539
540    /// Advance the write cursor by `n` bytes.
541    ///
542    /// # Safety
543    ///
544    /// This is marked unsafe because a malformed caller may
545    /// cause a subsequent out-of-bounds write.
546    unsafe fn advance_cursor(&mut self, n: usize);
547
548    /// Write a copy of the `src` slice into the buffer, starting at the provided offset.
549    ///
550    /// # Safety
551    ///
552    /// Implementations are not expected to bounds check the requested copy, although they may do
553    /// so and still satisfy this trait's contract.
554    unsafe fn put_slice_at(&mut self, src: &[u8], offset: usize);
555
556    /// Returns whether the buffer has sufficient remaining capacity to write an incoming value.
557    fn has_remaining(&self, num_bytes: usize) -> bool;
558
559    /// Advances the write cursor without immediately writing any bytes to the buffer. The returned
560    /// struct offers the ability to later write to the provided portion of the buffer.
561    fn put_slot(&mut self, width: usize) -> Result<WriteSlot, EncodingError> {
562        if self.has_remaining(width) {
563            let slot = WriteSlot { range: self.cursor()..(self.cursor() + width) };
564            unsafe {
565                self.advance_cursor(width);
566            }
567            Ok(slot)
568        } else {
569            Err(EncodingError::BufferTooSmall)
570        }
571    }
572
573    /// Write `src` into the provided slot that was created at a previous point in the stream.
574    fn fill_slot(&mut self, slot: WriteSlot, src: &[u8]) {
575        assert_eq!(
576            src.len(),
577            slot.range.end - slot.range.start,
578            "WriteSlots can only insert exactly-sized content into the buffer"
579        );
580        unsafe {
581            self.put_slice_at(src, slot.range.start);
582        }
583    }
584
585    /// Writes the contents of the `src` buffer to `self`, starting at `self.cursor()` and
586    /// advancing the cursor by `src.len()`.
587    ///
588    /// # Panics
589    ///
590    /// This function panics if there is not enough remaining capacity in `self`.
591    fn put_slice(&mut self, src: &[u8]) -> Result<(), EncodingError> {
592        if self.has_remaining(src.len()) {
593            unsafe {
594                self.put_slice_at(src, self.cursor());
595                self.advance_cursor(src.len());
596            }
597            Ok(())
598        } else {
599            Err(EncodingError::NoCapacity)
600        }
601    }
602
603    /// Writes an unsigned 64 bit integer to `self` in little-endian byte order.
604    ///
605    /// Advances the cursor by 8 bytes.
606    ///
607    /// # Examples
608    ///
609    /// ```
610    /// use bytes::BufMut;
611    ///
612    /// let mut buf = vec![0; 8];
613    /// buf.put_u64_le_at(0x0102030405060708, 0);
614    /// assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");
615    /// ```
616    ///
617    /// # Panics
618    ///
619    /// This function panics if there is not enough remaining capacity in `self`.
620    fn put_u64_le(&mut self, n: u64) -> Result<(), EncodingError> {
621        self.put_slice(&n.to_le_bytes())
622    }
623
624    /// Writes a signed 64 bit integer to `self` in little-endian byte order.
625    ///
626    /// The cursor position is advanced by 8.
627    ///
628    /// # Examples
629    ///
630    /// ```
631    /// use bytes::BufMut;
632    ///
633    /// let mut buf = vec![0; 8];
634    /// buf.put_i64_le_at(0x0102030405060708, 0);
635    /// assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");
636    /// ```
637    ///
638    /// # Panics
639    ///
640    /// This function panics if there is not enough remaining capacity in `self`.
641    fn put_i64_le(&mut self, n: i64) -> Result<(), EncodingError> {
642        self.put_slice(&n.to_le_bytes())
643    }
644
645    /// Writes a double-precision IEEE 754 floating point number to `self`.
646    ///
647    /// The cursor position is advanced by 8.
648    ///
649    /// # Examples
650    ///
651    /// ```
652    /// use bytes::BufMut;
653    ///
654    /// let mut buf = vec![];
655    /// buf.put_i64_le(0x0102030405060708);
656    /// assert_eq!(buf, b"\x08\x07\x06\x05\x04\x03\x02\x01");
657    /// ```
658    ///
659    /// # Panics
660    ///
661    /// This function panics if there is not enough remaining capacity in `self`.
662    fn put_f64(&mut self, n: f64) -> Result<(), EncodingError> {
663        self.put_slice(&n.to_bits().to_ne_bytes())
664    }
665}
666
667/// A region of the buffer which was advanced past and can later be filled in.
668#[must_use]
669pub struct WriteSlot {
670    range: std::ops::Range<usize>,
671}
672
673/// Wrapper for a vector that allows us to implement necessary traits.
674#[derive(Debug, Default)]
675pub struct ResizableBuffer(Vec<u8>);
676
677impl From<Vec<u8>> for ResizableBuffer {
678    fn from(buf: Vec<u8>) -> Self {
679        Self(buf)
680    }
681}
682
683impl Deref for ResizableBuffer {
684    type Target = Vec<u8>;
685
686    // Required method
687    fn deref(&self) -> &Self::Target {
688        &self.0
689    }
690}
691
692impl ResizableBuffer {
693    /// Return the inner vector.
694    pub fn into_inner(self) -> Vec<u8> {
695        self.0
696    }
697}
698
699impl MutableBuffer for Cursor<ResizableBuffer> {
700    fn capacity(&self) -> usize {
701        self.get_ref().0.len()
702    }
703
704    fn cursor(&self) -> usize {
705        self.position() as usize
706    }
707
708    fn has_remaining(&self, _num_bytes: usize) -> bool {
709        true
710    }
711
712    unsafe fn advance_cursor(&mut self, n: usize) {
713        self.set_position(self.position() + n as u64);
714    }
715
716    unsafe fn put_slice_at(&mut self, to_put: &[u8], offset: usize) {
717        let this = &mut self.get_mut().0;
718        if offset < this.len() {
719            let available = this.len() - offset;
720
721            // Copy the elements that fit into the buffer.
722            let min = available.min(to_put.len());
723            let dest = &mut this[offset..(offset + min)];
724            dest.copy_from_slice(&to_put[..min]);
725
726            // If we couldn't fit all elements, then extend the buffer with the remaining elements.
727            if available < to_put.len() {
728                this.extend_from_slice(&to_put[available..]);
729            }
730        } else {
731            // If the offset is bigger than the length, fill with zeros up to the offset and then
732            // write the slice.
733            this.resize(offset, 0);
734            this.extend_from_slice(to_put);
735        }
736    }
737}
738
739impl<T: MutableBuffer + ?Sized> MutableBuffer for &mut T {
740    fn has_remaining(&self, num_bytes: usize) -> bool {
741        (**self).has_remaining(num_bytes)
742    }
743    fn capacity(&self) -> usize {
744        (**self).capacity()
745    }
746
747    fn cursor(&self) -> usize {
748        (**self).cursor()
749    }
750
751    unsafe fn advance_cursor(&mut self, n: usize) {
752        (**self).advance_cursor(n);
753    }
754
755    unsafe fn put_slice_at(&mut self, to_put: &[u8], offset: usize) {
756        (**self).put_slice_at(to_put, offset);
757    }
758}
759
760impl<T: MutableBuffer + ?Sized> MutableBuffer for Box<T> {
761    fn has_remaining(&self, num_bytes: usize) -> bool {
762        (**self).has_remaining(num_bytes)
763    }
764    fn capacity(&self) -> usize {
765        (**self).capacity()
766    }
767
768    fn cursor(&self) -> usize {
769        (**self).cursor()
770    }
771
772    unsafe fn advance_cursor(&mut self, n: usize) {
773        (**self).advance_cursor(n);
774    }
775
776    unsafe fn put_slice_at(&mut self, to_put: &[u8], offset: usize) {
777        (**self).put_slice_at(to_put, offset);
778    }
779}
780
781impl MutableBuffer for Cursor<Vec<u8>> {
782    fn has_remaining(&self, num_bytes: usize) -> bool {
783        (self.cursor() + num_bytes) <= self.capacity()
784    }
785
786    fn capacity(&self) -> usize {
787        self.get_ref().len()
788    }
789
790    fn cursor(&self) -> usize {
791        self.position() as usize
792    }
793
794    unsafe fn advance_cursor(&mut self, n: usize) {
795        self.set_position(self.position() + n as u64);
796    }
797
798    unsafe fn put_slice_at(&mut self, to_put: &[u8], offset: usize) {
799        let dest = &mut self.get_mut()[offset..(offset + to_put.len())];
800        dest.copy_from_slice(to_put);
801    }
802}
803
804impl MutableBuffer for Cursor<&mut [u8]> {
805    fn has_remaining(&self, num_bytes: usize) -> bool {
806        (self.cursor() + num_bytes) <= self.capacity()
807    }
808
809    fn capacity(&self) -> usize {
810        self.get_ref().len()
811    }
812
813    fn cursor(&self) -> usize {
814        self.position() as usize
815    }
816
817    unsafe fn advance_cursor(&mut self, n: usize) {
818        self.set_position(self.position() + n as u64);
819    }
820
821    unsafe fn put_slice_at(&mut self, to_put: &[u8], offset: usize) {
822        let dest = &mut self.get_mut()[offset..(offset + to_put.len())];
823        dest.copy_from_slice(to_put);
824    }
825}
826
827impl<const N: usize> MutableBuffer for Cursor<[u8; N]> {
828    fn has_remaining(&self, num_bytes: usize) -> bool {
829        (self.cursor() + num_bytes) <= self.capacity()
830    }
831    fn capacity(&self) -> usize {
832        self.get_ref().len()
833    }
834
835    fn cursor(&self) -> usize {
836        self.position() as usize
837    }
838
839    unsafe fn advance_cursor(&mut self, n: usize) {
840        self.set_position(self.position() + n as u64);
841    }
842
843    unsafe fn put_slice_at(&mut self, to_put: &[u8], offset: usize) {
844        let dest = &mut self.get_mut()[offset..(offset + to_put.len())];
845        dest.copy_from_slice(to_put);
846    }
847}
848
849/// An error that occurred while encoding data to the stream format.
850#[derive(Debug, Error)]
851pub enum EncodingError {
852    /// The provided buffer is too small.
853    #[error("buffer is too small")]
854    BufferTooSmall,
855
856    /// We attempted to encode values which are not yet supported by this implementation of
857    /// the Fuchsia Tracing format.
858    #[error("unsupported value type")]
859    Unsupported,
860
861    /// We attempted to write to a buffer with no remaining capacity.
862    #[error("the buffer has no remaining capacity")]
863    NoCapacity,
864
865    /// Some other error happened. Useful for integrating with this crate, but providing custom
866    /// errors.
867    #[error(transparent)]
868    Other(Box<dyn std::error::Error + Send + Sync>),
869}
870
871impl EncodingError {
872    /// Treat a custom error as an encoding error.
873    pub fn other<E>(err: E) -> Self
874    where
875        E: std::error::Error + Send + Sync + 'static,
876    {
877        Self::Other(err.into())
878    }
879}
880
881impl From<TryFromSliceError> for EncodingError {
882    fn from(_: TryFromSliceError) -> Self {
883        EncodingError::BufferTooSmall
884    }
885}
886
887/// Adds `count` to the dropped count for the message.  Returns `true` if successful.
888pub fn add_dropped_count(message: &mut Vec<u8>, count: u64) -> bool {
889    const DROPPED_HEADER_SIZE_WORDS: u16 = 4; // Header (1), name (2), value (1)
890    const DROPPED_HEADER: Header = Header(
891        4                                                     // arg type U64
892        | (DROPPED_HEADER_SIZE_WORDS as u64) << 4             // size words
893        | (string_mask(constants::NUM_DROPPED) as u64) << 16, // string ref
894    );
895
896    if message.len() < 16 {
897        return false;
898    }
899
900    // See if the message already has a dropped argument.
901    let mut argument = &mut message[16..];
902    while !argument.is_empty() {
903        let Ok((header, _)) = Header::read_from_prefix(argument) else {
904            return false;
905        };
906        let arg_len = header.size_words() as usize * 8;
907        if arg_len == 0 || arg_len > argument.len() {
908            return false;
909        }
910        if header.0 == DROPPED_HEADER.0
911            && &argument[8..8 + constants::NUM_DROPPED.len()] == constants::NUM_DROPPED.as_bytes()
912        {
913            let value = u64::mut_from_bytes(&mut argument[24..32]).unwrap();
914            *value = value.saturating_add(count);
915            return true;
916        }
917        argument = &mut argument[arg_len..];
918    }
919
920    let message_header = Header::mut_from_bytes(&mut message[..8]).unwrap();
921    let new_size = message_header.size_words() + DROPPED_HEADER_SIZE_WORDS;
922    if new_size > MAX_SIZE_WORDS {
923        return false;
924    }
925    message_header.set_size_words(new_size);
926
927    // Append the dropped argument.
928    message.extend(DROPPED_HEADER.0.as_bytes());
929    message.extend(constants::NUM_DROPPED.as_bytes());
930    message.extend(std::iter::repeat_n(0, 16 - constants::NUM_DROPPED.len()));
931    message.extend(count.as_bytes());
932
933    true
934}
935
936#[cfg(test)]
937mod tests {
938    use super::*;
939    use crate::parse::parse_record;
940
941    #[fuchsia::test]
942    fn build_basic_record() {
943        let mut encoder = Encoder::new(Cursor::new([0u8; 1024]), EncoderOpts::default());
944        encoder
945            .write_event(WriteEventParams::<_, &str, _> {
946                event: TestRecord {
947                    severity: Severity::Info.into_primitive(),
948                    timestamp: zx::BootInstant::from_nanos(12345),
949                    file: None,
950                    line: None,
951                    record_arguments: vec![],
952                },
953                tags: &[],
954                metatags: std::iter::empty(),
955                pid: zx::Koid::from_raw(0),
956                tid: zx::Koid::from_raw(0),
957                dropped: 0,
958            })
959            .expect("wrote event");
960        let (record, _) = parse_record(encoder.inner().get_ref()).expect("wrote valid record");
961        assert_eq!(
962            record,
963            Record {
964                timestamp: zx::BootInstant::from_nanos(12345),
965                severity: Severity::Info.into_primitive(),
966                arguments: vec![
967                    Argument::pid(zx::Koid::from_raw(0)),
968                    Argument::tid(zx::Koid::from_raw(0)),
969                ]
970            }
971        );
972    }
973
974    #[fuchsia::test]
975    fn build_records_with_location() {
976        let mut encoder = Encoder::new(Cursor::new([0u8; 1024]), EncoderOpts::default());
977        encoder
978            .write_event(WriteEventParams::<_, &str, _> {
979                event: TestRecord {
980                    severity: Severity::Error.into_primitive(),
981                    timestamp: zx::BootInstant::from_nanos(12345),
982                    file: Some("foo.rs"),
983                    line: Some(10),
984                    record_arguments: vec![],
985                },
986                tags: &[],
987                metatags: std::iter::empty(),
988                pid: zx::Koid::from_raw(0),
989                tid: zx::Koid::from_raw(0),
990                dropped: 0,
991            })
992            .expect("wrote event");
993        let (record, _) = parse_record(encoder.inner().get_ref()).expect("wrote valid record");
994        assert_eq!(
995            record,
996            Record {
997                timestamp: zx::BootInstant::from_nanos(12345),
998                severity: Severity::Error.into_primitive(),
999                arguments: vec![
1000                    Argument::pid(zx::Koid::from_raw(0)),
1001                    Argument::tid(zx::Koid::from_raw(0)),
1002                    Argument::file("foo.rs"),
1003                    Argument::line(10),
1004                ]
1005            }
1006        );
1007    }
1008
1009    #[fuchsia::test]
1010    fn build_record_with_dropped_count() {
1011        let mut encoder = Encoder::new(Cursor::new([0u8; 1024]), EncoderOpts::default());
1012        encoder
1013            .write_event(WriteEventParams::<_, &str, _> {
1014                event: TestRecord {
1015                    severity: Severity::Warn.into_primitive(),
1016                    timestamp: zx::BootInstant::from_nanos(12345),
1017                    file: None,
1018                    line: None,
1019                    record_arguments: vec![],
1020                },
1021                tags: &[],
1022                metatags: std::iter::empty(),
1023                pid: zx::Koid::from_raw(0),
1024                tid: zx::Koid::from_raw(0),
1025                dropped: 7,
1026            })
1027            .expect("wrote event");
1028        let (record, _) = parse_record(encoder.inner().get_ref()).expect("wrote valid record");
1029        assert_eq!(
1030            record,
1031            Record {
1032                timestamp: zx::BootInstant::from_nanos(12345),
1033                severity: Severity::Warn.into_primitive(),
1034                arguments: vec![
1035                    Argument::pid(zx::Koid::from_raw(0)),
1036                    Argument::tid(zx::Koid::from_raw(0)),
1037                    Argument::dropped(7),
1038                ]
1039            }
1040        );
1041    }
1042
1043    #[test]
1044    fn resizable_vec_mutable_buffer() {
1045        // Putting a slice at offset=len is equivalent to concatenating.
1046        let mut vec = Cursor::new(ResizableBuffer(vec![1u8, 2, 3]));
1047        unsafe {
1048            vec.put_slice_at(&[4, 5, 6], 3);
1049        }
1050        assert_eq!(vec.get_ref().0, vec![1, 2, 3, 4, 5, 6]);
1051
1052        // Putting a slice at an offset inside the buffer, is equivalent to replacing the items
1053        // there.
1054        let mut vec = Cursor::new(ResizableBuffer(vec![1, 3, 7, 9, 11, 13, 15]));
1055        unsafe {
1056            vec.put_slice_at(&[2, 4, 6], 2);
1057        }
1058        assert_eq!(vec.get_ref().0, vec![1, 3, 2, 4, 6, 13, 15]);
1059
1060        // Putting a slice at an index in range replaces all the items and extends if needed.
1061        let mut vec = Cursor::new(ResizableBuffer(vec![1, 2, 3]));
1062        unsafe {
1063            vec.put_slice_at(&[4, 5, 6, 7], 0);
1064        }
1065        assert_eq!(vec.get_ref().0, vec![4, 5, 6, 7]);
1066
1067        // Putting a slice at an offset beyond the buffer, fills with zeros the items in between.
1068        let mut vec = Cursor::new(ResizableBuffer(vec![1, 2, 3]));
1069        unsafe {
1070            vec.put_slice_at(&[4, 5, 6], 5);
1071        }
1072        assert_eq!(vec.get_ref().0, vec![1, 2, 3, 0, 0, 4, 5, 6]);
1073    }
1074
1075    #[test]
1076    fn add_dropped_count_to_existing_count() {
1077        const INITIAL_DROPPED: u64 = 7;
1078        const EXTRA_DROPPED: u64 = 53;
1079
1080        let mut encoder = Encoder::new(Cursor::new(vec![0; 256]), EncoderOpts::default());
1081        encoder
1082            .write_event(WriteEventParams::<_, &str, _> {
1083                event: TestRecord {
1084                    severity: Severity::Error.into_primitive(),
1085                    timestamp: zx::BootInstant::from_nanos(12345),
1086                    file: None,
1087                    line: Some(123),
1088                    record_arguments: vec![],
1089                },
1090                tags: &[],
1091                metatags: std::iter::empty(),
1092                pid: zx::Koid::from_raw(0),
1093                tid: zx::Koid::from_raw(0),
1094                dropped: INITIAL_DROPPED,
1095            })
1096            .expect("wrote event");
1097        let cursor = encoder.take();
1098        let position = cursor.position();
1099        let mut buffer = cursor.into_inner();
1100        buffer.truncate(position as usize);
1101        assert!(add_dropped_count(&mut buffer, EXTRA_DROPPED));
1102        let (record, _) = parse_record(&buffer).expect("wrote valid record");
1103        assert_eq!(
1104            record,
1105            Record {
1106                timestamp: zx::BootInstant::from_nanos(12345),
1107                severity: Severity::Error.into_primitive(),
1108                arguments: vec![
1109                    Argument::pid(zx::Koid::from_raw(0)),
1110                    Argument::tid(zx::Koid::from_raw(0)),
1111                    Argument::dropped(INITIAL_DROPPED + EXTRA_DROPPED),
1112                    Argument::Line(123),
1113                ]
1114            }
1115        );
1116    }
1117
1118    #[test]
1119    fn add_dropped_count_when_none_exists() {
1120        const DROPPED: u64 = 53;
1121
1122        let mut encoder = Encoder::new(Cursor::new(vec![0; 256]), EncoderOpts::default());
1123        encoder
1124            .write_event(WriteEventParams::<_, &str, _> {
1125                event: TestRecord {
1126                    severity: Severity::Error.into_primitive(),
1127                    timestamp: zx::BootInstant::from_nanos(12345),
1128                    file: None,
1129                    line: Some(123),
1130                    record_arguments: vec![],
1131                },
1132                tags: &[],
1133                metatags: std::iter::empty(),
1134                pid: zx::Koid::from_raw(0),
1135                tid: zx::Koid::from_raw(0),
1136                dropped: 0,
1137            })
1138            .expect("wrote event");
1139        let cursor = encoder.take();
1140        let position = cursor.position();
1141        let mut buffer = cursor.into_inner();
1142        buffer.truncate(position as usize);
1143        assert!(add_dropped_count(&mut buffer, DROPPED));
1144        let (record, _) = parse_record(&buffer).expect("wrote valid record");
1145        assert_eq!(
1146            record,
1147            Record {
1148                timestamp: zx::BootInstant::from_nanos(12345),
1149                severity: Severity::Error.into_primitive(),
1150                arguments: vec![
1151                    Argument::pid(zx::Koid::from_raw(0)),
1152                    Argument::tid(zx::Koid::from_raw(0)),
1153                    Argument::Line(123),
1154                    Argument::dropped(DROPPED),
1155                ]
1156            }
1157        );
1158    }
1159
1160    #[test]
1161    fn add_dropped_count_when_just_enough_room() {
1162        const DROPPED: u64 = 53;
1163
1164        let mut encoder =
1165            Encoder::new(Cursor::new(vec![0; MAX_SIZE_WORDS as usize * 8]), EncoderOpts::default());
1166        // We want the argument to be just big enough so that there is only just enough room for
1167        // the dropped count:
1168        //
1169        //   Header    :    1
1170        //   Timestamp :    1
1171        //   Pid       :    3
1172        //   Tid       :    3
1173        //   Line      :    3
1174        //   Foo       : 4080
1175        //   Dropped   :    4
1176        //               ====
1177        //               4095
1178        let foo_arg = Argument::new("foo", String::from_iter(std::iter::repeat_n('x', 4078 * 8)));
1179        encoder
1180            .write_event(WriteEventParams::<_, &str, _> {
1181                event: TestRecord {
1182                    severity: Severity::Error.into_primitive(),
1183                    timestamp: zx::BootInstant::from_nanos(12345),
1184                    file: None,
1185                    line: Some(123),
1186                    record_arguments: vec![foo_arg.clone()],
1187                },
1188                tags: &[],
1189                metatags: std::iter::empty(),
1190                pid: zx::Koid::from_raw(0),
1191                tid: zx::Koid::from_raw(0),
1192                dropped: 0,
1193            })
1194            .expect("wrote event");
1195        let cursor = encoder.take();
1196        let position = cursor.position();
1197        let mut buffer = cursor.into_inner();
1198        buffer.truncate(position as usize);
1199        assert!(add_dropped_count(&mut buffer, DROPPED));
1200        let (record, _) = parse_record(&buffer).expect("wrote valid record");
1201        assert_eq!(
1202            record,
1203            Record {
1204                timestamp: zx::BootInstant::from_nanos(12345),
1205                severity: Severity::Error.into_primitive(),
1206                arguments: vec![
1207                    Argument::pid(zx::Koid::from_raw(0)),
1208                    Argument::tid(zx::Koid::from_raw(0)),
1209                    Argument::Line(123),
1210                    foo_arg,
1211                    Argument::dropped(DROPPED),
1212                ]
1213            }
1214        );
1215    }
1216
1217    #[test]
1218    fn add_dropped_count_invalid_message() {
1219        // Message too small.
1220        assert!(!add_dropped_count(&mut vec![1, 2, 3], 5));
1221
1222        // Argument too small.
1223        assert!(!add_dropped_count(&mut vec![0; 17], 5));
1224
1225        // Zero argument len.
1226        assert!(!add_dropped_count(&mut vec![0; 24], 5));
1227
1228        // Argument too big.
1229        let mut message = vec![0; 16];
1230        let mut arg_header = Header(0);
1231        arg_header.set_size_words(2);
1232        message.extend(arg_header.0.as_bytes());
1233        assert!(!add_dropped_count(&mut message, 5));
1234
1235        // Message too too big to accept another argument.
1236        let mut message = Vec::new();
1237        let mut header = Header(0);
1238        header.set_size_words(MAX_SIZE_WORDS);
1239        message.extend(header.0.as_bytes());
1240        message.extend([0; 8]); // timestamp
1241        let mut arg_header = Header(0);
1242        arg_header.set_size_words(4093);
1243        message.extend(arg_header.0.as_bytes());
1244        message.resize(4095 * 8, 0);
1245        assert!(!add_dropped_count(&mut message, 5));
1246    }
1247}
diagnostics_log_encoding/encode.rs

diagnostics_log_encoding/
encode.rs
