1 /*
2  * Copyright (C) 2024 The Android Open Source Project
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *  * Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  *  * Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in
12  *    the documentation and/or other materials provided with the
13  *    distribution.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
18  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
19  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
20  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
21  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
22  * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
23  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
24  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
25  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26  * SUCH DAMAGE.
27  */
28 
29 #pragma once
30 
31 /**
32  * @file android/crash_detail.h
33  * @brief Attach extra information to android crashes.
34  */
35 
36 #include <stddef.h>
37 #include <sys/cdefs.h>
38 
39 __BEGIN_DECLS
40 
41 typedef struct crash_detail_t crash_detail_t;
42 
43 /**
44  * Register a new buffer to get logged into tombstones for crashes.
45  *
46  * It will be added to both the tombstone proto in the crash_detail field, and
47  * in the tombstone text format.
48  *
49  * Tombstone proto definition:
50  *   https://cs.android.com/android/platform/superproject/main/+/main:system/core/debuggerd/proto/tombstone.proto
51  *
52  * An app can get hold of these for any `REASON_CRASH_NATIVE` instance of
53  * `android.app.ApplicationExitInfo`.
54  *
55  * https://developer.android.com/reference/android/app/ApplicationExitInfo#getTraceInputStream()
56 
57  * The lifetime of name and data has to be valid until the program crashes, or until
58  * android_crash_detail_unregister is called.
59  *
60  * Example usage:
61  *   const char* stageName = "garbage_collection";
62  *   crash_detail_t* cd = android_crash_detail_register("stage", stageName, strlen(stageName));
63  *   do_garbage_collection();
64  *   android_crash_detail_unregister(cd);
65  *
66  * If this example crashes in do_garbage_collection, a line will show up in the textual representation of the tombstone:
67  *   Extra crash detail: stage: 'garbage_collection'
68  *
69  * Introduced in API 35.
70  *
71  * \param name identifying name for this extra data.
72  *             this should generally be a human-readable UTF-8 string, but we are treating
73  *             it as arbitrary bytes because it could be corrupted by the crash.
74  * \param name_size number of bytes of the buffer pointed to by name
75  * \param data a buffer containing the extra detail bytes, if null the crash detail
76  *             is disabled until android_crash_detail_replace_data replaces it with
77  *             a non-null pointer.
78  * \param data_size number of bytes of the buffer pointed to by data
79  *
80  * \return a handle to the extra crash detail.
81  */
82 crash_detail_t* _Nullable android_crash_detail_register(
83     const void* _Nonnull name, size_t name_size, const void* _Nullable data, size_t data_size) __INTRODUCED_IN(35);
84 
85 /**
86  * Unregister crash detail from being logged into tombstones.
87  *
88  * After this function returns, the lifetime of the objects crash_detail was
89  * constructed from no longer needs to be valid.
90  *
91  * Introduced in API 35.
92  *
93  * \param crash_detail the crash_detail that should be removed.
94  */
95 void android_crash_detail_unregister(crash_detail_t* _Nonnull crash_detail) __INTRODUCED_IN(35);
96 
97 /**
98  * Replace data of crash detail.
99  *
100  * This is more efficient than using android_crash_detail_unregister followed by
101  * android_crash_detail_register. If you very frequently need to swap out the data,
102  * you can hold onto the crash_detail.
103  *
104  * Introduced in API 35.
105  *
106  * \param data the new buffer containing the extra detail bytes, or null to disable until
107  *             android_crash_detail_replace_data is called again with non-null data.
108  * \param data_size the number of bytes of the buffer pointed to by data.
109  */
110 void android_crash_detail_replace_data(crash_detail_t* _Nonnull crash_detail, const void* _Nullable data, size_t data_size) __INTRODUCED_IN(35);
111 
112 /**
113  * Replace name of crash detail.
114  *
115  * This is more efficient than using android_crash_detail_unregister followed by
116  * android_crash_detail_register. If you very frequently need to swap out the name,
117  * you can hold onto the crash_detail.
118  *
119  * Introduced in API 35.
120  *
121  * \param name identifying name for this extra data.
122  * \param name_size number of bytes of the buffer pointed to by name
123  */
124 void android_crash_detail_replace_name(crash_detail_t* _Nonnull crash_detail, const void* _Nonnull name, size_t name_size) __INTRODUCED_IN(35);
125 
126 __END_DECLS
127