text: /**
   * @file murasaki_platform.hpp
   *
   * @date 2017/11/12
   * @author Seiichi "Suikan" Horie
   * @brief An interface for the applicaiton from murasaki library to main.c
   * @details
   * The resources below are impremented in the murasaki_platform.cpp and serve as glue to the main.c.
   */
  
  #ifndef MURASAKI_PLATFORM_HPP_
  #define MURASAKI_PLATFORM_HPP_
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  #include <stdint.h>
  // Murasaki platform control
  /**
   * @brief Initialize the platform variables.
   * @ingroup MURASAKI_PLATFORM_GROUP
   * @details
   * The murasaki::platform variable is an interface between the application program and HAL / RTOS.
   * To use it correctly, the initialization is needed before any activity of murasaki client.
   *
   * @code
   * void StartDefaultTask(void const * argument)
   * {
   *     InitPlatform();
   *     ExecPlatform();
   * }
   * @endcode
   *
   * This function have to be invoked from the StartDefaultTask() of the main.c only once
   * to initialize the platform variable.
   *
   */
  void InitPlatform();
  
  /**
   * @brief The body of the real application.
   * @ingroup MURASAKI_PLATFORM_GROUP
   * @details
   * The body function of the murasaki application. Usually this function is called from
   * the StartDefaultTask() of the main.c.
   *
   * This function is invoked only once, and never return. See @ref InitPlatform() as calling sample.
   *
   * By default, it toggles LED as sample program.
   * This function can be customized freely.
   */
  void ExecPlatform();
  
  /**
   * @brief Hook for the assert_failure() in main.c
   * @ingroup MURASAKI_PLATFORM_GROUP
   * @param file Name of the source file where assertion happen
   * @param line Number of the line where assertion happen
   * @details
   * This routine provides a custom hook for the assertion inside STM32Cube HAL.
   * All assertion raised in HAL will be redirected here.
   *
   * @code
   * void assert_failed(uint8_t* file, uint32_t line)
   * {
   *     CustomAssertFailed(file, line);
   * }
   * @endcode
   * By default, this routine output a message with location informaiton
   * to the debugger console.
   */
  void CustomAssertFailed(uint8_t* file, uint32_t line);
  
  /**
   * @brief Hook for the default exception handler. Never return.
   * @ingroup MURASAKI_PLATFORM_GROUP
   * @details
   * An entry of the exception. Especialy for the Hard Fault exception.
   * In this function, the Stack pointer just before exception is retrieved
   * and pass as the first parameter of the PrintFaultResult().
   *
   * Note : To print the correct information, this function have to be
   * Jumped in from the exception entry without any data push to the stack.
   * To avoid the pushing extra data to stack or making stack frame,
   * Compile the program without debug information and with certain
   * optimization leve, when you investigate the Hard Fault.
   *
   * For example, the start up code for the Nucleo-L152RE is startup_stml152xe.s.
   * This file is generated by CubeIDE. This file has default handler as like this:
   *
   * @code
   * .section .text.Default_Handler,"ax",%progbits
   *     Default_Handler:
   * Infinite_Loop:
   *     b Infinite_Loop
   * @endcode
   *
   * This code can be modified to call CustomDefaultHanler as like this :
   * @code
   * .global CustomDefaultHandler
   * .section .text.Default_Handler,"ax",%progbits
   * Default_Handler:
   *     bl CustomDefaultHandler
   * Infinite_Loop:
   *     b Infinite_Loop
   * @endcode
   *
   * While it is declared as function prototype, the CustomDefaultHandler is just a label.
   * Do not call from user application.
   */
  void CustomDefaultHandler();
  
  /**
   * @brief Printing out the context information.
   * @param stack_pointer retrieved stack pointer before interrupt / exception.
   * @details
   * Do not call from application. This is murasaki_internal_only.
   *
   */
  void PrintFaultResult(unsigned int * stack_pointer);
  
  /**
   * @brief StackOverflow hook for FreeRTOS
   * @param xTask Task ID which causes stack overflow.
   * @param pcTaskName Name of the task which cuases stack overflow.
   * @fn vApplicationStackOverflowHook
   * @ingroup MURASAKI_PLATFORM_GROUP
   *
   * @details
   * This function will be called from FreeRTOS when some task causes overflow.
   * See TaskStrategy::getStackMinHeadroom() for details.
   *
   * Because this function prototype is declared by system,
   * we don't have prototype in the murasaki_platform.hpp.
   */
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif /* MURASAKI_PLATFORM_HPP_ */
  