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#if !__IIG
30#if KERNEL
31#include <IOKit/IOExtensiblePaniclog.h>
32#endif
33#endif
34
35#ifndef _IOKIT_UIOEXTENSIBLEPANICLOG_H
36#define _IOKIT_UIOEXTENSIBLEPANICLOG_H
37
38#include <DriverKit/OSObject.iig>
39#include <DriverKit/IOBufferMemoryDescriptor.iig>
40
41/*!
42@iig implementation
43#include <DriverKit/IODispatchQueue.h>
44#include <DriverKit/IOUserClient.h>
45#include <DriverKit/IOServiceStateNotificationDispatchSource.h>
46@iig end
47*/
48
49enum {
50    kIOExtensiblePaniclogOptionsNone = 0x0,
51    kIOExtensiblePaniclogOptionsWithBuffer = 0x1,
52};
53
54class KERNEL IOExtensiblePaniclog : public OSObject
55{
56public:
57    virtual bool
58    init() override;
59
60    virtual void
61    free() override;
62
63    /*!
64     * @brief       This function is to be called to create IOExtensiblePaniclog object.
65     * @discussion  First function to be called.
66     *
67     * @param       uuid  The UUID of the handle.
68     * @param       data_id The string describing the handle. MAX length of 32.
69     * @param       max_len The maximum length of the buffer.
70     * @param       options Options to be passed while creating the handle
71     * @param       out The pointer to the created IOExtensiblePaniclog object. NULL in case of an error.
72     * @return      True in case of success. False in case of an error.
73     */
74    static kern_return_t
75    Create(OSData *uuid, OSString *data_id, uint32_t max_len, uint32_t options,
76            IOExtensiblePaniclog **out);
77
78    /*!
79     * @brief       This function is called to set the IOExtensiblePaniclog object active.
80     * @discussion  When it is set active, it is picked up and added to the extensible paniclog
81     *              in case of a panic.
82     *
83     * @return      0 on success, negative value in case of failure.
84     */
85    virtual kern_return_t SetActive();
86
87    /*!
88     * @brief       This function is called to set the IOExtensiblePaniclog object inactive.
89     * @discussion  When it is set inactive, this buffer is not picked up in case of a panic
90     *
91     * @return      True in case of success. False in case of an error.
92     */
93    virtual kern_return_t SetInactive();
94
95    /*!
96     * @brief       This function is called to insert data into the buffer.
97     * @discussion  This function overwrites the data in the buffer. The write starts from
98     *              offset 0 and continues until 'len'
99     *
100     * @param       data Data to be inserted
101     * @param       len The length to be copied.
102     *
103     * @return      0 in case of success. Negative in case of an error.
104     */
105    virtual kern_return_t InsertData(OSData *data);
106
107    /*!
108     * @brief       This function is called to insert data into the buffer.
109     * @discussion  This function overwrites the data in the buffer. The write starts from
110     *              last written byte and continues until 'len'
111     *
112     * @param       data Data to be inserted
113     * @param       len The length to be copied.
114     *
115     * @return      0 in case of success. Negative in case of an error.
116     */
117    virtual kern_return_t AppendData(OSData *data);
118
119     /*!
120     * @brief       Function to get the Memory descriptor created in the Create function
121     *
122     * @param       mem The pointer to the IOBufferMemoryDescriptor object
123     *
124     * @return      0 in case of success. Negative in case of an error.
125     */
126    virtual kern_return_t CopyMemoryDescriptor(IOBufferMemoryDescriptor **mem);
127
128     /*!
129     * @brief       This function is called to get a pointer to the ext paniclog buffer
130     * @discussion  After this function is called, the user is responsible for copying data into the buffer.
131     *              The entire buffer is copied when a system panics.
132     *              After claiming the buffer, YieldBuffer() has to be called to set the used_len of the buffer
133     *              before calling InsertData() or AppendData()
134     *
135     * @param       addr Address of the mapped buffer
136     * @param       len The length of the mapped buffer. This is same value as the max_len in
137     *                  the Create() function
138     *
139     * @return      0 in case of success. Negative in case of an error.
140     */
141    virtual kern_return_t ClaimBuffer(uint64_t *addr, uint64_t *len) LOCALONLY;
142
143    /*!
144     * @brief       This function is called to yield the buffer and set the used_len for the buffer
145     * @discussion  After this function call, InsertData() and AppendData() can be called.
146     *
147     * @param       used_len The length of the buffer used by the client.
148     *
149     * @return      0 in case of success. Negative in case of an error.
150     */
151    virtual kern_return_t YieldBuffer(uint32_t used_len) LOCALONLY;
152
153    /*!
154     * @brief       This function is called to set the used len of the buffer
155     *
156     * @param       used_len The length of the buffer used by the client.
157     *
158     * @return      0 in case of success. Negative in case of an error.
159     */
160    virtual kern_return_t SetUsedLen(uint32_t used_len);
161};
162
163#endif /* _IOKIT_UIOEXTENSIBLEPANICLOG_H */
164