• utrace
• arch
• HowTo

utrace arch porting How-To

There are several independent pieces of arch support that are required before kernels using CONFIG_UTRACE=y can be built. These are all represented for Kconfig dependencies by CONFIG_HAVE_ARCH_TRACEHOOK.

When your arch has met all the requirements, make arch/cpu/Kconfig do:

        select HAVE_ARCH_TRACEHOOK

This will make the CONFIG_UTRACE option available.

The comments near HAVE_ARCH_TRACEHOOK in the arch/Kconfig file list all the things your arch should do before setting it.

The current list is:

1. task_pt_regs()

   • Define this inline function in asm/processor.h or asm/ptrace.h.

2. arch_has_single_step(), arch_has_block_step()

   • If your hardware has single-step and/or block-step support, then define these macros and related functions.

     See the kerneldoc comments in linux/ptrace.h for details.

3. linux/regset.h

   • You must define user_regset structures and calls for your machine, and define task_user_regset_view(). The formats must match those used for core dumps, and have appropriate .core_note_type fields. See linux/regset.h for details.

4. CORE_DUMP_USE_REGSET

   • You must #define CORE_DUMP_USE_REGSET in asm/elf.h and test that core dumps work via the user_regset interfaces and produce correct results.

5. asm/syscall.h

   • You must supply asm/syscall.h for your arch, with all the functions (usually inlines) described in asm-generic/syscall.h.

6. TIF_SYSCALL_TRACE

   • Setting TIF_SYSCALL_TRACE must cause calls from arch code to tracehook_report_syscall_entry() and tracehook_report_syscall_exit() instead of the old ptrace behavior. Note that the calling arch code should handle the return value from

     tracehook_report_syscall_entry(), which is behavior that was not required for the old ptrace support. This needs to implement some form of safe abort of the syscall. See the kerneldoc comments for the exact details.

7. TIF_NOTIFY_RESUME

   • You must define the TIF_NOTIFY_RESUME bit. This should behave in the arch code like TIF_SIGPENDING, i.e. checked when returning to user mode so you can never miss one. But when TIF_NOTIFY_RESUME is set, the arch code must do:

                     clear_thread_flag(TIF_NOTIFY_RESUME);
                     tracehook_notify_resume(regs);

     where regs is the same as task_pt_regs(current). (That is the only effect of TIF_NOTIFY_RESUME, and it does not affect waits et al like TIF_SIGPENDING does.) This code path should not unconditionally go into the signals code, i.e. at some point you should check TIF_SIGPENDING independently and not enter a do_signal() path when only TIF_NOTIFY_RESUME is set; this avoids debugged threads serializing on their shared siglock.

8. tracehook_signal_handler()

   • Your signal handling code should call tracehook_signal_handler() after doing handler setup. This happens after all the signal magic (sa_mask handling et al), usually the last thing before returning from do_signal() or a similar function in the arch code. See linux/tracehook.h for the parameters to pass it.