trbr
Version:
TraceBreaker is a simple tool to decode and analyze ESP backtraces
333 lines (330 loc) • 10.5 kB
TypeScript
// Generated by dts-bundle-generator v9.5.1
export class AbortError extends Error {
constructor();
code: string;
}
declare const riscvDecoders: Record<RiscvTargetArch, DecodeFunction>;
export type DecodeFunction = DecodeFunction$1;
export type RiscvTargetArch = RiscvTargetArch$1;
export type DecodeResult = DecodeResult$1;
export type ThreadDecodeResult = {
threadId: string;
TCB: number;
threadName?: string | undefined;
result: DecodeResult;
current?: boolean | undefined;
};
export type CoredumpDecodeResult = ThreadDecodeResult[];
/**
* @param {unknown} arg
* @returns {arg is DecodeTarget}
*/
export function isDecodeTarget(arg: unknown): arg is DecodeTarget;
/**
* @param {DecodeParams} params
* @param {DecodeInput} decodeInput
* @param {DecodeOptions} options
* @returns {Promise<
* DecodeResult | import('./coredump.js').CoredumpDecodeResult
* >}
*/
export function decode(params: DecodeParams, decodeInput: DecodeInput, options?: DecodeOptions): Promise<DecodeResult$1 | CoredumpDecodeResult>;
/**
* @param {unknown} arg
* @returns {arg is GDBLine}
*/
export function isGDBLine(arg: unknown): arg is GDBLine;
/**
* @param {unknown} arg
* @returns {arg is ParsedGDBLine}
*/
export function isParsedGDBLine(arg: unknown): arg is ParsedGDBLine;
/** @typedef {Awaited<ReturnType<DecodeCoredumpFunction>>[number] | string} DecodeFunctionInput */
/**
* @typedef {DecodeInputFileSource
* | DecodeInputStreamSource
* | DecodeFunctionInput} DecodeInput
*/
/**
* @typedef {Object} AllocInfo
* @property {AddrLocation} allocAddr
* @property {number} allocSize
*/
/**
* @typedef {Object} FaultInfo
* @property {number} coreId
* @property {AddrLine} programCounter PC at fault (PC for ESP32, MEPC for
* RISC-V, EPC1 for ESP8266)
* @property {AddrLine} [faultAddr] EXCVADDR for ESP32, EXCVADDR for RISC-V and
* ESP8266
* @property {number} [faultCode] EXCCAUSE for ESP32, EXCCODE for RISC-V
* @property {string} [faultMessage]
*/
/**
* @typedef {Object} DecodeResult
* @property {FaultInfo} [faultInfo]
* @property {Record<string, number>} [regs]
* @property {(GDBLine | ParsedGDBLine)[]} stacktraceLines
* @property {AllocInfo} [allocInfo]
*/
/**
* @typedef {Object} DecodeOptions
* @property {AbortSignal} [signal]
* @property {Debug} [debug]
*/
/**
* @callback Debug
* @param {any} formatter
* @param {...any} args
* @returns {void}
*/
/**
* @typedef {Object} PanicInfo
* @property {number} coreId
* @property {number} [programCounter]
* @property {number} [faultAddr]
* @property {number} [faultCode]
* @property {Record<string, number>} regs
*/
/**
* @typedef {PanicInfo & {
* stackBaseAddr: number
* stackData: Buffer
* target: keyof typeof riscvDecoders
* }} PanicInfoWithStackData
*/
/**
* @typedef {PanicInfo & {
* backtraceAddrs: (AddrLine | number)[]
* }} PanicInfoWithBacktrace
*/
/**
* @callback DecodeCoredumpFunction
* @param {DecodeParams} params
* @param {string} coredumpInput
* @param {DecodeOptions} options
* @returns {Promise<(PanicInfoWithBacktrace | PanicInfoWithStackData)[]>}
*/
export const defaultTargetArch: "xtensa";
export const arches: DecodeTarget[];
export type DecodeParams = DecodeParams$1;
/**
* `'0x12345678'` or `'this::loop'`
*/
export type RegAddr = string;
export type GDBLine = {
regAddr: RegAddr;
/**
* `'36'` or `'??'`
*/
lineNumber: string;
};
export type FrameArg = {
/**
* - When name and value are absent, type is the name
*/
name: string;
type?: string | undefined;
value?: string | undefined;
};
export type ParsedGDBLine = GDBLine & {
file: string;
method: string;
args?: FrameArg[];
};
export type AddrLocation = RegAddr | GDBLine | ParsedGDBLine;
export type AddrLine = {
addr?: number | undefined;
location: AddrLocation;
};
type DecodeFunction$1 = (params: DecodeParams, input: DecodeFunctionInput, options?: DecodeOptions | undefined) => Promise<DecodeResult$1>;
export type DecodeInputFileSource = {
inputPath: string;
};
export type DecodeInputStreamSource = {
inputStream: NodeJS.ReadableStream;
};
export type DecodeFunctionInput = Awaited<ReturnType<DecodeCoredumpFunction>>[number] | string;
export type DecodeInput = DecodeInputFileSource | DecodeInputStreamSource | DecodeFunctionInput;
export type AllocInfo = {
allocAddr: AddrLocation;
allocSize: number;
};
export type FaultInfo = {
coreId: number;
/**
* PC at fault (PC for ESP32, MEPC for
* RISC-V, EPC1 for ESP8266)
*/
programCounter: AddrLine;
/**
* EXCVADDR for ESP32, EXCVADDR for RISC-V and
* ESP8266
*/
faultAddr?: AddrLine | undefined;
/**
* EXCCAUSE for ESP32, EXCCODE for RISC-V
*/
faultCode?: number | undefined;
faultMessage?: string | undefined;
};
type DecodeResult$1 = {
faultInfo?: FaultInfo | undefined;
regs?: Record<string, number> | undefined;
stacktraceLines: (GDBLine | ParsedGDBLine)[];
allocInfo?: AllocInfo | undefined;
};
export type DecodeOptions = {
signal?: AbortSignal | undefined;
debug?: Debug | undefined;
};
export type Debug = (formatter: any, ...args: any[]) => void;
export type PanicInfo = {
coreId: number;
programCounter?: number | undefined;
faultAddr?: number | undefined;
faultCode?: number | undefined;
regs: Record<string, number>;
};
export type PanicInfoWithStackData = PanicInfo & {
stackBaseAddr: number;
stackData: Buffer;
target: keyof typeof riscvDecoders;
};
export type PanicInfoWithBacktrace = PanicInfo & {
backtraceAddrs: (AddrLine | number)[];
};
export type DecodeCoredumpFunction = (params: DecodeParams, coredumpInput: string, options: DecodeOptions) => Promise<(PanicInfoWithBacktrace | PanicInfoWithStackData)[]>;
export type DecodeTarget = DecodeTarget$1;
/**
* @typedef {Object} FindTooPathParams
* @property {string} arduinoCliPath
* @property {import('fqbn').FQBN} fqbn
* @property {string} [arduinoCliConfigPath]
* @property {string} [additionalUrls]
*/
/**
* @param {FindTooPathParams} params
* @param {import('./decode/decode.js').DecodeOptions} [options]
*/
export function findToolPath({ arduinoCliPath, fqbn, arduinoCliConfigPath, additionalUrls }: FindTooPathParams, options?: DecodeOptions): Promise<string>;
/** @typedef {(typeof targetArchs)[number]} DecodeTarget */
/** @typedef {(typeof riscTargetArchs)[number]} RiscvTargetArch */
/**
* @param {unknown} arg
* @returns {arg is RiscvTargetArch}
*/
export function isRiscvTargetArch(arg: unknown): arg is RiscvTargetArch$1;
/**
* @param {FindTargetArchParams} params
* @returns {DecodeTarget}
*/
export function findTargetArch({ buildProperties }: FindTargetArchParams): DecodeTarget$1;
/**
* @typedef {Object} ResolveToolPathParams
* @property {import('fqbn').FQBN} fqbn
* @property {Record<string, string>} buildProperties
*/
/**
* @param {ResolveToolPathParams} params
* @returns {Promise<string>}
*/
export function resolveToolPath({ fqbn, buildProperties }: ResolveToolPathParams): Promise<string>;
declare const targetArchs: readonly [
"xtensa",
"esp32c2",
"esp32c3",
"esp32c6",
"esp32h2",
"esp32h4",
"esp32p4"
];
export type FindTooPathParams = {
arduinoCliPath: string;
fqbn: import("fqbn").FQBN;
arduinoCliConfigPath?: string | undefined;
additionalUrls?: string | undefined;
};
type DecodeTarget$1 = (typeof targetArchs)[number];
type RiscvTargetArch$1 = (typeof riscTargetArchs)[number];
export type ResolveToolPathParams = {
fqbn: import("fqbn").FQBN;
buildProperties: Record<string, string>;
};
export type FindTargetArchParams = {
buildProperties: Record<string, string>;
};
declare const riscTargetArchs: readonly [
"esp32c2",
"esp32c3",
"esp32c6",
"esp32h2",
"esp32h4",
"esp32p4"
];
/**
* @overload
* @param {CreateDecodeParamsFromParams} params
* @returns {Promise<DecodeParams>}
*/
export function createDecodeParams(params: CreateDecodeParamsFromParams): Promise<DecodeParams$1>;
/**
* @overload
* @param {CreateCoredumpDecodeParamsFromParams} params
* @returns {Promise<DecodeCoredumpParams>}
*/
export function createDecodeParams(params: CreateCoredumpDecodeParamsFromParams): Promise<DecodeCoredumpParams>;
type DecodeTarget$2 = DecodeTarget$1;
export type FQBN = import("fqbn").FQBN;
type DecodeParams$1 = {
toolPath: string;
elfPath: string;
targetArch: DecodeTarget$2;
};
export type DecodeCoredumpParams = DecodeParams$1 & CoredumpMode;
export type CreateDecodeParamsParams = {
elfPath: string;
};
export type ArduinoCliParams = {
arduinoCliPath: string;
arduinoCliConfigPath?: string | undefined;
additionalUrls?: string | undefined;
};
export type ToolParams = {
toolPath: string;
targetArch?: "esp32c2" | "esp32c3" | "esp32c6" | "esp32h2" | "esp32h4" | "esp32p4" | "xtensa" | undefined;
};
export type CoredumpMode = {
coredumpMode: true;
};
export type BacktraceMode = {
coredumpMode?: false | undefined;
};
export type WithFQBN = {
fqbn: FQBN;
};
export type WithBuildProperties = WithFQBN & {
buildProperties: Record<string, string>;
};
export type CreateDecodeParamsFromToolParams = CreateDecodeParamsParams & ToolParams & BacktraceMode;
export type CreateDecodeParamsFromFQBNParams = CreateDecodeParamsParams & ArduinoCliParams & WithFQBN & BacktraceMode;
export type CreateDecodeParamsFromBuildPropertiesParams = CreateDecodeParamsParams & WithBuildProperties & BacktraceMode;
export type CreateDecodeParamsFromParams = CreateDecodeParamsFromToolParams | CreateDecodeParamsFromFQBNParams | CreateDecodeParamsFromBuildPropertiesParams;
export type CreateCoredumpDecodeParamsFromToolParams = CreateDecodeParamsParams & ToolParams & CoredumpMode;
export type CreateCoredumpDecodeParamsFromFQBNParams = CreateDecodeParamsParams & ArduinoCliParams & WithFQBN & CoredumpMode;
export type CreateCoredumpDecodeParamsFromBuildPropertiesParams = CreateDecodeParamsParams & WithBuildProperties & CoredumpMode;
export type CreateCoredumpDecodeParamsFromParams = CreateCoredumpDecodeParamsFromToolParams | CreateCoredumpDecodeParamsFromFQBNParams | CreateCoredumpDecodeParamsFromBuildPropertiesParams;
/**
* @param {import('./decode.js').DecodeResult | CoredumpDecodeResult} result
* @param {StringifyOptions} [options]
*/
export function stringifyDecodeResult(result: DecodeResult$1 | CoredumpDecodeResult$1, options?: StringifyOptions): string;
export type StringifyOptions = {
color?: "force" | "disable" | undefined;
/**
* Default is `'\n'`
*/
lineSeparator?: string | undefined;
};
type CoredumpDecodeResult$1 = CoredumpDecodeResult;
export {};