1UTRACE_CONTROL(9)               utrace core API              UTRACE_CONTROL(9)
2
3
4

NAME

6       utrace_control - control a thread being traced by a tracing engine
7

SYNOPSIS

9       int utrace_control(struct task_struct * target,
10                          struct utrace_engine * engine,
11                          enum utrace_resume_action action);
12

ARGUMENTS

14       target
15           thread to affect
16
17       engine
18           attached engine to affect
19
20       action
21
22           enum utrace_resume_action for thread to do
23

DESCRIPTION

25       This is how a tracing engine asks a traced thread to do something. This
26       call is controlled by the action argument, which has the same meaning
27       as the enum utrace_resume_action value returned by event reporting
28       callbacks.
29
30       If target is already dead (target->exit_state nonzero), all actions
31       except UTRACE_DETACH fail with -ESRCH.
32
33       The following sections describe each option for the action argument.
34

UTRACE_DETACH

36       After this, the engine data structure is no longer accessible, and the
37       thread might be reaped. The thread will start running again if it was
38       stopped and no longer has any attached engines that want it stopped.
39
40       If the report_reap callback may already have begun, this fails with
41       -ESRCH. If the report_death callback may already have begun, this fails
42       with -EALREADY.
43
44       If target is not already stopped, then a callback to this engine might
45       be in progress or about to start on another CPU. If so, then this
46       returns -EINPROGRESS; the detach happens as soon as the pending
47       callback is finished. To synchronize after an -EINPROGRESS return, see
48       utrace_barrier.
49
50       If target is properly stopped before utrace_control is called, then
51       after successful return it's guaranteed that no more callbacks to the
52       engine->ops vector will be made.
53
54       The only exception is SIGKILL (and exec or group-exit by another thread
55       in the group), which can cause asynchronous report_death and/or
56       report_reap callbacks even when UTRACE_STOP was used. (In that event,
57       this fails with -ESRCH or -EALREADY, see above.)
58

UTRACE_STOP

60       This asks that target stop running. This returns 0 only if target is
61       already stopped, either for tracing or for job control. Then target
62       will remain stopped until another utrace_control call is made on
63       engine; target can be woken only by SIGKILL (or equivalent, such as
64       exec or termination by another thread in the same thread group).
65
66       This returns -EINPROGRESS if target is not already stopped. Then the
67       effect is like UTRACE_REPORT. A report_quiesce or report_signal
68       callback will be made soon. Your callback can then return UTRACE_STOP
69       to keep target stopped.
70
71       This does not interrupt system calls in progress, including ones that
72       sleep for a long time. For that, use UTRACE_INTERRUPT. To interrupt
73       system calls and then keep target stopped, your report_signal callback
74       can return UTRACE_STOP.
75

UTRACE_RESUME

77       Just let target continue running normally, reversing the effect of a
78       previous UTRACE_STOP. If another engine is keeping target stopped, then
79       it remains stopped until all engines let it resume. If target was not
80       stopped, this has no effect.
81

UTRACE_REPORT

83       This is like UTRACE_RESUME, but also ensures that there will be a
84       report_quiesce or report_signal callback made soon. If target had been
85       stopped, then there will be a callback before it resumes running
86       normally. If another engine is keeping target stopped, then there might
87       be no callbacks until all engines let it resume.
88
89       Since this is meaningless unless report_quiesce callbacks will be made,
90       it returns -EINVAL if engine lacks UTRACE_EVENT(QUIESCE).
91

UTRACE_INTERRUPT

93       This is like UTRACE_REPORT, but ensures that target will make a
94       report_signal callback before it resumes or delivers signals. If target
95       was in a system call or about to enter one, work in progress will be
96       interrupted as if by SIGSTOP. If another engine is keeping target
97       stopped, then there might be no callbacks until all engines let it
98       resume.
99
100       This gives engine an opportunity to introduce a forced signal
101       disposition via its report_signal callback.
102

UTRACE_SINGLESTEP

104       It's invalid to use this unless arch_has_single_step returned true.
105       This is like UTRACE_RESUME, but resumes for one user instruction only.
106
107       Note that passing UTRACE_SINGLESTEP or UTRACE_BLOCKSTEP to
108       utrace_control or returning it from an event callback alone does not
109       necessarily ensure that stepping will be enabled. If there are more
110       callbacks made to any engine before returning to user mode, then the
111       resume action is chosen only by the last set of callbacks. To be sure,
112       enable UTRACE_EVENT(QUIESCE) and look for the report_quiesce callback
113       with a zero event mask, or the report_signal callback with
114       UTRACE_SIGNAL_REPORT.
115
116       Since this is not robust unless report_quiesce callbacks will be made,
117       it returns -EINVAL if engine lacks UTRACE_EVENT(QUIESCE).
118

UTRACE_BLOCKSTEP

120       It's invalid to use this unless arch_has_block_step returned true. This
121       is like UTRACE_SINGLESTEP, but resumes for one whole basic block of
122       user instructions.
123
124       Since this is not robust unless report_quiesce callbacks will be made,
125       it returns -EINVAL if engine lacks UTRACE_EVENT(QUIESCE).
126
127       UTRACE_BLOCKSTEP devolves to UTRACE_SINGLESTEP when another tracing
128       engine is using UTRACE_SINGLESTEP at the same time.
129
130
131
132Kernel Hackers Manual 2.6.       November 2011               UTRACE_CONTROL(9)
Impressum