1 | /* |
2 | * Copyright (c) 2022 Apple Computer, 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 | #ifndef _IOKIT_IOEXTENSIBLEPANICLOG_H |
30 | #define _IOKIT_IOEXTENSIBLEPANICLOG_H |
31 | |
32 | #include <libkern/c++/OSObject.h> |
33 | #include <libkern/c++/OSPtr.h> |
34 | #include <IOKit/IOLib.h> |
35 | #include <DriverKit/IOExtensiblePaniclog.h> |
36 | #include <IOKit/IOBufferMemoryDescriptor.h> |
37 | |
38 | __BEGIN_DECLS |
39 | #include <kern/ext_paniclog.h> |
40 | __END_DECLS |
41 | |
42 | class IOExtensiblePaniclog : public OSObject |
43 | { |
44 | OSDeclareDefaultStructorsWithDispatch(IOExtensiblePaniclog); |
45 | |
46 | private: |
47 | ext_paniclog_handle_t *extPaniclogHandle; |
48 | |
49 | IOBufferMemoryDescriptor *iomd; |
50 | |
51 | protected: |
52 | bool init() APPLE_KEXT_OVERRIDE; |
53 | |
54 | void free(void) APPLE_KEXT_OVERRIDE; |
55 | |
56 | public: |
57 | |
58 | /*! |
59 | * @brief This function is to be called to create IOExtensiblePaniclog object. |
60 | * @discussion First function to be called. |
61 | * |
62 | * @param uuid The UUID of the handle. |
63 | * @param data_id The pointer to a string describing the handle. MAX length of 32. |
64 | * @param max_len The maximum length of the buffer. |
65 | * @param options Options to be passed while creating the handle |
66 | * @param out The pointer to the created IOExtensiblePaniclog object. NULL in case of an error. |
67 | * @return True in case of success. False in case of an error. |
68 | */ |
69 | static bool createWithUUID(uuid_t uuid, const char *data_id, |
70 | uint32_t max_len, ext_paniclog_create_options_t options, IOExtensiblePaniclog **out); |
71 | |
72 | /*! |
73 | * @brief This function is called to set the IOExtensiblePaniclog object active. |
74 | * @discussion When it is set active, it is picked up and added to the extensible paniclog |
75 | * in case of a panic. |
76 | * |
77 | * @return 0 on success, negative value in case of failure. |
78 | */ |
79 | int setActive(); |
80 | |
81 | /*! |
82 | * @brief This function is called to set the IOExtensiblePaniclog object inactive. |
83 | * @discussion When it is set inactive, this buffer is not picked up in case of a panic |
84 | * |
85 | * @return True in case of success. False in case of an error. |
86 | */ |
87 | int setInactive(); |
88 | |
89 | /*! |
90 | * @brief This function is called to insert data into the buffer. |
91 | * @discussion This function overwrites the data in the buffer. The write starts from |
92 | * offset 0 and continues until 'len' |
93 | * |
94 | * @param addr The address of the source buffer |
95 | * @param len The length to be copied. |
96 | * |
97 | * @return 0 in case of success. Negative in case of an error. |
98 | */ |
99 | int insertData(void *addr, uint32_t len); |
100 | |
101 | /*! |
102 | * @brief This function is called to insert data into the buffer. |
103 | * @discussion This function overwrites the data in the buffer. The write starts from |
104 | * last written byte and continues until 'len' |
105 | * |
106 | * @param addr The address of the source buffer |
107 | * @param len The length to be copied. |
108 | * |
109 | * @return 0 in case of success. Negative in case of an error. |
110 | */ |
111 | int appendData(void *addr, uint32_t len); |
112 | |
113 | /*! |
114 | * @brief This function is called to get a pointer to the ext paniclog buffer |
115 | * @discussion After this function is called, the user is responsible for copying data into the buffer. |
116 | * The entire buffer is copied when a system panics. |
117 | * After claiming the buffer, yieldBuffer() has to be called to set the used_len of the buffer |
118 | * before calling insertData() or appendData() |
119 | * |
120 | * @return Returns the address of the buffer. |
121 | */ |
122 | void *claimBuffer(); |
123 | |
124 | /*! |
125 | * @brief This function is called to yield the buffer and set the used_len for the buffer |
126 | * @discussion After this function call, insertData() and appendData() can be called. |
127 | * |
128 | * @param used_len The length of the buffer used by the client. |
129 | * |
130 | * @return 0 in case of success. Negative in case of an error. |
131 | */ |
132 | int yieldBuffer(uint32_t used_len); |
133 | |
134 | /*! |
135 | * @brief This function is called to set the used len of the buffer |
136 | * |
137 | * @param used_len The length of the buffer used by the client. |
138 | * |
139 | * @return 0 in case of success. Negative in case of an error. |
140 | */ |
141 | int setUsedLen(uint32_t used_len); |
142 | }; |
143 | |
144 | #endif // _IOKIT_IOEXTENSIBLEPANICLOG_H |
145 | |