summaryrefslogtreecommitdiffstats
path: root/osal.h
blob: edd382d829224a3fec3c0c2ee70a290baacde8f7 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
/*
 * Copyright (c) 2015 - 2018, Texas Instruments Incorporated
 * All rights reserved.
 *
 * 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.
 */
/** ============================================================================
 *  @file       osal.h
 *
 *  @brief      OS Abstraction Layer header
 *
 *  ============================================================================
 */

#ifndef ti_OSAL__include
#define ti_OSAL__include

#ifdef __cplusplus
extern "C" {
#endif

#include <ti/osal/HwiP.h>
#include <ti/osal/MuxIntcP.h>
#include <ti/osal/SemaphoreP.h>
#include <ti/osal/CacheP.h>
#include <ti/osal/TimerP.h>
#include <ti/osal/RegisterIntr.h>
#include <ti/osal/Queue.h>
#ifdef _TMS320C6X
#include <ti/osal/EventCombinerP.h>
#endif

/*********************************************************************
 * @def osal_OK
 * OSAL operation successful
 *********************************************************************/
#define osal_OK        (0)

/*********************************************************************
 * @def osal_FAILURE
 * OSAL operation failed
 *********************************************************************/
#define osal_FAILURE  (-(int32_t)(1))

/*********************************************************************
 * @def osal_UNSUPPORTED
 * OSAL operation is not supported
 *********************************************************************/
#define osal_UNSUPPORTED       (-(int32_t)(2))

/*********************************************************************
 * @def osal_NOMEM
 * OSAL operation is not successful due to internal osal static memory
 * is full. Application would need to create additional memory blocks
 * during startup by calling @ref Osal_setHwAttrs API to set the additional
 * memory blocks for semaphoreP and hwiP
 *********************************************************************/
#define osal_NOMEM             (-(int32_t)(3))

/*********************************************************************
 * @def OSAL_NONOS_SEMAPHOREP_SIZE_BYTES
 * Semaphorep handle size for non-os use case
 * Application can use this size to provide a secondary extended
 * memory block for semaphore creation when all the memory  (internal to osal)
 * are utilized
 *
 *********************************************************************/
#define  OSAL_NONOS_SEMAPHOREP_SIZE_BYTES ((uint32_t) 48U)

/*********************************************************************
 * @def OSAL_NONOS_HWI_SIZE_BYTES
 * HwiP handle size for non-os use case
 * Application can use this size to provide a secondary extended
 * memory block for hwip creation when all the memory  (internal to osal)
 * are utilized
 *********************************************************************/
#define  OSAL_NONOS_HWIP_SIZE_BYTES ((uint32_t) 48U)

/*********************************************************************
 * @def OSAL_TIRTOS_SEMAPHOREP_SIZE_BYTES
 * Semaphorep handle size for non-os use case
 * Application can use this size to provide a secondary extended
 * memory block for semaphore creation when all the memory  (internal to osal)
 * are utilized
 *
 *********************************************************************/
#define  OSAL_TIRTOS_SEMAPHOREP_SIZE_BYTES ((uint32_t) 96U)

/*********************************************************************
 * @def OSAL_TIRTOS_HWI_SIZE_BYTES
 * HwiP handle size for non-os use case
 * Application can use this size to provide a secondary extended
 * memory block for hwip creation when all the memory  (internal to osal)
 * are utilized
 *********************************************************************/
#define  OSAL_TIRTOS_HWIP_SIZE_BYTES (96U)

/**
 *  \brief This structure holds static memory status parameters of OSAL
 *         library
 */
typedef struct Osal_StaticMemoryStatus
{
    uint32_t peakSemObjs;
    uint32_t numMaxSemObjs;
    uint32_t numFreeSemObjs;

    uint32_t peakTimerObjs;
    uint32_t numMaxTimerObjs;
    uint32_t numFreeTimerObjs;

    uint32_t peakHwiObjs;
    uint32_t numMaxHwiObjs;
    uint32_t numFreeHwiObjs;
} Osal_StaticMemStatus;

/**
 *  \brief This enum defines the multiple thread types used under OSAL
 *         library
 */
typedef enum Osal_ThreadType_e {
    Osal_ThreadType_Hwi,   /*!< Current thread is a Hwi  */
    Osal_ThreadType_Swi,   /*!< Current thread is a Swi  */
    Osal_ThreadType_Task,  /*!< Current thread is a Task */
    Osal_ThreadType_Main   /*!< Current thread is Main   */
} Osal_ThreadType;

/* Internal function for assert */
extern void Osal_DebugP_assert(int32_t expression, const char *file, int32_t line);
/*!
 *  @brief  Assert checking function
 *
 *  If the expression is evaluated to true, the API does nothing.
 *  If it is evaluated to false, the underlying RTOS port implementation
 *  handles the assert via its mechanisms.
 *
 *  @param  expression Expression to evaluate
 */
/* in real code use TI's version of OSAL_Assert (which is also fatal for OSAL_Assert(1)*/
#define OSAL_Assert(expression) (Osal_DebugP_assert((int32_t)((expression)?1:0),\
                                                  __FILE__, __LINE__))

/*!
 *  @brief  Function to get the current thread type.
 *
 *
 *  @return current thread type
 */
extern Osal_ThreadType Osal_getThreadType(void);

/*!
 *  @brief  Function to get the delay/sleep.
 *
 *  @param  nTicks number of ticks
 *
 *  #@note  for bare metal application it is number of 1ms ticks
 *
 *          Prerequisites: Board_init() to be called before 
 *          invoking this API
 *
 *  @return osal_OK for success, osal_FAILURE on failure
 */
extern int32_t Osal_delay(uint32_t nTicks);

/*!
 *  @brief  Osal hw access type 
 *
 */
typedef enum {
  OSAL_HWACCESS_UNRESTRICTED, /* No restriction on hardware access or configuration */
  OSAL_HWACCESS_RESTRICTED    /* Restrictive access to hardware such as GIC */
} Osal_HwAccessType;

/*!
 *  @brief  Osal memory address range
 *
 */
typedef struct Osal_memRange_s {
  uintptr_t    base;          /**< Start address value */
  uint32_t     size;          /**< size in bytes */
} Osal_memRange;

/*!
 *  @brief  Osal hw attributes structure
 *
 */
typedef struct Osal_HwAttrs_s
{
   /* CPU frequency in KHz */
   int32_t  cpuFreqKHz;
   /* External Clock value in KHz */
   int32_t  extClkKHz;
#if defined(gnu_targets_arm_A15F)
   /* Set Target processor list */
   uint32_t a15TargetProcMask;
#endif
#ifdef _TMS320C6X
   int32_t ECM_intNum[4]; /* Interrupt numbers for Event combiner groups (0-3)*/
#endif
   Osal_HwAccessType hwAccessType;
   /* Below timer base configuration is applicable for only AM335x/AM437x SoCs
    * It is not applicable and should not be set for other SoCs
    * Osal setHwAttrs API would return failure (osal_UNSUPPORTED) if attempted to
    * be set for SoCs other than AM335x and AM437x.
    */
   uintptr_t     osalDelayTimerBaseAddr;
   Osal_memRange  extSemaphorePBlock;
   Osal_memRange  extHwiPBlock;
} Osal_HwAttrs;


/*!
 * bit map to set external clock in Osal_HwAttr default value
 */
#define  OSAL_HWATTR_SET_EXT_CLK    (0x00000001U)

/*!
 * bit map to set Event combiner interrupt numbers in the Osal_HwAttr
 */
#define  OSAL_HWATTR_SET_ECM_INT      (0x00000002U)

/*!
 * bit map to set the hardware access type
 */
#define OSAL_HWATTR_SET_HWACCESS_TYPE (0x00000004U)

/*!
 * bit map to set the osal_delay Timer base address
 */
#define OSAL_HWATTR_SET_OSALDELAY_TIMER_BASE (0x00000008U)

/*!
 * bit map to set the extended SemaphoreP memory block for additional SemaphoreP needs
 */
#define OSAL_HWATTR_SET_SEMP_EXT_BASE   (0x00000010U)

/*!
 * bit map to set the extended HwiP memory block for additional HwiP needs
 */
#define OSAL_HWATTR_SET_HWIP_EXT_BASE   (0x00000020U)

/*!
 * bit map to set the CPU frequency
 */
#define OSAL_HWATTR_SET_CPU_FREQ        (0x00000040U)

/*!
 * bit map to set the target processor list to direct interrupts to specific core
 */
#define OSAL_HWATTR_SET_TARG_PROC_LIST  (0x00000080)


/*!
 *  @brief  Function to set the Hw Attributes
 *
 *  @param  ctrlBitMap control bit map as defined by the OSAL_HWATTR_SET control bits
 *
 *  @param  hwAttrs    pointer to Osal_HwAttrs structure
 *
 *  @return osal_OK for success, osal_FAILURE on failure and
 *   osal_UNSUPPORTED for unsupported configurations
 *   osal_UNSUPPORTED is a non fatal error and applications
 *   can continue processing if they get this error code.
 *   Osal would be configured to utilize default timer for
 *   Osal_delay() API. The default timer address for AM437x and
 *   AM335x SoCs are found under ti/osal/soc/'<'soc_part'>'/osal_soc.h
 *   For other SoCs the time base address is not applicable and
 *   the API returns osal_UNSUPPORTED as the return value.
 */
extern int32_t Osal_setHwAttrs(uint32_t ctrlBitMap, const Osal_HwAttrs *hwAttrs);

/*!
 *  @brief  Function to get the Hw Attributes
 *
 *  @param  hwAttrs  pointer to Osal_HwAttrs structure
 *
 *  @return osal_OK for success, osal_FAILURE on failure
 */
extern int32_t Osal_getHwAttrs(Osal_HwAttrs *hwAttrs);

/*!
 *  @brief  Function to get the static memory usage of OSAL library
 *
 *  @param  pMemStat  pointer to Osal_StaticMemStatus structure
 *
 *  @return osal_OK for success, osal_FAILURE on failure
 */
extern int32_t Osal_getStaticMemStatus(Osal_StaticMemStatus *pMemStat);

/*!
 *  @brief  Function to get the core ID of the running Core.
 *
 *  @return core ID of the running core
 */
extern int32_t Osal_getCoreId(void);

/*! 
 * @brief external references for Osal Hw Attribute structure 
 */
extern Osal_HwAttrs  gOsal_HwAttrs;

/*!
 * This macro generates compilier error if postulate is false, so 
 * allows 0 overhead compile time size check.  This "works" when
 * the expression contains sizeof() which otherwise doesn't work
 * with preprocessor */
#define OSAL_COMPILE_TIME_SIZE_CHECK(x,y)                              \
   do {                                                                 \
       struct {                                                 \
         uint8_t NegativeSizeIfPostulateFalse[(y) + 1U - (x)];         \
       } PostulateCheck;                                              \
   }                                                                   \
   while ((bool)false)

#ifdef __cplusplus
}
#endif

#endif /* ti_OSAL__include */