HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
debugger.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_BASE_ARCH_DEBUGGER_H
25 #define PXR_BASE_ARCH_DEBUGGER_H
26 
27 /// \file arch/debugger.h
28 /// Routines for interacting with a debugger.
29 
30 #include "pxr/pxr.h"
31 #include "pxr/base/arch/api.h"
33 
35 
36 /// Stop in a debugger.
37 ///
38 /// This function will do one of the following: start a debugger
39 /// attached to this process stopped on this function; stop in an
40 /// already attached debugger; stop and wait for a debugger to
41 /// attach, or nothing.
42 ///
43 /// On Linux this will start a debugger using \c ArchDebuggerAttach()
44 /// if no debugger is attached. If a debugger is (or was) attached it
45 /// will stop on this function due to \c SIGTRAP. Alternatively, users
46 /// can configure the debugger to not stop on \c SIGTRAP and instead
47 /// break on \c ArchDebuggerTrap().
48 ///
49 /// If a debugger is not attached, \c ArchDebuggerAttach() does not
50 /// attach one, and \c ArchDebuggerWait() has been most recently
51 /// called with \c true then this will wait for a debugger to attach,
52 /// otherwise it does nothing and the process does not stop. The user
53 /// can continue the process from the debugger simply by issuing the
54 /// continue command. The user can also continue the process from an
55 /// attached terminal by putting the process into the foreground or
56 /// background.
57 ///
59 void ArchDebuggerTrap() ARCH_NOINLINE;
60 
61 /// Cause debug traps to wait for the debugger or not.
62 ///
63 /// When \p wait is \c true the next call to \c ArchDebuggerTrap()
64 /// will cause the process to wait for a signal. The user can attach
65 /// a debugger to continue the process. The process will not wait
66 /// again until another call to this function with \p wait \c true.
67 ///
69 void ArchDebuggerWait(bool wait);
70 
71 /// Attach a debugger.
72 ///
73 /// Attaches the debugger by running the contents of the enviroment variable
74 /// ARCH_DEBUGGER using /bin/sh. Any '%p' in the contents of this variable
75 /// will be replaced with the process id of the process launching the debugger.
76 /// Any '%e' will be replaced with the path to the executable for the process.
77 ///
78 /// Returns true if ARCH_DEBUGGER is set and the debugger was successfully
79 /// launched, otherwise returns false.
81 bool ArchDebuggerAttach() ARCH_NOINLINE;
82 
83 /// Test if a debugger is attached
84 ///
85 /// Attempts to detect if a debugger is currently attached to the process.
87 bool ArchDebuggerIsAttached() ARCH_NOINLINE;
88 
89 /// Abort. This will try to avoid the JIT debugger if any if ARCH_AVOID_JIT
90 /// is in the environment and the debugger isn't already attached. In that
91 /// case it will _exit(134). If \p logging is \c false then this will
92 /// attempt to bypass any crash logging.
93 [[noreturn]]
95 void ArchAbort(bool logging = true);
96 
97 /// Stop in the debugger.
98 ///
99 /// This macro expands to \c ArchDebuggerTrap() and, if necessary and
100 /// possible, code to prevent optimization so the caller appears in the
101 /// debugger's stack trace. The calling functions should also use the
102 /// \c ARCH_NOINLINE function attribute.
103 #if defined(ARCH_COMPILER_GCC) || defined(ARCH_COMPILER_CLANG)
104 #define ARCH_DEBUGGER_TRAP do { ArchDebuggerTrap(); asm(""); } while (0)
105 #else
106 #define ARCH_DEBUGGER_TRAP do { ArchDebuggerTrap(); } while (0)
107 #endif
108 
110 
111 #endif // PXR_BASE_ARCH_DEBUGGER_H
ARCH_API void ArchAbort(bool logging=true)
ARCH_API void ArchDebuggerWait(bool wait)
ARCH_API bool ArchDebuggerIsAttached() ARCH_NOINLINE
*tasks wait()
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
PXR_NAMESPACE_OPEN_SCOPE ARCH_API void ArchDebuggerTrap() ARCH_NOINLINE
#define ARCH_API
Definition: api.h:40
ARCH_API bool ArchDebuggerAttach() ARCH_NOINLINE