| // Copyright 2025 The Fuchsia Authors. All rights reserved. | |
| // Use of this source code is governed by a BSD-style license that can be | |
| // found in the LICENSE file. | |
| #ifndef SRC_LIB_DIAGNOSTICS_LOG_MESSAGE_RUST_CPP_LOG_DECODER_LOG_DECODER_H_ | |
| #define SRC_LIB_DIAGNOSTICS_LOG_MESSAGE_RUST_CPP_LOG_DECODER_LOG_DECODER_H_ | |
| // Warning: | |
| // This file was autogenerated by cbindgen. | |
| // Do not modify this file manually. | |
| #include <zircon/types.h> | |
| #include <cstdarg> | |
| #include <cstdint> | |
| #include <cstdlib> | |
| #include <new> | |
| #include <ostream> | |
| struct Bump; | |
| /// A stateful parser that reconstructs fully attributed `LogsData` records from a stream of | |
| /// FXT log packets. | |
| /// | |
| /// # Background & Architecture | |
| /// | |
| /// In the Fuchsia Trace Format (FXT) structured logging protocol, log attribution metadata is | |
| /// separated from the actual log payload to optimize transmission overhead. Instead of repeating | |
| /// the full moniker and component URL on every log record, the system transmits two distinct | |
| /// types of records: | |
| /// | |
| /// 1. **Manifest/Control Records**: Sent with the `LOG_CONTROL_BIT` set. These records map a | |
| /// numeric base tag ID to component identity metadata (`ExtendedMoniker` and URL). | |
| /// 2. **Legacy Log Records**: Contain the message content, severity, timestamp, and | |
| /// arguments, along with a tag ID indicating which component produced the log. | |
| /// | |
| /// # Stateful Parsing | |
| /// | |
| /// `MessageParser` maintains an internal `tag_map` to track the active association between | |
| /// numeric tag IDs and their component identity (`ExtendedMetadata`). | |
| /// | |
| /// - When parsing a manifest record (`is_control == true`), `MessageParser` updates its state | |
| /// mapping for the derived base tag. If the record also reports rolled out (dropped) logs, a | |
| /// `LogsData` payload representing those dropped logs is returned. Otherwise, it registers | |
| /// the attribution mapping and returns `Ok((None, remaining))`. | |
| /// - When parsing a legacy log record (`is_control == false`), `MessageParser` resolves the | |
| /// record's tag to retrieve the component's identity from the internal mapping, constructing | |
| /// a fully attributed `LogsData` containing the correct component moniker and URL. | |
| struct MessageParser; | |
| /// Array for FFI purposes between C++ and Rust. | |
| /// If len is 0, ptr is allowed to be nullptr, | |
| /// otherwise, ptr must be valid. | |
| template <typename T> | |
| struct CppArray { | |
| /// Number of elements in the array | |
| uintptr_t len; | |
| /// Pointer to the first element in the array, | |
| /// may be null in the case of a 0 length array, | |
| /// but is not guaranteed to always be null of | |
| /// len is 0. | |
| const T *ptr; | |
| }; | |
| /// Represents a UTF-8 encoded string for FFI purposes. | |
| /// This is equivalent to a CppArray<u8> as it is | |
| /// #[repr(transparent)], but with the additional | |
| /// constraint that the contents of the array | |
| /// is a valid UTF-8 string. | |
| using CppString = CppArray<uint8_t>; | |
| /// Represents a value in a key-value pair for FFI purposes between C++ and Rust. | |
| struct CppValue { | |
| enum class Tag : uint8_t { | |
| CPP_VALUE_SIGNED_INT, | |
| CPP_VALUE_UNSIGNED_INT, | |
| CPP_VALUE_FLOATING, | |
| CPP_VALUE_BOOLEAN, | |
| CPP_VALUE_TEXT, | |
| }; | |
| struct CppValue_SignedInt_Body { | |
| int64_t _0; | |
| }; | |
| struct CppValue_UnsignedInt_Body { | |
| uint64_t _0; | |
| }; | |
| struct CppValue_Floating_Body { | |
| double _0; | |
| }; | |
| struct CppValue_Boolean_Body { | |
| bool _0; | |
| }; | |
| struct CppValue_Text_Body { | |
| CppString _0; | |
| }; | |
| Tag tag; | |
| union { | |
| CppValue_SignedInt_Body SIGNED_INT; | |
| CppValue_UnsignedInt_Body UNSIGNED_INT; | |
| CppValue_Floating_Body FLOATING; | |
| CppValue_Boolean_Body BOOLEAN; | |
| CppValue_Text_Body TEXT; | |
| }; | |
| }; | |
| /// Represents a key-value pair for FFI purposes between C++ and Rust. | |
| struct CppKeyValue { | |
| CppString key; | |
| CppValue value; | |
| }; | |
| /// Log message representation for FFI with C++. | |
| /// | |
| /// # Lifetime and Borrowing | |
| /// Strings within `LogMessage` (`tags`, `message`, and string keys/values in `kvps`) | |
| /// borrow directly from the incoming encoded message buffer (`bytes`) when possible, | |
| /// or from the provided arena allocator (`Bump`). | |
| /// Consequently, the incoming message buffer MUST remain valid and unmodified | |
| /// for at least as long as the `LogMessage` is in use. | |
| struct LogMessage { | |
| /// Severity of a log message. | |
| uint8_t severity; | |
| /// Tags in a log message, guaranteed to be non-null. | |
| CppArray<CppString> tags; | |
| /// Process ID from a LogMessage, or 0 if unknown | |
| uint64_t pid; | |
| /// Thread ID from a LogMessage, or 0 if unknown | |
| uint64_t tid; | |
| /// Number of dropped log messages. | |
| uint64_t dropped; | |
| /// The UTF-encoded log message, guaranteed to be valid UTF-8. | |
| CppString message; | |
| /// Source file where the log was emitted, if any. | |
| CppString file; | |
| /// Source line where the log was emitted, if any. | |
| uint64_t line; | |
| /// Last segment of the moniker, used as a default log tag if needed. | |
| CppString moniker_tag; | |
| /// Key-value pairs in a log message. | |
| CppArray<CppKeyValue> kvps; | |
| /// Timestamp on the boot timeline of the log message, | |
| /// in nanoseconds. | |
| int64_t timestamp; | |
| }; | |
| /// Like `Box` except that it can be moved when there are live pointers. | |
| template <typename T> | |
| struct AliasableBox { | |
| T *_0; | |
| }; | |
| /// LogMessages struct containing log messages | |
| /// It is created by calling fuchsia_decode_log_messages_to_struct, | |
| /// and freed by calling fuchsia_free_log_messages. | |
| /// Log messages contain embedded pointers to the bytes from | |
| /// which they were created, so the memory referred to | |
| /// by the LogMessages must not be modified or free'd until | |
| /// the LogMessages are free'd. | |
| struct LogMessages { | |
| CppArray<const LogMessage *> messages; | |
| const char *error_str; | |
| AliasableBox<Bump> allocator; | |
| }; | |
| extern "C" { | |
| extern "C" MessageParser *fuchsia_new_message_parser(); | |
| /// # Safety | |
| /// | |
| /// This should only be called with a pointer obtained through | |
| /// `fuchsia_new_message_parser`. | |
| extern "C" void fuchsia_free_message_parser(MessageParser *parser); | |
| /// # Safety | |
| /// | |
| /// - This function is NOT thread-safe. The caller must ensure that it is not called | |
| /// concurrently with the same `parser` pointer. | |
| /// | |
| /// Same as for `std::slice::from_raw_parts`. Summarizing in terms of this API: | |
| /// | |
| /// - `msg` must be valid for reads for `size`, and it must be properly aligned. | |
| /// - `msg` must point to `size` consecutive u8 values. | |
| /// - The `size` of the slice must be no larger than `isize::MAX`, and adding | |
| /// that size to data must not "wrap around" the address space. See the safety | |
| /// documentation of pointer::offset. | |
| /// If identity is provided, it must contain a valid moniker and URL. | |
| /// | |
| /// The returned LogMessages must be free'd with fuchsia_free_log_messages(log_messages). Free'ing | |
| /// the LogMessages struct frees the bump allocator itself (and everything allocated from it). | |
| extern "C" LogMessages fuchsia_decode_log_messages_to_struct(const uint8_t *msg, uintptr_t size, | |
| bool expect_extended_attribution, | |
| MessageParser *parser); | |
| /// # Safety | |
| /// | |
| /// This should only be called with `input` obtained through | |
| /// `fuchsia_decode_log_messages_to_struct`. | |
| extern "C" void fuchsia_free_log_messages(LogMessages input); | |
| } // extern "C" | |
| #endif // SRC_LIB_DIAGNOSTICS_LOG_MESSAGE_RUST_CPP_LOG_DECODER_LOG_DECODER_H_ |