1 /* 2 * Copyright (c) 2021 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 #ifdef XNU_KERNEL_PRIVATE 29 #ifndef _COREANALYTICS_H 30 #include <libkern/coreanalytics/coreanalytics_internal.h> 31 32 /* 33 * CoreAnalytics data types 34 */ 35 36 /* 64bit signed integers */ 37 #define CA_INT 1ULL 38 /* Boolean */ 39 #define CA_BOOL ((bool) 1) 40 /* 41 * A static const string. 42 * Currently, it is NOT safe to use a dynamically allocated string with 43 * the xnu CoreAnalytics interface. 44 */ 45 #define CA_UUID_LEN 37 46 #define CA_PROCNAME_LEN 17 47 #define CA_UBSANBUF_LEN 256 48 #define CA_TEAMID_MAX_LEN 32 49 #define CA_SIGNINGID_MAX_LEN 128 50 #define CA_STATIC_STRING(len) ca_sstr[len] 51 52 #define CA_EVENT_TYPE(name) struct _ca_event_ ## name 53 54 /* 55 * Defines a new CoreAnalytics event. 56 * The first argument is the event name. This will be prefixed with "com.apple.xnu.". 57 * The following arguments define the event type. Fields are defined as a type followed by a name. 58 * For example, say we've defined an event called "com.apple.xnu.my_event". It has the following fields 59 * count Integer 60 * bad_thing_happened Boolean 61 * name String 62 * 63 * We would define this event in xnu like so: 64 * CA_EVENT(my_event, 65 * CA_INT, count, 66 * CA_BOOL, bad_thing_happened, 67 * CA_STATIC_STRING(CA_UUID_LEN), name); 68 * 69 * This defines a struct that we can use to create the event. To get the struct's typename, use the CA_EVENT_TYPE macro. 70 * To send the struct, it needs to be allocated via the CoreAnalytics subsystem. So to create and send "my_event" we can do: 71 * ca_event_t event = CA_EVENT_ALLOCATE(my_event); 72 * CA_EVENT_TYPE(my_event) *event_data = event->data; 73 * event_data->count = count_value; 74 * event_data->bad_thing_happened = did_bad_thing_happen; 75 * strlcpy(event_data->name, bad_thing_name, CA_UUID_LEN); 76 * CA_EVENT_SEND(event); 77 * 78 * Note that CA_EVENT_SEND just enqueues the event on a lock free queue. Serializing & sending the event to userspace happens on another thread. 79 */ 80 81 #define CA_EVENT(name, ...) \ 82 const char * _CA_EVENT_NAME_PREFIX(name) = _CA_EVENT_ORG #name "\0" _CA_FOREACH(_CA_STRINGIFY, _CA_NULL_TERMINATOR, _CA_STRINGIFY, ##__VA_ARGS__) "\0"; \ 83 _Static_assert(sizeof(_CA_EVENT_ORG #name) <= 64, "CoreAnalytics event name ('" _CA_EVENT_ORG #name "') is too long"); \ 84 CA_EVENT_TYPE(name) { \ 85 _CA_FOREACH(_CA_TYPE_DECLARATION, _CA_NULL_EPSILON, _CA_VARIABLE_DECLARATION, ##__VA_ARGS__) \ 86 } __attribute__ ((packed)) 87 88 /* 89 * Allocates a new event struct. 90 * Should be freed via CA_EVENT_DEALLOCATE. 91 * Will be freed automatically by CA_EVENT_SEND. 92 * May block (use CA_EVENT_ALLOCATE_FLAGS with Z_NOWAIT for an allocation which can't block but may fail). 93 */ 94 #define CA_EVENT_ALLOCATE(name) \ 95 core_analytics_allocate_event(sizeof(CA_EVENT_TYPE(name)), _CA_EVENT_NAME_PREFIX(name), (zalloc_flags_t)(Z_WAITOK | Z_ZERO | Z_NOFAIL)) 96 97 /* 98 * Allocate a new event struct with custom zalloc flags. 99 */ 100 #define CA_EVENT_ALLOCATE_FLAGS(name, flags) \ 101 core_analytics_allocate_event(sizeof(CA_EVENT_TYPE(name)), _CA_EVENT_NAME_PREFIX(name), flags) 102 103 /* 104 * Deallocate an event allocated via CA_EVENT_ALLOCATE 105 */ 106 #define CA_EVENT_DEALLOCATE(event) \ 107 ({ \ 108 kfree_data(event->data, \ 109 core_analytics_event_size(event->format_str)); \ 110 kfree_type(struct _ca_event, event); \ 111 }) 112 113 /* 114 * Deallocate an event allocated via CA_EVENT_ALLOCATE using name 115 */ 116 #define CA_EVENT_DEALLOCATE_WITH_NAME(event, name) \ 117 ({ \ 118 kfree_data(event->data, sizeof(CA_EVENT_TYPE(name))); \ 119 kfree_type(struct _ca_event, event); \ 120 }) 121 122 /* 123 * Send the given event. Ownership of the event is transferred. 124 * Does not block. Does not allocate memory. 125 * Is safe to use from an interrupt context. 126 * The event may be dropped later in the pipeline. 127 * 128 * Disables preemption while sending the event. 129 * Use CA_EVENT_SEND_PREEMPTION_DISABLED if calling from a context 130 * where preemption is already disabled. 131 */ 132 #define CA_EVENT_SEND(event) core_analytics_send_event(event) 133 134 /* 135 * Same as CA_EVENT_SEND but the caller takes responsibility for disabling preemption. 136 */ 137 #define CA_EVENT_SEND_PREEMPTION_DISABLED(event) core_analytics_send_event_preemption_disabled(event) 138 139 #endif /* _COREANALYTICS_H */ 140 #endif /* XNU_KERNEL_PRIVATE */ 141