[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,
};

// 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);

private:
	virtual kern_return_t
	PrepareForDMA(
		uint64_t options,
		IOService * device,
		uint64_t offset,
		uint64_t length,

		uint64_t * flags,
		uint64_t * returnLength,
		uint32_t * segmentsCount,
		IOAddressSegment segments[32]);

	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 {
	46	kIOMemoryDirectionIn = 0x00000001,
	47	kIOMemoryDirectionOut = 0x00000002,
	48	kIOMemoryDirectionOutIn = kIOMemoryDirectionIn \| kIOMemoryDirectionOut,
	49	kIOMemoryDirectionInOut = kIOMemoryDirectionOutIn,
	50	};
	51
	52	// IOMemoryDescriptor CreateMapping options
	53	enum {
	54	kIOMemoryMapFixedAddress = 0x00000001,
	55	kIOMemoryMapReadOnly = 0x00000002,
	56	kIOMemoryMapCacheModeDefault = 0x00000000,
	57	kIOMemoryMapCacheModeInhibit = 0x00000100,
	58	kIOMemoryMapCacheModeCopyback = 0x00000200,
	59	kIOMemoryMapCacheModeWriteThrough = 0x00000400,
	60	};
	61
	62	struct IOAddressSegment {
	63	uint64_t address;
	64	uint64_t length;
65	};
66
ea3f0419	67	struct _IOMDPrivateState {
cb323159 A	68	uint64_t length;
	69	uint64_t options;
	70	};
	71
	72	/*!
	73	* @class IOMemoryDescriptor
	74	*
	75	* @abstract
	76	* IOMemoryDescriptor describes a memory buffer.
	77	*
	78	* @discussion
	79	* To allocate memory for I/O or sharing, use IOBufferMemoryDescriptor::Create()
	80	* Methods in this class are used for memory that was supplied as a parameter.
	81	*
	82
	83	@iig implementation
	84	#include <DriverKit/IOService.h>
	85	@iig end
	86	*/
	87
	88	class KERNEL IOMemoryDescriptor : public OSObject
	89	{
	90	public:
	91
	92
	93	virtual bool
	94	init() override;
	95
	96	virtual void
	97	free() override;
	98
	99	/*!
	100	* @brief Obtain the length of the memory described.
	101	* @param returnLength Returned length.
	102	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	103	*/
	104	kern_return_t
	105	GetLength(
	106	uint64_t * returnLength) LOCALONLY;
	107
	108	/*!
	109	* @brief Create a mapping of the memory in the callers address space.
	110	* @param options
	111	* kIOMemoryMapFixedAddress map at the address requested
	112	* kIOMemoryMapReadOnly create a read only mapping
	113	* kIOMemoryMapCacheModeDefault default cache mode
	114	* kIOMemoryMapCacheModeInhibit inhibited cache mode
	115	* kIOMemoryMapCacheModeCopyback copyback cache mode
	116	* kIOMemoryMapCacheModeWriteThrough write through cache mode
	117	* @param address Requested address if kIOMemoryMapFixedAddress was passed
	118	* @param offset Start offset of the mapping in the descriptor.
	119	* @param length Pass zero to map the entire memory, or a value <= the length of the descriptor.
	120	* @param alignment of the memory virtual mapping. Only zero for no alignment is supported.
	121	* @param map Returned IOMemoryMap object with +1 retain count.
	122	* It should be retained until the map is no longer required.
	123	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
	124	*/
	125	virtual kern_return_t
	126	CreateMapping(
	127	uint64_t options,
	128	uint64_t address,
	129	uint64_t offset,
	130	uint64_t length,
	131	uint64_t alignment,
132	IOMemoryMap ** map);
133
134	private:
135	virtual kern_return_t
136	PrepareForDMA(
137	uint64_t options,
138	IOService * device,
139	uint64_t offset,
140	uint64_t length,
141
142	uint64_t * flags,
143	uint64_t * returnLength,
144	uint32_t * segmentsCount,
145	IOAddressSegment segments[32]);
146
147	kern_return_t
148	Map(
149	uint64_t options,
150	uint64_t address,
151	uint64_t length,
152	uint64_t alignment,
153
154	uint64_t * returnAddress,
155	uint64_t * returnLength) LOCALONLY;
156	};
157
158	class EXTENDS (IOMemoryDescriptor) IOMemoryDescriptorPrivate
159	{
160	virtual kern_return_t
161	_CopyState(
ea3f0419	162	_IOMDPrivateState * state);
cb323159 A	163	};
	164
	165
	166
	167	#endif /* ! _IOKIT_UIOMEMORYDESCRIPTOR_H */