mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_ARM_BEETLE_SOC/TOOLCHAIN_ARM_STD/hpal_blep.h@171:3a7713b1edbc, 2018-11-08 (annotated)

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
mbed library. Release version 164

Who changed what in which revision?

UserRevisionLine numberNew contents of line
AnnaBridge 171:3a7713b1edbc 1 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 2 /*!
AnnaBridge 171:3a7713b1edbc 3 * \file hpal_blep.h
AnnaBridge 171:3a7713b1edbc 4 *
AnnaBridge 171:3a7713b1edbc 5 * \brief HPAL BLEP initialization.
AnnaBridge 171:3a7713b1edbc 6 *
AnnaBridge 171:3a7713b1edbc 7 * \internal
AnnaBridge 171:3a7713b1edbc 8
AnnaBridge 171:3a7713b1edbc 9 * __LICENSE__
AnnaBridge 171:3a7713b1edbc 10 *
AnnaBridge 171:3a7713b1edbc 11 * Copyright (c) 2015 ARM, Ltd., all rights reserved.
AnnaBridge 171:3a7713b1edbc 12 * ARM confidential and proprietary.
AnnaBridge 171:3a7713b1edbc 13 *
AnnaBridge 171:3a7713b1edbc 14 * IMPORTANT. Your use of this file is governed by a Software License Agreement
AnnaBridge 171:3a7713b1edbc 15 * ("Agreement") that must be accepted in order to download or otherwise receive a
AnnaBridge 171:3a7713b1edbc 16 * copy of this file. You may not use or copy this file for any purpose other than
AnnaBridge 171:3a7713b1edbc 17 * as described in the Agreement. If you do not agree to all of the terms of the
AnnaBridge 171:3a7713b1edbc 18 * Agreement do not use this file and delete all copies in your possession or control;
AnnaBridge 171:3a7713b1edbc 19 * if you do not have a copy of the Agreement, you must contact ARM, Ltd. prior
AnnaBridge 171:3a7713b1edbc 20 * to any use, copying or further distribution of this software.
AnnaBridge 171:3a7713b1edbc 21
AnnaBridge 171:3a7713b1edbc 22 * \endinternal
AnnaBridge 171:3a7713b1edbc 23 *
AnnaBridge 171:3a7713b1edbc 24 * __USAGE NOTE__
AnnaBridge 171:3a7713b1edbc 25 *
AnnaBridge 171:3a7713b1edbc 26 * main() will usually start Cordio initialization:
AnnaBridge 171:3a7713b1edbc 27 *
AnnaBridge 171:3a7713b1edbc 28 * \code
AnnaBridge 171:3a7713b1edbc 29 *
AnnaBridge 171:3a7713b1edbc 30 * int main()
AnnaBridge 171:3a7713b1edbc 31 * {
AnnaBridge 171:3a7713b1edbc 32 * wsfHandlerId_t handlerId;
AnnaBridge 171:3a7713b1edbc 33 *
AnnaBridge 171:3a7713b1edbc 34 * // ... initialize platform ...
AnnaBridge 171:3a7713b1edbc 35 *
AnnaBridge 171:3a7713b1edbc 36 * handlerId = WsfOsSetNextHandler(HpalBlepHandler);
AnnaBridge 171:3a7713b1edbc 37 * HpalBlepInit(handlerId);
AnnaBridge 171:3a7713b1edbc 38 *
AnnaBridge 171:3a7713b1edbc 39 * // ... add other handlers ...
AnnaBridge 171:3a7713b1edbc 40 *
AnnaBridge 171:3a7713b1edbc 41 * HpalBlepSetStartupCback(mainBlepStartCallback);
AnnaBridge 171:3a7713b1edbc 42 * HpalBlepStart(&myBlobCbacks, (void *)&myContext);
AnnaBridge 171:3a7713b1edbc 43 *
AnnaBridge 171:3a7713b1edbc 44 * // ... dispatcher loop ...
AnnaBridge 171:3a7713b1edbc 45 *
AnnaBridge 171:3a7713b1edbc 46 * }
AnnaBridge 171:3a7713b1edbc 47 *
AnnaBridge 171:3a7713b1edbc 48 * \endcode
AnnaBridge 171:3a7713b1edbc 49 *
AnnaBridge 171:3a7713b1edbc 50 * The startup callback will receive a pass/fail indication after startup complees. The application
AnnaBridge 171:3a7713b1edbc 51 * can then assign callbacks for the HCI interface and "take up" the HCI to begin sending commands
AnnaBridge 171:3a7713b1edbc 52 * and receiving events.
AnnaBridge 171:3a7713b1edbc 53 *
AnnaBridge 171:3a7713b1edbc 54 * \code
AnnaBridge 171:3a7713b1edbc 55 *
AnnaBridge 171:3a7713b1edbc 56 * static void mainBlepStartCallback(bool_t ok)
AnnaBridge 171:3a7713b1edbc 57 * {
AnnaBridge 171:3a7713b1edbc 58 * // ... start BLE stack initialization ...
AnnaBridge 171:3a7713b1edbc 59 *
AnnaBridge 171:3a7713b1edbc 60 * HpalHciSetCbacks(&myHciCbacks);
AnnaBridge 171:3a7713b1edbc 61 * HpalHciTakeUp();
AnnaBridge 171:3a7713b1edbc 62 *
AnnaBridge 171:3a7713b1edbc 63 * // ... more BLE stack initialization ...
AnnaBridge 171:3a7713b1edbc 64 *
AnnaBridge 171:3a7713b1edbc 65 * // ... start using BLE ...
AnnaBridge 171:3a7713b1edbc 66 * }
AnnaBridge 171:3a7713b1edbc 67 *
AnnaBridge 171:3a7713b1edbc 68 * \endcode
AnnaBridge 171:3a7713b1edbc 69 *
AnnaBridge 171:3a7713b1edbc 70 * __STARTUP PROCESS__
AnnaBridge 171:3a7713b1edbc 71 *
AnnaBridge 171:3a7713b1edbc 72 * Setup of the BLEP begins with a @ref STARTUP "VS_Startup event" sent from Cordio.
AnnaBridge 171:3a7713b1edbc 73 * The Startup_Flags parameter indicates whether the currently-executing firmware (here the
AnnaBridge 171:3a7713b1edbc 74 * bootloader) requires a firmware update to perform Bluetooth LE operations if bit 0x02 is set.
AnnaBridge 171:3a7713b1edbc 75 *
AnnaBridge 171:3a7713b1edbc 76 * If firmware must be updated, the firmware should be retrieved from storage, and a description
AnnaBridge 171:3a7713b1edbc 77 * provided to Cordio in a @ref FW_LOAD "VS_Firmware_Load command". The Status and Extended_Status
AnnaBridge 171:3a7713b1edbc 78 * should be checked in the Command_Complete event returned in response. The firmware data should
AnnaBridge 171:3a7713b1edbc 79 * then be supplied with a series of @ref FW_DATA "VS_Firmware_Data commands". Again, from each
AnnaBridge 171:3a7713b1edbc 80 * Command_Complete event returned in response, the Status and Extended_Status should be checked.
AnnaBridge 171:3a7713b1edbc 81 * After the Command_Complete event following the final VS_FW_Data command, Cordio will reset and
AnnaBridge 171:3a7713b1edbc 82 * the new firmware will begin executing. Another @ref STARTUP "VS_Startup event" will be sent
AnnaBridge 171:3a7713b1edbc 83 * from Cordio.
AnnaBridge 171:3a7713b1edbc 84 *
AnnaBridge 171:3a7713b1edbc 85 * The Startup_Flags parameter from the VS_Startup event will also indicate whether Cordio needs
AnnaBridge 171:3a7713b1edbc 86 * a trim update to operate if bit 0x01 is set. If trim must be updated, the trim should be
AnnaBridge 171:3a7713b1edbc 87 * retrieved from storage, and a description provided to Cordio in a @ref TRIM_LOAD "VS_Trim_Load command".
AnnaBridge 171:3a7713b1edbc 88 * The Status and Extended_Status should be checked in the Command_Complete event returned in
AnnaBridge 171:3a7713b1edbc 89 * response. The trim data should then be supplied with a series of @ref TRIM_DATA "VS_Trim_Data commands".
AnnaBridge 171:3a7713b1edbc 90 * Again, from each Command_Complete event returned in response, the Status and Extended_Status
AnnaBridge 171:3a7713b1edbc 91 * should be checked. Multiple trim blobs may be uploaded sequentially.
AnnaBridge 171:3a7713b1edbc 92 *
AnnaBridge 171:3a7713b1edbc 93 * After the firmware update and trim update (if necessary), Cordio should be ready to process
AnnaBridge 171:3a7713b1edbc 94 * standard Bluetooth LE commands. The Startup_Flags from the last VS_Startup event should
AnnaBridge 171:3a7713b1edbc 95 * confirm this by setting bit 0x04.
AnnaBridge 171:3a7713b1edbc 96 *
AnnaBridge 171:3a7713b1edbc 97 * \dot
AnnaBridge 171:3a7713b1edbc 98 * digraph G {
AnnaBridge 171:3a7713b1edbc 99 * node [shape="oval", color="darkorange", width=2, height=0.6, fixedsize=true];
AnnaBridge 171:3a7713b1edbc 100 * edge [color="darkorange"];
AnnaBridge 171:3a7713b1edbc 101 *
AnnaBridge 171:3a7713b1edbc 102 * WAIT_FOR_STARTUP [label="Wait for STARTUP\n from bootloader"];
AnnaBridge 171:3a7713b1edbc 103 * START_FW_LOAD [label="Start firmware load"];
AnnaBridge 171:3a7713b1edbc 104 * DO_FW_LOAD [label="Load firmware"];
AnnaBridge 171:3a7713b1edbc 105 * WAIT_FOR_FW_STARTUP [label="Wait for STARTUP\n from firmware"];
AnnaBridge 171:3a7713b1edbc 106 * START_TRIM_LOAD [label="Start trim load"];
AnnaBridge 171:3a7713b1edbc 107 * DO_TRIM_LOAD [label="Load a trim blob"];
AnnaBridge 171:3a7713b1edbc 108 * DONE_FAILURE [label="Done with error"];
AnnaBridge 171:3a7713b1edbc 109 * DONE_SUCCESS [label="Done with success"];
AnnaBridge 171:3a7713b1edbc 110 *
AnnaBridge 171:3a7713b1edbc 111 * WAIT_FOR_STARTUP -> START_FW_LOAD;
AnnaBridge 171:3a7713b1edbc 112 *
AnnaBridge 171:3a7713b1edbc 113 * START_FW_LOAD -> START_TRIM_LOAD [label="doesn't\n need fw"];
AnnaBridge 171:3a7713b1edbc 114 * START_FW_LOAD -> DO_FW_LOAD;
AnnaBridge 171:3a7713b1edbc 115 * DO_FW_LOAD -> DO_FW_LOAD [label="more data"];
AnnaBridge 171:3a7713b1edbc 116 * DO_FW_LOAD -> WAIT_FOR_FW_STARTUP [label="no more\n data"];
AnnaBridge 171:3a7713b1edbc 117 *
AnnaBridge 171:3a7713b1edbc 118 * WAIT_FOR_FW_STARTUP -> START_TRIM_LOAD;
AnnaBridge 171:3a7713b1edbc 119 *
AnnaBridge 171:3a7713b1edbc 120 * START_TRIM_LOAD -> DONE_SUCCESS [label="doesn't\n need trim"];
AnnaBridge 171:3a7713b1edbc 121 * START_TRIM_LOAD -> DO_TRIM_LOAD [label="another\n trim blob"];
AnnaBridge 171:3a7713b1edbc 122 * START_TRIM_LOAD -> DONE_SUCCESS [label="no more\n trim blobs"];
AnnaBridge 171:3a7713b1edbc 123 * DO_TRIM_LOAD -> DO_TRIM_LOAD [label="more data"];
AnnaBridge 171:3a7713b1edbc 124 * DO_TRIM_LOAD -> START_TRIM_LOAD [label="no more\n data"];
AnnaBridge 171:3a7713b1edbc 125 *
AnnaBridge 171:3a7713b1edbc 126 * WAIT_FOR_STARTUP -> DONE_FAILURE [label="timeout\n or error"];
AnnaBridge 171:3a7713b1edbc 127 * START_FW_LOAD -> DONE_FAILURE [label="timeout\n or error"];
AnnaBridge 171:3a7713b1edbc 128 * DO_FW_LOAD -> DONE_FAILURE [label="timeout\n or error"];
AnnaBridge 171:3a7713b1edbc 129 * WAIT_FOR_FW_STARTUP -> DONE_FAILURE [label="timeout\n or error"];
AnnaBridge 171:3a7713b1edbc 130 * START_TRIM_LOAD -> DONE_FAILURE [label="timeout\n or error"];
AnnaBridge 171:3a7713b1edbc 131 * DO_TRIM_LOAD -> DONE_FAILURE [label="timeout\n or error"];
AnnaBridge 171:3a7713b1edbc 132 * }
AnnaBridge 171:3a7713b1edbc 133 * \enddot
AnnaBridge 171:3a7713b1edbc 134 */
AnnaBridge 171:3a7713b1edbc 135 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 136
AnnaBridge 171:3a7713b1edbc 137 #ifndef HPAL_BLEP_H
AnnaBridge 171:3a7713b1edbc 138 #define HPAL_BLEP_H
AnnaBridge 171:3a7713b1edbc 139
AnnaBridge 171:3a7713b1edbc 140 #ifdef __cplusplus
AnnaBridge 171:3a7713b1edbc 141 extern "C" {
AnnaBridge 171:3a7713b1edbc 142 #endif
AnnaBridge 171:3a7713b1edbc 143
AnnaBridge 171:3a7713b1edbc 144 #include "cordio_bt4_defs.h"
AnnaBridge 171:3a7713b1edbc 145
AnnaBridge 171:3a7713b1edbc 146 #include "wsf_types.h"
AnnaBridge 171:3a7713b1edbc 147 #include "wsf_os.h"
AnnaBridge 171:3a7713b1edbc 148
AnnaBridge 171:3a7713b1edbc 149 /**************************************************************************************************
AnnaBridge 171:3a7713b1edbc 150 Data Types
AnnaBridge 171:3a7713b1edbc 151 **************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 152
AnnaBridge 171:3a7713b1edbc 153 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 154 /*!
AnnaBridge 171:3a7713b1edbc 155 * \brief Header preceding each blob of data.
AnnaBridge 171:3a7713b1edbc 156 */
AnnaBridge 171:3a7713b1edbc 157 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 158 typedef CordioTc2ImgHdr_t hpalBlepBlobHeader_t;
AnnaBridge 171:3a7713b1edbc 159
AnnaBridge 171:3a7713b1edbc 160 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 161 /*!
AnnaBridge 171:3a7713b1edbc 162 * \brief Callback for BLEP startup status.
AnnaBridge 171:3a7713b1edbc 163 */
AnnaBridge 171:3a7713b1edbc 164 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 165 typedef void (*hpalBlepStartupCback_t)(bool_t ok);
AnnaBridge 171:3a7713b1edbc 166
AnnaBridge 171:3a7713b1edbc 167 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 168 /*!
AnnaBridge 171:3a7713b1edbc 169 * \brief Storage callbacks invoked during startup to read patch and trim data.
AnnaBridge 171:3a7713b1edbc 170 */
AnnaBridge 171:3a7713b1edbc 171 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 172 typedef struct
AnnaBridge 171:3a7713b1edbc 173 {
AnnaBridge 171:3a7713b1edbc 174 /***********************************************************************************************/
AnnaBridge 171:3a7713b1edbc 175 /*!
AnnaBridge 171:3a7713b1edbc 176 * \brief Setup device for reading from beginning of blob storage.
AnnaBridge 171:3a7713b1edbc 177 *
AnnaBridge 171:3a7713b1edbc 178 * \param pContext Context given to HpalBlepStart()
AnnaBridge 171:3a7713b1edbc 179 *
AnnaBridge 171:3a7713b1edbc 180 * \return TRUE if successful
AnnaBridge 171:3a7713b1edbc 181 */
AnnaBridge 171:3a7713b1edbc 182 /***********************************************************************************************/
AnnaBridge 171:3a7713b1edbc 183 bool_t (*StartStorage)(void *pContext);
AnnaBridge 171:3a7713b1edbc 184
AnnaBridge 171:3a7713b1edbc 185 /***********************************************************************************************/
AnnaBridge 171:3a7713b1edbc 186 /*!
AnnaBridge 171:3a7713b1edbc 187 * \brief Storage device is no longer needed, so it can be powered down.
AnnaBridge 171:3a7713b1edbc 188 *
AnnaBridge 171:3a7713b1edbc 189 * \param pContext Context given to HpalBlepStart()
AnnaBridge 171:3a7713b1edbc 190 *
AnnaBridge 171:3a7713b1edbc 191 * \return TRUE if successful
AnnaBridge 171:3a7713b1edbc 192 */
AnnaBridge 171:3a7713b1edbc 193 /***********************************************************************************************/
AnnaBridge 171:3a7713b1edbc 194 bool_t (*EndStorage)(void *pContext);
AnnaBridge 171:3a7713b1edbc 195
AnnaBridge 171:3a7713b1edbc 196 /***********************************************************************************************/
AnnaBridge 171:3a7713b1edbc 197 /*!
AnnaBridge 171:3a7713b1edbc 198 * \brief Read next blob header from storage device.
AnnaBridge 171:3a7713b1edbc 199 *
AnnaBridge 171:3a7713b1edbc 200 * \param pContext Context given to HpalBlepStart()
AnnaBridge 171:3a7713b1edbc 201 * \param pHdr Pointer to structure that will receive header
AnnaBridge 171:3a7713b1edbc 202 *
AnnaBridge 171:3a7713b1edbc 203 * \return TRUE if successful
AnnaBridge 171:3a7713b1edbc 204 */
AnnaBridge 171:3a7713b1edbc 205 /***********************************************************************************************/
AnnaBridge 171:3a7713b1edbc 206 bool_t (*ReadNextBlobHeader)(void *pContext, hpalBlepBlobHeader_t *pHdr);
AnnaBridge 171:3a7713b1edbc 207
AnnaBridge 171:3a7713b1edbc 208 /***********************************************************************************************/
AnnaBridge 171:3a7713b1edbc 209 /*!
AnnaBridge 171:3a7713b1edbc 210 * \brief Read more data from current blob at current offset. Reading data advances the
AnnaBridge 171:3a7713b1edbc 211 * offset.
AnnaBridge 171:3a7713b1edbc 212 *
AnnaBridge 171:3a7713b1edbc 213 * \param pContext Context given to HpalBlep_Startup()
AnnaBridge 171:3a7713b1edbc 214 * \param pData Storage for data
AnnaBridge 171:3a7713b1edbc 215 * \param length Number of bytes to read
AnnaBridge 171:3a7713b1edbc 216 *
AnnaBridge 171:3a7713b1edbc 217 * \return TRUE if successful
AnnaBridge 171:3a7713b1edbc 218 */
AnnaBridge 171:3a7713b1edbc 219 /***********************************************************************************************/
AnnaBridge 171:3a7713b1edbc 220 bool_t (*ReadMoreBlobData)(void *pContext, uint8_t *pData, uint32_t length);
AnnaBridge 171:3a7713b1edbc 221
AnnaBridge 171:3a7713b1edbc 222 /***********************************************************************************************/
AnnaBridge 171:3a7713b1edbc 223 /*!
AnnaBridge 171:3a7713b1edbc 224 * \brief Advance the offset of the current blob.
AnnaBridge 171:3a7713b1edbc 225 *
AnnaBridge 171:3a7713b1edbc 226 * \param pContext Context given to HpalBlep_Startup()
AnnaBridge 171:3a7713b1edbc 227 * \param length Number of bytes to skip
AnnaBridge 171:3a7713b1edbc 228 *
AnnaBridge 171:3a7713b1edbc 229 * \return TRUE if successful
AnnaBridge 171:3a7713b1edbc 230 */
AnnaBridge 171:3a7713b1edbc 231 /***********************************************************************************************/
AnnaBridge 171:3a7713b1edbc 232 bool_t (*SkipBlobData)(void *pContext, uint32_t length);
AnnaBridge 171:3a7713b1edbc 233 } hpalBlepStorageCbacks_t;
AnnaBridge 171:3a7713b1edbc 234
AnnaBridge 171:3a7713b1edbc 235 /**************************************************************************************************
AnnaBridge 171:3a7713b1edbc 236 Function Declarations
AnnaBridge 171:3a7713b1edbc 237 **************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 238
AnnaBridge 171:3a7713b1edbc 239 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 240 /*!
AnnaBridge 171:3a7713b1edbc 241 * \brief Initialize the BLEP startup.
AnnaBridge 171:3a7713b1edbc 242 *
AnnaBridge 171:3a7713b1edbc 243 * \param handlerId Handler ID for HpalBlepHandler().
AnnaBridge 171:3a7713b1edbc 244 *
AnnaBridge 171:3a7713b1edbc 245 * \return None.
AnnaBridge 171:3a7713b1edbc 246 */
AnnaBridge 171:3a7713b1edbc 247 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 248 void HpalBlepInit(wsfHandlerId_t handlerId);
AnnaBridge 171:3a7713b1edbc 249
AnnaBridge 171:3a7713b1edbc 250 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 251 /*!
AnnaBridge 171:3a7713b1edbc 252 * \brief Begin BLEP startup.
AnnaBridge 171:3a7713b1edbc 253 *
AnnaBridge 171:3a7713b1edbc 254 * \param pCbacks Storage callbacks.
AnnaBridge 171:3a7713b1edbc 255 * \param pCbackContext Storage callback context.
AnnaBridge 171:3a7713b1edbc 256 *
AnnaBridge 171:3a7713b1edbc 257 * \return None.
AnnaBridge 171:3a7713b1edbc 258 */
AnnaBridge 171:3a7713b1edbc 259 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 260 void HpalBlepStart(const hpalBlepStorageCbacks_t *pCbacks, void *pCbackContext);
AnnaBridge 171:3a7713b1edbc 261
AnnaBridge 171:3a7713b1edbc 262 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 263 /*!
AnnaBridge 171:3a7713b1edbc 264 * \brief Set callback that will indicate startup status.
AnnaBridge 171:3a7713b1edbc 265 *
AnnaBridge 171:3a7713b1edbc 266 * \param cback Application callback.
AnnaBridge 171:3a7713b1edbc 267 *
AnnaBridge 171:3a7713b1edbc 268 * \return None.
AnnaBridge 171:3a7713b1edbc 269 */
AnnaBridge 171:3a7713b1edbc 270 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 271 void HpalBlepSetStartupCback(hpalBlepStartupCback_t cback);
AnnaBridge 171:3a7713b1edbc 272
AnnaBridge 171:3a7713b1edbc 273 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 274 /*!
AnnaBridge 171:3a7713b1edbc 275 * \brief Handler for BLEP startup messages.
AnnaBridge 171:3a7713b1edbc 276 *
AnnaBridge 171:3a7713b1edbc 277 * \param event WSF event mask.
AnnaBridge 171:3a7713b1edbc 278 * \param pMsg WSF message.
AnnaBridge 171:3a7713b1edbc 279 *
AnnaBridge 171:3a7713b1edbc 280 * \return None.
AnnaBridge 171:3a7713b1edbc 281 */
AnnaBridge 171:3a7713b1edbc 282 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 283 void HpalBlepHandler(wsfEventMask_t event, wsfMsgHdr_t *pMsg);
AnnaBridge 171:3a7713b1edbc 284
AnnaBridge 171:3a7713b1edbc 285 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 286 /*!
AnnaBridge 171:3a7713b1edbc 287 * @mainpage Host Software Architecture
AnnaBridge 171:3a7713b1edbc 288 *
AnnaBridge 171:3a7713b1edbc 289 * __OVERVIEW__
AnnaBridge 171:3a7713b1edbc 290 *
AnnaBridge 171:3a7713b1edbc 291 * The architecture of a typical host's software can be divided into four basic components: the
AnnaBridge 171:3a7713b1edbc 292 * application, a host BLE stack, an RTOS or bare-metal event framework, and the CORDIO Host
AnnaBridge 171:3a7713b1edbc 293 * Peripheral Access Library (HPAL).
AnnaBridge 171:3a7713b1edbc 294 *
AnnaBridge 171:3a7713b1edbc 295 * The host BLE stack will provide some API, generally proprietary, for managing connections to
AnnaBridge 171:3a7713b1edbc 296 * devices (advertising, scanning, connecting, etc.) and organizing attributes into services and
AnnaBridge 171:3a7713b1edbc 297 * accessing the attribute values.
AnnaBridge 171:3a7713b1edbc 298 *
AnnaBridge 171:3a7713b1edbc 299 * The CORDIO HPAL provides to the stack an interface for writing to the standard Bluetooth Host
AnnaBridge 171:3a7713b1edbc 300 * Controller Interface (HCI) or receiving alerts when new messages have been received, as well as
AnnaBridge 171:3a7713b1edbc 301 * CORDIO-specific startup routines the application (perhaps through the stack) must call before
AnnaBridge 171:3a7713b1edbc 302 * HCI transactions begin. The provided HPAL implementation is independent of host MCU, BLE stack,
AnnaBridge 171:3a7713b1edbc 303 * and any (if any) RTOS. However, the provided startup code does submit and service messages on
AnnaBridge 171:3a7713b1edbc 304 * the WSF event-driven OS framework.
AnnaBridge 171:3a7713b1edbc 305 *
AnnaBridge 171:3a7713b1edbc 306 * \dot
AnnaBridge 171:3a7713b1edbc 307 * graph G {
AnnaBridge 171:3a7713b1edbc 308 * node [shape="polygon", sides=4 color="darkorange", width=2.5 fixedsize=true];
AnnaBridge 171:3a7713b1edbc 309 * edge [color="darkorange"];
AnnaBridge 171:3a7713b1edbc 310 * splines="ortho";
AnnaBridge 171:3a7713b1edbc 311 *
AnnaBridge 171:3a7713b1edbc 312 * subgraph cluster0 {
AnnaBridge 171:3a7713b1edbc 313 * app -- host;
AnnaBridge 171:3a7713b1edbc 314 * host -- hpal [label="HCI messages", color="darkorange"];
AnnaBridge 171:3a7713b1edbc 315 * hpal -- peripheral [label="LLCC Bus", color="darkorange"];
AnnaBridge 171:3a7713b1edbc 316 * color=white;
AnnaBridge 171:3a7713b1edbc 317 * ratio=fill;
AnnaBridge 171:3a7713b1edbc 318 * edge [style="invis"];
AnnaBridge 171:3a7713b1edbc 319 * }
AnnaBridge 171:3a7713b1edbc 320 * rtos -- wsf [constraint=false];
AnnaBridge 171:3a7713b1edbc 321 * app -- wsf [constraint=false];
AnnaBridge 171:3a7713b1edbc 322 * host -- wsf [constraint=false headport="s", tailport="e"];
AnnaBridge 171:3a7713b1edbc 323 * hpal -- wsf [constraint=false headport="s", tailport="e"];
AnnaBridge 171:3a7713b1edbc 324 *
AnnaBridge 171:3a7713b1edbc 325 * app [label="Application Profiles\n or Services"];
AnnaBridge 171:3a7713b1edbc 326 * host [label="Host\n BLE Stack"];
AnnaBridge 171:3a7713b1edbc 327 * hpal [label="CORDIO HPAL"];
AnnaBridge 171:3a7713b1edbc 328 * peripheral [label="CORDIO Peripheral"];
AnnaBridge 171:3a7713b1edbc 329 *
AnnaBridge 171:3a7713b1edbc 330 * rtos [label="RTOS or\n Bare-Metal\n Event Framework", width=1.5 height=1.0];
AnnaBridge 171:3a7713b1edbc 331 * wsf [label="WSF", width=1.5, height=0.5];
AnnaBridge 171:3a7713b1edbc 332 * }
AnnaBridge 171:3a7713b1edbc 333 * \enddot
AnnaBridge 171:3a7713b1edbc 334 *
AnnaBridge 171:3a7713b1edbc 335 * __CORDIO HPAL__
AnnaBridge 171:3a7713b1edbc 336 *
AnnaBridge 171:3a7713b1edbc 337 * The CORDIO peripheral has two operational modes. It enters _statup mode_ after reset, when
AnnaBridge 171:3a7713b1edbc 338 * the host software must load firmware and trim patches. If that sequence is successful, the
AnnaBridge 171:3a7713b1edbc 339 * peripheral will enter _HCI mode_, during which the standard HCI interface expected by the host
AnnaBridge 171:3a7713b1edbc 340 * BLE stack will be alive.
AnnaBridge 171:3a7713b1edbc 341 *
AnnaBridge 171:3a7713b1edbc 342 * The passage from startup to HCI modes is guided by the module _hpal_blep_ and kicked off with
AnnaBridge 171:3a7713b1edbc 343 * a call of the API function \ref HpalBlepStart(). During this process, a series of
AnnaBridge 171:3a7713b1edbc 344 * vendor-specific HCI commands and events are exchanged across the LLCC bus. When startup has
AnnaBridge 171:3a7713b1edbc 345 * completed, the startup callback (set with \ref HpalBlepSetStartupCback()) will return
AnnaBridge 171:3a7713b1edbc 346 * a status indication; in the event of an error, the LLCC bus will be disabled and the HCI
AnnaBridge 171:3a7713b1edbc 347 * interface will be locked to prevent inadvertent access.
AnnaBridge 171:3a7713b1edbc 348 *
AnnaBridge 171:3a7713b1edbc 349 * After a successful startup, the HCI can be accessed directly with the functions in the module
AnnaBridge 171:3a7713b1edbc 350 * _hpal_hci_. Management functions can "take up" (\ref HpalHciTakeUp()) or "take down" (\ref
AnnaBridge 171:3a7713b1edbc 351 * HpalHciTakeDown()) the interface. Writes are performed directly (@\refHpalHci_Write()) and
AnnaBridge 171:3a7713b1edbc 352 * completed reads or writes indicated through callbacks (\ref HpalHciSetCbacks()). A basic
AnnaBridge 171:3a7713b1edbc 353 * logging facility will, optionally, dump packet information or contents to a console for
AnnaBridge 171:3a7713b1edbc 354 * debugging.
AnnaBridge 171:3a7713b1edbc 355 */
AnnaBridge 171:3a7713b1edbc 356 /*************************************************************************************************/
AnnaBridge 171:3a7713b1edbc 357
AnnaBridge 171:3a7713b1edbc 358 #ifdef __cplusplus
AnnaBridge 171:3a7713b1edbc 359 };
AnnaBridge 171:3a7713b1edbc 360 #endif
AnnaBridge 171:3a7713b1edbc 361
AnnaBridge 171:3a7713b1edbc 362 #endif /* HPAL_BLEP_H */