1 /***************************************************************************
2  * Copyright (c) 2024 Microsoft Corporation
3  *
4  * This program and the accompanying materials are made available under the
5  * terms of the MIT License which is available at
6  * https://opensource.org/licenses/MIT.
7  *
8  * SPDX-License-Identifier: MIT
9  **************************************************************************/
10 
11 /**************************************************************************/
12 /**************************************************************************/
13 /**                                                                       */
14 /** Thread-Metric Component                                               */
15 /**                                                                       */
16 /** Application Interface (API)                                           */
17 /**                                                                       */
18 /**************************************************************************/
19 /**************************************************************************/
20 
21 /**************************************************************************/
22 /*                                                                        */
23 /*  APPLICATION INTERFACE DEFINITION                       RELEASE        */
24 /*                                                                        */
25 /*    tm_api.h                                            PORTABLE C      */
26 /*                                                           6.1.7        */
27 /*  AUTHOR                                                                */
28 /*                                                                        */
29 /*    William E. Lamie, Microsoft Corporation                             */
30 /*                                                                        */
31 /*  DESCRIPTION                                                           */
32 /*                                                                        */
33 /*    This file defines the basic Application Interface (API)             */
34 /*    implementation source code for the Thread-Metrics performance       */
35 /*    test suite. All service prototypes and data structure definitions   */
36 /*    are defined in this file.                                           */
37 /*                                                                        */
38 /*  RELEASE HISTORY                                                       */
39 /*                                                                        */
40 /*    DATE              NAME                      DESCRIPTION             */
41 /*                                                                        */
42 /*  10-15-2021     William E. Lamie         Initial Version 6.1.7         */
43 /*                                                                        */
44 /**************************************************************************/
45 
46 #ifndef TM_API_H
47 #define TM_API_H
48 
49 #include "tm_porting_layer.h"
50 
51 /*
52  * Determine if a C++ compiler is being used.  If so, ensure that standard
53  * C is used to process the API information.
54  */
55 
56 #ifdef __cplusplus
57 
58 /* Yes, C++ compiler is present.  Use standard C.  */
59 extern "C" {
60 
61 #endif
62 
63 /* Define API constants.  */
64 
65 #define TM_SUCCESS 0
66 #define TM_ERROR   1
67 
68 /* Define the time interval in seconds. This can be changed with a -D compiler option.  */
69 
70 #ifndef TM_TEST_DURATION
71 #define TM_TEST_DURATION 30
72 #endif
73 
74 /*
75  * Define RTOS Neutral APIs. RTOS vendors should fill in the guts of the following
76  * API. Once this is done the Thread-Metric tests can be successfully run.
77  */
78 
79 void tm_initialize(void (*test_initialization_function)(void));
80 int tm_thread_create(int thread_id, int priority, void (*entry_function)(void *, void *, void *));
81 int tm_thread_resume(int thread_id);
82 int tm_thread_suspend(int thread_id);
83 void tm_thread_relinquish(void);
84 void tm_thread_sleep(int seconds);
85 int tm_queue_create(int queue_id);
86 int tm_queue_send(int queue_id, unsigned long *message_ptr);
87 int tm_queue_receive(int queue_id, unsigned long *message_ptr);
88 int tm_semaphore_create(int semaphore_id);
89 int tm_semaphore_get(int semaphore_id);
90 int tm_semaphore_put(int semaphore_id);
91 int tm_memory_pool_create(int pool_id);
92 int tm_memory_pool_allocate(int pool_id, unsigned char **memory_ptr);
93 int tm_memory_pool_deallocate(int pool_id, unsigned char *memory_ptr);
94 
95 /*
96  * Determine if a C++ compiler is being used.  If so, complete the standard
97  * C conditional started above.
98  */
99 #ifdef __cplusplus
100 }
101 #endif
102 
103 #endif
104