1 /*
2  * Copyright 2008-2012 Freescale Semiconductor Inc.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *     * Redistributions of source code must retain the above copyright
7  *       notice, this list of conditions and the following disclaimer.
8  *     * Redistributions in binary form must reproduce the above copyright
9  *       notice, this list of conditions and the following disclaimer in the
10  *       documentation and/or other materials provided with the distribution.
11  *     * Neither the name of Freescale Semiconductor nor the
12  *       names of its contributors may be used to endorse or promote products
13  *       derived from this software without specific prior written permission.
14  *
15  *
16  * ALTERNATIVELY, this software may be distributed under the terms of the
17  * GNU General Public License ("GPL") as published by the Free Software
18  * Foundation, either version 2 of that License or (at your option) any
19  * later version.
20  *
21  * THIS SOFTWARE IS PROVIDED BY Freescale Semiconductor ``AS IS'' AND ANY
22  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
24  * DISCLAIMED. IN NO EVENT SHALL Freescale Semiconductor BE LIABLE FOR ANY
25  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
26  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
27  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
28  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
33 
34 /**************************************************************************//**
35  @File          fm_muram_ext.h
36 
37  @Description   FM MURAM Application Programming Interface.
38 *//***************************************************************************/
39 #ifndef __FM_MURAM_EXT
40 #define __FM_MURAM_EXT
41 
42 #include "error_ext.h"
43 #include "std_ext.h"
44 
45 
46 /**************************************************************************//**
47 
48  @Group         FM_grp Frame Manager API
49 
50  @Description   FM API functions, definitions and enums
51 
52  @{
53 *//***************************************************************************/
54 
55 /**************************************************************************//**
56  @Group         FM_muram_grp FM MURAM
57 
58  @Description   FM MURAM API functions, definitions and enums
59 
60  @{
61 *//***************************************************************************/
62 
63 /**************************************************************************//**
64  @Group         FM_muram_init_grp FM MURAM Initialization Unit
65 
66  @Description   FM MURAM initialization API functions, definitions and enums
67 
68  @{
69 *//***************************************************************************/
70 
71 /**************************************************************************//**
72  @Function      FM_MURAM_ConfigAndInit
73 
74  @Description   Creates partition in the MURAM.
75 
76                 The routine returns a handle (descriptor) to the MURAM partition.
77                 This descriptor must be passed as first parameter to all other
78                 FM-MURAM function calls.
79 
80                 No actual initialization or configuration of FM_MURAM hardware is
81                 done by this routine.
82 
83  @Param[in]     baseAddress - Pointer to base of memory mapped FM-MURAM.
84  @Param[in]     size        - Size of the FM-MURAM partition.
85 
86  @Return        Handle to FM-MURAM object, or NULL for Failure.
87 *//***************************************************************************/
88 t_Handle FM_MURAM_ConfigAndInit(uintptr_t baseAddress, uint32_t size);
89 
90 /**************************************************************************//**
91  @Function      FM_MURAM_Free
92 
93  @Description   Frees all resources that were assigned to FM-MURAM module.
94 
95                 Calling this routine invalidates the descriptor.
96 
97  @Param[in]     h_FmMuram - FM-MURAM module descriptor.
98 
99  @Return        E_OK on success; Error code otherwise.
100 *//***************************************************************************/
101 t_Error  FM_MURAM_Free(t_Handle h_FmMuram);
102 
103 /** @} */ /* end of FM_muram_init_grp group */
104 
105 
106 /**************************************************************************//**
107  @Group         FM_muram_ctrl_grp FM MURAM Control Unit
108 
109  @Description   FM MURAM control API functions, definitions and enums
110 
111  @{
112 *//***************************************************************************/
113 
114 /**************************************************************************//**
115  @Function      FM_MURAM_AllocMem
116 
117  @Description   Allocate some memory from FM-MURAM partition.
118 
119  @Param[in]     h_FmMuram - FM-MURAM module descriptor.
120  @Param[in]     size      - size of the memory to be allocated.
121  @Param[in]     align     - Alignment of the memory.
122 
123  @Return        address of the allocated memory; NULL otherwise.
124 *//***************************************************************************/
125 void  * FM_MURAM_AllocMem(t_Handle h_FmMuram, uint32_t size, uint32_t align);
126 
127 /**************************************************************************//**
128  @Function      FM_MURAM_AllocMemForce
129 
130  @Description   Allocate some specific memory from FM-MURAM partition (according
131                 to base).
132 
133  @Param[in]     h_FmMuram - FM-MURAM module descriptor.
134  @Param[in]     base      - the desired base-address to be allocated.
135  @Param[in]     size      - size of the memory to be allocated.
136 
137  @Return        address of the allocated memory; NULL otherwise.
138 *//***************************************************************************/
139 void  * FM_MURAM_AllocMemForce(t_Handle h_FmMuram, uint64_t base, uint32_t size);
140 
141 /**************************************************************************//**
142  @Function      FM_MURAM_FreeMem
143 
144  @Description   Free an allocated memory from FM-MURAM partition.
145 
146  @Param[in]     h_FmMuram - FM-MURAM module descriptor.
147  @Param[in]     ptr       - A pointer to an allocated memory.
148 
149  @Return        E_OK on success; Error code otherwise.
150 *//***************************************************************************/
151 t_Error FM_MURAM_FreeMem(t_Handle h_FmMuram, void *ptr);
152 
153 /**************************************************************************//**
154  @Function      FM_MURAM_GetFreeMemSize
155 
156  @Description   Returns the size (in bytes) of free MURAM memory.
157 
158  @Param[in]     h_FmMuram - FM-MURAM module descriptor.
159 
160  @Return        Free MURAM memory size in bytes.
161 *//***************************************************************************/
162 uint64_t FM_MURAM_GetFreeMemSize(t_Handle h_FmMuram);
163 
164 /** @} */ /* end of FM_muram_ctrl_grp group */
165 /** @} */ /* end of FM_muram_grp group */
166 /** @} */ /* end of FM_grp group */
167 
168 
169 
170 #endif /* __FM_MURAM_EXT */
171