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
42class IOExtensiblePaniclog : public OSObject
43{
44 OSDeclareDefaultStructorsWithDispatch(IOExtensiblePaniclog);
45
46private:
47 ext_paniclog_handle_t *extPaniclogHandle;
48
49 IOBufferMemoryDescriptor *iomd;
50
51protected:
52 bool init() APPLE_KEXT_OVERRIDE;
53
54 void free(void) APPLE_KEXT_OVERRIDE;
55
56public:
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