[apple/xnu.git] / iokit / DriverKit / IOMemoryDescriptor.iig

/*
 * 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 */
Commit	Line	Data
cb323159 A	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 <IOKit/IOMemoryDescriptor.h>
	32	#endif
	33	#endif
	34
	35	#ifndef _IOKIT_UIOMEMORYDESCRIPTOR_H
	36	#define _IOKIT_UIOMEMORYDESCRIPTOR_H
	37
	38	#include <DriverKit/OSObject.iig>
	39
	40	class IOService;
	41	class IOMemoryMap;
	42
	43
	44	// IOMemoryDescriptor Create options
	45	enum {
f427ee49 A	46	kIOMemoryDirectionIn = 0x00000001,
	47	kIOMemoryDirectionOut = 0x00000002,
	48	kIOMemoryDirectionOutIn = kIOMemoryDirectionIn \| kIOMemoryDirectionOut,
	49	kIOMemoryDirectionInOut = kIOMemoryDirectionOutIn,
	50	kIOMemoryDisableCopyOnWrite = 0x00000010
cb323159 A	51	};
	52
	53	// IOMemoryDescriptor CreateMapping options
	54	enum {
	55	kIOMemoryMapFixedAddress = 0x00000001,
	56	kIOMemoryMapReadOnly = 0x00000002,
	57	kIOMemoryMapCacheModeDefault = 0x00000000,
	58	kIOMemoryMapCacheModeInhibit = 0x00000100,
	59	kIOMemoryMapCacheModeCopyback = 0x00000200,
	60	kIOMemoryMapCacheModeWriteThrough = 0x00000400,
	61	};
	62
	63	struct IOAddressSegment {
	64	uint64_t address;
	65	uint64_t length;
	66	};
	67
ea3f0419	68	struct _IOMDPrivateState {
cb323159 A	69	uint64_t length;
	70	uint64_t options;
	71	};
	72
	73	/*!
	74	* @class IOMemoryDescriptor
	75	*
	76	* @abstract
	77	* IOMemoryDescriptor describes a memory buffer.
	78	*
	79	* @discussion
	80	* To allocate memory for I/O or sharing, use IOBufferMemoryDescriptor::Create()
	81	* Methods in this class are used for memory that was supplied as a parameter.
	82	*
	83
	84	@iig implementation
	85	#include <DriverKit/IOService.h>
	86	@iig end
	87	*/
	88
	89	class KERNEL IOMemoryDescriptor : public OSObject
	90	{
	91	public:
	92
	93
	94	virtual bool
	95	init() override;
	96
	97	virtual void
	98	free() override;
	99
	100	/*!
	101	* @brief Obtain the length of the memory described.
	102	* @param returnLength Returned length.
	103	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	104	*/
	105	kern_return_t
	106	GetLength(
	107	uint64_t * returnLength) LOCALONLY;
	108
	109	/*!
	110	* @brief Create a mapping of the memory in the callers address space.
	111	* @param options
	112	* kIOMemoryMapFixedAddress map at the address requested
	113	* kIOMemoryMapReadOnly create a read only mapping
	114	* kIOMemoryMapCacheModeDefault default cache mode
	115	* kIOMemoryMapCacheModeInhibit inhibited cache mode
	116	* kIOMemoryMapCacheModeCopyback copyback cache mode
	117	* kIOMemoryMapCacheModeWriteThrough write through cache mode
	118	* @param address Requested address if kIOMemoryMapFixedAddress was passed
	119	* @param offset Start offset of the mapping in the descriptor.
	120	* @param length Pass zero to map the entire memory, or a value <= the length of the descriptor.
	121	* @param alignment of the memory virtual mapping. Only zero for no alignment is supported.
f427ee49	122	* @param map Returned IOMemoryMap object with +1 retain count.
cb323159 A	123	* It should be retained until the map is no longer required.
	124	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	125	*/
	126	virtual kern_return_t
	127	CreateMapping(
	128	uint64_t options,
	129	uint64_t address,
	130	uint64_t offset,
	131	uint64_t length,
	132	uint64_t alignment,
	133	IOMemoryMap ** map);
	134
f427ee49 A	135	/*!
	136	* @brief Create a memory descriptor that is a subrange of another memory
	137	* descriptor
	138	* @param memoryDescriptorCreateOptions
	139	* kIOMemoryDirectionIn memory described will be writable
	140	* kIOMemoryDirectionOut memory described will be readable
	141	* @param offset Start offset of the memory relative to the descriptor ofDescriptor.
	142	* @param length Length of the memory.
	143	* @param ofDescriptor Memory descriptor describing source memory.
	144	* @param memory Returned IOMemoryDescriptor object with +1 retain count.
	145	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	146	*/
	147	static kern_return_t
	148	CreateSubMemoryDescriptor(
	149	uint64_t memoryDescriptorCreateOptions,
	150	uint64_t offset,
	151	uint64_t length,
	152	IOMemoryDescriptor * ofDescriptor,
	153	IOMemoryDescriptor ** memory) __attribute__((availability(driverkit,introduced=20.0)));
cb323159	154
f427ee49 A	155	/*!
	156	* @brief Create a memory descriptor that is a concatenation of a set of memory
	157	* descriptors
	158	* @param memoryDescriptorCreateOptions
	159	* kIOMemoryDirectionIn memory described will be writable. The source
	160	* descriptors must include this direction.
	161	* kIOMemoryDirectionOut memory described will be readable. The source
	162	* descriptors must include this direction.
	163	* @param withDescriptorsCount Number of valid memory descriptors being passed
	164	* in the withDescriptors array.
	165	* @param withDescriptors Source memory descriptor array.
	166	* @param memory Returned IOMemoryDescriptor object with +1 retain count.
	167	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	168	*/
	169	static kern_return_t
	170	CreateWithMemoryDescriptors(
	171	uint64_t memoryDescriptorCreateOptions,
	172	uint32_t withDescriptorsCount,
	173	IOMemoryDescriptor * const withDescriptors[32],
	174	IOMemoryDescriptor ** memory) __attribute__((availability(driverkit,introduced=20.0)));
cb323159	175
f427ee49	176	private:
cb323159 A	177	kern_return_t
	178	Map(
	179	uint64_t options,
	180	uint64_t address,
	181	uint64_t length,
	182	uint64_t alignment,
	183
	184	uint64_t * returnAddress,
	185	uint64_t * returnLength) LOCALONLY;
	186	};
	187
	188	class EXTENDS (IOMemoryDescriptor) IOMemoryDescriptorPrivate
	189	{
	190	virtual kern_return_t
	191	_CopyState(
ea3f0419	192	_IOMDPrivateState * state);
cb323159 A	193	};
	194
	195
	196
	197	#endif /* ! _IOKIT_UIOMEMORYDESCRIPTOR_H */