1 /**
2 * @file SysLink.h
3 *
4 * @brief This module contains common definitions, types, structures and
5 * functions used by SysLink.
6 *
7 *
8 */
9 /*
10 * ============================================================================
11 *
12 * Copyright (c) 2008-2012, Texas Instruments Incorporated
13 *
14 * Redistribution and use in source and binary forms, with or without
15 * modification, are permitted provided that the following conditions
16 * are met:
17 *
18 * * Redistributions of source code must retain the above copyright
19 * notice, this list of conditions and the following disclaimer.
20 *
21 * * Redistributions in binary form must reproduce the above copyright
22 * notice, this list of conditions and the following disclaimer in the
23 * documentation and/or other materials provided with the distribution.
24 *
25 * * Neither the name of Texas Instruments Incorporated nor the names of
26 * its contributors may be used to endorse or promote products derived
27 * from this software without specific prior written permission.
28 *
29 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
30 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
31 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
32 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
33 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
34 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
35 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
36 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
37 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
38 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
39 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
40 * Contact information for paper mail:
41 * Texas Instruments
42 * Post Office Box 655303
43 * Dallas, Texas 75265
44 * Contact information:
45 * http://www-k.ext.ti.com/sc/technical-support/product-information-centers.htm?
46 * DCMP=TIHomeTracking&HQS=Other+OT+home_d_contact
47 * ============================================================================
48 *
49 */
53 #ifndef _SysLink_H_
54 #define _SysLink_H_
57 #if defined (__cplusplus)
58 extern "C" {
59 #endif
61 /* =============================================================================
62 * macros & defines
63 * =============================================================================
64 */
66 /* The bulk of this file is wrapped in this doxygen INTERNAL as it's not intended
67 * to be used by end users. Most of this is implementation details that users
68 * shouldn't see or bind to.
69 */
71 /** @cond INTERNAL */
73 /**
74 * @const IPC_BUFFER_ALIGN
75 *
76 * @desc Macro to align a number.
77 * x: The number to be aligned
78 * y: The value that the number should be aligned to.
79 */
80 #define IPC_BUFFER_ALIGN(x, y) (UInt32)((UInt32)((x + y - 1) / y) * y)
83 /**
84 * @brief Maximum number of mem entries for each core for one platform.
85 */
86 #define SYSLINK_MAX_MEMENTRIES 32
88 /**
89 * @brief Max name length.
90 */
91 #define SYSLINK_MAX_NAMELENGTH 32
93 /* =============================================================================
94 * Structures & Enums
95 * =============================================================================
96 */
98 typedef UInt32 SysLink_MapMask;
100 /**
101 * @brief Kernel Virtual address on master processor
102 */
103 #define SysLink_MASTERKNLVIRT (SysLink_MapMask)(1 << 0)
105 /**
106 * @brief User Virtual address on master processor
107 */
108 #define SysLink_MASTERUSRVIRT (SysLink_MapMask)(1 << 1)
110 /**
111 * @brief Virtual address on slave processor
112 */
113 #define SysLink_SLAVEVIRT (SysLink_MapMask)(1 << 2)
115 /**
116 * @brief Enumeration of Client notifyMgr notification types.
117 */
118 typedef enum SysLink_NotifyType_tag {
119 SysLink_NOTIFICATION_NONE = 0,
120 /*!< No notification required*/
121 SysLink_NOTIFICATION_ALWAYS = 1,
122 /*!< Notify whenever the other client sends data/frees up space.*/
123 SysLink_NOTIFICATION_ONCE = 2,
124 /*!< Notify when the other side sends data/frees up buffer. Once the
125 * notification is done, the notification is disabled until it is
126 * enabled again.
127 */
128 SysLink_NOTIFICATION_HDWRFIFO_ALWAYS = 3,
129 /*!< Notify whenever the other side sends data/frees up space.
130 * This notification is never disabled.
131 */
132 SysLink_NOTIFICATION_HDWRFIFO_ONCE = 4
133 /*!< Notify when the other side sends data/frees up buffer. Once the
134 * notification is done, the notification is disabled until it is enabled
135 * again. The notification is enabled once the watermark is crossed and
136 * does not require buffer to get full/empty.
137 */
138 } SysLink_NotifyType;
140 /**
141 * @brief Structure for memEntry.
142 */
143 typedef struct SysLink_MemEntry_tag {
144 UInt32 slaveVirtAddr; /**< Virtual address */
145 UInt32 masterPhysAddr; /**< Physical address */
146 UInt32 size; /**< Size of the entry */
147 SysLink_MapMask mapMask; /**< Used for entries for which map is TRUE */
148 Bool map; /**< Flag indicating whether this region should
149 * be mapped to the slave MMU.
150 */
151 Bool isCached; /**< Flag indicating whether the cache is enabled
152 * for this region
153 */
154 Bool isValid; /**< Specifies if the memEntry is valid */
155 } SysLink_MemEntry;
157 /**
158 * @brief Structure for memEntry block for one core.
159 */
160 typedef struct SysLink_MemEntry_Block_tag {
161 Char procName[SYSLINK_MAX_NAMELENGTH];
162 /*!< Processor name for which entries are being defined*/
163 UInt32 numEntries;
164 /*!< Max memEntries for one core*/
165 SysLink_MemEntry memEntries [SYSLINK_MAX_MEMENTRIES];
166 /*!< Entire memory map (p->v) for one code*/
167 } SysLink_MemEntry_Block;
170 /**
171 * @brief Structure for memEntry block for one core.
172 */
173 typedef struct SysLink_MemoryMap_tag {
174 UInt16 numBlocks;
175 /*!< Number of memory blocks in the memory map */
176 SysLink_MemEntry_Block * memBlocks;
177 /*!< Poninter to entire system memory map */
178 } SysLink_MemoryMap;
180 /** @endcond */
182 /**
183 * @brief Config params override strings.
184 *
185 * This string is a list of semi-colon-delimited "assignments" that can be set
186 * by users prior to the initial call to SysLink_setup() to affect system
187 * behavior.
188 *
189 * Example assignments include:
190 * - "ProcMgr.proc[DSP].mmuEnable=FALSE;"
191 * - "ProcMgr.proc[VPSS-M3].mmuEnable=TRUE;"
192 * - "SharedRegion.entry[1].cacheEnable=FALSE;"
193 * - "SharedRegion.entry[3].cacheEnable=FALSE;"
194 *
195 * @remarks Note that many users don't explicitly set this string and
196 * rebuild their app, but rather leverage the @c SL_PARAMS
197 * environment variable to set this string's value.
198 *
199 * @remarks In many systems, slaveloader (or similar) is used to load
200 * and start the slaves, and is therefore the initial app
201 * in the system. In those systems, it's important to set
202 * this variable (or @c SL_PARAMS) prior to running slaveloader.
203 *
204 * @remarks A common mistake is to forget to terminate the string with
205 * a trailing semi-colon.
206 */
207 extern String SysLink_params;
210 /* =============================================================================
211 * APIs
212 * =============================================================================
213 */
214 /**
215 * @brief Function to initialize SysLink.
216 *
217 * This function must be called in every user process before making
218 * calls to any other SysLink APIs.
219 *
220 * @sa SysLink_destroy()
221 */
222 Void SysLink_setup (Void);
224 /**
225 * @brief Function to finalize SysLink.
226 *
227 * This function must be called in every user process at the end
228 * after all usage of SysLink in that process is complete.
229 *
230 * @sa SysLink_setup()
231 */
232 Void SysLink_destroy (Void);
235 #if defined (__cplusplus)
236 }
237 #endif
240 #endif /*_SysLink_H_*/