/* Copyright (c) 2010, The Linux Foundation. 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 /* * 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_ */