p4wq.h File Reference

#include <zephyr/kernel.h>
#include <zephyr/sys/iterable_sections.h>

Go to the source code of this file.

Data Structures
struct	k_p4wq_work
	P4 Queue Work Item. More...
struct	k_p4wq
	P4 Queue. More...
struct	k_p4wq_initparam

Macros
#define	K_P4WQ_QUEUE_PER_THREAD   BIT(0)
#define	K_P4WQ_DELAYED_START   BIT(1)
#define	K_P4WQ_USER_CPU_MASK   BIT(2)
#define	K_P4WQ_DEFINE(name, n_threads, stack_sz)
	Statically initialize a P4 Work Queue.
#define	K_P4WQ_ARRAY_DEFINE(name, n_threads, stack_sz, flg)
	Statically initialize an array of P4 Work Queues.

Typedefs
typedef void(*	k_p4wq_handler_t) (struct k_p4wq_work *work)
	P4 Queue handler callback.

Functions
void	k_p4wq_init (struct k_p4wq *queue)
	Initialize P4 Queue.
void	k_p4wq_add_thread (struct k_p4wq *queue, struct k_thread *thread, k_thread_stack_t *stack, size_t stack_size)
	Dynamically add a thread object to a P4 Queue pool.
void	k_p4wq_submit (struct k_p4wq *queue, struct k_p4wq_work *item)
	Submit work item to a P4 queue.
bool	k_p4wq_cancel (struct k_p4wq *queue, struct k_p4wq_work *item)
	Cancel submitted P4 work item.
int	k_p4wq_wait (struct k_p4wq_work *work, k_timeout_t timeout)
	Regain ownership of the work item, wait for completion if it's synchronous.
void	k_p4wq_enable_static_thread (struct k_p4wq *queue, struct k_thread *thread, uint32_t cpu_mask)

Macro Definition Documentation

K_P4WQ_ARRAY_DEFINE

#define K_P4WQ_ARRAY_DEFINE	(		name,
			n_threads,
			stack_sz,
			flg
	)

Value:

        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,                 \
        }

Statically initialize an array of P4 Work Queues.

Statically defines an array of struct k_p4wq objects with the specified number of threads which will be initialized at boot and ready for use on entry to main().

Parameters

name	Symbol name of the struct k_p4wq array that will be defined
n_threads	Number of threads and work queues
stack_sz	Requested stack size of each thread, in bytes
flg	Flags

K_P4WQ_DEFINE

#define K_P4WQ_DEFINE	(		name,
			n_threads,
			stack_sz
	)

Value:

        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,                                             \
        }

Statically initialize a P4 Work Queue.

Statically defines a struct k_p4wq object with the specified number of threads which will be initialized at boot and ready for use on entry to main().

Parameters

name	Symbol name of the struct k_p4wq that will be defined
n_threads	Number of threads in the work queue pool
stack_sz	Requested stack size of each thread, in bytes

K_P4WQ_DELAYED_START

#define K_P4WQ_DELAYED_START   BIT(1)

K_P4WQ_QUEUE_PER_THREAD

#define K_P4WQ_QUEUE_PER_THREAD   BIT(0)

K_P4WQ_USER_CPU_MASK

#define K_P4WQ_USER_CPU_MASK   BIT(2)

Typedef Documentation

k_p4wq_handler_t

typedef void(* k_p4wq_handler_t) (struct k_p4wq_work *work)

P4 Queue handler callback.

Function Documentation

k_p4wq_add_thread()

void k_p4wq_add_thread	(	struct k_p4wq *	queue,
		struct k_thread *	thread,
		k_thread_stack_t *	stack,
		size_t	stack_size
	)

Dynamically add a thread object to a P4 Queue pool.

Adds a thread to the pool managed by a P4 queue. The thread object must not be in use. If k_thread_create() has previously been called on it, it must be aborted before being given to the queue.

Parameters

queue	P4 Queue to which to add the thread
thread	Uninitialized/aborted thread object to add
stack	Thread stack memory
stack_size	Thread stack size

k_p4wq_cancel()

bool k_p4wq_cancel	(	struct k_p4wq *	queue,
		struct k_p4wq_work *	item
	)

Cancel submitted P4 work item.

Cancels a previously-submitted work item and removes it from the queue. Returns true if the item was found in the queue and removed. If the function returns false, either the item was never submitted, has already been executed, or is still running.

Returns

true if the item was successfully removed, otherwise false

k_p4wq_enable_static_thread()

void k_p4wq_enable_static_thread	(	struct k_p4wq *	queue,
		struct k_thread *	thread,
		uint32_t	cpu_mask
	)

k_p4wq_init()

void k_p4wq_init

(

struct k_p4wq *

queue

)

Initialize P4 Queue.

Initializes a P4 Queue object. These objects must be initialized via this function (or statically using K_P4WQ_DEFINE) before any other API calls are made on it.

Parameters

queue

P4 Queue to initialize

k_p4wq_submit()

void k_p4wq_submit	(	struct k_p4wq *	queue,
		struct k_p4wq_work *	item
	)

Submit work item to a P4 queue.

Submits the specified work item to the queue. The caller must have already initialized the relevant fields of the struct. The queue will execute the handler when CPU time is available and when no higher-priority work items are available. The handler may be invoked on any CPU.

The caller must not mutate the struct while it is stored in the queue. The memory should remain unchanged until k_p4wq_cancel() is called or until the entry to the handler function.

Note

This call is a scheduling point, so if the submitted item (or any other ready thread) has a higher priority than the current thread and the current thread has a preemptible priority then the caller will yield.

Parameters

queue	P4 Queue to which to submit
item	P4 work item to be submitted

k_p4wq_wait()

int k_p4wq_wait	(	struct k_p4wq_work *	work,
		k_timeout_t	timeout
	)

Regain ownership of the work item, wait for completion if it's synchronous.