API Reference

This page is auto-generated from the source code docstrings using Sphinx autodoc.

kdumpling module

kdumpling - A Python library for creating Linux kdump crash dump files.

This library allows you to synthesize valid ELF64 vmcore files from raw memory data and vmcoreinfo values.

class kdumpling.KdumpBuilder(arch: str = 'x86_64')[source]

Bases: object

Builder for creating Linux kdump vmcore files.

A vmcore is an ELF64 core dump file containing: - ELF header identifying it as a core dump - Program headers describing memory segments - A PT_NOTE segment with VMCOREINFO metadata - PT_LOAD segments with the actual memory data

The builder also supports the kdump compressed format (makedumpfile compatible), which provides per-page compression and filtering.

Example usage:

builder = KdumpBuilder(arch=’x86_64’) builder.set_vmcoreinfo(“OSRELEASE=5.14.0nPAGE_SIZE=4096n”) builder.add_memory_segment(phys_addr=0x100000, data=memory_bytes) builder.write(“output.vmcore”)

For custom metadata:

builder.add_custom_note(: name=b”MYAPP”, note_type=1, data=b”version=1.0”

)

arch: str = 'x86_64'

set_vmcoreinfo(data: str | bytes) → KdumpBuilder[source]

Set the VMCOREINFO metadata string.

This is typically the content from /sys/kernel/vmcoreinfo or /proc/vmcore-info on a running Linux system.

Parameters:: data – The vmcoreinfo string (e.g., “OSRELEASE=5.14.0nPAGE_SIZE=4096n”)
Returns:: self for method chaining

add_memory_segment(phys_addr: int, data: bytes | str | BinaryIO, virt_addr: int | None = None) → KdumpBuilder[source]

Add a memory segment to the dump.

Parameters:

phys_addr – The physical address where this memory resides
data – The memory data. Can be: - bytes: Raw memory content - str: Path to a file containing the data - BinaryIO: File-like object to read from
virt_addr – Optional virtual address for this segment. If not specified, defaults to the physical address. This is useful for tools like drgn that need to read memory by virtual address.

Returns:

self for method chaining

Example

# Physical address only (virt_addr defaults to phys_addr) builder.add_memory_segment(phys_addr=0x100000, data=memory_bytes)

# With explicit virtual address (for kernel memory mappings) builder.add_memory_segment(

phys_addr=0x100000, data=memory_bytes, virt_addr=0xffff888000100000

)

add_cpu_context(cpu_id: int = 0, registers: dict[str, int] | None = None, pid: int = 0, **kwargs: int) → KdumpBuilder[source]

Add CPU register state for a processor.

This creates an NT_PRSTATUS note containing the CPU’s register state at the time of the crash. This is useful for tools like crash and gdb to show backtraces.

Parameters:

cpu_id – CPU identifier (0-indexed)
registers – Dictionary mapping register names to values. For x86_64: RIP, RSP, RBP, RAX, RBX, etc. For aarch64: X0-X30, SP, PC, PSTATE
pid – Process ID associated with this CPU
**kwargs – Additional prstatus fields (pr_ppid, pr_pgrp, etc.)

Returns:

self for method chaining

Example

builder.add_cpu_context(: cpu_id=0, registers={‘RIP’: 0xffffffff81000000, ‘RSP’: 0xffff888000000000}, pid=1

)

add_custom_note(name: bytes | str, note_type: int, data: bytes | str) → KdumpBuilder[source]

Add a custom ELF note to the vmcore.

Custom notes are stored in the PT_NOTE segment alongside standard notes like VMCOREINFO and NT_PRSTATUS. Tools that don’t recognize the note type will safely ignore it.

Parameters:

name – Vendor/namespace identifier (e.g., b”KDUMPLING” or “MYAPP”). Using a unique name prevents conflicts with other tools.
note_type – Numeric type identifier. See CustomNoteType for predefined values, or use any integer.
data – The note data. Can be bytes or a string (will be UTF-8 encoded).

Returns:

self for method chaining

Example

builder.add_custom_note(: name=b”KDUMPLING”, note_type=CustomNoteType.METADATA, data=b”sha256=abc123…”

)

add_metadata(data: dict[str, str] | bytes | str, vendor: bytes | str = b'KDUMPLING') → KdumpBuilder[source]

Add metadata to the vmcore.

This is a convenience method for adding key-value metadata using the METADATA note type.

Parameters:

data – Metadata to add. Can be: - dict: Key-value pairs (converted to “key=valuen” format) - bytes/str: Raw metadata content
vendor – Vendor name for the note (default: “KDUMPLING”)

Returns:

self for method chaining

Example

builder.add_metadata({: “sha256”: “abc123…”, “created_at”: “2024-01-28T10:30:00Z”, “source”: “memory_forensics_tool”

})

add_annotations(annotations: dict[str, str], vendor: bytes | str = b'KDUMPLING') → KdumpBuilder[source]

Add custom annotations to the vmcore.

Annotations are free-form key-value pairs that can be used to attach contextual information to the dump.

Parameters:

annotations – Dictionary of annotation key-value pairs
vendor – Vendor name for the note (default: “KDUMPLING”)

Returns:

self for method chaining

Example

builder.add_annotations({: “hostname”: “prod-server-01”, “kernel_panic_reason”: “out of memory”, “captured_by”: “crash_collector v2.1”

})

property stats: DumpStats

Get statistics about the dump being built.

Returns:: DumpStats object with information about segments, size, etc.

Example

builder = KdumpBuilder() builder.add_memory_segment(0x1000, b”x00” * 4096) print(builder.stats) # Dump Statistics: # Architecture: x86_64 # Memory Segments: 1 # …

write(output_path: str, format: OutputFormat = OutputFormat.ELF, compression: CompressionType = CompressionType.ZLIB, compression_level: int = 6) → None[source]

Write the vmcore file to disk.

Parameters:

output_path – Path where the vmcore file will be written
format – Output format (ELF or KDUMP_COMPRESSED). Default is ELF.
compression – Compression type for KDUMP_COMPRESSED format. Default is ZLIB. Ignored for ELF format.
compression_level – Compression level 1-9. Default is 6. Ignored for ELF format.

Example

# Write standard ELF vmcore (default) builder.write(“output.vmcore”)

# Write kdump compressed format with zlib builder.write(

“output.vmcore”, format=OutputFormat.KDUMP_COMPRESSED, compression=CompressionType.ZLIB

)

__init__(arch: str = 'x86_64') → None

class kdumpling.DumpStats(architecture: str, num_memory_segments: int, num_cpu_contexts: int, total_memory_size: int, vmcoreinfo_size: int, estimated_file_size: int, memory_segments: list[tuple[int, int, int]])[source]

Bases: object

Statistics about a vmcore dump being built.

Provides information about the dump’s contents and estimated size.

architecture: str

num_memory_segments: int

num_cpu_contexts: int

total_memory_size: int

vmcoreinfo_size: int

estimated_file_size: int

memory_segments: list[tuple[int, int, int]]

property total_memory_size_human: str: Total memory size in human-readable format.

property estimated_file_size_human: str: Estimated file size in human-readable format.

__str__() → str[source]: Return a formatted string representation of the stats.

__init__(architecture: str, num_memory_segments: int, num_cpu_contexts: int, total_memory_size: int, vmcoreinfo_size: int, estimated_file_size: int, memory_segments: list[tuple[int, int, int]]) → None

class kdumpling.CpuContext(cpu_id: int = 0, pid: int = 0, registers: dict[str, int]=<factory>, si_signo: int = 0, si_code: int = 0, si_errno: int = 0, pr_pid: int = 0, pr_ppid: int = 0, pr_pgrp: int = 0, pr_sid: int = 0, pr_utime_sec: int = 0, pr_utime_usec: int = 0, pr_stime_sec: int = 0, pr_stime_usec: int = 0, pr_cutime_sec: int = 0, pr_cutime_usec: int = 0, pr_cstime_sec: int = 0, pr_cstime_usec: int = 0)[source]

Bases: object

CPU context for a single processor.

This represents the register state at the time of the crash.

cpu_id: int = 0

pid: int = 0

registers: dict[str, int]

si_signo: int = 0

si_code: int = 0

si_errno: int = 0

pr_pid: int = 0

pr_ppid: int = 0

pr_pgrp: int = 0

pr_sid: int = 0

pr_utime_sec: int = 0

pr_utime_usec: int = 0

pr_stime_sec: int = 0

pr_stime_usec: int = 0

pr_cutime_sec: int = 0

pr_cutime_usec: int = 0

pr_cstime_sec: int = 0

pr_cstime_usec: int = 0

__init__(cpu_id: int = 0, pid: int = 0, registers: dict[str, int]=<factory>, si_signo: int = 0, si_code: int = 0, si_errno: int = 0, pr_pid: int = 0, pr_ppid: int = 0, pr_pgrp: int = 0, pr_sid: int = 0, pr_utime_sec: int = 0, pr_utime_usec: int = 0, pr_stime_sec: int = 0, pr_stime_usec: int = 0, pr_cutime_sec: int = 0, pr_cutime_usec: int = 0, pr_cstime_sec: int = 0, pr_cstime_usec: int = 0) → None

class kdumpling.X86_64Reg(value)[source]

Bases: IntEnum

x86_64 register indices in the prstatus pr_reg array.

R15 = 0

R14 = 1

R13 = 2

R12 = 3

RBP = 4

RBX = 5

R11 = 6

R10 = 7

R9 = 8

R8 = 9

RAX = 10

RCX = 11

RDX = 12

RSI = 13

RDI = 14

ORIG_RAX = 15

RIP = 16

CS = 17

EFLAGS = 18

RSP = 19

SS = 20

FS_BASE = 21

GS_BASE = 22

DS = 23

ES = 24

FS = 25

GS = 26

class kdumpling.AArch64Reg(value)[source]

Bases: IntEnum

AArch64 register indices.

X0 = 0

X1 = 1

X2 = 2

X3 = 3

X4 = 4

X5 = 5

X6 = 6

X7 = 7

X8 = 8

X9 = 9

X10 = 10

X11 = 11

X12 = 12

X13 = 13

X14 = 14

X15 = 15

X16 = 16

X17 = 17

X18 = 18

X19 = 19

X20 = 20

X21 = 21

X22 = 22

X23 = 23

X24 = 24

X25 = 25

X26 = 26

X27 = 27

X28 = 28

X29 = 29

X30 = 30

SP = 31

PC = 32

PSTATE = 33

class kdumpling.OutputFormat(value)[source]

Bases: IntEnum

Output format for vmcore files.

ELF = 0

KDUMP_COMPRESSED = 1

class kdumpling.CompressionType(value)[source]

Bases: IntEnum

Compression algorithms for kdump compressed format.

NONE = 0

ZLIB = 1

LZO = 2

SNAPPY = 4

ZSTD = 8

class kdumpling.CustomNote(name: bytes, note_type: int, data: bytes)[source]

Bases: object

A custom ELF note to be included in the vmcore.

Custom notes allow users to embed additional metadata in their vmcore files, such as hashes, timestamps, annotations, or any other application-specific data.

The note is identified by a (name, type) tuple. Using a unique vendor name (like “KDUMPLING” or your company name) prevents conflicts with other tools.

Example

note = CustomNote(: name=b”KDUMPLING”, note_type=CustomNoteType.METADATA, data=b”sha256=abc123…”

)

name: bytes

note_type: int

data: bytes

__init__(name: bytes, note_type: int, data: bytes) → None

class kdumpling.CustomNoteType(value)[source]

Bases: IntEnum

Predefined custom note types for kdumpling metadata.

Users can also use any integer value for custom types.

METADATA = 1

ANNOTATIONS = 2

FILE_INFO = 3

USER_DEFINED = 256

kdumpling.builder module

KdumpBuilder - Main class for building Linux kdump vmcore files.

class kdumpling.builder.OutputFormat(value)[source]

Bases: IntEnum

Output format for vmcore files.

ELF = 0

KDUMP_COMPRESSED = 1

class kdumpling.builder.CompressionType(value)[source]

Bases: IntEnum

Compression algorithms for kdump compressed format.

NONE = 0

ZLIB = 1

LZO = 2

SNAPPY = 4

ZSTD = 8

class kdumpling.builder.CustomNoteType(value)[source]

Bases: IntEnum

Predefined custom note types for kdumpling metadata.

Users can also use any integer value for custom types.

METADATA = 1

ANNOTATIONS = 2

FILE_INFO = 3

USER_DEFINED = 256

class kdumpling.builder.CustomNote(name: bytes, note_type: int, data: bytes)[source]

Bases: object

A custom ELF note to be included in the vmcore.

Custom notes allow users to embed additional metadata in their vmcore files, such as hashes, timestamps, annotations, or any other application-specific data.

The note is identified by a (name, type) tuple. Using a unique vendor name (like “KDUMPLING” or your company name) prevents conflicts with other tools.

Example

note = CustomNote(: name=b”KDUMPLING”, note_type=CustomNoteType.METADATA, data=b”sha256=abc123…”

)

name: bytes

note_type: int

data: bytes

__init__(name: bytes, note_type: int, data: bytes) → None

class kdumpling.builder.DumpStats(architecture: str, num_memory_segments: int, num_cpu_contexts: int, total_memory_size: int, vmcoreinfo_size: int, estimated_file_size: int, memory_segments: list[tuple[int, int, int]])[source]

Bases: object

Statistics about a vmcore dump being built.

Provides information about the dump’s contents and estimated size.

architecture: str

num_memory_segments: int

num_cpu_contexts: int

total_memory_size: int

vmcoreinfo_size: int

estimated_file_size: int

memory_segments: list[tuple[int, int, int]]

property total_memory_size_human: str: Total memory size in human-readable format.

property estimated_file_size_human: str: Estimated file size in human-readable format.

__str__() → str[source]: Return a formatted string representation of the stats.

__init__(architecture: str, num_memory_segments: int, num_cpu_contexts: int, total_memory_size: int, vmcoreinfo_size: int, estimated_file_size: int, memory_segments: list[tuple[int, int, int]]) → None

class kdumpling.builder.MemorySegment(phys_addr: int, data: bytes | str | BinaryIO, virt_addr: int | None = None, size: int = 0)[source]

Bases: object

Represents a memory segment to be included in the dump.

phys_addr

Physical memory address where this segment resides

Type:: int

data

The memory data (bytes, file path, or file-like object)

Type:: bytes | str | BinaryIO

virt_addr

Virtual memory address (optional, defaults to phys_addr if None)

Type:: int | None

size

Size of the segment in bytes (computed automatically)

Type:: int

phys_addr: int

data: bytes | str | BinaryIO

virt_addr: int | None = None

size: int = 0

property effective_virt_addr: int: Return the virtual address to use (virt_addr if set, otherwise phys_addr).

get_data() → bytes[source]: Read and return the segment data as bytes.

write_to(output: BinaryIO) → None[source]: Stream the segment data to an output file.

__init__(phys_addr: int, data: bytes | str | BinaryIO, virt_addr: int | None = None, size: int = 0) → None

class kdumpling.builder.KdumpBuilder(arch: str = 'x86_64')[source]

Bases: object

Builder for creating Linux kdump vmcore files.

A vmcore is an ELF64 core dump file containing: - ELF header identifying it as a core dump - Program headers describing memory segments - A PT_NOTE segment with VMCOREINFO metadata - PT_LOAD segments with the actual memory data

The builder also supports the kdump compressed format (makedumpfile compatible), which provides per-page compression and filtering.

Example usage:

builder = KdumpBuilder(arch=’x86_64’) builder.set_vmcoreinfo(“OSRELEASE=5.14.0nPAGE_SIZE=4096n”) builder.add_memory_segment(phys_addr=0x100000, data=memory_bytes) builder.write(“output.vmcore”)

For custom metadata:

builder.add_custom_note(: name=b”MYAPP”, note_type=1, data=b”version=1.0”

)

arch: str = 'x86_64'

set_vmcoreinfo(data: str | bytes) → KdumpBuilder[source]

Set the VMCOREINFO metadata string.

This is typically the content from /sys/kernel/vmcoreinfo or /proc/vmcore-info on a running Linux system.

Parameters:: data – The vmcoreinfo string (e.g., “OSRELEASE=5.14.0nPAGE_SIZE=4096n”)
Returns:: self for method chaining

add_memory_segment(phys_addr: int, data: bytes | str | BinaryIO, virt_addr: int | None = None) → KdumpBuilder[source]

Add a memory segment to the dump.

Parameters:

phys_addr – The physical address where this memory resides
data – The memory data. Can be: - bytes: Raw memory content - str: Path to a file containing the data - BinaryIO: File-like object to read from
virt_addr – Optional virtual address for this segment. If not specified, defaults to the physical address. This is useful for tools like drgn that need to read memory by virtual address.

Returns:

self for method chaining

Example

# Physical address only (virt_addr defaults to phys_addr) builder.add_memory_segment(phys_addr=0x100000, data=memory_bytes)

# With explicit virtual address (for kernel memory mappings) builder.add_memory_segment(

phys_addr=0x100000, data=memory_bytes, virt_addr=0xffff888000100000

)

add_cpu_context(cpu_id: int = 0, registers: dict[str, int] | None = None, pid: int = 0, **kwargs: int) → KdumpBuilder[source]

Add CPU register state for a processor.

This creates an NT_PRSTATUS note containing the CPU’s register state at the time of the crash. This is useful for tools like crash and gdb to show backtraces.

Parameters:

cpu_id – CPU identifier (0-indexed)
registers – Dictionary mapping register names to values. For x86_64: RIP, RSP, RBP, RAX, RBX, etc. For aarch64: X0-X30, SP, PC, PSTATE
pid – Process ID associated with this CPU
**kwargs – Additional prstatus fields (pr_ppid, pr_pgrp, etc.)

Returns:

self for method chaining

Example

builder.add_cpu_context(: cpu_id=0, registers={‘RIP’: 0xffffffff81000000, ‘RSP’: 0xffff888000000000}, pid=1

)

add_custom_note(name: bytes | str, note_type: int, data: bytes | str) → KdumpBuilder[source]

Add a custom ELF note to the vmcore.

Custom notes are stored in the PT_NOTE segment alongside standard notes like VMCOREINFO and NT_PRSTATUS. Tools that don’t recognize the note type will safely ignore it.

Parameters:

name – Vendor/namespace identifier (e.g., b”KDUMPLING” or “MYAPP”). Using a unique name prevents conflicts with other tools.
note_type – Numeric type identifier. See CustomNoteType for predefined values, or use any integer.
data – The note data. Can be bytes or a string (will be UTF-8 encoded).

Returns:

self for method chaining

Example

builder.add_custom_note(: name=b”KDUMPLING”, note_type=CustomNoteType.METADATA, data=b”sha256=abc123…”

)

add_metadata(data: dict[str, str] | bytes | str, vendor: bytes | str = b'KDUMPLING') → KdumpBuilder[source]

Add metadata to the vmcore.

This is a convenience method for adding key-value metadata using the METADATA note type.

Parameters:

data – Metadata to add. Can be: - dict: Key-value pairs (converted to “key=valuen” format) - bytes/str: Raw metadata content
vendor – Vendor name for the note (default: “KDUMPLING”)

Returns:

self for method chaining

Example

builder.add_metadata({: “sha256”: “abc123…”, “created_at”: “2024-01-28T10:30:00Z”, “source”: “memory_forensics_tool”

})

add_annotations(annotations: dict[str, str], vendor: bytes | str = b'KDUMPLING') → KdumpBuilder[source]

Add custom annotations to the vmcore.

Annotations are free-form key-value pairs that can be used to attach contextual information to the dump.

Parameters:

annotations – Dictionary of annotation key-value pairs
vendor – Vendor name for the note (default: “KDUMPLING”)

Returns:

self for method chaining

Example

builder.add_annotations({: “hostname”: “prod-server-01”, “kernel_panic_reason”: “out of memory”, “captured_by”: “crash_collector v2.1”

})

property stats: DumpStats

Get statistics about the dump being built.

Returns:: DumpStats object with information about segments, size, etc.

Example

builder = KdumpBuilder() builder.add_memory_segment(0x1000, b”x00” * 4096) print(builder.stats) # Dump Statistics: # Architecture: x86_64 # Memory Segments: 1 # …

write(output_path: str, format: OutputFormat = OutputFormat.ELF, compression: CompressionType = CompressionType.ZLIB, compression_level: int = 6) → None[source]

Write the vmcore file to disk.

Parameters:

output_path – Path where the vmcore file will be written
format – Output format (ELF or KDUMP_COMPRESSED). Default is ELF.
compression – Compression type for KDUMP_COMPRESSED format. Default is ZLIB. Ignored for ELF format.
compression_level – Compression level 1-9. Default is 6. Ignored for ELF format.

Example

# Write standard ELF vmcore (default) builder.write(“output.vmcore”)

# Write kdump compressed format with zlib builder.write(

“output.vmcore”, format=OutputFormat.KDUMP_COMPRESSED, compression=CompressionType.ZLIB

)

__init__(arch: str = 'x86_64') → None

kdumpling.cpu_context module

CPU context structures for different architectures.

This module defines the register layouts for NT_PRSTATUS notes which contain CPU state at the time of the crash.

class kdumpling.cpu_context.NoteType(value)[source]

Bases: IntEnum

ELF note types for core dumps.

NT_PRSTATUS = 1

NT_PRFPREG = 2

NT_PRPSINFO = 3

NT_TASKSTRUCT = 4

NT_AUXV = 6

NT_SIGINFO = 1397311305

NT_FILE = 1179208773

NT_PRXFPREG = 1189489535

class kdumpling.cpu_context.X86_64Reg(value)[source]

Bases: IntEnum

x86_64 register indices in the prstatus pr_reg array.

R15 = 0

R14 = 1

R13 = 2

R12 = 3

RBP = 4

RBX = 5

R11 = 6

R10 = 7

R9 = 8

R8 = 9

RAX = 10

RCX = 11

RDX = 12

RSI = 13

RDI = 14

ORIG_RAX = 15

RIP = 16

CS = 17

EFLAGS = 18

RSP = 19

SS = 20

FS_BASE = 21

GS_BASE = 22

DS = 23

ES = 24

FS = 25

GS = 26

class kdumpling.cpu_context.AArch64Reg(value)[source]

Bases: IntEnum

AArch64 register indices.

X0 = 0

X1 = 1

X2 = 2

X3 = 3

X4 = 4

X5 = 5

X6 = 6

X7 = 7

X8 = 8

X9 = 9

X10 = 10

X11 = 11

X12 = 12

X13 = 13

X14 = 14

X15 = 15

X16 = 16

X17 = 17

X18 = 18

X19 = 19

X20 = 20

X21 = 21

X22 = 22

X23 = 23

X24 = 24

X25 = 25

X26 = 26

X27 = 27

X28 = 28

X29 = 29

X30 = 30

SP = 31

PC = 32

PSTATE = 33

class kdumpling.cpu_context.ArchRegisterInfo(num_registers: int, register_size: int, reg_enum: type[IntEnum] | None = None)[source]

Bases: object

Architecture-specific register information.

num_registers: int

register_size: int

reg_enum: type[IntEnum] | None = None

property pr_reg_size: int: Size of the pr_reg array in bytes.

__init__(num_registers: int, register_size: int, reg_enum: type[IntEnum] | None = None) → None

class kdumpling.cpu_context.CpuContext(cpu_id: int = 0, pid: int = 0, registers: dict[str, int]=<factory>, si_signo: int = 0, si_code: int = 0, si_errno: int = 0, pr_pid: int = 0, pr_ppid: int = 0, pr_pgrp: int = 0, pr_sid: int = 0, pr_utime_sec: int = 0, pr_utime_usec: int = 0, pr_stime_sec: int = 0, pr_stime_usec: int = 0, pr_cutime_sec: int = 0, pr_cutime_usec: int = 0, pr_cstime_sec: int = 0, pr_cstime_usec: int = 0)[source]

Bases: object

CPU context for a single processor.

This represents the register state at the time of the crash.

cpu_id: int = 0

pid: int = 0

registers: dict[str, int]

si_signo: int = 0

si_code: int = 0

si_errno: int = 0

pr_pid: int = 0

pr_ppid: int = 0

pr_pgrp: int = 0

pr_sid: int = 0

pr_utime_sec: int = 0

pr_utime_usec: int = 0

pr_stime_sec: int = 0

pr_stime_usec: int = 0

pr_cutime_sec: int = 0

pr_cutime_usec: int = 0

pr_cstime_sec: int = 0

pr_cstime_usec: int = 0

__init__(cpu_id: int = 0, pid: int = 0, registers: dict[str, int]=<factory>, si_signo: int = 0, si_code: int = 0, si_errno: int = 0, pr_pid: int = 0, pr_ppid: int = 0, pr_pgrp: int = 0, pr_sid: int = 0, pr_utime_sec: int = 0, pr_utime_usec: int = 0, pr_stime_sec: int = 0, pr_stime_usec: int = 0, pr_cutime_sec: int = 0, pr_cutime_usec: int = 0, pr_cstime_sec: int = 0, pr_cstime_usec: int = 0) → None

kdumpling.cpu_context.pack_prstatus(ctx: CpuContext, arch: str, endianness: ElfData) → bytes[source]

Pack a prstatus structure for the given architecture.

The prstatus structure format (for 64-bit):

struct elf_prstatus {: struct elf_siginfo pr_info; // 12 bytes short pr_cursig; // 2 bytes unsigned long pr_sigpend; // 8 bytes unsigned long pr_sighold; // 8 bytes pid_t pr_pid; // 4 bytes pid_t pr_ppid; // 4 bytes pid_t pr_pgrp; // 4 bytes pid_t pr_sid; // 4 bytes struct timeval pr_utime; // 16 bytes struct timeval pr_stime; // 16 bytes struct timeval pr_cutime; // 16 bytes struct timeval pr_cstime; // 16 bytes elf_gregset_t pr_reg; // varies by arch int pr_fpvalid; // 4 bytes

};

Parameters:

ctx – CPU context with register values
arch – Architecture name
endianness – Little or big endian

Returns:

Packed prstatus structure as bytes

kdumpling.cpu_context.get_prstatus_size(arch: str) → int[source]

Get the size of the prstatus structure for an architecture.

Parameters:: arch – Architecture name
Returns:: Size in bytes

kdumpling.elf module

ELF64 constants and structures for building vmcore files.

class kdumpling.elf.ElfClass(value)[source]

Bases: IntEnum

ELFCLASS32 = 1

ELFCLASS64 = 2

class kdumpling.elf.ElfData(value)[source]

Bases: IntEnum

ELFDATA2LSB = 1

ELFDATA2MSB = 2

class kdumpling.elf.ElfType(value)[source]

Bases: IntEnum

ET_NONE = 0

ET_REL = 1

ET_EXEC = 2

ET_DYN = 3

ET_CORE = 4

class kdumpling.elf.ElfMachine(value)[source]

Bases: IntEnum

EM_NONE = 0

EM_386 = 3

EM_X86_64 = 62

EM_ARM = 40

EM_AARCH64 = 183

EM_S390 = 22

EM_PPC64 = 21

EM_RISCV = 243

class kdumpling.elf.PhdrType(value)[source]

Bases: IntEnum

PT_NULL = 0

PT_LOAD = 1

PT_NOTE = 4

class kdumpling.elf.PhdrFlags(value)[source]

Bases: IntEnum

PF_X = 1

PF_W = 2

PF_R = 4

class kdumpling.elf.NoteType(value)[source]

Bases: IntEnum

NT_PRSTATUS = 1

NT_PRFPREG = 2

NT_PRPSINFO = 3

class kdumpling.elf.ArchInfo(machine: ElfMachine, endianness: ElfData, page_size: int = 4096)[source]

Bases: NamedTuple

Architecture-specific information.

machine: ElfMachine: Alias for field number 0

endianness: ElfData: Alias for field number 1

page_size: int: Alias for field number 2

kdumpling.elf.pack_elf64_ehdr(machine: ElfMachine, endianness: ElfData, phdr_count: int, phdr_offset: int) → bytes[source]

Pack an ELF64 header for a core dump.

Parameters:

machine – Target architecture (e.g., EM_X86_64)
endianness – Little or big endian
phdr_count – Number of program headers
phdr_offset – File offset to program headers

Returns:

64 bytes representing the ELF64 header

kdumpling.elf.pack_elf64_phdr(endianness: ElfData, p_type: PhdrType, p_flags: int, p_offset: int, p_vaddr: int, p_paddr: int, p_filesz: int, p_memsz: int, p_align: int = 0) → bytes[source]

Pack an ELF64 program header.

Parameters:

endianness – Little or big endian
p_type – Segment type (PT_LOAD, PT_NOTE, etc.)
p_flags – Segment flags (read/write/execute)
p_offset – File offset of segment data
p_vaddr – Virtual address
p_paddr – Physical address
p_filesz – Size in file
p_memsz – Size in memory
p_align – Alignment

Returns:

56 bytes representing the program header

kdumpling.elf.pack_elf_note(endianness: ElfData, name: bytes, note_type: int, desc: bytes) → bytes[source]

Pack an ELF note entry.

Notes have the format: - namesz (4 bytes): length of name including null terminator - descsz (4 bytes): length of descriptor - type (4 bytes): note type - name (namesz bytes, padded to 4-byte boundary) - desc (descsz bytes, padded to 4-byte boundary)

Parameters:

endianness – Little or big endian
name – Note name (without null terminator)
note_type – Note type identifier
desc – Note descriptor data

Returns:

The packed note entry

kdumpling.kdump_compressed module

Kdump compressed format (makedumpfile compatible) structures and utilities.

This module implements the kdump compressed dump format used by makedumpfile and supported by tools like crash, libkdumpfile, and drgn.

The format provides: - Per-page compression (zlib, lzo, snappy, zstd) - Page filtering (exclude zero pages, cache, user pages, etc.) - Efficient storage with bitmap-based indexing

File structure (per makedumpfile specification):: Offset 0x0000: disk_dump_header (with “KDUMP “ signature) Offset 0x1000: kdump_sub_header Offset 0x2000: 1st bitmap (valid memory pages) Offset varies: 2nd bitmap (dumped pages) Offset varies: Page descriptors Offset varies: Compressed page data Offset varies: vmcoreinfo (offset stored in sub_header) Offset varies: notes data (offset stored in sub_header)

class kdumpling.kdump_compressed.DumpLevel(value)[source]

Bases: IntFlag

Dump levels for page filtering (compatible with makedumpfile).

These can be combined with | operator.

DL_NONE = 0

DL_EXCLUDE_ZERO = 1

DL_EXCLUDE_CACHE = 2

DL_EXCLUDE_CACHE_PRIVATE = 4

DL_EXCLUDE_USER = 8

DL_EXCLUDE_FREE = 16

class kdumpling.kdump_compressed.DumpHeaderVersion(value)[source]

Bases: IntEnum

Dump header version numbers.

VERSION_1 = 1

VERSION_2 = 2

VERSION_3 = 3

VERSION_4 = 4

VERSION_5 = 5

VERSION_6 = 6

class kdumpling.kdump_compressed.CompressionMethod(value)[source]

Bases: IntEnum

Compression method flags stored in status field.

COMPRESS_NONE = 0

COMPRESS_ZLIB = 1

COMPRESS_LZO = 2

COMPRESS_SNAPPY = 4

COMPRESS_ZSTD = 8

class kdumpling.kdump_compressed.DiskDumpHeader(signature: bytes = b'KDUMP ', header_version: int = DumpHeaderVersion.VERSION_6, sysname: bytes = b'Linux', nodename: bytes = b'', release: bytes = b'', version: bytes = b'', machine: bytes = b'', domainname: bytes = b'', timestamp_sec: int = 0, timestamp_usec: int = 0, status: int = 0, block_size: int = 4096, sub_hdr_size: int = 1, bitmap_blocks: int = 0, max_mapnr: int = 0, total_ram_blocks: int = 0, device_blocks: int = 0, written_blocks: int = 0, current_cpu: int = 0, nr_cpus: int = 1)[source]

Bases: object

disk_dump_header structure.

This is the primary header at offset 0x1000 in the file.

struct disk_dump_header {: char signature[8]; // “KDUMP ” int header_version; // Version number struct new_utsname utsname; // System info (65 * 6 = 390 bytes) char _pad1[2]; // Padding struct timeval timestamp; // Time of dump unsigned int status; // Compression flags int block_size; // Block size (usually 4096) int sub_hdr_size; // Size of sub-header in blocks unsigned int bitmap_blocks; // Size of bitmap in blocks unsigned int max_mapnr; // Max page frame number (32-bit) unsigned int total_ram_blocks; // Total RAM in blocks unsigned int device_blocks; // Device blocks (split dumps) unsigned int written_blocks; // Blocks written unsigned int current_cpu; // CPU that made the dump int nr_cpus; // Number of CPUs struct task_struct *tasks[0]; // Per-CPU task pointers

};

signature: bytes = b'KDUMP '

header_version: int = 6

sysname: bytes = b'Linux'

nodename: bytes = b''

release: bytes = b''

version: bytes = b''

machine: bytes = b''

domainname: bytes = b''

timestamp_sec: int = 0

timestamp_usec: int = 0

status: int = 0

block_size: int = 4096

sub_hdr_size: int = 1

bitmap_blocks: int = 0

max_mapnr: int = 0

total_ram_blocks: int = 0

device_blocks: int = 0

written_blocks: int = 0

current_cpu: int = 0

nr_cpus: int = 1

pack(endianness: ElfData) → bytes[source]: Pack the header into bytes.

__init__(signature: bytes = b'KDUMP ', header_version: int = DumpHeaderVersion.VERSION_6, sysname: bytes = b'Linux', nodename: bytes = b'', release: bytes = b'', version: bytes = b'', machine: bytes = b'', domainname: bytes = b'', timestamp_sec: int = 0, timestamp_usec: int = 0, status: int = 0, block_size: int = 4096, sub_hdr_size: int = 1, bitmap_blocks: int = 0, max_mapnr: int = 0, total_ram_blocks: int = 0, device_blocks: int = 0, written_blocks: int = 0, current_cpu: int = 0, nr_cpus: int = 1) → None

class kdumpling.kdump_compressed.KdumpSubHeader(phys_base: int = 0, dump_level: int = 0, split: int = 0, start_pfn: int = 0, end_pfn: int = 0, offset_vmcoreinfo: int = 0, size_vmcoreinfo: int = 0, offset_note: int = 0, size_note: int = 0, offset_eraseinfo: int = 0, size_eraseinfo: int = 0, start_pfn_64: int = 0, end_pfn_64: int = 0, max_mapnr_64: int = 0)[source]

Bases: object

kdump_sub_header structure.

This is at offset 0x2000 in the file.

struct kdump_sub_header {: unsigned long phys_base; int dump_level; int split; unsigned long start_pfn; unsigned long end_pfn; off_t offset_vmcoreinfo; unsigned long size_vmcoreinfo; off_t offset_note; unsigned long size_note; off_t offset_eraseinfo; unsigned long size_eraseinfo; unsigned long long start_pfn_64; unsigned long long end_pfn_64; unsigned long long max_mapnr_64;

};

phys_base: int = 0

dump_level: int = 0

split: int = 0

start_pfn: int = 0

end_pfn: int = 0

offset_vmcoreinfo: int = 0

size_vmcoreinfo: int = 0

offset_note: int = 0

size_note: int = 0

offset_eraseinfo: int = 0

size_eraseinfo: int = 0

start_pfn_64: int = 0

end_pfn_64: int = 0

max_mapnr_64: int = 0

pack(endianness: ElfData) → bytes[source]: Pack the sub-header into bytes.

__init__(phys_base: int = 0, dump_level: int = 0, split: int = 0, start_pfn: int = 0, end_pfn: int = 0, offset_vmcoreinfo: int = 0, size_vmcoreinfo: int = 0, offset_note: int = 0, size_note: int = 0, offset_eraseinfo: int = 0, size_eraseinfo: int = 0, start_pfn_64: int = 0, end_pfn_64: int = 0, max_mapnr_64: int = 0) → None

class kdumpling.kdump_compressed.PageDescriptor(offset: int = 0, size: int = 0, flags: int = 0, page_flags: int = 0)[source]

Bases: object

page_desc structure describing a single page.

struct page_desc {: off_t offset; // File offset of page data unsigned int size; // Size of compressed data (or page_size if not compressed) unsigned int flags; // Page flags (compression type, etc.) unsigned long long page_flags; // Kernel page flags

};

offset: int = 0

size: int = 0

flags: int = 0

page_flags: int = 0

pack(endianness: ElfData) → bytes[source]: Pack the page descriptor into bytes.

__init__(offset: int = 0, size: int = 0, flags: int = 0, page_flags: int = 0) → None

kdumpling.kdump_compressed.compress_page(data: bytes, method: CompressionMethod, level: int = 6) → tuple[bytes, bool][source]

Compress a page of data.

Parameters:

data – Page data to compress
method – Compression method to use
level – Compression level (1-9 for zlib/zstd)

Returns:

Tuple of (compressed_data, was_compressed) If compression doesn’t reduce size, returns original data with False.

kdumpling.kdump_compressed.is_zero_page(data: bytes) → bool[source]: Check if a page is all zeros.

kdumpling.kdump_compressed.write_kdump_compressed(output_path: str, segments: list[MemorySegment], vmcoreinfo: bytes, notes_data: bytes, arch_info: ArchInfo, compression: CompressionMethod = CompressionMethod.COMPRESS_ZLIB, dump_level: int = <DumpLevel.DL_EXCLUDE_ZERO: 1>, compression_level: int = 6, osrelease: str = '') → None[source]

Write a kdump compressed format file.

Parameters:

output_path – Path to write the dump file
segments – List of memory segments to include
vmcoreinfo – VMCOREINFO data
notes_data – Pre-built notes section (NT_PRSTATUS, etc.)
arch_info – Architecture information
compression – Compression method to use
dump_level – Page filtering level
compression_level – Compression level (1-9)
osrelease – Kernel release string for header