1/* 2 * Copyright (c) 2019-2019 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#if !__IIG 30#if KERNEL 31#include <libkern/c++/OSObject.h> 32#endif 33#endif 34 35#ifndef _IOKIT_UOSOBJECT_H 36#define _IOKIT_UOSOBJECT_H 37 38#if !KERNEL 39#include <stddef.h> 40#include <stdint.h> 41#include <DriverKit/IOReturn.h> 42#if DRIVERKIT_PRIVATE 43#include <mach/port.h> 44#endif /* DRIVERKIT_PRIVATE */ 45#if !__IIG 46#include <string.h> 47#include <DriverKit/OSMetaClass.h> 48#endif /* !__IIG */ 49class OSObject; 50typedef OSObject * OSObjectPtr; 51#endif /* !KERNEL */ 52 53#if !__IIG_ATTRIBUTES_DEFINED__ 54 55#define __IIG_ATTRIBUTES_DEFINED__ 1 56 57#if __IIG || __DOCUMENTATION__ 58 59#define IIG_KERNEL __attribute__((annotate("kernel"))) 60#define IIG_NATIVE __attribute__((annotate("native"))) 61#define IIG_LOCAL __attribute__((annotate("local"))) 62#define IIG_LOCALONLY __attribute__((annotate("localonly"))) 63#define IIG_REMOTE __attribute__((annotate("remote"))) 64#define IIG_LOCALHOST __attribute__((annotate("localhost"))) 65#define IIG_INVOKEREPLY __attribute__((annotate("invokereply"))) 66#define IIG_REPLY __attribute__((annotate("reply"))) 67#define IIG_PORTMAKESEND __attribute__((annotate("MACH_MSG_TYPE_MAKE_SEND"))) 68#define IIG_PORTCOPYSEND __attribute__((annotate("MACH_MSG_TYPE_COPY_SEND"))) 69#define IIG_TARGET __attribute__((annotate("target"))) 70#define IIG_TYPE(p) __attribute__((annotate("type=" # p))) 71//#define IIG_ARRAY(maxcount) __attribute__((annotate(# maxcount), annotate("array"))) 72#define IIG_EXTENDS(cls) __attribute__((annotate("extends=" # cls))) 73//#define IIG_INTERFACE __attribute__((annotate("interface"))) 74//#define IIG_IMPLEMENTS(i) void __implements(i *); 75#define IIG_QUEUENAME(name) __attribute__((annotate("queuename=" # name))) 76#define IIG_SERIALIZABLE __attribute__((annotate("serializable"))) 77#define IIG_CONCRETE __attribute__((annotate("concrete"))) 78 79#if __IIG 80#define KERNEL IIG_KERNEL 81#endif /* __IIG */ 82#define NATIVE IIG_NATIVE 83#define LOCAL IIG_LOCAL 84#define LOCALONLY IIG_LOCALONLY 85#define REMOTE IIG_REMOTE 86#define LOCALHOST IIG_LOCALHOST 87#define INVOKEREPLY IIG_INVOKEREPLY 88#define REPLY IIG_REPLY 89#define PORTMAKESEND IIG_PORTMAKESEND 90#define PORTCOPYSEND IIG_PORTCOPYSEND 91#define TARGET IIG_TARGET 92#define TYPE(p) IIG_TYPE(p) 93//#define ARRAY(maxcount) IIG_ARRAY(maxcount) 94#define EXTENDS(cls) IIG_EXTENDS(cls) 95//#define INTERFACE IIG_INTERFACE 96//#define IMPLEMENTS(i) IIG_IMPLEMENTS(i) 97#define QUEUENAME(name) IIG_QUEUENAME(name) 98 99#else /* __IIG || __DOCUMENTATION__ */ 100 101#define IIG_KERNEL 102#define IIG_NATIVE 103#define IIG_LOCAL 104#define IIG_LOCALONLY 105#define IIG_REMOTE 106#define IIG_LOCALHOST 107#define IIG_INVOKEREPLY 108#define IIG_REPLY 109#define IIG_PORTMAKESEND 110#define IIG_PORTCOPYSEND 111#define IIG_TARGET 112#define IIG_TYPE(p) 113//#define IIG_ARRAY(maxcount) 114#define IIG_EXTENDS(cls) 115//#define IIG_INTERFACE 116//#define IIG_IMPLEMENTS(i) 117#define IIG_QUEUENAME(name) 118#define IIG_SERIALIZABLE 119 120#endif /* __IIG || __DOCUMENTATION__ */ 121 122#endif /* __IIG_ATTRIBUTES_DEFINED__ */ 123 124 125#if !__IIG 126#if KERNEL 127typedef OSObject OSContainer; 128#else /* KERNEL */ 129class IIG_SERIALIZABLE OSContainer; 130#endif /* KERNEL */ 131#else /* !__IIG */ 132class IIG_SERIALIZABLE OSContainer; 133#endif /* !__IIG */ 134 135/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 136 137/* 138 * DRIVERKIT_ macros below can be used to describe the ownership semantics 139 * of functions handling subclasses of OSObject. 140 * The attributes propagate with inheritance, but can be overriden. 141 * New versions of the Clang Static Analyzer can use this knowledge to 142 * check the code for leaks or uses-after-free. 143 */ 144 145#ifndef KERNEL 146/* 147 * By default, methods returning OSObjects are assumed to have the following 148 * owneship semantics: 149 * - Functions and methods that have "Get" in their name are assumed to be 150 * getters. They return at "+0" and the caller is not responsible for releasing 151 * the returned object. 152 * 153 * - All other methods are assumed to return at "+1", and the caller is 154 * responsible for releasing the returned object. 155 * 156 * The semantics implied by the naming convention described above can be 157 * overriden using either DRIVERKIT_RETURNS_RETAINED or 158 * DRIVERKIT_RETURNS_NOT_RETAINED attribute applied to a function. 159 * In the former case, it stipulates that the function is returning at "+1", 160 * and in the latter case "+0". 161 * DRIVERKIT_RETURNS_RETAINED and DRIVERKIT_RETURNS_NOT_RETAINED attributes 162 * can be also applied to out parameters, in which case they specify 163 * that an out parameter is written into at +1 or +0 respectively. 164 * Behavior of out parameters of non-void functions can be additionally 165 * customized via annotations that explain how a function returns a retained 166 * or a non-retained value through its out-parameter depending on its 167 * return value: DRIVERKIT_RETURNS_RETAINED_ON_ZERO and 168 * DRIVERKIT_RETURNS_RETAINED_ON_NONZERO. 169 */ 170#if __has_attribute(os_returns_retained) 171#define DRIVERKIT_RETURNS_RETAINED __attribute__((os_returns_retained)) 172#else 173#define DRIVERKIT_RETURNS_RETAINED 174#endif 175#if __has_attribute(os_returns_not_retained) 176#define DRIVERKIT_RETURNS_NOT_RETAINED __attribute__((os_returns_not_retained)) 177#else 178#define DRIVERKIT_RETURNS_NOT_RETAINED 179#endif 180 181/* 182 * DRIVERKIT_CONSUMED attribute can be applied to parameters. 183 * It specifies that this function call would consume the reference to the 184 * annotated parameter. 185 */ 186#if __has_attribute(os_consumed) 187#define DRIVERKIT_CONSUMED __attribute__((os_consumed)) 188#else 189#define DRIVERKIT_CONSUMED 190#endif 191 192/* 193 * DRIVERKIT_CONSUMES_THIS attribute can be applied to C++ methods. 194 * It specifies that this method call consumes a reference to "this" (e.g. 195 * by storing a reference to "this" in a passed parameter). 196 */ 197#if __has_attribute(os_consumes_this) 198#define DRIVERKIT_CONSUMES_THIS __attribute__((os_consumes_this)) 199#else 200#define DRIVERKIT_CONSUMES_THIS 201#endif 202 203/* 204 * DRIVERKIT_RETURNS_RETAINED_ON_ZERO is an attribute applicable to out 205 * parameters. 206 * It specifies that an out parameter at +1 is written into an argument iff 207 * the function returns a zero return value. 208 */ 209#if __has_attribute(os_returns_retained_on_zero) 210#define DRIVERKIT_RETURNS_RETAINED_ON_ZERO __attribute__((os_returns_retained_on_zero)) 211#else 212#define DRIVERKIT_RETURNS_RETAINED_ON_ZERO 213#endif 214 215/* 216 * DRIVERKIT_RETURNS_RETAINED_ON_NON_ZERO is an attribute applicable to out 217 * parameters. 218 * It specifies that an out parameter at +1 is written into an argument iff 219 * the function returns a non-zero return value. 220 */ 221#if __has_attribute(os_returns_retained_on_non_zero) 222#define DRIVERKIT_RETURNS_RETAINED_ON_NONZERO __attribute__((os_returns_retained_on_non_zero)) 223#else 224#define DRIVERKIT_RETURNS_RETAINED_ON_NONZERO 225#endif 226 227 228/* 229 * Macros below are equivalent to their DRIVERKIT_ counterparts. 230 * They are provided for source-compatibility with IOKit code so they can 231 * be used in code that gets compiled for both platforms. 232 */ 233#define LIBKERN_RETURNS_RETAINED DRIVERKIT_RETURNS_RETAINED 234#define LIBKERN_RETURNS_NOT_RETAINED DRIVERKIT_RETURNS_NOT_RETAINED 235#define LIBKERN_CONSUMED DRIVERKIT_CONSUMED 236#define LIBKERN_CONSUMES_THIS DRIVERKIT_CONSUMES_THIS 237#define LIBKERN_RETURNS_RETAINED_ON_ZERO DRIVERKIT_RETURNS_RETAINED_ON_ZERO 238#define LIBKERN_RETURNS_RETAINED_ON_NONZERO DRIVERKIT_RETURNS_RETAINED_ON_NONZERO 239 240#endif /* !defined(KERNEL) */ 241 242/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 243 244 245class IIG_SERIALIZABLE OSData; 246class IIG_SERIALIZABLE OSNumber; 247class IIG_SERIALIZABLE OSString; 248class IIG_SERIALIZABLE OSBoolean; 249class IIG_SERIALIZABLE OSDictionary; 250class IIG_SERIALIZABLE OSArray; 251class IIG_SERIALIZABLE OSSet; 252class IIG_SERIALIZABLE OSOrderedSet; 253 254class OSMetaClass; 255class IODispatchQueue; 256typedef char IODispatchQueueName[256]; 257 258#if __IIG 259class OSMetaClassBase 260{ 261 virtual const OSMetaClass * 262 getMetaClass() const LOCALONLY; 263 264 virtual void 265 retain() const LOCALONLY; 266 267 virtual void 268 release() const LOCALONLY; 269 270 virtual bool 271 isEqualTo(const OSMetaClassBase * anObject) const LOCALONLY; 272}; 273#endif /* __IIG */ 274 275 276/*! 277@iig implementation 278#include <DriverKit/IODispatchQueue.h> 279@iig end 280*/ 281 282class OSObject : public OSMetaClassBase 283{ 284public: 285 286 virtual bool 287 init() LOCALONLY; 288 289 virtual void 290 free() LOCALONLY; 291 292 virtual void 293 retain() const override; 294 295 virtual void 296 release() const override; 297 298 virtual kern_return_t 299 SetDispatchQueue( 300 const IODispatchQueueName name, 301 IODispatchQueue * queue) KERNEL = 0; 302 303 virtual kern_return_t 304 CopyDispatchQueue( 305 const IODispatchQueueName name, 306 IODispatchQueue ** queue) KERNEL = 0; 307}; 308 309#define DEFN(classname, name) \ 310name ## _Impl(classname ## _ ## name ## _Args) 311 312/* 313 * Use of the IMPL macro is discouraged and should be replaced by a normal c++ 314 * method implementation (with the all method arguments) and the name of the method 315 * given a suffix '_Impl' 316 */ 317 318#define IMPL(classname, name) \ 319classname :: DEFN(classname, name) 320 321/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 322 323#endif /* ! _IOKIT_UOSOBJECT_H */ 324