1 | /* |
2 | * Copyright (c) 2015 Apple Inc. All rights reserved. |
3 | * |
4 | * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ |
5 | * |
6 | * This file contains Original Code and/or Modifications of Original Code |
7 | * as defined in and that are subject to the Apple Public Source License |
8 | * Version 2.0 (the 'License'). You may not use this file except in |
9 | * compliance with the License. The rights granted to you under the License |
10 | * may not be used to create, or enable the creation or redistribution of, |
11 | * unlawful or unlicensed copies of an Apple operating system, or to |
12 | * circumvent, violate, or enable the circumvention or violation of, any |
13 | * terms of an Apple operating system software license agreement. |
14 | * |
15 | * Please obtain a copy of the License at |
16 | * http://www.opensource.apple.com/apsl/ and read it before using this file. |
17 | * |
18 | * The Original Code and all software distributed under the License are |
19 | * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER |
20 | * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, |
21 | * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, |
22 | * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. |
23 | * Please see the License for the specific language governing rights and |
24 | * limitations under the License. |
25 | * |
26 | * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ |
27 | */ |
28 | |
29 | #ifndef SYS_KTRACE_H |
30 | #define SYS_KTRACE_H |
31 | |
32 | #include <stdint.h> |
33 | #include <os/base.h> |
34 | #include <kern/locks.h> |
35 | |
36 | __enum_decl(ktrace_state_t, unsigned int, { |
37 | /* No tool has configured ktrace. */ |
38 | KTRACE_STATE_OFF = 0, |
39 | /* A foreground tool has configured ktrace. */ |
40 | KTRACE_STATE_FG, |
41 | /* A background tool has configured ktrace. */ |
42 | KTRACE_STATE_BG, |
43 | }); |
44 | |
45 | void ktrace_lock(void); |
46 | void ktrace_unlock(void); |
47 | void ktrace_assert_lock_held(void); |
48 | void ktrace_start_single_threaded(void); |
49 | void ktrace_end_single_threaded(void); |
50 | |
51 | /* |
52 | * Subsystems that use ktrace to manage ownership. These values are passed as |
53 | * part of the `*_mask` arguments in `ktrace_configure` and `ktrace_reset`. |
54 | */ |
55 | #define KTRACE_KDEBUG (1 << 0) |
56 | #define KTRACE_KPERF (1 << 1) |
57 | |
58 | /* |
59 | * Used by subsystems to inform ktrace that a configuration is occurring. |
60 | * Validates whether the current process has privileges to configure |
61 | * ktrace. Pass the subsystem(s) being configured in config_mask. |
62 | * |
63 | * `ktrace_lock` must be held. |
64 | * |
65 | * Returns 0 if configuration is allowed, EPERM if process is not privileged, |
66 | * and EBUSY if ktrace is owned by another process. |
67 | */ |
68 | int ktrace_configure(uint32_t config_mask); |
69 | |
70 | /* |
71 | * Tell ktrace to reset a configuration. Pass the susbsystem(s) that are to |
72 | * be reset in the reset_mask. |
73 | * |
74 | * `ktrace_lock` must be held. |
75 | */ |
76 | void ktrace_reset(uint32_t reset_mask); |
77 | |
78 | /* |
79 | * Determine if the current process can read the configuration of ktrace. |
80 | * Only the owning process or a root privileged process is allowed. |
81 | * |
82 | * `ktrace_lock` must be held. |
83 | * |
84 | * Returns 0 if allowed, EPERM otherwise. |
85 | */ |
86 | int ktrace_read_check(void); |
87 | |
88 | /* |
89 | * With certain boot-args, the kernel can start tracing without user space |
90 | * intervention. With `trace=<n_events>`, the kernel will start tracing at |
91 | * boot. With `trace_wake=<n_events>`, the kernel will start tracing on the |
92 | * wake path out of hibernation (on Intel only). |
93 | * |
94 | * In these cases, ktrace must be aware of the state changes. This function |
95 | * should be called whenever the kernel initiates configuring ktrace. |
96 | * |
97 | * `ktrace_lock` must be held. |
98 | */ |
99 | void ktrace_kernel_configure(uint32_t config_mask); |
100 | |
101 | /* |
102 | * This KPI allows kernel systems to disable ktrace. ktrace will only be |
103 | * disabled if the state matches the provided state_to_match. |
104 | * |
105 | * This does not reset the configuration of any subsystems -- it just makes |
106 | * them stop logging events or sampling data. |
107 | * |
108 | * `ktrace_lock` must be held. |
109 | */ |
110 | void ktrace_disable(ktrace_state_t state_to_match); |
111 | |
112 | /* |
113 | * Returns the pid of the process that owns ktrace. If ktrace is unowned, |
114 | * returns 0. |
115 | * |
116 | * `ktrace_lock` must be held. |
117 | */ |
118 | int ktrace_get_owning_pid(void); |
119 | |
120 | /* |
121 | * Returns true if background tracing is active, false otherwise. |
122 | * |
123 | * `ktrace_lock` must be held. |
124 | */ |
125 | bool ktrace_background_active(void); |
126 | |
127 | /* |
128 | * These functions exist for the transition for kperf to allow blessing other |
129 | * processes. They should not be used by other clients. |
130 | */ |
131 | extern bool ktrace_keep_ownership_on_reset; |
132 | extern int ktrace_root_set_owner_allowed; |
133 | int ktrace_set_owning_pid(int pid); |
134 | |
135 | #endif /* SYS_KTRACE_H */ |
136 | |