emdbg.debug.px4.task

  1# Copyright (c) 2023, Auterion AG
  2# SPDX-License-Identifier: BSD-3-Clause
  3
  4from __future__ import annotations
  5from functools import cached_property
  6from . import utils
  7from .system_load import system_load
  8from .device import Device
  9from .base import Base
 10from dataclasses import dataclass
 11from collections import defaultdict
 12import rich.box
 13from rich.text import Text
 14from rich.table import Table
 15
 16# The mapping from register name to position on the thread stack
 17_XCP_REGS_MAP: dict[str, int] = {
 18    "msp":     0,
 19    "basepri": 1,
 20    "r4":      2,
 21    "r5":      3,
 22    "r6":      4,
 23    "r7":      5,
 24    "r8":      6,
 25    "r9":      7,
 26    "r10":     8,
 27    "r11":     9,
 28    "s16":     11 + 0,
 29    "s17":     11 + 1,
 30    "s18":     11 + 2,
 31    "s19":     11 + 3,
 32    "s20":     11 + 4,
 33    "s21":     11 + 5,
 34    "s22":     11 + 6,
 35    "s23":     11 + 7,
 36    "s24":     11 + 8,
 37    "s25":     11 + 9,
 38    "s26":     11 + 10,
 39    "s27":     11 + 11,
 40    "s28":     11 + 12,
 41    "s29":     11 + 13,
 42    "s30":     11 + 14,
 43    "s31":     11 + 15,
 44    "r0":      27 + 0,
 45    "r1":      27 + 1,
 46    "r2":      27 + 2,
 47    "r3":      27 + 3,
 48    "r12":     27 + 4,
 49    "r14":     27 + 5,
 50    "r15":     27 + 6,
 51    "xpsr":    27 + 7,
 52    "s0":      27 + 8,
 53    "s1":      27 + 9,
 54    "s2":      27 + 10,
 55    "s3":      27 + 11,
 56    "s4":      27 + 12,
 57    "s5":      27 + 13,
 58    "s6":      27 + 14,
 59    "s7":      27 + 15,
 60    "s8":      27 + 16,
 61    "s9":      27 + 17,
 62    "s10":     27 + 18,
 63    "s11":     27 + 19,
 64    "s12":     27 + 20,
 65    "s13":     27 + 21,
 66    "s14":     27 + 22,
 67    "s15":     27 + 23,
 68    "fpscr":   27 + 24,
 69}
 70
 71class Task(Base):
 72    """
 73    NuttX task
 74    """
 75    _STACK_COLOR = 0xdeadbeef
 76    _FILE_DESCRIPTORS_PER_BLOCK = 6 # TODO query from ELF
 77
 78    @dataclass
 79    class Load:
 80        total: int
 81        """Total task runtime in µs"""
 82        interval: int
 83        """Interval task runtime in µs since last sample"""
 84        delta: int
 85        """Task runtime in µs within the interval"""
 86
 87        @property
 88        def relative(self) -> float:
 89            """Relative runtime within the interval"""
 90            return self.delta / self.interval if self.interval else 0
 91
 92    def __init__(self, gdb, tcb_ptr: "gdb.Value"):
 93        super().__init__(gdb)
 94        self._tcb = tcb_ptr
 95        self._system_load = system_load(self._gdb)
 96        self.pid = self._tcb["pid"]
 97        self.init_priority = int(self._tcb["init_priority"])
 98        self.stack_limit = int(self._tcb["adj_stack_size"])
 99        self.stack_ptr = self._tcb["stack_base_ptr"]
100        self._is_running_switched = None
101
102    @cached_property
103    def name(self) -> str:
104        """Name of the task"""
105        try:
106            return self._tcb["name"].string()
107        except:
108            return "?"
109
110    @cached_property
111    def sched_priority(self) -> int:
112        """The scheduled priority of the task"""
113        return int(self._tcb["sched_priority"])
114
115    @cached_property
116    def _statenames(self):
117        return self._gdb.types.make_enum_dict(self._gdb.lookup_type("enum tstate_e"))
118
119    @cached_property
120    def state(self) -> str:
121        """Task state name"""
122        for name, value in self._statenames.items():
123            if value == self._tcb["task_state"]:
124                return name
125        return "UNKNOWN"
126
127    @cached_property
128    def short_state(self) -> str:
129        """The short name of the task state"""
130        mapping = {
131            "TASK_PENDING": "PEND", "TASK_READYTORUN": "READY", "TASK_RUNNING": "RUN",
132            "WAIT_SEM": "w:sem", "WAIT_SIG": "w:sig"}
133        return mapping.get(self.state.replace("TSTATE_", ""), "???")
134
135    def _is_state_in(self, *states: list[str]) -> bool:
136        states = {int(self._statenames[s]) for s in states}
137        if int(self._tcb["task_state"]) in states:
138            return True
139        return False
140
141    @cached_property
142    def is_waiting(self) -> bool:
143        """The task is waiting for a semaphore or signal"""
144        if self._is_state_in("TSTATE_WAIT_SEM", "TSTATE_WAIT_SIG"):
145            return True
146
147    @cached_property
148    def is_runnable(self) -> bool:
149        """The task is pending, ready to run, or running"""
150        return self._is_state_in("TSTATE_TASK_PENDING",
151                                 "TSTATE_TASK_READYTORUN",
152                                 "TSTATE_TASK_RUNNING")
153
154    @cached_property
155    def stack_used(self) -> int:
156        """The amount of stack used by the thread in bytes"""
157        if not self.stack_ptr: return 0
158        stack_u32p = self.stack_ptr.cast(self._gdb.lookup_type("unsigned int").pointer())
159        # Stack grows from top to bottom, we do a binary search for the
160        # 0xdeadbeef value from the bottom upwards
161        watermark = utils.binary_search_last(stack_u32p, self._STACK_COLOR, hi=self.stack_limit // 4) + 1
162        # validate the binary search (does not seem necessary)
163        # for ii in range(0, watermark):
164        #     if stack_u32p[ii] != self._STACK_COLOR:
165        #         print(f"{self.name}: Correcting stack size from {watermark * 4} to {ii * 4}!")
166        #         return ii * 4
167        return self.stack_limit - watermark * 4
168
169    @cached_property
170    def waiting_for(self) -> str:
171        """
172        What the task is waiting for. If its a semaphore, return an object,
173        otherwise a string.
174        """
175        if self._is_state_in("TSTATE_WAIT_SEM"):
176            from .semaphore import Semaphore
177            sem = self._tcb['waitsem']
178            ostr = f"{int(sem):#08x} "
179            if descr := self.description_at(sem): ostr += f"<{descr}> "
180            ostr += Semaphore(self._gdb, sem).to_string()
181            return ostr
182        if self._is_state_in("TSTATE_WAIT_SIG"):
183            return "signal"
184        return ""
185
186    @cached_property
187    def files(self) -> list["gdb.Value"]:
188        """The list of inode pointers the task holds"""
189        filelist = self._tcb["group"]["tg_filelist"]
190        rows = filelist["fl_rows"]
191        files = filelist["fl_files"]
192        result = []
193        for ri in range(rows):
194            for ci in range(self._FILE_DESCRIPTORS_PER_BLOCK):
195                file = files[ri][ci]
196                if inode := file["f_inode"]:
197                    result.append(file)
198        return result
199
200    @cached_property
201    def location(self) -> "gdb.Block":
202        """The block the task is currently executing"""
203        if self.is_current_task:
204            pc = self.read_register("pc")
205        else:
206            pc = self._tcb["xcp"]["regs"][32]
207        block = self.block(pc)
208        while block and not block.function:
209            block = block.superblock
210        return block.function if block else int(pc)
211
212    def switch_to(self) -> bool:
213        """Switch to this task by writing the register file"""
214        if self.is_current_task:
215            return False
216        regs = {name: self._tcb["xcp"]["regs"][offset]
217                for name, offset in _XCP_REGS_MAP.items()}
218        regs = self.fix_nuttx_sp(regs)
219        self.write_registers(regs)
220        self._is_running_switched = True
221        return True
222
223    def switch_from(self) -> dict[str, int] | None:
224        """Switch to this task by writing the register file"""
225        if not self.is_current_task:
226            return None
227        self._is_running_switched = False
228        if self.short_state == "RUN":
229            self._is_running_switched = None
230        return self.registers
231
232    @cached_property
233    def is_current_task(self) -> bool:
234        """If the task is currently running"""
235        if self._is_running_switched is not None:
236            return self._is_running_switched
237        return self.short_state == "RUN"
238
239    @cached_property
240    def load(self) -> Load:
241        """The task load based on the system load monitor"""
242        if self._system_load is None: return self.Load(0, 0, 0)
243        _, interval, sl = self._system_load.sample
244        total, delta = sl.get(int(self._tcb), (0,0))
245        return self.Load(total, interval, delta)
246
247    def __repr__(self) -> str:
248        return f"Task({self.name}, {self.pid})"
249
250    def __str__(self) -> str:
251        ostr = self.__repr__() + f": state={self.state}, "
252        ostr += f"prio={self.sched_priority}({self.init_priority}), "
253        ostr += f"stack={self.stack_used}/{self.stack_limit}"
254        if waiting := self.waiting_for:
255            ostr += f", waiting={waiting}"
256        return ostr
257
258
259def all_tasks(gdb) -> list[Task]:
260    """Return a list of all tasks"""
261    type_tcb_s = gdb.lookup_type("struct tcb_s").pointer()
262    def _tasks(name):
263        tcbs = []
264        if (task_list := gdb.lookup_global_symbol(name)) is None:
265            return []
266        task_list = task_list.value()
267        current_task = task_list["head"]
268        if current_task:
269            while True:
270                tcbs.append(Task(gdb, current_task.cast(type_tcb_s)))
271                if current_task == task_list["tail"]:
272                    break
273                next_task = current_task["flink"]
274                # if next_task["blink"] == current_task:
275                #   LOGGER.error(f"Task linkage is broken in {tasks}!")
276                #   break
277                current_task = next_task
278        return tcbs
279
280    tcbs  = _tasks("g_pendingtasks")
281    tcbs += _tasks("g_readytorun")
282    tcbs += _tasks("g_waitingforsemaphore")
283    tcbs += _tasks("g_waitingforsignal")
284    tcbs += _tasks("g_inactivetasks")
285    return tcbs
286
287
288_RESTORE_REGISTERS = None
289def task_switch(gdb, pid: int) -> bool:
290    """
291    Switch to another task.
292    On initial switch the current register file is saved and can be restored
293    by passing a PID <0.
294
295    :param pid: the PID of the task to switch to, or <0 to restore initial task.
296    :return: Success of switching operation.
297    """
298    global _RESTORE_REGISTERS
299    # Restore registers to original task
300    if pid < 0:
301        if _RESTORE_REGISTERS is not None:
302            Base(gdb).write_registers(_RESTORE_REGISTERS)
303        _RESTORE_REGISTERS = None
304        return True
305
306    # Otherwise find the new pointer
307    tcbs = all_tasks(gdb)
308    if (next_task := next((t for t in tcbs if int(t.pid) == pid), None)) is not None:
309        # Find the currently executing task and save their registers
310        if (current_task := next((t for t in tcbs if t.is_current_task), None)) is not None:
311            regs = current_task.switch_from()
312        else:
313            regs = Base(gdb).registers
314        # We only care about the first register set for restoration
315        if next_task.switch_to():
316            if _RESTORE_REGISTERS is None:
317                _RESTORE_REGISTERS = regs
318            print(f"Switched to task '{next_task.name}' ({pid}).")
319            return True
320
321        print("Task already loaded!")
322        return False
323
324    print(f"Unknown task PID '{pid}'!")
325    return False
326
327
328def all_tasks_as_table(gdb, sort_key: str = None, with_stack_usage: bool = True,
329                       with_file_names: bool = True, with_waiting: bool = True) \
330                                    -> tuple[Table, str] | tuple[None, None]:
331    """
332    Return a table of running tasks similar to the NSH top command.
333
334    :param sort_key: optional lambda function to sort the table rows.
335    :param with_stack_usage: compute and show the task stack usage.
336    :param with_file_names: show what files the task has open.
337    :param with_waiting: show what the task is waiting for.
338
339    :return: The task table and additional output. If no tasks are found, return `None`.
340    """
341    table = Table(box=rich.box.MINIMAL_DOUBLE_HEAD)
342    table.add_column("struct tcb_s*", justify="right", no_wrap=True)
343    table.add_column("pid", justify="right", no_wrap=True)
344    table.add_column("Task Name")
345    table.add_column("Location", no_wrap=True)
346    table.add_column("CPU(ms)", justify="right")
347    table.add_column("CPU(%)", justify="right")
348    table.add_column("Stack\nUsage", justify="right")
349    table.add_column("Stack\nAvail", justify="right")
350    table.add_column("Prio", justify="right")
351    table.add_column("Base", justify="right")
352    if with_file_names: table.add_column("Open File Names")
353    else: table.add_column("FDs", justify="right")
354    table.add_column("State")
355    if with_waiting: table.add_column("Waiting For")
356
357    tasks = all_tasks(gdb)
358    if not tasks: return None, None
359    interval_us = tasks[0].load.interval
360    if not interval_us:
361        start, *_ = tasks[0]._system_load.sample
362        total_interval_us = (Device(gdb).uptime - start) or 1
363    total_user_us, total_idle_us = 0, 0
364    rows = []
365    for task in tasks:
366        # Remember the CPU loads for idle task and add it for the other tasks
367        if task.pid == 0: total_idle_us = task.load.delta if interval_us else task.load.total
368        else: total_user_us += task.load.delta if interval_us else task.load.total
369
370        # Find the file names or just the number of file descriptors
371        if with_file_names:
372            file_names = [task.read_string(f["f_inode"]["i_name"]) for f in task.files]
373            file_description = ", ".join(sorted(list(set(file_names))))
374        else:
375            file_description = len(task.files)
376
377        # Add all the values per row
378        relative = task.load.relative if interval_us else task.load.total / total_interval_us
379        stack_overflow = with_stack_usage and task.stack_used >= (task.stack_limit - max(8, task.stack_limit * 0.1))
380        row = [hex(task._tcb), task.pid, task.name,
381               hex(task.location) if isinstance(task.location, int) else task.location.name,
382               task.load.total//1000, f"{(relative * 100):.1f}",
383               Text.assemble((str(task.stack_used) if with_stack_usage else "", "bold red" if stack_overflow else "")),
384               Text.assemble((str(task.stack_limit), "bold" if stack_overflow else "")),
385               Text.assemble((str(task.sched_priority), "bold red" if task.sched_priority > task.init_priority else "")),
386               task.init_priority, file_description, task.short_state]
387        if with_waiting:
388            row.append(task.waiting_for)
389        rows.append(row)
390
391    # Sort the rows by PID by default and format the table
392    for row in sorted(rows, key=lambda l: l[1] if sort_key is None else sort_key):
393        table.add_row(*[r if isinstance(r, Text) else str(r) for r in row],
394                      style="bold blue" if row[11] == "RUN" else None)
395
396    # Add the task information
397    running = sum(1 for t in tasks if t.is_runnable)
398    sleeping = sum(1 for t in tasks if t.is_waiting)
399    output = f"Processes: {len(tasks)} total, {running} running, {sleeping} sleeping\n"
400
401    # Add CPU utilization and guard against division by zero
402    if not interval_us: interval_us = total_interval_us
403    user = 100 * total_user_us / interval_us;
404    idle = 100 * total_idle_us / interval_us;
405    sched = 100 * (interval_us - total_idle_us - total_user_us) / interval_us;
406    output += f"CPU usage: {user:.1f}% tasks, {sched:.1f}% sched, {idle:.1f}% idle\n"
407
408    # Uptime finally
409    output += f"Uptime: {Device(gdb).uptime/1e6:.2f}s total, {interval_us/1e6:.2f}s interval\n"
410    return table, output
411
412
413def all_files_as_table(gdb, sort_key: str = None) -> Table | None:
414    """
415    Return a table of open files owned by tasks.
416
417    :param sort_key: optional lambda function to sort the table rows.
418
419    :return: The file table or `None` if no tasks exist.
420    """
421    tasks = all_tasks(gdb)
422    if not tasks: return None
423
424    files = {}
425    file_tasks = defaultdict(set)
426    for task in tasks:
427        # Find the file names or just the number of file descriptors
428        for f in task.files:
429            files[int(f["f_inode"])] = f["f_inode"]
430            file_tasks[int(f["f_inode"])].add(task)
431    # Format the rows
432    rows = []
433    for addr, inode in files.items():
434        rows.append((hex(addr),
435                     hex(inode["i_private"]) if inode["i_private"] else "",
436                     task.read_string(inode["i_name"]),
437                     ", ".join(sorted(t.name for t in file_tasks[addr]))))
438    # sort and add rows
439    table = Table(box=rich.box.MINIMAL_DOUBLE_HEAD)
440    table.add_column("struct inode*", justify="right", no_wrap=True)
441    table.add_column("i_private*", justify="right", no_wrap=True)
442    table.add_column("Name")
443    table.add_column("Tasks")
444    for row in sorted(rows, key=lambda l: l[2] if sort_key is None else sort_key):
445        table.add_row(*row)
446    return table