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 29 /* socd_client.h: machine-independent API for interfacing with soc diagnostics data pipeline. 30 * NOTE: this file is included by socd parser and should not declare any symbols nor 31 * include kernel specific headers. Use socd_client_kern.h for kernel specifics. 32 */ 33 34 #ifndef _KERN_SOCD_CLIENT_H_ 35 #define _KERN_SOCD_CLIENT_H_ 36 37 #include <stdint.h> 38 #include <sys/cdefs.h> 39 #include <uuid/uuid.h> 40 #include <sys/kdebug.h> 41 42 __BEGIN_DECLS 43 44 /* "stickiness" is an attribute in the debugid that means "dont overwrite this entry" */ 45 #define SOCD_TRACE_MODE_NONE 0x0 46 #define SOCD_TRACE_MODE_STICKY_TRACEPOINT 0x1 47 48 /* socd trace event id format within kdebug code */ 49 #define SOCD_TRACE_MODE_MASK (0x3000) 50 #define SOCD_TRACE_MODE_SMASK (0x3) 51 #define SOCD_TRACE_MODE_OFFSET (12) 52 53 #define SOCD_TRACE_CLASS_MASK (0x0c00) 54 #define SOCD_TRACE_CLASS_SMASK (0x3) 55 #define SOCD_TRACE_CLASS_OFFSET (10) 56 57 #define SOCD_TRACE_CODE_MASK (0x3ff) 58 #define SOCD_TRACE_CODE_SMASK (SOCD_TRACE_CODE_MASK) 59 #define SOCD_TRACE_CODE_OFFSET (0) 60 61 #define SOCD_TRACE_EXTRACT_EVENTID(debugid) (KDBG_EXTRACT_CODE(debugid)) 62 #define SOCD_TRACE_EXTRACT_MODE(debugid) ((SOCD_TRACE_EXTRACT_EVENTID(debugid) & SOCD_TRACE_MODE_MASK) >> SOCD_TRACE_MODE_OFFSET) 63 #define SOCD_TRACE_EXTRACT_CLASS(debugid) ((SOCD_TRACE_EXTRACT_EVENTID(debugid) & SOCD_TRACE_CLASS_MASK) >> SOCD_TRACE_CLASS_OFFSET) 64 #define SOCD_TRACE_EXTRACT_CODE(debugid) ((SOCD_TRACE_EXTRACT_EVENTID(debugid) & SOCD_TRACE_CODE_MASK) >> SOCD_TRACE_CODE_OFFSET) 65 66 /* Generate an eventid corresponding to Mode, Class, Code. */ 67 #define SOCD_TRACE_EVENTID(class, mode, code) \ 68 (((unsigned)((mode) & SOCD_TRACE_MODE_SMASK) << SOCD_TRACE_MODE_OFFSET) | \ 69 ((unsigned)((class) & SOCD_TRACE_CLASS_SMASK) << SOCD_TRACE_CLASS_OFFSET) | \ 70 ((unsigned)((code) & SOCD_TRACE_CODE_SMASK) << SOCD_TRACE_CODE_OFFSET)) 71 72 /* SOCD_TRACE_GEN_STR is used by socd parser to symbolicate trace classes & codes */ 73 #define SOCD_TRACE_GEN_STR(entry) #entry, 74 #define SOCD_TRACE_GEN_CLASS_ENUM(entry) SOCD_TRACE_CLASS_##entry, 75 #define SOCD_TRACE_GEN_CODE_ENUM(entry) SOCD_TRACE_CODE_##entry, 76 77 /* * 78 * List of socd trace classes 79 * 80 * XNU: Tracepoints from xnu itself 81 * WDT: Tracepoints from whatever kext is in charge of the system watchdog 82 * SOC: Tracepoints relating to SoC-wide events or errors (e.g. an SoC thermal sensor reading) 83 */ 84 #define SOCD_TRACE_FOR_EACH_CLASS(iter) \ 85 iter(XNU) \ 86 iter(WDT) \ 87 iter(SOC) 88 89 /* List of xnu trace codes */ 90 #define SOCD_TRACE_FOR_EACH_XNU_CODE(iter) \ 91 iter(XNU_PANIC) \ 92 iter(XNU_START_IOKIT) \ 93 iter(XNU_PLATFORM_ACTION) \ 94 iter(XNU_PM_SET_POWER_STATE) \ 95 iter(XNU_PM_INFORM_POWER_CHANGE) \ 96 iter(XNU_STACKSHOT) \ 97 iter(XNU_PM_SET_POWER_STATE_ACK) \ 98 iter(XNU_PM_INFORM_POWER_CHANGE_ACK) \ 99 iter(XNU_KERNEL_STATE_PANIC) 100 101 typedef enum { 102 SOCD_TRACE_FOR_EACH_CLASS(SOCD_TRACE_GEN_CLASS_ENUM) 103 SOCD_TRACE_CLASS_MAX 104 } socd_client_trace_class_t; 105 106 typedef enum { 107 SOCD_TRACE_FOR_EACH_XNU_CODE(SOCD_TRACE_GEN_CODE_ENUM) 108 SOCD_TRACE_CODE_XNU_MAX 109 } socd_client_trace_code_xnu_t; 110 111 /* * 112 * Records socd client header information. Also used to determine 113 * proper offset when appending trace data to SoCD report. 114 * 115 * SoCD Trace Layout in memory: 116 * socd_push_header_t: 117 * (5 bytes) socd_generic_header_t 118 * (3 bytes) --padding for alignment-- 119 * (4 bytes) socd_desc_t (size of overall region, number of records that are supported === 1) 120 * socd_push_record_t: 121 * (1 byte) agent ID 122 * (1 byte) version 123 * (2 bytes) offset into buff for start of record in 32-bit words 124 * (2 bytes) size (same accounting) 125 * (2 bytes) --padding for alignement-- 126 * socd_client_hdr_t: <--- header reports offset 0x14 here 127 * (4 bytes) version 128 * (8 bytes) boot time 129 * (16 bytes) kernel uuid 130 * (16 bytes) primary KC uuid 131 * socd_client_trace_entry_t: 132 * (8 bytes) timestamp 133 * (4 bytes) debugid 134 * (8 bytes) arg1 135 * (8 bytes) arg2 136 * (8 bytes) arg3 137 * (8 bytes) arg4 138 * <repeating trace records here, each is 44 bytes) 139 * 140 * Trace report will store as many entries as possible within the 141 * allotted space. 142 */ 143 typedef struct { 144 uint32_t version; 145 uint64_t boot_time; 146 uuid_t kernel_uuid; 147 uuid_t primary_kernelcache_uuid; 148 } __attribute__((packed)) socd_client_hdr_t; 149 150 typedef uint64_t socd_client_trace_arg_t; 151 152 typedef struct { 153 uint64_t timestamp; 154 uint32_t debugid; 155 socd_client_trace_arg_t arg1; 156 socd_client_trace_arg_t arg2; 157 socd_client_trace_arg_t arg3; 158 socd_client_trace_arg_t arg4; 159 } __attribute ((packed)) socd_client_trace_entry_t; 160 161 __END_DECLS 162 163 #ifdef KERNEL 164 #include <kern/socd_client_kern.h> 165 #endif /* defined(KERNEL) */ 166 167 #endif /* !defined(_KERN_SOCD_CLIENT_H_) */ 168