1 /*
2  * Copyright (c) 2018-2023, Arm Limited. All rights reserved.
3  * Copyright (c) 2023 Cypress Semiconductor Corporation (an Infineon
4  * company) or an affiliate of Cypress Semiconductor Corporation. All rights
5  * reserved.
6  *
7  * SPDX-License-Identifier: BSD-3-Clause
8  *
9  */
10 
11 #ifndef __M_THREAD_H__ /* Add an extra M as thread.h is common. */
12 #define __M_THREAD_H__
13 
14 #include <stddef.h>
15 #include <stdint.h>
16 
17 #include "tfm_arch.h"
18 
19 /* State codes */
20 #define THRD_STATE_CREATING       0
21 #define THRD_STATE_RUNNABLE       1
22 #define THRD_STATE_BLOCK          2
23 #define THRD_STATE_DETACH         3
24 #define THRD_STATE_INVALID        4
25 #define THRD_STATE_RET_VAL_AVAIL  5
26 
27 /* Priorities. Lower value has higher priority */
28 #define THRD_PRIOR_HIGHEST        0x0
29 #define THRD_PRIOR_HIGH           0xF
30 #define THRD_PRIOR_MEDIUM         0x1F
31 #define THRD_PRIOR_LOW            0x7F
32 #define THRD_PRIOR_LOWEST         0xFF
33 
34 /* Error codes */
35 #define THRD_SUCCESS              0
36 #define THRD_ERR_GENERIC          1
37 
38 /* Thread entry function type */
39 typedef void (*thrd_fn_t)(void *);
40 
41 /* An address causes exceptions (invalid address and security bit). */
42 #define THRD_GENERAL_EXIT  ((thrd_fn_t)(0xFFFFFFFE))
43 
44 /* Thread context */
45 struct thread_t {
46     uint8_t                priority;          /* Priority                          */
47     uint8_t                state;             /* State                             */
48     uint16_t               flags;             /* Flags and align, DO NOT REMOVE!   */
49     struct context_ctrl_t *p_context_ctrl;    /* Context control (sp, splimit, lr) */
50     struct thread_t       *next;              /* Next thread in list               */
51 };
52 
53 /* Query thread state function type */
54 typedef uint32_t (*thrd_query_state_t)(struct thread_t *p_thrd,
55                                        uint32_t *p_retval);
56 /*
57  * Definition for the current thread and its access helper preprocessor.
58  * The definition needs to be declared in one of the sources.
59  */
60 extern struct thread_t *p_curr_thrd;
61 #define CURRENT_THREAD p_curr_thrd
62 
63 /*
64  * Initialize the thread_t struct with the given inputs.
65  *
66  * Parameters:
67  *  p_thrd         -    Pointer of caller provided thread_t struct to be init
68  *  p_ctx_ctrl     -    Initial Context control (sp, splimit, lr)
69  *  priority       -    Initial priority
70  */
71 #define THRD_INIT(p_thrd, p_ctx_ctrl, prio) do {                         \
72                         (p_thrd)->priority       = (uint8_t)(prio);      \
73                         (p_thrd)->state          = THRD_STATE_CREATING;  \
74                         (p_thrd)->flags          = 0;                    \
75                         (p_thrd)->p_context_ctrl = p_ctx_ctrl;           \
76                     } while (0)
77 
78 /*
79  * Set thread priority.
80  *
81  * Parameters :
82  *  p_thrd         -     Pointer of thread_t struct
83  *  priority       -     Priority value (0~255)
84  *
85  * Note :
86  *  The new priority may not take effect immediately.
87  */
88 #define THRD_SET_PRIORITY(p_thrd, priority) \
89                                         p_thrd->priority = (uint8_t)(priority)
90 
91 /*
92  * Update current thread's bound context pointer.
93  *
94  * Parameters :
95  *  x              -     Context pointer to be bound with the current thread.
96  */
97 #define THRD_UPDATE_CUR_CTXCTRL(x)          \
98                                 CURRENT_THREAD->p_context_ctrl = (x)
99 
100 /*
101  * Init the global query state callback function pointer.
102  *
103  * Parameters :
104  *  fn             -     Query state function pointer.
105  */
106 void thrd_set_query_callback(thrd_query_state_t fn);
107 
108 /*
109  * Set thread state, and updates the runnable head.
110  *
111  * Parameters :
112  *  p_thrd         -     Pointer of thread_t struct
113  *  new_state      -     New state of thread
114  */
115 void thrd_set_state(struct thread_t *p_thrd, uint32_t new_state);
116 
117 /*
118  * Prepare thread context with given info and insert it into schedulable list.
119  *
120  * Parameters :
121  *  p_thrd         -     Pointer of thread_t struct
122  *  fn             -     Thread entry function
123  *  exit_fn        -     The function to go when 'fn' exited
124  *  param          -     Parameter passed to fn
125  *
126  * Note :
127  *  - The thread is not "started" immediately.
128  */
129 void thrd_start(struct thread_t *p_thrd, thrd_fn_t fn, thrd_fn_t exit_fn, void *param);
130 
131 /*
132  * Get the next thread to run in list.
133  *
134  * Return :
135  *  Pointer of next thread to run.
136  */
137 struct thread_t *thrd_next(void);
138 
139 /*
140  * Start scheduling.
141  *
142  * ppth [out]       -     The first runnable thread
143  *
144  * Return :
145  *  The EXC_RETURN payload of the first runnable thread for caller usage.
146  */
147 uint32_t thrd_start_scheduler(struct thread_t **ppth);
148 
149 #endif /* __M_THREAD_H__ */
150