board_api.h

00001 /*
00002  * @brief Common board API functions
00003  *
00004  * @note
00005  * Copyright(C) NXP Semiconductors, 2013
00006  * All rights reserved.
00007  *
00008  * @par
00009  * Software that is described herein is for illustrative purposes only
00010  * which provides customers with programming information regarding the
00011  * LPC products.  This software is supplied "AS IS" without any warranties of
00012  * any kind, and NXP Semiconductors and its licensor disclaim any and
00013  * all warranties, express or implied, including all implied warranties of
00014  * merchantability, fitness for a particular purpose and non-infringement of
00015  * intellectual property rights.  NXP Semiconductors assumes no responsibility
00016  * or liability for the use of the software, conveys no license or rights under any
00017  * patent, copyright, mask work right, or any other intellectual property rights in
00018  * or to any products. NXP Semiconductors reserves the right to make changes
00019  * in the software without notification. NXP Semiconductors also makes no
00020  * representation or warranty that such application will be suitable for the
00021  * specified use without further testing or modification.
00022  *
00023  * @par
00024  * Permission to use, copy, modify, and distribute this software and its
00025  * documentation is hereby granted, under NXP Semiconductors' and its
00026  * licensor's relevant copyrights in the software, without fee, provided that it
00027  * is used in conjunction with NXP Semiconductors microcontrollers.  This
00028  * copyright, permission, and disclaimer notice must appear in all copies of
00029  * this code.
00030  */
00031 
00032 #ifndef __BOARD_API_H_
00033 #define __BOARD_API_H_
00034 
00035 //#include "lpc_types.h"
00036 #include <stdio.h>
00037 
00038 #ifdef __cplusplus
00039 extern "C" {
00040 #endif
00041 
00042 /** @defgroup BOARD_COMMON_API BOARD: Common board functions
00043  * @ingroup BOARD_Common
00044  * This file contains common board definitions that are shared across
00045  * boards and devices. All of these functions do not need to be
00046  * implemented for a specific board, but if they are implemented, they
00047  * should use this API standard.
00048  * @{
00049  */
00050 
00051 /**
00052  * @brief   Setup and initialize hardware prior to call to main()
00053  * @return  None
00054  * @note    Board_SystemInit() is called prior to the application and sets up system
00055  * clocking, memory, and any resources needed prior to the application
00056  * starting.
00057  */
00058 void Board_SystemInit(void);
00059 
00060 /**
00061  * @brief   Setup pin multiplexer per board schematics
00062  * @return  None
00063  * @note    Board_SetupMuxing() should be called from SystemInit() prior to application
00064  * main() is called. So that the PINs are set in proper state.
00065  */
00066 void Board_SetupMuxing(void);
00067 
00068 /**
00069  * @brief   Setup system clocking 
00070  * @return  None
00071  * @note    This sets up board clocking.
00072  */
00073 void Board_SetupClocking(void);
00074 
00075 /**
00076  * @brief   Setup external system memory
00077  * @return  None
00078  * @note    This function is typically called after pin mux setup and clock setup and
00079  * sets up any external memory needed by the system (DRAM, SRAM, etc.). Not all
00080  * boards need this function.
00081  */
00082 void Board_SetupExtMemory(void);
00083 
00084 /**
00085  * @brief   Set up and initialize all required blocks and functions related to the board hardware.
00086  * @return  None
00087  */
00088 void Board_Init(void);
00089 
00090 /**
00091  * @brief   Initializes board UART for output, required for printf redirection
00092  * @return  None
00093  */
00094 void Board_Debug_Init(void);
00095 
00096 /**
00097  * @brief   Sends a single character on the UART, required for printf redirection
00098  * @param   ch  : character to send
00099  * @return  None
00100  */
00101 void Board_UARTPutChar(char ch);
00102 
00103 /**
00104  * @brief   Get a single character from the UART, required for scanf input
00105  * @return  EOF if not character was received, or character value
00106  */
00107 int Board_UARTGetChar(void);
00108 
00109 /**
00110  * @brief   Prints a string to the UART
00111  * @param   str : Terminated string to output
00112  * @return  None
00113  */
00114 void Board_UARTPutSTR(char *str);
00115 
00116 /**
00117  * @brief   Sets the state of a board LED to on or off
00118  * @param   LEDNumber   : LED number to set state for
00119  * @param   State       : true for on, false for off
00120  * @return  None
00121  */
00122 void Board_LED_Set(uint8_t LEDNumber, bool State);
00123 
00124 /**
00125  * @brief   Returns the current state of a board LED
00126  * @param   LEDNumber   : LED number to set state for
00127  * @return  true if the LED is on, otherwise false
00128  */
00129 bool Board_LED_Test(uint8_t LEDNumber);
00130 
00131 /**
00132  * @brief   Toggles the current state of a board LED
00133  * @param   LEDNumber   : LED number to change state for
00134  * @return  None
00135  */
00136 void Board_LED_Toggle(uint8_t LEDNumber);
00137 
00138 /**
00139  * @brief Function prototype for a MS delay function. Board layers or example code may
00140  *        define this function as needed.
00141  */
00142 typedef void (*p_msDelay_func_t)(uint32_t);
00143 
00144 /* The DEBUG* functions are selected based on system configuration.
00145    Code that uses the DEBUG* functions will have their I/O routed to
00146    the UART, semihosting, or nowhere. */
00147 #if defined(DEBUG_ENABLE)
00148 #if defined(DEBUG_SEMIHOSTING)
00149 #define DEBUGINIT()
00150 #define DEBUGOUT(...) printf(__VA_ARGS__)
00151 #define DEBUGSTR(str) printf(str)
00152 #define DEBUGIN() (int) EOF
00153 
00154 #else
00155 #define DEBUGINIT() Board_Debug_Init()
00156 #define DEBUGOUT(...) printf(__VA_ARGS__)
00157 #define DEBUGSTR(str) Board_UARTPutSTR(str)
00158 #define DEBUGIN() Board_UARTGetChar()
00159 #endif /* defined(DEBUG_SEMIHOSTING) */
00160 
00161 #else
00162 #define DEBUGINIT()
00163 #define DEBUGOUT(...)
00164 #define DEBUGSTR(str)
00165 #define DEBUGIN() (int) EOF
00166 #endif /* defined(DEBUG_ENABLE) */
00167 
00168 /**
00169  * @}
00170  */
00171 
00172 #ifdef __cplusplus
00173 }
00174 #endif
00175 
00176 #endif /* __BOARD_API_H_ */