1 /* 2 * Copyright (C) 2024 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef __ADYNAMICINSTRUMENTATIONMANAGER_H__ 18 #define __ADYNAMICINSTRUMENTATIONMANAGER_H__ 19 20 #include <sys/cdefs.h> 21 #include <sys/types.h> 22 23 __BEGIN_DECLS 24 25 struct ADynamicInstrumentationManager_MethodDescriptor; 26 typedef struct ADynamicInstrumentationManager_MethodDescriptor 27 ADynamicInstrumentationManager_MethodDescriptor; 28 29 struct ADynamicInstrumentationManager_TargetProcess; 30 typedef struct ADynamicInstrumentationManager_TargetProcess 31 ADynamicInstrumentationManager_TargetProcess; 32 33 struct ADynamicInstrumentationManager_ExecutableMethodFileOffsets; 34 typedef struct ADynamicInstrumentationManager_ExecutableMethodFileOffsets 35 ADynamicInstrumentationManager_ExecutableMethodFileOffsets; 36 37 /** 38 * Initializes an ADynamicInstrumentationManager_TargetProcess. Caller must clean up when they are 39 * done with ADynamicInstrumentationManager_TargetProcess_destroy. 40 * 41 * @param uid of targeted process. 42 * @param pid of targeted process. 43 * @param processName UTF-8 encoded string representing the same process as specified by `pid`. 44 * Supplied to disambiguate from corner cases that may arise from pid reuse. 45 * Referenced parameter must outlive the returned 46 * ADynamicInstrumentationManager_TargetProcess. 47 */ 48 ADynamicInstrumentationManager_TargetProcess* _Nullable 49 ADynamicInstrumentationManager_TargetProcess_create( 50 uid_t uid, pid_t pid, const char* _Nonnull processName) __INTRODUCED_IN(36); 51 /** 52 * Clean up an ADynamicInstrumentationManager_TargetProcess. 53 * 54 * @param instance returned from ADynamicInstrumentationManager_TargetProcess_create. 55 */ 56 void ADynamicInstrumentationManager_TargetProcess_destroy( 57 const ADynamicInstrumentationManager_TargetProcess* _Nullable instance) __INTRODUCED_IN(36); 58 59 /** 60 * Initializes an ADynamicInstrumentationManager_MethodDescriptor. Caller must clean up when they 61 * are done with ADynamicInstrumentationManager_MethodDescriptor_destroy. 62 * 63 * @param fullyQualifiedClassName UTF-8 encoded fqcn of class containing the method. Referenced 64 * parameter must outlive the returned 65 * ADynamicInstrumentationManager_MethodDescriptor. 66 * @param methodName UTF-8 encoded method name. Referenced parameter must outlive the returned 67 * ADynamicInstrumentationManager_MethodDescriptor. 68 * @param fullyQualifiedParameters UTF-8 encoded fqcn of parameters of the method's signature, 69 * or e.g. "int" for primitives. Referenced parameter should 70 * outlive the returned 71 * ADynamicInstrumentationManager_MethodDescriptor. 72 * @param numParameters length of `fullyQualifiedParameters` array. 73 */ 74 ADynamicInstrumentationManager_MethodDescriptor* _Nullable 75 ADynamicInstrumentationManager_MethodDescriptor_create( 76 const char* _Nonnull fullyQualifiedClassName, const char* _Nonnull methodName, 77 const char* _Nonnull* _Nonnull fullyQualifiedParameters, size_t numParameters) 78 __INTRODUCED_IN(36); 79 /** 80 * Clean up an ADynamicInstrumentationManager_MethodDescriptor. 81 * 82 * @param instance returned from ADynamicInstrumentationManager_MethodDescriptor_create. 83 */ 84 void ADynamicInstrumentationManager_MethodDescriptor_destroy( 85 const ADynamicInstrumentationManager_MethodDescriptor* _Nullable instance) 86 __INTRODUCED_IN(36); 87 88 /** 89 * Get the containerPath calculated by 90 * ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 91 * @param instance created with ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 92 * @return The OS path of the containing file as a UTF-8 string, which has the same lifetime 93 * as the ADynamicInstrumentationManager_ExecutableMethodFileOffsets instance passed 94 * as a param. 95 */ 96 const char* _Nullable ADynamicInstrumentationManager_ExecutableMethodFileOffsets_getContainerPath( 97 const ADynamicInstrumentationManager_ExecutableMethodFileOffsets* _Nonnull instance) 98 __INTRODUCED_IN(36); 99 /** 100 * Get the containerOffset calculated by 101 * ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 102 * @param instance created with ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 103 * @return The absolute address of the containing file within remote the process' virtual memory 104 * space. 105 */ 106 uint64_t ADynamicInstrumentationManager_ExecutableMethodFileOffsets_getContainerOffset( 107 const ADynamicInstrumentationManager_ExecutableMethodFileOffsets* _Nonnull instance) 108 __INTRODUCED_IN(36); 109 /** 110 * Get the methodOffset calculated by ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 111 * @param instance created with ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 112 * @return The offset of the method within the container whose address is returned by 113 * ADynamicInstrumentationManager_ExecutableMethodFileOffsets_getContainerOffset. 114 */ 115 uint64_t ADynamicInstrumentationManager_ExecutableMethodFileOffsets_getMethodOffset( 116 const ADynamicInstrumentationManager_ExecutableMethodFileOffsets* _Nonnull instance) 117 __INTRODUCED_IN(36); 118 /** 119 * Clean up an ADynamicInstrumentationManager_ExecutableMethodFileOffsets. 120 * 121 * @param instance returned from ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 122 */ 123 void ADynamicInstrumentationManager_ExecutableMethodFileOffsets_destroy( 124 const ADynamicInstrumentationManager_ExecutableMethodFileOffsets* _Nullable instance) 125 __INTRODUCED_IN(36); 126 /** 127 * Provides ART metadata about the described java method within the target process. 128 * 129 * @param targetProcess describes for which process the data is requested. 130 * @param methodDescriptor describes the targeted method. 131 * @param out will be populated with the data if successful. A nullptr combined 132 * with an OK status means that the program method is defined, but the offset 133 * info was unavailable because it is not AOT compiled. Caller owns `out` and 134 * should clean it up with 135 * ADynamicInstrumentationManager_ExecutableMethodFileOffsets_destroy. 136 * @return status indicating success or failure. The values correspond to the `binder_exception_t` 137 * enum values from <android/binder_status.h>. 138 */ 139 int32_t ADynamicInstrumentationManager_getExecutableMethodFileOffsets( 140 const ADynamicInstrumentationManager_TargetProcess* _Nonnull targetProcess, 141 const ADynamicInstrumentationManager_MethodDescriptor* _Nonnull methodDescriptor, 142 const ADynamicInstrumentationManager_ExecutableMethodFileOffsets* _Nullable* _Nonnull out) 143 __INTRODUCED_IN(36); 144 145 __END_DECLS 146 147 #endif // __ADYNAMICINSTRUMENTATIONMANAGER_H__ 148