p4wq.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef ZEPHYR_INCLUDE_SYS_P4WQ_H_
#define ZEPHYR_INCLUDE_SYS_P4WQ_H_
 
#include <zephyr/kernel.h>
#include <zephyr/sys/iterable_sections.h>
 
/* Zephyr Pooled Parallel Preemptible Priority-based Work Queues */
 
struct k_p4wq_work;
 
typedef void (*k_p4wq_handler_t)(struct k_p4wq_work *work);
 
typedef void (*k_p4wq_done_handler_t)(struct k_p4wq_work *work);
 
struct k_p4wq_work {
        /* Filled out by submitting code */
        int32_t priority;
        int32_t deadline;
        k_p4wq_handler_t handler;
        bool sync;
        struct k_sem done_sem;
 
        /* reserved for implementation */
        union {
                struct rbnode rbnode;
                sys_dlist_t dlnode;
        };
        struct k_thread *thread;
        struct k_p4wq *queue;
};
 
#define K_P4WQ_QUEUE_PER_THREAD         BIT(0)
#define K_P4WQ_DELAYED_START            BIT(1)
#define K_P4WQ_USER_CPU_MASK            BIT(2)
 
struct k_p4wq {
        struct k_spinlock lock;
 
        /* Pending threads waiting for work items
         *
         * FIXME: a waitq isn't really the right data structure here.
         * Wait queues are priority-sorted, but we don't want that
         * sorting overhead since we're effectively doing it ourselves
         * by directly mutating the priority when a thread is
         * unpended.  We just want "blocked threads on a list", but
         * there's no clean scheduler API for that.
         */
        _wait_q_t waitq;
 
        /* Work items waiting for processing */
        struct rbtree queue;
 
        /* Work items in progress */
        sys_dlist_t active;
 
        /* K_P4WQ_* flags above */
        uint32_t flags;
 
        /* done handler which is called every time after work was successfully executed
         * and k_p4wq_work is not needed by p4wq anymore
         */
        k_p4wq_done_handler_t done_handler;
};
 
struct k_p4wq_initparam {
        uint32_t num;
        uintptr_t stack_size;
        struct k_p4wq *queue;
        struct k_thread *threads;
        struct z_thread_stack_element *stacks;
        uint32_t flags;
        k_p4wq_done_handler_t done_handler;
};
 
#define K_P4WQ_DEFINE_WITH_DONE_HANDLER(name, n_threads, stack_sz, dn_handler)                  \
        static K_THREAD_STACK_ARRAY_DEFINE(_p4stacks_##name,            \
                                           n_threads, stack_sz);        \
        static struct k_thread _p4threads_##name[n_threads];            \
        static struct k_p4wq name;                                      \
        static const STRUCT_SECTION_ITERABLE(k_p4wq_initparam,          \
                                             _init_##name) = {          \
                .num = n_threads,                                       \
                .stack_size = stack_sz,                                 \
                .threads = _p4threads_##name,                           \
                .stacks = &(_p4stacks_##name[0][0]),                    \
                .queue = &name,                                         \
                .flags = 0,                                             \
                .done_handler = dn_handler,                     \
        }
 
#define K_P4WQ_DEFINE(name, n_threads, stack_sz)                        \
        K_P4WQ_DEFINE_WITH_DONE_HANDLER(name, n_threads, stack_sz, NULL)
 
#define K_P4WQ_ARRAY_DEFINE_WITH_DONE_HANDLER(name, n_threads, stack_sz, flg, dn_handler) \
        static K_THREAD_STACK_ARRAY_DEFINE(_p4stacks_##name,            \
                                           n_threads, stack_sz);        \
        static struct k_thread _p4threads_##name[n_threads];            \
        static struct k_p4wq name[n_threads];                           \
        static const STRUCT_SECTION_ITERABLE(k_p4wq_initparam,          \
                                             _init_##name) = {          \
                .num = n_threads,                                       \
                .stack_size = stack_sz,                                 \
                .threads = _p4threads_##name,                           \
                .stacks = &(_p4stacks_##name[0][0]),                    \
                .queue = name,                                          \
                .flags = K_P4WQ_QUEUE_PER_THREAD | flg,                 \
                .done_handler = dn_handler,                                                     \
        }
 
#define K_P4WQ_ARRAY_DEFINE(name, n_threads, stack_sz, flg)             \
        K_P4WQ_ARRAY_DEFINE_WITH_DONE_HANDLER(name, n_threads, stack_sz, flg, NULL)
 
void k_p4wq_init(struct k_p4wq *queue);
 
void k_p4wq_add_thread(struct k_p4wq *queue, struct k_thread *thread,
                       k_thread_stack_t *stack,
                       size_t stack_size);
 
void k_p4wq_submit(struct k_p4wq *queue, struct k_p4wq_work *item);
 
bool k_p4wq_cancel(struct k_p4wq *queue, struct k_p4wq_work *item);
 
int k_p4wq_wait(struct k_p4wq_work *work, k_timeout_t timeout);
 
void k_p4wq_enable_static_thread(struct k_p4wq *queue, struct k_thread *thread,
                                 uint32_t cpu_mask);
 
#endif /* ZEPHYR_INCLUDE_SYS_P4WQ_H_ */