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 /* List of socd trace classes */ 78 #define SOCD_TRACE_FOR_EACH_CLASS(iter) \ 79 iter(XNU) \ 80 iter(WDT) 81 82 /* List of xnu trace codes */ 83 #define SOCD_TRACE_FOR_EACH_XNU_CODE(iter) \ 84 iter(XNU_PANIC) \ 85 iter(XNU_START_IOKIT) \ 86 iter(XNU_PLATFORM_ACTION) \ 87 iter(XNU_PM_SET_POWER_STATE) \ 88 iter(XNU_PM_INFORM_POWER_CHANGE) \ 89 iter(XNU_STACKSHOT) \ 90 iter(XNU_PM_SET_POWER_STATE_ACK) \ 91 iter(XNU_PM_INFORM_POWER_CHANGE_ACK) \ 92 iter(XNU_KERNEL_STATE_PANIC) 93 94 typedef enum { 95 SOCD_TRACE_FOR_EACH_CLASS(SOCD_TRACE_GEN_CLASS_ENUM) 96 SOCD_TRACE_CLASS_MAX 97 } socd_client_trace_class_t; 98 99 typedef enum { 100 SOCD_TRACE_FOR_EACH_XNU_CODE(SOCD_TRACE_GEN_CODE_ENUM) 101 SOCD_TRACE_CODE_XNU_MAX 102 } socd_client_trace_code_xnu_t; 103 104 /* * 105 * Records socd client header information. Also used to determine 106 * proper offset when appending trace data to SoCD report. 107 * 108 * SoCD Trace Layout in memory: 109 * socd_push_header_t: 110 * (5 bytes) socd_generic_header_t 111 * (3 bytes) --padding for alignment-- 112 * (4 bytes) socd_desc_t (size of overall region, number of records that are supported === 1) 113 * socd_push_record_t: 114 * (1 byte) agent ID 115 * (1 byte) version 116 * (2 bytes) offset into buff for start of record in 32-bit words 117 * (2 bytes) size (same accounting) 118 * (2 bytes) --padding for alignement-- 119 * socd_client_hdr_t: <--- header reports offset 0x14 here 120 * (4 bytes) version 121 * (8 bytes) boot time 122 * (16 bytes) kernel uuid 123 * (16 bytes) primary KC uuid 124 * socd_client_trace_entry_t: 125 * (8 bytes) timestamp 126 * (4 bytes) debugid 127 * (8 bytes) arg1 128 * (8 bytes) arg2 129 * (8 bytes) arg3 130 * (8 bytes) arg4 131 * <repeating trace records here, each is 44 bytes) 132 * 133 * Trace report will store as many entries as possible within the 134 * allotted space. 135 */ 136 typedef struct { 137 uint32_t version; 138 uint64_t boot_time; 139 uuid_t kernel_uuid; 140 uuid_t primary_kernelcache_uuid; 141 } __attribute__((packed)) socd_client_hdr_t; 142 143 typedef uint64_t socd_client_trace_arg_t; 144 145 typedef struct { 146 uint64_t timestamp; 147 uint32_t debugid; 148 socd_client_trace_arg_t arg1; 149 socd_client_trace_arg_t arg2; 150 socd_client_trace_arg_t arg3; 151 socd_client_trace_arg_t arg4; 152 } __attribute ((packed)) socd_client_trace_entry_t; 153 154 __END_DECLS 155 156 #ifdef KERNEL 157 #include <kern/socd_client_kern.h> 158 #endif /* defined(KERNEL) */ 159 160 #endif /* !defined(_KERN_SOCD_CLIENT_H_) */ 161