added hal_time_ms

This commit is contained in:
Matthias Ringwald 2015-04-23 11:53:31 +02:00
parent ae7b593d36
commit 8c4fd93283

View File

@ -88,7 +88,8 @@ morekeywords={*, timer_source_t, data_source_t, uint32_t, uint16_t, uint8_t, RUN
\color{bkblue}\rule{\barWidth{}}{22cm}
\end{minipage}
\hfill\begin{minipage}[b]{.8\textwidth}\begin{flushright}
{\color{bkblue}VERSION \versionNr{} \\
{\color{bkblue}
% VERSION \versionNr{} \\
\today \\}
\vspace*{7.5cm}
\hfill\includegraphics[width=0.85\textwidth]{picts/bklogo.pdf}
@ -289,7 +290,7 @@ The complete run loop cycle looks like this: first, the callback function of all
Incoming data over the UART, USB, or timer ticks will generate an interrupt and wake up the microcontroller. In order to avoid the situation where a data source becomes ready just before the run loop enters sleep mode, an interrupt-driven data source has to call the \emph{embedded\_trigger} function. The call to \emph{embedded\_trigger} sets an internal flag that is checked in the critical section just before entering sleep mode.
Timers are single shot: a timer will be removed from the timer list before its event handler callback is executed. If you need a periodic timer, you can re-register the same timer source in the callback function, as shown in Listing \ref{PeriodicTimerHandler}. Note that BTstack expects to get called periodically to keep its time, see Section \ref{section:tickAbstraction} for more on the tick hardware abstraction.
Timers are single shot: a timer will be removed from the timer list before its event handler callback is executed. If you need a periodic timer, you can re-register the same timer source in the callback function, as shown in Listing \ref{PeriodicTimerHandler}. Note that BTstack expects to get called periodically to keep its time, see Section \ref{section:timeAbstraction} for more on the tick hardware abstraction.
The Run loop API is provided in Appendix \ref{appendix:api_run_loop}. To enable the use of timers, make sure that you defined HAVE\_TICK in the config file.
@ -1051,17 +1052,46 @@ void handle_gatt_client_event(le_event_t * event){
\section{Porting to Other Platforms}
In this chapter, we highlight the BTstack components that need to be adjusted for different hardware platforms.
\subsection{Tick Hardware Abstraction Layer}
\label{section:tickAbstraction}
BTstack requires a way to learn about passing time. In an embedded configuration, the following functions have to be provided. The \emph{hal\_tick\_init} and the \emph{hal\_tick\_set\_handler} functions will be called during the initialization of the run loop.
\subsection{Time Abstraction Layer}
\label{section:timeAbstraction}
BTstack requires a way to learn about passing time. \emph{run\_loop\_embedded.c} supports to different modes: system ticks or a system clock with millisecond resolution. BTstack's timing requirements are really low as only Bluetooth timeouts in the second range need to be handled.
\subsubsection{Tick Hardware Abstraction}
\label{ssection:tickAbstraction}
If your platform doesn't require a system clock or if you already have a system tick (as it is the default with CMSIS on ARM Cortex devices), you can use that to implement BTstack's time abstraction in \emph{include/btstack/hal\_tick.h>}.
For this, you need to define \emph{HAVE\_TICK} in \emph{btstack-config.h}:
\begin{lstlisting}
#define HAVE_TICK
\end{lstlisting}
Then, you need to implement the functions \emph{hal\_tick\_init} and \emph{hal\_tick\_set\_handler}, which will be called during the initialization of the run loop.
\begin{lstlisting}
\begin{lstlisting}
void hal_tick_init(void);
void hal_tick_set_handler(void (*tick_handler)(void));
int hal_tick_get_tick_period_in_ms(void);
\end{lstlisting}
\end{lstlisting}
After BTstack calls \emph{hal\_tick\_init()} and \emph{hal\_tick\_set\_handler(tick\_handler)}, it expects that the \emph{tick\_handler} gets called every \emph{hal\_tick\_get\_tick\_period\_in\_ms()} ms.
\subsubsection{Time MS Hardware Abstraction}
\label{ssection:timeMSAbstraction}
If your platform already has a system clock or it is more convenient to provide such a clock, you can use the Time MS Hardware Abstraction in \emph{include/btstack/hal\_time\_ms.h}.
For this, you need to define \emph{HAVE\_TICK} in \emph{btstack-config.h}:
\begin{lstlisting}
#define HAVE_TIME_MS
\end{lstlisting}
Then, you need to implement the function \emph{hal\_time\_ms()}, which will be called from BTstack's run loop and when setting a timer for the future. It has to return the time in milliseconds.
\begin{lstlisting}
uint32_t hal_time_ms(void);
\end{lstlisting}
\subsection{Bluetooth Hardware Control API}
\label{section:bt_hw_control}
The Bluetooth hardware control API can provide the HCI layer with a custom initialization script, a vendor-specific baud rate change command, and system power notifications. It is also used to control the power mode of the Bluetooth module, i.e., turning it on/off and putting to sleep. In addition, it provides an error handler \emph{hw\_error} that is called when a Hardware Error is reported by the Bluetooth module. The callback allows for persistent logging or signaling of this failure. \todo{add recipe}
@ -1198,6 +1228,7 @@ When using BTstack in a multi-threaded environment, this assumption has to stay
\begin{tabular*}{\textwidth}{lp{3.5cm}p{8.5cm}}\toprule
Rev & Date & Comments\\
\midrule
1.x & April 3, 2015 & Added Time MS Hardware Abstraction.\\
1.3 & November 6, 2014 & Introducing GATT client and server. Work in progress.\\
1.2 & November 1, 2013 & Explained Secure Simple Pairing in "Pairing of devices".\\
1.1 & August 30, 2013 & Introduced SDP client. Updated Quick Recipe on "Query remote SDP service".\\