utest_scheduler.h

00001 /****************************************************************************
00002  * Copyright (c) 2015, ARM Limited, All Rights Reserved
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License"); you may
00006  * not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  * http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
00013  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  ****************************************************************************
00017  */
00018 
00019 #ifndef UTEST_SCHEDULER_H
00020 #define UTEST_SCHEDULER_H
00021 
00022 #include "mbed.h"
00023 #include <stdint.h>
00024 #include <stdbool.h>
00025 #include <stdio.h>
00026 
00027 #ifdef __cplusplus
00028 extern "C" {
00029 #endif
00030 
00031 /**
00032  * The utest harness manages its own state and therefore does not require the scheduler to
00033  * bind any arguments to the scheduled callback.
00034  */
00035 typedef void (*utest_v1_harness_callback_t)(void);
00036 
00037 /**
00038  * utest calls this function before running the test specification.
00039  * Use this function to initialize your scheduler before the first callback is requested.
00040  *
00041  * @retval  `0` if success
00042  * @retval  non-zero if failure
00043  */
00044 typedef int32_t (*utest_v1_scheduler_init_callback_t)(void);
00045 
00046 /**
00047  * utest calls this function when it needs to schedule a callback with a delay in milliseconds.
00048  * `delay_ms` will only be non-zero if an asynchronous test case exists in the test specification.
00049  * @note If your scheduler cannot provide asynchronous callbacks (which probably require a hardware timer),
00050  *       then this scheduler may return `NULL` as a handle and `utest` will fail the asynchronous request and move on.
00051  *       Note that test cases which do not require asynchronous callback support will still work fine then.
00052  *
00053  * @warning You MUST NOT execute the callback inside this function, even for a delay of 0ms.
00054  *          Buffer the callback and call it in your main loop.
00055  * @warning You MUST NOT execute the callback in an interrupt context!
00056  *          Buffer the callback and call it in your main loop.
00057  * @note utest only schedules one callback at any given time.
00058  *       This should make the implementation of this scheduler a lot simpler for you.
00059  *
00060  * @param   callback    the pointer to the callback function
00061  * @param   delay_ms    the delay in milliseconds after which the callback should be executed
00062  * @return  A handle to identify the scheduled callback, or `NULL` for failure.
00063  */
00064 typedef void *(*utest_v1_scheduler_post_callback_t)(const utest_v1_harness_callback_t callback, timestamp_t delay_ms);
00065 
00066 /**
00067  * utest needs to cancel callbacks with a non-zero delay some time later.
00068  * Even though `utest` only schedules one callback at any given time, it can cancel a callback more than once.
00069  * You should therefore make use of the handle to make sure you do not cancel the wrong callback.
00070  *
00071  * @note If your scheduler cannot provide asynchronous callbacks, do nothing in this function and return non-zero.
00072  *
00073  * @param   handle  the handle returned from the `post` call to identify which callback to be cancelled.
00074  * @retval  `0` if success
00075  * @retval  non-zero if failure
00076  */
00077 typedef int32_t (*utest_v1_scheduler_cancel_callback_t)(void *handle);
00078 
00079 /**
00080  * utest calls this function at the end of the `Harness::run()` function, after (!) the first callback has been requested.
00081  * This function is meant to implement an optional event loop, which may very well be blocking (if your scheduler works with that).
00082  * This assumes that `Harness::run()` will be called on the main stack (ie. not in an interrupt!).
00083  *
00084  * @retval  `0` if success
00085  * @retval  non-zero if failure
00086  */
00087 typedef int32_t (*utest_v1_scheduler_run_callback_t)(void);
00088 
00089 /**
00090  * The scheduler interface consists out of the `post` and `cancel` functions,
00091  * which you must implement to use `utest`.
00092  */
00093 typedef struct {
00094     utest_v1_scheduler_init_callback_t init;
00095     utest_v1_scheduler_post_callback_t post;
00096     utest_v1_scheduler_cancel_callback_t cancel;
00097     utest_v1_scheduler_run_callback_t run;
00098 } utest_v1_scheduler_t;
00099 
00100 #ifdef __cplusplus
00101 }
00102 #endif
00103 
00104 #endif // UTEST_SCHEDULER_H