include/linux/vcm.h - fp2-dev/kernel/msm - Gitiles

 /* Copyright (c) 2010, Code Aurora Forum. All rights reserved.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License version 2 and
  * only version 2 as published by the Free Software Foundation.
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
  *
  */

 #ifndef _VCM_H_
 #define _VCM_H_

 /* All undefined types must be defined using platform specific headers */

 #include <linux/vcm_types.h>

 /*
  * Virtual contiguous memory (VCM) region primitives.
  *
  * Current memory mapping software uses a CPU centric management
  * model. This makes sense in general, average hardware only contains an
  * CPU MMU and possibly a graphics MMU. If every device in the system
  * has one or more MMUs a CPU centric MM programming model breaks down.
  *
  * Looking at mapping from a system-wide perspective reveals a general
  * graph problem. Each node that talks to memory, either through an MMU
  * or directly (via physical memory) can be thought of as the device end
  * of a mapping edge. The other edge is the physical memory that is
  * mapped.
  *
  * In the direct mapped case, it is useful to give the device an
  * MMU. This one-to-one MMU allows direct mapped devices to
  * participate in graph management, they simply see memory through a
  * one-to-one mapping.
  *
  * The CPU nodes can also be brought under the same mapping
  * abstraction with the use of a light overlay on the existing
  * VMM. This light overlay brings the VMM's page table abstraction for
  * each process and the kernel into the graph management API.
  *
  * Taken together this system wide approach provides a capability that
  * is greater than the sum of its parts by allowing users to reason
  * about system wide mapping issues without getting bogged down in CPU
  * centric device page table management issues.
  */


 /*
  * Creating, freeing and managing VCMs.
  *
  * A VCM region is a virtual space that can be reserved from and
  * associated with one or more devices. At creation the user can
  * specify an offset to start addresses and a length of the entire VCM
  * region. Reservations out of a VCM region are always contiguous.
  */

 /**
  * vcm_create() - Create a VCM region
  * @start_addr:		The starting address of the VCM region.
  * @len:		The len of the VCM region. This must be at least
  *			vcm_get_min_page_size() bytes.
  *
  * A VCM typically abstracts a page table.
  *
  * All functions in this API are passed and return opaque things
  * because the underlying implementations will vary. The goal
  * is really graph management. vcm_create() creates the "device end"
  * of an edge in the mapping graph.
  *
  * The return value is non-zero if a VCM has successfully been
  * created. It will return zero if a VCM region cannot be created or
  * len is invalid.
  */
 struct vcm *vcm_create(unsigned long start_addr, size_t len);


 /**
  * vcm_create_from_prebuilt() - Create a VCM region from an existing region
  * @ext_vcm_id:		An external opaque value that allows the
  *			implementation to reference an already built table.
  *
  * The ext_vcm_id will probably reference a page table that's been built
  * by the VM.
  *
  * The platform specific implementation will provide this.
  *
  * The return value is non-zero if a VCM has successfully been created.
  */
 struct vcm *vcm_create_from_prebuilt(size_t ext_vcm_id);


 /**
  * vcm_clone() - Clone a VCM
  * @vcm:		A VCM to clone from.
  *
  * Perform a VCM "deep copy." The resulting VCM will match the original at
  * the point of cloning. Subsequent updates to either VCM will only be
  * seen by that VCM.
  *
  * The return value is non-zero if a VCM has been successfully cloned.
  */
 struct vcm *vcm_clone(struct vcm *vcm);


 /**
  * vcm_get_start_addr() - Get the starting address of the VCM region.
  * @vcm:		The VCM we're interested in getting the starting
  *			address of.
  *
  * The return value will be 1 if an error has occurred.
  */
 size_t vcm_get_start_addr(struct vcm *vcm);


 /**
  * vcm_get_len() - Get the length of the VCM region.
  * @vcm:		The VCM we're interested in reading the length from.
  *
  * The return value will be non-zero for a valid VCM. VCM regions
  * cannot have 0 len.
  */
 size_t vcm_get_len(struct vcm *vcm);


 /**
  * vcm_free() - Free a VCM.
  * @vcm:		The VCM we're interested in freeing.
  *
  * The return value is 0 if the VCM has been freed or:
  * -EBUSY		The VCM region contains reservations or has been
  *			associated (active or not) and cannot be freed.
  * -EINVAL		The vcm argument is invalid.
  */
 int vcm_free(struct vcm *vcm);


 /*
  * Creating, freeing and managing reservations out of a VCM.
  *
  */

 /**
  * vcm_reserve() - Create a reservation from a VCM region.
  * @vcm:		The VCM region to reserve from.
  * @len:		The length of the reservation. Must be at least
  *			vcm_get_min_page_size() bytes.
  * @attr:		See 'Reservation Attributes'.
  *
  * A reservation, res_t, is a contiguous range from a VCM region.
  *
  * The return value is non-zero if a reservation has been successfully
  * created. It is 0 if any of the parameters are invalid.
  */
 struct res *vcm_reserve(struct vcm *vcm, size_t len, u32 attr);


 /**
  * vcm_reserve_at() - Make a reservation at a given logical location.
  * @memtarget:		A logical location to start the reservation from.
  * @vcm:		The VCM region to start the reservation from.
  * @len:		The length of the reservation.
  * @attr:		See 'Reservation Attributes'.
  *
  * The return value is non-zero if a reservation has been successfully
  * created.
  */
 struct res *vcm_reserve_at(enum memtarget_t memtarget, struct vcm *vcm,
 			   size_t len, u32 attr);


 /**
  * vcm_get_vcm_from_res() - Return the VCM region of a reservation.
  * @res:		The reservation to return the VCM region of.
  *
  * Te return value will be non-zero if the reservation is valid. A valid
  * reservation is always associated with a VCM region; there is no such
  * thing as an orphan reservation.
  */
 struct vcm *vcm_get_vcm_from_res(struct res *res);


 /**
  * vcm_unreserve() - Unreserve the reservation.
  * @res:		The reservation to unreserve.
  *
  * The return value will be 0 if the reservation was successfully
  * unreserved and:
  * -EBUSY		The reservation is still backed,
  * -EINVAL		The vcm argument is invalid.
  */
 int vcm_unreserve(struct res *res);


 /**
  * vcm_set_res_attr() - Set attributes of an existing reservation.
  * @res:		An existing reservation of interest.
  * @attr:		See 'Reservation Attributes'.
  *
  * This function can only be used on an existing reservation; there
  * are no orphan reservations. All attributes can be set on a existing
  * reservation.
  *
  * The return value will be 0 for a success, otherwise it will be:
  * -EINVAL		res or attr are invalid.
  */
 int vcm_set_res_attr(struct res *res, u32 attr);


 /**
  * vcm_get_num_res() - Return the number of reservations in a VCM region.
  * @vcm:		The VCM region of interest.
  */
 size_t vcm_get_num_res(struct vcm *vcm);


 /**
  * vcm_get_next_res() - Read each reservation one at a time.
  * @vcm:		The VCM region of interest.
  * @res:		Contains the last reservation. Pass NULL on the
  *			first call.
  *
  * This function works like a foreach reservation in a VCM region.
  *
  * The return value will be non-zero for each reservation in a VCM. A
  * zero indicates no further reservations.
  */
 struct res *vcm_get_next_res(struct vcm *vcm, struct res *res);


 /**
  * vcm_res_copy() - Copy len bytes from one reservation to another.
  * @to:			The reservation to copy to.
  * @from:		The reservation to copy from.
  * @len:		The length of bytes to copy.
  *
  * The return value is the number of bytes copied.
  */
 size_t vcm_res_copy(struct res *to, size_t to_off, struct res *from, size_t
 		    from_off, size_t len);


 /**
  * vcm_get_min_page_size() - Return the minimum page size supported by
  *			     the architecture.
  */
 size_t vcm_get_min_page_size(void);


 /**
  * vcm_back() - Physically back a reservation.
  * @res:		The reservation containing the virtual contiguous
  *			region to back.
  * @physmem:		The physical memory that will back the virtual
  *			contiguous memory region.
  *
  * One VCM can be associated with multiple devices. When you vcm_back()
  * each association must be active. This is not strictly necessary. It may
  * be changed in the future.
  *
  * This function returns 0 on a successful physical backing. Otherwise
  * it returns:
  * -EINVAL		res or physmem is invalid or res's len
  *			is different from physmem's len.
  * -EAGAIN		Try again, one of the devices hasn't been activated.
  */
 int vcm_back(struct res *res, struct physmem *physmem);


 /**
  * vcm_unback() - Unback a reservation.
  * @res:		The reservation to unback.
  *
  * One VCM can be associated with multiple devices. When you vcm_unback()
  * each association must be active.
  *
  * This function returns 0 on a successful unbacking. Otherwise
  * it returns:
  * -EINVAL		res is invalid.
  * -EAGAIN		Try again, one of the devices hasn't been activated.
  */
 int vcm_unback(struct res *res);


 /**
  * vcm_phys_alloc() - Allocate physical memory for the VCM region.
  * @memtype:		The memory type to allocate.
  * @len:		The length of the allocation.
  * @attr:		See 'Physical Allocation Attributes'.
  *
  * This function will allocate chunks of memory according to the attr
  * it is passed.
  *
  * The return value is non-zero if physical memory has been
  * successfully allocated.
  */
 struct physmem *vcm_phys_alloc(enum memtype_t memtype, size_t len, u32 attr);


 /**
  * vcm_phys_free() - Free a physical allocation.
  * @physmem:		The physical allocation to free.
  *
  * The return value is 0 if the physical allocation has been freed or:
  * -EBUSY		Their are reservation mapping the physical memory.
  * -EINVAL		The physmem argument is invalid.
  */
 int vcm_phys_free(struct physmem *physmem);


 /**
  * vcm_get_physmem_from_res() - Return a reservation's physmem
  * @res:		An existing reservation of interest.
  *
  * The return value will be non-zero on success, otherwise it will be:
  * -EINVAL		res is invalid
  * -ENOMEM		res is unbacked
  */
 struct physmem *vcm_get_physmem_from_res(struct res *res);


 /**
  * vcm_get_memtype_of_physalloc() - Return the memtype of a reservation.
  * @physmem:		The physical allocation of interest.
  *
  * This function returns the memtype of a reservation or VCM_INVALID
  * if res is invalid.
  */
 enum memtype_t vcm_get_memtype_of_physalloc(struct physmem *physmem);


 /*
  * Associate a VCM with a device, activate that association and remove it.
  *
  */

 /**
  * vcm_assoc() - Associate a VCM with a device.
  * @vcm:		The VCM region of interest.
  * @dev:		The device to associate the VCM with.
  * @attr:		See 'Association Attributes'.
  *
  * This function returns non-zero if a association is made. It returns 0
  * if any of its parameters are invalid or VCM_ATTR_VALID is not present.
  */
 struct avcm *vcm_assoc(struct vcm *vcm, struct device *dev, u32 attr);


 /**
  * vcm_deassoc() - Deassociate a VCM from a device.
  * @avcm:		The association we want to break.
  *
  * The function returns 0 on success or:
  * -EBUSY		The association is currently activated.
  * -EINVAL		The avcm parameter is invalid.
  */
 int vcm_deassoc(struct avcm *avcm);


 /**
  * vcm_set_assoc_attr() - Set an AVCM's attributes.
  * @avcm:		The AVCM of interest.
  * @attr:		The new attr. See 'Association Attributes'.
  *
  * Every attribute can be set at runtime if an association isn't activated.
  *
  * This function returns 0 on success or:
  * -EBUSY		The association is currently activated.
  * -EINVAL		The avcm parameter is invalid.
  */
 int vcm_set_assoc_attr(struct avcm *avcm, u32 attr);


 /**
  * vcm_get_assoc_attr() - Return an AVCM's attributes.
  * @avcm:		The AVCM of interest.
  *
  * This function returns 0 on error.
  */
 u32 vcm_get_assoc_attr(struct avcm *avcm);


 /**
  * vcm_activate() - Activate an AVCM.
  * @avcm:		The AVCM to activate.
  *
  * You have to deactivate, before you activate.
  *
  * This function returns 0 on success or:
  * -EINVAL		avcm is invalid
  * -ENODEV		no device
  * -EBUSY		device is already active
  * -1			hardware failure
  */
 int vcm_activate(struct avcm *avcm);


 /**
  * vcm_deactivate() - Deactivate an association.
  * @avcm:		The AVCM to deactivate.
  *
  * This function returns 0 on success or:
  * -ENOENT		avcm is not activate
  * -EINVAL		avcm is invalid
  * -1			hardware failure
  */
 int vcm_deactivate(struct avcm *avcm);


 /**
  * vcm_is_active() - Query if an AVCM is active.
  * @avcm:		The AVCM of interest.
  *
  * returns 0 for not active, 1 for active or -EINVAL for error.
  *
  */
 int vcm_is_active(struct avcm *avcm);


 /*
  * Create, manage and remove a boundary in a VCM.
  */

 /**
  * vcm_create_bound() - Create a bound in a VCM.
  * @vcm:		The VCM that needs a bound.
  * @len:		The len of the bound.
  *
  * The allocator picks the virtual addresses of the bound.
  *
  * This function returns non-zero if a bound was created.
  */
 struct bound *vcm_create_bound(struct vcm *vcm, size_t len);


 /**
  * vcm_free_bound() - Free a bound.
  * @bound:		The bound to remove.
  *
  * This function returns 0 if bound has been removed or:
  * -EBUSY		The bound contains reservations and cannot be removed.
  * -EINVAL		The bound is invalid.
  */
 int vcm_free_bound(struct bound *bound);


 /**
  * vcm_reserve_from_bound() - Make a reservation from a bounded area.
  * @bound:		The bound to reserve from.
  * @len:		The len of the reservation.
  * @attr:		See 'Reservation Attributes'.
  *
  * The return value is non-zero on success. It is 0 if any parameter
  * is invalid.
  */
 struct res *vcm_reserve_from_bound(struct bound *bound, size_t len,
 				   u32 attr);


 /**
  * vcm_get_bound_start_addr() - Return the starting device address of the bound
  * @bound:		The bound of interest.
  *
  * On success this function returns the starting addres of the bound. On error
  * it returns:
  * 1			bound_id is invalid.
  */
 size_t vcm_get_bound_start_addr(struct bound *bound);


 /*
  * Perform low-level control over VCM regions and reservations.
  */

 /**
  * vcm_map_phys_addr() - Produce a physmem from a contiguous
  *                       physical address
  *
  * @phys:		The physical address of the contiguous range.
  * @len:		The len of the contiguous address range.
  *
  * Returns non-zero on success, 0 on failure.
  */
 struct physmem *vcm_map_phys_addr(phys_addr_t phys, size_t len);


 /**
  * vcm_get_next_phys_addr() - Get the next physical addr and len of a physmem.
  * @physmem:		The physmem of interest.
  * @phys:		The current physical address. Set this to NULL to
  *			start the iteration.
  * @len			An output: the len of the next physical segment.
  *
  * physmems may contain physically discontiguous sections. This
  * function returns the next physical address and len. Pass NULL to
  * phys to get the first physical address. The len of the physical
  * segment is returned in *len.
  *
  * Returns 0 if there is no next physical address.
  */
 size_t vcm_get_next_phys_addr(struct physmem *physmem, phys_addr_t phys,
 			      size_t *len);


 /**
  * vcm_get_dev_addr() - Return the device address of a reservation.
  * @res:		The reservation of interest.
  *
  *
  * On success this function returns the device address of a reservation. On
  * error it returns:
  * 1			res is invalid.
  *
  * Note: This may return a kernel address if the reservation was
  * created from vcm_create_from_prebuilt() and the prebuilt ext_vcm_id
  * references a VM page table.
  */
 phys_addr_t vcm_get_dev_addr(struct res *res);


 /**
  * vcm_get_res() - Return the reservation from a device address and a VCM
  * @dev_addr:		The device address of interest.
  * @vcm:		The VCM that contains the reservation
  *
  * This function returns 0 if there is no reservation whose device
  * address is dev_addr.
  */
 struct res *vcm_get_res(unsigned long dev_addr, struct vcm *vcm);


 /**
  * vcm_translate() - Translate from one device address to another.
  * @src_dev:		The source device address.
  * @src_vcm:		The source VCM region.
  * @dst_vcm:		The destination VCM region.
  *
  * Derive the device address from a VCM region that maps the same physical
  * memory as a device address from another VCM region.
  *
  * On success this function returns the device address of a translation. On
  * error it returns:
  * 1			res_id is invalid.
  */
 size_t vcm_translate(struct device *src_dev, struct vcm *src_vcm,
 		     struct vcm *dst_vcm);


 /**
  * vcm_get_phys_num_res() - Return the number of reservations mapping a
  *			    physical address.
  * @phys:		The physical address to read.
  */
 size_t vcm_get_phys_num_res(phys_addr_t phys);


 /**
  * vcm_get_next_phys_res() - Return the next reservation mapped to a physical
  *			     address.
  * @phys:		The physical address to map.
  * @res:		The starting reservation. Set this to NULL for the first
  *			reservation.
  * @len:		The virtual length of the reservation
  *
  * This function returns 0 for the last reservation or no reservation.
  */
 struct res *vcm_get_next_phys_res(phys_addr_t phys, struct res *res,
 				  size_t *len);


 /**
  * vcm_get_pgtbl_pa() - Return the physcial address of a VCM's page table.
  * @vcm:	The VCM region of interest.
  *
  * This function returns non-zero on success.
  */
 phys_addr_t vcm_get_pgtbl_pa(struct vcm *vcm);


 /**
  * vcm_get_cont_memtype_pa() - Return the phys base addr of a memtype's
  *			       first contiguous region.
  * @memtype:		The memtype of interest.
  *
  * This function returns non-zero on success. A zero return indicates that
  * the given memtype does not have a contiguous region or that the memtype
  * is invalid.
  */
 phys_addr_t vcm_get_cont_memtype_pa(enum memtype_t memtype);


 /**
  * vcm_get_cont_memtype_len() - Return the len of a memtype's
  *				first contiguous region.
  * @memtype:		The memtype of interest.
  *
  * This function returns non-zero on success. A zero return indicates that
  * the given memtype does not have a contiguous region or that the memtype
  * is invalid.
  */
 size_t vcm_get_cont_memtype_len(enum memtype_t memtype);


 /**
  * vcm_dev_addr_to_phys_addr() - Perform a device address page-table lookup.
  * @vcm:		VCM to use for translation.
  * @dev_addr:		The device address to map.
  *
  * This function returns the pa of a va from a device's page-table. It will
  * fault if the dev_addr is not mapped.
  */
 phys_addr_t vcm_dev_addr_to_phys_addr(struct vcm *vcm, unsigned long dev_addr);


 /*
  * Fault Hooks
  *
  * vcm_hook()
  */

 /**
  * vcm_hook() - Add a fault handler.
  * @dev:		The device.
  * @handler:		The handler.
  * @data:		A private piece of data that will get passed to the
  *			handler.
  *
  * This function returns 0 for a successful registration or:
  * -EINVAL		The arguments are invalid.
  */
 int vcm_hook(struct device *dev, vcm_handler handler, void *data);


 /*
  * Low level, platform agnostic, HW control.
  *
  * vcm_hw_ver()
  */

 /**
  * vcm_hw_ver() - Return the hardware version of a device, if it has one.
  * @dev		The device.
  */
 size_t vcm_hw_ver(size_t dev);

 #endif /* _VCM_H_ */
	/* Copyright (c) 2010, Code Aurora Forum. All rights reserved.
	*
	* This program is free software; you can redistribute it and/or modify
	* it under the terms of the GNU General Public License version 2 and
	* only version 2 as published by the Free Software Foundation.
	*
	* This program is distributed in the hope that it will be useful,
	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
	* GNU General Public License for more details.
	*
	*/

	#ifndef _VCM_H_
	#define _VCM_H_

	/* All undefined types must be defined using platform specific headers */

	#include <linux/vcm_types.h>

	/*
	* Virtual contiguous memory (VCM) region primitives.
	*
	* Current memory mapping software uses a CPU centric management
	* model. This makes sense in general, average hardware only contains an
	* CPU MMU and possibly a graphics MMU. If every device in the system
	* has one or more MMUs a CPU centric MM programming model breaks down.
	*
	* Looking at mapping from a system-wide perspective reveals a general
	* graph problem. Each node that talks to memory, either through an MMU
	* or directly (via physical memory) can be thought of as the device end
	* of a mapping edge. The other edge is the physical memory that is
	* mapped.
	*
	* In the direct mapped case, it is useful to give the device an
	* MMU. This one-to-one MMU allows direct mapped devices to
	* participate in graph management, they simply see memory through a
	* one-to-one mapping.
	*
	* The CPU nodes can also be brought under the same mapping
	* abstraction with the use of a light overlay on the existing
	* VMM. This light overlay brings the VMM's page table abstraction for
	* each process and the kernel into the graph management API.
	*
	* Taken together this system wide approach provides a capability that
	* is greater than the sum of its parts by allowing users to reason
	* about system wide mapping issues without getting bogged down in CPU
	* centric device page table management issues.
	*/


	/*
	* Creating, freeing and managing VCMs.
	*
	* A VCM region is a virtual space that can be reserved from and
	* associated with one or more devices. At creation the user can
	* specify an offset to start addresses and a length of the entire VCM
	* region. Reservations out of a VCM region are always contiguous.
	*/

	/**
	* vcm_create() - Create a VCM region
	* @start_addr: The starting address of the VCM region.
	* @len: The len of the VCM region. This must be at least
	* vcm_get_min_page_size() bytes.
	*
	* A VCM typically abstracts a page table.
	*
	* All functions in this API are passed and return opaque things
	* because the underlying implementations will vary. The goal
	* is really graph management. vcm_create() creates the "device end"
	* of an edge in the mapping graph.
	*
	* The return value is non-zero if a VCM has successfully been
	* created. It will return zero if a VCM region cannot be created or
	* len is invalid.
	*/
	struct vcm *vcm_create(unsigned long start_addr, size_t len);


	/**
	* vcm_create_from_prebuilt() - Create a VCM region from an existing region
	* @ext_vcm_id: An external opaque value that allows the
	* implementation to reference an already built table.
	*
	* The ext_vcm_id will probably reference a page table that's been built
	* by the VM.
	*
	* The platform specific implementation will provide this.
	*
	* The return value is non-zero if a VCM has successfully been created.
	*/
	struct vcm *vcm_create_from_prebuilt(size_t ext_vcm_id);


	/**
	* vcm_clone() - Clone a VCM
	* @vcm: A VCM to clone from.
	*
	* Perform a VCM "deep copy." The resulting VCM will match the original at
	* the point of cloning. Subsequent updates to either VCM will only be
	* seen by that VCM.
	*
	* The return value is non-zero if a VCM has been successfully cloned.
	*/
	struct vcm vcm_clone(struct vcm vcm);


	/**
	* vcm_get_start_addr() - Get the starting address of the VCM region.
	* @vcm: The VCM we're interested in getting the starting
	* address of.
	*
	* The return value will be 1 if an error has occurred.
	*/
	size_t vcm_get_start_addr(struct vcm *vcm);


	/**
	* vcm_get_len() - Get the length of the VCM region.
	* @vcm: The VCM we're interested in reading the length from.
	*
	* The return value will be non-zero for a valid VCM. VCM regions
	* cannot have 0 len.
	*/
	size_t vcm_get_len(struct vcm *vcm);


	/**
	* vcm_free() - Free a VCM.
	* @vcm: The VCM we're interested in freeing.
	*
	* The return value is 0 if the VCM has been freed or:
	* -EBUSY The VCM region contains reservations or has been
	* associated (active or not) and cannot be freed.
	* -EINVAL The vcm argument is invalid.
	*/
	int vcm_free(struct vcm *vcm);


	/*
	* Creating, freeing and managing reservations out of a VCM.
	*
	*/

	/**
	* vcm_reserve() - Create a reservation from a VCM region.
	* @vcm: The VCM region to reserve from.
	* @len: The length of the reservation. Must be at least
	* vcm_get_min_page_size() bytes.
	* @attr: See 'Reservation Attributes'.
	*
	* A reservation, res_t, is a contiguous range from a VCM region.
	*
	* The return value is non-zero if a reservation has been successfully
	* created. It is 0 if any of the parameters are invalid.
	*/
	struct res vcm_reserve(struct vcm vcm, size_t len, u32 attr);


	/**
	* vcm_reserve_at() - Make a reservation at a given logical location.
	* @memtarget: A logical location to start the reservation from.
	* @vcm: The VCM region to start the reservation from.
	* @len: The length of the reservation.
	* @attr: See 'Reservation Attributes'.
	*
	* The return value is non-zero if a reservation has been successfully
	* created.
	*/
	struct res vcm_reserve_at(enum memtarget_t memtarget, struct vcm vcm,
	size_t len, u32 attr);


	/**
	* vcm_get_vcm_from_res() - Return the VCM region of a reservation.
	* @res: The reservation to return the VCM region of.
	*
	* Te return value will be non-zero if the reservation is valid. A valid
	* reservation is always associated with a VCM region; there is no such
	* thing as an orphan reservation.
	*/
	struct vcm vcm_get_vcm_from_res(struct res res);


	/**
	* vcm_unreserve() - Unreserve the reservation.
	* @res: The reservation to unreserve.
	*
	* The return value will be 0 if the reservation was successfully
	* unreserved and:
	* -EBUSY The reservation is still backed,
	* -EINVAL The vcm argument is invalid.
	*/
	int vcm_unreserve(struct res *res);


	/**
	* vcm_set_res_attr() - Set attributes of an existing reservation.
	* @res: An existing reservation of interest.
	* @attr: See 'Reservation Attributes'.
	*
	* This function can only be used on an existing reservation; there
	* are no orphan reservations. All attributes can be set on a existing
	* reservation.
	*
	* The return value will be 0 for a success, otherwise it will be:
	* -EINVAL res or attr are invalid.
	*/
	int vcm_set_res_attr(struct res *res, u32 attr);


	/**
	* vcm_get_num_res() - Return the number of reservations in a VCM region.
	* @vcm: The VCM region of interest.
	*/
	size_t vcm_get_num_res(struct vcm *vcm);


	/**
	* vcm_get_next_res() - Read each reservation one at a time.
	* @vcm: The VCM region of interest.
	* @res: Contains the last reservation. Pass NULL on the
	* first call.
	*
	* This function works like a foreach reservation in a VCM region.
	*
	* The return value will be non-zero for each reservation in a VCM. A
	* zero indicates no further reservations.
	*/
	struct res vcm_get_next_res(struct vcm vcm, struct res *res);


	/**
	* vcm_res_copy() - Copy len bytes from one reservation to another.
	* @to: The reservation to copy to.
	* @from: The reservation to copy from.
	* @len: The length of bytes to copy.
	*
	* The return value is the number of bytes copied.
	*/
	size_t vcm_res_copy(struct res to, size_t to_off, struct res from, size_t
	from_off, size_t len);


	/**
	* vcm_get_min_page_size() - Return the minimum page size supported by
	* the architecture.
	*/
	size_t vcm_get_min_page_size(void);


	/**
	* vcm_back() - Physically back a reservation.
	* @res: The reservation containing the virtual contiguous
	* region to back.
	* @physmem: The physical memory that will back the virtual
	* contiguous memory region.
	*
	* One VCM can be associated with multiple devices. When you vcm_back()
	* each association must be active. This is not strictly necessary. It may
	* be changed in the future.
	*
	* This function returns 0 on a successful physical backing. Otherwise
	* it returns:
	* -EINVAL res or physmem is invalid or res's len
	* is different from physmem's len.
	* -EAGAIN Try again, one of the devices hasn't been activated.
	*/
	int vcm_back(struct res res, struct physmem physmem);


	/**
	* vcm_unback() - Unback a reservation.
	* @res: The reservation to unback.
	*
	* One VCM can be associated with multiple devices. When you vcm_unback()
	* each association must be active.
	*
	* This function returns 0 on a successful unbacking. Otherwise
	* it returns:
	* -EINVAL res is invalid.
	* -EAGAIN Try again, one of the devices hasn't been activated.
	*/
	int vcm_unback(struct res *res);


	/**
	* vcm_phys_alloc() - Allocate physical memory for the VCM region.
	* @memtype: The memory type to allocate.
	* @len: The length of the allocation.
	* @attr: See 'Physical Allocation Attributes'.
	*
	* This function will allocate chunks of memory according to the attr
	* it is passed.
	*
	* The return value is non-zero if physical memory has been
	* successfully allocated.
	*/
	struct physmem *vcm_phys_alloc(enum memtype_t memtype, size_t len, u32 attr);


	/**
	* vcm_phys_free() - Free a physical allocation.
	* @physmem: The physical allocation to free.
	*
	* The return value is 0 if the physical allocation has been freed or:
	* -EBUSY Their are reservation mapping the physical memory.
	* -EINVAL The physmem argument is invalid.
	*/
	int vcm_phys_free(struct physmem *physmem);


	/**
	* vcm_get_physmem_from_res() - Return a reservation's physmem
	* @res: An existing reservation of interest.
	*
	* The return value will be non-zero on success, otherwise it will be:
	* -EINVAL res is invalid
	* -ENOMEM res is unbacked
	*/
	struct physmem vcm_get_physmem_from_res(struct res res);


	/**
	* vcm_get_memtype_of_physalloc() - Return the memtype of a reservation.
	* @physmem: The physical allocation of interest.
	*
	* This function returns the memtype of a reservation or VCM_INVALID
	* if res is invalid.
	*/
	enum memtype_t vcm_get_memtype_of_physalloc(struct physmem *physmem);


	/*
	* Associate a VCM with a device, activate that association and remove it.
	*
	*/

	/**
	* vcm_assoc() - Associate a VCM with a device.
	* @vcm: The VCM region of interest.
	* @dev: The device to associate the VCM with.
	* @attr: See 'Association Attributes'.
	*
	* This function returns non-zero if a association is made. It returns 0
	* if any of its parameters are invalid or VCM_ATTR_VALID is not present.
	*/
	struct avcm vcm_assoc(struct vcm vcm, struct device *dev, u32 attr);


	/**
	* vcm_deassoc() - Deassociate a VCM from a device.
	* @avcm: The association we want to break.
	*
	* The function returns 0 on success or:
	* -EBUSY The association is currently activated.
	* -EINVAL The avcm parameter is invalid.
	*/
	int vcm_deassoc(struct avcm *avcm);


	/**
	* vcm_set_assoc_attr() - Set an AVCM's attributes.
	* @avcm: The AVCM of interest.
	* @attr: The new attr. See 'Association Attributes'.
	*
	* Every attribute can be set at runtime if an association isn't activated.
	*
	* This function returns 0 on success or:
	* -EBUSY The association is currently activated.
	* -EINVAL The avcm parameter is invalid.
	*/
	int vcm_set_assoc_attr(struct avcm *avcm, u32 attr);


	/**
	* vcm_get_assoc_attr() - Return an AVCM's attributes.
	* @avcm: The AVCM of interest.
	*
	* This function returns 0 on error.
	*/
	u32 vcm_get_assoc_attr(struct avcm *avcm);


	/**
	* vcm_activate() - Activate an AVCM.
	* @avcm: The AVCM to activate.
	*
	* You have to deactivate, before you activate.
	*
	* This function returns 0 on success or:
	* -EINVAL avcm is invalid
	* -ENODEV no device
	* -EBUSY device is already active
	* -1 hardware failure
	*/
	int vcm_activate(struct avcm *avcm);


	/**
	* vcm_deactivate() - Deactivate an association.
	* @avcm: The AVCM to deactivate.
	*
	* This function returns 0 on success or:
	* -ENOENT avcm is not activate
	* -EINVAL avcm is invalid
	* -1 hardware failure
	*/
	int vcm_deactivate(struct avcm *avcm);


	/**
	* vcm_is_active() - Query if an AVCM is active.
	* @avcm: The AVCM of interest.
	*
	* returns 0 for not active, 1 for active or -EINVAL for error.
	*
	*/
	int vcm_is_active(struct avcm *avcm);


	/*
	* Create, manage and remove a boundary in a VCM.
	*/

	/**
	* vcm_create_bound() - Create a bound in a VCM.
	* @vcm: The VCM that needs a bound.
	* @len: The len of the bound.
	*
	* The allocator picks the virtual addresses of the bound.
	*
	* This function returns non-zero if a bound was created.
	*/
	struct bound vcm_create_bound(struct vcm vcm, size_t len);


	/**
	* vcm_free_bound() - Free a bound.
	* @bound: The bound to remove.
	*
	* This function returns 0 if bound has been removed or:
	* -EBUSY The bound contains reservations and cannot be removed.
	* -EINVAL The bound is invalid.
	*/
	int vcm_free_bound(struct bound *bound);


	/**
	* vcm_reserve_from_bound() - Make a reservation from a bounded area.
	* @bound: The bound to reserve from.
	* @len: The len of the reservation.
	* @attr: See 'Reservation Attributes'.
	*
	* The return value is non-zero on success. It is 0 if any parameter
	* is invalid.
	*/
	struct res vcm_reserve_from_bound(struct bound bound, size_t len,
	u32 attr);


	/**
	* vcm_get_bound_start_addr() - Return the starting device address of the bound
	* @bound: The bound of interest.
	*
	* On success this function returns the starting addres of the bound. On error
	* it returns:
	* 1 bound_id is invalid.
	*/
	size_t vcm_get_bound_start_addr(struct bound *bound);



	/*
	* Perform low-level control over VCM regions and reservations.
	*/

	/**
	* vcm_map_phys_addr() - Produce a physmem from a contiguous
	* physical address
	*
	* @phys: The physical address of the contiguous range.
	* @len: The len of the contiguous address range.
	*
	* Returns non-zero on success, 0 on failure.
	*/
	struct physmem *vcm_map_phys_addr(phys_addr_t phys, size_t len);


	/**
	* vcm_get_next_phys_addr() - Get the next physical addr and len of a physmem.
	* @physmem: The physmem of interest.
	* @phys: The current physical address. Set this to NULL to
	* start the iteration.
	* @len An output: the len of the next physical segment.
	*
	* physmems may contain physically discontiguous sections. This
	* function returns the next physical address and len. Pass NULL to
	* phys to get the first physical address. The len of the physical
	* segment is returned in *len.
	*
	* Returns 0 if there is no next physical address.
	*/
	size_t vcm_get_next_phys_addr(struct physmem *physmem, phys_addr_t phys,
	size_t *len);


	/**
	* vcm_get_dev_addr() - Return the device address of a reservation.
	* @res: The reservation of interest.
	*
	*
	* On success this function returns the device address of a reservation. On
	* error it returns:
	* 1 res is invalid.
	*
	* Note: This may return a kernel address if the reservation was
	* created from vcm_create_from_prebuilt() and the prebuilt ext_vcm_id
	* references a VM page table.
	*/
	phys_addr_t vcm_get_dev_addr(struct res *res);


	/**
	* vcm_get_res() - Return the reservation from a device address and a VCM
	* @dev_addr: The device address of interest.
	* @vcm: The VCM that contains the reservation
	*
	* This function returns 0 if there is no reservation whose device
	* address is dev_addr.
	*/
	struct res vcm_get_res(unsigned long dev_addr, struct vcm vcm);


	/**
	* vcm_translate() - Translate from one device address to another.
	* @src_dev: The source device address.
	* @src_vcm: The source VCM region.
	* @dst_vcm: The destination VCM region.
	*
	* Derive the device address from a VCM region that maps the same physical
	* memory as a device address from another VCM region.
	*
	* On success this function returns the device address of a translation. On
	* error it returns:
	* 1 res_id is invalid.
	*/
	size_t vcm_translate(struct device src_dev, struct vcm src_vcm,
	struct vcm *dst_vcm);


	/**
	* vcm_get_phys_num_res() - Return the number of reservations mapping a
	* physical address.
	* @phys: The physical address to read.
	*/
	size_t vcm_get_phys_num_res(phys_addr_t phys);


	/**
	* vcm_get_next_phys_res() - Return the next reservation mapped to a physical
	* address.
	* @phys: The physical address to map.
	* @res: The starting reservation. Set this to NULL for the first
	* reservation.
	* @len: The virtual length of the reservation
	*
	* This function returns 0 for the last reservation or no reservation.
	*/
	struct res vcm_get_next_phys_res(phys_addr_t phys, struct res res,
	size_t *len);


	/**
	* vcm_get_pgtbl_pa() - Return the physcial address of a VCM's page table.
	* @vcm: The VCM region of interest.
	*
	* This function returns non-zero on success.
	*/
	phys_addr_t vcm_get_pgtbl_pa(struct vcm *vcm);


	/**
	* vcm_get_cont_memtype_pa() - Return the phys base addr of a memtype's
	* first contiguous region.
	* @memtype: The memtype of interest.
	*
	* This function returns non-zero on success. A zero return indicates that
	* the given memtype does not have a contiguous region or that the memtype
	* is invalid.
	*/
	phys_addr_t vcm_get_cont_memtype_pa(enum memtype_t memtype);


	/**
	* vcm_get_cont_memtype_len() - Return the len of a memtype's
	* first contiguous region.
	* @memtype: The memtype of interest.
	*
	* This function returns non-zero on success. A zero return indicates that
	* the given memtype does not have a contiguous region or that the memtype
	* is invalid.
	*/
	size_t vcm_get_cont_memtype_len(enum memtype_t memtype);


	/**
	* vcm_dev_addr_to_phys_addr() - Perform a device address page-table lookup.
	* @vcm: VCM to use for translation.
	* @dev_addr: The device address to map.
	*
	* This function returns the pa of a va from a device's page-table. It will
	* fault if the dev_addr is not mapped.
	*/
	phys_addr_t vcm_dev_addr_to_phys_addr(struct vcm *vcm, unsigned long dev_addr);


	/*
	* Fault Hooks
	*
	* vcm_hook()
	*/

	/**
	* vcm_hook() - Add a fault handler.
	* @dev: The device.
	* @handler: The handler.
	* @data: A private piece of data that will get passed to the
	* handler.
	*
	* This function returns 0 for a successful registration or:
	* -EINVAL The arguments are invalid.
	*/
	int vcm_hook(struct device dev, vcm_handler handler, void data);



	/*
	* Low level, platform agnostic, HW control.
	*
	* vcm_hw_ver()
	*/

	/**
	* vcm_hw_ver() - Return the hardware version of a device, if it has one.
	* @dev The device.
	*/
	size_t vcm_hw_ver(size_t dev);

	#endif /* _VCM_H_ */