Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
utest_scheduler.h
1 
2 /** \addtogroup frameworks */
3 /** @{*/
4 /****************************************************************************
5  * Copyright (c) 2015, ARM Limited, All Rights Reserved
6  * SPDX-License-Identifier: Apache-2.0
7  *
8  * Licensed under the Apache License, Version 2.0 (the "License"); you may
9  * not use this file except in compliance with the License.
10  * You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
16  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  ****************************************************************************
20  */
21 
22 #ifndef UTEST_SCHEDULER_H
23 #define UTEST_SCHEDULER_H
24 
25 #include "hal/ticker_api.h"
26 #include <stdint.h>
27 #include <stdbool.h>
28 #include <stdio.h>
29 
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33 
34 /**
35  * The utest harness manages its own state and therefore does not require the scheduler to
36  * bind any arguments to the scheduled callback.
37  */
38 typedef void (*utest_v1_harness_callback_t)(void);
39 
40 /**
41  * utest calls this function before running the test specification.
42  * Use this function to initialize your scheduler before the first callback is requested.
43  *
44  * @retval `0` if success
45  * @retval non-zero if failure
46  */
47 typedef int32_t (*utest_v1_scheduler_init_callback_t)(void);
48 
49 /**
50  * utest calls this function when it needs to schedule a callback with a delay in milliseconds.
51  * `delay_ms` will only be non-zero if an asynchronous test case exists in the test specification.
52  * @note If your scheduler cannot provide asynchronous callbacks (which probably require a hardware timer),
53  * then this scheduler may return `NULL` as a handle and `utest` will fail the asynchronous request and move on.
54  * Note that test cases which do not require asynchronous callback support will still work fine then.
55  *
56  * @warning You MUST NOT execute the callback inside this function, even for a delay of 0ms.
57  * Buffer the callback and call it in your main loop.
58  * @warning You MUST NOT execute the callback in an interrupt context!
59  * Buffer the callback and call it in your main loop.
60  * @note utest only schedules one callback at any given time.
61  * This should make the implementation of this scheduler a lot simpler for you.
62  *
63  * @param callback the pointer to the callback function
64  * @param delay_ms the delay in milliseconds after which the callback should be executed
65  * @return A handle to identify the scheduled callback, or `NULL` for failure.
66  */
67 typedef void *(*utest_v1_scheduler_post_callback_t)(const utest_v1_harness_callback_t callback, timestamp_t delay_ms);
68 
69 /**
70  * utest needs to cancel callbacks with a non-zero delay some time later.
71  * Even though `utest` only schedules one callback at any given time, it can cancel a callback more than once.
72  * You should therefore make use of the handle to make sure you do not cancel the wrong callback.
73  *
74  * @note If your scheduler cannot provide asynchronous callbacks, do nothing in this function and return non-zero.
75  *
76  * @param handle the handle returned from the `post` call to identify which callback to be cancelled.
77  * @retval `0` if success
78  * @retval non-zero if failure
79  */
80 typedef int32_t (*utest_v1_scheduler_cancel_callback_t)(void *handle);
81 
82 /**
83  * utest calls this function at the end of the `Harness::run()` function, after (!) the first callback has been requested.
84  * This function is meant to implement an optional event loop, which may very well be blocking (if your scheduler works with that).
85  * This assumes that `Harness::run()` will be called on the main stack (ie. not in an interrupt!).
86  *
87  * @retval `0` if success
88  * @retval non-zero if failure
89  */
90 typedef int32_t (*utest_v1_scheduler_run_callback_t)(void);
91 
92 /**
93  * The scheduler interface consists out of the `post` and `cancel` functions,
94  * which you must implement to use `utest`.
95  */
96 typedef struct {
97  utest_v1_scheduler_init_callback_t init;
98  utest_v1_scheduler_post_callback_t post;
99  utest_v1_scheduler_cancel_callback_t cancel;
100  utest_v1_scheduler_run_callback_t run;
101 } utest_v1_scheduler_t;
102 
103 #ifdef __cplusplus
104 }
105 #endif
106 
107 #endif // UTEST_SCHEDULER_H
108 
109 /** @}*/
utest_v1_scheduler_run_callback_t
int32_t(* utest_v1_scheduler_run_callback_t)(void)
utest calls this function at the end of the Harness::run() function, after (!) the first callback has...
Definition: utest_scheduler.h:90
utest_v1_scheduler_t
The scheduler interface consists out of the post and cancel functions, which you must implement to us...
Definition: utest_scheduler.h:96
mbed::callback
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
utest_v1_scheduler_cancel_callback_t
int32_t(* utest_v1_scheduler_cancel_callback_t)(void *handle)
utest needs to cancel callbacks with a non-zero delay some time later.
Definition: utest_scheduler.h:80
utest_v1_scheduler_post_callback_t
void *(* utest_v1_scheduler_post_callback_t)(const utest_v1_harness_callback_t callback, timestamp_t delay_ms)
utest calls this function when it needs to schedule a callback with a delay in milliseconds.
Definition: utest_scheduler.h:67
utest_v1_harness_callback_t
void(* utest_v1_harness_callback_t)(void)
The utest harness manages its own state and therefore does not require the scheduler to bind any argu...
Definition: utest_scheduler.h:38
timestamp_t
uint32_t timestamp_t
Legacy format representing a timestamp in us.
Definition: ticker_api.h:33
utest_v1_scheduler_init_callback_t
int32_t(* utest_v1_scheduler_init_callback_t)(void)
utest calls this function before running the test specification.
Definition: utest_scheduler.h:47
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.