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