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 to disambiguate from corner cases that may arise from pid reuse. 44 */ 45 ADynamicInstrumentationManager_TargetProcess* _Nonnull 46 ADynamicInstrumentationManager_TargetProcess_create( 47 uid_t uid, pid_t pid, const char* _Nonnull processName) __INTRODUCED_IN(36); 48 /** 49 * Clean up an ADynamicInstrumentationManager_TargetProcess. 50 * 51 * @param instance returned from ADynamicInstrumentationManager_TargetProcess_create. 52 */ 53 void ADynamicInstrumentationManager_TargetProcess_destroy( 54 const ADynamicInstrumentationManager_TargetProcess* _Nonnull instance) __INTRODUCED_IN(36); 55 56 /** 57 * Initializes an ADynamicInstrumentationManager_MethodDescriptor. Caller must clean up when they 58 * are done with ADynamicInstrumentationManager_MethodDescriptor_Destroy. 59 * 60 * @param fullyQualifiedClassName fqcn of class containing the method. 61 * @param methodName 62 * @param fullyQualifiedParameters fqcn of parameters of the method's signature, or e.g. "int" for 63 * primitives. 64 * @param numParameters length of `fullyQualifiedParameters` array. 65 */ 66 ADynamicInstrumentationManager_MethodDescriptor* _Nonnull 67 ADynamicInstrumentationManager_MethodDescriptor_create( 68 const char* _Nonnull fullyQualifiedClassName, const char* _Nonnull methodName, 69 const char* _Nonnull fullyQualifiedParameters[_Nonnull], size_t numParameters) 70 __INTRODUCED_IN(36); 71 /** 72 * Clean up an ADynamicInstrumentationManager_MethodDescriptor. 73 * 74 * @param instance returned from ADynamicInstrumentationManager_MethodDescriptor_create. 75 */ 76 void ADynamicInstrumentationManager_MethodDescriptor_destroy( 77 const ADynamicInstrumentationManager_MethodDescriptor* _Nonnull instance) 78 __INTRODUCED_IN(36); 79 80 /** 81 * Get the containerPath calculated by 82 * ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 83 * @param instance created with ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 84 * @return The OS path of the containing file. 85 */ 86 const char* _Nullable ADynamicInstrumentationManager_ExecutableMethodFileOffsets_getContainerPath( 87 const ADynamicInstrumentationManager_ExecutableMethodFileOffsets* _Nonnull instance) 88 __INTRODUCED_IN(36); 89 /** 90 * Get the containerOffset calculated by 91 * ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 92 * @param instance created with ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 93 * @return The offset of the containing file within the process' memory. 94 */ 95 uint64_t ADynamicInstrumentationManager_ExecutableMethodFileOffsets_getContainerOffset( 96 const ADynamicInstrumentationManager_ExecutableMethodFileOffsets* _Nonnull instance) 97 __INTRODUCED_IN(36); 98 /** 99 * Get the methodOffset calculated by ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 100 * @param instance created with ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 101 * @return The offset of the method within the containing file. 102 */ 103 uint64_t ADynamicInstrumentationManager_ExecutableMethodFileOffsets_getMethodOffset( 104 const ADynamicInstrumentationManager_ExecutableMethodFileOffsets* _Nonnull instance) 105 __INTRODUCED_IN(36); 106 /** 107 * Clean up an ADynamicInstrumentationManager_ExecutableMethodFileOffsets. 108 * 109 * @param instance returned from ADynamicInstrumentationManager_getExecutableMethodFileOffsets. 110 */ 111 void ADynamicInstrumentationManager_ExecutableMethodFileOffsets_destroy( 112 const ADynamicInstrumentationManager_ExecutableMethodFileOffsets* _Nonnull instance) 113 __INTRODUCED_IN(36); 114 /** 115 * Provides ART metadata about the described java method within the target process. 116 * 117 * @param targetProcess describes for which process the data is requested. 118 * @param methodDescriptor describes the targeted method. 119 * @param out will be populated with the data if successful. A nullptr combined 120 * with an OK status means that the program method is defined, but the offset 121 * info was unavailable because it is not AOT compiled. 122 * @return status indicating success or failure. The values correspond to the `binder_exception_t` 123 * enum values from <android/binder_status.h>. 124 */ 125 int32_t ADynamicInstrumentationManager_getExecutableMethodFileOffsets( 126 const ADynamicInstrumentationManager_TargetProcess* _Nonnull targetProcess, 127 const ADynamicInstrumentationManager_MethodDescriptor* _Nonnull methodDescriptor, 128 const ADynamicInstrumentationManager_ExecutableMethodFileOffsets* _Nullable* _Nonnull out) 129 __INTRODUCED_IN(36); 130 131 __END_DECLS 132 133 #endif // __ADYNAMICINSTRUMENTATIONMANAGER_H__ 134