utrace

Go to the documentation of this file.

// vim:set ft=cpp: -*- Mode: C++ -*-
/*
 * Copyright (C) 2026 Kernkonzept GmbH.
 * Author(s): Martin Decky <martin.decky@kernkonzept.com>
 *
 * License: see LICENSE.spdx (in this directory or the directories above)
 */

 
#pragma once
 
#include <version>
#include <bit>
#include <string>
#include <optional>
#include <l4/sys/ktrace_events.h>
#include <l4/sys/consts.h>
#include <l4/sys/capability>
#include <l4/sys/debugger>
#include <l4/utrace/ring_buffer>
 
#if defined(__cpp_lib_generator)
#include <generator>
#else
#include <vector>
#endif
 
namespace utrace {

static constexpr size_t log_name_buffer_size = 64U;

static constexpr size_t object_name_buffer_size = 16U;

class Tracebuffer
{
public:
  using Sequence = L4_ktrace_t__Mword;
  using Item = l4_tracebuffer_entry_t;
 
  using Buffer = Ring_buffer_consumer<Sequence, Item, &Item::_number>;
  using Drop_policy = Buffer::Drop_policy;
  using Status = Buffer::Status;
  using Slot = Buffer::Slot;
 
  using Id = unsigned long;
 
  static_assert(sizeof(Status) <= L4_PAGESIZE);

  struct Index_desc
  {
    unsigned index;
    std::string name;
    std::string shortname;
  };

  static void validate();

  static unsigned version();

  static std::endian endianness();

  static std::optional<Index_desc> index(unsigned idx);

#if defined(__cpp_lib_generator)
  static std::generator<Index_desc> indexes();
#else
  static std::vector<Index_desc> indexes();
#endif

  static Tracebuffer &instance();

  size_t items() const;

  size_t dequeue(Item *items, size_t capacity, size_t burst, Drop_policy policy,
                 Sequence *drops = nullptr);

  static std::optional<Id> ptr_to_id(void *const ptr);

  static std::optional<std::string> id_to_name(Id const id);
 
private:
  static constexpr unsigned tracebuffer_version = 0;
  static constexpr size_t yield_cycles = 100;

  class Factory
  {
  public:
    static Factory &instance();

    Status &status();

    Slot *slots();
 
  private:
    Factory();

    ~Factory();

    static l4_fpage_t reserve(size_t size);

    static Status *map_status(l4_fpage_t fpage);

    static Slot *map_slots(l4_fpage_t fpage, size_t items);
 
    l4_fpage_t _fpage_status;
    l4_fpage_t _fpage_slots;
 
    Status *_status;
    Slot *_slots;
  };
 
  Tracebuffer() = delete;

  Tracebuffer(Factory &factory);
 
  static L4::Cap<L4::Debugger> _jdb;
  Buffer _buffer;
};
 
}; // namespace utrace