pykdebugparser 1.2.7__tar.gz → 1.3.0__tar.gz

{pykdebugparser-1.2.7 → pykdebugparser-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pykdebugparser
-Version: 1.2.7
+Version: 1.3.0
 Summary: Python parser for kdebug events
 Author: Matan Perelman
 Author-email: matan1008@gmail.com
@@ -28,16 +28,17 @@ License: MIT License
         
 Project-URL: Homepage, https://github.com/matan1008/pykdebugparser
 Project-URL: Source, https://github.com/matan1008/pykdebugparser
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: construct
+Requires-Dist: bytestruct>=0.1.0
 Requires-Dist: pygments
 Requires-Dist: click
 Requires-Dist: termcolor

pykdebugparser-1.3.0/pykdebugparser/kd_buf_parser.py

@@ -0,0 +1,314 @@
+from dataclasses import dataclass, field
+import io
+import plistlib
+import struct
+from collections import namedtuple
+from typing import Annotated, Any
+
+from bytestruct import GREEDY_BYTES, U64_LE, BinaryParseError, BinaryStruct, ByteReader, Bytes, CodecBase, \
+    PaddedString, Prefixed, TruncatedDataError, u32, u64
+
+from pykdebugparser.kevent import from_kd_buf, from_kd_bufs, KD_BUF_FORMAT
+from pykdebugparser.os_log_event import OsLogEvent
+
+KEVENT_SIZE = struct.calcsize(KD_BUF_FORMAT)
+# Upper bound for a single bulk read of kevents.
+KEVENTS_READ_SIZE = KEVENT_SIZE * 1024
+
+ProcessData = namedtuple('ProcessData', ['pid', 'name'])
+
+RAW_VERSION_SIZE = 4
+RAW_VERSION2_BYTES = b'\x00\x02\xaa\x55'
+RAW_VERSION3_BYTES = b'\x00\x03\xaa\x55'
+# Header flag of a 64-bit kernel.
+KDBG_LP64 = 0x1
+TRACEV3_STACKSHOT_END = b'stackshot_out_fl'
+TRACEV3_THREADMAP_TAG = b'\x00\x1d\x00\x00\x00\x00\x00\x00'
+TRACEV3_EVENTS_TAG = b'\x00\x1e\x00\x00\x00\x00\x00\x00'
+TRACEV3_MORE_EVENTS = b'\x00\x20\x00\x00\x00\x00\x00\x00'
+TRACEV3_DYLD_MODULES = b'\x01\x80\x00\x00\x00\x00\x00\x00'
+TRACEV3_TRACE_CODES = b'\x0f\x80\x00\x00\x00\x00\x00\x00'
+TRACEV3_PROCESSES = b'\x10\x80\x00\x00\x00\x00\x00\x00'
+TRACEV3_LOG_EVENTS = b'\x11\x80\x00\x00\x00\x00\x00\x00'
+TRACEV3_LOG_STRINGS = b'\x12\x80\x00\x00\x00\x00\x00\x00'
+TRACEV3_KERNEL_EXTENSIONS = b'\x05\x80\x00\x00\x00\x00\x00\x00'
+TRACEV3_IMAGES = b'\x04\x80\x00\x00\x01\x00\x00\x00'
+
+
+class Bplist(CodecBase[Any]):
+    """
+    Codec for a plist (all remaining bytes).
+    """
+
+    def read(self, reader: ByteReader) -> Any:
+        return plistlib.loads(GREEDY_BYTES.read(reader))
+
+    def build(self, value: Any) -> bytes:
+        return plistlib.dumps(value)
+
+
+@dataclass
+class KdThreadmap(BinaryStruct, byte_order='<'):
+    tid: u64
+    pid: u32
+    process: Annotated[str, PaddedString(0x14)]
+
+
+@dataclass
+class KdHeaderV2(BinaryStruct, byte_order='<'):
+    """
+    Header of a trace version 2 (`RAW_VERSION2`), as written by kperf's `kperf_buffer_readdata`.
+    The fields up to `tod_usecs` follow XNU's `RAW_header`; kperf always writes the time of day as zero.
+    """
+    number_of_threads: u32
+    tod_secs: u64
+    tod_usecs: u32
+    flags: u32
+    tick_frequency: u64
+    # Never written by kperf, so it holds whatever the buffer contained before.
+    _unused: Annotated[bytes, Bytes(0x100)] = field(default=bytes(0x100), init=False, repr=False, compare=False)
+
+    @property
+    def is_64bit(self) -> bool:
+        return bool(self.flags & KDBG_LP64)
+
+
+@dataclass
+class KdHeaderV3(BinaryStruct, byte_order='<'):
+    tag: u32
+    sub_tag: u32
+    length: u64
+    timebase_numer: u32
+    timebase_denom: u32
+    timestamp: u64
+    walltime_secs: u64
+    walltime_usecs: u32
+    timezone_minuteswest: u32
+    timezone_dst: u32
+    flags: u32
+    tag2: u32
+    cpu_info: Annotated[Any, Prefixed(U64_LE, Bplist())]
+
+
+@dataclass
+class KdV3Block(BinaryStruct, byte_order='<'):
+    """
+    An additional data block of a trace version 3, aligned to 8 bytes (unless it is the last one).
+    """
+    tag: Annotated[bytes, Bytes(8)]
+    data: Annotated[bytes, Prefixed(U64_LE, GREEDY_BYTES)]
+
+
+def read_exactly(reader: io.IOBase, size: int) -> bytes:
+    """
+    Read exactly `size` bytes from a stream.
+    :param reader: Stream to read from.
+    :param size: Number of bytes to read.
+    :return: The data read.
+    :raises TruncatedDataError: The stream ended first.
+    """
+    data = reader.read(size)
+    if len(data) != size:
+        raise TruncatedDataError(f'expected {size} bytes, found {len(data)}')
+    return data
+
+
+def skip_zeros(reader: io.IOBase):
+    """
+    Skip zero bytes in a stream, leaving it at the first non-zero byte (or at its end).
+    Reads a byte at a time and seeks back once, so a stream never consumes data past the zeros.
+    :param reader: Stream to skip in.
+    """
+    while True:
+        position = reader.tell()
+        if reader.read(1) != b'\x00':
+            reader.seek(position, 0)
+            return
+
+
+def parse_threadmap(data: bytes) -> list:
+    """
+    Parse consecutive threadmap entries, stopping at the first one that can't be parsed.
+    :param data: Threadmap entries.
+    :return: Parsed entries.
+    """
+    reader = ByteReader(data)
+    threadmap = []
+    while reader.remaining:
+        try:
+            threadmap.append(KdThreadmap.read(reader))
+        except BinaryParseError:
+            break
+    return threadmap
+
+
+def parse_v3_blocks(data: bytes) -> list:
+    """
+    Parse the additional data blocks of a trace version 3, stopping at the first one that can't be parsed.
+    :param data: Additional data blocks.
+    :return: Parsed blocks.
+    """
+    reader = ByteReader(data)
+    blocks = []
+    while True:
+        try:
+            block = KdV3Block.read(reader)
+        except BinaryParseError:
+            break
+        blocks.append(block)
+        # The last block may be unpadded.
+        reader.skip(min(-(KdV3Block.SIZE + 8 + len(block.data)) % 8, reader.remaining))
+    return blocks
+
+
+def seek_until(reader, data: bytes):
+    """
+    Read from a stream until matching data.
+    Reading is aligned to the data size.
+    :param reader: Stream to read from.
+    :param data: Data to match.
+    """
+    found = reader.read(len(data))
+    while found != data:
+        found = found[1:] + reader.read(1)
+
+
+class KdBufParser:
+    """
+    Parser for raw kd_buf buffer.
+    """
+
+    def __init__(self, threads_pids=None, pids_names=None):
+        self.threads_pids = {} if threads_pids is None else threads_pids
+        self.pids_names = {} if pids_names is None else pids_names
+        self.versions = {
+            RAW_VERSION2_BYTES: self.parse_v2,
+            RAW_VERSION3_BYTES: self.parse_v3,
+        }
+        self.trace_codes = ''
+        self.images = {}
+        self.dyld_modules = {}
+        self.processes = {}
+        self.kernel_extensions = {'Binaries': []}
+        self.v3_header = None
+
+    def parse(self, reader: io.IOBase):
+        """
+        Parse kevents from a stream.
+        :param reader: Stream to read from.
+        :return: Generator for parsed kevents.
+        """
+        version = reader.read(RAW_VERSION_SIZE)
+        return self.versions[version](reader)
+
+    def set_thread_map(self, parsed_threadmap):
+        self.threads_pids.clear()
+        self.pids_names.clear()
+        for thread in parsed_threadmap:
+            self.threads_pids[thread.tid] = thread.pid
+            self.pids_names[thread.pid] = thread.process
+
+    def parse_v2(self, reader: io.IOBase):
+        """
+        Parse trace version 2.
+        :param reader: Stream to parse.
+        :return: Generator for parsed kevents.
+        """
+        header = KdHeaderV2.parse(read_exactly(reader, KdHeaderV2.SIZE))
+        self.set_thread_map([KdThreadmap.parse(read_exactly(reader, KdThreadmap.SIZE))
+                             for _ in range(header.number_of_threads)])
+        skip_zeros(reader)
+        read1 = getattr(reader, 'read1', None)
+        if read1 is None:
+            # Without `read1` a bigger `read` might block until more data than currently available arrives.
+            while True:
+                buf = reader.read(KEVENT_SIZE)
+                if not buf:
+                    break
+                yield from_kd_buf(buf)
+            return
+        # `read1` returns whatever is available, so kevents are decoded in bulk without delaying live streams.
+        leftover = b''
+        while True:
+            buf = read1(KEVENTS_READ_SIZE)
+            if not buf:
+                break
+            if leftover:
+                buf = leftover + buf
+            end = len(buf) - len(buf) % KEVENT_SIZE
+            if end != len(buf):
+                leftover = buf[end:]
+                buf = buf[:end]
+            else:
+                leftover = b''
+            yield from from_kd_bufs(buf)
+        if leftover:
+            # A truncated kevent, fail just like a non-bulk read would.
+            yield from_kd_buf(leftover)
+
+    def parse_v3(self, reader: io.IOBase):
+        """
+        Parse trace version 3.
+        :param reader: Stream to parse.
+        :return: Generator for parsed kevents.
+        """
+        header = read_exactly(reader, KdHeaderV3.SIZE + U64_LE.size)
+        header += read_exactly(reader, U64_LE.unpack_from(header, KdHeaderV3.SIZE)[0])
+        read_exactly(reader, -len(header) % 8)
+        self.v3_header = KdHeaderV3.parse(header)
+        # Align the reader to 8 bytes from the beginning of the stream
+        reader.read(8 - RAW_VERSION_SIZE)
+        # The threadmap tag appears randomly in the stackshot.
+        seek_until(reader, TRACEV3_STACKSHOT_END)
+        seek_until(reader, TRACEV3_THREADMAP_TAG)
+        threadmap_size = U64_LE.parse(read_exactly(reader, U64_LE.size))
+        self.set_thread_map(parse_threadmap(read_exactly(reader, threadmap_size)))
+
+        while True:
+            seek_until(reader, TRACEV3_EVENTS_TAG)
+            size = U64_LE.parse(read_exactly(reader, U64_LE.size))
+            reader.read(8)  # All zeros, unknown.
+            for _ in range(size // KEVENT_SIZE):
+                buf = reader.read(KEVENT_SIZE)
+                yield from_kd_buf(buf)
+            if reader.read(len(TRACEV3_MORE_EVENTS)) != TRACEV3_MORE_EVENTS:
+                break
+        reader.seek(-8, 1)
+
+        additional_data = parse_v3_blocks(reader.read())
+
+        self.trace_codes = ''
+        self.kernel_extensions = {'Binaries': []}
+        self.dyld_modules = {}
+        self.images = {}
+        self.processes = {}
+
+        log_events = []
+        log_strings = {}
+
+        for block in additional_data:
+            if block.tag == TRACEV3_DYLD_MODULES:
+                data = plistlib.loads(block.data)
+                if not self.dyld_modules:
+                    self.dyld_modules.update(data)
+                else:
+                    self.dyld_modules['Binaries'].extend(data['Binaries'])
+            elif block.tag == TRACEV3_TRACE_CODES:
+                self.trace_codes += block.data.decode()
+            elif block.tag == TRACEV3_PROCESSES:
+                self.processes = plistlib.loads(block.data)
+            elif block.tag == TRACEV3_KERNEL_EXTENSIONS:
+                self.kernel_extensions['Binaries'].extend(plistlib.loads(block.data)['Binaries'])
+            elif block.tag == TRACEV3_IMAGES:
+                self.images = plistlib.loads(block.data)
+            elif block.tag == TRACEV3_LOG_EVENTS:
+                log_events.extend(plistlib.loads(block.data)['Events'])
+            elif block.tag == TRACEV3_LOG_STRINGS:
+                log_strings = {v: k for k, v in plistlib.loads(block.data)['StringIndex'].items()}
+
+        for event in log_events:
+            log_event = OsLogEvent.from_raw_log_event(event, log_strings)
+            if log_event.process and log_event.thread_identifier:
+                self.threads_pids[log_event.thread_identifier] = log_event.process_identifier
+                self.pids_names[log_event.process_identifier] = log_event.process
+            yield log_event

pykdebugparser-1.3.0/pykdebugparser/kevent.py

@@ -0,0 +1,46 @@
+from collections import namedtuple
+import enum
+import struct
+
+KDBG_EVENTID_MASK = 0xfffffffc
+KDBG_FUNC_MASK = 0x00000003
+KD_BUF_FORMAT = '<Q32sQIIQ'
+# Same layout as `KD_BUF_FORMAT`, with the 32 bytes of arguments unpacked as 4 64-bit values.
+KD_BUF_STRUCT = struct.Struct('<QQQQQQIIQ')
+KD_BUF_SIZE = KD_BUF_STRUCT.size
+Kevent = namedtuple('Kevent', ['timestamp', 'data', 'values', 'tid', 'debugid', 'eventid', 'func_qualifier'])
+
+
+class DgbFuncQual(enum.Enum):
+    """
+    Event's role in the trace.
+    """
+    DBG_FUNC_NONE = 0
+    DBG_FUNC_START = 1
+    DBG_FUNC_END = 2
+    DBG_FUNC_ALL = 3
+
+
+def from_kd_buf(kd_buf: bytes) -> Kevent:
+    """
+    Create a Kevent object from a kd_buf kevent's struct.
+    :param kd_buf: Buffer of kd_buf kevent's struct.
+    :return: Parsed kevent.
+    """
+    timestamp, arg0, arg1, arg2, arg3, tid, debugid, cpuid, unused = KD_BUF_STRUCT.unpack(kd_buf)
+    return Kevent(timestamp, kd_buf[8:40], (arg0, arg1, arg2, arg3), tid, debugid, debugid & KDBG_EVENTID_MASK,
+                  debugid & KDBG_FUNC_MASK)
+
+
+def from_kd_bufs(kd_bufs: bytes):
+    """
+    Create Kevent objects from consecutive kd_buf kevent's structs.
+    :param kd_bufs: Buffer of kd_buf kevent's structs, its length must be a multiple of the struct size.
+    :return: Generator of parsed kevents.
+    """
+    new_kevent = tuple.__new__  # Skips the namedtuple's Python-level __new__, the result is identical.
+    offset = 8
+    for timestamp, arg0, arg1, arg2, arg3, tid, debugid, cpuid, unused in KD_BUF_STRUCT.iter_unpack(kd_bufs):
+        yield new_kevent(Kevent, (timestamp, kd_bufs[offset:offset + 32], (arg0, arg1, arg2, arg3), tid, debugid,
+                                  debugid & KDBG_EVENTID_MASK, debugid & KDBG_FUNC_MASK))
+        offset += KD_BUF_SIZE

{pykdebugparser-1.2.7 → pykdebugparser-1.3.0}/pykdebugparser/os_log_event.py

@@ -3,7 +3,7 @@ from datetime import datetime, timezone
 import enum
 from typing import List, Dict
 
-from construct import Struct, Byte, Int32ul, BitStruct, Padding, Flag, BitsInteger, Int64ul
+from bytestruct import U64_LE, BinaryStruct, u8, u32
 
 
 class OsLogType(enum.Enum):
@@ -81,7 +81,7 @@ class FirehoseTracepointSignpostType(enum.IntFlag):
     scope_system = 0xc0
 
 
-class FirehoseTracepointSingpostFlags(enum.Enum):
+class FirehoseTracepointSingpostFlags(enum.IntFlag):
     has_private_data = 1
     has_subsystem = 2
     has_rules = 4
@@ -100,22 +100,24 @@ tracepoint_types = {
 
 tracepoint_flags = {
     FirehoseTracepointNamespace.log: FirehoseTracepointLogFlags,
-    FirehoseTracepointNamespace.trace: FirehoseTracepointSingpostFlags,
+    FirehoseTracepointNamespace.signpost: FirehoseTracepointSingpostFlags,
 }
 
-firehose_tracepoint_id = Struct(
-    'namespace' / Byte,
-    'type_' / Byte,
-    'trace_flags' / BitStruct(
-        Padding(2),
-        'has_large_offset' / Flag,
-        'has_unique_pid' / Flag,
-        'pc_style' / BitsInteger(3),
-        'has_current_aid' / Flag,
-    ),
-    'flags' / Byte,
-    'code' / Int32ul,
-)
+# `trace_flags` bits.
+TRACE_FLAGS_HAS_LARGE_OFFSET = 0x20
+TRACE_FLAGS_HAS_UNIQUE_PID = 0x10
+TRACE_FLAGS_PC_STYLE_SHIFT = 1
+TRACE_FLAGS_PC_STYLE_MASK = 0x7
+TRACE_FLAGS_HAS_CURRENT_AID = 0x01
+
+
+@dataclass
+class FirehoseTracepointId(BinaryStruct, byte_order='<'):
+    namespace: u8
+    type_: u8
+    trace_flags: u8
+    flags: u8
+    code: u32
 
 
 @dataclass
@@ -262,7 +264,8 @@ class OsLogEvent:
 
     @classmethod
     def parse_trace_identifier(cls, trace_identifier):
-        trace_id = firehose_tracepoint_id.parse(Int64ul.build(trace_identifier))
+        trace_id = FirehoseTracepointId.parse(U64_LE.build(trace_identifier))
+        trace_flags = trace_id.trace_flags
         trace_namespace = FirehoseTracepointNamespace(trace_id.namespace)
         if trace_namespace in tracepoint_types:
             type_ = tracepoint_types[trace_namespace](trace_id.type_)
@@ -275,10 +278,10 @@ class OsLogEvent:
         return TraceIdentifier(
             namespace=trace_namespace,
             type_=type_,
-            has_large_offset=trace_id.trace_flags.has_large_offset,
-            has_unique_pid=trace_id.trace_flags.has_unique_pid,
-            pc_style=FirehoseTracepointFlagsPcStyle(trace_id.trace_flags.pc_style),
-            has_current_aid=trace_id.trace_flags.has_current_aid,
+            has_large_offset=bool(trace_flags & TRACE_FLAGS_HAS_LARGE_OFFSET),
+            has_unique_pid=bool(trace_flags & TRACE_FLAGS_HAS_UNIQUE_PID),
+            pc_style=FirehoseTracepointFlagsPcStyle((trace_flags >> TRACE_FLAGS_PC_STYLE_SHIFT) & TRACE_FLAGS_PC_STYLE_MASK),
+            has_current_aid=bool(trace_flags & TRACE_FLAGS_HAS_CURRENT_AID),
             flags=tracepoint_flags[trace_namespace](
                 trace_id.flags) if trace_namespace in tracepoint_flags else None,
             code=trace_id.code,

{pykdebugparser-1.2.7 → pykdebugparser-1.3.0}/pykdebugparser/pykdebugparser.py

@@ -1,5 +1,6 @@
 from datetime import datetime
 import io
+import math
 
 from pygments import highlight, lexers, formatters
 from termcolor import colored
@@ -25,6 +26,8 @@ class PyKdebugParser:
         self.filter_process = None
         self.filter_class = []
         self.filter_subclass = []
+        # Event ids (debugids without the function qualifier) to include, on top of the class/subclass filters.
+        self.filter_eventid = set()
         self.show_timestamp = True
         self.show_name = True
         self.show_func_qual = True
@@ -41,15 +44,29 @@ class PyKdebugParser:
         self.pids_names = {}
         self.dyld_addresses = []
         self.dyld_uuids = []
+        self._timestamp_cache = None
 
     def kevents(self, kdebug: io.IOBase):
         events_generator = KdBufParser(self.threads_pids, self.pids_names).parse(kdebug)
-        events_generator = filter(lambda e: not isinstance(e, OsLogEvent), events_generator)
-        if self.filter_tid is not None:
-            events_generator = filter(lambda e: e.tid == self.filter_tid, events_generator)
-        if self.filter_class or self.filter_subclass:
-            events_generator = filter(lambda e: self._is_eventid_allowed(e.eventid), events_generator)
-        return events_generator
+        return self._filter_kevents(events_generator, self.filter_tid is not None,
+                                    bool(self.filter_class or self.filter_subclass or self.filter_eventid))
+
+    def _filter_kevents(self, events_generator, by_tid, by_class):
+        # A single generator instead of a `filter` chain, avoiding a lambda call per kevent per filter.
+        filter_class = self.filter_class
+        filter_subclass = self.filter_subclass
+        filter_eventid = set(self.filter_eventid)
+        for event in events_generator:
+            if isinstance(event, OsLogEvent):
+                continue
+            if by_tid and event.tid != self.filter_tid:
+                continue
+            if by_class:
+                eventid = event.eventid
+                if not ((eventid >> 24 in filter_class) or (eventid >> 16 in filter_subclass)
+                        or eventid in filter_eventid):
+                    continue
+            yield event
 
     def formatted_kevents(self, kdebug: io.IOBase, trace_codes=None):
         trace_codes_map = default_trace_codes() if trace_codes is None else trace_codes
@@ -58,11 +75,12 @@ class PyKdebugParser:
     def traces(self, kdebug: io.IOBase, trace_codes=None):
         trace_codes_map = default_trace_codes() if trace_codes is None else trace_codes
 
-        has_filters = self.filter_class or self.filter_subclass
+        has_filters = self.filter_class or self.filter_subclass or self.filter_eventid
         add_trace_class = has_filters and DBG_TRACE not in self.filter_class
         if add_trace_class:
             self.filter_class.append(DBG_TRACE)
-        has_bsd = DBG_BSD in self.filter_class or any(filter(lambda sc: sc >> 8 == DBG_BSD, self.filter_subclass))
+        has_bsd = (DBG_BSD in self.filter_class or any(sc >> 8 == DBG_BSD for sc in self.filter_subclass)
+                   or any(eventid >> 24 == DBG_BSD for eventid in self.filter_eventid))
         add_fs_class = has_filters and has_bsd and DBG_FSYSTEM not in self.filter_class
         if add_fs_class:
             self.filter_class.append(DBG_FSYSTEM)
@@ -113,9 +131,22 @@ class PyKdebugParser:
         offset_usec = (
                 ((timestamp - self.mach_absolute_time) * self.numer) / (self.denom * 1000)
         )
-        ts = datetime.fromtimestamp((self.usecs_since_epoch + offset_usec) / 1000000, tz=self.timezone)
-        time_string = ts.strftime('%Y-%m-%d %H:%M:%S.%f')
-        return f'{time_string:<27}'
+        posix_time = (self.usecs_since_epoch + offset_usec) / 1000000
+        # Split to seconds and microseconds exactly like `datetime.fromtimestamp` does (round half to even), so
+        # the date and time part can be formatted only once per second.
+        fraction, seconds = math.modf(posix_time)
+        microseconds = round(fraction * 1000000)
+        if microseconds >= 1000000:
+            microseconds -= 1000000
+            seconds += 1.0
+        elif microseconds < 0:
+            microseconds += 1000000
+            seconds -= 1.0
+        cache = self._timestamp_cache
+        if cache is None or cache[0] != seconds or cache[1] is not self.timezone:
+            prefix = datetime.fromtimestamp(seconds, tz=self.timezone).strftime('%Y-%m-%d %H:%M:%S.')
+            cache = self._timestamp_cache = (seconds, self.timezone, prefix)
+        return f'{cache[2]}{microseconds:06d}'.ljust(27)
 
     def _format_process(self, tid):
         pid = self.threads_pids.get(tid, -1)
@@ -184,4 +215,5 @@ class PyKdebugParser:
         return event_rep
 
     def _is_eventid_allowed(self, event_id):
-        return (event_id >> 24 in self.filter_class) or (event_id >> 16 in self.filter_subclass)
+        return ((event_id >> 24 in self.filter_class) or (event_id >> 16 in self.filter_subclass)
+                or event_id in self.filter_eventid)

pykdebugparser-1.3.0/pykdebugparser/trace_codes.py

@@ -0,0 +1,52 @@
+from typing import Iterable, Mapping, Optional, Set
+from pathlib import Path
+
+
+def from_trace_codes_text(codes_text: str) -> Mapping[int, str]:
+    """
+    Convert a trace codes text to dictionary.
+    :param codes_text: Trace codes file data.
+    :return: Mapping between code and event name.
+    """
+    return {int(s[0], 16): s[1] for s in map(lambda l: l.split(), codes_text.splitlines())}
+
+
+def from_trace_codes_file(path: str) -> Mapping[int, str]:
+    """
+    Read trace codes from a file.
+    :param path: Trace codes file path.
+    :return: Mapping between code and event name.
+    """
+    with open(path, 'r') as fd:
+        return from_trace_codes_text(fd.read())
+
+
+def default_trace_codes() -> Mapping[int, str]:
+    """
+    Get the default trace codes mapping.
+    :return: Mapping between code and event name.
+    """
+    with open(Path(__file__).resolve().parent.joinpath('trace.codes'), 'r') as fd:
+        return from_trace_codes_text(fd.read())
+
+
+def syscall_eventids(names: Iterable[str], trace_codes: Optional[Mapping[int, str]] = None) -> Set[int]:
+    """
+    Get the event ids of BSD syscalls by name, for `PyKdebugParser.filter_eventid`.
+    A name also matches its `_nocancel` variant (e.g. `open` gives `BSC_open` and `BSC_open_nocancel`).
+    :param names: Syscall names, such as `open` or `openat`.
+    :param trace_codes: Mapping between code and event name; the default trace codes if omitted.
+    :return: The event ids.
+    :raises ValueError: A name is not a known syscall.
+    """
+    codes = {name: code for code, name in (default_trace_codes() if trace_codes is None else trace_codes).items()}
+    eventids = set()
+    unknown = []
+    for name in names:
+        matches = {codes[event] for event in (f'BSC_{name}', f'BSC_{name}_nocancel') if event in codes}
+        if not matches:
+            unknown.append(name)
+        eventids |= matches
+    if unknown:
+        raise ValueError(f'unknown syscalls: {", ".join(unknown)}')
+    return eventids

pykdebugparser-1.3.0/pykdebugparser/trace_handlers/__init__.py

@@ -0,0 +1,23 @@
+class UnknownEnumValue(int):
+    """
+    A raw value that its enum doesn't define (e.g. a combination of flags or a value added in a newer OS).
+    It has `name` and `value` like an enum member, so it is formatted as the raw number instead of failing the parse.
+    """
+
+    @property
+    def name(self) -> str:
+        return str(int(self))
+
+    @property
+    def value(self) -> int:
+        return int(self)
+
+
+def parse_enum(enum_type, value):
+    """
+    Convert a raw value to an enum member, falling back to `UnknownEnumValue` for values the enum doesn't define.
+    """
+    try:
+        return enum_type(value)
+    except ValueError:
+        return UnknownEnumValue(value)