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
83typedef enum {
84 SOCD_TRACE_FOR_EACH_CLASS(SOCD_TRACE_GEN_CLASS_ENUM)
85 SOCD_TRACE_CLASS_MAX
86} socd_client_trace_class_t;
87
88typedef 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 */
125typedef 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
132typedef uint64_t socd_client_trace_arg_t;
133
134typedef 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