blob: 2dd2a80c66c69be45f06e02c3e3f3c7a40a46112 [file] [log] [blame]
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001/*
2 * Copyright (c) 2016, Wind River Systems, Inc.
3 *
David B. Kinderac74d8b2017-01-18 17:01:01 -08004 * SPDX-License-Identifier: Apache-2.0
Benjamin Walsh456c6da2016-09-02 18:55:39 -04005 */
6
7/**
8 * @file
9 *
10 * @brief Public kernel APIs.
11 */
12
13#ifndef _kernel__h_
14#define _kernel__h_
15
Benjamin Walshdfa7ce52017-01-22 17:06:05 -050016#if !defined(_ASMLANGUAGE)
Benjamin Walsh456c6da2016-09-02 18:55:39 -040017#include <stddef.h>
Kumar Gala78908162017-04-19 10:32:08 -050018#include <zephyr/types.h>
Anas Nashif173902f2017-01-17 07:08:56 -050019#include <limits.h>
Benjamin Walsh456c6da2016-09-02 18:55:39 -040020#include <toolchain.h>
Anas Nashif397d29d2017-06-17 11:30:47 -040021#include <linker/sections.h>
Benjamin Walsh456c6da2016-09-02 18:55:39 -040022#include <atomic.h>
23#include <errno.h>
24#include <misc/__assert.h>
25#include <misc/dlist.h>
26#include <misc/slist.h>
Benjamin Walsh62092182016-12-20 14:39:08 -050027#include <misc/util.h>
Anas Nashifea8c6aad2016-12-23 07:32:56 -050028#include <kernel_version.h>
Anas Nashifa6149502017-01-17 07:47:31 -050029#include <drivers/rand32.h>
Andrew Boie73abd322017-04-04 13:19:13 -070030#include <kernel_arch_thread.h>
Andrew Boie13ca6fe2017-09-23 12:05:49 -070031#include <syscall.h>
Benjamin Walsh456c6da2016-09-02 18:55:39 -040032
33#ifdef __cplusplus
34extern "C" {
35#endif
36
Anas Nashifbbb157d2017-01-15 08:46:31 -050037/**
38 * @brief Kernel APIs
39 * @defgroup kernel_apis Kernel APIs
40 * @{
41 * @}
42 */
43
Anas Nashif61f4b242016-11-18 10:53:59 -050044#ifdef CONFIG_KERNEL_DEBUG
45#include <misc/printk.h>
Benjamin Walsh456c6da2016-09-02 18:55:39 -040046#define K_DEBUG(fmt, ...) printk("[%s] " fmt, __func__, ##__VA_ARGS__)
47#else
48#define K_DEBUG(fmt, ...)
49#endif
50
Benjamin Walsh2f280412017-01-14 19:23:46 -050051#if defined(CONFIG_COOP_ENABLED) && defined(CONFIG_PREEMPT_ENABLED)
52#define _NUM_COOP_PRIO (CONFIG_NUM_COOP_PRIORITIES)
53#define _NUM_PREEMPT_PRIO (CONFIG_NUM_PREEMPT_PRIORITIES + 1)
54#elif defined(CONFIG_COOP_ENABLED)
55#define _NUM_COOP_PRIO (CONFIG_NUM_COOP_PRIORITIES + 1)
56#define _NUM_PREEMPT_PRIO (0)
57#elif defined(CONFIG_PREEMPT_ENABLED)
58#define _NUM_COOP_PRIO (0)
59#define _NUM_PREEMPT_PRIO (CONFIG_NUM_PREEMPT_PRIORITIES + 1)
60#else
61#error "invalid configuration"
62#endif
63
64#define K_PRIO_COOP(x) (-(_NUM_COOP_PRIO - (x)))
Benjamin Walsh456c6da2016-09-02 18:55:39 -040065#define K_PRIO_PREEMPT(x) (x)
66
Benjamin Walsh456c6da2016-09-02 18:55:39 -040067#define K_ANY NULL
68#define K_END NULL
69
Benjamin Walshedb35702017-01-14 18:47:22 -050070#if defined(CONFIG_COOP_ENABLED) && defined(CONFIG_PREEMPT_ENABLED)
Benjamin Walsh456c6da2016-09-02 18:55:39 -040071#define K_HIGHEST_THREAD_PRIO (-CONFIG_NUM_COOP_PRIORITIES)
Benjamin Walshedb35702017-01-14 18:47:22 -050072#elif defined(CONFIG_COOP_ENABLED)
73#define K_HIGHEST_THREAD_PRIO (-CONFIG_NUM_COOP_PRIORITIES - 1)
74#elif defined(CONFIG_PREEMPT_ENABLED)
Benjamin Walsh456c6da2016-09-02 18:55:39 -040075#define K_HIGHEST_THREAD_PRIO 0
Benjamin Walshedb35702017-01-14 18:47:22 -050076#else
77#error "invalid configuration"
Benjamin Walsh456c6da2016-09-02 18:55:39 -040078#endif
79
Benjamin Walsh7fa3cd72017-01-14 18:49:11 -050080#ifdef CONFIG_PREEMPT_ENABLED
Benjamin Walsh456c6da2016-09-02 18:55:39 -040081#define K_LOWEST_THREAD_PRIO CONFIG_NUM_PREEMPT_PRIORITIES
82#else
83#define K_LOWEST_THREAD_PRIO -1
84#endif
85
Benjamin Walshfab8d922016-11-08 15:36:36 -050086#define K_IDLE_PRIO K_LOWEST_THREAD_PRIO
87
Benjamin Walsh456c6da2016-09-02 18:55:39 -040088#define K_HIGHEST_APPLICATION_THREAD_PRIO (K_HIGHEST_THREAD_PRIO)
89#define K_LOWEST_APPLICATION_THREAD_PRIO (K_LOWEST_THREAD_PRIO - 1)
90
91typedef sys_dlist_t _wait_q_t;
92
Anas Nashif2f203c22016-12-18 06:57:45 -050093#ifdef CONFIG_OBJECT_TRACING
94#define _OBJECT_TRACING_NEXT_PTR(type) struct type *__next
95#define _OBJECT_TRACING_INIT .__next = NULL,
Benjamin Walsh456c6da2016-09-02 18:55:39 -040096#else
Anas Nashif2f203c22016-12-18 06:57:45 -050097#define _OBJECT_TRACING_INIT
98#define _OBJECT_TRACING_NEXT_PTR(type)
Benjamin Walsh456c6da2016-09-02 18:55:39 -040099#endif
100
Benjamin Walshacc68c12017-01-29 18:57:45 -0500101#ifdef CONFIG_POLL
Luiz Augusto von Dentz7d01c5e2017-08-21 10:49:29 +0300102#define _POLL_EVENT_OBJ_INIT(obj) \
103 .poll_events = SYS_DLIST_STATIC_INIT(&obj.poll_events),
104#define _POLL_EVENT sys_dlist_t poll_events
Benjamin Walshacc68c12017-01-29 18:57:45 -0500105#else
Luiz Augusto von Dentz7d01c5e2017-08-21 10:49:29 +0300106#define _POLL_EVENT_OBJ_INIT(obj)
Benjamin Walshacc68c12017-01-29 18:57:45 -0500107#define _POLL_EVENT
108#endif
109
Benjamin Walshf6ca7de2016-11-08 10:36:50 -0500110struct k_thread;
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400111struct k_mutex;
112struct k_sem;
Benjamin Walsh31a3f6a2016-10-25 13:28:35 -0400113struct k_alert;
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400114struct k_msgq;
115struct k_mbox;
116struct k_pipe;
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +0200117struct k_queue;
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400118struct k_fifo;
119struct k_lifo;
120struct k_stack;
Benjamin Walsh7ef0f622016-10-24 17:04:43 -0400121struct k_mem_slab;
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400122struct k_mem_pool;
123struct k_timer;
Benjamin Walshacc68c12017-01-29 18:57:45 -0500124struct k_poll_event;
125struct k_poll_signal;
Chunlin Hane9c97022017-07-07 20:29:30 +0800126struct k_mem_domain;
127struct k_mem_partition;
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400128
Andrew Boie5bd891d2017-09-27 12:59:28 -0700129/* This enumeration needs to be kept in sync with the lists of kernel objects
130 * and subsystems in scripts/gen_kobject_list.py, as well as the otype_to_str()
131 * function in kernel/userspace.c
132 */
Andrew Boie945af952017-08-22 13:15:23 -0700133enum k_objects {
Andrew Boie5bd891d2017-09-27 12:59:28 -0700134 /* Core kernel objects */
Andrew Boie945af952017-08-22 13:15:23 -0700135 K_OBJ_ALERT,
136 K_OBJ_DELAYED_WORK,
137 K_OBJ_MEM_SLAB,
138 K_OBJ_MSGQ,
139 K_OBJ_MUTEX,
140 K_OBJ_PIPE,
141 K_OBJ_SEM,
142 K_OBJ_STACK,
143 K_OBJ_THREAD,
144 K_OBJ_TIMER,
145 K_OBJ_WORK,
146 K_OBJ_WORK_Q,
147
Andrew Boie5bd891d2017-09-27 12:59:28 -0700148 /* Driver subsystems */
149 K_OBJ_DRIVER_ADC,
150 K_OBJ_DRIVER_AIO_CMP,
151 K_OBJ_DRIVER_CLOCK_CONTROL,
152 K_OBJ_DRIVER_COUNTER,
153 K_OBJ_DRIVER_CRYPTO,
154 K_OBJ_DRIVER_DMA,
155 K_OBJ_DRIVER_ETH,
156 K_OBJ_DRIVER_FLASH,
157 K_OBJ_DRIVER_GPIO,
158 K_OBJ_DRIVER_I2C,
159 K_OBJ_DRIVER_I2S,
160 K_OBJ_DRIVER_IPM,
161 K_OBJ_DRIVER_PINMUX,
162 K_OBJ_DRIVER_PWM,
163 K_OBJ_DRIVER_RANDOM,
164 K_OBJ_DRIVER_RTC,
165 K_OBJ_DRIVER_SENSOR,
166 K_OBJ_DRIVER_SHARED_IRQ,
167 K_OBJ_DRIVER_SPI,
168 K_OBJ_DRIVER_UART,
169 K_OBJ_DRIVER_WDT,
170
Andrew Boie945af952017-08-22 13:15:23 -0700171 K_OBJ_LAST
172};
173
174#ifdef CONFIG_USERSPACE
175/* Table generated by gperf, these objects are retrieved via
176 * _k_object_find() */
177struct _k_object {
178 char *name;
179 char perms[CONFIG_MAX_THREAD_BYTES];
180 char type;
181 char flags;
182} __packed;
183
184#define K_OBJ_FLAG_INITIALIZED BIT(0)
185/**
186 * Ensure a system object is a valid object of the expected type
187 *
188 * Searches for the object and ensures that it is indeed an object
189 * of the expected type, that the caller has the right permissions on it,
190 * and that the object has been initialized.
191 *
192 * This function is intended to be called on the kernel-side system
193 * call handlers to validate kernel object pointers passed in from
194 * userspace.
195 *
196 * @param obj Address of the kernel object
197 * @param otype Expected type of the kernel object
198 * @param init If true, this is for an init function and we will not error
199 * out if the object is not initialized
200 * @return 0 If the object is valid
201 * -EBADF if not a valid object of the specified type
202 * -EPERM If the caller does not have permissions
David B. Kinder8065dbc2017-09-21 15:25:40 -0700203 * -EINVAL Object is not initialized
Andrew Boie945af952017-08-22 13:15:23 -0700204 */
205int _k_object_validate(void *obj, enum k_objects otype, int init);
206
207
208/**
209 * Lookup a kernel object and init its metadata if it exists
210 *
211 * Calling this on an object will make it usable from userspace.
212 * Intended to be called as the last statement in kernel object init
213 * functions.
214 *
215 * @param object Address of the kernel object
216 */
217void _k_object_init(void *obj);
Andrew Boie743e4682017-10-04 12:25:50 -0700218#else
219static inline int _k_object_validate(void *obj, enum k_objects otype, int init)
220{
221 ARG_UNUSED(obj);
222 ARG_UNUSED(otype);
223 ARG_UNUSED(init);
Andrew Boie945af952017-08-22 13:15:23 -0700224
Andrew Boie743e4682017-10-04 12:25:50 -0700225 return 0;
226}
227
228static inline void _k_object_init(void *obj)
229{
230 ARG_UNUSED(obj);
231}
232
233static inline void _impl_k_object_access_grant(void *object,
234 struct k_thread *thread)
235{
236 ARG_UNUSED(object);
237 ARG_UNUSED(thread);
238}
239
240static inline void _impl_k_object_access_all_grant(void *object)
241{
242 ARG_UNUSED(object);
243}
244#endif /* !CONFIG_USERSPACE */
Andrew Boie945af952017-08-22 13:15:23 -0700245
246/**
247 * grant a thread access to a kernel object
248 *
249 * The thread will be granted access to the object if the caller is from
250 * supervisor mode, or the caller is from user mode AND has permissions
251 * on the object already.
252 *
253 * @param object Address of kernel object
254 * @param thread Thread to grant access to the object
255 */
Andrew Boie743e4682017-10-04 12:25:50 -0700256__syscall void k_object_access_grant(void *object, struct k_thread *thread);
Andrew Boie945af952017-08-22 13:15:23 -0700257
Andrew Boie3b5ae802017-10-04 12:10:32 -0700258
259/**
260 * grant all present and future threads access to an object
261 *
262 * If the caller is from supervisor mode, or the caller is from user mode and
263 * have sufficient permissions on the object, then that object will have
264 * permissions granted to it for *all* current and future threads running in
265 * the system, effectively becoming a public kernel object.
266 *
267 * Use of this API should be avoided on systems that are running untrusted code
268 * as it is possible for such code to derive the addresses of kernel objects
269 * and perform unwanted operations on them.
270 *
271 * @param object Address of kernel object
272 */
Andrew Boie743e4682017-10-04 12:25:50 -0700273__syscall void k_object_access_all_grant(void *object);
Andrew Boie945af952017-08-22 13:15:23 -0700274
Andrew Boie73abd322017-04-04 13:19:13 -0700275/* timeouts */
276
277struct _timeout;
278typedef void (*_timeout_func_t)(struct _timeout *t);
279
280struct _timeout {
281 sys_dnode_t node;
282 struct k_thread *thread;
283 sys_dlist_t *wait_q;
284 s32_t delta_ticks_from_prev;
285 _timeout_func_t func;
286};
287
288extern s32_t _timeout_remaining_get(struct _timeout *timeout);
289
Andrew Boie1e06ffc2017-09-11 09:30:04 -0700290/**
291 * @typedef k_thread_entry_t
292 * @brief Thread entry point function type.
293 *
294 * A thread's entry point function is invoked when the thread starts executing.
295 * Up to 3 argument values can be passed to the function.
296 *
297 * The thread terminates execution permanently if the entry point function
298 * returns. The thread is responsible for releasing any shared resources
299 * it may own (such as mutexes and dynamically allocated memory), prior to
300 * returning.
301 *
302 * @param p1 First argument.
303 * @param p2 Second argument.
304 * @param p3 Third argument.
305 *
306 * @return N/A
307 */
308typedef void (*k_thread_entry_t)(void *p1, void *p2, void *p3);
Andrew Boie73abd322017-04-04 13:19:13 -0700309
310#ifdef CONFIG_THREAD_MONITOR
311struct __thread_entry {
Andrew Boie1e06ffc2017-09-11 09:30:04 -0700312 k_thread_entry_t pEntry;
Andrew Boie73abd322017-04-04 13:19:13 -0700313 void *parameter1;
314 void *parameter2;
315 void *parameter3;
316};
317#endif
318
319/* can be used for creating 'dummy' threads, e.g. for pending on objects */
320struct _thread_base {
321
322 /* this thread's entry in a ready/wait queue */
323 sys_dnode_t k_q_node;
324
325 /* user facing 'thread options'; values defined in include/kernel.h */
326 u8_t user_options;
327
328 /* thread state */
329 u8_t thread_state;
330
331 /*
332 * scheduler lock count and thread priority
333 *
334 * These two fields control the preemptibility of a thread.
335 *
336 * When the scheduler is locked, sched_locked is decremented, which
337 * means that the scheduler is locked for values from 0xff to 0x01. A
338 * thread is coop if its prio is negative, thus 0x80 to 0xff when
339 * looked at the value as unsigned.
340 *
341 * By putting them end-to-end, this means that a thread is
342 * non-preemptible if the bundled value is greater than or equal to
343 * 0x0080.
344 */
345 union {
346 struct {
347#if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
348 u8_t sched_locked;
349 s8_t prio;
350#else /* LITTLE and PDP */
351 s8_t prio;
352 u8_t sched_locked;
353#endif
354 };
355 u16_t preempt;
356 };
357
358 /* data returned by APIs */
359 void *swap_data;
360
361#ifdef CONFIG_SYS_CLOCK_EXISTS
362 /* this thread's entry in a timeout queue */
363 struct _timeout timeout;
364#endif
Andrew Boie2acfcd62017-08-30 14:31:03 -0700365
366#ifdef CONFIG_USERSPACE
367 /* Bit position in kernel object permissions bitfield for this thread */
368 unsigned int perm_index;
369#endif
Andrew Boie73abd322017-04-04 13:19:13 -0700370};
371
372typedef struct _thread_base _thread_base_t;
373
374#if defined(CONFIG_THREAD_STACK_INFO)
375/* Contains the stack information of a thread */
376struct _thread_stack_info {
377 /* Stack Start */
378 u32_t start;
379 /* Stack Size */
380 u32_t size;
381};
Andrew Boie41c68ec2017-05-11 15:38:20 -0700382
383typedef struct _thread_stack_info _thread_stack_info_t;
Andrew Boie73abd322017-04-04 13:19:13 -0700384#endif /* CONFIG_THREAD_STACK_INFO */
385
Chunlin Hane9c97022017-07-07 20:29:30 +0800386#if defined(CONFIG_USERSPACE)
387struct _mem_domain_info {
388 /* memory domain queue node */
389 sys_dnode_t mem_domain_q_node;
390 /* memory domain of the thread */
391 struct k_mem_domain *mem_domain;
392};
393
394#endif /* CONFIG_USERSPACE */
395
Andrew Boie73abd322017-04-04 13:19:13 -0700396struct k_thread {
397
398 struct _thread_base base;
399
400 /* defined by the architecture, but all archs need these */
401 struct _caller_saved caller_saved;
402 struct _callee_saved callee_saved;
403
404 /* static thread init data */
405 void *init_data;
406
407 /* abort function */
408 void (*fn_abort)(void);
409
410#if defined(CONFIG_THREAD_MONITOR)
411 /* thread entry and parameters description */
412 struct __thread_entry *entry;
413
414 /* next item in list of all threads */
415 struct k_thread *next_thread;
416#endif
417
418#ifdef CONFIG_THREAD_CUSTOM_DATA
419 /* crude thread-local storage */
420 void *custom_data;
421#endif
422
423#ifdef CONFIG_ERRNO
424 /* per-thread errno variable */
425 int errno_var;
426#endif
427
428#if defined(CONFIG_THREAD_STACK_INFO)
429 /* Stack Info */
430 struct _thread_stack_info stack_info;
431#endif /* CONFIG_THREAD_STACK_INFO */
432
Chunlin Hane9c97022017-07-07 20:29:30 +0800433#if defined(CONFIG_USERSPACE)
434 /* memory domain info of the thread */
435 struct _mem_domain_info mem_domain_info;
436#endif /* CONFIG_USERSPACE */
437
Andrew Boie73abd322017-04-04 13:19:13 -0700438 /* arch-specifics: must always be at the end */
439 struct _thread_arch arch;
440};
441
442typedef struct k_thread _thread_t;
Benjamin Walshb7ef0cb2016-10-05 17:32:01 -0400443typedef struct k_thread *k_tid_t;
Andrew Boie73abd322017-04-04 13:19:13 -0700444#define tcs k_thread
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400445
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400446enum execution_context_types {
447 K_ISR = 0,
448 K_COOP_THREAD,
449 K_PREEMPT_THREAD,
450};
451
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400452/**
Carles Cuficb0cf9f2017-01-10 10:57:38 +0100453 * @defgroup profiling_apis Profiling APIs
454 * @ingroup kernel_apis
455 * @{
456 */
457
458/**
459 * @brief Analyze the main, idle, interrupt and system workqueue call stacks
460 *
Andrew Boiedc5d9352017-06-02 12:56:47 -0700461 * This routine calls @ref STACK_ANALYZE on the 4 call stacks declared and
Carles Cuficb0cf9f2017-01-10 10:57:38 +0100462 * maintained by the kernel. The sizes of those 4 call stacks are defined by:
463 *
464 * CONFIG_MAIN_STACK_SIZE
465 * CONFIG_IDLE_STACK_SIZE
466 * CONFIG_ISR_STACK_SIZE
467 * CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE
468 *
469 * @note CONFIG_INIT_STACKS and CONFIG_PRINTK must be set for this function to
470 * produce output.
471 *
472 * @return N/A
473 */
474extern void k_call_stacks_analyze(void);
475
476/**
477 * @} end defgroup profiling_apis
478 */
479
480/**
Allan Stephensc98da842016-11-11 15:45:03 -0500481 * @defgroup thread_apis Thread APIs
482 * @ingroup kernel_apis
483 * @{
484 */
485
Benjamin Walshed240f22017-01-22 13:05:08 -0500486#endif /* !_ASMLANGUAGE */
487
488
489/*
490 * Thread user options. May be needed by assembly code. Common part uses low
491 * bits, arch-specific use high bits.
492 */
493
494/* system thread that must not abort */
495#define K_ESSENTIAL (1 << 0)
496
497#if defined(CONFIG_FP_SHARING)
498/* thread uses floating point registers */
499#define K_FP_REGS (1 << 1)
500#endif
501
Andrew Boie5cfa5dc2017-08-30 14:17:44 -0700502/* This thread has dropped from supervisor mode to user mode and consequently
503 * has additional restrictions
504 */
505#define K_USER (1 << 2)
506
Benjamin Walshed240f22017-01-22 13:05:08 -0500507#ifdef CONFIG_X86
508/* x86 Bitmask definitions for threads user options */
509
510#if defined(CONFIG_FP_SHARING) && defined(CONFIG_SSE)
511/* thread uses SSEx (and also FP) registers */
512#define K_SSE_REGS (1 << 7)
513#endif
514#endif
515
516/* end - thread options */
517
518#if !defined(_ASMLANGUAGE)
519
Andrew Boie507852a2017-07-25 18:47:07 -0700520/* Using typedef deliberately here, this is quite intended to be an opaque
521 * type. K_THREAD_STACK_BUFFER() should be used to access the data within.
522 *
523 * The purpose of this data type is to clearly distinguish between the
524 * declared symbol for a stack (of type k_thread_stack_t) and the underlying
525 * buffer which composes the stack data actually used by the underlying
526 * thread; they cannot be used interchangably as some arches precede the
527 * stack buffer region with guard areas that trigger a MPU or MMU fault
528 * if written to.
529 *
530 * APIs that want to work with the buffer inside should continue to use
531 * char *.
532 *
533 * Stacks should always be created with K_THREAD_STACK_DEFINE().
534 */
535struct __packed _k_thread_stack_element {
536 char data;
537};
538typedef struct _k_thread_stack_element *k_thread_stack_t;
539
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400540
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400541/**
Andrew Boied26cf2d2017-03-30 13:07:02 -0700542 * @brief Create a thread.
543 *
544 * This routine initializes a thread, then schedules it for execution.
545 *
546 * The new thread may be scheduled for immediate execution or a delayed start.
547 * If the newly spawned thread does not have a delayed start the kernel
548 * scheduler may preempt the current thread to allow the new thread to
549 * execute.
550 *
551 * Thread options are architecture-specific, and can include K_ESSENTIAL,
552 * K_FP_REGS, and K_SSE_REGS. Multiple options may be specified by separating
553 * them using "|" (the logical OR operator).
554 *
555 * Historically, users often would use the beginning of the stack memory region
556 * to store the struct k_thread data, although corruption will occur if the
557 * stack overflows this region and stack protection features may not detect this
558 * situation.
559 *
560 * @param new_thread Pointer to uninitialized struct k_thread
561 * @param stack Pointer to the stack space.
562 * @param stack_size Stack size in bytes.
563 * @param entry Thread entry function.
564 * @param p1 1st entry point parameter.
565 * @param p2 2nd entry point parameter.
566 * @param p3 3rd entry point parameter.
567 * @param prio Thread priority.
568 * @param options Thread options.
569 * @param delay Scheduling delay (in milliseconds), or K_NO_WAIT (for no delay).
570 *
571 * @return ID of new thread.
572 */
Andrew Boie507852a2017-07-25 18:47:07 -0700573extern k_tid_t k_thread_create(struct k_thread *new_thread,
574 k_thread_stack_t stack,
Andrew Boied26cf2d2017-03-30 13:07:02 -0700575 size_t stack_size,
Andrew Boie1e06ffc2017-09-11 09:30:04 -0700576 k_thread_entry_t entry,
Andrew Boied26cf2d2017-03-30 13:07:02 -0700577 void *p1, void *p2, void *p3,
578 int prio, u32_t options, s32_t delay);
579
Andrew Boie3f091b52017-08-30 14:34:14 -0700580/**
581 * @brief Drop a thread's privileges permanently to user mode
582 *
583 * @param entry Function to start executing from
584 * @param p1 1st entry point parameter
585 * @param p2 2nd entry point parameter
586 * @param p3 3rd entry point parameter
587 */
588extern FUNC_NORETURN void k_thread_user_mode_enter(k_thread_entry_t entry,
589 void *p1, void *p2,
590 void *p3);
Andrew Boie3f091b52017-08-30 14:34:14 -0700591
Andrew Boied26cf2d2017-03-30 13:07:02 -0700592/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500593 * @brief Put the current thread to sleep.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400594 *
Allan Stephensc98da842016-11-11 15:45:03 -0500595 * This routine puts the current thread to sleep for @a duration
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500596 * milliseconds.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400597 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500598 * @param duration Number of milliseconds to sleep.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400599 *
600 * @return N/A
601 */
Andrew Boie76c04a22017-09-27 14:45:10 -0700602__syscall void k_sleep(s32_t duration);
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400603
604/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500605 * @brief Cause the current thread to busy wait.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400606 *
607 * This routine causes the current thread to execute a "do nothing" loop for
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500608 * @a usec_to_wait microseconds.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400609 *
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400610 * @return N/A
611 */
Kumar Galacc334c72017-04-21 10:55:34 -0500612extern void k_busy_wait(u32_t usec_to_wait);
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400613
614/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500615 * @brief Yield the current thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400616 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500617 * This routine causes the current thread to yield execution to another
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400618 * thread of the same or higher priority. If there are no other ready threads
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500619 * of the same or higher priority, the routine returns immediately.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400620 *
621 * @return N/A
622 */
Andrew Boie468190a2017-09-29 14:00:48 -0700623__syscall void k_yield(void);
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400624
625/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500626 * @brief Wake up a sleeping thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400627 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500628 * This routine prematurely wakes up @a thread from sleeping.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400629 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500630 * If @a thread is not currently sleeping, the routine has no effect.
631 *
632 * @param thread ID of thread to wake.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400633 *
634 * @return N/A
635 */
Andrew Boie468190a2017-09-29 14:00:48 -0700636__syscall void k_wakeup(k_tid_t thread);
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400637
638/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500639 * @brief Get thread ID of the current thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400640 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500641 * @return ID of current thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400642 */
Andrew Boie76c04a22017-09-27 14:45:10 -0700643__syscall k_tid_t k_current_get(void);
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400644
645/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500646 * @brief Cancel thread performing a delayed start.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400647 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500648 * This routine prevents @a thread from executing if it has not yet started
649 * execution. The thread must be re-spawned before it will execute.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400650 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500651 * @param thread ID of thread to cancel.
652 *
David B. Kinder8b986d72017-04-18 15:56:26 -0700653 * @retval 0 Thread spawning canceled.
Allan Stephens9ef50f42016-11-16 15:33:31 -0500654 * @retval -EINVAL Thread has already started executing.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400655 */
Andrew Boie468190a2017-09-29 14:00:48 -0700656__syscall int k_thread_cancel(k_tid_t thread);
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400657
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400658/**
Allan Stephensc98da842016-11-11 15:45:03 -0500659 * @brief Abort a thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400660 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500661 * This routine permanently stops execution of @a thread. The thread is taken
662 * off all kernel queues it is part of (i.e. the ready queue, the timeout
663 * queue, or a kernel object wait queue). However, any kernel resources the
664 * thread might currently own (such as mutexes or memory blocks) are not
665 * released. It is the responsibility of the caller of this routine to ensure
666 * all necessary cleanup is performed.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400667 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500668 * @param thread ID of thread to abort.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400669 *
670 * @return N/A
671 */
Andrew Boie468190a2017-09-29 14:00:48 -0700672__syscall void k_thread_abort(k_tid_t thread);
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400673
Andrew Boie7d627c52017-08-30 11:01:56 -0700674
675/**
676 * @brief Start an inactive thread
677 *
678 * If a thread was created with K_FOREVER in the delay parameter, it will
679 * not be added to the scheduling queue until this function is called
680 * on it.
681 *
682 * @param thread thread to start
683 */
Andrew Boie468190a2017-09-29 14:00:48 -0700684__syscall void k_thread_start(k_tid_t thread);
Andrew Boie7d627c52017-08-30 11:01:56 -0700685
Allan Stephensc98da842016-11-11 15:45:03 -0500686/**
687 * @cond INTERNAL_HIDDEN
688 */
689
Benjamin Walshd211a522016-12-06 11:44:01 -0500690/* timeout has timed out and is not on _timeout_q anymore */
691#define _EXPIRED (-2)
692
693/* timeout is not in use */
694#define _INACTIVE (-1)
695
Peter Mitsisa04c0d72016-09-28 19:26:00 -0400696struct _static_thread_data {
Andrew Boied26cf2d2017-03-30 13:07:02 -0700697 struct k_thread *init_thread;
Andrew Boie507852a2017-07-25 18:47:07 -0700698 k_thread_stack_t init_stack;
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400699 unsigned int init_stack_size;
Andrew Boie1e06ffc2017-09-11 09:30:04 -0700700 k_thread_entry_t init_entry;
Allan Stephens7c5bffa2016-10-26 10:01:28 -0500701 void *init_p1;
702 void *init_p2;
703 void *init_p3;
704 int init_prio;
Kumar Galacc334c72017-04-21 10:55:34 -0500705 u32_t init_options;
706 s32_t init_delay;
Allan Stephens7c5bffa2016-10-26 10:01:28 -0500707 void (*init_abort)(void);
Kumar Galacc334c72017-04-21 10:55:34 -0500708 u32_t init_groups;
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400709};
710
Andrew Boied26cf2d2017-03-30 13:07:02 -0700711#define _THREAD_INITIALIZER(thread, stack, stack_size, \
Peter Mitsisb2fd5be2016-10-11 12:06:25 -0400712 entry, p1, p2, p3, \
Allan Stephens6cfe1322016-10-26 10:16:51 -0500713 prio, options, delay, abort, groups) \
714 { \
Andrew Boied26cf2d2017-03-30 13:07:02 -0700715 .init_thread = (thread), \
716 .init_stack = (stack), \
Allan Stephens6cfe1322016-10-26 10:16:51 -0500717 .init_stack_size = (stack_size), \
Andrew Boie1e06ffc2017-09-11 09:30:04 -0700718 .init_entry = (k_thread_entry_t)entry, \
Peter Mitsisb2fd5be2016-10-11 12:06:25 -0400719 .init_p1 = (void *)p1, \
720 .init_p2 = (void *)p2, \
721 .init_p3 = (void *)p3, \
Allan Stephens6cfe1322016-10-26 10:16:51 -0500722 .init_prio = (prio), \
723 .init_options = (options), \
724 .init_delay = (delay), \
725 .init_abort = (abort), \
726 .init_groups = (groups), \
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400727 }
728
Peter Mitsisb2fd5be2016-10-11 12:06:25 -0400729/**
Allan Stephensc98da842016-11-11 15:45:03 -0500730 * INTERNAL_HIDDEN @endcond
731 */
732
733/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500734 * @brief Statically define and initialize a thread.
735 *
736 * The thread may be scheduled for immediate execution or a delayed start.
737 *
738 * Thread options are architecture-specific, and can include K_ESSENTIAL,
739 * K_FP_REGS, and K_SSE_REGS. Multiple options may be specified by separating
740 * them using "|" (the logical OR operator).
741 *
742 * The ID of the thread can be accessed using:
743 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -0500744 * @code extern const k_tid_t <name>; @endcode
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500745 *
746 * @param name Name of the thread.
747 * @param stack_size Stack size in bytes.
748 * @param entry Thread entry function.
749 * @param p1 1st entry point parameter.
750 * @param p2 2nd entry point parameter.
751 * @param p3 3rd entry point parameter.
752 * @param prio Thread priority.
753 * @param options Thread options.
754 * @param delay Scheduling delay (in milliseconds), or K_NO_WAIT (for no delay).
Peter Mitsisb2fd5be2016-10-11 12:06:25 -0400755 *
756 * @internal It has been observed that the x86 compiler by default aligns
757 * these _static_thread_data structures to 32-byte boundaries, thereby
758 * wasting space. To work around this, force a 4-byte alignment.
759 */
Allan Stephens6cfe1322016-10-26 10:16:51 -0500760#define K_THREAD_DEFINE(name, stack_size, \
761 entry, p1, p2, p3, \
762 prio, options, delay) \
Andrew Boiedc5d9352017-06-02 12:56:47 -0700763 K_THREAD_STACK_DEFINE(_k_thread_stack_##name, stack_size); \
Andrew Boie8749c262017-08-29 12:18:07 -0700764 struct k_thread __kernel _k_thread_obj_##name; \
Allan Stephens6cfe1322016-10-26 10:16:51 -0500765 struct _static_thread_data _k_thread_data_##name __aligned(4) \
Allan Stephense7d2cc22016-10-19 16:10:46 -0500766 __in_section(_static_thread_data, static, name) = \
Andrew Boied26cf2d2017-03-30 13:07:02 -0700767 _THREAD_INITIALIZER(&_k_thread_obj_##name, \
768 _k_thread_stack_##name, stack_size, \
Allan Stephens6cfe1322016-10-26 10:16:51 -0500769 entry, p1, p2, p3, prio, options, delay, \
Andrew Boied26cf2d2017-03-30 13:07:02 -0700770 NULL, 0); \
771 const k_tid_t name = (k_tid_t)&_k_thread_obj_##name
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400772
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400773/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500774 * @brief Get a thread's priority.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400775 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500776 * This routine gets the priority of @a thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400777 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500778 * @param thread ID of thread whose priority is needed.
779 *
780 * @return Priority of @a thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400781 */
Andrew Boie76c04a22017-09-27 14:45:10 -0700782__syscall int k_thread_priority_get(k_tid_t thread);
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400783
784/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500785 * @brief Set a thread's priority.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400786 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500787 * This routine immediately changes the priority of @a thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400788 *
789 * Rescheduling can occur immediately depending on the priority @a thread is
790 * set to:
791 *
792 * - If its priority is raised above the priority of the caller of this
793 * function, and the caller is preemptible, @a thread will be scheduled in.
794 *
795 * - If the caller operates on itself, it lowers its priority below that of
796 * other threads in the system, and the caller is preemptible, the thread of
797 * highest priority will be scheduled in.
798 *
799 * Priority can be assigned in the range of -CONFIG_NUM_COOP_PRIORITIES to
800 * CONFIG_NUM_PREEMPT_PRIORITIES-1, where -CONFIG_NUM_COOP_PRIORITIES is the
801 * highest priority.
802 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500803 * @param thread ID of thread whose priority is to be set.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400804 * @param prio New priority.
805 *
806 * @warning Changing the priority of a thread currently involved in mutex
807 * priority inheritance may result in undefined behavior.
808 *
809 * @return N/A
810 */
Andrew Boie468190a2017-09-29 14:00:48 -0700811__syscall void k_thread_priority_set(k_tid_t thread, int prio);
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400812
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400813/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500814 * @brief Suspend a thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400815 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500816 * This routine prevents the kernel scheduler from making @a thread the
817 * current thread. All other internal operations on @a thread are still
818 * performed; for example, any timeout it is waiting on keeps ticking,
819 * kernel objects it is waiting on are still handed to it, etc.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400820 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500821 * If @a thread is already suspended, the routine has no effect.
822 *
823 * @param thread ID of thread to suspend.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400824 *
825 * @return N/A
826 */
Andrew Boie468190a2017-09-29 14:00:48 -0700827__syscall void k_thread_suspend(k_tid_t thread);
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400828
829/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500830 * @brief Resume a suspended thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400831 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500832 * This routine allows the kernel scheduler to make @a thread the current
833 * thread, when it is next eligible for that role.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400834 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500835 * If @a thread is not currently suspended, the routine has no effect.
836 *
837 * @param thread ID of thread to resume.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400838 *
839 * @return N/A
840 */
Andrew Boie468190a2017-09-29 14:00:48 -0700841__syscall void k_thread_resume(k_tid_t thread);
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400842
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400843/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500844 * @brief Set time-slicing period and scope.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400845 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500846 * This routine specifies how the scheduler will perform time slicing of
847 * preemptible threads.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400848 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500849 * To enable time slicing, @a slice must be non-zero. The scheduler
850 * ensures that no thread runs for more than the specified time limit
851 * before other threads of that priority are given a chance to execute.
852 * Any thread whose priority is higher than @a prio is exempted, and may
David B. Kinder8b986d72017-04-18 15:56:26 -0700853 * execute as long as desired without being preempted due to time slicing.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400854 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500855 * Time slicing only limits the maximum amount of time a thread may continuously
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400856 * execute. Once the scheduler selects a thread for execution, there is no
857 * minimum guaranteed time the thread will execute before threads of greater or
858 * equal priority are scheduled.
859 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500860 * When the current thread is the only one of that priority eligible
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400861 * for execution, this routine has no effect; the thread is immediately
862 * rescheduled after the slice period expires.
863 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500864 * To disable timeslicing, set both @a slice and @a prio to zero.
865 *
866 * @param slice Maximum time slice length (in milliseconds).
867 * @param prio Highest thread priority level eligible for time slicing.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400868 *
869 * @return N/A
870 */
Kumar Galacc334c72017-04-21 10:55:34 -0500871extern void k_sched_time_slice_set(s32_t slice, int prio);
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400872
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400873/**
Allan Stephensc98da842016-11-11 15:45:03 -0500874 * @} end defgroup thread_apis
875 */
876
877/**
878 * @addtogroup isr_apis
879 * @{
880 */
881
882/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500883 * @brief Determine if code is running at interrupt level.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400884 *
Allan Stephensc98da842016-11-11 15:45:03 -0500885 * This routine allows the caller to customize its actions, depending on
886 * whether it is a thread or an ISR.
887 *
888 * @note Can be called by ISRs.
889 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500890 * @return 0 if invoked by a thread.
891 * @return Non-zero if invoked by an ISR.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400892 */
Benjamin Walshc7ba8b12016-11-08 16:12:59 -0500893extern int k_is_in_isr(void);
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400894
Benjamin Walsh445830d2016-11-10 15:54:27 -0500895/**
896 * @brief Determine if code is running in a preemptible thread.
897 *
Allan Stephensc98da842016-11-11 15:45:03 -0500898 * This routine allows the caller to customize its actions, depending on
899 * whether it can be preempted by another thread. The routine returns a 'true'
900 * value if all of the following conditions are met:
Benjamin Walsh445830d2016-11-10 15:54:27 -0500901 *
Allan Stephensc98da842016-11-11 15:45:03 -0500902 * - The code is running in a thread, not at ISR.
903 * - The thread's priority is in the preemptible range.
904 * - The thread has not locked the scheduler.
Benjamin Walsh445830d2016-11-10 15:54:27 -0500905 *
Allan Stephensc98da842016-11-11 15:45:03 -0500906 * @note Can be called by ISRs.
907 *
908 * @return 0 if invoked by an ISR or by a cooperative thread.
Benjamin Walsh445830d2016-11-10 15:54:27 -0500909 * @return Non-zero if invoked by a preemptible thread.
910 */
Andrew Boie468190a2017-09-29 14:00:48 -0700911__syscall int k_is_preempt_thread(void);
Benjamin Walsh445830d2016-11-10 15:54:27 -0500912
Allan Stephensc98da842016-11-11 15:45:03 -0500913/**
914 * @} end addtogroup isr_apis
915 */
916
917/**
918 * @addtogroup thread_apis
919 * @{
920 */
921
922/**
923 * @brief Lock the scheduler.
Benjamin Walshd7ad1762016-11-10 14:46:58 -0500924 *
Allan Stephensc98da842016-11-11 15:45:03 -0500925 * This routine prevents the current thread from being preempted by another
926 * thread by instructing the scheduler to treat it as a cooperative thread.
927 * If the thread subsequently performs an operation that makes it unready,
928 * it will be context switched out in the normal manner. When the thread
929 * again becomes the current thread, its non-preemptible status is maintained.
Benjamin Walshd7ad1762016-11-10 14:46:58 -0500930 *
Allan Stephensc98da842016-11-11 15:45:03 -0500931 * This routine can be called recursively.
Benjamin Walshd7ad1762016-11-10 14:46:58 -0500932 *
Allan Stephensc98da842016-11-11 15:45:03 -0500933 * @note k_sched_lock() and k_sched_unlock() should normally be used
934 * when the operation being performed can be safely interrupted by ISRs.
935 * However, if the amount of processing involved is very small, better
936 * performance may be obtained by using irq_lock() and irq_unlock().
Benjamin Walshd7ad1762016-11-10 14:46:58 -0500937 *
938 * @return N/A
939 */
940extern void k_sched_lock(void);
941
Allan Stephensc98da842016-11-11 15:45:03 -0500942/**
943 * @brief Unlock the scheduler.
Benjamin Walshd7ad1762016-11-10 14:46:58 -0500944 *
Allan Stephensc98da842016-11-11 15:45:03 -0500945 * This routine reverses the effect of a previous call to k_sched_lock().
946 * A thread must call the routine once for each time it called k_sched_lock()
947 * before the thread becomes preemptible.
Benjamin Walshd7ad1762016-11-10 14:46:58 -0500948 *
949 * @return N/A
950 */
951extern void k_sched_unlock(void);
952
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400953/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500954 * @brief Set current thread's custom data.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400955 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500956 * This routine sets the custom data for the current thread to @ value.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400957 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500958 * Custom data is not used by the kernel itself, and is freely available
959 * for a thread to use as it sees fit. It can be used as a framework
960 * upon which to build thread-local storage.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400961 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500962 * @param value New custom data value.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400963 *
964 * @return N/A
965 */
Andrew Boie468190a2017-09-29 14:00:48 -0700966__syscall void k_thread_custom_data_set(void *value);
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400967
968/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500969 * @brief Get current thread's custom data.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400970 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500971 * This routine returns the custom data for the current thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400972 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -0500973 * @return Current custom data value.
Peter Mitsis348eb4c2016-10-26 11:22:14 -0400974 */
Andrew Boie468190a2017-09-29 14:00:48 -0700975__syscall void *k_thread_custom_data_get(void);
Benjamin Walsh456c6da2016-09-02 18:55:39 -0400976
977/**
Allan Stephensc98da842016-11-11 15:45:03 -0500978 * @} end addtogroup thread_apis
979 */
980
Benjamin Walsha9604bd2016-09-21 11:05:56 -0400981#include <sys_clock.h>
982
Allan Stephensc2f15a42016-11-17 12:24:22 -0500983/**
984 * @addtogroup clock_apis
985 * @{
986 */
987
988/**
989 * @brief Generate null timeout delay.
990 *
991 * This macro generates a timeout delay that that instructs a kernel API
992 * not to wait if the requested operation cannot be performed immediately.
993 *
994 * @return Timeout delay value.
995 */
996#define K_NO_WAIT 0
997
998/**
999 * @brief Generate timeout delay from milliseconds.
1000 *
1001 * This macro generates a timeout delay that that instructs a kernel API
1002 * to wait up to @a ms milliseconds to perform the requested operation.
1003 *
1004 * @param ms Duration in milliseconds.
1005 *
1006 * @return Timeout delay value.
1007 */
Johan Hedberg14471692016-11-13 10:52:15 +02001008#define K_MSEC(ms) (ms)
Allan Stephensc2f15a42016-11-17 12:24:22 -05001009
1010/**
1011 * @brief Generate timeout delay from seconds.
1012 *
1013 * This macro generates a timeout delay that that instructs a kernel API
1014 * to wait up to @a s seconds to perform the requested operation.
1015 *
1016 * @param s Duration in seconds.
1017 *
1018 * @return Timeout delay value.
1019 */
Johan Hedberg14471692016-11-13 10:52:15 +02001020#define K_SECONDS(s) K_MSEC((s) * MSEC_PER_SEC)
Allan Stephensc2f15a42016-11-17 12:24:22 -05001021
1022/**
1023 * @brief Generate timeout delay from minutes.
1024 *
1025 * This macro generates a timeout delay that that instructs a kernel API
1026 * to wait up to @a m minutes to perform the requested operation.
1027 *
1028 * @param m Duration in minutes.
1029 *
1030 * @return Timeout delay value.
1031 */
Johan Hedberg14471692016-11-13 10:52:15 +02001032#define K_MINUTES(m) K_SECONDS((m) * 60)
Allan Stephensc2f15a42016-11-17 12:24:22 -05001033
1034/**
1035 * @brief Generate timeout delay from hours.
1036 *
1037 * This macro generates a timeout delay that that instructs a kernel API
1038 * to wait up to @a h hours to perform the requested operation.
1039 *
1040 * @param h Duration in hours.
1041 *
1042 * @return Timeout delay value.
1043 */
Johan Hedberg14471692016-11-13 10:52:15 +02001044#define K_HOURS(h) K_MINUTES((h) * 60)
1045
Allan Stephensc98da842016-11-11 15:45:03 -05001046/**
Allan Stephensc2f15a42016-11-17 12:24:22 -05001047 * @brief Generate infinite timeout delay.
1048 *
1049 * This macro generates a timeout delay that that instructs a kernel API
1050 * to wait as long as necessary to perform the requested operation.
1051 *
1052 * @return Timeout delay value.
1053 */
1054#define K_FOREVER (-1)
1055
1056/**
1057 * @} end addtogroup clock_apis
1058 */
1059
1060/**
Allan Stephensc98da842016-11-11 15:45:03 -05001061 * @cond INTERNAL_HIDDEN
1062 */
Benjamin Walsha9604bd2016-09-21 11:05:56 -04001063
Benjamin Walsh62092182016-12-20 14:39:08 -05001064/* kernel clocks */
1065
1066#if (sys_clock_ticks_per_sec == 1000) || \
1067 (sys_clock_ticks_per_sec == 500) || \
1068 (sys_clock_ticks_per_sec == 250) || \
1069 (sys_clock_ticks_per_sec == 125) || \
1070 (sys_clock_ticks_per_sec == 100) || \
1071 (sys_clock_ticks_per_sec == 50) || \
1072 (sys_clock_ticks_per_sec == 25) || \
1073 (sys_clock_ticks_per_sec == 20) || \
1074 (sys_clock_ticks_per_sec == 10) || \
1075 (sys_clock_ticks_per_sec == 1)
1076
1077 #define _ms_per_tick (MSEC_PER_SEC / sys_clock_ticks_per_sec)
1078#else
1079 /* yields horrible 64-bit math on many architectures: try to avoid */
1080 #define _NON_OPTIMIZED_TICKS_PER_SEC
1081#endif
1082
1083#ifdef _NON_OPTIMIZED_TICKS_PER_SEC
Kumar Galacc334c72017-04-21 10:55:34 -05001084extern s32_t _ms_to_ticks(s32_t ms);
Benjamin Walsh62092182016-12-20 14:39:08 -05001085#else
Kumar Galacc334c72017-04-21 10:55:34 -05001086static ALWAYS_INLINE s32_t _ms_to_ticks(s32_t ms)
Benjamin Walsh62092182016-12-20 14:39:08 -05001087{
Kumar Galacc334c72017-04-21 10:55:34 -05001088 return (s32_t)ceiling_fraction((u32_t)ms, _ms_per_tick);
Benjamin Walsh62092182016-12-20 14:39:08 -05001089}
1090#endif
1091
Allan Stephens6c98c4d2016-10-17 14:34:53 -05001092/* added tick needed to account for tick in progress */
Ramesh Thomas89ffd442017-02-05 19:37:19 -08001093#ifdef CONFIG_TICKLESS_KERNEL
1094#define _TICK_ALIGN 0
1095#else
Allan Stephens6c98c4d2016-10-17 14:34:53 -05001096#define _TICK_ALIGN 1
Ramesh Thomas89ffd442017-02-05 19:37:19 -08001097#endif
Allan Stephens6c98c4d2016-10-17 14:34:53 -05001098
Kumar Galacc334c72017-04-21 10:55:34 -05001099static inline s64_t __ticks_to_ms(s64_t ticks)
Benjamin Walsha9604bd2016-09-21 11:05:56 -04001100{
Benjamin Walsh62092182016-12-20 14:39:08 -05001101#ifdef CONFIG_SYS_CLOCK_EXISTS
1102
1103#ifdef _NON_OPTIMIZED_TICKS_PER_SEC
Kumar Galacc334c72017-04-21 10:55:34 -05001104 return (MSEC_PER_SEC * (u64_t)ticks) / sys_clock_ticks_per_sec;
Benjamin Walsh57d55dc2016-10-04 16:58:08 -04001105#else
Kumar Galacc334c72017-04-21 10:55:34 -05001106 return (u64_t)ticks * _ms_per_tick;
Benjamin Walsh62092182016-12-20 14:39:08 -05001107#endif
1108
1109#else
Benjamin Walsh57d55dc2016-10-04 16:58:08 -04001110 __ASSERT(ticks == 0, "");
1111 return 0;
1112#endif
Benjamin Walsha9604bd2016-09-21 11:05:56 -04001113}
1114
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001115struct k_timer {
1116 /*
1117 * _timeout structure must be first here if we want to use
1118 * dynamic timer allocation. timeout.node is used in the double-linked
1119 * list of free timers
1120 */
1121 struct _timeout timeout;
1122
Allan Stephens45bfa372016-10-12 12:39:42 -05001123 /* wait queue for the (single) thread waiting on this timer */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001124 _wait_q_t wait_q;
1125
1126 /* runs in ISR context */
Allan Stephens45bfa372016-10-12 12:39:42 -05001127 void (*expiry_fn)(struct k_timer *);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001128
1129 /* runs in the context of the thread that calls k_timer_stop() */
Allan Stephens45bfa372016-10-12 12:39:42 -05001130 void (*stop_fn)(struct k_timer *);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001131
1132 /* timer period */
Kumar Galacc334c72017-04-21 10:55:34 -05001133 s32_t period;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001134
Allan Stephens45bfa372016-10-12 12:39:42 -05001135 /* timer status */
Kumar Galacc334c72017-04-21 10:55:34 -05001136 u32_t status;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001137
Benjamin Walshe4e98f92017-01-12 19:38:53 -05001138 /* user-specific data, also used to support legacy features */
1139 void *user_data;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001140
Anas Nashif2f203c22016-12-18 06:57:45 -05001141 _OBJECT_TRACING_NEXT_PTR(k_timer);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001142};
1143
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001144#define _K_TIMER_INITIALIZER(obj, expiry, stop) \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001145 { \
Benjamin Walshd211a522016-12-06 11:44:01 -05001146 .timeout.delta_ticks_from_prev = _INACTIVE, \
Allan Stephens1342adb2016-11-03 13:54:53 -05001147 .timeout.wait_q = NULL, \
1148 .timeout.thread = NULL, \
1149 .timeout.func = _timer_expiration_handler, \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001150 .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \
Allan Stephens1342adb2016-11-03 13:54:53 -05001151 .expiry_fn = expiry, \
1152 .stop_fn = stop, \
1153 .status = 0, \
Benjamin Walshe4e98f92017-01-12 19:38:53 -05001154 .user_data = 0, \
Anas Nashif2f203c22016-12-18 06:57:45 -05001155 _OBJECT_TRACING_INIT \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001156 }
1157
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001158#define K_TIMER_INITIALIZER DEPRECATED_MACRO _K_TIMER_INITIALIZER
1159
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001160/**
Allan Stephensc98da842016-11-11 15:45:03 -05001161 * INTERNAL_HIDDEN @endcond
1162 */
1163
1164/**
1165 * @defgroup timer_apis Timer APIs
1166 * @ingroup kernel_apis
1167 * @{
1168 */
1169
1170/**
Allan Stephens5eceb852016-11-16 10:16:30 -05001171 * @typedef k_timer_expiry_t
1172 * @brief Timer expiry function type.
1173 *
1174 * A timer's expiry function is executed by the system clock interrupt handler
1175 * each time the timer expires. The expiry function is optional, and is only
1176 * invoked if the timer has been initialized with one.
1177 *
1178 * @param timer Address of timer.
1179 *
1180 * @return N/A
1181 */
1182typedef void (*k_timer_expiry_t)(struct k_timer *timer);
1183
1184/**
1185 * @typedef k_timer_stop_t
1186 * @brief Timer stop function type.
1187 *
1188 * A timer's stop function is executed if the timer is stopped prematurely.
1189 * The function runs in the context of the thread that stops the timer.
1190 * The stop function is optional, and is only invoked if the timer has been
1191 * initialized with one.
1192 *
1193 * @param timer Address of timer.
1194 *
1195 * @return N/A
1196 */
1197typedef void (*k_timer_stop_t)(struct k_timer *timer);
1198
1199/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001200 * @brief Statically define and initialize a timer.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001201 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001202 * The timer can be accessed outside the module where it is defined using:
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001203 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05001204 * @code extern struct k_timer <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001205 *
1206 * @param name Name of the timer variable.
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001207 * @param expiry_fn Function to invoke each time the timer expires.
1208 * @param stop_fn Function to invoke if the timer is stopped while running.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001209 */
Allan Stephens1342adb2016-11-03 13:54:53 -05001210#define K_TIMER_DEFINE(name, expiry_fn, stop_fn) \
Allan Stephense7d2cc22016-10-19 16:10:46 -05001211 struct k_timer name \
1212 __in_section(_k_timer, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001213 _K_TIMER_INITIALIZER(name, expiry_fn, stop_fn)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001214
Allan Stephens45bfa372016-10-12 12:39:42 -05001215/**
1216 * @brief Initialize a timer.
1217 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001218 * This routine initializes a timer, prior to its first use.
Allan Stephens45bfa372016-10-12 12:39:42 -05001219 *
1220 * @param timer Address of timer.
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001221 * @param expiry_fn Function to invoke each time the timer expires.
1222 * @param stop_fn Function to invoke if the timer is stopped while running.
Allan Stephens45bfa372016-10-12 12:39:42 -05001223 *
1224 * @return N/A
1225 */
1226extern void k_timer_init(struct k_timer *timer,
Allan Stephens5eceb852016-11-16 10:16:30 -05001227 k_timer_expiry_t expiry_fn,
1228 k_timer_stop_t stop_fn);
Andy Ross8d8b2ac2016-09-23 10:08:54 -07001229
Allan Stephens45bfa372016-10-12 12:39:42 -05001230/**
1231 * @brief Start a timer.
1232 *
1233 * This routine starts a timer, and resets its status to zero. The timer
1234 * begins counting down using the specified duration and period values.
1235 *
1236 * Attempting to start a timer that is already running is permitted.
1237 * The timer's status is reset to zero and the timer begins counting down
1238 * using the new duration and period values.
1239 *
1240 * @param timer Address of timer.
1241 * @param duration Initial timer duration (in milliseconds).
1242 * @param period Timer period (in milliseconds).
1243 *
1244 * @return N/A
1245 */
Andrew Boiea354d492017-09-29 16:22:28 -07001246__syscall void k_timer_start(struct k_timer *timer,
1247 s32_t duration, s32_t period);
Allan Stephens45bfa372016-10-12 12:39:42 -05001248
1249/**
1250 * @brief Stop a timer.
1251 *
1252 * This routine stops a running timer prematurely. The timer's stop function,
1253 * if one exists, is invoked by the caller.
1254 *
1255 * Attempting to stop a timer that is not running is permitted, but has no
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001256 * effect on the timer.
Allan Stephens45bfa372016-10-12 12:39:42 -05001257 *
Anas Nashif4fb12ae2017-02-01 20:06:55 -05001258 * @note Can be called by ISRs. The stop handler has to be callable from ISRs
1259 * if @a k_timer_stop is to be called from ISRs.
1260 *
Allan Stephens45bfa372016-10-12 12:39:42 -05001261 * @param timer Address of timer.
1262 *
1263 * @return N/A
1264 */
Andrew Boiea354d492017-09-29 16:22:28 -07001265__syscall void k_timer_stop(struct k_timer *timer);
Allan Stephens45bfa372016-10-12 12:39:42 -05001266
1267/**
1268 * @brief Read timer status.
1269 *
1270 * This routine reads the timer's status, which indicates the number of times
1271 * it has expired since its status was last read.
1272 *
1273 * Calling this routine resets the timer's status to zero.
1274 *
1275 * @param timer Address of timer.
1276 *
1277 * @return Timer status.
1278 */
Andrew Boiea354d492017-09-29 16:22:28 -07001279__syscall u32_t k_timer_status_get(struct k_timer *timer);
Allan Stephens45bfa372016-10-12 12:39:42 -05001280
1281/**
1282 * @brief Synchronize thread to timer expiration.
1283 *
1284 * This routine blocks the calling thread until the timer's status is non-zero
1285 * (indicating that it has expired at least once since it was last examined)
1286 * or the timer is stopped. If the timer status is already non-zero,
1287 * or the timer is already stopped, the caller continues without waiting.
1288 *
1289 * Calling this routine resets the timer's status to zero.
1290 *
1291 * This routine must not be used by interrupt handlers, since they are not
1292 * allowed to block.
1293 *
1294 * @param timer Address of timer.
1295 *
1296 * @return Timer status.
1297 */
Andrew Boiea354d492017-09-29 16:22:28 -07001298__syscall u32_t k_timer_status_sync(struct k_timer *timer);
Allan Stephens45bfa372016-10-12 12:39:42 -05001299
1300/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001301 * @brief Get time remaining before a timer next expires.
Allan Stephens45bfa372016-10-12 12:39:42 -05001302 *
1303 * This routine computes the (approximate) time remaining before a running
1304 * timer next expires. If the timer is not running, it returns zero.
1305 *
1306 * @param timer Address of timer.
1307 *
1308 * @return Remaining time (in milliseconds).
1309 */
Andrew Boiea354d492017-09-29 16:22:28 -07001310__syscall s32_t k_timer_remaining_get(struct k_timer *timer);
1311
1312static inline s32_t _impl_k_timer_remaining_get(struct k_timer *timer)
Johan Hedbergf99ad3f2016-12-09 10:39:49 +02001313{
1314 return _timeout_remaining_get(&timer->timeout);
1315}
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001316
Allan Stephensc98da842016-11-11 15:45:03 -05001317/**
Benjamin Walshe4e98f92017-01-12 19:38:53 -05001318 * @brief Associate user-specific data with a timer.
1319 *
1320 * This routine records the @a user_data with the @a timer, to be retrieved
1321 * later.
1322 *
1323 * It can be used e.g. in a timer handler shared across multiple subsystems to
1324 * retrieve data specific to the subsystem this timer is associated with.
1325 *
1326 * @param timer Address of timer.
1327 * @param user_data User data to associate with the timer.
1328 *
1329 * @return N/A
1330 */
Andrew Boiea354d492017-09-29 16:22:28 -07001331__syscall void k_timer_user_data_set(struct k_timer *timer, void *user_data);
1332
1333static inline void _impl_k_timer_user_data_set(struct k_timer *timer,
1334 void *user_data)
Benjamin Walshe4e98f92017-01-12 19:38:53 -05001335{
1336 timer->user_data = user_data;
1337}
1338
1339/**
1340 * @brief Retrieve the user-specific data from a timer.
1341 *
1342 * @param timer Address of timer.
1343 *
1344 * @return The user data.
1345 */
Andrew Boiea354d492017-09-29 16:22:28 -07001346__syscall void *k_timer_user_data_get(struct k_timer *timer);
1347
1348static inline void *_impl_k_timer_user_data_get(struct k_timer *timer)
Benjamin Walshe4e98f92017-01-12 19:38:53 -05001349{
1350 return timer->user_data;
1351}
1352
1353/**
Allan Stephensc98da842016-11-11 15:45:03 -05001354 * @} end defgroup timer_apis
1355 */
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001356
Allan Stephensc98da842016-11-11 15:45:03 -05001357/**
Allan Stephensc2f15a42016-11-17 12:24:22 -05001358 * @addtogroup clock_apis
Allan Stephensc98da842016-11-11 15:45:03 -05001359 * @{
1360 */
Allan Stephens45bfa372016-10-12 12:39:42 -05001361
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001362/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001363 * @brief Get system uptime.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001364 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001365 * This routine returns the elapsed time since the system booted,
1366 * in milliseconds.
1367 *
1368 * @return Current uptime.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001369 */
Kumar Galacc334c72017-04-21 10:55:34 -05001370extern s64_t k_uptime_get(void);
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001371
Ramesh Thomas89ffd442017-02-05 19:37:19 -08001372#ifdef CONFIG_TICKLESS_KERNEL
1373/**
1374 * @brief Enable clock always on in tickless kernel
1375 *
David B. Kinderfc5f2b32017-05-02 17:21:56 -07001376 * This routine enables keeping the clock running when
Ramesh Thomas89ffd442017-02-05 19:37:19 -08001377 * there are no timer events programmed in tickless kernel
1378 * scheduling. This is necessary if the clock is used to track
1379 * passage of time.
1380 *
1381 * @retval prev_status Previous status of always on flag
1382 */
1383static inline int k_enable_sys_clock_always_on(void)
1384{
1385 int prev_status = _sys_clock_always_on;
1386
1387 _sys_clock_always_on = 1;
1388 _enable_sys_clock();
1389
1390 return prev_status;
1391}
1392
1393/**
1394 * @brief Disable clock always on in tickless kernel
1395 *
David B. Kinderfc5f2b32017-05-02 17:21:56 -07001396 * This routine disables keeping the clock running when
Ramesh Thomas89ffd442017-02-05 19:37:19 -08001397 * there are no timer events programmed in tickless kernel
1398 * scheduling. To save power, this routine should be called
1399 * immediately when clock is not used to track time.
1400 */
1401static inline void k_disable_sys_clock_always_on(void)
1402{
1403 _sys_clock_always_on = 0;
1404}
1405#else
1406#define k_enable_sys_clock_always_on() do { } while ((0))
1407#define k_disable_sys_clock_always_on() do { } while ((0))
1408#endif
1409
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001410/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001411 * @brief Get system uptime (32-bit version).
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001412 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001413 * This routine returns the lower 32-bits of the elapsed time since the system
1414 * booted, in milliseconds.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001415 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001416 * This routine can be more efficient than k_uptime_get(), as it reduces the
1417 * need for interrupt locking and 64-bit math. However, the 32-bit result
1418 * cannot hold a system uptime time larger than approximately 50 days, so the
1419 * caller must handle possible rollovers.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001420 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001421 * @return Current uptime.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001422 */
Andrew Boie76c04a22017-09-27 14:45:10 -07001423__syscall u32_t k_uptime_get_32(void);
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001424
1425/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001426 * @brief Get elapsed time.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001427 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001428 * This routine computes the elapsed time between the current system uptime
1429 * and an earlier reference time, in milliseconds.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001430 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001431 * @param reftime Pointer to a reference time, which is updated to the current
1432 * uptime upon return.
1433 *
1434 * @return Elapsed time.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001435 */
Kumar Galacc334c72017-04-21 10:55:34 -05001436extern s64_t k_uptime_delta(s64_t *reftime);
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001437
1438/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001439 * @brief Get elapsed time (32-bit version).
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001440 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001441 * This routine computes the elapsed time between the current system uptime
1442 * and an earlier reference time, in milliseconds.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001443 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001444 * This routine can be more efficient than k_uptime_delta(), as it reduces the
1445 * need for interrupt locking and 64-bit math. However, the 32-bit result
1446 * cannot hold an elapsed time larger than approximately 50 days, so the
1447 * caller must handle possible rollovers.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001448 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001449 * @param reftime Pointer to a reference time, which is updated to the current
1450 * uptime upon return.
1451 *
1452 * @return Elapsed time.
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001453 */
Kumar Galacc334c72017-04-21 10:55:34 -05001454extern u32_t k_uptime_delta_32(s64_t *reftime);
Benjamin Walshba5ddc12016-09-21 16:01:22 -04001455
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001456/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001457 * @brief Read the hardware clock.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001458 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001459 * This routine returns the current time, as measured by the system's hardware
1460 * clock.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001461 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001462 * @return Current hardware clock up-counter (in cycles).
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001463 */
Andrew Boiee08d07c2017-02-15 13:40:17 -08001464#define k_cycle_get_32() _arch_k_cycle_get_32()
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001465
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001466/**
Allan Stephensc2f15a42016-11-17 12:24:22 -05001467 * @} end addtogroup clock_apis
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001468 */
1469
Allan Stephensc98da842016-11-11 15:45:03 -05001470/**
1471 * @cond INTERNAL_HIDDEN
1472 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001473
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001474struct k_queue {
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001475 sys_slist_t data_q;
Luiz Augusto von Dentz84db6412017-07-13 12:43:59 +03001476 union {
1477 _wait_q_t wait_q;
1478
1479 _POLL_EVENT;
1480 };
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001481
1482 _OBJECT_TRACING_NEXT_PTR(k_queue);
1483};
1484
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001485#define _K_QUEUE_INITIALIZER(obj) \
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001486 { \
1487 .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \
1488 .data_q = SYS_SLIST_STATIC_INIT(&obj.data_q), \
Luiz Augusto von Dentz7d01c5e2017-08-21 10:49:29 +03001489 _POLL_EVENT_OBJ_INIT(obj) \
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001490 _OBJECT_TRACING_INIT \
1491 }
1492
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001493#define K_QUEUE_INITIALIZER DEPRECATED_MACRO _K_QUEUE_INITIALIZER
1494
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001495/**
1496 * INTERNAL_HIDDEN @endcond
1497 */
1498
1499/**
1500 * @defgroup queue_apis Queue APIs
1501 * @ingroup kernel_apis
1502 * @{
1503 */
1504
1505/**
1506 * @brief Initialize a queue.
1507 *
1508 * This routine initializes a queue object, prior to its first use.
1509 *
1510 * @param queue Address of the queue.
1511 *
1512 * @return N/A
1513 */
1514extern void k_queue_init(struct k_queue *queue);
1515
1516/**
Paul Sokolovsky3f507072017-04-25 17:54:31 +03001517 * @brief Cancel waiting on a queue.
1518 *
1519 * This routine causes first thread pending on @a queue, if any, to
1520 * return from k_queue_get() call with NULL value (as if timeout expired).
1521 *
1522 * @note Can be called by ISRs.
1523 *
1524 * @param queue Address of the queue.
1525 *
1526 * @return N/A
1527 */
1528extern void k_queue_cancel_wait(struct k_queue *queue);
1529
1530/**
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001531 * @brief Append an element to the end of a queue.
1532 *
1533 * This routine appends a data item to @a queue. A queue data item must be
1534 * aligned on a 4-byte boundary, and the first 32 bits of the item are
1535 * reserved for the kernel's use.
1536 *
1537 * @note Can be called by ISRs.
1538 *
1539 * @param queue Address of the queue.
1540 * @param data Address of the data item.
1541 *
1542 * @return N/A
1543 */
1544extern void k_queue_append(struct k_queue *queue, void *data);
1545
1546/**
1547 * @brief Prepend an element to a queue.
1548 *
1549 * This routine prepends a data item to @a queue. A queue data item must be
1550 * aligned on a 4-byte boundary, and the first 32 bits of the item are
1551 * reserved for the kernel's use.
1552 *
1553 * @note Can be called by ISRs.
1554 *
1555 * @param queue Address of the queue.
1556 * @param data Address of the data item.
1557 *
1558 * @return N/A
1559 */
1560extern void k_queue_prepend(struct k_queue *queue, void *data);
1561
1562/**
1563 * @brief Inserts an element to a queue.
1564 *
1565 * This routine inserts a data item to @a queue after previous item. A queue
1566 * data item must be aligned on a 4-byte boundary, and the first 32 bits of the
1567 * item are reserved for the kernel's use.
1568 *
1569 * @note Can be called by ISRs.
1570 *
1571 * @param queue Address of the queue.
1572 * @param prev Address of the previous data item.
1573 * @param data Address of the data item.
1574 *
1575 * @return N/A
1576 */
1577extern void k_queue_insert(struct k_queue *queue, void *prev, void *data);
1578
1579/**
1580 * @brief Atomically append a list of elements to a queue.
1581 *
1582 * This routine adds a list of data items to @a queue in one operation.
1583 * The data items must be in a singly-linked list, with the first 32 bits
1584 * in each data item pointing to the next data item; the list must be
1585 * NULL-terminated.
1586 *
1587 * @note Can be called by ISRs.
1588 *
1589 * @param queue Address of the queue.
1590 * @param head Pointer to first node in singly-linked list.
1591 * @param tail Pointer to last node in singly-linked list.
1592 *
1593 * @return N/A
1594 */
1595extern void k_queue_append_list(struct k_queue *queue, void *head, void *tail);
1596
1597/**
1598 * @brief Atomically add a list of elements to a queue.
1599 *
1600 * This routine adds a list of data items to @a queue in one operation.
1601 * The data items must be in a singly-linked list implemented using a
1602 * sys_slist_t object. Upon completion, the original list is empty.
1603 *
1604 * @note Can be called by ISRs.
1605 *
1606 * @param queue Address of the queue.
1607 * @param list Pointer to sys_slist_t object.
1608 *
1609 * @return N/A
1610 */
1611extern void k_queue_merge_slist(struct k_queue *queue, sys_slist_t *list);
1612
1613/**
1614 * @brief Get an element from a queue.
1615 *
1616 * This routine removes first data item from @a queue. The first 32 bits of the
1617 * data item are reserved for the kernel's use.
1618 *
1619 * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT.
1620 *
1621 * @param queue Address of the queue.
1622 * @param timeout Waiting period to obtain a data item (in milliseconds),
1623 * or one of the special values K_NO_WAIT and K_FOREVER.
1624 *
1625 * @return Address of the data item if successful; NULL if returned
1626 * without waiting, or waiting period timed out.
1627 */
Kumar Galacc334c72017-04-21 10:55:34 -05001628extern void *k_queue_get(struct k_queue *queue, s32_t timeout);
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001629
1630/**
Luiz Augusto von Dentz50b93772017-07-03 16:52:45 +03001631 * @brief Remove an element from a queue.
1632 *
1633 * This routine removes data item from @a queue. The first 32 bits of the
1634 * data item are reserved for the kernel's use. Removing elements from k_queue
1635 * rely on sys_slist_find_and_remove which is not a constant time operation.
1636 *
1637 * @note Can be called by ISRs
1638 *
1639 * @param queue Address of the queue.
1640 * @param data Address of the data item.
1641 *
1642 * @return true if data item was removed
1643 */
1644static inline bool k_queue_remove(struct k_queue *queue, void *data)
1645{
1646 return sys_slist_find_and_remove(&queue->data_q, (sys_snode_t *)data);
1647}
1648
1649/**
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001650 * @brief Query a queue to see if it has data available.
1651 *
1652 * Note that the data might be already gone by the time this function returns
1653 * if other threads are also trying to read from the queue.
1654 *
1655 * @note Can be called by ISRs.
1656 *
1657 * @param queue Address of the queue.
1658 *
1659 * @return Non-zero if the queue is empty.
1660 * @return 0 if data is available.
1661 */
1662static inline int k_queue_is_empty(struct k_queue *queue)
1663{
1664 return (int)sys_slist_is_empty(&queue->data_q);
1665}
1666
1667/**
Paul Sokolovsky16bb3ec2017-06-08 17:13:03 +03001668 * @brief Peek element at the head of queue.
1669 *
1670 * Return element from the head of queue without removing it.
1671 *
1672 * @param queue Address of the queue.
1673 *
1674 * @return Head element, or NULL if queue is empty.
1675 */
1676static inline void *k_queue_peek_head(struct k_queue *queue)
1677{
1678 return sys_slist_peek_head(&queue->data_q);
1679}
1680
1681/**
1682 * @brief Peek element at the tail of queue.
1683 *
1684 * Return element from the tail of queue without removing it.
1685 *
1686 * @param queue Address of the queue.
1687 *
1688 * @return Tail element, or NULL if queue is empty.
1689 */
1690static inline void *k_queue_peek_tail(struct k_queue *queue)
1691{
1692 return sys_slist_peek_tail(&queue->data_q);
1693}
1694
1695/**
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001696 * @brief Statically define and initialize a queue.
1697 *
1698 * The queue can be accessed outside the module where it is defined using:
1699 *
1700 * @code extern struct k_queue <name>; @endcode
1701 *
1702 * @param name Name of the queue.
1703 */
1704#define K_QUEUE_DEFINE(name) \
1705 struct k_queue name \
1706 __in_section(_k_queue, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001707 _K_QUEUE_INITIALIZER(name)
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02001708
1709/**
1710 * @} end defgroup queue_apis
1711 */
1712
1713/**
1714 * @cond INTERNAL_HIDDEN
1715 */
1716
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001717struct k_fifo {
Luiz Augusto von Dentze5ed88f2017-02-21 15:27:20 +02001718 struct k_queue _queue;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001719};
1720
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001721#define _K_FIFO_INITIALIZER(obj) \
Allan Stephensc98da842016-11-11 15:45:03 -05001722 { \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001723 ._queue = _K_QUEUE_INITIALIZER(obj._queue) \
Allan Stephensc98da842016-11-11 15:45:03 -05001724 }
1725
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001726#define K_FIFO_INITIALIZER DEPRECATED_MACRO _K_FIFO_INITIALIZER
1727
Allan Stephensc98da842016-11-11 15:45:03 -05001728/**
1729 * INTERNAL_HIDDEN @endcond
1730 */
1731
1732/**
1733 * @defgroup fifo_apis Fifo APIs
1734 * @ingroup kernel_apis
1735 * @{
1736 */
1737
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001738/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001739 * @brief Initialize a fifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001740 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001741 * This routine initializes a fifo object, prior to its first use.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001742 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001743 * @param fifo Address of the fifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001744 *
1745 * @return N/A
1746 */
Luiz Augusto von Dentze5ed88f2017-02-21 15:27:20 +02001747#define k_fifo_init(fifo) \
1748 k_queue_init((struct k_queue *) fifo)
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001749
1750/**
Paul Sokolovsky3f507072017-04-25 17:54:31 +03001751 * @brief Cancel waiting on a fifo.
1752 *
1753 * This routine causes first thread pending on @a fifo, if any, to
1754 * return from k_fifo_get() call with NULL value (as if timeout
1755 * expired).
1756 *
1757 * @note Can be called by ISRs.
1758 *
1759 * @param fifo Address of the fifo.
1760 *
1761 * @return N/A
1762 */
1763#define k_fifo_cancel_wait(fifo) \
1764 k_queue_cancel_wait((struct k_queue *) fifo)
1765
1766/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001767 * @brief Add an element to a fifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001768 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001769 * This routine adds a data item to @a fifo. A fifo data item must be
1770 * aligned on a 4-byte boundary, and the first 32 bits of the item are
1771 * reserved for the kernel's use.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001772 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001773 * @note Can be called by ISRs.
1774 *
1775 * @param fifo Address of the fifo.
1776 * @param data Address of the data item.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001777 *
1778 * @return N/A
1779 */
Luiz Augusto von Dentze5ed88f2017-02-21 15:27:20 +02001780#define k_fifo_put(fifo, data) \
1781 k_queue_append((struct k_queue *) fifo, data)
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001782
1783/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001784 * @brief Atomically add a list of elements to a fifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001785 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001786 * This routine adds a list of data items to @a fifo in one operation.
1787 * The data items must be in a singly-linked list, with the first 32 bits
1788 * each data item pointing to the next data item; the list must be
1789 * NULL-terminated.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001790 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001791 * @note Can be called by ISRs.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001792 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001793 * @param fifo Address of the fifo.
1794 * @param head Pointer to first node in singly-linked list.
1795 * @param tail Pointer to last node in singly-linked list.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001796 *
1797 * @return N/A
1798 */
Luiz Augusto von Dentze5ed88f2017-02-21 15:27:20 +02001799#define k_fifo_put_list(fifo, head, tail) \
1800 k_queue_append_list((struct k_queue *) fifo, head, tail)
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001801
1802/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001803 * @brief Atomically add a list of elements to a fifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001804 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001805 * This routine adds a list of data items to @a fifo in one operation.
1806 * The data items must be in a singly-linked list implemented using a
1807 * sys_slist_t object. Upon completion, the sys_slist_t object is invalid
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001808 * and must be re-initialized via sys_slist_init().
1809 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001810 * @note Can be called by ISRs.
1811 *
1812 * @param fifo Address of the fifo.
1813 * @param list Pointer to sys_slist_t object.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001814 *
1815 * @return N/A
1816 */
Luiz Augusto von Dentze5ed88f2017-02-21 15:27:20 +02001817#define k_fifo_put_slist(fifo, list) \
1818 k_queue_merge_slist((struct k_queue *) fifo, list)
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001819
1820/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001821 * @brief Get an element from a fifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001822 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001823 * This routine removes a data item from @a fifo in a "first in, first out"
1824 * manner. The first 32 bits of the data item are reserved for the kernel's use.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001825 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001826 * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT.
1827 *
1828 * @param fifo Address of the fifo.
1829 * @param timeout Waiting period to obtain a data item (in milliseconds),
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001830 * or one of the special values K_NO_WAIT and K_FOREVER.
1831 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05001832 * @return Address of the data item if successful; NULL if returned
1833 * without waiting, or waiting period timed out.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001834 */
Luiz Augusto von Dentze5ed88f2017-02-21 15:27:20 +02001835#define k_fifo_get(fifo, timeout) \
1836 k_queue_get((struct k_queue *) fifo, timeout)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001837
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001838/**
Benjamin Walsh39b80d82017-01-28 10:06:07 -05001839 * @brief Query a fifo to see if it has data available.
1840 *
1841 * Note that the data might be already gone by the time this function returns
1842 * if other threads is also trying to read from the fifo.
1843 *
1844 * @note Can be called by ISRs.
1845 *
1846 * @param fifo Address of the fifo.
1847 *
1848 * @return Non-zero if the fifo is empty.
1849 * @return 0 if data is available.
1850 */
Luiz Augusto von Dentze5ed88f2017-02-21 15:27:20 +02001851#define k_fifo_is_empty(fifo) \
1852 k_queue_is_empty((struct k_queue *) fifo)
Benjamin Walsh39b80d82017-01-28 10:06:07 -05001853
1854/**
Paul Sokolovsky16bb3ec2017-06-08 17:13:03 +03001855 * @brief Peek element at the head of fifo.
1856 *
1857 * Return element from the head of fifo without removing it. A usecase
1858 * for this is if elements of the fifo are themselves containers. Then
1859 * on each iteration of processing, a head container will be peeked,
1860 * and some data processed out of it, and only if the container is empty,
1861 * it will be completely remove from the fifo.
1862 *
1863 * @param fifo Address of the fifo.
1864 *
1865 * @return Head element, or NULL if the fifo is empty.
1866 */
1867#define k_fifo_peek_head(fifo) \
1868 k_queue_peek_head((struct k_queue *) fifo)
1869
1870/**
1871 * @brief Peek element at the tail of fifo.
1872 *
1873 * Return element from the tail of fifo (without removing it). A usecase
1874 * for this is if elements of the fifo are themselves containers. Then
1875 * it may be useful to add more data to the last container in fifo.
1876 *
1877 * @param fifo Address of the fifo.
1878 *
1879 * @return Tail element, or NULL if fifo is empty.
1880 */
1881#define k_fifo_peek_tail(fifo) \
1882 k_queue_peek_tail((struct k_queue *) fifo)
1883
1884/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001885 * @brief Statically define and initialize a fifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001886 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001887 * The fifo can be accessed outside the module where it is defined using:
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001888 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05001889 * @code extern struct k_fifo <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001890 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001891 * @param name Name of the fifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001892 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001893#define K_FIFO_DEFINE(name) \
Allan Stephense7d2cc22016-10-19 16:10:46 -05001894 struct k_fifo name \
Luiz Augusto von Dentze5ed88f2017-02-21 15:27:20 +02001895 __in_section(_k_queue, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001896 _K_FIFO_INITIALIZER(name)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001897
Allan Stephensc98da842016-11-11 15:45:03 -05001898/**
1899 * @} end defgroup fifo_apis
1900 */
1901
1902/**
1903 * @cond INTERNAL_HIDDEN
1904 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001905
1906struct k_lifo {
Luiz Augusto von Dentz0dc4dd42017-02-21 15:49:52 +02001907 struct k_queue _queue;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001908};
1909
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001910#define _K_LIFO_INITIALIZER(obj) \
Allan Stephensc98da842016-11-11 15:45:03 -05001911 { \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001912 ._queue = _K_QUEUE_INITIALIZER(obj._queue) \
Allan Stephensc98da842016-11-11 15:45:03 -05001913 }
1914
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001915#define K_LIFO_INITIALIZER DEPRECATED_MACRO _K_LIFO_INITIALIZER
1916
Allan Stephensc98da842016-11-11 15:45:03 -05001917/**
1918 * INTERNAL_HIDDEN @endcond
1919 */
1920
1921/**
1922 * @defgroup lifo_apis Lifo APIs
1923 * @ingroup kernel_apis
1924 * @{
1925 */
1926
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001927/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001928 * @brief Initialize a lifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001929 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001930 * This routine initializes a lifo object, prior to its first use.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001931 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001932 * @param lifo Address of the lifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001933 *
1934 * @return N/A
1935 */
Luiz Augusto von Dentz0dc4dd42017-02-21 15:49:52 +02001936#define k_lifo_init(lifo) \
1937 k_queue_init((struct k_queue *) lifo)
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001938
1939/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001940 * @brief Add an element to a lifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001941 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001942 * This routine adds a data item to @a lifo. A lifo data item must be
1943 * aligned on a 4-byte boundary, and the first 32 bits of the item are
1944 * reserved for the kernel's use.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001945 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001946 * @note Can be called by ISRs.
1947 *
1948 * @param lifo Address of the lifo.
1949 * @param data Address of the data item.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001950 *
1951 * @return N/A
1952 */
Luiz Augusto von Dentz0dc4dd42017-02-21 15:49:52 +02001953#define k_lifo_put(lifo, data) \
1954 k_queue_prepend((struct k_queue *) lifo, data)
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001955
1956/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001957 * @brief Get an element from a lifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001958 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001959 * This routine removes a data item from @a lifo in a "last in, first out"
1960 * manner. The first 32 bits of the data item are reserved for the kernel's use.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001961 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001962 * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT.
1963 *
1964 * @param lifo Address of the lifo.
1965 * @param timeout Waiting period to obtain a data item (in milliseconds),
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001966 * or one of the special values K_NO_WAIT and K_FOREVER.
1967 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05001968 * @return Address of the data item if successful; NULL if returned
1969 * without waiting, or waiting period timed out.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001970 */
Luiz Augusto von Dentz0dc4dd42017-02-21 15:49:52 +02001971#define k_lifo_get(lifo, timeout) \
1972 k_queue_get((struct k_queue *) lifo, timeout)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001973
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001974/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001975 * @brief Statically define and initialize a lifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001976 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001977 * The lifo can be accessed outside the module where it is defined using:
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001978 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05001979 * @code extern struct k_lifo <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001980 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05001981 * @param name Name of the fifo.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04001982 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001983#define K_LIFO_DEFINE(name) \
Allan Stephense7d2cc22016-10-19 16:10:46 -05001984 struct k_lifo name \
Luiz Augusto von Dentz0dc4dd42017-02-21 15:49:52 +02001985 __in_section(_k_queue, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07001986 _K_LIFO_INITIALIZER(name)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001987
Allan Stephensc98da842016-11-11 15:45:03 -05001988/**
1989 * @} end defgroup lifo_apis
1990 */
1991
1992/**
1993 * @cond INTERNAL_HIDDEN
1994 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001995
1996struct k_stack {
1997 _wait_q_t wait_q;
Kumar Galacc334c72017-04-21 10:55:34 -05001998 u32_t *base, *next, *top;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04001999
Anas Nashif2f203c22016-12-18 06:57:45 -05002000 _OBJECT_TRACING_NEXT_PTR(k_stack);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002001};
2002
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002003#define _K_STACK_INITIALIZER(obj, stack_buffer, stack_num_entries) \
Allan Stephensc98da842016-11-11 15:45:03 -05002004 { \
2005 .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \
2006 .base = stack_buffer, \
2007 .next = stack_buffer, \
2008 .top = stack_buffer + stack_num_entries, \
Anas Nashif2f203c22016-12-18 06:57:45 -05002009 _OBJECT_TRACING_INIT \
Allan Stephensc98da842016-11-11 15:45:03 -05002010 }
2011
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002012#define K_STACK_INITIALIZER DEPRECATED_MACRO _K_STACK_INITIALIZER
2013
Allan Stephensc98da842016-11-11 15:45:03 -05002014/**
2015 * INTERNAL_HIDDEN @endcond
2016 */
2017
2018/**
2019 * @defgroup stack_apis Stack APIs
2020 * @ingroup kernel_apis
2021 * @{
2022 */
2023
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002024/**
2025 * @brief Initialize a stack.
2026 *
2027 * This routine initializes a stack object, prior to its first use.
2028 *
2029 * @param stack Address of the stack.
2030 * @param buffer Address of array used to hold stacked values.
2031 * @param num_entries Maximum number of values that can be stacked.
2032 *
2033 * @return N/A
2034 */
Allan Stephens018cd9a2016-10-07 15:13:24 -05002035extern void k_stack_init(struct k_stack *stack,
Kumar Galacc334c72017-04-21 10:55:34 -05002036 u32_t *buffer, int num_entries);
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002037
2038/**
2039 * @brief Push an element onto a stack.
2040 *
2041 * This routine adds a 32-bit value @a data to @a stack.
2042 *
2043 * @note Can be called by ISRs.
2044 *
2045 * @param stack Address of the stack.
2046 * @param data Value to push onto the stack.
2047 *
2048 * @return N/A
2049 */
Kumar Galacc334c72017-04-21 10:55:34 -05002050extern void k_stack_push(struct k_stack *stack, u32_t data);
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002051
2052/**
2053 * @brief Pop an element from a stack.
2054 *
2055 * This routine removes a 32-bit value from @a stack in a "last in, first out"
2056 * manner and stores the value in @a data.
2057 *
2058 * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT.
2059 *
2060 * @param stack Address of the stack.
2061 * @param data Address of area to hold the value popped from the stack.
2062 * @param timeout Waiting period to obtain a value (in milliseconds),
2063 * or one of the special values K_NO_WAIT and K_FOREVER.
2064 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05002065 * @retval 0 Element popped from stack.
2066 * @retval -EBUSY Returned without waiting.
2067 * @retval -EAGAIN Waiting period timed out.
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002068 */
Kumar Galacc334c72017-04-21 10:55:34 -05002069extern int k_stack_pop(struct k_stack *stack, u32_t *data, s32_t timeout);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002070
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002071/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002072 * @brief Statically define and initialize a stack
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002073 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002074 * The stack can be accessed outside the module where it is defined using:
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002075 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05002076 * @code extern struct k_stack <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002077 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002078 * @param name Name of the stack.
2079 * @param stack_num_entries Maximum number of values that can be stacked.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002080 */
Peter Mitsis602e6a82016-10-17 11:48:43 -04002081#define K_STACK_DEFINE(name, stack_num_entries) \
Kumar Galacc334c72017-04-21 10:55:34 -05002082 u32_t __noinit \
Peter Mitsis602e6a82016-10-17 11:48:43 -04002083 _k_stack_buf_##name[stack_num_entries]; \
Allan Stephense7d2cc22016-10-19 16:10:46 -05002084 struct k_stack name \
2085 __in_section(_k_stack, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002086 _K_STACK_INITIALIZER(name, _k_stack_buf_##name, \
Peter Mitsis602e6a82016-10-17 11:48:43 -04002087 stack_num_entries)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002088
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002089/**
Allan Stephensc98da842016-11-11 15:45:03 -05002090 * @} end defgroup stack_apis
2091 */
2092
Allan Stephens6bba9b02016-11-16 14:56:54 -05002093struct k_work;
2094
Allan Stephensc98da842016-11-11 15:45:03 -05002095/**
2096 * @defgroup workqueue_apis Workqueue Thread APIs
2097 * @ingroup kernel_apis
2098 * @{
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002099 */
2100
Allan Stephens6bba9b02016-11-16 14:56:54 -05002101/**
2102 * @typedef k_work_handler_t
2103 * @brief Work item handler function type.
2104 *
2105 * A work item's handler function is executed by a workqueue's thread
2106 * when the work item is processed by the workqueue.
2107 *
2108 * @param work Address of the work item.
2109 *
2110 * @return N/A
2111 */
2112typedef void (*k_work_handler_t)(struct k_work *work);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002113
2114/**
Allan Stephens6bba9b02016-11-16 14:56:54 -05002115 * @cond INTERNAL_HIDDEN
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002116 */
Allan Stephens6bba9b02016-11-16 14:56:54 -05002117
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002118struct k_work_q {
Luiz Augusto von Dentzadb581b2017-07-03 19:09:44 +03002119 struct k_queue queue;
Andrew Boied26cf2d2017-03-30 13:07:02 -07002120 struct k_thread thread;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002121};
2122
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002123enum {
Iván Briano9c7b5ea2016-10-04 18:11:05 -03002124 K_WORK_STATE_PENDING, /* Work item pending state */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002125};
2126
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002127struct k_work {
Luiz Augusto von Dentzadb581b2017-07-03 19:09:44 +03002128 void *_reserved; /* Used by k_queue implementation. */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002129 k_work_handler_t handler;
2130 atomic_t flags[1];
2131};
2132
Allan Stephens6bba9b02016-11-16 14:56:54 -05002133struct k_delayed_work {
2134 struct k_work work;
2135 struct _timeout timeout;
2136 struct k_work_q *work_q;
2137};
2138
2139extern struct k_work_q k_sys_work_q;
2140
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002141/**
Allan Stephens6bba9b02016-11-16 14:56:54 -05002142 * INTERNAL_HIDDEN @endcond
2143 */
2144
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002145#define _K_WORK_INITIALIZER(work_handler) \
2146 { \
2147 ._reserved = NULL, \
2148 .handler = work_handler, \
2149 .flags = { 0 } \
2150 }
2151
2152#define K_WORK_INITIALIZER DEPRECATED_MACRO _K_WORK_INITIALIZER
2153
Allan Stephens6bba9b02016-11-16 14:56:54 -05002154/**
2155 * @brief Initialize a statically-defined work item.
2156 *
2157 * This macro can be used to initialize a statically-defined workqueue work
2158 * item, prior to its first use. For example,
2159 *
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002160 * @code static K_WORK_DEFINE(<work>, <work_handler>); @endcode
Allan Stephens6bba9b02016-11-16 14:56:54 -05002161 *
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002162 * @param work Symbol name for work item object
Allan Stephens6bba9b02016-11-16 14:56:54 -05002163 * @param work_handler Function to invoke each time work item is processed.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002164 */
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002165#define K_WORK_DEFINE(work, work_handler) \
2166 struct k_work work \
2167 __in_section(_k_work, static, work) = \
2168 _K_WORK_INITIALIZER(work_handler)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002169
2170/**
Allan Stephens6bba9b02016-11-16 14:56:54 -05002171 * @brief Initialize a work item.
2172 *
2173 * This routine initializes a workqueue work item, prior to its first use.
2174 *
2175 * @param work Address of work item.
2176 * @param handler Function to invoke each time work item is processed.
2177 *
2178 * @return N/A
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002179 */
2180static inline void k_work_init(struct k_work *work, k_work_handler_t handler)
2181{
Luiz Augusto von Dentzee1e99b2016-09-26 09:36:49 +03002182 atomic_clear_bit(work->flags, K_WORK_STATE_PENDING);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002183 work->handler = handler;
Andrew Boie945af952017-08-22 13:15:23 -07002184 _k_object_init(work);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002185}
2186
2187/**
Allan Stephens6bba9b02016-11-16 14:56:54 -05002188 * @brief Submit a work item.
Luiz Augusto von Dentz4ab9d322016-09-26 09:39:27 +03002189 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002190 * This routine submits work item @a work to be processed by workqueue
2191 * @a work_q. If the work item is already pending in the workqueue's queue
2192 * as a result of an earlier submission, this routine has no effect on the
2193 * work item. If the work item has already been processed, or is currently
2194 * being processed, its work is considered complete and the work item can be
2195 * resubmitted.
Luiz Augusto von Dentz4ab9d322016-09-26 09:39:27 +03002196 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002197 * @warning
2198 * A submitted work item must not be modified until it has been processed
2199 * by the workqueue.
2200 *
2201 * @note Can be called by ISRs.
2202 *
2203 * @param work_q Address of workqueue.
2204 * @param work Address of work item.
Luiz Augusto von Dentz4ab9d322016-09-26 09:39:27 +03002205 *
2206 * @return N/A
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002207 */
2208static inline void k_work_submit_to_queue(struct k_work_q *work_q,
2209 struct k_work *work)
2210{
Luiz Augusto von Dentz4ab9d322016-09-26 09:39:27 +03002211 if (!atomic_test_and_set_bit(work->flags, K_WORK_STATE_PENDING)) {
Luiz Augusto von Dentzc1fa82b2017-07-03 19:24:10 +03002212 k_queue_append(&work_q->queue, work);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002213 }
2214}
2215
2216/**
Allan Stephens6bba9b02016-11-16 14:56:54 -05002217 * @brief Check if a work item is pending.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002218 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002219 * This routine indicates if work item @a work is pending in a workqueue's
2220 * queue.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002221 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002222 * @note Can be called by ISRs.
2223 *
2224 * @param work Address of work item.
2225 *
2226 * @return 1 if work item is pending, or 0 if it is not pending.
Luiz Augusto von Dentzee1e99b2016-09-26 09:36:49 +03002227 */
2228static inline int k_work_pending(struct k_work *work)
2229{
Iván Briano9c7b5ea2016-10-04 18:11:05 -03002230 return atomic_test_bit(work->flags, K_WORK_STATE_PENDING);
Luiz Augusto von Dentzee1e99b2016-09-26 09:36:49 +03002231}
2232
2233/**
Allan Stephens6bba9b02016-11-16 14:56:54 -05002234 * @brief Start a workqueue.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002235 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002236 * This routine starts workqueue @a work_q. The workqueue spawns its work
2237 * processing thread, which runs forever.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002238 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002239 * @param work_q Address of workqueue.
Andrew Boiedc5d9352017-06-02 12:56:47 -07002240 * @param stack Pointer to work queue thread's stack space, as defined by
2241 * K_THREAD_STACK_DEFINE()
2242 * @param stack_size Size of the work queue thread's stack (in bytes), which
2243 * should either be the same constant passed to
2244 * K_THREAD_STACK_DEFINE() or the value of K_THREAD_STACK_SIZEOF().
Allan Stephens6bba9b02016-11-16 14:56:54 -05002245 * @param prio Priority of the work queue's thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002246 *
2247 * @return N/A
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002248 */
Andrew Boie507852a2017-07-25 18:47:07 -07002249extern void k_work_q_start(struct k_work_q *work_q,
2250 k_thread_stack_t stack,
Benjamin Walsh669360d2016-11-14 16:46:14 -05002251 size_t stack_size, int prio);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002252
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002253/**
Allan Stephens6bba9b02016-11-16 14:56:54 -05002254 * @brief Initialize a delayed work item.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002255 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002256 * This routine initializes a workqueue delayed work item, prior to
2257 * its first use.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002258 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002259 * @param work Address of delayed work item.
2260 * @param handler Function to invoke each time work item is processed.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002261 *
2262 * @return N/A
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002263 */
Benjamin Walsh72e5a392016-09-30 11:32:33 -04002264extern void k_delayed_work_init(struct k_delayed_work *work,
2265 k_work_handler_t handler);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002266
2267/**
Allan Stephens6bba9b02016-11-16 14:56:54 -05002268 * @brief Submit a delayed work item.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002269 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002270 * This routine schedules work item @a work to be processed by workqueue
2271 * @a work_q after a delay of @a delay milliseconds. The routine initiates
David B. Kinder8b986d72017-04-18 15:56:26 -07002272 * an asynchronous countdown for the work item and then returns to the caller.
Allan Stephens6bba9b02016-11-16 14:56:54 -05002273 * Only when the countdown completes is the work item actually submitted to
2274 * the workqueue and becomes pending.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002275 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002276 * Submitting a previously submitted delayed work item that is still
2277 * counting down cancels the existing submission and restarts the countdown
2278 * using the new delay. If the work item is currently pending on the
2279 * workqueue's queue because the countdown has completed it is too late to
2280 * resubmit the item, and resubmission fails without impacting the work item.
2281 * If the work item has already been processed, or is currently being processed,
2282 * its work is considered complete and the work item can be resubmitted.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002283 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002284 * @warning
2285 * A delayed work item must not be modified until it has been processed
2286 * by the workqueue.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002287 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002288 * @note Can be called by ISRs.
2289 *
2290 * @param work_q Address of workqueue.
2291 * @param work Address of delayed work item.
2292 * @param delay Delay before submitting the work item (in milliseconds).
2293 *
2294 * @retval 0 Work item countdown started.
2295 * @retval -EINPROGRESS Work item is already pending.
2296 * @retval -EINVAL Work item is being processed or has completed its work.
2297 * @retval -EADDRINUSE Work item is pending on a different workqueue.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002298 */
Benjamin Walsh72e5a392016-09-30 11:32:33 -04002299extern int k_delayed_work_submit_to_queue(struct k_work_q *work_q,
2300 struct k_delayed_work *work,
Kumar Galacc334c72017-04-21 10:55:34 -05002301 s32_t delay);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002302
2303/**
Allan Stephens6bba9b02016-11-16 14:56:54 -05002304 * @brief Cancel a delayed work item.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002305 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002306 * This routine cancels the submission of delayed work item @a work.
David B. Kinder8b986d72017-04-18 15:56:26 -07002307 * A delayed work item can only be canceled while its countdown is still
Allan Stephens6bba9b02016-11-16 14:56:54 -05002308 * underway.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002309 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002310 * @note Can be called by ISRs.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002311 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002312 * @param work Address of delayed work item.
2313 *
David B. Kinder8b986d72017-04-18 15:56:26 -07002314 * @retval 0 Work item countdown canceled.
Allan Stephens6bba9b02016-11-16 14:56:54 -05002315 * @retval -EINPROGRESS Work item is already pending.
2316 * @retval -EINVAL Work item is being processed or has completed its work.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002317 */
Benjamin Walsh72e5a392016-09-30 11:32:33 -04002318extern int k_delayed_work_cancel(struct k_delayed_work *work);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002319
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002320/**
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002321 * @brief Submit a work item to the system workqueue.
2322 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002323 * This routine submits work item @a work to be processed by the system
2324 * workqueue. If the work item is already pending in the workqueue's queue
2325 * as a result of an earlier submission, this routine has no effect on the
2326 * work item. If the work item has already been processed, or is currently
2327 * being processed, its work is considered complete and the work item can be
2328 * resubmitted.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002329 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002330 * @warning
2331 * Work items submitted to the system workqueue should avoid using handlers
2332 * that block or yield since this may prevent the system workqueue from
2333 * processing other work items in a timely manner.
2334 *
2335 * @note Can be called by ISRs.
2336 *
2337 * @param work Address of work item.
2338 *
2339 * @return N/A
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002340 */
2341static inline void k_work_submit(struct k_work *work)
2342{
2343 k_work_submit_to_queue(&k_sys_work_q, work);
2344}
2345
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002346/**
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002347 * @brief Submit a delayed work item to the system workqueue.
2348 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002349 * This routine schedules work item @a work to be processed by the system
2350 * workqueue after a delay of @a delay milliseconds. The routine initiates
David B. Kinder8b986d72017-04-18 15:56:26 -07002351 * an asynchronous countdown for the work item and then returns to the caller.
Allan Stephens6bba9b02016-11-16 14:56:54 -05002352 * Only when the countdown completes is the work item actually submitted to
2353 * the workqueue and becomes pending.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002354 *
Allan Stephens6bba9b02016-11-16 14:56:54 -05002355 * Submitting a previously submitted delayed work item that is still
2356 * counting down cancels the existing submission and restarts the countdown
2357 * using the new delay. If the work item is currently pending on the
2358 * workqueue's queue because the countdown has completed it is too late to
2359 * resubmit the item, and resubmission fails without impacting the work item.
2360 * If the work item has already been processed, or is currently being processed,
2361 * its work is considered complete and the work item can be resubmitted.
2362 *
2363 * @warning
2364 * Work items submitted to the system workqueue should avoid using handlers
2365 * that block or yield since this may prevent the system workqueue from
2366 * processing other work items in a timely manner.
2367 *
2368 * @note Can be called by ISRs.
2369 *
2370 * @param work Address of delayed work item.
2371 * @param delay Delay before submitting the work item (in milliseconds).
2372 *
2373 * @retval 0 Work item countdown started.
2374 * @retval -EINPROGRESS Work item is already pending.
2375 * @retval -EINVAL Work item is being processed or has completed its work.
2376 * @retval -EADDRINUSE Work item is pending on a different workqueue.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002377 */
2378static inline int k_delayed_work_submit(struct k_delayed_work *work,
Kumar Galacc334c72017-04-21 10:55:34 -05002379 s32_t delay)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002380{
Allan Stephens6c98c4d2016-10-17 14:34:53 -05002381 return k_delayed_work_submit_to_queue(&k_sys_work_q, work, delay);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002382}
2383
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002384/**
Johan Hedbergc8201b22016-12-09 10:42:22 +02002385 * @brief Get time remaining before a delayed work gets scheduled.
2386 *
2387 * This routine computes the (approximate) time remaining before a
2388 * delayed work gets executed. If the delayed work is not waiting to be
2389 * schedules, it returns zero.
2390 *
2391 * @param work Delayed work item.
2392 *
2393 * @return Remaining time (in milliseconds).
2394 */
Kumar Galacc334c72017-04-21 10:55:34 -05002395static inline s32_t k_delayed_work_remaining_get(struct k_delayed_work *work)
Johan Hedbergc8201b22016-12-09 10:42:22 +02002396{
2397 return _timeout_remaining_get(&work->timeout);
2398}
2399
2400/**
Allan Stephensc98da842016-11-11 15:45:03 -05002401 * @} end defgroup workqueue_apis
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002402 */
2403
Allan Stephensc98da842016-11-11 15:45:03 -05002404/**
2405 * @cond INTERNAL_HIDDEN
2406 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002407
2408struct k_mutex {
2409 _wait_q_t wait_q;
Benjamin Walshb7ef0cb2016-10-05 17:32:01 -04002410 struct k_thread *owner;
Kumar Galacc334c72017-04-21 10:55:34 -05002411 u32_t lock_count;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002412 int owner_orig_prio;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002413
Anas Nashif2f203c22016-12-18 06:57:45 -05002414 _OBJECT_TRACING_NEXT_PTR(k_mutex);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002415};
2416
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002417#define _K_MUTEX_INITIALIZER(obj) \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002418 { \
2419 .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \
2420 .owner = NULL, \
2421 .lock_count = 0, \
2422 .owner_orig_prio = K_LOWEST_THREAD_PRIO, \
Anas Nashif2f203c22016-12-18 06:57:45 -05002423 _OBJECT_TRACING_INIT \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002424 }
2425
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002426#define K_MUTEX_INITIALIZER DEPRECATED_MACRO _K_MUTEX_INITIALIZER
2427
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002428/**
Allan Stephensc98da842016-11-11 15:45:03 -05002429 * INTERNAL_HIDDEN @endcond
2430 */
2431
2432/**
2433 * @defgroup mutex_apis Mutex APIs
2434 * @ingroup kernel_apis
2435 * @{
2436 */
2437
2438/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002439 * @brief Statically define and initialize a mutex.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002440 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002441 * The mutex can be accessed outside the module where it is defined using:
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002442 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05002443 * @code extern struct k_mutex <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002444 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002445 * @param name Name of the mutex.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002446 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002447#define K_MUTEX_DEFINE(name) \
Allan Stephense7d2cc22016-10-19 16:10:46 -05002448 struct k_mutex name \
2449 __in_section(_k_mutex, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002450 _K_MUTEX_INITIALIZER(name)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002451
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002452/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002453 * @brief Initialize a mutex.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002454 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002455 * This routine initializes a mutex object, prior to its first use.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002456 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002457 * Upon completion, the mutex is available and does not have an owner.
2458 *
2459 * @param mutex Address of the mutex.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002460 *
2461 * @return N/A
2462 */
Andrew Boie2f7519b2017-09-29 03:33:06 -07002463__syscall void k_mutex_init(struct k_mutex *mutex);
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002464
2465/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002466 * @brief Lock a mutex.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002467 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002468 * This routine locks @a mutex. If the mutex is locked by another thread,
2469 * the calling thread waits until the mutex becomes available or until
2470 * a timeout occurs.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002471 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002472 * A thread is permitted to lock a mutex it has already locked. The operation
2473 * completes immediately and the lock count is increased by 1.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002474 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002475 * @param mutex Address of the mutex.
2476 * @param timeout Waiting period to lock the mutex (in milliseconds),
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002477 * or one of the special values K_NO_WAIT and K_FOREVER.
2478 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05002479 * @retval 0 Mutex locked.
2480 * @retval -EBUSY Returned without waiting.
2481 * @retval -EAGAIN Waiting period timed out.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002482 */
Andrew Boie2f7519b2017-09-29 03:33:06 -07002483__syscall int k_mutex_lock(struct k_mutex *mutex, s32_t timeout);
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002484
2485/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002486 * @brief Unlock a mutex.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002487 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002488 * This routine unlocks @a mutex. The mutex must already be locked by the
2489 * calling thread.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002490 *
2491 * The mutex cannot be claimed by another thread until it has been unlocked by
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002492 * the calling thread as many times as it was previously locked by that
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002493 * thread.
2494 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002495 * @param mutex Address of the mutex.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002496 *
2497 * @return N/A
2498 */
Andrew Boie2f7519b2017-09-29 03:33:06 -07002499__syscall void k_mutex_unlock(struct k_mutex *mutex);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002500
Allan Stephensc98da842016-11-11 15:45:03 -05002501/**
2502 * @} end defgroup mutex_apis
2503 */
2504
2505/**
2506 * @cond INTERNAL_HIDDEN
2507 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002508
2509struct k_sem {
2510 _wait_q_t wait_q;
2511 unsigned int count;
2512 unsigned int limit;
Benjamin Walshacc68c12017-01-29 18:57:45 -05002513 _POLL_EVENT;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002514
Anas Nashif2f203c22016-12-18 06:57:45 -05002515 _OBJECT_TRACING_NEXT_PTR(k_sem);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002516};
2517
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002518#define _K_SEM_INITIALIZER(obj, initial_count, count_limit) \
Allan Stephensc98da842016-11-11 15:45:03 -05002519 { \
2520 .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \
2521 .count = initial_count, \
2522 .limit = count_limit, \
Luiz Augusto von Dentz7d01c5e2017-08-21 10:49:29 +03002523 _POLL_EVENT_OBJ_INIT(obj) \
Anas Nashif2f203c22016-12-18 06:57:45 -05002524 _OBJECT_TRACING_INIT \
Allan Stephensc98da842016-11-11 15:45:03 -05002525 }
2526
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002527#define K_SEM_INITIALIZER DEPRECATED_MACRO _K_SEM_INITIALIZER
2528
Allan Stephensc98da842016-11-11 15:45:03 -05002529/**
2530 * INTERNAL_HIDDEN @endcond
2531 */
2532
2533/**
2534 * @defgroup semaphore_apis Semaphore APIs
2535 * @ingroup kernel_apis
2536 * @{
2537 */
2538
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002539/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002540 * @brief Initialize a semaphore.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002541 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002542 * This routine initializes a semaphore object, prior to its first use.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002543 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002544 * @param sem Address of the semaphore.
2545 * @param initial_count Initial semaphore count.
2546 * @param limit Maximum permitted semaphore count.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002547 *
2548 * @return N/A
2549 */
Andrew Boie99280232017-09-29 14:17:47 -07002550__syscall void k_sem_init(struct k_sem *sem, unsigned int initial_count,
2551 unsigned int limit);
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002552
2553/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002554 * @brief Take a semaphore.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002555 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002556 * This routine takes @a sem.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002557 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002558 * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT.
2559 *
2560 * @param sem Address of the semaphore.
2561 * @param timeout Waiting period to take the semaphore (in milliseconds),
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002562 * or one of the special values K_NO_WAIT and K_FOREVER.
2563 *
Benjamin Walsh91f834c2016-12-01 11:39:49 -05002564 * @note When porting code from the nanokernel legacy API to the new API, be
2565 * careful with the return value of this function. The return value is the
2566 * reverse of the one of nano_sem_take family of APIs: 0 means success, and
2567 * non-zero means failure, while the nano_sem_take family returns 1 for success
2568 * and 0 for failure.
2569 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05002570 * @retval 0 Semaphore taken.
2571 * @retval -EBUSY Returned without waiting.
2572 * @retval -EAGAIN Waiting period timed out.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002573 */
Andrew Boie99280232017-09-29 14:17:47 -07002574__syscall int k_sem_take(struct k_sem *sem, s32_t timeout);
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002575
2576/**
2577 * @brief Give a semaphore.
2578 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002579 * This routine gives @a sem, unless the semaphore is already at its maximum
2580 * permitted count.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002581 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002582 * @note Can be called by ISRs.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002583 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002584 * @param sem Address of the semaphore.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002585 *
2586 * @return N/A
2587 */
Andrew Boie99280232017-09-29 14:17:47 -07002588__syscall void k_sem_give(struct k_sem *sem);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002589
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002590/**
2591 * @brief Reset a semaphore's count to zero.
2592 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002593 * This routine sets the count of @a sem to zero.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002594 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002595 * @param sem Address of the semaphore.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002596 *
2597 * @return N/A
2598 */
Andrew Boie990bf162017-10-03 12:36:49 -07002599__syscall void k_sem_reset(struct k_sem *sem);
Andrew Boiefc273c02017-09-23 12:51:23 -07002600
2601static inline void _impl_k_sem_reset(struct k_sem *sem)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002602{
2603 sem->count = 0;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002604}
2605
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002606/**
2607 * @brief Get a semaphore's count.
2608 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002609 * This routine returns the current count of @a sem.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002610 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002611 * @param sem Address of the semaphore.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002612 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002613 * @return Current semaphore count.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002614 */
Andrew Boie990bf162017-10-03 12:36:49 -07002615__syscall unsigned int k_sem_count_get(struct k_sem *sem);
Andrew Boiefc273c02017-09-23 12:51:23 -07002616
2617static inline unsigned int _impl_k_sem_count_get(struct k_sem *sem)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002618{
2619 return sem->count;
2620}
2621
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002622/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002623 * @brief Statically define and initialize a semaphore.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002624 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002625 * The semaphore can be accessed outside the module where it is defined using:
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002626 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05002627 * @code extern struct k_sem <name>; @endcode
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002628 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002629 * @param name Name of the semaphore.
2630 * @param initial_count Initial semaphore count.
2631 * @param count_limit Maximum permitted semaphore count.
Benjamin Walshb9c1a062016-10-15 17:12:35 -04002632 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002633#define K_SEM_DEFINE(name, initial_count, count_limit) \
Allan Stephense7d2cc22016-10-19 16:10:46 -05002634 struct k_sem name \
2635 __in_section(_k_sem, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002636 _K_SEM_INITIALIZER(name, initial_count, count_limit)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002637
Allan Stephensc98da842016-11-11 15:45:03 -05002638/**
2639 * @} end defgroup semaphore_apis
2640 */
2641
2642/**
2643 * @defgroup alert_apis Alert APIs
2644 * @ingroup kernel_apis
2645 * @{
2646 */
2647
Allan Stephens5eceb852016-11-16 10:16:30 -05002648/**
2649 * @typedef k_alert_handler_t
2650 * @brief Alert handler function type.
2651 *
2652 * An alert's alert handler function is invoked by the system workqueue
David B. Kinder8b986d72017-04-18 15:56:26 -07002653 * when the alert is signaled. The alert handler function is optional,
Allan Stephens5eceb852016-11-16 10:16:30 -05002654 * and is only invoked if the alert has been initialized with one.
2655 *
2656 * @param alert Address of the alert.
2657 *
2658 * @return 0 if alert has been consumed; non-zero if alert should pend.
2659 */
2660typedef int (*k_alert_handler_t)(struct k_alert *alert);
Allan Stephensc98da842016-11-11 15:45:03 -05002661
2662/**
2663 * @} end defgroup alert_apis
2664 */
2665
2666/**
2667 * @cond INTERNAL_HIDDEN
2668 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002669
Benjamin Walsh31a3f6a2016-10-25 13:28:35 -04002670#define K_ALERT_DEFAULT NULL
2671#define K_ALERT_IGNORE ((void *)(-1))
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002672
Benjamin Walsh31a3f6a2016-10-25 13:28:35 -04002673struct k_alert {
2674 k_alert_handler_t handler;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002675 atomic_t send_count;
2676 struct k_work work_item;
2677 struct k_sem sem;
2678
Anas Nashif2f203c22016-12-18 06:57:45 -05002679 _OBJECT_TRACING_NEXT_PTR(k_alert);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002680};
2681
Benjamin Walsh31a3f6a2016-10-25 13:28:35 -04002682extern void _alert_deliver(struct k_work *work);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002683
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002684#define _K_ALERT_INITIALIZER(obj, alert_handler, max_num_pending_alerts) \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002685 { \
Benjamin Walsh31a3f6a2016-10-25 13:28:35 -04002686 .handler = (k_alert_handler_t)alert_handler, \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002687 .send_count = ATOMIC_INIT(0), \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002688 .work_item = _K_WORK_INITIALIZER(_alert_deliver), \
2689 .sem = _K_SEM_INITIALIZER(obj.sem, 0, max_num_pending_alerts), \
Anas Nashif2f203c22016-12-18 06:57:45 -05002690 _OBJECT_TRACING_INIT \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002691 }
2692
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002693#define K_ALERT_INITIALIZER DEPRECATED_MACRO _K_ALERT_INITIALIZER
2694
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002695/**
Allan Stephensc98da842016-11-11 15:45:03 -05002696 * INTERNAL_HIDDEN @endcond
2697 */
2698
2699/**
2700 * @addtogroup alert_apis
2701 * @{
2702 */
2703
2704/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002705 * @brief Statically define and initialize an alert.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002706 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05002707 * The alert can be accessed outside the module where it is defined using:
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002708 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05002709 * @code extern struct k_alert <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002710 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002711 * @param name Name of the alert.
2712 * @param alert_handler Action to take when alert is sent. Specify either
2713 * the address of a function to be invoked by the system workqueue
2714 * thread, K_ALERT_IGNORE (which causes the alert to be ignored), or
2715 * K_ALERT_DEFAULT (which causes the alert to pend).
2716 * @param max_num_pending_alerts Maximum number of pending alerts.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002717 */
Peter Mitsis058fa4e2016-10-25 14:42:30 -04002718#define K_ALERT_DEFINE(name, alert_handler, max_num_pending_alerts) \
Benjamin Walsh31a3f6a2016-10-25 13:28:35 -04002719 struct k_alert name \
Allan Stephense7d2cc22016-10-19 16:10:46 -05002720 __in_section(_k_alert, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002721 _K_ALERT_INITIALIZER(name, alert_handler, \
Peter Mitsis058fa4e2016-10-25 14:42:30 -04002722 max_num_pending_alerts)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002723
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002724/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002725 * @brief Initialize an alert.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002726 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002727 * This routine initializes an alert object, prior to its first use.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002728 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002729 * @param alert Address of the alert.
2730 * @param handler Action to take when alert is sent. Specify either the address
2731 * of a function to be invoked by the system workqueue thread,
2732 * K_ALERT_IGNORE (which causes the alert to be ignored), or
2733 * K_ALERT_DEFAULT (which causes the alert to pend).
2734 * @param max_num_pending_alerts Maximum number of pending alerts.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002735 *
2736 * @return N/A
2737 */
Peter Mitsis058fa4e2016-10-25 14:42:30 -04002738extern void k_alert_init(struct k_alert *alert, k_alert_handler_t handler,
2739 unsigned int max_num_pending_alerts);
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002740
2741/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002742 * @brief Receive an alert.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002743 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002744 * This routine receives a pending alert for @a alert.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002745 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002746 * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT.
2747 *
2748 * @param alert Address of the alert.
2749 * @param timeout Waiting period to receive the alert (in milliseconds),
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002750 * or one of the special values K_NO_WAIT and K_FOREVER.
2751 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05002752 * @retval 0 Alert received.
2753 * @retval -EBUSY Returned without waiting.
2754 * @retval -EAGAIN Waiting period timed out.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002755 */
Andrew Boie310e9872017-09-29 04:41:15 -07002756__syscall int k_alert_recv(struct k_alert *alert, s32_t timeout);
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002757
2758/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002759 * @brief Signal an alert.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002760 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002761 * This routine signals @a alert. The action specified for @a alert will
2762 * be taken, which may trigger the execution of an alert handler function
2763 * and/or cause the alert to pend (assuming the alert has not reached its
2764 * maximum number of pending alerts).
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002765 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002766 * @note Can be called by ISRs.
2767 *
2768 * @param alert Address of the alert.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002769 *
2770 * @return N/A
2771 */
Andrew Boie310e9872017-09-29 04:41:15 -07002772__syscall void k_alert_send(struct k_alert *alert);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002773
2774/**
Allan Stephensc98da842016-11-11 15:45:03 -05002775 * @} end addtogroup alert_apis
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002776 */
2777
Allan Stephensc98da842016-11-11 15:45:03 -05002778/**
2779 * @cond INTERNAL_HIDDEN
2780 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002781
2782struct k_msgq {
2783 _wait_q_t wait_q;
Peter Mitsis026b4ed2016-10-13 11:41:45 -04002784 size_t msg_size;
Kumar Galacc334c72017-04-21 10:55:34 -05002785 u32_t max_msgs;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002786 char *buffer_start;
2787 char *buffer_end;
2788 char *read_ptr;
2789 char *write_ptr;
Kumar Galacc334c72017-04-21 10:55:34 -05002790 u32_t used_msgs;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002791
Anas Nashif2f203c22016-12-18 06:57:45 -05002792 _OBJECT_TRACING_NEXT_PTR(k_msgq);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002793};
2794
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002795#define _K_MSGQ_INITIALIZER(obj, q_buffer, q_msg_size, q_max_msgs) \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002796 { \
2797 .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \
Peter Mitsis1da807e2016-10-06 11:36:59 -04002798 .max_msgs = q_max_msgs, \
2799 .msg_size = q_msg_size, \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002800 .buffer_start = q_buffer, \
Peter Mitsis1da807e2016-10-06 11:36:59 -04002801 .buffer_end = q_buffer + (q_max_msgs * q_msg_size), \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002802 .read_ptr = q_buffer, \
2803 .write_ptr = q_buffer, \
2804 .used_msgs = 0, \
Anas Nashif2f203c22016-12-18 06:57:45 -05002805 _OBJECT_TRACING_INIT \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002806 }
2807
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002808#define K_MSGQ_INITIALIZER DEPRECATED_MACRO _K_MSGQ_INITIALIZER
2809
Peter Mitsis1da807e2016-10-06 11:36:59 -04002810/**
Allan Stephensc98da842016-11-11 15:45:03 -05002811 * INTERNAL_HIDDEN @endcond
2812 */
2813
2814/**
2815 * @defgroup msgq_apis Message Queue APIs
2816 * @ingroup kernel_apis
2817 * @{
2818 */
2819
2820/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002821 * @brief Statically define and initialize a message queue.
Peter Mitsis1da807e2016-10-06 11:36:59 -04002822 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002823 * The message queue's ring buffer contains space for @a q_max_msgs messages,
2824 * each of which is @a q_msg_size bytes long. The buffer is aligned to a
Allan Stephensda827222016-11-09 14:23:58 -06002825 * @a q_align -byte boundary, which must be a power of 2. To ensure that each
2826 * message is similarly aligned to this boundary, @a q_msg_size must also be
2827 * a multiple of @a q_align.
Peter Mitsis1da807e2016-10-06 11:36:59 -04002828 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002829 * The message queue can be accessed outside the module where it is defined
2830 * using:
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002831 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05002832 * @code extern struct k_msgq <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04002833 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002834 * @param q_name Name of the message queue.
2835 * @param q_msg_size Message size (in bytes).
2836 * @param q_max_msgs Maximum number of messages that can be queued.
Allan Stephensda827222016-11-09 14:23:58 -06002837 * @param q_align Alignment of the message queue's ring buffer.
Peter Mitsis1da807e2016-10-06 11:36:59 -04002838 */
2839#define K_MSGQ_DEFINE(q_name, q_msg_size, q_max_msgs, q_align) \
2840 static char __noinit __aligned(q_align) \
2841 _k_fifo_buf_##q_name[(q_max_msgs) * (q_msg_size)]; \
Allan Stephense7d2cc22016-10-19 16:10:46 -05002842 struct k_msgq q_name \
2843 __in_section(_k_msgq, static, q_name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07002844 _K_MSGQ_INITIALIZER(q_name, _k_fifo_buf_##q_name, \
Peter Mitsis1da807e2016-10-06 11:36:59 -04002845 q_msg_size, q_max_msgs)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002846
Peter Mitsisd7a37502016-10-13 11:37:40 -04002847/**
2848 * @brief Initialize a message queue.
2849 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002850 * This routine initializes a message queue object, prior to its first use.
2851 *
Allan Stephensda827222016-11-09 14:23:58 -06002852 * The message queue's ring buffer must contain space for @a max_msgs messages,
2853 * each of which is @a msg_size bytes long. The buffer must be aligned to an
2854 * N-byte boundary, where N is a power of 2 (i.e. 1, 2, 4, ...). To ensure
2855 * that each message is similarly aligned to this boundary, @a q_msg_size
2856 * must also be a multiple of N.
2857 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002858 * @param q Address of the message queue.
2859 * @param buffer Pointer to ring buffer that holds queued messages.
2860 * @param msg_size Message size (in bytes).
Peter Mitsisd7a37502016-10-13 11:37:40 -04002861 * @param max_msgs Maximum number of messages that can be queued.
2862 *
2863 * @return N/A
2864 */
Peter Mitsis1da807e2016-10-06 11:36:59 -04002865extern void k_msgq_init(struct k_msgq *q, char *buffer,
Kumar Galacc334c72017-04-21 10:55:34 -05002866 size_t msg_size, u32_t max_msgs);
Peter Mitsisd7a37502016-10-13 11:37:40 -04002867
2868/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002869 * @brief Send a message to a message queue.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002870 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002871 * This routine sends a message to message queue @a q.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002872 *
Benjamin Walsh8215ce12016-11-09 19:45:19 -05002873 * @note Can be called by ISRs.
2874 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002875 * @param q Address of the message queue.
2876 * @param data Pointer to the message.
2877 * @param timeout Waiting period to add the message (in milliseconds),
2878 * or one of the special values K_NO_WAIT and K_FOREVER.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002879 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05002880 * @retval 0 Message sent.
2881 * @retval -ENOMSG Returned without waiting or queue purged.
2882 * @retval -EAGAIN Waiting period timed out.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002883 */
Kumar Galacc334c72017-04-21 10:55:34 -05002884extern int k_msgq_put(struct k_msgq *q, void *data, s32_t timeout);
Peter Mitsisd7a37502016-10-13 11:37:40 -04002885
2886/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002887 * @brief Receive a message from a message queue.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002888 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002889 * This routine receives a message from message queue @a q in a "first in,
2890 * first out" manner.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002891 *
Allan Stephensc98da842016-11-11 15:45:03 -05002892 * @note Can be called by ISRs, but @a timeout must be set to K_NO_WAIT.
Benjamin Walsh8215ce12016-11-09 19:45:19 -05002893 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002894 * @param q Address of the message queue.
2895 * @param data Address of area to hold the received message.
2896 * @param timeout Waiting period to receive the message (in milliseconds),
2897 * or one of the special values K_NO_WAIT and K_FOREVER.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002898 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05002899 * @retval 0 Message received.
2900 * @retval -ENOMSG Returned without waiting.
2901 * @retval -EAGAIN Waiting period timed out.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002902 */
Kumar Galacc334c72017-04-21 10:55:34 -05002903extern int k_msgq_get(struct k_msgq *q, void *data, s32_t timeout);
Peter Mitsisd7a37502016-10-13 11:37:40 -04002904
2905/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002906 * @brief Purge a message queue.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002907 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002908 * This routine discards all unreceived messages in a message queue's ring
2909 * buffer. Any threads that are blocked waiting to send a message to the
2910 * message queue are unblocked and see an -ENOMSG error code.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002911 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002912 * @param q Address of the message queue.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002913 *
2914 * @return N/A
2915 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002916extern void k_msgq_purge(struct k_msgq *q);
2917
Peter Mitsis67be2492016-10-07 11:44:34 -04002918/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002919 * @brief Get the amount of free space in a message queue.
Peter Mitsis67be2492016-10-07 11:44:34 -04002920 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002921 * This routine returns the number of unused entries in a message queue's
2922 * ring buffer.
Peter Mitsis67be2492016-10-07 11:44:34 -04002923 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002924 * @param q Address of the message queue.
2925 *
2926 * @return Number of unused ring buffer entries.
Peter Mitsis67be2492016-10-07 11:44:34 -04002927 */
Kumar Galacc334c72017-04-21 10:55:34 -05002928static inline u32_t k_msgq_num_free_get(struct k_msgq *q)
Peter Mitsis67be2492016-10-07 11:44:34 -04002929{
2930 return q->max_msgs - q->used_msgs;
2931}
2932
Peter Mitsisd7a37502016-10-13 11:37:40 -04002933/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002934 * @brief Get the number of messages in a message queue.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002935 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002936 * This routine returns the number of messages in a message queue's ring buffer.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002937 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05002938 * @param q Address of the message queue.
2939 *
2940 * @return Number of messages.
Peter Mitsisd7a37502016-10-13 11:37:40 -04002941 */
Kumar Galacc334c72017-04-21 10:55:34 -05002942static inline u32_t k_msgq_num_used_get(struct k_msgq *q)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002943{
2944 return q->used_msgs;
2945}
2946
Allan Stephensc98da842016-11-11 15:45:03 -05002947/**
2948 * @} end defgroup msgq_apis
2949 */
2950
2951/**
2952 * @defgroup mem_pool_apis Memory Pool APIs
2953 * @ingroup kernel_apis
2954 * @{
2955 */
2956
Andy Ross73cb9582017-05-09 10:42:39 -07002957/* Note on sizing: the use of a 20 bit field for block means that,
2958 * assuming a reasonable minimum block size of 16 bytes, we're limited
2959 * to 16M of memory managed by a single pool. Long term it would be
2960 * good to move to a variable bit size based on configuration.
2961 */
2962struct k_mem_block_id {
2963 u32_t pool : 8;
2964 u32_t level : 4;
2965 u32_t block : 20;
2966};
2967
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002968struct k_mem_block {
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002969 void *data;
Andy Ross73cb9582017-05-09 10:42:39 -07002970 struct k_mem_block_id id;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002971};
2972
Allan Stephensc98da842016-11-11 15:45:03 -05002973/**
2974 * @} end defgroup mem_pool_apis
2975 */
2976
2977/**
2978 * @defgroup mailbox_apis Mailbox APIs
2979 * @ingroup kernel_apis
2980 * @{
2981 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002982
2983struct k_mbox_msg {
2984 /** internal use only - needed for legacy API support */
Kumar Galacc334c72017-04-21 10:55:34 -05002985 u32_t _mailbox;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002986 /** size of message (in bytes) */
Peter Mitsisd93078c2016-10-14 12:59:37 -04002987 size_t size;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002988 /** application-defined information value */
Kumar Galacc334c72017-04-21 10:55:34 -05002989 u32_t info;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04002990 /** sender's message data buffer */
2991 void *tx_data;
2992 /** internal use only - needed for legacy API support */
2993 void *_rx_data;
2994 /** message data block descriptor */
2995 struct k_mem_block tx_block;
2996 /** source thread id */
2997 k_tid_t rx_source_thread;
2998 /** target thread id */
2999 k_tid_t tx_target_thread;
3000 /** internal use only - thread waiting on send (may be a dummy) */
3001 k_tid_t _syncing_thread;
3002#if (CONFIG_NUM_MBOX_ASYNC_MSGS > 0)
3003 /** internal use only - semaphore used during asynchronous send */
3004 struct k_sem *_async_sem;
3005#endif
3006};
3007
Allan Stephensc98da842016-11-11 15:45:03 -05003008/**
3009 * @cond INTERNAL_HIDDEN
3010 */
3011
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003012struct k_mbox {
3013 _wait_q_t tx_msg_queue;
3014 _wait_q_t rx_msg_queue;
3015
Anas Nashif2f203c22016-12-18 06:57:45 -05003016 _OBJECT_TRACING_NEXT_PTR(k_mbox);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003017};
3018
Andrew Boie65a9d2a2017-06-27 10:51:23 -07003019#define _K_MBOX_INITIALIZER(obj) \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003020 { \
3021 .tx_msg_queue = SYS_DLIST_STATIC_INIT(&obj.tx_msg_queue), \
3022 .rx_msg_queue = SYS_DLIST_STATIC_INIT(&obj.rx_msg_queue), \
Anas Nashif2f203c22016-12-18 06:57:45 -05003023 _OBJECT_TRACING_INIT \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003024 }
3025
Andrew Boie65a9d2a2017-06-27 10:51:23 -07003026#define K_MBOX_INITIALIZER DEPRECATED_MACRO _K_MBOX_INITIALIZER
3027
Peter Mitsis12092702016-10-14 12:57:23 -04003028/**
Allan Stephensc98da842016-11-11 15:45:03 -05003029 * INTERNAL_HIDDEN @endcond
3030 */
3031
3032/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003033 * @brief Statically define and initialize a mailbox.
Peter Mitsis12092702016-10-14 12:57:23 -04003034 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003035 * The mailbox is to be accessed outside the module where it is defined using:
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003036 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05003037 * @code extern struct k_mbox <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003038 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003039 * @param name Name of the mailbox.
Peter Mitsis12092702016-10-14 12:57:23 -04003040 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003041#define K_MBOX_DEFINE(name) \
Allan Stephense7d2cc22016-10-19 16:10:46 -05003042 struct k_mbox name \
3043 __in_section(_k_mbox, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07003044 _K_MBOX_INITIALIZER(name) \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003045
Peter Mitsis12092702016-10-14 12:57:23 -04003046/**
3047 * @brief Initialize a mailbox.
3048 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003049 * This routine initializes a mailbox object, prior to its first use.
3050 *
3051 * @param mbox Address of the mailbox.
Peter Mitsis12092702016-10-14 12:57:23 -04003052 *
3053 * @return N/A
3054 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003055extern void k_mbox_init(struct k_mbox *mbox);
3056
Peter Mitsis12092702016-10-14 12:57:23 -04003057/**
3058 * @brief Send a mailbox message in a synchronous manner.
3059 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003060 * This routine sends a message to @a mbox and waits for a receiver to both
3061 * receive and process it. The message data may be in a buffer, in a memory
3062 * pool block, or non-existent (i.e. an empty message).
Peter Mitsis12092702016-10-14 12:57:23 -04003063 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003064 * @param mbox Address of the mailbox.
3065 * @param tx_msg Address of the transmit message descriptor.
3066 * @param timeout Waiting period for the message to be received (in
3067 * milliseconds), or one of the special values K_NO_WAIT
3068 * and K_FOREVER. Once the message has been received,
3069 * this routine waits as long as necessary for the message
3070 * to be completely processed.
Peter Mitsis12092702016-10-14 12:57:23 -04003071 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05003072 * @retval 0 Message sent.
3073 * @retval -ENOMSG Returned without waiting.
3074 * @retval -EAGAIN Waiting period timed out.
Peter Mitsis12092702016-10-14 12:57:23 -04003075 */
Peter Mitsis40680f62016-10-14 10:04:55 -04003076extern int k_mbox_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
Kumar Galacc334c72017-04-21 10:55:34 -05003077 s32_t timeout);
Peter Mitsis12092702016-10-14 12:57:23 -04003078
Peter Mitsis12092702016-10-14 12:57:23 -04003079/**
3080 * @brief Send a mailbox message in an asynchronous manner.
3081 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003082 * This routine sends a message to @a mbox without waiting for a receiver
3083 * to process it. The message data may be in a buffer, in a memory pool block,
3084 * or non-existent (i.e. an empty message). Optionally, the semaphore @a sem
3085 * will be given when the message has been both received and completely
3086 * processed by the receiver.
Peter Mitsis12092702016-10-14 12:57:23 -04003087 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003088 * @param mbox Address of the mailbox.
3089 * @param tx_msg Address of the transmit message descriptor.
3090 * @param sem Address of a semaphore, or NULL if none is needed.
Peter Mitsis12092702016-10-14 12:57:23 -04003091 *
3092 * @return N/A
3093 */
Peter Mitsis40680f62016-10-14 10:04:55 -04003094extern void k_mbox_async_put(struct k_mbox *mbox, struct k_mbox_msg *tx_msg,
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003095 struct k_sem *sem);
3096
Peter Mitsis12092702016-10-14 12:57:23 -04003097/**
3098 * @brief Receive a mailbox message.
3099 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003100 * This routine receives a message from @a mbox, then optionally retrieves
3101 * its data and disposes of the message.
Peter Mitsis12092702016-10-14 12:57:23 -04003102 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003103 * @param mbox Address of the mailbox.
3104 * @param rx_msg Address of the receive message descriptor.
3105 * @param buffer Address of the buffer to receive data, or NULL to defer data
3106 * retrieval and message disposal until later.
3107 * @param timeout Waiting period for a message to be received (in
3108 * milliseconds), or one of the special values K_NO_WAIT
3109 * and K_FOREVER.
Peter Mitsis12092702016-10-14 12:57:23 -04003110 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05003111 * @retval 0 Message received.
3112 * @retval -ENOMSG Returned without waiting.
3113 * @retval -EAGAIN Waiting period timed out.
Peter Mitsis12092702016-10-14 12:57:23 -04003114 */
Peter Mitsis40680f62016-10-14 10:04:55 -04003115extern int k_mbox_get(struct k_mbox *mbox, struct k_mbox_msg *rx_msg,
Kumar Galacc334c72017-04-21 10:55:34 -05003116 void *buffer, s32_t timeout);
Peter Mitsis12092702016-10-14 12:57:23 -04003117
3118/**
3119 * @brief Retrieve mailbox message data into a buffer.
3120 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003121 * This routine completes the processing of a received message by retrieving
3122 * its data into a buffer, then disposing of the message.
Peter Mitsis12092702016-10-14 12:57:23 -04003123 *
3124 * Alternatively, this routine can be used to dispose of a received message
3125 * without retrieving its data.
3126 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003127 * @param rx_msg Address of the receive message descriptor.
3128 * @param buffer Address of the buffer to receive data, or NULL to discard
3129 * the data.
Peter Mitsis12092702016-10-14 12:57:23 -04003130 *
3131 * @return N/A
3132 */
Peter Mitsis40680f62016-10-14 10:04:55 -04003133extern void k_mbox_data_get(struct k_mbox_msg *rx_msg, void *buffer);
Peter Mitsis12092702016-10-14 12:57:23 -04003134
3135/**
3136 * @brief Retrieve mailbox message data into a memory pool block.
3137 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003138 * This routine completes the processing of a received message by retrieving
3139 * its data into a memory pool block, then disposing of the message.
3140 * The memory pool block that results from successful retrieval must be
3141 * returned to the pool once the data has been processed, even in cases
3142 * where zero bytes of data are retrieved.
Peter Mitsis12092702016-10-14 12:57:23 -04003143 *
3144 * Alternatively, this routine can be used to dispose of a received message
3145 * without retrieving its data. In this case there is no need to return a
3146 * memory pool block to the pool.
3147 *
3148 * This routine allocates a new memory pool block for the data only if the
3149 * data is not already in one. If a new block cannot be allocated, the routine
3150 * returns a failure code and the received message is left unchanged. This
3151 * permits the caller to reattempt data retrieval at a later time or to dispose
3152 * of the received message without retrieving its data.
3153 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003154 * @param rx_msg Address of a receive message descriptor.
3155 * @param pool Address of memory pool, or NULL to discard data.
3156 * @param block Address of the area to hold memory pool block info.
3157 * @param timeout Waiting period to wait for a memory pool block (in
3158 * milliseconds), or one of the special values K_NO_WAIT
3159 * and K_FOREVER.
Peter Mitsis12092702016-10-14 12:57:23 -04003160 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05003161 * @retval 0 Data retrieved.
3162 * @retval -ENOMEM Returned without waiting.
3163 * @retval -EAGAIN Waiting period timed out.
Peter Mitsis12092702016-10-14 12:57:23 -04003164 */
Peter Mitsis40680f62016-10-14 10:04:55 -04003165extern int k_mbox_data_block_get(struct k_mbox_msg *rx_msg,
Peter Mitsis0cb65c32016-09-29 14:07:36 -04003166 struct k_mem_pool *pool,
Kumar Galacc334c72017-04-21 10:55:34 -05003167 struct k_mem_block *block, s32_t timeout);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003168
Allan Stephensc98da842016-11-11 15:45:03 -05003169/**
3170 * @} end defgroup mailbox_apis
3171 */
3172
3173/**
3174 * @cond INTERNAL_HIDDEN
3175 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003176
3177struct k_pipe {
3178 unsigned char *buffer; /* Pipe buffer: may be NULL */
3179 size_t size; /* Buffer size */
3180 size_t bytes_used; /* # bytes used in buffer */
3181 size_t read_index; /* Where in buffer to read from */
3182 size_t write_index; /* Where in buffer to write */
3183
3184 struct {
3185 _wait_q_t readers; /* Reader wait queue */
3186 _wait_q_t writers; /* Writer wait queue */
3187 } wait_q;
3188
Anas Nashif2f203c22016-12-18 06:57:45 -05003189 _OBJECT_TRACING_NEXT_PTR(k_pipe);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003190};
3191
Andrew Boie65a9d2a2017-06-27 10:51:23 -07003192#define _K_PIPE_INITIALIZER(obj, pipe_buffer, pipe_buffer_size) \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003193 { \
3194 .buffer = pipe_buffer, \
3195 .size = pipe_buffer_size, \
3196 .bytes_used = 0, \
3197 .read_index = 0, \
3198 .write_index = 0, \
3199 .wait_q.writers = SYS_DLIST_STATIC_INIT(&obj.wait_q.writers), \
3200 .wait_q.readers = SYS_DLIST_STATIC_INIT(&obj.wait_q.readers), \
Anas Nashif2f203c22016-12-18 06:57:45 -05003201 _OBJECT_TRACING_INIT \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003202 }
3203
Andrew Boie65a9d2a2017-06-27 10:51:23 -07003204#define K_PIPE_INITIALIZER DEPRECATED_MACRO _K_PIPE_INITIALIZER
3205
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003206/**
Allan Stephensc98da842016-11-11 15:45:03 -05003207 * INTERNAL_HIDDEN @endcond
3208 */
3209
3210/**
3211 * @defgroup pipe_apis Pipe APIs
3212 * @ingroup kernel_apis
3213 * @{
3214 */
3215
3216/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003217 * @brief Statically define and initialize a pipe.
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003218 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003219 * The pipe can be accessed outside the module where it is defined using:
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003220 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05003221 * @code extern struct k_pipe <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003222 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003223 * @param name Name of the pipe.
3224 * @param pipe_buffer_size Size of the pipe's ring buffer (in bytes),
3225 * or zero if no ring buffer is used.
3226 * @param pipe_align Alignment of the pipe's ring buffer (power of 2).
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003227 */
Peter Mitsise5d9c582016-10-14 14:44:57 -04003228#define K_PIPE_DEFINE(name, pipe_buffer_size, pipe_align) \
3229 static unsigned char __noinit __aligned(pipe_align) \
3230 _k_pipe_buf_##name[pipe_buffer_size]; \
Allan Stephense7d2cc22016-10-19 16:10:46 -05003231 struct k_pipe name \
3232 __in_section(_k_pipe, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07003233 _K_PIPE_INITIALIZER(name, _k_pipe_buf_##name, pipe_buffer_size)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003234
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003235/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003236 * @brief Initialize a pipe.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003237 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003238 * This routine initializes a pipe object, prior to its first use.
3239 *
3240 * @param pipe Address of the pipe.
3241 * @param buffer Address of the pipe's ring buffer, or NULL if no ring buffer
3242 * is used.
3243 * @param size Size of the pipe's ring buffer (in bytes), or zero if no ring
3244 * buffer is used.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003245 *
3246 * @return N/A
3247 */
Andrew Boieb9a05782017-09-29 16:05:32 -07003248__syscall void k_pipe_init(struct k_pipe *pipe, unsigned char *buffer,
3249 size_t size);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003250
3251/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003252 * @brief Write data to a pipe.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003253 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003254 * This routine writes up to @a bytes_to_write bytes of data to @a pipe.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003255 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003256 * @param pipe Address of the pipe.
3257 * @param data Address of data to write.
3258 * @param bytes_to_write Size of data (in bytes).
3259 * @param bytes_written Address of area to hold the number of bytes written.
3260 * @param min_xfer Minimum number of bytes to write.
3261 * @param timeout Waiting period to wait for the data to be written (in
3262 * milliseconds), or one of the special values K_NO_WAIT
3263 * and K_FOREVER.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003264 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05003265 * @retval 0 At least @a min_xfer bytes of data were written.
3266 * @retval -EIO Returned without waiting; zero data bytes were written.
3267 * @retval -EAGAIN Waiting period timed out; between zero and @a min_xfer
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003268 * minus one data bytes were written.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003269 */
Andrew Boieb9a05782017-09-29 16:05:32 -07003270__syscall int k_pipe_put(struct k_pipe *pipe, void *data,
3271 size_t bytes_to_write, size_t *bytes_written,
3272 size_t min_xfer, s32_t timeout);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003273
3274/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003275 * @brief Read data from a pipe.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003276 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003277 * This routine reads up to @a bytes_to_read bytes of data from @a pipe.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003278 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003279 * @param pipe Address of the pipe.
3280 * @param data Address to place the data read from pipe.
3281 * @param bytes_to_read Maximum number of data bytes to read.
3282 * @param bytes_read Address of area to hold the number of bytes read.
3283 * @param min_xfer Minimum number of data bytes to read.
3284 * @param timeout Waiting period to wait for the data to be read (in
3285 * milliseconds), or one of the special values K_NO_WAIT
3286 * and K_FOREVER.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003287 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05003288 * @retval 0 At least @a min_xfer bytes of data were read.
3289 * @retval -EIO Returned without waiting; zero data bytes were read.
3290 * @retval -EAGAIN Waiting period timed out; between zero and @a min_xfer
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003291 * minus one data bytes were read.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003292 */
Andrew Boieb9a05782017-09-29 16:05:32 -07003293__syscall int k_pipe_get(struct k_pipe *pipe, void *data,
3294 size_t bytes_to_read, size_t *bytes_read,
3295 size_t min_xfer, s32_t timeout);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003296
3297/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003298 * @brief Write memory block to a pipe.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003299 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003300 * This routine writes the data contained in a memory block to @a pipe.
3301 * Once all of the data in the block has been written to the pipe, it will
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003302 * free the memory block @a block and give the semaphore @a sem (if specified).
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003303 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003304 * @param pipe Address of the pipe.
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003305 * @param block Memory block containing data to send
3306 * @param size Number of data bytes in memory block to send
3307 * @param sem Semaphore to signal upon completion (else NULL)
3308 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003309 * @return N/A
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003310 */
3311extern void k_pipe_block_put(struct k_pipe *pipe, struct k_mem_block *block,
3312 size_t size, struct k_sem *sem);
3313
3314/**
Allan Stephensc98da842016-11-11 15:45:03 -05003315 * @} end defgroup pipe_apis
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003316 */
3317
Allan Stephensc98da842016-11-11 15:45:03 -05003318/**
3319 * @cond INTERNAL_HIDDEN
3320 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003321
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003322struct k_mem_slab {
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003323 _wait_q_t wait_q;
Kumar Galacc334c72017-04-21 10:55:34 -05003324 u32_t num_blocks;
Peter Mitsisfb02d572016-10-13 16:55:45 -04003325 size_t block_size;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003326 char *buffer;
3327 char *free_list;
Kumar Galacc334c72017-04-21 10:55:34 -05003328 u32_t num_used;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003329
Anas Nashif2f203c22016-12-18 06:57:45 -05003330 _OBJECT_TRACING_NEXT_PTR(k_mem_slab);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003331};
3332
Andrew Boie65a9d2a2017-06-27 10:51:23 -07003333#define _K_MEM_SLAB_INITIALIZER(obj, slab_buffer, slab_block_size, \
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003334 slab_num_blocks) \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003335 { \
3336 .wait_q = SYS_DLIST_STATIC_INIT(&obj.wait_q), \
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003337 .num_blocks = slab_num_blocks, \
3338 .block_size = slab_block_size, \
3339 .buffer = slab_buffer, \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003340 .free_list = NULL, \
3341 .num_used = 0, \
Anas Nashif2f203c22016-12-18 06:57:45 -05003342 _OBJECT_TRACING_INIT \
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003343 }
3344
Andrew Boie65a9d2a2017-06-27 10:51:23 -07003345#define K_MEM_SLAB_INITIALIZER DEPRECATED_MACRO _K_MEM_SLAB_INITIALIZER
3346
3347
Peter Mitsis578f9112016-10-07 13:50:31 -04003348/**
Allan Stephensc98da842016-11-11 15:45:03 -05003349 * INTERNAL_HIDDEN @endcond
3350 */
3351
3352/**
3353 * @defgroup mem_slab_apis Memory Slab APIs
3354 * @ingroup kernel_apis
3355 * @{
3356 */
3357
3358/**
Allan Stephensda827222016-11-09 14:23:58 -06003359 * @brief Statically define and initialize a memory slab.
Peter Mitsis578f9112016-10-07 13:50:31 -04003360 *
Allan Stephensda827222016-11-09 14:23:58 -06003361 * The memory slab's buffer contains @a slab_num_blocks memory blocks
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003362 * that are @a slab_block_size bytes long. The buffer is aligned to a
Allan Stephensda827222016-11-09 14:23:58 -06003363 * @a slab_align -byte boundary. To ensure that each memory block is similarly
3364 * aligned to this boundary, @a slab_block_size must also be a multiple of
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003365 * @a slab_align.
Peter Mitsis578f9112016-10-07 13:50:31 -04003366 *
Allan Stephensda827222016-11-09 14:23:58 -06003367 * The memory slab can be accessed outside the module where it is defined
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003368 * using:
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003369 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05003370 * @code extern struct k_mem_slab <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003371 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003372 * @param name Name of the memory slab.
3373 * @param slab_block_size Size of each memory block (in bytes).
3374 * @param slab_num_blocks Number memory blocks.
3375 * @param slab_align Alignment of the memory slab's buffer (power of 2).
Peter Mitsis578f9112016-10-07 13:50:31 -04003376 */
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003377#define K_MEM_SLAB_DEFINE(name, slab_block_size, slab_num_blocks, slab_align) \
3378 char __noinit __aligned(slab_align) \
3379 _k_mem_slab_buf_##name[(slab_num_blocks) * (slab_block_size)]; \
3380 struct k_mem_slab name \
Allan Stephense7d2cc22016-10-19 16:10:46 -05003381 __in_section(_k_mem_slab, static, name) = \
Andrew Boie65a9d2a2017-06-27 10:51:23 -07003382 _K_MEM_SLAB_INITIALIZER(name, _k_mem_slab_buf_##name, \
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003383 slab_block_size, slab_num_blocks)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003384
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003385/**
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003386 * @brief Initialize a memory slab.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003387 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003388 * Initializes a memory slab, prior to its first use.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003389 *
Allan Stephensda827222016-11-09 14:23:58 -06003390 * The memory slab's buffer contains @a slab_num_blocks memory blocks
3391 * that are @a slab_block_size bytes long. The buffer must be aligned to an
3392 * N-byte boundary, where N is a power of 2 larger than 2 (i.e. 4, 8, 16, ...).
3393 * To ensure that each memory block is similarly aligned to this boundary,
3394 * @a slab_block_size must also be a multiple of N.
3395 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003396 * @param slab Address of the memory slab.
3397 * @param buffer Pointer to buffer used for the memory blocks.
3398 * @param block_size Size of each memory block (in bytes).
3399 * @param num_blocks Number of memory blocks.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003400 *
3401 * @return N/A
3402 */
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003403extern void k_mem_slab_init(struct k_mem_slab *slab, void *buffer,
Kumar Galacc334c72017-04-21 10:55:34 -05003404 size_t block_size, u32_t num_blocks);
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003405
3406/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003407 * @brief Allocate memory from a memory slab.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003408 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003409 * This routine allocates a memory block from a memory slab.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003410 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003411 * @param slab Address of the memory slab.
3412 * @param mem Pointer to block address area.
3413 * @param timeout Maximum time to wait for operation to complete
3414 * (in milliseconds). Use K_NO_WAIT to return without waiting,
3415 * or K_FOREVER to wait as long as necessary.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003416 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05003417 * @retval 0 Memory allocated. The block address area pointed at by @a mem
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003418 * is set to the starting address of the memory block.
Allan Stephens9ef50f42016-11-16 15:33:31 -05003419 * @retval -ENOMEM Returned without waiting.
3420 * @retval -EAGAIN Waiting period timed out.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003421 */
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003422extern int k_mem_slab_alloc(struct k_mem_slab *slab, void **mem,
Kumar Galacc334c72017-04-21 10:55:34 -05003423 s32_t timeout);
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003424
3425/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003426 * @brief Free memory allocated from a memory slab.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003427 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003428 * This routine releases a previously allocated memory block back to its
3429 * associated memory slab.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003430 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003431 * @param slab Address of the memory slab.
3432 * @param mem Pointer to block address area (as set by k_mem_slab_alloc()).
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003433 *
3434 * @return N/A
3435 */
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003436extern void k_mem_slab_free(struct k_mem_slab *slab, void **mem);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003437
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003438/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003439 * @brief Get the number of used blocks in a memory slab.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003440 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003441 * This routine gets the number of memory blocks that are currently
3442 * allocated in @a slab.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003443 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003444 * @param slab Address of the memory slab.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003445 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003446 * @return Number of allocated memory blocks.
Peter Mitsis4a5d62f2016-10-13 16:53:30 -04003447 */
Kumar Galacc334c72017-04-21 10:55:34 -05003448static inline u32_t k_mem_slab_num_used_get(struct k_mem_slab *slab)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003449{
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003450 return slab->num_used;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003451}
3452
Peter Mitsisc001aa82016-10-13 13:53:37 -04003453/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003454 * @brief Get the number of unused blocks in a memory slab.
Peter Mitsisc001aa82016-10-13 13:53:37 -04003455 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003456 * This routine gets the number of memory blocks that are currently
3457 * unallocated in @a slab.
Peter Mitsisc001aa82016-10-13 13:53:37 -04003458 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003459 * @param slab Address of the memory slab.
Peter Mitsisc001aa82016-10-13 13:53:37 -04003460 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003461 * @return Number of unallocated memory blocks.
Peter Mitsisc001aa82016-10-13 13:53:37 -04003462 */
Kumar Galacc334c72017-04-21 10:55:34 -05003463static inline u32_t k_mem_slab_num_free_get(struct k_mem_slab *slab)
Peter Mitsisc001aa82016-10-13 13:53:37 -04003464{
Benjamin Walsh7ef0f622016-10-24 17:04:43 -04003465 return slab->num_blocks - slab->num_used;
Peter Mitsisc001aa82016-10-13 13:53:37 -04003466}
3467
Allan Stephensc98da842016-11-11 15:45:03 -05003468/**
3469 * @} end defgroup mem_slab_apis
3470 */
3471
3472/**
3473 * @cond INTERNAL_HIDDEN
3474 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003475
Andy Ross73cb9582017-05-09 10:42:39 -07003476struct k_mem_pool_lvl {
3477 union {
3478 u32_t *bits_p;
3479 u32_t bits;
3480 };
3481 sys_dlist_t free_list;
Dmitriy Korovkin3c426882016-09-01 18:14:17 -04003482};
3483
Dmitriy Korovkin3c426882016-09-01 18:14:17 -04003484struct k_mem_pool {
Andy Ross73cb9582017-05-09 10:42:39 -07003485 void *buf;
3486 size_t max_sz;
3487 u16_t n_max;
3488 u8_t n_levels;
3489 u8_t max_inline_level;
3490 struct k_mem_pool_lvl *levels;
Dmitriy Korovkin3c426882016-09-01 18:14:17 -04003491 _wait_q_t wait_q;
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003492};
3493
Andy Ross73cb9582017-05-09 10:42:39 -07003494#define _ALIGN4(n) ((((n)+3)/4)*4)
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003495
Andy Ross73cb9582017-05-09 10:42:39 -07003496#define _MPOOL_HAVE_LVL(max, min, l) (((max) >> (2*(l))) >= (min) ? 1 : 0)
3497
3498#define _MPOOL_LVLS(maxsz, minsz) \
3499 (_MPOOL_HAVE_LVL(maxsz, minsz, 0) + \
3500 _MPOOL_HAVE_LVL(maxsz, minsz, 1) + \
3501 _MPOOL_HAVE_LVL(maxsz, minsz, 2) + \
3502 _MPOOL_HAVE_LVL(maxsz, minsz, 3) + \
3503 _MPOOL_HAVE_LVL(maxsz, minsz, 4) + \
3504 _MPOOL_HAVE_LVL(maxsz, minsz, 5) + \
3505 _MPOOL_HAVE_LVL(maxsz, minsz, 6) + \
3506 _MPOOL_HAVE_LVL(maxsz, minsz, 7) + \
3507 _MPOOL_HAVE_LVL(maxsz, minsz, 8) + \
3508 _MPOOL_HAVE_LVL(maxsz, minsz, 9) + \
3509 _MPOOL_HAVE_LVL(maxsz, minsz, 10) + \
3510 _MPOOL_HAVE_LVL(maxsz, minsz, 11) + \
3511 _MPOOL_HAVE_LVL(maxsz, minsz, 12) + \
3512 _MPOOL_HAVE_LVL(maxsz, minsz, 13) + \
3513 _MPOOL_HAVE_LVL(maxsz, minsz, 14) + \
3514 _MPOOL_HAVE_LVL(maxsz, minsz, 15))
3515
3516/* Rounds the needed bits up to integer multiples of u32_t */
3517#define _MPOOL_LBIT_WORDS_UNCLAMPED(n_max, l) \
3518 ((((n_max) << (2*(l))) + 31) / 32)
3519
3520/* One word gets stored free unioned with the pointer, otherwise the
3521 * calculated unclamped value
Dmitriy Korovkin3c426882016-09-01 18:14:17 -04003522 */
Andy Ross73cb9582017-05-09 10:42:39 -07003523#define _MPOOL_LBIT_WORDS(n_max, l) \
3524 (_MPOOL_LBIT_WORDS_UNCLAMPED(n_max, l) < 2 ? 0 \
3525 : _MPOOL_LBIT_WORDS_UNCLAMPED(n_max, l))
Allan Stephensc98da842016-11-11 15:45:03 -05003526
Andy Ross73cb9582017-05-09 10:42:39 -07003527/* How many bytes for the bitfields of a single level? */
3528#define _MPOOL_LBIT_BYTES(maxsz, minsz, l, n_max) \
3529 (_MPOOL_LVLS((maxsz), (minsz)) >= (l) ? \
3530 4 * _MPOOL_LBIT_WORDS((n_max), l) : 0)
Dmitriy Korovkin3c426882016-09-01 18:14:17 -04003531
Andy Ross73cb9582017-05-09 10:42:39 -07003532/* Size of the bitmap array that follows the buffer in allocated memory */
3533#define _MPOOL_BITS_SIZE(maxsz, minsz, n_max) \
3534 (_MPOOL_LBIT_BYTES(maxsz, minsz, 0, n_max) + \
3535 _MPOOL_LBIT_BYTES(maxsz, minsz, 1, n_max) + \
3536 _MPOOL_LBIT_BYTES(maxsz, minsz, 2, n_max) + \
3537 _MPOOL_LBIT_BYTES(maxsz, minsz, 3, n_max) + \
3538 _MPOOL_LBIT_BYTES(maxsz, minsz, 4, n_max) + \
3539 _MPOOL_LBIT_BYTES(maxsz, minsz, 5, n_max) + \
3540 _MPOOL_LBIT_BYTES(maxsz, minsz, 6, n_max) + \
3541 _MPOOL_LBIT_BYTES(maxsz, minsz, 7, n_max) + \
3542 _MPOOL_LBIT_BYTES(maxsz, minsz, 8, n_max) + \
3543 _MPOOL_LBIT_BYTES(maxsz, minsz, 9, n_max) + \
3544 _MPOOL_LBIT_BYTES(maxsz, minsz, 10, n_max) + \
3545 _MPOOL_LBIT_BYTES(maxsz, minsz, 11, n_max) + \
3546 _MPOOL_LBIT_BYTES(maxsz, minsz, 12, n_max) + \
3547 _MPOOL_LBIT_BYTES(maxsz, minsz, 13, n_max) + \
3548 _MPOOL_LBIT_BYTES(maxsz, minsz, 14, n_max) + \
3549 _MPOOL_LBIT_BYTES(maxsz, minsz, 15, n_max))
Dmitriy Korovkin07414672016-11-03 13:35:42 -04003550
3551/**
Allan Stephensc98da842016-11-11 15:45:03 -05003552 * INTERNAL_HIDDEN @endcond
Dmitriy Korovkin07414672016-11-03 13:35:42 -04003553 */
3554
Peter Mitsis2a2b0752016-10-06 16:27:01 -04003555/**
Allan Stephensc98da842016-11-11 15:45:03 -05003556 * @addtogroup mem_pool_apis
3557 * @{
3558 */
3559
3560/**
3561 * @brief Statically define and initialize a memory pool.
Peter Mitsis2a2b0752016-10-06 16:27:01 -04003562 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003563 * The memory pool's buffer contains @a n_max blocks that are @a max_size bytes
3564 * long. The memory pool allows blocks to be repeatedly partitioned into
3565 * quarters, down to blocks of @a min_size bytes long. The buffer is aligned
Andy Ross73cb9582017-05-09 10:42:39 -07003566 * to a @a align -byte boundary.
Peter Mitsis2a2b0752016-10-06 16:27:01 -04003567 *
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003568 * If the pool is to be accessed outside the module where it is defined, it
3569 * can be declared via
3570 *
Allan Stephens82d4c3a2016-11-17 09:23:46 -05003571 * @code extern struct k_mem_pool <name>; @endcode
Peter Mitsis348eb4c2016-10-26 11:22:14 -04003572 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003573 * @param name Name of the memory pool.
Andy Ross73cb9582017-05-09 10:42:39 -07003574 * @param minsz Size of the smallest blocks in the pool (in bytes).
3575 * @param maxsz Size of the largest blocks in the pool (in bytes).
3576 * @param nmax Number of maximum sized blocks in the pool.
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003577 * @param align Alignment of the pool's buffer (power of 2).
Peter Mitsis2a2b0752016-10-06 16:27:01 -04003578 */
Andy Ross73cb9582017-05-09 10:42:39 -07003579#define K_MEM_POOL_DEFINE(name, minsz, maxsz, nmax, align) \
3580 char __aligned(align) _mpool_buf_##name[_ALIGN4(maxsz * nmax) \
3581 + _MPOOL_BITS_SIZE(maxsz, minsz, nmax)]; \
3582 struct k_mem_pool_lvl _mpool_lvls_##name[_MPOOL_LVLS(maxsz, minsz)]; \
3583 struct k_mem_pool name __in_section(_k_mem_pool, static, name) = { \
3584 .buf = _mpool_buf_##name, \
3585 .max_sz = maxsz, \
3586 .n_max = nmax, \
3587 .n_levels = _MPOOL_LVLS(maxsz, minsz), \
3588 .levels = _mpool_lvls_##name, \
3589 }
Dmitriy Korovkin3c426882016-09-01 18:14:17 -04003590
Peter Mitsis937042c2016-10-13 13:18:26 -04003591/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003592 * @brief Allocate memory from a memory pool.
Peter Mitsis937042c2016-10-13 13:18:26 -04003593 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003594 * This routine allocates a memory block from a memory pool.
Peter Mitsis937042c2016-10-13 13:18:26 -04003595 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003596 * @param pool Address of the memory pool.
3597 * @param block Pointer to block descriptor for the allocated memory.
3598 * @param size Amount of memory to allocate (in bytes).
3599 * @param timeout Maximum time to wait for operation to complete
3600 * (in milliseconds). Use K_NO_WAIT to return without waiting,
3601 * or K_FOREVER to wait as long as necessary.
3602 *
Allan Stephens9ef50f42016-11-16 15:33:31 -05003603 * @retval 0 Memory allocated. The @a data field of the block descriptor
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003604 * is set to the starting address of the memory block.
Allan Stephens9ef50f42016-11-16 15:33:31 -05003605 * @retval -ENOMEM Returned without waiting.
3606 * @retval -EAGAIN Waiting period timed out.
Peter Mitsis937042c2016-10-13 13:18:26 -04003607 */
Dmitriy Korovkin3c426882016-09-01 18:14:17 -04003608extern int k_mem_pool_alloc(struct k_mem_pool *pool, struct k_mem_block *block,
Kumar Galacc334c72017-04-21 10:55:34 -05003609 size_t size, s32_t timeout);
Peter Mitsis937042c2016-10-13 13:18:26 -04003610
3611/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003612 * @brief Free memory allocated from a memory pool.
Peter Mitsis937042c2016-10-13 13:18:26 -04003613 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003614 * This routine releases a previously allocated memory block back to its
3615 * memory pool.
3616 *
3617 * @param block Pointer to block descriptor for the allocated memory.
Peter Mitsis937042c2016-10-13 13:18:26 -04003618 *
3619 * @return N/A
3620 */
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003621extern void k_mem_pool_free(struct k_mem_block *block);
Peter Mitsis937042c2016-10-13 13:18:26 -04003622
3623/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003624 * @brief Defragment a memory pool.
Peter Mitsis937042c2016-10-13 13:18:26 -04003625 *
Andy Ross73cb9582017-05-09 10:42:39 -07003626 * This is a no-op API preserved for backward compatibility only.
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003627 *
Andy Ross73cb9582017-05-09 10:42:39 -07003628 * @param pool Unused
Peter Mitsis937042c2016-10-13 13:18:26 -04003629 *
3630 * @return N/A
3631 */
Andy Ross73cb9582017-05-09 10:42:39 -07003632static inline void __deprecated k_mem_pool_defrag(struct k_mem_pool *pool) {}
Peter Mitsis937042c2016-10-13 13:18:26 -04003633
3634/**
Allan Stephensc98da842016-11-11 15:45:03 -05003635 * @} end addtogroup mem_pool_apis
3636 */
3637
3638/**
3639 * @defgroup heap_apis Heap Memory Pool APIs
3640 * @ingroup kernel_apis
3641 * @{
3642 */
3643
3644/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003645 * @brief Allocate memory from heap.
Peter Mitsis937042c2016-10-13 13:18:26 -04003646 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003647 * This routine provides traditional malloc() semantics. Memory is
Allan Stephens480a1312016-10-13 15:44:48 -05003648 * allocated from the heap memory pool.
Peter Mitsis937042c2016-10-13 13:18:26 -04003649 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003650 * @param size Amount of memory requested (in bytes).
Peter Mitsis937042c2016-10-13 13:18:26 -04003651 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003652 * @return Address of the allocated memory if successful; otherwise NULL.
Peter Mitsis937042c2016-10-13 13:18:26 -04003653 */
Peter Mitsis5f399242016-10-13 13:26:25 -04003654extern void *k_malloc(size_t size);
Peter Mitsis937042c2016-10-13 13:18:26 -04003655
3656/**
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003657 * @brief Free memory allocated from heap.
Allan Stephens480a1312016-10-13 15:44:48 -05003658 *
3659 * This routine provides traditional free() semantics. The memory being
3660 * returned must have been allocated from the heap memory pool.
Peter Mitsis937042c2016-10-13 13:18:26 -04003661 *
Anas Nashif345fdd52016-12-20 08:36:04 -05003662 * If @a ptr is NULL, no operation is performed.
3663 *
Allan Stephens5a7a86c2016-11-04 13:53:19 -05003664 * @param ptr Pointer to previously allocated memory.
Peter Mitsis937042c2016-10-13 13:18:26 -04003665 *
3666 * @return N/A
3667 */
3668extern void k_free(void *ptr);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003669
Allan Stephensc98da842016-11-11 15:45:03 -05003670/**
3671 * @} end defgroup heap_apis
3672 */
3673
Benjamin Walshacc68c12017-01-29 18:57:45 -05003674/* polling API - PRIVATE */
3675
Benjamin Walshb0179862017-02-02 16:39:57 -05003676#ifdef CONFIG_POLL
3677#define _INIT_OBJ_POLL_EVENT(obj) do { (obj)->poll_event = NULL; } while ((0))
3678#else
3679#define _INIT_OBJ_POLL_EVENT(obj) do { } while ((0))
3680#endif
3681
Benjamin Walshacc68c12017-01-29 18:57:45 -05003682/* private - implementation data created as needed, per-type */
3683struct _poller {
3684 struct k_thread *thread;
3685};
3686
3687/* private - types bit positions */
3688enum _poll_types_bits {
3689 /* can be used to ignore an event */
3690 _POLL_TYPE_IGNORE,
3691
3692 /* to be signaled by k_poll_signal() */
3693 _POLL_TYPE_SIGNAL,
3694
3695 /* semaphore availability */
3696 _POLL_TYPE_SEM_AVAILABLE,
3697
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02003698 /* queue/fifo/lifo data availability */
3699 _POLL_TYPE_DATA_AVAILABLE,
Benjamin Walshacc68c12017-01-29 18:57:45 -05003700
3701 _POLL_NUM_TYPES
3702};
3703
3704#define _POLL_TYPE_BIT(type) (1 << ((type) - 1))
3705
3706/* private - states bit positions */
3707enum _poll_states_bits {
3708 /* default state when creating event */
3709 _POLL_STATE_NOT_READY,
3710
Benjamin Walshacc68c12017-01-29 18:57:45 -05003711 /* signaled by k_poll_signal() */
3712 _POLL_STATE_SIGNALED,
3713
3714 /* semaphore is available */
3715 _POLL_STATE_SEM_AVAILABLE,
3716
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02003717 /* data is available to read on queue/fifo/lifo */
3718 _POLL_STATE_DATA_AVAILABLE,
Benjamin Walshacc68c12017-01-29 18:57:45 -05003719
3720 _POLL_NUM_STATES
3721};
3722
3723#define _POLL_STATE_BIT(state) (1 << ((state) - 1))
3724
3725#define _POLL_EVENT_NUM_UNUSED_BITS \
Benjamin Walsh969d4a72017-02-02 11:25:11 -05003726 (32 - (0 \
3727 + 8 /* tag */ \
3728 + _POLL_NUM_TYPES \
3729 + _POLL_NUM_STATES \
3730 + 1 /* modes */ \
3731 ))
Benjamin Walshacc68c12017-01-29 18:57:45 -05003732
3733#if _POLL_EVENT_NUM_UNUSED_BITS < 0
3734#error overflow of 32-bit word in struct k_poll_event
3735#endif
3736
3737/* end of polling API - PRIVATE */
3738
3739
3740/**
3741 * @defgroup poll_apis Async polling APIs
3742 * @ingroup kernel_apis
3743 * @{
3744 */
3745
3746/* Public polling API */
3747
3748/* public - values for k_poll_event.type bitfield */
3749#define K_POLL_TYPE_IGNORE 0
3750#define K_POLL_TYPE_SIGNAL _POLL_TYPE_BIT(_POLL_TYPE_SIGNAL)
3751#define K_POLL_TYPE_SEM_AVAILABLE _POLL_TYPE_BIT(_POLL_TYPE_SEM_AVAILABLE)
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02003752#define K_POLL_TYPE_DATA_AVAILABLE _POLL_TYPE_BIT(_POLL_TYPE_DATA_AVAILABLE)
3753#define K_POLL_TYPE_FIFO_DATA_AVAILABLE K_POLL_TYPE_DATA_AVAILABLE
Benjamin Walshacc68c12017-01-29 18:57:45 -05003754
3755/* public - polling modes */
3756enum k_poll_modes {
3757 /* polling thread does not take ownership of objects when available */
3758 K_POLL_MODE_NOTIFY_ONLY = 0,
3759
3760 K_POLL_NUM_MODES
3761};
3762
3763/* public - values for k_poll_event.state bitfield */
3764#define K_POLL_STATE_NOT_READY 0
Benjamin Walshacc68c12017-01-29 18:57:45 -05003765#define K_POLL_STATE_SIGNALED _POLL_STATE_BIT(_POLL_STATE_SIGNALED)
3766#define K_POLL_STATE_SEM_AVAILABLE _POLL_STATE_BIT(_POLL_STATE_SEM_AVAILABLE)
Luiz Augusto von Dentza7ddb872017-02-21 14:50:42 +02003767#define K_POLL_STATE_DATA_AVAILABLE _POLL_STATE_BIT(_POLL_STATE_DATA_AVAILABLE)
3768#define K_POLL_STATE_FIFO_DATA_AVAILABLE K_POLL_STATE_DATA_AVAILABLE
Benjamin Walshacc68c12017-01-29 18:57:45 -05003769
3770/* public - poll signal object */
3771struct k_poll_signal {
3772 /* PRIVATE - DO NOT TOUCH */
Luiz Augusto von Dentz7d01c5e2017-08-21 10:49:29 +03003773 sys_dlist_t poll_events;
Benjamin Walshacc68c12017-01-29 18:57:45 -05003774
3775 /*
3776 * 1 if the event has been signaled, 0 otherwise. Stays set to 1 until
3777 * user resets it to 0.
3778 */
3779 unsigned int signaled;
3780
3781 /* custom result value passed to k_poll_signal() if needed */
3782 int result;
3783};
3784
Luiz Augusto von Dentz7d01c5e2017-08-21 10:49:29 +03003785#define K_POLL_SIGNAL_INITIALIZER(obj) \
Benjamin Walshacc68c12017-01-29 18:57:45 -05003786 { \
Luiz Augusto von Dentz7d01c5e2017-08-21 10:49:29 +03003787 .poll_events = SYS_DLIST_STATIC_INIT(&obj.poll_events), \
Benjamin Walshacc68c12017-01-29 18:57:45 -05003788 .signaled = 0, \
3789 .result = 0, \
3790 }
3791
3792struct k_poll_event {
3793 /* PRIVATE - DO NOT TOUCH */
Luiz Augusto von Dentz7d01c5e2017-08-21 10:49:29 +03003794 sys_dnode_t _node;
3795
3796 /* PRIVATE - DO NOT TOUCH */
Benjamin Walshacc68c12017-01-29 18:57:45 -05003797 struct _poller *poller;
3798
Benjamin Walsh969d4a72017-02-02 11:25:11 -05003799 /* optional user-specified tag, opaque, untouched by the API */
Kumar Galacc334c72017-04-21 10:55:34 -05003800 u32_t tag:8;
Benjamin Walsh969d4a72017-02-02 11:25:11 -05003801
Benjamin Walshacc68c12017-01-29 18:57:45 -05003802 /* bitfield of event types (bitwise-ORed K_POLL_TYPE_xxx values) */
Kumar Galacc334c72017-04-21 10:55:34 -05003803 u32_t type:_POLL_NUM_TYPES;
Benjamin Walshacc68c12017-01-29 18:57:45 -05003804
3805 /* bitfield of event states (bitwise-ORed K_POLL_STATE_xxx values) */
Kumar Galacc334c72017-04-21 10:55:34 -05003806 u32_t state:_POLL_NUM_STATES;
Benjamin Walshacc68c12017-01-29 18:57:45 -05003807
3808 /* mode of operation, from enum k_poll_modes */
Kumar Galacc334c72017-04-21 10:55:34 -05003809 u32_t mode:1;
Benjamin Walshacc68c12017-01-29 18:57:45 -05003810
3811 /* unused bits in 32-bit word */
Kumar Galacc334c72017-04-21 10:55:34 -05003812 u32_t unused:_POLL_EVENT_NUM_UNUSED_BITS;
Benjamin Walshacc68c12017-01-29 18:57:45 -05003813
3814 /* per-type data */
3815 union {
3816 void *obj;
3817 struct k_poll_signal *signal;
3818 struct k_sem *sem;
3819 struct k_fifo *fifo;
Luiz Augusto von Dentze5ed88f2017-02-21 15:27:20 +02003820 struct k_queue *queue;
Benjamin Walshacc68c12017-01-29 18:57:45 -05003821 };
3822};
3823
Benjamin Walsh969d4a72017-02-02 11:25:11 -05003824#define K_POLL_EVENT_INITIALIZER(event_type, event_mode, event_obj) \
Benjamin Walshacc68c12017-01-29 18:57:45 -05003825 { \
3826 .poller = NULL, \
3827 .type = event_type, \
3828 .state = K_POLL_STATE_NOT_READY, \
3829 .mode = event_mode, \
3830 .unused = 0, \
Benjamin Walsh969d4a72017-02-02 11:25:11 -05003831 { .obj = event_obj }, \
3832 }
3833
3834#define K_POLL_EVENT_STATIC_INITIALIZER(event_type, event_mode, event_obj, \
3835 event_tag) \
3836 { \
3837 .type = event_type, \
3838 .tag = event_tag, \
3839 .state = K_POLL_STATE_NOT_READY, \
3840 .mode = event_mode, \
3841 .unused = 0, \
3842 { .obj = event_obj }, \
Benjamin Walshacc68c12017-01-29 18:57:45 -05003843 }
3844
3845/**
3846 * @brief Initialize one struct k_poll_event instance
3847 *
3848 * After this routine is called on a poll event, the event it ready to be
3849 * placed in an event array to be passed to k_poll().
3850 *
3851 * @param event The event to initialize.
3852 * @param type A bitfield of the types of event, from the K_POLL_TYPE_xxx
3853 * values. Only values that apply to the same object being polled
3854 * can be used together. Choosing K_POLL_TYPE_IGNORE disables the
3855 * event.
Paul Sokolovskycfef9792017-07-18 11:53:06 +03003856 * @param mode Future. Use K_POLL_MODE_NOTIFY_ONLY.
Benjamin Walshacc68c12017-01-29 18:57:45 -05003857 * @param obj Kernel object or poll signal.
3858 *
3859 * @return N/A
3860 */
3861
Kumar Galacc334c72017-04-21 10:55:34 -05003862extern void k_poll_event_init(struct k_poll_event *event, u32_t type,
Benjamin Walshacc68c12017-01-29 18:57:45 -05003863 int mode, void *obj);
3864
3865/**
3866 * @brief Wait for one or many of multiple poll events to occur
3867 *
3868 * This routine allows a thread to wait concurrently for one or many of
3869 * multiple poll events to have occurred. Such events can be a kernel object
3870 * being available, like a semaphore, or a poll signal event.
3871 *
3872 * When an event notifies that a kernel object is available, the kernel object
3873 * is not "given" to the thread calling k_poll(): it merely signals the fact
3874 * that the object was available when the k_poll() call was in effect. Also,
3875 * all threads trying to acquire an object the regular way, i.e. by pending on
3876 * the object, have precedence over the thread polling on the object. This
3877 * means that the polling thread will never get the poll event on an object
3878 * until the object becomes available and its pend queue is empty. For this
3879 * reason, the k_poll() call is more effective when the objects being polled
3880 * only have one thread, the polling thread, trying to acquire them.
3881 *
Luiz Augusto von Dentz7d01c5e2017-08-21 10:49:29 +03003882 * When k_poll() returns 0, the caller should loop on all the events that were
3883 * passed to k_poll() and check the state field for the values that were
3884 * expected and take the associated actions.
Benjamin Walshacc68c12017-01-29 18:57:45 -05003885 *
3886 * Before being reused for another call to k_poll(), the user has to reset the
3887 * state field to K_POLL_STATE_NOT_READY.
3888 *
3889 * @param events An array of pointers to events to be polled for.
3890 * @param num_events The number of events in the array.
3891 * @param timeout Waiting period for an event to be ready (in milliseconds),
3892 * or one of the special values K_NO_WAIT and K_FOREVER.
3893 *
3894 * @retval 0 One or more events are ready.
Benjamin Walshacc68c12017-01-29 18:57:45 -05003895 * @retval -EAGAIN Waiting period timed out.
3896 */
3897
3898extern int k_poll(struct k_poll_event *events, int num_events,
Kumar Galacc334c72017-04-21 10:55:34 -05003899 s32_t timeout);
Benjamin Walshacc68c12017-01-29 18:57:45 -05003900
3901/**
Benjamin Walsha304f162017-02-02 16:46:09 -05003902 * @brief Initialize a poll signal object.
3903 *
3904 * Ready a poll signal object to be signaled via k_poll_signal().
3905 *
3906 * @param signal A poll signal.
3907 *
3908 * @return N/A
3909 */
3910
3911extern void k_poll_signal_init(struct k_poll_signal *signal);
3912
3913/**
Benjamin Walshacc68c12017-01-29 18:57:45 -05003914 * @brief Signal a poll signal object.
3915 *
3916 * This routine makes ready a poll signal, which is basically a poll event of
3917 * type K_POLL_TYPE_SIGNAL. If a thread was polling on that event, it will be
3918 * made ready to run. A @a result value can be specified.
3919 *
3920 * The poll signal contains a 'signaled' field that, when set by
3921 * k_poll_signal(), stays set until the user sets it back to 0. It thus has to
3922 * be reset by the user before being passed again to k_poll() or k_poll() will
3923 * consider it being signaled, and will return immediately.
3924 *
3925 * @param signal A poll signal.
3926 * @param result The value to store in the result field of the signal.
3927 *
3928 * @retval 0 The signal was delivered successfully.
3929 * @retval -EAGAIN The polling thread's timeout is in the process of expiring.
3930 */
3931
3932extern int k_poll_signal(struct k_poll_signal *signal, int result);
3933
3934/* private internal function */
Luiz Augusto von Dentz7d01c5e2017-08-21 10:49:29 +03003935extern int _handle_obj_poll_events(sys_dlist_t *events, u32_t state);
Benjamin Walshacc68c12017-01-29 18:57:45 -05003936
3937/**
3938 * @} end defgroup poll_apis
3939 */
3940
Benjamin Walshc3a2bbb2016-12-14 13:04:36 -05003941/**
3942 * @brief Make the CPU idle.
3943 *
3944 * This function makes the CPU idle until an event wakes it up.
3945 *
3946 * In a regular system, the idle thread should be the only thread responsible
3947 * for making the CPU idle and triggering any type of power management.
3948 * However, in some more constrained systems, such as a single-threaded system,
3949 * the only thread would be responsible for this if needed.
3950 *
3951 * @return N/A
3952 */
3953extern void k_cpu_idle(void);
3954
3955/**
3956 * @brief Make the CPU idle in an atomic fashion.
3957 *
3958 * Similar to k_cpu_idle(), but called with interrupts locked if operations
3959 * must be done atomically before making the CPU idle.
3960 *
3961 * @param key Interrupt locking key obtained from irq_lock().
3962 *
3963 * @return N/A
3964 */
3965extern void k_cpu_atomic_idle(unsigned int key);
3966
Kumar Galacc334c72017-04-21 10:55:34 -05003967extern void _sys_power_save_idle_exit(s32_t ticks);
Andrew Boie350f88d2017-01-18 13:13:45 -08003968
Benjamin Walsh456c6da2016-09-02 18:55:39 -04003969#include <arch/cpu.h>
3970
Andrew Boiecdb94d62017-04-18 15:22:05 -07003971#ifdef _ARCH_EXCEPT
3972/* This archtecture has direct support for triggering a CPU exception */
3973#define _k_except_reason(reason) _ARCH_EXCEPT(reason)
3974#else
3975
3976#include <misc/printk.h>
3977
3978/* NOTE: This is the implementation for arches that do not implement
3979 * _ARCH_EXCEPT() to generate a real CPU exception.
3980 *
3981 * We won't have a real exception frame to determine the PC value when
3982 * the oops occurred, so print file and line number before we jump into
3983 * the fatal error handler.
3984 */
3985#define _k_except_reason(reason) do { \
3986 printk("@ %s:%d:\n", __FILE__, __LINE__); \
3987 _NanoFatalErrorHandler(reason, &_default_esf); \
3988 CODE_UNREACHABLE; \
3989 } while (0)
3990
3991#endif /* _ARCH__EXCEPT */
3992
3993/**
3994 * @brief Fatally terminate a thread
3995 *
3996 * This should be called when a thread has encountered an unrecoverable
3997 * runtime condition and needs to terminate. What this ultimately
3998 * means is determined by the _fatal_error_handler() implementation, which
3999 * will be called will reason code _NANO_ERR_KERNEL_OOPS.
4000 *
4001 * If this is called from ISR context, the default system fatal error handler
4002 * will treat it as an unrecoverable system error, just like k_panic().
4003 */
4004#define k_oops() _k_except_reason(_NANO_ERR_KERNEL_OOPS)
4005
4006/**
4007 * @brief Fatally terminate the system
4008 *
4009 * This should be called when the Zephyr kernel has encountered an
4010 * unrecoverable runtime condition and needs to terminate. What this ultimately
4011 * means is determined by the _fatal_error_handler() implementation, which
4012 * will be called will reason code _NANO_ERR_KERNEL_PANIC.
4013 */
4014#define k_panic() _k_except_reason(_NANO_ERR_KERNEL_PANIC)
4015
Benjamin Walsh456c6da2016-09-02 18:55:39 -04004016/*
4017 * private APIs that are utilized by one or more public APIs
4018 */
4019
Benjamin Walshb12a8e02016-12-14 15:24:12 -05004020#ifdef CONFIG_MULTITHREADING
Benjamin Walsh456c6da2016-09-02 18:55:39 -04004021extern void _init_static_threads(void);
Benjamin Walshb12a8e02016-12-14 15:24:12 -05004022#else
4023#define _init_static_threads() do { } while ((0))
4024#endif
4025
4026extern int _is_thread_essential(void);
Allan Stephens1342adb2016-11-03 13:54:53 -05004027extern void _timer_expiration_handler(struct _timeout *t);
Benjamin Walsh456c6da2016-09-02 18:55:39 -04004028
Andrew Boiedc5d9352017-06-02 12:56:47 -07004029/* arch/cpu.h may declare an architecture or platform-specific macro
4030 * for properly declaring stacks, compatible with MMU/MPU constraints if
4031 * enabled
4032 */
4033#ifdef _ARCH_THREAD_STACK_DEFINE
4034#define K_THREAD_STACK_DEFINE(sym, size) _ARCH_THREAD_STACK_DEFINE(sym, size)
4035#define K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size) \
4036 _ARCH_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size)
4037#define K_THREAD_STACK_MEMBER(sym, size) _ARCH_THREAD_STACK_MEMBER(sym, size)
4038#define K_THREAD_STACK_SIZEOF(sym) _ARCH_THREAD_STACK_SIZEOF(sym)
Andrew Boie507852a2017-07-25 18:47:07 -07004039static inline char *K_THREAD_STACK_BUFFER(k_thread_stack_t sym)
4040{
4041 return _ARCH_THREAD_STACK_BUFFER(sym);
4042}
Andrew Boiedc5d9352017-06-02 12:56:47 -07004043#else
4044/**
4045 * @brief Declare a toplevel thread stack memory region
4046 *
4047 * This declares a region of memory suitable for use as a thread's stack.
4048 *
4049 * This is the generic, historical definition. Align to STACK_ALIGN and put in
4050 * 'noinit' section so that it isn't zeroed at boot
4051 *
Andrew Boie507852a2017-07-25 18:47:07 -07004052 * The declared symbol will always be a k_thread_stack_t which can be passed to
4053 * k_thread_create, but should otherwise not be manipulated. If the buffer
4054 * inside needs to be examined, use K_THREAD_STACK_BUFFER().
Andrew Boiedc5d9352017-06-02 12:56:47 -07004055 *
4056 * It is legal to precede this definition with the 'static' keyword.
4057 *
4058 * It is NOT legal to take the sizeof(sym) and pass that to the stackSize
4059 * parameter of k_thread_create(), it may not be the same as the
4060 * 'size' parameter. Use K_THREAD_STACK_SIZEOF() instead.
4061 *
4062 * @param sym Thread stack symbol name
4063 * @param size Size of the stack memory region
4064 */
4065#define K_THREAD_STACK_DEFINE(sym, size) \
Andrew Boie507852a2017-07-25 18:47:07 -07004066 struct _k_thread_stack_element __noinit __aligned(STACK_ALIGN) sym[size]
Andrew Boiedc5d9352017-06-02 12:56:47 -07004067
4068/**
4069 * @brief Declare a toplevel array of thread stack memory regions
4070 *
4071 * Create an array of equally sized stacks. See K_THREAD_STACK_DEFINE
4072 * definition for additional details and constraints.
4073 *
4074 * This is the generic, historical definition. Align to STACK_ALIGN and put in
4075 * 'noinit' section so that it isn't zeroed at boot
4076 *
4077 * @param sym Thread stack symbol name
4078 * @param nmemb Number of stacks to declare
4079 * @param size Size of the stack memory region
4080 */
4081
4082#define K_THREAD_STACK_ARRAY_DEFINE(sym, nmemb, size) \
Andrew Boie507852a2017-07-25 18:47:07 -07004083 struct _k_thread_stack_element __noinit \
4084 __aligned(STACK_ALIGN) sym[nmemb][size]
Andrew Boiedc5d9352017-06-02 12:56:47 -07004085
4086/**
4087 * @brief Declare an embedded stack memory region
4088 *
4089 * Used for stacks embedded within other data structures. Use is highly
4090 * discouraged but in some cases necessary. For memory protection scenarios,
4091 * it is very important that any RAM preceding this member not be writable
4092 * by threads else a stack overflow will lead to silent corruption. In other
4093 * words, the containing data structure should live in RAM owned by the kernel.
4094 *
4095 * @param sym Thread stack symbol name
4096 * @param size Size of the stack memory region
4097 */
4098#define K_THREAD_STACK_MEMBER(sym, size) \
Andrew Boie507852a2017-07-25 18:47:07 -07004099 struct _k_thread_stack_element __aligned(STACK_ALIGN) sym[size]
Andrew Boiedc5d9352017-06-02 12:56:47 -07004100
4101/**
4102 * @brief Return the size in bytes of a stack memory region
4103 *
4104 * Convenience macro for passing the desired stack size to k_thread_create()
4105 * since the underlying implementation may actually create something larger
4106 * (for instance a guard area).
4107 *
4108 * The value returned here is guaranteed to match the 'size' parameter
Andrew Boiebefb0692017-07-20 14:22:23 -07004109 * passed to K_THREAD_STACK_DEFINE.
4110 *
4111 * Do not use this for stacks declared with K_THREAD_STACK_ARRAY_DEFINE(),
4112 * it is not guaranteed to return the original value since each array
4113 * element must be aligned.
Andrew Boiedc5d9352017-06-02 12:56:47 -07004114 *
4115 * @param sym Stack memory symbol
4116 * @return Size of the stack
4117 */
4118#define K_THREAD_STACK_SIZEOF(sym) sizeof(sym)
4119
4120/**
4121 * @brief Get a pointer to the physical stack buffer
4122 *
4123 * Convenience macro to get at the real underlying stack buffer used by
4124 * the CPU. Guaranteed to be a character pointer of size K_THREAD_STACK_SIZEOF.
4125 * This is really only intended for diagnostic tools which want to examine
4126 * stack memory contents.
4127 *
4128 * @param sym Declared stack symbol name
4129 * @return The buffer itself, a char *
4130 */
Andrew Boie507852a2017-07-25 18:47:07 -07004131static inline char *K_THREAD_STACK_BUFFER(k_thread_stack_t sym)
4132{
4133 return (char *)sym;
4134}
Andrew Boiedc5d9352017-06-02 12:56:47 -07004135
4136#endif /* _ARCH_DECLARE_STACK */
4137
Chunlin Hane9c97022017-07-07 20:29:30 +08004138/**
4139 * @defgroup mem_domain_apis Memory domain APIs
4140 * @ingroup kernel_apis
4141 * @{
4142 */
4143
4144/** @def MEM_PARTITION_ENTRY
4145 * @brief Used to declare a memory partition entry
4146 */
4147#define MEM_PARTITION_ENTRY(_start, _size, _attr) \
4148 {\
4149 .start = _start, \
4150 .size = _size, \
4151 .attr = _attr, \
4152 }
4153
4154/** @def K_MEM_PARTITION_DEFINE
4155 * @brief Used to declare a memory partition
4156 */
4157#ifdef _ARCH_MEM_PARTITION_ALIGN_CHECK
4158#define K_MEM_PARTITION_DEFINE(name, start, size, attr) \
4159 _ARCH_MEM_PARTITION_ALIGN_CHECK(start, size); \
4160 struct k_mem_partition name = \
4161 MEM_PARTITION_ENTRY((u32_t)start, size, attr)
4162#else
4163#define K_MEM_PARTITION_DEFINE(name, start, size, attr) \
4164 struct k_mem_partition name = \
4165 MEM_PARTITION_ENTRY((u32_t)start, size, attr)
4166#endif /* _ARCH_MEM_PARTITION_ALIGN_CHECK */
4167
4168
4169/* memory partition */
4170struct k_mem_partition {
4171 /* start address of memory partition */
4172 u32_t start;
4173 /* size of memory partition */
4174 u32_t size;
4175 /* attribute of memory partition */
4176 u32_t attr;
4177};
4178
4179#if defined(CONFIG_USERSPACE)
4180/* memory domian */
4181struct k_mem_domain {
4182 /* number of partitions in the domain */
4183 u32_t num_partitions;
4184 /* partitions in the domain */
4185 struct k_mem_partition partitions[CONFIG_MAX_DOMAIN_PARTITIONS];
4186 /* domain q */
4187 sys_dlist_t mem_domain_q;
4188};
4189#endif /* CONFIG_USERSPACE */
4190
4191/**
4192 * @brief Initialize a memory domain.
4193 *
4194 * Initialize a memory domain with given name and memory partitions.
4195 *
4196 * @param domain The memory domain to be initialized.
4197 * @param num_parts The number of array items of "parts" parameter.
4198 * @param parts An array of pointers to the memory partitions. Can be NULL
4199 * if num_parts is zero.
4200 */
4201
4202extern void k_mem_domain_init(struct k_mem_domain *domain, u32_t num_parts,
4203 struct k_mem_partition *parts[]);
4204/**
4205 * @brief Destroy a memory domain.
4206 *
4207 * Destroy a memory domain.
4208 *
4209 * @param domain The memory domain to be destroyed.
4210 */
4211
4212extern void k_mem_domain_destroy(struct k_mem_domain *domain);
4213
4214/**
4215 * @brief Add a memory partition into a memory domain.
4216 *
4217 * Add a memory partition into a memory domain.
4218 *
4219 * @param domain The memory domain to be added a memory partition.
4220 * @param part The memory partition to be added
4221 */
4222
4223extern void k_mem_domain_add_partition(struct k_mem_domain *domain,
4224 struct k_mem_partition *part);
4225
4226/**
4227 * @brief Remove a memory partition from a memory domain.
4228 *
4229 * Remove a memory partition from a memory domain.
4230 *
4231 * @param domain The memory domain to be removed a memory partition.
4232 * @param part The memory partition to be removed
4233 */
4234
4235extern void k_mem_domain_remove_partition(struct k_mem_domain *domain,
4236 struct k_mem_partition *part);
4237
4238/**
4239 * @brief Add a thread into a memory domain.
4240 *
4241 * Add a thread into a memory domain.
4242 *
4243 * @param domain The memory domain that the thread is going to be added into.
4244 * @param thread ID of thread going to be added into the memory domain.
4245 */
4246
4247extern void k_mem_domain_add_thread(struct k_mem_domain *domain,
4248 k_tid_t thread);
4249
4250/**
4251 * @brief Remove a thread from its memory domain.
4252 *
4253 * Remove a thread from its memory domain.
4254 *
4255 * @param thread ID of thread going to be removed from its memory domain.
4256 */
4257
4258extern void k_mem_domain_remove_thread(k_tid_t thread);
4259
4260/**
4261 * @} end defgroup mem_domain_apis
4262 */
4263
Benjamin Walsh456c6da2016-09-02 18:55:39 -04004264#ifdef __cplusplus
4265}
4266#endif
4267
Andrew Boiee004dec2016-11-07 09:01:19 -08004268#if defined(CONFIG_CPLUSPLUS) && defined(__cplusplus)
4269/*
4270 * Define new and delete operators.
4271 * At this moment, the operators do nothing since objects are supposed
4272 * to be statically allocated.
4273 */
4274inline void operator delete(void *ptr)
4275{
4276 (void)ptr;
4277}
4278
4279inline void operator delete[](void *ptr)
4280{
4281 (void)ptr;
4282}
4283
4284inline void *operator new(size_t size)
4285{
4286 (void)size;
4287 return NULL;
4288}
4289
4290inline void *operator new[](size_t size)
4291{
4292 (void)size;
4293 return NULL;
4294}
4295
4296/* Placement versions of operator new and delete */
4297inline void operator delete(void *ptr1, void *ptr2)
4298{
4299 (void)ptr1;
4300 (void)ptr2;
4301}
4302
4303inline void operator delete[](void *ptr1, void *ptr2)
4304{
4305 (void)ptr1;
4306 (void)ptr2;
4307}
4308
4309inline void *operator new(size_t size, void *ptr)
4310{
4311 (void)size;
4312 return ptr;
4313}
4314
4315inline void *operator new[](size_t size, void *ptr)
4316{
4317 (void)size;
4318 return ptr;
4319}
4320
4321#endif /* defined(CONFIG_CPLUSPLUS) && defined(__cplusplus) */
4322
Andrew Boiefa94ee72017-09-28 16:54:35 -07004323#include <syscalls/kernel.h>
4324
Benjamin Walshdfa7ce52017-01-22 17:06:05 -05004325#endif /* !_ASMLANGUAGE */
4326
Benjamin Walsh456c6da2016-09-02 18:55:39 -04004327#endif /* _kernel__h_ */