Data Structures | Defines | Typedefs | Enumerations | Functions
mmap_resource.h File Reference

Private header file for the KEYSTONE_MMAP component which relevent to the allocation of resources such as logical addresses and MPAX registers. More...

#include <stdint.h>

Data Structures

struct  keystone_mmap_mapping_t
 This structure provides the mapping information. More...
struct  keystone_mmap_heap_element_s
 This strucutre is the basic element of the address space heap. More...
struct  keystone_mmap_resources_s
 This strucutre maintains the keystone_mmap resources for a specific context. More...

Defines

#define KEYSTONE_MMAP_MAX_NUM_MAPS   8
 Maximum number of individual mappings supported by the MPAX component. This number was chosen because of the HW limit of K2H.
#define KEYSTONE_MMAP_MAX_NUM_HEAP_ELEMS   80
 Maximum number of heap elements.

Typedefs

typedef struct
keystone_mmap_heap_element_s 
keystone_mmap_heap_element_t
 This strucutre is the basic element of the address space heap.
typedef struct
keystone_mmap_resources_s 
keystone_mmap_resources_t
 This strucutre maintains the keystone_mmap resources for a specific context.

Enumerations

enum  
 Error codes returned by the mmap_resource APIs.
enum  { KEYSTONE_MMAP_CACHED, KEYSTONE_MMAP_NONCACHED }
 Cache options for mapped memory. More...

Functions

int32_t keystone_mmap_resource_init (uint32_t num_regs, uint32_t *xmc_regs, uint32_t *ses_regs, uint32_t num_heaps, uint32_t *heap_base, uint32_t *heap_size, keystone_mmap_resources_t *resources)
int32_t keystone_mmap_resource_alloc (uint32_t num_bufs, uint64_t *phys_addrs, uint32_t *lengths, uint32_t *protections, uint32_t *virt_addrs, keystone_mmap_resources_t *resources)
int32_t keystone_mmap_resource_free (uint32_t num_bufs, uint32_t *virt_addrs, uint32_t *lengths, keystone_mmap_resources_t *resources)

Detailed Description

Private header file for the KEYSTONE_MMAP component which relevent to the allocation of resources such as logical addresses and MPAX registers.

NOTE: (C) Copyright 2013 Texas Instruments, Inc.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of Texas Instruments Incorporated nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


Define Documentation

Maximum number of heap elements.

Because the HW only supports power of 2 sizes and alignments for mapping, the addressi space heap is organized into a binary tree. This allows for efficient defragmentation when mappings are freed.

This number was chosen with respect to the maximum number of mappings allowed by the HW. The maximum theoretical size of the available address space is 2^32 bytes, and the minimum size that can be mapped is 2^12 bytes. This would allow a maximum of 2^20 mappings, and require 2^21 heap elements. However, the HW supports a maximum of 8 mappings.


Typedef Documentation

This strucutre is the basic element of the address space heap.

These elements are used to construct a binary tree representing the fragmentation of the address space into power of 2 sizes. They are statically allocated in the keystone_mmap_resources_t structure in the heap elemnt bank.

This strucutre maintains the keystone_mmap resources for a specific context.

This strucutre maintains the mapping table and the address space heaps.


Enumeration Type Documentation

anonymous enum

Cache options for mapped memory.

Enumerator:
KEYSTONE_MMAP_CACHED 

Map as cached memory.

KEYSTONE_MMAP_NONCACHED 

Map as noncached memory.


Function Documentation

int32_t keystone_mmap_resource_alloc ( uint32_t  num_bufs,
uint64_t *  phys_addrs,
uint32_t *  lengths,
uint32_t *  protections,
uint32_t *  virt_addrs,
keystone_mmap_resources_t resources 
)

Description


This functions takes physical buffers and lengths and allocates the resources required to map all of the buffer. If the allocation is successful, the array of addressable virtual address is populated along with the physical mapping configuration.

Parameters:
[in]num_bufsNumber of buffers for which to allocate mapping resources.
[in]phys_addrsArray of physical addresses of the base of each buffer.
[in]lengthsArray of lengths for each buffer.
[in]protectionsArray containing the read/write/execute permissions along with cacheability.
[out]virt_addrsAn array which, upon succesful resource allocation, will be populated with the virtual addresses corresponding to the physical buffers.
[in,out]resourcesResource structure which manages the mapping resources. This structure contains a keystone_mmap_mapping_t structure which is the table of mapping information which should be passed to keystone_mmap_map() to perform the actual mapping.
Return values:
KEYSTONE_MMAP_RESOURCE_NOERRon success. Other values correspond to an error condition. (
See also:
)

Description


This functions takes physical buffers and lengths and allocates the resources required to map all of the buffer. If the allocation is successful, the array of addressable virtual address is populated along with the physical mapping configuration.

Parameters:
[in]num_bufsNumber of buffers for which to allocate mapping resources.
[in]phys_addrsArray of physical addresses of the base of each buffer.
[in]lengthsArray of lengths for each buffer.
[in]protectionsArray containing the read/write/execute permissions along with cacheability.
[out]virt_addrsAn array which, upon succesful resource allocation, will be populated with the virtual addresses corresponding to the physical buffers.
[in,out]resourcesResource structure which manages the mapping resources. This structure contains a keystone_mmap_mapping_t structure which is the table of mapping information which should be passed to keystone_mmap_do_map() to perform the actual mapping.
Return values:
KEYSTONE_MMAP_RESOURCE_NOERRon success. Other values correspond to an error condition. (
See also:
)
int32_t keystone_mmap_resource_free ( uint32_t  num_bufs,
uint32_t *  virt_addrs,
uint32_t *  lengths,
keystone_mmap_resources_t resources 
)

Description


This function frees resources associated to mapped physical buffers, The virtual addresses and lengths are supplied to this function and the corresponding mapping entries are removed.

Parameters:
[in]num_bufsnumber of buffers which are to be unmapped.
[in]virt_addrsArray of virtual address of the buffers which are to be unmapped.
[in]lengthsArray of lengths of the buffers which are to be unmapped.
[in,out]resourcesResource structure managing the resources used for mapping.
Return values:
KEYSTONE_MMAP_RESOURCE_NOERRon success. Other values correspond to an error condition. (
See also:
)

A single buffer may require 2 mappings to save address space resource.

Check if beginning or end of mapped region is within the actual mapping.

int32_t keystone_mmap_resource_init ( uint32_t  num_regs,
uint32_t *  xmc_regs,
uint32_t *  ses_regs,
uint32_t  num_heaps,
uint32_t *  heap_base,
uint32_t *  heap_size,
keystone_mmap_resources_t resources 
)

Description


This function initializes the data structures which manage the resources used for mapping. These resources are the address space heaps and MPAX registers used for mapping.

Parameters:
[in]num_regsNumber of XMC and SES register pairs available for mapping.
[in]xmc_regsArray of XMC register indexes which are available for mapping. XMC registers allow the DSP core to access the mapped memory.
[in]ses_regsArray of SES register indexes which are available for mapping. SES registers allows EDMA to access the mapped memory.
[in]num_heapsNumber of contiguous address space ranges which are available for mapping.
[in]heap_baseArray of base addresses of each contiguous address space range.
[in]heap_sizeArray of sizes of each contiguous address space range.
[out]resourcesKEYSTONE_MMAP resource strucutre which manages the resources used for mapping.
Return values:
KEYSTONE_MMAP_RESOURCE_NOERRon success. Other values correspond to an error condition. (
See also:
)

Copyright 2014, Texas Instruments Incorporated