Add Govind's changes to pdk platform lib for new HSR4/interconnect boards
[processor-sdk/performance-audio-sr.git] / pdk_k2g_1_0_1 / packages / ti / platform / platform.h
1 /*
2  * Copyright (c) 2010-2015, 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   platform.h
36  *
37  *  @brief  The Platform Library is a thin utility
38  *  layer on top of  CSL and other board utilities. It provides uniform APIs
39  *  for all supported platforms. It aims to assist user to quickly write portable
40  *  applications for its supported platforms by hiding board level details
41  *  from the user.
42  *
43  *
44  */
46 #ifndef PLATFORM_UTILS_H_
47 #define PLATFORM_UTILS_H_
49 /**
50  * @mainpage Platform Utility APIs
51  *  Defines a set of APIs for accessing and working with the various platform peripherals.
52  *
53  */
56 /** @defgroup  Platform_standard_data_types  Standard Data Types */
57 /*@{*/
58 /**
59  *  @brief      Platform Library uses basic C99 data types. The basic types used are
60  *              uint32_t, int32_t, uint8_t, int8_t, uint16_t and int16_t. The standard
61  *              C char is used for strings. Complex types (or typdefs) if used are defined
62  *              within this header file.
63  */
64 #include <stdint.h>
65 #define EXAMPLE_VARIABLE uint32_t
66 /*@}*/  /* defgroup */
68 /** @defgroup  Platform_memory_section  Linker Memory Sections */
69 /*@{*/
70 /**
71   * @brief  Memory Sections. You need to place these in your application linker map.
72   *
73   *                     Section name: PLATFORM_LIB_SECTION
74   *
75   *                     All of the static information used within the platform library is stored
76   *                     within this section.
77   */
78  #define PLATFORM_LIB_SECTION "This section defines the memory section for the platform library"
79 /*@}*/  /* defgroup */
81 /** @defgroup  Platform_cache Platform Cache */
82 /*@{*/
83 /**
84   * @brief  The following definitions are for handling cache alignment on the platform.
85   *
86   *             MAX_CACHE_LINE must be set to the cache line size of the platform.
87   *
88   *             When allocating memory that must be cache aligned, it must be a multiple of
89   *             the cache line size. Use platform_roundup to get the appropriate size.
90   *
91   *             As an example to allocate a cache aligned block of memory you would do
92   *             something like:
93   *
94   *                     buffer_len_aligned = platform_roundup (buffer_len, MAX_CACHE_LINE)
95   *                     Malloc (buffer_len_aligned)
96   *
97   */
98 /* w should be power of 2 */
99 #define PLATFORM_CACHE_LINE_SIZE (128)
100 #define platform_roundup(n,w) (((n) + (w) - 1) & ~((w) - 1))
102 /**
103  *   @n@b Convert_CoreLocal2GlobalAddr
104  *
105  *   @b Description
106  *   @n This API converts a core local L2 address to a global L2 address.
107  *
108  *   @param[in]  addr  L2 address to be converted to global.
109  *
110  *   @return    uint32_t >0  Global L2 address
111  *
112  */
113 uint32_t Convert_CoreLocal2GlobalAddr (uint32_t  addr);
116 /*@}*/  /* defgroup */
118 /** @defgroup  Compilation_Flags Compilation Flags */
119 /*@{*/
120 /***
121   * @brief  Flags for compiling the library.
122   *
123   *             The file paltform_internal.h has compilation flags that can be set.
124   */
125 /*@}*/  /* defgroup */
127 /** @defgroup  Platform_common  Common */
128 /*@{*/
130 /**
131  * Error codes used by Platform functions. Negative values are errors,
132  * while positive values indicate success.
133  */
135 #define Platform_STATUS        int32_t /** Platform API return type */
137 #define Platform_EINVALID     -3   /**< Error code for invalid parameters */
138 #define Platform_EUNSUPPORTED -2   /**< Error code for unsupported feature */
139 #define Platform_EFAIL        -1   /**< General failure code */
140 #define Platform_EOK           0   /**< General success code */
142 /* Set the endianess for the platform */
143 #define PLATFORM_LE 1
144 #define PLATFORM_BE 0
146 #define PLATFORM_MAX_EMAC_PORT_NUM       2   /**< Maximum number of EMAC ports */
148 /**
149  *  @brief This structure contains multicore processor information, e.g. # of the core, processor name, etc.
150  */
151 typedef struct {
152     int32_t core_count;
153     /**<Number of cores*/
154     char name[32];
155     /**<Name of processor (eg: TMS320C6472)*/
156     uint16_t id;
157     /**<CPU ID of the Device (eg. Ch -> C64x CPU, 10h -> C64x+ CPU).*/
158     uint16_t revision_id;
159     /**<CPU Revision ID*/
160     uint16_t megamodule_revision_major;
161     /**<Megamodule Revision ID Major*/
162     uint16_t megamodule_revision_minor;
163     /**<Megamodule Revision ID Minor*/
164     uint16_t silicon_revision_major;
165     /**<Silicon Revision ID Major*/
166     uint16_t silicon_revision_minor;
167     /**<Silicon Revision ID Minor*/
168     uint8_t endian;
169     /**<Endian: {PLATFORM_LE | PLATFORM_BE}*/
170 } CPU_info;
172 /**
173  *  @brief This structure contains information about the EMAC, e.g. # of EMAC port, MAC address for the port, etc.
174  */
175 typedef struct {
176     int32_t port_count;
177     /**<Number of EMAC ports*/
178     uint8_t efuse_mac_address[6];
179     /**<EFUSE EMAC address */ /* August 15, 2011 - this field is deprecated, MAC address is now defined in the new data structure PLATFORM_EMAC_EXT_info */
180     uint8_t eeprom_mac_address[6];
181     /**<EEPROM EMAC address */ /* August 15, 2011 - this field is deprecated, MAC address is now defined in the new data structure PLATFORM_EMAC_EXT_info */
182 } EMAC_info;
185 /**
186  * @brief Indicates the EMAC port mode
187  *
188  */
189 typedef enum {
190     PLATFORM_EMAC_PORT_MODE_NONE,
191     /**<EMAC port not used */
192     PLATFORM_EMAC_PORT_MODE_PHY,
193     /**<EMAC port connected to a PHY */
194     PLATFORM_EMAC_PORT_MODE_AMC,
195     /**<EMAC port connected to the backplane AMC chassis */
196     PLATFORM_EMAC_PORT_MODE_MAX
197     /**<End of port mode */
198 } PLATFORM_EMAC_PORT_MODE;
201 /**
202  *  @brief This structure contains extended information about the EMAC, e.g. port #, port mode, port MAC addess, etc.
203  */
204 typedef struct {
205     uint32_t                        port_num;
206     /**<Port number of the EMAC port */
207     PLATFORM_EMAC_PORT_MODE         mode;
208     /**<Mode of the EMAC port */
209     uint8_t                         mac_address[6];
210     /**<MAC address of the EMAC port */
211 } PLATFORM_EMAC_EXT_info;
214 /** @brief LED Classes */
216 typedef enum {
217     PLATFORM_USER_LED_CLASS,
218     /** <USER LED Group */
219     PLATFORM_SYSTEM_LED_CLASS,
220     /** <SYSTEM LED Group */
221     PLATFORM_END_LED_CLASS
222     /** END OF LED Groups */
223 } LED_CLASS_E;
225 /**
226  *  @brief This structure contains information about LED on the platform
227  */
228 typedef struct {
229     int32_t count;
230     /**<Number of LEDs*/
231 } LED_info;
233 /**
234  * @brief Define how platform_write should behave.
235  *    These write types can be set in the init structure
236  */
238 typedef enum {
239     PLATFORM_WRITE_UART,
240     /** <Write to the UART */
241     PLATFORM_WRITE_PRINTF,
242     /** <printf mapped output -- CCS console */
243     PLATFORM_WRITE_ALL
244     /** <write all - default configuration */
245 } WRITE_info;
247 /**
248  *  @brief This structure contains board specific information, e.g. cpu info, board Rev., LED info, etc.
249  */
250 typedef struct {
251     char version[16];
252     /**<Platform library version */
253     CPU_info cpu;
254     /**<CPU information */
255     char board_name[32];
256     /**<Name of the board */
257     char serial_nbr[16];
258     /**<Serial number for the unit as read from the I2C */
259     uint16_t board_rev;
260     /**<Revision number of the board, as read from the H/W*/
261         uint32_t frequency;
262     /**<CPU frequency (MHz)*/
263     /**<Peripheral information */
264     EMAC_info emac;
265     /**<EMAC information*/
266     LED_info led[PLATFORM_END_LED_CLASS];
267     /**<LED information*/
268 } platform_info;
271 /**
272  *  @brief      Get platform information.
273  *
274  *
275  *  @param[out] p_info  This structure will have platform information on return
276  *
277  */
279 void platform_get_info(platform_info * p_info);
281 /**
282  *  @brief This structure contains peripherals to be initialized. It provides for basic board initialization.
283  *                      Flash and Character device are intiialized and controlled when they are opened.
284  *
285  *  @remark
286  *     The init flags are set when platform_init() API is called by the application during
287  *     the board initialization, by default all the flags are set to 1.
288  */
289 typedef struct {
290     uint8_t pll;
291     /**<1: initialize PLL */
292     uint8_t ddr;
293     /**<1: initialize ddr */
294     uint8_t tcsl;
295     /**<1: initialize Time Stamp Counter (Low) Register */ /* June 2, 2011 - This flag is now deprecated and the TCSL is always initialized */
296     uint8_t phy;
297     /**<1: initialize PHY and its dependent components */
298     uint8_t ecc;
299     /**<1: initialize memory ECC checks. If 0, they are not disabled but the default power on state is disabled. */
300 } platform_init_flags;
303 /**
304  *  @brief This structure contains initialization parameters
305  */
307 typedef struct {
308     uint32_t pllm;
309     /**<Platform pll multiplier (0 to set the default value)*/
310     uint32_t plld;
311     /**<Platform pll divider (0 to set the default value)*/
312     uint32_t prediv;
313     /**<Platform pll predivider (0 to set the default value)*/
314     uint32_t postdiv;
315     /**<Platform pll postdivider (0 to set the default value)*/
316     uint16_t mastercore;
317     /** Designates this core as the Master. Default is Core 0 */
318  } platform_init_config;
320 /**
321  *  @brief     Plarform initialization
322  *
323  *  @param[in] p_flags  This structure will have init enable flags for peripherals
324  *
325  *  @param[in] p_config  This structure will have init configuration parameters
326  *
327  *  @retval    Platform_EOK on Success
328  *
329  *  @remark    This function can be called multiple times to init various peripherals,
330  *             normally this API is called first when board is initialized by the application
331  *
332  */
334 Platform_STATUS platform_init(platform_init_flags * p_flags, platform_init_config * p_config);
337 /**
338  *  @brief     Test external (DDR) memory region
339  *
340  *  @param[in] start_address  DDR Address to start at
341  *
342  *  @param[in] end_address    DDR Address to end at
343  *
344  *  @retval    Platform_EOK on Success
345  *
346  *  @remark    If the test fails, platform_errno will be set to the DDR address the test
347  *                         failed at.
348  */
350 Platform_STATUS platform_external_memory_test(uint32_t start_address, uint32_t end_address);
352 /**
353  *  @brief     Test external (DDR) memory region
354  *
355  *  @param[in] id  Core to run th einternal memory test on
356  * *
357  *  @retval    Platform_EOK on Success
358  *
359  *  @remark    If the test fails, platform_errno will be set to the DDR address the test
360  *                         failed at.
361  */
363 Platform_STATUS platform_internal_memory_test(uint32_t id);
367 /**
368  *  @brief     Plarform get core_id
369  *
370  *  @retval    Returns current core ID
371  *
372  */
374 uint32_t platform_get_coreid(void);
376 /*@}*/  /* defgroup */
378 /** @defgroup    EMAC_PHY_support_functions  EMAC */
379 /*@{*/
381 /**
382  * @brief MAC address type
383  *
384  */
385 typedef enum {
386     /** MAC address in EFUSE */
387     PLATFORM_MAC_TYPE_EFUSE,
388     /** MAC address in EEPROM */
389     PLATFORM_MAC_TYPE_EEPROM
390 } PLATFORM_MAC_TYPE;
392 /**
393  *  @brief     Plarform get MAC address from EFUSE
394  *
395  *             August 15, 2011 - this API is deprecated, application needs to call
396  *             the new API platform_get_emac_info() to get the MAC address of the port
397  *
398  *  @param[in] type  MAC address storage type
399  *
400  *  @param[out] mac_address  MAC address assigned to the core
401  *
402  *  @retval    Platform_EOK on Success
403  *
404  */
406 Platform_STATUS platform_get_macaddr(PLATFORM_MAC_TYPE type, uint8_t * mac_address);
408 /**
409  *  @brief     Plarform get information of an EMAC port
410  *
411  *  @param[in] port_num  port number
412  *
413  *  @param[out] emac_info  EMAC port information
414  *
415  *  @retval    Platform_EOK on Success
416  *
417  */
419 Platform_STATUS platform_get_emac_info(uint32_t port_num, PLATFORM_EMAC_EXT_info * emac_info);
421 /**
422  *  @brief     Get PHY address for a port number
423  *
424  *             Please note that this function is a place holder for C64x devices
425  *             and is not used for KeyStone devices.
426  *
427  *  @param[in] port_num  port number
428  *
429  *  @retval    event id or -1 on failure
430  *
431  */
433 int32_t platform_get_phy_addr(uint32_t port_num);
435 /**
436  *  @brief     Platform EMAC/PHY link status
437  *
438  *  @param[in] port_num  port number
439  *
440  *  @retval    0 on success
441  *
442  *  @remark    This is ONLY supported for on chip PHY
443  *
444  */
446 Platform_STATUS platform_phy_link_status(uint32_t port_num);
448 /*@}*/  /* defgroup */
450 /** @defgroup    Memory_device_support_functions  Memory Devices (e.g. Flash) */
451 /*@{*/
453 /**
454  * @brief Devices
455  *         The platform library provides a common interface for reading and writing
456  *         flash and serial memory devices on the platform.
457  *
458  *         To work with a device you must first open it, perform a read or write, and
459  *         then close it.
460  *
461  *         In addition to the basic operations of read and write, certain types of devices, like flash
462  *         may support other extended operations.
463  *
464  * Devices
465  *
466  *  Types:      NOR
467  *                      NAND
468  *                      EEPROM
469  *
470  * Operations:
471  *                      Open
472  *                      Close
473  *                      Read
474  *                      Write
475  *
476  *      Extended Operations:
477  *                      Erase                   Supported by NOR and NAND devices
478  *                      ReadSpare               Supported by NAND devices
479  *                      WriteSpare              Supported by NAND devices
480  *                      MarkBlockBad    Supported by NAND devices
481  *
482  *
483  *  Nand Device Notes:
484  *
485  *  Writes
486  *
487  *  When writing the NAND device you may either a) Write one page at a time or
488  *  b) write a block of data that is larger than a single page. All writes to the
489  *  NAND flash must be aligned to start on a page boundary.
490  *
491  *  When using platform_device_write() if you write a single page (done by
492  *  setting the length of the write to the page size) then your application will need to
493  *  take care of erasing and preserving the block the page is in.
494  *
495  *  If you write more than a page, the platform_device_write call will handle
496  *  erasing the block the page is in and will also preserve the contents of other
497  *  pages within the block that are not being written to. The algorithm used is as
498  *  follows:
499  *
500  *         While we have data to write do
501  *       skip block if bad (and keep skipping until the next good block is found)
502  *       read the block    (page level)
503  *       erase the block   (block level)
504  *       write the block   (page level)
505  *
506  *      Reads
507  *
508  *  When using platform_device_read on a NAND device it will currently only read a
509  *  single page at a time.
510  *
511  *
512  *  Nor Device Notes
513  *
514  *  Writes
515  *
516  *  When working the NOR device you may either write a block of data that is larger than
517  *  a single page. All writes to the flash must be aligned to start on a page boundary.
518  *
519  *  When using platform_device_write() if you write a single page (done by
520  *  setting the length of the write to the page size) then your application will need to
521  *  take care of erasing and preserving the block the page is in.
522  *
523  *  If you write more than a page, the platform_device_write call will handle
524  *  erasing the block the page is in and will also preserve the contents of other
525  *  pages within the block that are not being written to. The algorithm used is as
526  *  follows:
527  *
528  *         While we have data to write do
529  *       skip block if bad (and keep skipping until the next good block is found)
530  *       read the block    (page level)
531  *       erase the block   (block level)
532  *       write the block   (page level)
533  *
534  *  Reads
535  *
536  *  When using platform_device_read on a NOR device, you may read as much as you like.
537  */
539 /**
540  * @brief       Device Identifiers. These are used in the Open call to allow access to a specific
541  *                      memory device.
542  *
543  */
544 #define PLATFORM_DEVID_MT29F1G08ABCHC   0x2CA1          /**< 128MB NAND Flash */
545 #define PLATFORM_DEVID_NAND512R3A2D     0x2036          /**< 64MB NAND Flash */
546 #define PLATFORM_DEVID_MT29F4G08ABADA   0x2CDC          /**< 512MB NAND Flash */
547 #define PLATFORM_DEVID_MT29F16G08ADBCAH4C 0x2CA5        /**< 16Gb,1.8v,x8 */
548 #define PLATFORM_DEVID_MT29F2G16ABAFA   0x2CCA      /**< 2Gb, x16, 3.3V */
549 #define PLATFORM_DEVID_NORN25Q128       0xBB18          /**< 16MB NOR Flash */
550 #define PLATFORM_DEVID_NORN25Q128A13ESF40F 0xBA18       /**< 16MB, 3.3v NOR Flash */
551 #define PLATFORM_DEVID_NORN25Q032A      0xBB16          /**< 4MB NOR Flash */
552 #define    PLATFORM_DEVID_EEPROM50              0x50            /**< EEPROM @ slave address 0x50  */
553 #define    PLATFORM_DEVID_EEPROM51              0x51            /**< EEPROM @ slave address 0x51  */
554 #define    PLATFORM_DEVID_EMMC                   0xFF00         /**< eMMC device Id  */
555 #define    PLATFORM_DEVID_SD                 0xFF01             /**< Micro SD device Id  */
556 #define PLATFORM_DEVID_QSPIFLASH_S25FL512S 0x0220   /**< QSPI flash device Id (0x220 - 512Mb), manufacture Id (0x01) */
558 /**
559  * @brief Indicates the type of device
560  *
561  */
562 typedef enum {
563     PLATFORM_DEVICE_NAND,
564     /**<NAND Flash*/
565     PLATFORM_DEVICE_NOR,
566     /**<NOR Flash*/
567     PLATFORM_DEVICE_EEPROM,
568     /**<EEPROM */
569 #ifdef DEVICE_K2G
570     PLATFORM_DEVICE_SD,
571     /**<SD Card*/
572     PLATFORM_DEVICE_EMMC,
573     /**<eMMC Card*/
574     PLATFORM_DEVICE_QSPI_FLASH,
575     /**<QSPI flash */
576 #endif
577     PLATFORM_DEVICE_MAX
578     /**<End of devices*/
579 } PLATFORM_DEVICE_TYPE;
581 /**
582  *  @brief      This type defines the opaque handle returned to a device that is opened.
583  *              The handle must be used in all subsequent operations.
584  *
585  */
586 typedef uint32_t PLATFORM_DEVHANDLE;
588 /**
589  *  @brief This structure contains information about the flash device on the platform
590  *
591  *                      The bblist points to an array of bytes where each position represents a
592  *                      block on the device. If the block is good it is marked as 0xFF. If the block
593  *                      is bad, it is marked as 0x00. For devices that do not support a bad block list this
594  *                      value will be NULL. The number of blocks in the bblist is determined by the block_count field.
595  */
596 typedef struct {
597     int32_t manufacturer_id;            /**<manufacturer ID*/
598     int32_t device_id;                          /**<Manufacturers device ID*/
599     PLATFORM_DEVICE_TYPE  type;         /**<Type of device */
600     int32_t width;                                      /**<Width in bits*/
601     int32_t block_count;                        /**<Total blocks. First block starts at 0. */
602     int32_t page_count;                         /**<Page count per block*/
603     int32_t page_size;                          /**<Number of bytes in a page including spare area*/
604     int32_t spare_size;                         /**<Spare area size in bytes*/
605     PLATFORM_DEVHANDLE handle;          /**<Handle to the block device as returned by Open. Handle is Opaque, do not interpret or modify */
606     int32_t     bboffset;                               /**<Offset into spare area to check for a bad block */
607         uint32_t column;                                /**<Column for a NAND device */
608         uint32_t flags;                                 /**<Flags is a copy of the flags that were used to open the device */
609         void    *internal;                              /**<Do not use. Used internally by the platform library */
610     uint8_t *bblist;                            /** <Bad Block list or NULL if device does not support one  */
611 } PLATFORM_DEVICE_info;
613 #ifdef DEVICE_K2G
615 /**
616  * @brief UART port Id
617  */
618 typedef enum {
619     PLATFORM_UART_PORT_0,
620     /** < UART port 0 */
621     PLATFORM_UART_PORT_1,
622     /** < UART port 1 */
623     PLATFORM_UART_PORT_2
624     /** < UART port 2 */
625 } UART_PORT;
627 /**
628  * @brief Options to eMMC/uSD card bus width
629  */
630 typedef enum {
631     PLATFORM_MMCSD_BUS_1BIT,
632     /**< MMC/SD bus width 1-bit */
633     PLATFORM_MMCSD_BUS_4BIT,
634     /**< MMC/SD bus width 4-bit */
635     PLATFORM_MMCSD_BUS_8BIT
636     /**< MMC/SD bus width 8-bit */
637 } PLATFORM_MMCSD_BUS_WIDTH;
639 /**
640  * @brief Options to set qspi flash read/write access mode
641  */
642 typedef enum {
643     PLATFORM_QSPI_IO_MODE_SINGLE,
644     /**< QSPI flash read/write access on single I/O line */
645     PLATFORM_QSPI_IO_MODE_DUAL,
646     /**< QSPI flash read/write access on two I/O lines */
647     PLATFORM_QSPI_IO_MODE_QUAD
648     /**< QSPI flash read/write access on four I/O lines */
649 } PLATFORM_QSPI_IO_MODE;
651 /**
652  * @brief UART parameters
653  */
654 typedef struct
656         uint8_t uart_port;
657 } PLATFORM_UART_Params;
659 /**
660  * @brief QSPI flash parameters
661  */
662 typedef struct
664         uint8_t read_mode;
665         uint8_t write_mode;
666 } PLATFORM_QSPI_Params;
668 /**
669  * @brief Define how platform_read should behave.
670  *    These write types can be set in the init structure
671  */
672 typedef enum {
673     PLATFORM_READ_UART,
674     /** <Read from the UART */
675     PLATFORM_READ_SCANF
676     /** <Read from scanf -- CCS console */
677 } READ_info;
679 #endif /* #ifdef DEVICE_K2G */
681 /**
682  *  @brief       Opens a device for use
683  *
684  *  @param[in]   deviceid               Device to open
685  *
686  *      @param[in]       flags                  Various flags
687  *
688  *  @retval      NULL or a pointer to the File Handle if successful.
689  *
690  *  @remark
691  *               On success a handle is returned in p_devinfo which should be used in
692  *                               all subsequent calls. As of now, the devices are not virtualized and only
693  *                               one open may exist at a time for a particular device.
694  *
695  *                               If NULL is returned paltform_errno should be set to indicate why the
696  *                               open was un-successful.
697  *
698  *                               Flag Usage: (Currently none defined, use 0)
699  */
701 PLATFORM_DEVICE_info *platform_device_open(uint32_t deviceid, uint32_t flags);
703 /**
704  *  @brief       Closes the device
705  *
706  *  @param[in]   handle  Handle to the device as returned in the open call.
707  *
708  *  @retval      Platform_EOK on Success
709  *
710  */
712 Platform_STATUS platform_device_close (PLATFORM_DEVHANDLE handle);
715 /**
716  *  @brief      Write the data to the device
717  *
718  *  @param[in]  handle  Handle to the device as returned by open
719  *
720  *  @param[in]  offset          Offset to start writing the data at.
721  *
722  *  @param[in]  buf          Pointer to  data to write
723  *
724  *  @param[in]  len          Length of the data pointed to by buf
725  *
726  *  @retval     Platform_EOK on Success
727  *
728  *  @remark             For NAND devices use the platform_blocknpage_to_offset call.
729  *
730  *
731  */
732 Platform_STATUS platform_device_write(PLATFORM_DEVHANDLE        handle,
733                                                                          uint32_t       offset,
734                                      uint8_t    *buf,
735                                      uint32_t   len);
737 /**
738  *  @brief      Convert the block and page number to offset
739  *
740  *  @param[in]  handle  Handle to the device as returned by open
741  *
742  *  @param[in]  offset          Offset to start writing the data at.
743  *
744  *  @param[in]  block       Block number
745  *
746  *  @param[in]  page        Page number
747  *
748  *  @retval     Platform_EOK on Success
749  *
750  *
751  */
752 Platform_STATUS platform_blocknpage_to_offset(PLATFORM_DEVHANDLE        handle,
753                                                                          uint32_t       *offset,
754                                      uint32_t   block,
755                                      uint32_t   page);
758 /**
759  *  @brief      Convert the offset to block and page number
760  *
761  *  @param[in]  handle  Handle to the device as returned by open
762  *
763  *  @param[in]  offset          Offset to start writing the data at.
764  *
765  *  @param[in]  block       Pointer to the block number
766  *
767  *  @param[in]  page        Pointer to the Page number
768  *
769  *  @retval     Platform_EOK on Success
770  *
771  *
772  */
773 Platform_STATUS platform_offset_to_blocknpage(PLATFORM_DEVHANDLE handle,
774                                                                          uint32_t       offset,
775                                      uint32_t   *block,
776                                      uint32_t   *page);
778 /**
779  *  @brief       Reads a page from the device
780  *
781  *  @param[in]   handle  Flash device handle from the open
782  *
783  *  @param[in]   offset Offset to start the read from
784  *
785  *  @param[in]   buf    Pointer to a buffer to read the data into
786  *
787  *  @param[in]  len     Amount of data to read
788  *
789  *  @retval      Platform_EOK on Success
790  *
791  *  @remark      The buffer size should be page_size + spare_size
792  *               The application should not write into the spare area
793  *
794  *               For NAND devices use the platform_offset_to_blocknpage call.
795  *
796  *  errno        This routine may set platform_errno to
797  *               the following values on an error (see below for explanation):
798  *               PLATFORM_ERRNO_ECC_FAIL
799  */
802 Platform_STATUS platform_device_read(PLATFORM_DEVHANDLE         handle,
803                                                                          uint32_t       offset,
804                                      uint8_t    *buf,
805                                      uint32_t   len);
807 /**
808  *  @brief       Reads spare data from the flash device
809  *
810  *  @param[in]   handle  Flash device handle from the open
811  *
812  *  @param[in]   block_number Block ID to read from
813  *
814  *  @param[in]   page_number  Page to read the spare area from
815  *
816  *  @param[in]   buf          Pointer to message data
817  *
818  *  @retval      Platform_EOK on Success
819  *
820  *  @remark      The buffer size should be spare_size.
821  */
823 Platform_STATUS platform_device_read_spare_data(PLATFORM_DEVHANDLE handle,
824                                                                                                 uint32_t block_number,
825                                                                                                 uint32_t page_number,
826                                                                                                 uint8_t *buf);
829 /**
830  *  @brief       Marks the block bad
831  *
832  *  @param[in]   handle  Handle from the open
833  *
834  *  @param[in]   block_number Block to write the spare area for
835  *
836  *
837  *  @retval      Platform_EOK on Success
838  *
839  *  @remark      This API can be specifically used to mark a block to be bad
840  *               when there is read error due to the ECC failure.
841  *               The bad block mark byte is indexed by the bboffset. The application should
842  *               only overwirte the bad block mark byte in the spare area
843  *               data when marking a block bad.
844  *
845  */
847 Platform_STATUS platform_device_mark_block_bad (PLATFORM_DEVHANDLE handle,
848                                                 uint32_t block_number);
850 /**
851  *  @brief       Writes spare data to the flash device
852  *
853  *  @param[in]   handle  Handle from the open
854  *
855  *  @param[in]   block_number Block to write the spare area for
856  *
857  *  @param[in]   page_number  Page to write the spare area for
858  *
859  *  @param[in]   buf          Pointer to spare area data to write
860  *
861  *  @retval      Platform_EOK on Success
862  *
863  *  @remark      This API can be used to mark a block to be bad when there
864  *               is read error due to the ECC failure. The bad block mark
865  *               byte is indexed by the bboffset. The application should
866  *               only overwirte the bad block mark byte in the spare area
867  *               data when marking a block bad.
868  *
869  *               The buffer size should be spare_size. This function
870  *                               should ONLY be used when you know what you are doing
871  *                               and have a specific purpose in mind. Incorrectly
872  *                               changing the spare area of a block may lead to
873  *                               unpredictable results or render it not useable.
874  */
876 Platform_STATUS platform_device_write_spare_data(PLATFORM_DEVHANDLE handle,
877                                                 uint32_t block_number,
878                                                                                                 uint32_t page_number,
879                                                                                                 uint8_t *buf);
881 /**
882  *  @brief       erase a block on the flash block
883  *
884  *  @param[in]   handle  Flash device handle from the open
885  *
886  *  @param[in]   block_number Block ID to erase
887  *
888  *  @retval      Platform_EOK on Success
889  *
890  */
892 Platform_STATUS platform_device_erase_block(PLATFORM_DEVHANDLE handle,
893                                             uint32_t block_number);
896 /*@}*/  /* defgroup */
898 /** @defgroup    UART_functions  UART */
899 /*@{*/
902 /**
903  *  @brief      Initialize the UART.
904  *
905  *  @retval     Platform_EOK on Success
906  *
907  *  @remark     This routine must be called before you read and write to the UART.
908  *                      The default baudrate of 115200 will be set. It can be changed
909  *                      by calling platform_uart_set_baudrate.
910  */
912 Platform_STATUS platform_uart_init(void);
914 #ifdef DEVICE_K2G
915 /**
916  *  @brief      Sets UART parameters
917  *
918  *  UART platform library on K2G supports three HW instances of UART controller
919  *  but platform uart APIs does not provide option choose UART port number.
920  *  Set UART port number using this function and subsequent calls to platform
921  *  uart APIs will use the uart port number set.
922  *
923  *  Currently this API is only to set UART port number, can be extended
924  *  by adding more parameters to 'PLATFORM_UART_Params' if needed.
925  *
926  *  @param[in]  params  UART parameters
927  *                      Use below values to set UART port number
928  *                          PLATFORM_UART_PORT_0
929  *                          PLATFORM_UART_PORT_1
930  *                          PLATFORM_UART_PORT_2
931  *
932  *  @retval     Platform_EOK on Success
933  *
934  */
935 Platform_STATUS platform_uart_set_params(PLATFORM_UART_Params *params);
936 #endif
938 /**
939  *  @brief      Set the baud rate for the UART
940  *
941  *  @param[in]  baudrate Baudrate to use: (2400, 4800, 9600, 19200, 38400, 57600, 115200)
942  *
943  *  @retval     Platform_EOK on Success
944  *
945  */
947 Platform_STATUS platform_uart_set_baudrate(uint32_t baudrate);
949 /**
950  *  @brief      Read a byte from UART
951  *
952  *  @param[in]  buf  Pointer to message data
953  *
954  *  @param[in]  delay Wait time (in micro-seconds)
955  *                    for input FIFO to be non-empty.
956  *                    0 => Wait for ever.
957  *
958  *  @retval     Platform_EOK on Success
959  *
960  */
962 Platform_STATUS platform_uart_read(uint8_t *buf, uint32_t delay);
964 /**
965  *  @brief      Write a character to the UART
966  *
967  *  @param[in]  chr     character to write
968  *
969  *
970  *  @retval     Platform_EOK on Success
971  *
972  */
974 Platform_STATUS platform_uart_write(uint8_t chr);
976 /**
977  *  @brief       Platform Write
978  *
979  *  @param[in]   *fmt    printf style vararg
980  *
981  *  @retval      Nothing (but platform_errno may get set)
982  *
983  *  @remark      This routine will output the printf style string
984  *               to one or both of the UART and/or through a printf
985  *               call (in CCS this is mapped to the console window).
986  *               By default, both are written. This can be controlled
987  *               by setting write_type in the paltform_init structure.
988  *               By default, both the UART and printf outputs are used.
989  *
990  *                               The largest string size you can write is 80 characters.
991  *                               Some checking is performed (on the fmt string only) to be
992  *                               sure it is under that length. Note that expansion could
993  *                               set the string higher and therefore corrupt memory.
994  *
995  *               User platform_write_configure to control where the
996  *               output appears. The call retturns the previous setting.
997  *
998  *                               This call is not intended to be used for serious debugging.
999  *                               Its purpose is light duty writing of messages. It should not
1000  *               be called from an interrupt context as it uses printf when
1001  *                               writing to the console. The following wiki articles are good
1002  *               write ups on printf vs. system_printf vs. real time tracing
1003  *                                http://processors.wiki.ti.com/index.php/Printf_support_in_compiler
1004  *                                http://processors.wiki.ti.com/index.php/Tips_for_using_printf
1005  */
1007 void platform_write(const char *fmt, ...);
1008 WRITE_info platform_write_configure (WRITE_info write_type);
1010 /**
1011  *  \brief    Reads input from scanf or UART or both
1012  *
1013  * This function uses the same configuration as platform_write which is
1014  * set using platform_write_configure()
1015  *
1016  *  \param  data   [OUT] Buffer to store the user input
1017  *  \param  length [IN] Number of bytes to read
1018  *
1019  *  \return   - Number of bytes read successfully
1020  */
1021 uint32_t platform_read(uint8_t *data, uint32_t length);
1023 #ifdef DEVICE_K2G
1024 /**
1025  *  \brief    Connfigures the input source for platform_read
1026  *
1027  *  \param  rdype  [IN] Input source for read
1028  *
1029  *  \return   - Input source for read before applying new configuration
1030  */
1031 READ_info platform_read_configure (READ_info    rdype);
1032 #endif
1034 /*@}*/  /* defgroup */
1036 /**
1037  * ============================================================================
1038  *  @n@b         platform_fpgaWriteConfigReg
1039  *
1040  *  @brief       This function writes to spicified FPGA configuration reg.
1041  *
1042  *  @param[in]   uchAddress  The FPGA offset address that you want to write
1043  *
1044  *  @param[in]   uchValue    The value you want to write
1045  *
1046  *  @retval      0 on Success
1047  *
1048  *  @remark      Please refer to the specific EVM technical reference manual for a full list of FPGA register offset address.
1049  *  @verbatim
1050             uint8_t uchValue = 0;
1051                 uint8_t uchAdd   = (0x08);
1053             ret = platform_fpgaWriteConfigReg(uchAdd, uchValue);
1055  *  @return      None
1056  * =============================================================================
1057  */
1058 uint32_t platform_fpgaWriteConfigReg(uint8_t uchAddress, uint8_t uchValue);
1061 /**
1062  * ============================================================================
1063  *  @n@b platform_fpgaReadConfigReg
1064  *
1065  *  @brief       This function reads spicified FPGA configuration reg.
1066  *
1067  *  @param[in]   uchAddress  The FPGA offset address that you want to read
1068  *
1069  *  @param[in]   uchValue    The pointer to store the read value
1070  *
1071  *  @retval      0 on Success
1072  *
1073  *  @remark      Please refer to the specific EVM technical reference manual for a full list of FPGA register offset address.
1074  *  @verbatim
1075             uint8_t uchValue = 0;
1076                 uint8_t uchAdd   = (0x08);
1078             ret = platform_fpgaReadConfigReg(uchAdd, &uchValue);
1079  *  @return      None
1080  * =============================================================================
1081  */
1082 uint32_t platform_fpgaReadConfigReg(uint8_t uchAddress, uint8_t *puchValue);
1087 /** @defgroup    Utility_functions  Utility Functions */
1088 /*@{*/
1090 /** LED operation
1091 */
1092 typedef enum {
1094     /** Turn off LED
1095     */
1096     PLATFORM_LED_OFF = 0,
1098     /** Turn on LED
1099     */
1100     PLATFORM_LED_ON = 1
1102 } PLATFORM_LED_OP;
1104 /**
1105  *  @brief       Perform LED operation
1106  *
1107  *  @param[in]   led_id    LED ID
1108  *
1109  *  @param[in]   operation LED operation
1110  *
1111  *  @param[in]   led_class LED Class
1112  *
1113  *  @retval     Platform_EOK on Success
1114  *
1115  */
1117 Platform_STATUS platform_led(uint32_t led_id, PLATFORM_LED_OP operation, LED_CLASS_E led_class);
1119 /**
1120  *  @brief       Get user switch state
1121  *
1122  *  @param[in]   switch_id    Switch ID
1123  *
1124  *  @retval     returns switch state (0 or 1)
1125  *
1126  */
1128 uint32_t platform_get_switch_state(uint32_t id);
1130 /**
1131  *  @brief       Delay function. The call to this function returns after
1132  *               specified amount of time.
1133  *
1134  *  @param[in]   usecs Delay value in micro-seconds
1135  *
1136  *  @retval      Platform_EOK on Success
1137  *
1138  */
1140 Platform_STATUS platform_delay(uint32_t usecs);
1142 /**
1143  *  @brief       Delay function. The call to this function returns after
1144  *               specified amount of time. It uses the TSCL where 1 TCSL
1145  *               tick is 1 cycle.
1146  *
1147  *  @param[in]   cycles Delay value in clock cycles
1148  *
1149  *  @retval      None
1150  *
1151  */
1153 void platform_delaycycles(uint32_t cycles);
1155 /*@}*/  /* defgroup */
1157 /** @defgroup    OSAL_functions  OSAL Functions
1158 * These routines are called from Platform Library and must be implemented by the Application.
1159 */
1160 /*@{*/
1162 /**
1163  * ============================================================================
1164  *  @n@b Osal_platformMalloc
1165  *
1166  *  @b  brief
1167  *  @n  This API is used by platform_library to allocate memory. Applications
1168  *      must provide this function and attach it to their memory allocator.
1169  *
1170  *  @param[in]  num_bytes
1171  *      Number of bytes to be allocated.
1172  *  @param[in]  alignment
1173  *      byte alignment needed
1174  *
1175  *  @return
1176  *      Allocated block address
1177  * =============================================================================
1178  */
1179 uint8_t *Osal_platformMalloc (uint32_t num_bytes, uint32_t alignment);
1182 /**
1183  * ============================================================================
1184  *  @n@b Osal_platformFree
1185  *
1186  *  @b  brief
1187  *  @n  Frees up memory allocated using
1188  *      @a Osal_platformMalloc ()
1189  *
1190  *              Applications must provide this function and attach it to ther memory
1191  *              free handler.
1192  *
1193  *  @param[in]  dataPtr
1194  *      Pointer to the memory block to be cleaned up.
1195  *
1196  *  @param[in]  num_bytes
1197  *      Size of the memory block to be cleaned up.
1198  *
1199  *  @return
1200  *      Not Applicable
1201  * =============================================================================
1202  */
1203 void Osal_platformFree (uint8_t *dataPtr, uint32_t num_bytes);
1205 /**
1206  * ============================================================================
1207  *  @n@b Osal_platformSpiCsEnter
1208  *
1209  *  @b  brief
1210  *  @n  This API ensures multi-core and multi-threaded
1211  *      synchronization for the SPI bus.
1212  *
1213  *      This is a BLOCKING API.
1214  *
1215  *
1216  *  @return
1217  *  @n  Handle used to lock critical section
1218  * =============================================================================
1219  */
1220 void Osal_platformSpiCsEnter(void);
1223 /**
1224  * ============================================================================
1225  *  @n@b Osal_platformSpiCsExit
1226  *
1227  *  @b  brief
1228  *  @n  This API needs to be called to exit a previously
1229  *      acquired critical section lock using @a Osal_platformSpiCsEnter ()
1230  *      API. It resets the multi-core and multi-threaded lock,
1231  *      enabling another process/core to grab the SPI bus.
1232  *
1233  *
1234  *  @return     None
1235  * =============================================================================
1236  */
1237 void Osal_platformSpiCsExit (void);
1241 /*@}*/  /* defgroup */
1243 /** @defgroup    Error_handling  Error Handling (Errno values) */
1244 /*@{*/
1246 /**
1247  *  @brief platform_errno variable may be set to a non-zero value when
1248  *         a platform library call returns an error.
1249  *
1250  *      The errno value is not preserved. The calling application must
1251  *       save off the value if the platform function call fails.
1252  */
1253 extern uint32_t platform_errno;
1255 /** Platform errno values */
1257 #define PLATFORM_ERRNO_RESET            0                               /**< No error */
1259 #define PLATFORM_ERRNO_GENERIC          0x00000001
1260 #define PLATFORM_ERRNO_INVALID_ARGUMENT 0x00000002              /**< NULL pointer, argument out of range, etc                                                                   */
1262 #define PLATFORM_ERRNO_PLL_SETUP        0x00000003              /**< Error initializing */
1263 #define PLATFORM_ERRNO_EEPROM           0x00000004              /**< Error initializing */
1264 #define PLATFORM_ERRNO_UART             0x00000005              /**< Error initializing */
1265 #define PLATFORM_ERRNO_LED              0x00000006              /**<  Error initializing        */
1266 #define PLATFORM_ERRNO_I2C              0x00000007              /**<  Error initializing        */
1267 #define PLATFORM_ERRNO_MEMTEST          0x00000008              /**<  Error initializing        */
1268 #define PLATFORM_ERRNO_PHY              0x00000009              /**<  Error initializing        */
1269 #define PLATFORM_ERRNO_NAND             0x0000000a              /**<  Error initializing        */
1270 #define PLATFORM_ERRNO_NOR              0x0000000b              /**<  Generic error in NOR              */
1271 #define PLATFORM_ERRNO_UNSUPPORTED              0x0000000c              /**<  Functionality not supported */
1273 #define PLATFORM_ERRNO_ECC_FAIL                 0x00000010              /**<  The ECC calculation for the page read doesn't match. The application can try re-reading. */
1274 #define PLATFORM_ERRNO_BADFLASHDEV              0x00000011              /**<  The flash routines did no not recognize the flash manufacturer                    */
1275 #define PLATFORM_ERRNO_FLASHADDR                0x00000012              /**<  The block or page number specified does not exist for the Flash                   */
1276 #define PLATFORM_ERRNO_NANDBBT                  0x00000013              /**<  Could not update the NAND Bad Block Table                                                         */
1277 #define PLATFORM_ERRNO_NORADDR          0x00000014              /**<  Address for NOR does not exist                                                                                    */
1278 #define PLATFORM_ERRNO_NOFREEBLOCKS     0x00000015              /**<  There were not enough consecutive free blocks to write the data (based on your starting block number)*/
1280 #define PLATFORM_ERRNO_DEV_TIMEOUT              0x00000020              /**<  There was an idle timeout waiting on a device action                                      */
1281 #define PLATFORM_ERRNO_DEV_NAK                  0x00000021              /**<  The device NAK'd the command                                                                                              */
1282 #define PLATFORM_ERRNO_DEV_BUSY                 0x00000022              /**<  The device reported a busy state and could not complete the operation     */
1283 #define PLATFORM_ERRNO_DEV_FAIL                 0x00000023              /**<  Device returned a failed status                                                                                   */
1284 #define PLATFORM_ERRNO_PSCMOD_ENABLE    0x00000024              /**<  Unable to enable the PSC Module                                                                                   */
1286 #define PLATFORM_ERRNO_OOM                              0x00000030              /**<  Out of memory.. tried to allocate RAM but could not.                                              */
1288 #define PLATFORM_ERRNO_READTO                   0x00000040              /**<  UART read timeout                                                                                                                 */
1290 #define PLATFORM_ERRNO_AUDIO                    0x00000050              /**<  Generic in Audio module                                                                                   */
1291 #define PLATFORM_ERRNO_AUDIO_INIT           0x00000051          /**<  Error in Audio module initialization                                                                          */
1292 #define PLATFORM_ERRNO_AUDIO_CFG                0x00000052              /**<  Error in Audio module configuration                                                                           */
1293 #define PLATFORM_ERRNO_AUDIO_STATUS         0x00000053          /**<  Error in readig Audio module status                                                                           */
1295 /*@}*/  /* defgroup */
1297 /** @defgroup  Platform_common  Common */
1298 /*@{*/
1300 /**
1301  *  @brief Platform PLL init sequence return code
1302  *
1303  *  @remark This might be deprecated in future release of platform library
1304  */
1306 extern uint32_t platform_init_return_code;
1308 /*@}*/  /* defgroup */
1310 #ifdef DEVICE_K2G
1311 /** @defgroup  k2g Platform Specific function */
1312 /*@{*/
1314 /**
1315  *  @brief       Prints MMC/SD card information
1316  *
1317  *  @param[in]   handle  Flash device handle from the open
1318  *
1319  *  @retval      Platform_EOK on Success
1320  *
1321  */
1322 Platform_STATUS platform_device_print_info(PLATFORM_DEVHANDLE   handle);
1324 /**
1325  *  @brief       Configures MMC/SD card speed
1326  *
1327  *  @param[in]   handle  Flash device handle from the open
1328  *
1329  *  @param[in]   speed   Device speed value to set
1330  *
1331  *  @retval      Platform_EOK on Success
1332  *
1333  */
1334 Platform_STATUS platform_device_set_speed(PLATFORM_DEVHANDLE    deviceid,
1335                                           uint32_t speed);
1337 /**
1338  *  @brief       Configures MMC/SD bus width
1339  *
1340  *  @param[in]   handle  Flash device handle from the open
1341  *
1342  *  @param[in]   width   Bus width
1343  *
1344  *  @retval      Platform_EOK on Success
1345  *
1346  */
1347 Platform_STATUS platform_device_set_bus_width(PLATFORM_DEVHANDLE        deviceid,
1348                                                       PLATFORM_MMCSD_BUS_WIDTH  width);
1350 /**
1351  *  @brief      Sets flash device parameters
1352  *
1353  *  Function to set configuration parameters for different flash devices
1354  *  supported by the platform library.
1355  *
1356  *  This API is intended to be extended for different devices and flexible to
1357  *  to add new members to the supported device parameter structures.
1358  *  For better portability and extendability, it is recommended that any
1359  *  implementation in this API shall access the individual members of the
1360  *  device parameter structure and avoid any memory operations that will be
1361  *  done on the structure as a whole.
1362  *
1363  *  Devices supported by this API and parameters structure are listed below
1364  *  QSPI flash - PLATFORM_QSPI_Params
1365  *               By default platform library sets Read and write IO modes
1366  *               of QSPI flash to 'quad mode' which cab be modified using
1367  *               this structure.
1368  *
1369  *  @param[in]  handle  Flash device handle from the open
1370  *
1371  *  @param[in]  params  Pointer to parameter structure
1372  *
1373  *  @retval     Platform_EOK on Success
1374  *
1375  */
1376 Platform_STATUS platform_device_set_params(PLATFORM_DEVHANDLE deviceid, void *params);
1378 /*@}*/  /* defgroup */
1380 #endif  /* #ifdef DEVICE_K2G */
1382 #endif