From 040c74e6998a60635b8600195aa26b43ec57c1f1 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 29 Jan 2026 13:05:46 +0000 Subject: [PATCH 1/4] Remove WIP warning and fix PyPI badge on GitHub - Remove "work in progress" warning from docs homepage - Replace badge.fury.io badge with shields.io for PyPI version (badge.fury.io doesn't render on GitHub due to referrer policy) https://claude.ai/code/session_012eUQJKwLLveY4fc57kZcGw --- README.md | 2 +- docs/index.md | 4 ---- 2 files changed, 1 insertion(+), 5 deletions(-) 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/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: From 1fc962ee53e2bfff310dd003ddafd9254a1dc69c Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 29 Jan 2026 13:08:37 +0000 Subject: [PATCH 2/4] Add documentation for kdump compressed format support - Document OutputFormat and CompressionType enums in API reference - Update write() method signature with format/compression parameters - Add "Compressed Output" section to quickstart guide with examples - Document available compression types and their requirements https://claude.ai/code/session_012eUQJKwLLveY4fc57kZcGw --- docs/api.md | 46 +++++++++++++++++++++++++++++++++++++- docs/quickstart.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index b529e05..cb66635 100644 --- a/docs/api.md +++ b/docs/api.md @@ -79,13 +79,22 @@ Add CPU register state for a processor. #### write ```python -def write(self, output_path: str) -> None +def write( + self, + output_path: str, + format: OutputFormat = OutputFormat.ELF, + compression: CompressionType = CompressionType.ZLIB, + compression_level: int = 6 +) -> None ``` Write the vmcore file to disk. **Parameters:** - `output_path`: Path where the vmcore file will be written +- `format`: Output format (`OutputFormat.ELF` or `OutputFormat.KDUMP_COMPRESSED`). Default is ELF. +- `compression`: Compression type for KDUMP_COMPRESSED format. See `CompressionType`. Default is ZLIB. Ignored for ELF format. +- `compression_level`: Compression level 1-9. Default is 6. Higher values give better compression but are slower. Ignored for ELF format. ### Properties @@ -145,6 +154,41 @@ print(builder.stats) --- +## OutputFormat + +Output format options for vmcore files. + +```python +from kdumpling import OutputFormat +``` + +| Value | Description | +|-------|-------------| +| `OutputFormat.ELF` | Standard ELF64 vmcore (default). Compatible with all tools. | +| `OutputFormat.KDUMP_COMPRESSED` | Kdump compressed format (makedumpfile compatible). Provides per-page compression and filtering. | + +--- + +## CompressionType + +Compression algorithms for the kdump compressed format. + +```python +from kdumpling import CompressionType +``` + +| Value | Description | +|-------|-------------| +| `CompressionType.NONE` | No compression (dump level filtering only) | +| `CompressionType.ZLIB` | zlib/gzip compression (default, always available) | +| `CompressionType.LZO` | LZO compression (requires `python-lzo` package) | +| `CompressionType.SNAPPY` | Snappy compression (requires `python-snappy` package) | +| `CompressionType.ZSTD` | Zstandard compression (requires `zstandard` package) | + +**Note:** If an optional compression library is not installed, the writer will fall back to storing pages uncompressed. + +--- + ## CpuContext CPU context for a single processor (used internally). 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: From 606b75ddb9372eb6dcf877b9ce91445f08005a97 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 29 Jan 2026 14:17:54 +0000 Subject: [PATCH 3/4] Complete API documentation and add Sphinx autodoc support - Document add_custom_note, add_metadata, add_annotations methods - Add CustomNote and CustomNoteType documentation - Configure Sphinx autodoc with package path and napoleon settings - Create api-reference.md with auto-generated docs from docstrings - Add api-reference to table of contents The autodoc setup allows documentation to be generated directly from source code docstrings, helping keep docs in sync with implementation. https://claude.ai/code/session_012eUQJKwLLveY4fc57kZcGw --- docs/api-reference.md | 50 +++++++++++++++ docs/api.md | 138 ++++++++++++++++++++++++++++++++++++++++++ docs/conf.py | 30 +++++++++ docs/index.md | 1 + 4 files changed, 219 insertions(+) create mode 100644 docs/api-reference.md diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 0000000..4c482ad --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,50 @@ +# Auto-generated API Reference + +This page is auto-generated from the source code docstrings using Sphinx autodoc. +For a more curated guide, see the [API Reference](api.md). + +## kdumpling module + +```{eval-rst} +.. automodule:: kdumpling + :members: + :undoc-members: + :show-inheritance: + :imported-members: +``` + +## kdumpling.builder module + +```{eval-rst} +.. automodule:: kdumpling.builder + :members: + :undoc-members: + :show-inheritance: +``` + +## kdumpling.cpu_context module + +```{eval-rst} +.. automodule:: kdumpling.cpu_context + :members: + :undoc-members: + :show-inheritance: +``` + +## kdumpling.elf module + +```{eval-rst} +.. automodule:: kdumpling.elf + :members: + :undoc-members: + :show-inheritance: +``` + +## kdumpling.kdump_compressed module + +```{eval-rst} +.. automodule:: kdumpling.kdump_compressed + :members: + :undoc-members: + :show-inheritance: +``` diff --git a/docs/api.md b/docs/api.md index cb66635..70cb337 100644 --- a/docs/api.md +++ b/docs/api.md @@ -76,6 +76,93 @@ Add CPU register state for a processor. **Returns:** `self` for method chaining +#### add_custom_note + +```python +def add_custom_note( + self, + name: bytes | str, + note_type: int, + data: bytes | str +) -> KdumpBuilder +``` + +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:** +```python +builder.add_custom_note( + name=b"KDUMPLING", + note_type=CustomNoteType.METADATA, + data=b"sha256=abc123..." +) +``` + +#### add_metadata + +```python +def add_metadata( + self, + data: dict[str, str] | bytes | str, + vendor: bytes | str = b"KDUMPLING" +) -> KdumpBuilder +``` + +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=value\n"` format) + - `bytes`/`str`: Raw metadata content +- `vendor`: Vendor name for the note (default: `"KDUMPLING"`) + +**Returns:** `self` for method chaining + +**Example:** +```python +builder.add_metadata({ + "sha256": "abc123...", + "created_at": "2024-01-28T10:30:00Z", + "source": "memory_forensics_tool" +}) +``` + +#### add_annotations + +```python +def add_annotations( + self, + annotations: dict[str, str], + vendor: bytes | str = b"KDUMPLING" +) -> KdumpBuilder +``` + +Add custom annotations to the vmcore. Annotations are free-form key-value pairs for attaching 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:** +```python +builder.add_annotations({ + "hostname": "prod-server-01", + "kernel_panic_reason": "out of memory", + "captured_by": "crash_collector v2.1" +}) +``` + #### write ```python @@ -189,6 +276,57 @@ from kdumpling import CompressionType --- +## CustomNote + +A custom ELF note to be included in the vmcore. + +```python +from kdumpling import CustomNote +``` + +Custom notes allow users to embed additional metadata in their vmcore files, such as hashes, timestamps, annotations, or any other application-specific data. + +### Attributes + +| Attribute | Type | Description | +|-----------|------|-------------| +| `name` | `bytes` | Vendor/namespace identifier (e.g., `b"KDUMPLING"`) | +| `note_type` | `int` | Note type (see `CustomNoteType` for predefined values) | +| `data` | `bytes` | Note descriptor data | + +### Example + +```python +from kdumpling import CustomNote, CustomNoteType + +note = CustomNote( + name=b"KDUMPLING", + note_type=CustomNoteType.METADATA, + data=b"sha256=abc123..." +) +``` + +--- + +## CustomNoteType + +Predefined custom note types for kdumpling metadata. + +```python +from kdumpling import CustomNoteType +``` + +| Value | Description | +|-------|-------------| +| `CustomNoteType.METADATA` | Hash/signature information (value: 1) | +| `CustomNoteType.ANNOTATIONS` | Custom key-value annotations (value: 2) | +| `CustomNoteType.FILE_INFO` | File description information (value: 3) | +| `CustomNoteType.USER_DEFINED` | Start of user-defined range (value: 256) | + +Users can also use any integer value for custom types beyond the predefined ones. + +--- + ## CpuContext CPU context for a single processor (used internally). 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 640e225..b900137 100644 --- a/docs/index.md +++ b/docs/index.md @@ -60,4 +60,5 @@ pip install kdumpling quickstart api +api-reference ``` From 5036a9fb55f9b7f57641aa8e96e23a7654151d25 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 29 Jan 2026 14:38:14 +0000 Subject: [PATCH 4/4] Replace hand-written API docs with autodoc-generated version Removes duplicate documentation in favor of the auto-generated API reference. This ensures documentation stays in sync with code changes since it's generated directly from docstrings. https://claude.ai/code/session_012eUQJKwLLveY4fc57kZcGw --- docs/api-reference.md | 50 ------ docs/api.md | 398 ++++-------------------------------------- docs/index.md | 1 - 3 files changed, 32 insertions(+), 417 deletions(-) delete mode 100644 docs/api-reference.md diff --git a/docs/api-reference.md b/docs/api-reference.md deleted file mode 100644 index 4c482ad..0000000 --- a/docs/api-reference.md +++ /dev/null @@ -1,50 +0,0 @@ -# Auto-generated API Reference - -This page is auto-generated from the source code docstrings using Sphinx autodoc. -For a more curated guide, see the [API Reference](api.md). - -## kdumpling module - -```{eval-rst} -.. automodule:: kdumpling - :members: - :undoc-members: - :show-inheritance: - :imported-members: -``` - -## kdumpling.builder module - -```{eval-rst} -.. automodule:: kdumpling.builder - :members: - :undoc-members: - :show-inheritance: -``` - -## kdumpling.cpu_context module - -```{eval-rst} -.. automodule:: kdumpling.cpu_context - :members: - :undoc-members: - :show-inheritance: -``` - -## kdumpling.elf module - -```{eval-rst} -.. automodule:: kdumpling.elf - :members: - :undoc-members: - :show-inheritance: -``` - -## kdumpling.kdump_compressed module - -```{eval-rst} -.. automodule:: kdumpling.kdump_compressed - :members: - :undoc-members: - :show-inheritance: -``` diff --git a/docs/api.md b/docs/api.md index 70cb337..dfe5c5f 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,383 +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 - -#### add_custom_note - -```python -def add_custom_note( - self, - name: bytes | str, - note_type: int, - data: bytes | str -) -> KdumpBuilder -``` - -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:** -```python -builder.add_custom_note( - name=b"KDUMPLING", - note_type=CustomNoteType.METADATA, - data=b"sha256=abc123..." -) -``` - -#### add_metadata - -```python -def add_metadata( - self, - data: dict[str, str] | bytes | str, - vendor: bytes | str = b"KDUMPLING" -) -> KdumpBuilder -``` - -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=value\n"` format) - - `bytes`/`str`: Raw metadata content -- `vendor`: Vendor name for the note (default: `"KDUMPLING"`) - -**Returns:** `self` for method chaining - -**Example:** -```python -builder.add_metadata({ - "sha256": "abc123...", - "created_at": "2024-01-28T10:30:00Z", - "source": "memory_forensics_tool" -}) -``` - -#### add_annotations - -```python -def add_annotations( - self, - annotations: dict[str, str], - vendor: bytes | str = b"KDUMPLING" -) -> KdumpBuilder -``` - -Add custom annotations to the vmcore. Annotations are free-form key-value pairs for attaching 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:** -```python -builder.add_annotations({ - "hostname": "prod-server-01", - "kernel_panic_reason": "out of memory", - "captured_by": "crash_collector v2.1" -}) -``` - -#### write - -```python -def write( - self, - output_path: str, - format: OutputFormat = OutputFormat.ELF, - compression: CompressionType = CompressionType.ZLIB, - compression_level: int = 6 -) -> None -``` - -Write the vmcore file to disk. - -**Parameters:** -- `output_path`: Path where the vmcore file will be written -- `format`: Output format (`OutputFormat.ELF` or `OutputFormat.KDUMP_COMPRESSED`). Default is ELF. -- `compression`: Compression type for KDUMP_COMPRESSED format. See `CompressionType`. Default is ZLIB. Ignored for ELF format. -- `compression_level`: Compression level 1-9. Default is 6. Higher values give better compression but are slower. Ignored for ELF format. - -### Properties - -#### stats - -```python -@property -def stats(self) -> DumpStats -``` - -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) -# ... -``` - ---- - -## OutputFormat - -Output format options for vmcore files. - -```python -from kdumpling import OutputFormat -``` - -| Value | Description | -|-------|-------------| -| `OutputFormat.ELF` | Standard ELF64 vmcore (default). Compatible with all tools. | -| `OutputFormat.KDUMP_COMPRESSED` | Kdump compressed format (makedumpfile compatible). Provides per-page compression and filtering. | - ---- - -## CompressionType - -Compression algorithms for the kdump compressed format. - -```python -from kdumpling import CompressionType -``` - -| Value | Description | -|-------|-------------| -| `CompressionType.NONE` | No compression (dump level filtering only) | -| `CompressionType.ZLIB` | zlib/gzip compression (default, always available) | -| `CompressionType.LZO` | LZO compression (requires `python-lzo` package) | -| `CompressionType.SNAPPY` | Snappy compression (requires `python-snappy` package) | -| `CompressionType.ZSTD` | Zstandard compression (requires `zstandard` package) | - -**Note:** If an optional compression library is not installed, the writer will fall back to storing pages uncompressed. - ---- - -## CustomNote - -A custom ELF note to be included in the vmcore. - -```python -from kdumpling import CustomNote -``` - -Custom notes allow users to embed additional metadata in their vmcore files, such as hashes, timestamps, annotations, or any other application-specific data. - -### Attributes - -| Attribute | Type | Description | -|-----------|------|-------------| -| `name` | `bytes` | Vendor/namespace identifier (e.g., `b"KDUMPLING"`) | -| `note_type` | `int` | Note type (see `CustomNoteType` for predefined values) | -| `data` | `bytes` | Note descriptor data | - -### Example - -```python -from kdumpling import CustomNote, CustomNoteType - -note = CustomNote( - name=b"KDUMPLING", - note_type=CustomNoteType.METADATA, - data=b"sha256=abc123..." -) -``` - ---- - -## CustomNoteType - -Predefined custom note types for kdumpling metadata. - -```python -from kdumpling import CustomNoteType -``` - -| Value | Description | -|-------|-------------| -| `CustomNoteType.METADATA` | Hash/signature information (value: 1) | -| `CustomNoteType.ANNOTATIONS` | Custom key-value annotations (value: 2) | -| `CustomNoteType.FILE_INFO` | File description information (value: 3) | -| `CustomNoteType.USER_DEFINED` | Start of user-defined range (value: 256) | - -Users can also use any integer value for custom types beyond the predefined ones. - ---- - -## CpuContext - -CPU context for a single processor (used internally). - -```python -from kdumpling import CpuContext +```{eval-rst} +.. automodule:: kdumpling.cpu_context + :members: + :undoc-members: + :show-inheritance: ``` -### 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 | +## kdumpling.elf module ---- - -## 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 +```{eval-rst} +.. automodule:: kdumpling.elf + :members: + :undoc-members: + :show-inheritance: ``` -### 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/index.md b/docs/index.md index b900137..640e225 100644 --- a/docs/index.md +++ b/docs/index.md @@ -60,5 +60,4 @@ pip install kdumpling quickstart api -api-reference ```