blob: d38fbc4ea7fc02eba0bb3e7d695f9634d7c65c2e [file]
// 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_