/*
 * Copyright (c) 2019-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@
 */

#if !__IIG
#if KERNEL
#include <IOKit/IOMemoryDescriptor.h>
#endif
#endif

#ifndef _IOKIT_UIOMEMORYDESCRIPTOR_H
#define _IOKIT_UIOMEMORYDESCRIPTOR_H

#include <DriverKit/OSObject.iig>

class IOService;
class IOMemoryMap;


// IOMemoryDescriptor Create options
enum {
	kIOMemoryDirectionIn         = 0x00000001,
	kIOMemoryDirectionOut        = 0x00000002,
	kIOMemoryDirectionOutIn      = kIOMemoryDirectionIn | kIOMemoryDirectionOut,
	kIOMemoryDirectionInOut      = kIOMemoryDirectionOutIn,
	kIOMemoryDisableCopyOnWrite  = 0x00000010
};

// IOMemoryDescriptor CreateMapping options
enum {
	kIOMemoryMapFixedAddress          = 0x00000001,
	kIOMemoryMapReadOnly              = 0x00000002,
	kIOMemoryMapCacheModeDefault      = 0x00000000,
	kIOMemoryMapCacheModeInhibit      = 0x00000100,
	kIOMemoryMapCacheModeCopyback     = 0x00000200,
	kIOMemoryMapCacheModeWriteThrough = 0x00000400,
};

struct IOAddressSegment {
	uint64_t address;
	uint64_t length;
};

struct _IOMDPrivateState {
	uint64_t length;
	uint64_t options;
};

/*!
 * @class IOMemoryDescriptor
 *
 * @abstract
 * IOMemoryDescriptor describes a memory buffer. 
 *
 * @discussion
 * To allocate memory for I/O or sharing, use IOBufferMemoryDescriptor::Create()
 * Methods in this class are used for memory that was supplied as a parameter.
 *

@iig implementation
#include <DriverKit/IOService.h>
@iig end
*/

class KERNEL IOMemoryDescriptor : public OSObject
{
public:


	virtual bool
	init() override;

	virtual void
	free() override;

    /*!
     * @brief       Obtain the length of the memory described.
     * @param       returnLength Returned length.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	kern_return_t
	GetLength(
		uint64_t * returnLength) LOCALONLY;

    /*!
     * @brief       Create a mapping of the memory in the callers address space.
     * @param       options
	 *              kIOMemoryMapFixedAddress map at the address requested
	 *              kIOMemoryMapReadOnly create a read only mapping
	 *              kIOMemoryMapCacheModeDefault default cache mode
	 *              kIOMemoryMapCacheModeInhibit inhibited cache mode
	 *              kIOMemoryMapCacheModeCopyback copyback cache mode
	 *              kIOMemoryMapCacheModeWriteThrough write through cache mode
	 * @param       address Requested address if kIOMemoryMapFixedAddress was passed
	 * @param       offset Start offset of the mapping in the descriptor.
	 * @param       length Pass zero to map the entire memory, or a value <= the length of the descriptor.
	 * @param       alignment of the memory virtual mapping. Only zero for no alignment is supported.
	 * @param       map Returned IOMemoryMap object with +1 retain count.
	 *              It should be retained until the map is no longer required.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	CreateMapping(
		uint64_t options,
		uint64_t address,
		uint64_t offset,
		uint64_t length,
		uint64_t alignment,
		IOMemoryMap ** map);

    /*!
     * @brief       Create a memory descriptor that is a subrange of another memory
     *              descriptor
     * @param       memoryDescriptorCreateOptions
	 *              kIOMemoryDirectionIn memory described will be writable
	 *              kIOMemoryDirectionOut memory described will be readable
	 * @param       offset Start offset of the memory relative to the descriptor ofDescriptor.
	 * @param       length Length of the memory.
	 * @param       ofDescriptor Memory descriptor describing source memory.
	 * @param       memory Returned IOMemoryDescriptor object with +1 retain count.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	static kern_return_t
	CreateSubMemoryDescriptor(
	    uint64_t memoryDescriptorCreateOptions,
	    uint64_t offset,
	    uint64_t length,
		IOMemoryDescriptor * ofDescriptor,
		IOMemoryDescriptor ** memory) __attribute__((availability(driverkit,introduced=20.0)));

    /*!
     * @brief       Create a memory descriptor that is a concatenation of a set of memory
     *              descriptors
     * @param       memoryDescriptorCreateOptions
	 *              kIOMemoryDirectionIn memory described will be writable. The source
	 *              descriptors must include this direction.
	 *              kIOMemoryDirectionOut memory described will be readable. The source
	 *              descriptors must include this direction.
	 * @param       withDescriptorsCount Number of valid memory descriptors being passed
	 *              in the withDescriptors array.
	 * @param       withDescriptors Source memory descriptor array.
	 * @param       memory Returned IOMemoryDescriptor object with +1 retain count.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	static kern_return_t
	CreateWithMemoryDescriptors(
	    uint64_t memoryDescriptorCreateOptions,
		uint32_t withDescriptorsCount,
		IOMemoryDescriptor * const withDescriptors[32],
		IOMemoryDescriptor ** memory) __attribute__((availability(driverkit,introduced=20.0)));

private:
	kern_return_t
	Map(
		uint64_t options,
		uint64_t address,
		uint64_t length,
		uint64_t alignment,

		uint64_t * returnAddress,
		uint64_t * returnLength) LOCALONLY;
};

class EXTENDS (IOMemoryDescriptor) IOMemoryDescriptorPrivate
{
	virtual kern_return_t
	_CopyState(
		_IOMDPrivateState * state);
};



#endif /* ! _IOKIT_UIOMEMORYDESCRIPTOR_H */