1 /* 2 * Copyright (c) 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 /* IOOffset.h created by rsulack on Wed 17-Sep-1997 */ 29 /* IOOffset.h converted to C++ by gvdl on Fri 1998-10-30 */ 30 31 #ifndef _OS_OSNUMBER_H 32 #define _OS_OSNUMBER_H 33 34 #include <libkern/c++/OSPtr.h> 35 #include <libkern/c++/OSObject.h> 36 37 /*! 38 * @header 39 * 40 * @abstract 41 * This header declares the OSNumber container class. 42 */ 43 44 class OSNumber; 45 46 typedef OSNumber* OSNumberPtr; 47 48 /*! 49 * @class OSNumber 50 * 51 * @abstract 52 * OSNumber wraps an integer value in a C++ object 53 * for use in Libkern collections. 54 * 55 * @discussion 56 * OSNumber represents an integer of 8, 16, 32, or 64 bits 57 * as a Libkern C++ object. 58 * OSNumber objects are mutable: you can add to or set their values. 59 * 60 * <b>Use Restrictions</b> 61 * 62 * With very few exceptions in the I/O Kit, all Libkern-based C++ 63 * classes, functions, and macros are <b>unsafe</b> 64 * to use in a primary interrupt context. 65 * Consult the I/O Kit documentation related to primary interrupts 66 * for more information. 67 * 68 * OSNumber provides no concurrency protection; 69 * it's up to the usage context to provide any protection necessary. 70 * Some portions of the I/O Kit, such as 71 * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link, 72 * handle synchronization via defined member functions for setting 73 * properties. 74 */ 75 class OSNumber : public OSObject 76 { 77 friend class OSSerialize; 78 79 OSDeclareDefaultStructors(OSNumber); 80 81 #if APPLE_KEXT_ALIGN_CONTAINERS 82 83 protected: 84 unsigned int size; 85 unsigned long long value; 86 87 #else /* APPLE_KEXT_ALIGN_CONTAINERS */ 88 89 protected: 90 unsigned long long value; 91 unsigned int size; 92 93 struct ExpansionData { }; 94 95 /* Reserved for future use. (Internal use only) */ 96 ExpansionData * reserved; 97 98 #endif /* APPLE_KEXT_ALIGN_CONTAINERS */ 99 100 public: 101 102 /*! 103 * @function withNumber 104 * 105 * @abstract 106 * Creates and initializes an instance of OSNumber 107 * with an integer value. 108 * 109 * @param value The numeric integer value for the OSNumber to store. 110 * @param numberOfBits The number of bits to limit storage to. 111 * 112 * @result 113 * An instance of OSNumber with a reference count of 1; 114 * <code>NULL</code> on failure. 115 * 116 * @discussion 117 * <code>value</code> is masked to the provided <code>numberOfBits</code> 118 * when the OSNumber object is initialized. 119 * 120 * You can change the value of an OSNumber later 121 * using <code>@link setValue setValue@/link</code> 122 * and <code>@link addValue addValue@/link</code>, 123 * but you can't change the bit size. 124 */ 125 static OSPtr<OSNumber> withNumber( 126 unsigned long long value, 127 unsigned int numberOfBits); 128 129 130 /*! 131 * @function withNumber 132 * 133 * @abstract 134 * Creates and initializes an instance of OSNumber 135 * with an unsigned integer value represented as a C string. 136 * 137 * @param valueString A C string representing a numeric value 138 * for the OSNumber to store. 139 * @param numberOfBits The number of bits to limit storage to. 140 * 141 * @result 142 * An instance of OSNumber with a reference count of 1; 143 * <code>NULL</code> on failure. 144 * 145 * @discussion 146 * This function does not work in I/O Kit versions prior to 8.0 (Mac OS X 10.4). 147 * In I/O Kit version 8.0 and later, it works 148 * but is limited to parsing unsigned 32 bit quantities. 149 * The format of the C string may be decimal, hexadecimal ("0x" prefix), 150 * binary ("0b" prefix), or octal ("0" prefix). 151 * 152 * The parsed value is masked to the provided <code>numberOfBits</code> 153 * when the OSNumber object is initialized. 154 * 155 * You can change the value of an OSNumber later 156 * using <code>@link setValue setValue@/link</code> 157 * and <code>@link addValue addValue@/link</code>, 158 * but you can't change the bit size. 159 */ 160 static OSPtr<OSNumber> withNumber( 161 const char * valueString, 162 unsigned int numberOfBits); 163 164 165 /*! 166 * @function init 167 * 168 * @abstract 169 * Initializes an instance of OSNumber with an integer value. 170 * 171 * @param value The numeric integer value for the OSNumber to store. 172 * @param numberOfBits The number of bits to limit storage to. 173 * 174 * @result 175 * <code>true</code> if initialization succeeds, 176 * <code>false</code> on failure. 177 * 178 * @discussion 179 * Not for general use. Use the static instance creation method 180 * <code>@link 181 * //apple_ref/cpp/clm/OSNumber/withNumber/staticOSNumber*\/(constchar*,unsignedint) 182 * withNumber(unsigned long long, unsigned int)@/link</code> 183 * instead. 184 */ 185 virtual bool init( 186 unsigned long long value, 187 unsigned int numberOfBits); 188 189 190 /*! 191 * @function init 192 * 193 * @abstract 194 * Initializes an instance of OSNumber 195 * with an unsigned integer value represented as a C string. 196 * 197 * @param valueString A C string representing a numeric value 198 * for the OSNumber to store. 199 * @param numberOfBits The number of bits to limit storage to. 200 * 201 * @result 202 * <code>true</code> if initialization succeeds, 203 * <code>false</code> on failure. 204 * 205 * @discussion 206 * Not for general use. Use the static instance creation method 207 * <code>@link 208 * //apple_ref/cpp/clm/OSNumber/withNumber/staticOSNumber*\/(constchar*,unsignedint) 209 * withNumber(const char *, unsigned int)@/link</code> 210 * instead. 211 */ 212 virtual bool init( 213 const char * valueString, 214 unsigned int numberOfBits); 215 216 217 /*! 218 * @function free 219 * 220 * @abstract 221 * Deallocates or releases any resources 222 * used by the OSNumber instance. 223 * 224 * @discussion 225 * This function should not be called directly; 226 * use 227 * <code>@link 228 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/() 229 * release@/link</code> 230 * instead. 231 */ 232 virtual void free() APPLE_KEXT_OVERRIDE; 233 234 235 /*! 236 * @function numberOfBits 237 * 238 * @abstract 239 * Returns the number of bits used to represent 240 * the OSNumber object's integer value. 241 * 242 * @result 243 * The number of bits used to represent 244 * the OSNumber object's integer value. 245 * 246 * @discussion 247 * The number of bits is used to limit the stored value of the OSNumber. 248 * Any change to its value is performed as an <code>unsigned long long</code> 249 * and then truncated to the number of bits. 250 */ 251 virtual unsigned int numberOfBits() const; 252 253 254 /*! 255 * @function numberOfBytes 256 * 257 * @abstract 258 * Returns the number of bytes used to represent 259 * the OSNumber object's integer value. 260 * 261 * @result 262 * The number of bytes used to represent 263 * the OSNumber object's integer value. 264 * See <code>@link numberOfBits numberOfBits@/link</code>. 265 */ 266 virtual unsigned int numberOfBytes() const; 267 268 269 // xx-review: should switch to explicitly-sized int types 270 // xx-review: but that messes up C++ mangled symbols :-( 271 272 273 /*! 274 * @function unsigned8BitValue 275 * 276 * @abstract 277 * Returns the OSNumber object's integer value 278 * cast as an unsigned 8-bit integer. 279 * 280 * @result 281 * The OSNumber object's integer value 282 * cast as an unsigned 8-bit integer. 283 * 284 * @discussion 285 * This function merely casts the internal integer value, 286 * giving no indication of truncation or other potential conversion problems. 287 */ 288 virtual unsigned char unsigned8BitValue() const; 289 290 291 /*! 292 * @function unsigned16BitValue 293 * 294 * @abstract 295 * Returns the OSNumber object's integer value 296 * cast as an unsigned 16-bit integer. 297 * 298 * @result 299 * Returns the OSNumber object's integer value 300 * cast as an unsigned 16-bit integer. 301 * 302 * @discussion 303 * This function merely casts the internal integer value, 304 * giving no indication of truncation or other potential conversion problems. 305 */ 306 virtual unsigned short unsigned16BitValue() const; 307 308 309 /*! 310 * @function unsigned32BitValue 311 * 312 * @abstract 313 * Returns the OSNumber object's integer value 314 * cast as an unsigned 32-bit integer. 315 * 316 * @result 317 * Returns the OSNumber object's integer value 318 * cast as an unsigned 32-bit integer. 319 * 320 * @discussion 321 * This function merely casts the internal integer value, 322 * giving no indication of truncation or other potential conversion problems. 323 */ 324 virtual unsigned int unsigned32BitValue() const; 325 326 327 /*! 328 * @function unsigned64BitValue 329 * 330 * @abstract 331 * Returns the OSNumber object's integer value 332 * cast as an unsigned 64-bit integer. 333 * 334 * @result 335 * Returns the OSNumber object's integer value 336 * cast as an unsigned 64-bit integer. 337 * 338 * @discussion 339 * This function merely casts the internal integer value, 340 * giving no indication of truncation or other potential conversion problems. 341 */ 342 virtual unsigned long long unsigned64BitValue() const; 343 344 // xx-review: wow, there's no addNumber(OSNumber *)! 345 346 /*! 347 * @function addValue 348 * 349 * @abstract 350 * Adds a signed integer value to the internal integer value 351 * of the OSNumber object. 352 * 353 * @param value The value to be added. 354 * 355 * @discussion 356 * This function adds values as 64-bit integers, 357 * but masks the result by the bit size 358 * (see <code>@link numberOfBits numberOfBits@/link</code>), 359 * so addition overflows will not necessarily 360 * be the same as for plain C integers. 361 */ 362 virtual void addValue(signed long long value); 363 364 365 /*! 366 * @function setValue 367 * 368 * @abstract 369 * Replaces the current internal integer value 370 * of the OSNumber object by the value given. 371 * 372 * @param value The new value for the OSNumber object, 373 * which is truncated by the bit size of the OSNumber object 374 * (see <code>@link numberOfBits numberOfBits@/link</code>). 375 */ 376 virtual void setValue(unsigned long long value); 377 378 379 /*! 380 * @function isEqualTo 381 * 382 * @abstract 383 * Tests the equality of two OSNumber objects. 384 * 385 * @param aNumber The OSNumber to be compared against the receiver. 386 * 387 * @result 388 * <code>true</code> if the OSNumber objects are equal, 389 * <code>false</code> if not. 390 * 391 * @discussion 392 * Two OSNumber objects are considered equal 393 * if they represent the same C integer value. 394 */ 395 virtual bool isEqualTo(const OSNumber * aNumber) const; 396 397 398 /*! 399 * @function isEqualTo 400 * 401 * @abstract 402 * Tests the equality an OSNumber to an arbitrary object. 403 * 404 * @param anObject An object to be compared against the receiver. 405 * 406 * @result 407 * <code>true</code> if the objects are equal, 408 * <code>false</code> if not. 409 * 410 * @discussion 411 * An OSNumber is considered equal to another object if that object is 412 * derived from OSNumber and represents the same C integer value. 413 */ 414 virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE; 415 416 417 /*! 418 * @function serialize 419 * 420 * @abstract 421 * Archives the receiver into the provided 422 * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object. 423 * 424 * @param serializer The OSSerialize object. 425 * 426 * @result 427 * <code>true</code> if serialization succeeds, <code>false</code> if not. 428 */ 429 virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE; 430 431 432 OSMetaClassDeclareReservedUnused(OSNumber, 0); 433 OSMetaClassDeclareReservedUnused(OSNumber, 1); 434 OSMetaClassDeclareReservedUnused(OSNumber, 2); 435 OSMetaClassDeclareReservedUnused(OSNumber, 3); 436 OSMetaClassDeclareReservedUnused(OSNumber, 4); 437 OSMetaClassDeclareReservedUnused(OSNumber, 5); 438 OSMetaClassDeclareReservedUnused(OSNumber, 6); 439 OSMetaClassDeclareReservedUnused(OSNumber, 7); 440 }; 441 442 #endif /* !_OS_OSNUMBER_H */ 443