1 /*
2 * Copyright (c) 2010-2020, Texas Instruments Incorporated
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of Texas Instruments Incorporated nor the names of
17 * its contributors may be used to endorse or promote products derived
18 * from this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 *
32 */
34 /**
35 * @file board.h
36 *
37 * @brief The Board Library is a thin utility
38 * layer on top of CSL and other board utilities. It provides uniform APIs
39 * for all supported boards. It aims to assist user to quickly write portable
40 * applications for its supported boards by hiding board level details
41 * from the user.
42 *
43 *
44 */
46 #ifndef BOARD_UTILS_H_
47 #define BOARD_UTILS_H_
49 #ifdef __cplusplus
50 extern "C" {
51 #endif
53 /**
54 * \defgroup BOARD_LIB_MODULE Board Library
55 *
56 * @{
57 *
58 * Board library provides set of APIs to initialize the interfaces
59 * on a given HW platform. It takes care of configuring and enabling different
60 * modules like PLL, clocks inside SoC and HW components like DDR, pinmux
61 * on the board which are required to make sure board is ready for running the
62 * application software.
63 *
64 * A common standard API Board_init() is exposed to the applications to invoke
65 * different board initialization routines. This function is common across the
66 * platforms maintaining the portability and can receive different input
67 * configuration flags based on the board capabilities allowing extendibility.
68 *
69 * Board library eliminates the use of any additional configurations like
70 * GEL files to initialize the board except the cases like DDR initialization
71 * for loading the code into DDR before calling the Board init function.
72 * Given this limitation, applications invoking board library functions to
73 * initialize PLL, DDR and pinmux are supposed to run from SoC internal memory.
74 *
75 * Additional functionality for configuring the devices like Ethernet PHYs,
76 * Flash devices and IO expanders etc is provided based on the platform need.
77 * Refer to the device/platform specific library documentation for more details.
78 *
79 */
80 /* @} */
83 /**
84 * \ingroup BOARD_LIB_MODULE
85 *
86 * @defgroup BOARD_LIB_MODULE_TYPES Board Data Types
87 */
88 /*@{*/
89 /**
90 * @brief Board Library uses basic C99 data types. The basic types used are
91 * uint32_t, int32_t, uint8_t, int8_t, uint16_t and int16_t. The standard
92 * C char is used for strings. Complex types (or typdefs) if used are defined
93 * within this header file.
94 */
95 #include <stdint.h>
97 #include <ti/csl/hw_types.h>
99 /**
100 * @brief The following definitions are for handling cache alignment on the board.
101 *
102 * MAX_CACHE_LINE must be set to the cache line size of the board.
103 *
104 * When allocating memory that must be cache aligned, it must be a multiple of
105 * the cache line size. Use board_roundup to get the appropriate size.
106 *
107 * As an example to allocate a cache aligned block of memory you would do
108 * something like:
109 *
110 * buffer_len_aligned = board_roundup (buffer_len, MAX_CACHE_LINE)
111 * Malloc (buffer_len_aligned)
112 *
113 */
114 /* w should be power of 2 */
115 #define BOARD_CACHE_LINE_SIZE (128)
116 #define board_roundup(n,w) (((n) + (w) - 1) & ~((w) - 1))
118 /*************************************************************
119 * Return/Error values *
120 *************************************************************/
122 #include <ti/board/board_cfg.h>
124 /** Board status OK */
125 #define BOARD_SOK 0
126 /** Error code for invalid parameters */
127 #define BOARD_INVALID_PARAM -1
128 /** Error code for unsupported feature */
129 #define BOARD_UNSUPPORTED_FEATURE -2
130 /** I2C handle open failed */
131 #define BOARD_I2C_OPEN_FAIL -3
132 /** I2C transfer call failed */
133 #define BOARD_I2C_TRANSFER_FAIL -4
134 /** IO Delay region not in internal memory */
135 #define BOARD_PINMUX_BAD_MEM_REGION -5
136 /** Error code for init clock module */
137 #define BOARD_INIT_CLOCK_FAIL -6
138 /** Error code for init DDR */
139 #define BOARD_INIT_DDR_FAIL -7
140 /** Runtime pinmux configuration mode */
141 #define BOARD_PINMUX_INVALID_MODE -8
142 /** Board status FAIL */
143 #define BOARD_FAIL -10
145 /*************************************************************
146 * Init/Info Definitons *
147 *************************************************************/
149 /* Max number of characters per ID entry field */
150 #define BOARD_MAX_ID_STR_LEN 20
152 #define BOARD_BOARD_NAME_LEN (16U)
153 #define BOARD_DESIGN_REV_LEN (2U)
154 #define BOARD_PROC_NUM_LEN (4U)
155 #define BOARD_VARIANT_LEN (2U)
156 #define BOARD_PCBREV_LEN (2U)
157 #define BOARD_SCHMBOM_REV_LEN (2U)
158 #define BOARD_SWREV_LEN (2U)
159 #define BOARD_VENDORID_LEN (2U)
160 #define BOARD_BUILD_WEEK_LEN (2U)
161 #define BOARD_BUILD_YEAR_LEN (2U)
162 #define BOARD_BOARDID_LEN (6U)
163 #define BOARD_SERIAL_NUM_LEN (4U)
164 #define BOARD_MAC_ADDR_LEN (192U)
167 /*************************************************************
168 * SoC Info Definitons *
169 *************************************************************/
171 /* Default system clock value */
172 #define BOARD_SYS_CLK_DEFAULT (0xFFFFFFFFU)
174 /**
175 * @brief This structure contains board specific information
176 *
177 * This is the first generation (v1) of board ID info structure
178 * which is applicable to all the platforms prior to Keystone-III.
179 */
180 typedef struct {
182 /* Header ID of the SOC */
183 char header[BOARD_MAX_ID_STR_LEN];
185 /* Name of the board */
186 char boardName[BOARD_MAX_ID_STR_LEN];
188 /* Board version/revision info */
189 char version[BOARD_MAX_ID_STR_LEN];
191 /* Board serial number */
192 char serialNum[BOARD_MAX_ID_STR_LEN];
194 /* Board configuration codes */
195 char configCodes[2*BOARD_MAX_ID_STR_LEN];
197 /* Industrial Ethernet MAC address 0 */
198 char indEthMacID0[BOARD_MAX_ID_STR_LEN];
200 /* Industrial Ethernet MAC address 3 */
201 char indEthMacID3[BOARD_MAX_ID_STR_LEN];
203 } Board_IDInfo;
205 typedef struct
206 {
207 uint8_t macStructType;
208 uint16_t macLength;
209 uint16_t macControl;
210 uint8_t macAddress[BOARD_MAC_ADDR_LEN];
211 } __attribute__((packed)) Board_macInfo;
213 typedef struct
214 {
215 uint8_t ddrStructType;
216 uint16_t ddrStructLen;
217 uint16_t ddrCtrl;
218 } __attribute__((packed)) Board_ddrInfo;
220 typedef struct
221 {
222 uint8_t boardInfoStructType;
223 uint16_t boardInfoLength;
224 char boardName[BOARD_BOARD_NAME_LEN];
225 char designRev[BOARD_DESIGN_REV_LEN];
226 char procNum[BOARD_PROC_NUM_LEN];
227 char variant[BOARD_VARIANT_LEN];
228 char pcbRev[BOARD_PCBREV_LEN];
229 char schbomRev[BOARD_SCHMBOM_REV_LEN];
230 char swRev[BOARD_SWREV_LEN];
231 char vendorID[BOARD_VENDORID_LEN];
232 char buildWeek[BOARD_BUILD_WEEK_LEN];
233 char buildYear[BOARD_BUILD_YEAR_LEN];
234 char boardID[BOARD_BOARDID_LEN];
235 char serialNum[BOARD_SERIAL_NUM_LEN];
236 } __attribute__((packed)) Board_boardInfo;
238 typedef struct
239 {
240 uint32_t magicNumber;
241 uint8_t headerStructType;
242 uint16_t payloadSize;
243 } __attribute__((packed)) Board_headerInfo;
245 /**
246 * @brief This structure contains board specific information
247 *
248 * This is the second generation (v2) of board ID info structure
249 * which is applicable to the platforms from Keystone-III and later.
250 */
251 typedef struct
252 {
253 /* Header info of the board */
254 Board_headerInfo headerInfo;
256 /* Board id Info of the board */
257 Board_boardInfo boardInfo;
259 /* DDR info of the board */
260 Board_ddrInfo ddrInfo;
262 /* Mac Info of the board */
263 Board_macInfo macInfo;
265 /* End of the structure */
266 uint8_t endList;
268 } __attribute__((packed)) Board_IDInfo_v2;
270 /**
271 * @brief This structure contains SoC specific information
272 */
273 typedef struct {
275 /* System clock value in Hz */
276 uint32_t sysClock;
278 } Board_SoCInfo;
280 /** ---------------------------------------------------------------------------
281 * \brief Enumeration of reported temperature event types
282 *
283 * ----------------------------------------------------------------------------
284 */
285 typedef enum {
286 /** Temperature alert event occurred */
287 BOARD_DDR_TEMP_EVENT_TEMP_ALERT = 1,
288 /** Low temperature alarm event occurred */
289 BOARD_DDR_TEMP_EVENT_LOW_TEMP_ALARM = 2,
290 /** Temperature change event occurred: Needs 4 x refresh */
291 BOARD_DDR_TEMP_EVENT_TEMP_CHANGE_4X_REFRESH = 3,
292 /** Temperature change event occurred: Needs 2 x refresh */
293 BOARD_DDR_TEMP_EVENT_TEMP_CHANGE_2X_REFRESH = 4,
294 /** Temperature change event occurred: Needs 1 x refresh */
295 BOARD_DDR_TEMP_EVENT_TEMP_CHANGE_1X_REFRESH = 5,
296 /** Temperature change event occurred: Needs 0.5 x refresh */
297 BOARD_DDR_TEMP_EVENT_TEMP_CHANGE_1_BY_2_REFRESH = 6,
298 /** Temperature change event occurred: Needs 0.25 x refresh */
299 BOARD_DDR_TEMP_EVENT_TEMP_CHANGE_1_BY_4_REFRESH = 7,
300 /** Temperature change event occurred: Needs 0.25 x refresh and derating */
301 BOARD_DDR_TEMP_EVENT_TEMP_CHANGE_1_BY_4_REFRESH_WITH_DERATING = 8,
302 /** High temperature alarm event occurred */
303 BOARD_DDR_TEMP_EVENT_HIGH_TEMP_ALARM = 9,
304 } Board_DDRTempEventType;
306 typedef uint32_t Board_initCfg;
307 #define BOARD_INIT_ALL (0xFFFFFFFFU)
308 #define BOARD_INIT_UNLOCK_MMR (1 << 1U)
309 #define BOARD_INIT_PLL (1 << 2U)
310 #define BOARD_INIT_PLL_MCU (1 << 3U)
311 #define BOARD_INIT_PLL_MAIN (1 << 4U)
312 #define BOARD_INIT_MODULE_CLOCK (1 << 5U)
313 #define BOARD_INIT_MODULE_CLOCK_MCU (1 << 6U)
314 #define BOARD_INIT_MODULE_CLOCK_MAIN (1 << 7U)
315 #define BOARD_INIT_DDR (1 << 8U)
316 #define BOARD_INIT_WATCHDOG_DISABLE (1 << 9U)
317 #define BOARD_INIT_PINMUX_CONFIG (1 << 10U)
318 #define BOARD_INIT_PINMUX_CONFIG_MAIN (1 << 11U)
319 #define BOARD_INIT_PINMUX_CONFIG_MCU (1 << 12U)
320 #define BOARD_INIT_UART_STDIO (1 << 13U)
321 #define BOARD_INIT_ICSS_PINMUX (1 << 14U)
322 #define BOARD_INIT_ETH_PHY (1 << 15U)
323 #define BOARD_INIT_ECC (1 << 16U)
324 #define BOARD_INIT_PLL_OPP_HIGH (1 << 17U)
325 #define BOARD_INIT_PLL_OPP_OD (1 << 18U)
326 #define BOARD_INIT_PLL_OPP_NOM (1 << 19U)
327 /* iceK2G requires board specific Ethernet configurations for
328 proper operation of Ethernet interfaces. Applications
329 using NSS(Gigabit) or ICSS(10/100mbps) Ethernet inteface
330 should call Board_init() with config control macro
331 'BOARD_INIT_ETH_PHY' for initializing Gigabit Ethernet PHY and
332 'BOARD_INIT_ICSS_ETH_PHY' to invoke the PRU_ICSS Ethernet PHY
333 initialization */
334 /* Config control bit definition for 10/100 Ethernet PHY intialization */
335 #define BOARD_INIT_ICSS_ETH_PHY (1 << 20U)
336 /* Flag to enable EMIF pin mux configuration during Board_init.
337 EMIF pin mux is done as part of default pin mux as configuring EMIF pinmux
338 while system is running from SDRAM/DDR can corrupt the memory.
339 Use this flag only from the applications which are not running from SDRAM/DDR
340 */
341 #define BOARD_INIT_EMIF_PINMUX (1 << 21U)
342 /* Applies only to devices with DDR ECC support */
343 #define BOARD_INIT_DDR_ECC (1 << 22U)
344 /* Initializes SerDes module */
345 #define BOARD_INIT_SERDES_PHY (1 << 23U)
346 /* Initializes I2C controller instances used by the board */
347 #define BOARD_INIT_I2C (1 << 24U)
348 /* De-Initializes I2C controller instances used by the board */
349 #define BOARD_DEINIT_I2C (1 << 25U)
350 #define BOARD_INIT_CPSW9G_ETH_PHY (1 << 26U)
352 /* Configures ENET Control(mac mode, delay settings) for CPSW/ICCS ports */
353 #define BOARD_INIT_ENETCTRL_CPSW3G (1 << 27U)
354 #define BOARD_INIT_ENETCTRL_CPSW2G (1 << 27U)
355 #define BOARD_INIT_ENETCTRL_CPSW9G (1 << 28U)
356 #define BOARD_INIT_ENETCTRL_ICSS (1 << 29U)
357 #define BOARD_INIT_DEFAULT BOARD_INIT_ALL
358 #define BOARD_INIT_CPSW5G_ETH_PHY (BOARD_INIT_CPSW9G_ETH_PHY)
359 #define BOARD_INIT_ENETCTRL_CPSW5G (BOARD_INIT_ENETCTRL_CPSW9G)
361 #define BOARD_DEINIT_ALL (0xFFFFFFFFU)
362 #define BOARD_DEINIT_LOCK_MMR (1 << 1U)
363 #define BOARD_DEINIT_MODULE_CLOCK (1 << 2U)
364 #define BOARD_DEINIT_UART_STDIO (1 << 3U)
365 #define BOARD_DEINIT_DEFAULT BOARD_DEINIT_ALL
367 #define BOARD_RESOURCE_ALL (0xFFFFU)
368 #define BOARD_RESOURCE_MMR (1U)
369 #define BOARD_RESOURCE_MODULE_CLOCK (2U)
370 #define BOARD_RESOURCE_UART_STDIO (3U)
371 #define BOARD_RESOURCE_SCICLIENT (4U)
374 typedef void (*Board_thermalMgmtCallbackFunction_t)(Board_DDRTempEventType DDRTempEventType);
376 /* @} */
378 /**
379 * \ingroup BOARD_LIB_MODULE
380 *
381 * @defgroup BOARD_LIB_MODULE_APIS Board Standard APIs
382 */
383 /*@{*/
385 /*************************************************************
386 * APIs *
387 *************************************************************/
389 /**
390 * @brief Get board information.
391 *
392 * @param[out] info
393 * This structure will have board information on return
394 *
395 * @return Board_STATUS Returns status on API call
396 *
397 */
398 Board_STATUS Board_getIDInfo(Board_IDInfo *info);
400 /**
401 * @brief Get board information - v2
402 *
403 * @param[out] info
404 * This structure will have board information on return
405 * @param[in] slaveAddress
406 * I2C slave address of EEPROM to be read
407 *
408 * @return Board_STATUS Returns status on API call
409 *
410 */
411 Board_STATUS Board_getIDInfo_v2(Board_IDInfo_v2 *info, uint8_t slaveAddress);
413 /**
414 * @brief Set board information - v2
415 *
416 * @param[in] info
417 * This structure will have board information
418 * @param[in] slaveAddress
419 * I2C slave address of EEPROM to be write
420 *
421 * @return Board_STATUS Returns status on API call
422 *
423 */
424 Board_STATUS Board_writeIDInfo_v2(Board_IDInfo_v2 *info, uint8_t slaveAddress);
426 /**
427 * @brief Get SoC information.
428 *
429 * @param[out] socInfo
430 * This structure will have SoC information on return
431 *
432 * @return Board_STATUS Returns status on API call
433 *
434 */
435 Board_STATUS Board_getSoCInfo(Board_SoCInfo *socInfo);
437 /**
438 * @brief Initialization functions for a specific board.
439 *
440 * @param[in] cfg
441 * Param to indicate what to initialize when calling Board_init()
442 *
443 * @return Board_STATUS Returns status on API call
444 *
445 */
446 Board_STATUS Board_init(Board_initCfg cfg);
448 /**
449 * \brief Board library initialization function with limited module initializations
450 *
451 * This is ligher version of board init function which does not include the
452 * initialization of modules that depend on drivers. This can be used on
453 * platforms which are low on memory footprint.
454 *
455 * Please refer the board specific init code for list module init supported
456 * by this function.
457 *
458 * \param cfg [IN] Board configuration flags
459 *
460 * \return BOARD_SOK in case of success or appropriate error code
461 */
462 Board_STATUS Board_initLite(Board_initCfg cfg);
464 /**
465 * @brief Board library deinitialization function
466 *
467 * BOARD_DEINIT_UART_STDIO -
468 * Deinitializes the UART module.
469 *
470 * @param cfg [IN] Board configuration flags
471 *
472 * @return BOARD_SOK in case of success or appropriate error code
473 */
474 Board_STATUS Board_deinit(Board_initCfg cfg);
476 /**
477 * \brief Board library function to release the resources
478 *
479 * \param resourceID [IN] Resource ID
480 *
481 * \return BOARD_SOK in case of success or appropriate error code
482 */
483 Board_STATUS Board_releaseResource (uint32_t resourceID);
485 /**
486 * @brief Initialize Board DDR Temperature monitoring.
487 *
488 * @param[in] callbackFunction
489 * Callback function to be called with thermal events
490 *
491 * @return Board_STATUS Returns status on API call
492 *
493 */
494 Board_STATUS Board_DDRTempMonitoringInit(Board_thermalMgmtCallbackFunction_t callbackFunction);
496 #ifdef __cplusplus
497 }
498 #endif
500 #endif
501 /* @} */