/*
 * Copyright (c) 2019 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */
/* IOOffset.h created by rsulack on Wed 17-Sep-1997 */
/* IOOffset.h converted to C++ by gvdl on Fri 1998-10-30 */

#ifndef _OS_OSNUMBER_H
#define _OS_OSNUMBER_H

#include <libkern/c++/OSPtr.h>
#include <libkern/c++/OSObject.h>

/*!
 * @header
 *
 * @abstract
 * This header declares the OSNumber container class.
 */

class OSNumber;

typedef OSNumber* OSNumberPtr;

/*!
 * @class OSNumber
 *
 * @abstract
 * OSNumber wraps an integer value in a C++ object
 * for use in Libkern collections.
 *
 * @discussion
 * OSNumber represents an integer of 8, 16, 32, or 64 bits
 * as a Libkern C++ object.
 * OSNumber objects are mutable: you can add to or set their values.
 *
 * <b>Use Restrictions</b>
 *
 * With very few exceptions in the I/O Kit, all Libkern-based C++
 * classes, functions, and macros are <b>unsafe</b>
 * to use in a primary interrupt context.
 * Consult the I/O Kit documentation related to primary interrupts
 * for more information.
 *
 * OSNumber provides no concurrency protection;
 * it's up to the usage context to provide any protection necessary.
 * Some portions of the I/O Kit, such as
 * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link,
 * handle synchronization via defined member functions for setting
 * properties.
 */
class OSNumber : public OSObject
{
	friend class OSSerialize;

	OSDeclareDefaultStructors(OSNumber);

#if APPLE_KEXT_ALIGN_CONTAINERS

protected:
	unsigned int size;

#if XNU_KERNEL_PRIVATE
	union {
		unsigned long long value;
		double fpValue;
	};
#else
	unsigned long long value;
#endif /* XNU_KERNEL_PRIVATE */

#else /* APPLE_KEXT_ALIGN_CONTAINERS */

protected:
#if XNU_KERNEL_PRIVATE
	union {
		unsigned long long value;
		double fpValue;
	};
#else
	unsigned long long value;
#endif /* XNU_KERNEL_PRIVATE */
	unsigned int size;

	struct ExpansionData { };

/* Reserved for future use.  (Internal use only)  */
	ExpansionData * reserved;

#endif /* APPLE_KEXT_ALIGN_CONTAINERS */

public:

/*!
 * @function withNumber
 *
 * @abstract
 * Creates and initializes an instance of OSNumber
 * with an integer value.
 *
 * @param value        The numeric integer value for the OSNumber to store.
 * @param numberOfBits The number of bits to limit storage to.
 *
 * @result
 * An instance of OSNumber with a reference count of 1;
 * <code>NULL</code> on failure.
 *
 * @discussion
 * <code>value</code> is masked to the provided <code>numberOfBits</code>
 * when the OSNumber object is initialized.
 *
 * You can change the value of an OSNumber later
 * using <code>@link setValue setValue@/link</code>
 * and <code>@link addValue addValue@/link</code>,
 * but you can't change the bit size.
 */
	static OSPtr<OSNumber> withNumber(
		unsigned long long value,
		unsigned int       numberOfBits);

#if KERNEL_PRIVATE
/*!
 * @function withDouble
 * @abstract
 * Creates and initializes an instance of OSNumber
 * with an double value.
 */
	static OSPtr<OSNumber> withDouble(
		double             value);
/*!
 * @function withFloat
 * @abstract
 * Creates and initializes an instance of OSNumber
 * with an float value.
 */
	static OSPtr<OSNumber> withFloat(
		float              value);
#endif /* KERNEL_PRIVATE */

/*!
 * @function withNumber
 *
 * @abstract
 * Creates and initializes an instance of OSNumber
 * with an unsigned integer value represented as a C string.
 *
 * @param valueString  A C string representing a numeric value
 *                     for the OSNumber to store.
 * @param numberOfBits The number of bits to limit storage to.
 *
 * @result
 * An instance of OSNumber with a reference count of 1;
 * <code>NULL</code> on failure.
 *
 * @discussion
 * This function does not work in I/O Kit versions prior to 8.0 (Mac OS X 10.4).
 * In I/O Kit version 8.0 and later, it works
 * but is limited to parsing unsigned 32 bit quantities.
 * The format of the C string may be decimal, hexadecimal ("0x" prefix),
 * binary ("0b" prefix), or octal ("0" prefix).
 *
 * The parsed value is masked to the provided <code>numberOfBits</code>
 * when the OSNumber object is initialized.
 *
 * You can change the value of an OSNumber later
 * using <code>@link setValue setValue@/link</code>
 * and <code>@link addValue addValue@/link</code>,
 * but you can't change the bit size.
 */
	static OSPtr<OSNumber> withNumber(
		const char   * valueString,
		unsigned int   numberOfBits);


/*!
 * @function init
 *
 * @abstract
 * Initializes an instance of OSNumber with an integer value.
 *
 * @param value        The numeric integer value for the OSNumber to store.
 * @param numberOfBits The number of bits to limit storage to.
 *
 * @result
 * <code>true</code> if initialization succeeds,
 * <code>false</code> on failure.
 *
 * @discussion
 * Not for general use. Use the static instance creation method
 * <code>@link
 * //apple_ref/cpp/clm/OSNumber/withNumber/staticOSNumber*\/(constchar*,unsignedint)
 * withNumber(unsigned long long, unsigned int)@/link</code>
 * instead.
 */
	virtual bool init(
		unsigned long long value,
		unsigned int       numberOfBits);


/*!
 * @function init
 *
 * @abstract
 * Initializes an instance of OSNumber
 * with an unsigned integer value represented as a C string.
 *
 * @param valueString  A C string representing a numeric value
 *                     for the OSNumber to store.
 * @param numberOfBits The number of bits to limit storage to.
 *
 * @result
 * <code>true</code> if initialization succeeds,
 * <code>false</code> on failure.
 *
 * @discussion
 * Not for general use. Use the static instance creation method
 * <code>@link
 * //apple_ref/cpp/clm/OSNumber/withNumber/staticOSNumber*\/(constchar*,unsignedint)
 * withNumber(const char *, unsigned int)@/link</code>
 * instead.
 */
	virtual bool init(
		const char   * valueString,
		unsigned int   numberOfBits);


/*!
 * @function free
 *
 * @abstract
 * Deallocates or releases any resources
 * used by the OSNumber instance.
 *
 * @discussion
 * This function should not be called directly;
 * use
 * <code>@link
 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 * release@/link</code>
 * instead.
 */
	virtual void free() APPLE_KEXT_OVERRIDE;


/*!
 * @function numberOfBits
 *
 * @abstract
 * Returns the number of bits used to represent
 * the OSNumber object's integer value.
 *
 * @result
 * The number of bits used to represent
 * the OSNumber object's integer value.
 *
 * @discussion
 * The number of bits is used to limit the stored value of the OSNumber.
 * Any change to its value is performed as an <code>unsigned long long</code>
 * and then truncated to the number of bits.
 */
	virtual unsigned int numberOfBits() const;


/*!
 * @function numberOfBytes
 *
 * @abstract
 * Returns the number of bytes used to represent
 * the OSNumber object's integer value.
 *
 * @result
 * The number of bytes used to represent
 * the OSNumber object's integer value.
 * See <code>@link numberOfBits numberOfBits@/link</code>.
 */
	virtual unsigned int numberOfBytes() const;


// xx-review: should switch to explicitly-sized int types
// xx-review: but that messes up C++ mangled symbols :-(


/*!
 * @function unsigned8BitValue
 *
 * @abstract
 * Returns the OSNumber object's integer value
 * cast as an unsigned 8-bit integer.
 *
 * @result
 * The OSNumber object's integer value
 * cast as an unsigned 8-bit integer.
 *
 * @discussion
 * This function merely casts the internal integer value,
 * giving no indication of truncation or other potential conversion problems.
 */
	virtual unsigned char unsigned8BitValue() const;


/*!
 * @function unsigned16BitValue
 *
 * @abstract
 * Returns the OSNumber object's integer value
 * cast as an unsigned 16-bit integer.
 *
 * @result
 * Returns the OSNumber object's integer value
 * cast as an unsigned 16-bit integer.
 *
 * @discussion
 * This function merely casts the internal integer value,
 * giving no indication of truncation or other potential conversion problems.
 */
	virtual unsigned short unsigned16BitValue() const;


/*!
 * @function unsigned32BitValue
 *
 * @abstract
 * Returns the OSNumber object's integer value
 * cast as an unsigned 32-bit integer.
 *
 * @result
 * Returns the OSNumber object's integer value
 * cast as an unsigned 32-bit integer.
 *
 * @discussion
 * This function merely casts the internal integer value,
 * giving no indication of truncation or other potential conversion problems.
 */
	virtual unsigned int unsigned32BitValue() const;


/*!
 * @function unsigned64BitValue
 *
 * @abstract
 * Returns the OSNumber object's integer value
 * cast as an unsigned 64-bit integer.
 *
 * @result
 * Returns the OSNumber object's integer value
 * cast as an unsigned 64-bit integer.
 *
 * @discussion
 * This function merely casts the internal integer value,
 * giving no indication of truncation or other potential conversion problems.
 */
	virtual unsigned long long unsigned64BitValue() const;

#if KERNEL_PRIVATE
/*!
 * @function withDouble
 * @abstract
 * Returns the OSNumber object's floating point value.
 */
	double doubleValue() const;
/*!
 * @function withFloat
 * @abstract
 * Returns the OSNumber object's floating point value.
 */
	float floatValue() const;
#endif /* KERNEL_PRIVATE */


// xx-review: wow, there's no addNumber(OSNumber *)!

/*!
 * @function addValue
 *
 * @abstract
 * Adds a signed integer value to the internal integer value
 * of the OSNumber object.
 *
 * @param value  The value to be added.
 *
 * @discussion
 * This function adds values as 64-bit integers,
 * but masks the result by the bit size
 * (see <code>@link numberOfBits numberOfBits@/link</code>),
 * so addition overflows will not necessarily
 * be the same as for plain C integers.
 */
	virtual void addValue(signed long long value);


/*!
 * @function setValue
 *
 * @abstract
 * Replaces the current internal integer value
 * of the OSNumber object by the value given.
 *
 * @param value  The new value for the OSNumber object,
 *               which is truncated by the bit size of the OSNumber object
 *               (see <code>@link numberOfBits numberOfBits@/link</code>).
 */
	virtual void setValue(unsigned long long value);


/*!
 * @function isEqualTo
 *
 * @abstract
 * Tests the equality of two OSNumber objects.
 *
 * @param aNumber     The OSNumber to be compared against the receiver.
 *
 * @result
 * <code>true</code> if the OSNumber objects are equal,
 * <code>false</code> if not.
 *
 * @discussion
 * Two OSNumber objects are considered equal
 * if they represent the same C integer value.
 */
#if KERNEL_PRIVATE
/* Only compares the integer portion of the two OSNumber values.
 */
#endif /* KERNEL_PRIVATE */
	virtual bool isEqualTo(const OSNumber * aNumber) const;


/*!
 * @function isEqualTo
 *
 * @abstract
 * Tests the equality an OSNumber to an arbitrary object.
 *
 * @param anObject An object to be compared against the receiver.
 *
 * @result
 * <code>true</code> if the objects are equal,
 * <code>false</code> if not.
 *
 * @discussion
 * An OSNumber is considered equal to another object if that object is
 * derived from OSNumber and represents the same C integer value.
 */
	virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE;


/*!
 * @function serialize
 *
 * @abstract
 * Archives the receiver into the provided
 * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
 *
 * @param serializer The OSSerialize object.
 *
 * @result
 * <code>true</code> if serialization succeeds, <code>false</code> if not.
 */
	virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE;


	OSMetaClassDeclareReservedUnused(OSNumber, 0);
	OSMetaClassDeclareReservedUnused(OSNumber, 1);
	OSMetaClassDeclareReservedUnused(OSNumber, 2);
	OSMetaClassDeclareReservedUnused(OSNumber, 3);
	OSMetaClassDeclareReservedUnused(OSNumber, 4);
	OSMetaClassDeclareReservedUnused(OSNumber, 5);
	OSMetaClassDeclareReservedUnused(OSNumber, 6);
	OSMetaClassDeclareReservedUnused(OSNumber, 7);
};

#endif /* !_OS_OSNUMBER_H */