mbed_wait_api.h

00001 
00002 /** \addtogroup platform */
00003 /** @{*/
00004 /**
00005  * \defgroup platform_wait_api wait_api functions
00006  * @{
00007  */
00008 
00009 /* mbed Microcontroller Library
00010  * Copyright (c) 2006-2013 ARM Limited
00011  * SPDX-License-Identifier: Apache-2.0
00012  *
00013  * Licensed under the Apache License, Version 2.0 (the "License");
00014  * you may not use this file except in compliance with the License.
00015  * You may obtain a copy of the License at
00016  *
00017  *     http://www.apache.org/licenses/LICENSE-2.0
00018  *
00019  * Unless required by applicable law or agreed to in writing, software
00020  * distributed under the License is distributed on an "AS IS" BASIS,
00021  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00022  * See the License for the specific language governing permissions and
00023  * limitations under the License.
00024  */
00025 #ifndef MBED_WAIT_API_H
00026 #define MBED_WAIT_API_H
00027 
00028 #ifdef __cplusplus
00029 extern "C" {
00030 #endif
00031 
00032 /** Generic wait functions.
00033  *
00034  * These provide simple NOP type wait capabilities.
00035  *
00036  * Example:
00037  * @code
00038  * #include "mbed.h"
00039  *
00040  * DigitalOut heartbeat(LED1);
00041  *
00042  * int main() {
00043  *     while (1) {
00044  *         heartbeat = 1;
00045  *         wait(0.5);
00046  *         heartbeat = 0;
00047  *         wait(0.5);
00048  *     }
00049  * }
00050  * @endcode
00051  */
00052 
00053 /** Waits for a number of seconds, with microsecond resolution (within
00054  *  the accuracy of single precision floating point).
00055  *
00056  *  @param s number of seconds to wait
00057  *
00058  *  @note
00059  *    If the RTOS is present, this function spins to get the exact number of microseconds for
00060  *    microsecond precision up to 10 milliseconds. If delay is larger than 10 milliseconds and not in ISR, it is the same as
00061  *    `wait_ms`. We recommend `wait_us` and `wait_ms` over `wait`.
00062  */
00063 void wait(float s);
00064 
00065 /** Waits a number of milliseconds.
00066  *
00067  *  @param ms the whole number of milliseconds to wait
00068  *
00069  *  @note
00070  *    If the RTOS is present, it calls ThisThread::sleep_for(), which is same as CMSIS osDelay().
00071  *    You can't call this from interrupts, and it doesn't lock hardware sleep.
00072  */
00073 void wait_ms(int ms);
00074 
00075 /** Waits a number of microseconds.
00076  *
00077  *  @param us the whole number of microseconds to wait
00078  *
00079  *  @note
00080  *    This function always spins to get the exact number of microseconds.
00081  *    If RTOS is present, this will affect power (by preventing deep sleep) and
00082  *    multithread performance. Therefore, spinning for millisecond wait is not recommended.
00083  */
00084 void wait_us(int us);
00085 
00086 #ifdef __cplusplus
00087 }
00088 #endif
00089 
00090 #endif
00091 
00092 /** @}*/
00093 /** @}*/