debug_ipc

Namespaces

Enumerations

enum AutomationOperandKind : uint32_t
Name Value Comments
kZero 0

This type is just used as a default value. It outputs zero when evaluated.
kRegister 1

A kRegister takes a register index (in index_), and outputs the 64 bit value stored in that
register.
kConstant 2

A kConstant takes a uint32_t constant value (in value_), and outputs that value extended to a
uint64_t.
kStackSlot 3

A kStackSlot takes an offset into the stack (in index_), and returns the 64 bit value at that
stack location.
kRegisterTimesConstant 4

A kRegisterTimesConstant takes a register index (in index_) and a constant value (in value_),
and outputs the value of that register multiplied by the value.
kIndirectUInt32 5

a kIndirectUInt32 takes a register index (in index_) and a constant offset (in value_), and
outputs the 32 bit value at *(register + offset)
kIndirectUInt64 6

a kIndirectUInt64 takes a register index (in index_) and a constant offset (in value_), and
outputs the 64 bit value at *(register + offset)
kIndirectUInt32Loop 7

a kIndirectUInt32Loop is a special operand that is only valid for kLoopLoadMemory instructions.
It takes a constant offset (in value_), and outputs the 32 bit value at
*(address + cur_struct + offset)
kIndirectUInt64Loop 8

a kIndirectUInt64Loop is a special operand that is only valid for kLoopLoadMemory instructions.
It takes a constant offset (in value_), and outputs the 64 bit value at
*(address + cur_struct + offset)
kStoredValue 9

A kStoredValue takes a slot in the list of stored values (in index_), and outputs the 64 bit
value stored in that slot.

Defined at line 18 of file ../../src/developer/debug/ipc/automation_instruction.h

enum class ExceptionType : uint32_t
Name Value Comments
kNone 0

No current exception, used as placeholder or to indicate not set.
kGeneral 1

Zircon defines this as a sort of catch-all exception.
kPageFault 2

The usual band of execution traps.
kUndefinedInstruction 3

The usual band of execution traps.
kUnalignedAccess 4

The usual band of execution traps.
kPolicyError 5

Indicates the process was killed due to misusing a syscall, e.g. passing a bad handle.
kThreadStarting 6

Synthetic exeptions used by zircon to communicated with the debugger. The debug agent generally
shouldn't pass these on, but we should recognize them at least.
kThreadExiting 7

Synthetic exeptions used by zircon to communicated with the debugger. The debug agent generally
shouldn't pass these on, but we should recognize them at least.
kProcessStarting 8

Synthetic exeptions used by zircon to communicated with the debugger. The debug agent generally
shouldn't pass these on, but we should recognize them at least.
kHardwareBreakpoint 9

Hardware breakpoints are issues by the CPU via debug registers.
kWatchpoint 10

HW exceptions triggered on memory read/write.
kSingleStep 11

Single-step completion issued by the CPU.
kSoftwareBreakpoint 12

Software breakpoint. This will be issued when a breakpoint is hit and when the debugged program
manually issues a breakpoint instruction.
kSynthetic 13

Indicates this exception is not a real CPU exception but was generated internally for the
purposes of sending a stop notification. The frontend uses this value when the thread didn't
actually do anything, but the should be updated as if it hit an exception.
kUnknown 14

For exception codes the debugger doesn't recognize.
kLast 15

Not an actual exception type, for range checking.

Defined at line 27 of file ../../src/developer/debug/ipc/records.h

enum class ExceptionStrategy : uint32_t
Name Value Comments
kNone 0

No current exception, used as placeholder or to indicate not set.
kFirstChance 1

Indicates that the debugger only gets the first chance to handle the
exception, before the thread and process-level handlers.
kSecondChance 2

Indicates that the debugger also gets a second first chance to handle
the exception after process-level handler.
kLast 3

Not an actual exception strategy, for range checking.

Exception handling strategy.

Defined at line 75 of file ../../src/developer/debug/ipc/records.h

enum AutomationConditionKind : uint32_t
Name Value Comments
kFalse 0

This type is just used as a default value. It always returns false.
kEquals 1

A kEquals condition takes an operand and a uint64 constant.
It is true when operand == constant.
kNotEquals 2

A kNotEquals condition takes an operand and a uint64 constant.
It is true when operand != constant.
kMaskAndEquals 3

A kMaskAndEquals condition takes an operand, a uint64 mask, and a uint64 constant.
It is true when (operand
&
mask) == constant.
kMaskAndNotEquals 4

A kMaskAndNotEquals condition takes an operand, a uint64 mask, and a uint64 constant.
It is true when (operand
&
mask) != constant.

Defined at line 154 of file ../../src/developer/debug/ipc/automation_instruction.h

enum class TaskType : uint32_t
Name Value
kUnknown 0
kProcess 1
kJob 2

Defined at line 161 of file ../../src/developer/debug/ipc/records.h

enum AutomationInstructionKind : uint32_t
Name Value Comments
kNop 0

This type is just used as a default value. Has no effect if sent.
kLoadMemory 1

A kLoadMemory instruction takes two Operands:
address (in address_) is the address of some memory.
length (in length_) is the number of bytes to load from that memory.
It preloads length bytes from the memory at address.
It also takes a vector of conditions and only executes if it has no false conditions.
kLoopLoadMemory 2

A kLoopLoadMemory instruction takes four Operands and a uint32_t:
address (in address_) is the address of an array of structs.
length (in length_) is the number of structs in the array.
struct_pointer_offset (in extra_1_) is the offset in the struct to the pointer to load from.
struct_length_offset (in extra_2_) is the offset to the length of the memory to load.
item_size (in value_) is the uint32_t size of the structs in the array in bytes.
First it preloads the array of structs (loading length * item_size bytes from address_).
Next it iterates through each of the structs, preloading the number of bytes specified at
address[index] + struct_size_offset from the address at address[index] +
struct_pointer_offset
It also takes a vector of conditions and only executes if it has no false conditions.
kComputeAndStore 3

A kComputeAndStore instruction takes one Operand and a uint32_t:
value (in extra_1_) is the operand to be stored.
slot_index (in value_) is the slot index to store the result at.
It stores the value of the operand in that slot to be used by later operands. Nothing is
preloaded from this command.
It also takes a vector of conditions and only executes if it has no false conditions.
kClearStoredValues 4

A kClearStoredValues instruction takes no Operands.
It clears all values stored by kComputeAndStore commands.
It also takes a vector of conditions and only executes if it has no false conditions.

Defined at line 224 of file ../../src/developer/debug/ipc/automation_instruction.h

enum class Stop : uint32_t
Name Value Comments
kNone 0

Don't stop anything but accumulate hit counts.
kThread 1

Stop only the thread that hit the breakpoint.
kProcess 2

Stop all threads of the process that hit the breakpoint.
kAll 3

Stop all threads of all processes attached to the debugger.

What threads to stop when the breakpoint is hit. These are ordered such that the integer values

increase for larger scopes.

Defined at line 433 of file ../../src/developer/debug/ipc/records.h

enum class BreakpointType : uint32_t
Name Value Comments
kSoftware 0

Software code execution.
kHardware 1

Hardware code execution.
kReadWrite 2

Hardware read/write.
kWrite 3

Hardware write.
kLast 4

Not a real type, end marker.

NOTE: read-only could be added in the future as arm64 supports them. They're not added today as

x64 does not support them and presenting a common platform is cleaner for now.

Defined at line 442 of file ../../src/developer/debug/ipc/records.h

Records

Functions

  • bool operator== (const Module & a, const Module & b)

    Comparison function for checking for changes in the list.

    Defined at line 14 of file ../../src/developer/debug/debug_agent/module_list.cc

  • bool FilterMatches (const Filter & filter, const std::string & process_name, const std::vector<ComponentInfo> & components)

    Matches the filter with the given process_name or any of the components given in |components|,

    ignoring the job_koid.

    Defined at line 42 of file ../../src/developer/debug/ipc/filter_utils.cc

  • const Filter * GetFilterForId (const std::vector<const Filter *> & filters, const Filter::Identifier & id)

    Returns the filter from the given |filters| that has |id|.

    Defined at line 70 of file ../../src/developer/debug/ipc/filter_utils.cc

  • unwinder::Frame::Trust ConvertTrust (debug_ipc::StackFrame::Trust trust)

    Defined at line 14 of file ../../src/developer/debug/ipc/unwinder_support.cc

  • debug_ipc::StackFrame::Trust ConvertTrust (unwinder::Frame::Trust trust)

    Defined at line 37 of file ../../src/developer/debug/ipc/unwinder_support.cc

  • template <typename MsgType>
    bool Deserialize (std::vector<char> data, MsgType * msg, uint32_t * transaction_id, uint32_t version)

    MsgType can be either Request or Reply types.

    Defined at line 47 of file ../../src/developer/debug/ipc/message_reader.h

  • template <typename NotificationType>
    bool Deserialize (std::vector<char> data, NotificationType * notify, uint32_t version)

    Defined at line 58 of file ../../src/developer/debug/ipc/message_reader.h

  • unwinder::Registers ConvertRegisters (debug::Arch arch, const std::vector<debug::RegisterValue> & regs)

    Defined at line 60 of file ../../src/developer/debug/ipc/unwinder_support.cc

  • uint32_t GenerateFilterIdValue ()

    Shared function for clients to generate unique values for their filters.

    Defined at line 77 of file ../../src/developer/debug/ipc/filter_utils.cc

  • ExceptionType DecodeX64Exception (uint32_t code, fit::function<std::optional<X64DebugRegs> ()> fetch_debug_regs)

    Defined at line 62 of file ../../src/developer/debug/ipc/decode_exception.cc

  • std::map<uint64_t, debug_ipc::AttachConfig> GetAttachConfigsForFilterMatches (const std::vector<debug_ipc::FilterMatch> & matches, const std::vector<const debug_ipc::Filter *> & installed_filters)

    Converts a vector of FilterMatch objects and a vector of installed filters into a map of pids to

    AttachConfigs derived from any matching filters, or the defaults if there was no matching filter.

    Correctly takes into account filters that may match the same job or process and overlays settings

    appropriately. The returned map will not have duplicates.

    Defined at line 86 of file ../../src/developer/debug/ipc/filter_utils.cc

  • template <typename MsgType>
    std::vector<char> Serialize (const MsgType & request, uint32_t transaction_id, uint32_t version)

    Defined at line 89 of file ../../src/developer/debug/ipc/message_writer.h

  • std::vector<debug_ipc::StackFrame> ConvertFrames (const std::vector<unwinder::Frame> & frames)

    Defined at line 93 of file ../../src/developer/debug/ipc/unwinder_support.cc

  • template <typename NotificationType>
    std::vector<char> Serialize (const NotificationType & notify, uint32_t version)

    Defined at line 103 of file ../../src/developer/debug/ipc/message_writer.h

  • ExceptionType DecodeArm64Exception (uint32_t code, fit::function<std::optional<uint32_t> ()> fetch_esr)

    Defined at line 138 of file ../../src/developer/debug/ipc/decode_exception.cc

  • ExceptionType DecodeRiscv64Exception (uint32_t code)

    Defined at line 163 of file ../../src/developer/debug/ipc/decode_exception.cc

  • const char * ExceptionTypeToString (ExceptionType )

    Defined at line 32 of file ../../src/developer/debug/ipc/records.cc

  • bool IsDebug (ExceptionType )

    Defined at line 14 of file ../../src/developer/debug/ipc/records.cc

  • const char * ExceptionStrategyToString (ExceptionStrategy )

    Defined at line 71 of file ../../src/developer/debug/ipc/records.cc

  • std::optional<ExceptionStrategy> ToExceptionStrategy (uint32_t raw_value)

    Defined at line 86 of file ../../src/developer/debug/ipc/records.cc

  • std::optional<uint32_t> ToRawValue (ExceptionStrategy strategy)

    Defined at line 97 of file ../../src/developer/debug/ipc/records.cc

  • const char * BreakpointTypeToString (BreakpointType )

    Defined at line 161 of file ../../src/developer/debug/ipc/records.cc

  • bool IsWatchpointType (BreakpointType )

    Read, ReadWrite and Write are considered watchpoint types.

    Defined at line 179 of file ../../src/developer/debug/ipc/records.cc

  • const char * AttachPriorityToString (AttachConfig::Priority priority)

    Defined at line 197 of file ../../src/developer/debug/ipc/records.cc

Concepts

template <typename T> IsDebugIpcMessageType requires (T t, Serializer &s, uint32_t ver) { { t.Serialize(s, ver) }; }

The only requirement for a type to be compatible with debug_ipc is for it to contain a

Serialize method that serializes its own members using the provided serializer object. Use this

as a requirement when writing template functions for all debug_ipc message types. This concept

applies for both Request and Notification types. If you're only concerned about Notification

types, use the notification specific concept below this one.

Defined at line 82 of file ../../src/developer/debug/ipc/protocol.h

template <typename T> IsDebugIpcNotificationType requires (T t, Serializer &s, uint32_t ver) { { t.timestamp }; { t.Serialize(s, ver) }; }

The only difference for notification types is that they also have a required timestamp parameter,

which is optional for request types.

Defined at line 89 of file ../../src/developer/debug/ipc/protocol.h