diff --git a/README.md b/README.md index 05c3fb1..0597a37 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ CI Codecov Documentation - PyPI version + PyPI version Python versions License: MIT

diff --git a/docs/api.md b/docs/api.md index b529e05..dfe5c5f 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,201 +1,49 @@ # API Reference -## KdumpBuilder +This page is auto-generated from the source code docstrings using Sphinx autodoc. -The main class for building vmcore files. +## kdumpling module -```python -from kdumpling import KdumpBuilder +```{eval-rst} +.. automodule:: kdumpling + :members: + :undoc-members: + :show-inheritance: + :imported-members: ``` -### Constructor +## kdumpling.builder module -```python -KdumpBuilder(arch: str = 'x86_64') +```{eval-rst} +.. automodule:: kdumpling.builder + :members: + :undoc-members: + :show-inheritance: ``` -**Parameters:** -- `arch`: Target architecture. One of: `x86_64`, `aarch64`, `arm64`, `s390x`, `ppc64le`, `ppc64`, `riscv64` +## kdumpling.cpu_context module -**Raises:** -- `ValueError`: If the architecture is not supported - -### Methods - -#### set_vmcoreinfo - -```python -def set_vmcoreinfo(self, data: str | bytes) -> KdumpBuilder -``` - -Set the VMCOREINFO metadata string. - -**Parameters:** -- `data`: The vmcoreinfo string (e.g., `"OSRELEASE=5.14.0\nPAGESIZE=4096\n"`) - -**Returns:** `self` for method chaining - -#### add_memory_segment - -```python -def add_memory_segment(self, phys_addr: int, data: bytes | str | BinaryIO) -> KdumpBuilder -``` - -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 - -**Returns:** `self` for method chaining - -#### add_cpu_context - -```python -def add_cpu_context( - self, - cpu_id: int = 0, - registers: dict[str, int] | None = None, - pid: int = 0, - **kwargs: int -) -> KdumpBuilder -``` - -Add CPU register state for a processor. - -**Parameters:** -- `cpu_id`: CPU identifier (0-indexed) -- `registers`: Dictionary mapping register names to values - - For x86_64: `RIP`, `RSP`, `RBP`, `RAX`, `RBX`, `RCX`, `RDX`, `RSI`, `RDI`, `R8`-`R15`, etc. - - For aarch64: `X0`-`X30`, `SP`, `PC`, `PSTATE` -- `pid`: Process ID associated with this CPU -- `**kwargs`: Additional prstatus fields (`pr_ppid`, `pr_pgrp`, `pr_sid`, `si_signo`, etc.) - -**Returns:** `self` for method chaining - -#### write - -```python -def write(self, output_path: str) -> None +```{eval-rst} +.. automodule:: kdumpling.cpu_context + :members: + :undoc-members: + :show-inheritance: ``` -Write the vmcore file to disk. +## kdumpling.elf module -**Parameters:** -- `output_path`: Path where the vmcore file will be written - -### Properties - -#### stats - -```python -@property -def stats(self) -> DumpStats +```{eval-rst} +.. automodule:: kdumpling.elf + :members: + :undoc-members: + :show-inheritance: ``` -Get statistics about the dump being built. - -**Returns:** `DumpStats` object with information about segments, size, etc. - ---- - -## DumpStats - -Statistics about a vmcore dump being built. - -```python -from kdumpling import DumpStats -``` - -### Attributes - -| Attribute | Type | Description | -|-----------|------|-------------| -| `architecture` | `str` | Target architecture | -| `num_memory_segments` | `int` | Number of memory segments | -| `num_cpu_contexts` | `int` | Number of CPU contexts | -| `total_memory_size` | `int` | Total memory size in bytes | -| `vmcoreinfo_size` | `int` | Size of vmcoreinfo in bytes | -| `estimated_file_size` | `int` | Estimated output file size | -| `memory_segments` | `list[tuple[int, int]]` | List of (phys_addr, size) tuples | - -### Properties - -| Property | Type | Description | -|----------|------|-------------| -| `total_memory_size_human` | `str` | Human-readable memory size (e.g., "4.0 MB") | -| `estimated_file_size_human` | `str` | Human-readable file size | - -### String Representation - -`DumpStats` has a `__str__` method that provides a formatted summary: - -```python -print(builder.stats) -# Dump Statistics: -# Architecture: x86_64 -# Memory Segments: 2 -# CPU Contexts: 1 -# Total Memory: 8.0 KB (8192 bytes) -# ... -``` - ---- - -## CpuContext - -CPU context for a single processor (used internally). - -```python -from kdumpling import CpuContext -``` - -### Attributes - -| Attribute | Type | Description | -|-----------|------|-------------| -| `cpu_id` | `int` | CPU identifier | -| `pid` | `int` | Process ID | -| `registers` | `dict[str, int]` | Register name to value mapping | -| `si_signo` | `int` | Signal number | -| `pr_pid` | `int` | Process ID in prstatus | -| `pr_ppid` | `int` | Parent process ID | - ---- - -## Register Enums - -### X86_64Reg - -Register indices for x86_64 architecture. - -```python -from kdumpling import X86_64Reg - -# Available registers: -X86_64Reg.RIP # Instruction pointer -X86_64Reg.RSP # Stack pointer -X86_64Reg.RBP # Base pointer -X86_64Reg.RAX, X86_64Reg.RBX, X86_64Reg.RCX, X86_64Reg.RDX -X86_64Reg.RSI, X86_64Reg.RDI -X86_64Reg.R8, X86_64Reg.R9, X86_64Reg.R10, X86_64Reg.R11 -X86_64Reg.R12, X86_64Reg.R13, X86_64Reg.R14, X86_64Reg.R15 -# ... and more -``` - -### AArch64Reg - -Register indices for AArch64 (ARM64) architecture. - -```python -from kdumpling import AArch64Reg +## kdumpling.kdump_compressed module -# Available registers: -AArch64Reg.X0 through AArch64Reg.X30 -AArch64Reg.SP # Stack pointer -AArch64Reg.PC # Program counter -AArch64Reg.PSTATE # Processor state +```{eval-rst} +.. automodule:: kdumpling.kdump_compressed + :members: + :undoc-members: + :show-inheritance: ``` diff --git a/docs/conf.py b/docs/conf.py index dca03a1..644f75f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,5 +1,11 @@ # Configuration file for the Sphinx documentation builder. +import os +import sys + +# Add the package to the path for autodoc +sys.path.insert(0, os.path.abspath("..")) + project = "kdumpling" copyright = "2024, kdumpling contributors" author = "kdumpling contributors" @@ -36,3 +42,27 @@ ".rst": "restructuredtext", ".md": "markdown", } + +# Autodoc configuration +autodoc_default_options = { + "members": True, + "member-order": "bysource", + "special-members": "__init__", + "undoc-members": True, + "exclude-members": "__weakref__", + "show-inheritance": True, +} + +# Napoleon settings for Google/NumPy style docstrings +napoleon_google_docstring = True +napoleon_numpy_docstring = True +napoleon_include_init_with_doc = True +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = True +napoleon_use_admonition_for_examples = True +napoleon_use_admonition_for_notes = True +napoleon_use_admonition_for_references = False +napoleon_use_ivar = False +napoleon_use_param = True +napoleon_use_rtype = True +napoleon_type_aliases = None diff --git a/docs/index.md b/docs/index.md index 0e7501e..640e225 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,10 +8,6 @@ A Python library for creating Linux kdump crash dump files. -```{warning} -This library is currently a work in progress. The API may change in future releases. -``` - ## Overview **kdumpling** allows you to synthesize valid ELF64 vmcore files from raw memory data and vmcoreinfo values. This is useful for: diff --git a/docs/quickstart.md b/docs/quickstart.md index 7c4048e..2ab2b7a 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -99,6 +99,61 @@ Dump Statistics: 0x0000000000100000: 4.0 MB ``` +## Compressed Output + +kdumpling supports the kdump compressed format, which is compatible with makedumpfile and tools like crash, libkdumpfile, and drgn. This format provides per-page compression and can significantly reduce file sizes. + +### Basic Compressed Output + +```python +from kdumpling import KdumpBuilder, OutputFormat, CompressionType + +builder = KdumpBuilder(arch='x86_64') +builder.set_vmcoreinfo("OSRELEASE=5.14.0\nPAGESIZE=4096\n") +builder.add_memory_segment(0x100000, b'\x00' * 4096 * 100) # 400KB + +# Write in kdump compressed format with zlib compression +builder.write( + "compressed.vmcore", + format=OutputFormat.KDUMP_COMPRESSED, + compression=CompressionType.ZLIB +) +``` + +### Compression Options + +```python +from kdumpling import KdumpBuilder, OutputFormat, CompressionType + +builder = KdumpBuilder(arch='x86_64') +builder.set_vmcoreinfo("OSRELEASE=5.14.0\n") +builder.add_memory_segment(0x100000, memory_data) + +# No compression (still filters zero pages) +builder.write("dump.vmcore", format=OutputFormat.KDUMP_COMPRESSED, + compression=CompressionType.NONE) + +# Zlib compression (default, always available) +builder.write("dump.vmcore", format=OutputFormat.KDUMP_COMPRESSED, + compression=CompressionType.ZLIB, compression_level=9) + +# Zstandard compression (requires 'zstandard' package) +builder.write("dump.vmcore", format=OutputFormat.KDUMP_COMPRESSED, + compression=CompressionType.ZSTD) +``` + +### Available Compression Types + +| Type | Description | Requirement | +|------|-------------|-------------| +| `CompressionType.NONE` | No compression | None | +| `CompressionType.ZLIB` | zlib/gzip (default) | None (built-in) | +| `CompressionType.LZO` | LZO compression | `python-lzo` | +| `CompressionType.SNAPPY` | Snappy compression | `python-snappy` | +| `CompressionType.ZSTD` | Zstandard compression | `zstandard` | + +The compressed format automatically excludes zero-filled pages, reducing output size even without compression. + ## Supported Architectures kdumpling supports the following architectures: