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
655 {
656 uint8_t uart_port;
657 } PLATFORM_UART_Params;
659 /**
660 * @brief QSPI flash parameters
661 */
662 typedef struct
663 {
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