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 /* socd trace event id format within kdebug code */ 45 #define SOCD_TRACE_CLASS_MASK (0x3c00) 46 #define SOCD_TRACE_CLASS_SMASK (0xf) 47 #define SOCD_TRACE_CLASS_OFFSET (10) 48 #define SOCD_TRACE_CODE_MASK (0x3ff) 49 #define SOCD_TRACE_CODE_SMASK (SOCD_TRACE_CODE_MASK) 50 #define SOCD_TRACE_CODE_OFFSET (0) 51 52 #define SOCD_TRACE_EXTRACT_EVENTID(debugid) (KDBG_EXTRACT_CODE(debugid)) 53 #define SOCD_TRACE_EXTRACT_CLASS(debugid) ((SOCD_TRACE_EXTRACT_EVENTID(debugid) & SOCD_TRACE_CLASS_MASK) >> SOCD_TRACE_CLASS_OFFSET) 54 #define SOCD_TRACE_EXTRACT_CODE(debugid) ((SOCD_TRACE_EXTRACT_EVENTID(debugid) & SOCD_TRACE_CODE_MASK) >> SOCD_TRACE_CODE_OFFSET) 55 56 /* Generate an eventid corresponding to Class, Code. */ 57 #define SOCD_TRACE_EVENTID(class, code) \ 58 (((unsigned)((class) & SOCD_TRACE_CLASS_SMASK) << SOCD_TRACE_CLASS_OFFSET) | \ 59 ((unsigned)((code) & SOCD_TRACE_CODE_SMASK) << SOCD_TRACE_CODE_OFFSET)) 60 61 /* SOCD_TRACE_GEN_STR is used by socd parser to symbolicate trace classes & codes */ 62 #define SOCD_TRACE_GEN_STR(entry) #entry, 63 #define SOCD_TRACE_GEN_CLASS_ENUM(entry) SOCD_TRACE_CLASS_##entry, 64 #define SOCD_TRACE_GEN_CODE_ENUM(entry) SOCD_TRACE_CODE_##entry, 65 66 /* List of socd trace classes */ 67 #define SOCD_TRACE_FOR_EACH_CLASS(iter) \ 68 iter(XNU) \ 69 iter(WDT) 70 71 /* List of xnu trace codes */ 72 #define SOCD_TRACE_FOR_EACH_XNU_CODE(iter) \ 73 iter(XNU_PANIC) \ 74 iter(XNU_START_IOKIT) \ 75 iter(XNU_PLATFORM_ACTION) \ 76 iter(XNU_PM_SET_POWER_STATE) \ 77 iter(XNU_PM_INFORM_POWER_CHANGE) \ 78 iter(XNU_STACKSHOT) \ 79 iter(XNU_PM_SET_POWER_STATE_ACK) \ 80 iter(XNU_PM_INFORM_POWER_CHANGE_ACK) \ 81 iter(XNU_KERNEL_STATE_PANIC) 82 83 typedef enum { 84 SOCD_TRACE_FOR_EACH_CLASS(SOCD_TRACE_GEN_CLASS_ENUM) 85 SOCD_TRACE_CLASS_MAX 86 } socd_client_trace_class_t; 87 88 typedef enum { 89 SOCD_TRACE_FOR_EACH_XNU_CODE(SOCD_TRACE_GEN_CODE_ENUM) 90 SOCD_TRACE_CODE_XNU_MAX 91 } socd_client_trace_code_xnu_t; 92 93 /* * 94 * Records socd client header information. Also used to determine 95 * proper offset when appending trace data to SoCD report. 96 * 97 * SoCD Trace Layout in memory: 98 * socd_push_header_t: 99 * (5 bytes) socd_generic_header_t 100 * (3 bytes) --padding for alignment-- 101 * (4 bytes) socd_desc_t (size of overall region, number of records that are supported === 1) 102 * socd_push_record_t: 103 * (1 byte) agent ID 104 * (1 byte) version 105 * (2 bytes) offset into buff for start of record in 32-bit words 106 * (2 bytes) size (same accounting) 107 * (2 bytes) --padding for alignement-- 108 * socd_client_hdr_t: <--- header reports offset 0x14 here 109 * (4 bytes) version 110 * (8 bytes) boot time 111 * (16 bytes) kernel uuid 112 * (16 bytes) primary KC uuid 113 * socd_client_trace_entry_t: 114 * (8 bytes) timestamp 115 * (4 bytes) debugid 116 * (8 bytes) arg1 117 * (8 bytes) arg2 118 * (8 bytes) arg3 119 * (8 bytes) arg4 120 * <repeating trace records here, each is 44 bytes) 121 * 122 * Trace report will store as many entries as possible within the 123 * allotted space. 124 */ 125 typedef struct { 126 uint32_t version; 127 uint64_t boot_time; 128 uuid_t kernel_uuid; 129 uuid_t primary_kernelcache_uuid; 130 } __attribute__((packed)) socd_client_hdr_t; 131 132 typedef uint64_t socd_client_trace_arg_t; 133 134 typedef struct { 135 uint64_t timestamp; 136 uint32_t debugid; 137 socd_client_trace_arg_t arg1; 138 socd_client_trace_arg_t arg2; 139 socd_client_trace_arg_t arg3; 140 socd_client_trace_arg_t arg4; 141 } __attribute ((packed)) socd_client_trace_entry_t; 142 143 __END_DECLS 144 145 #ifdef KERNEL 146 #include <kern/socd_client_kern.h> 147 #endif /* defined(KERNEL) */ 148 149 #endif /* !defined(_KERN_SOCD_CLIENT_H_) */ 150