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