From 79bbe8f4b09876cbb23f11cc4ef1f8fd4c69e4ca Mon Sep 17 00:00:00 2001 From: Ben Marsh Date: Wed, 31 Jan 2024 11:35:09 +0000 Subject: [PATCH] doc: kernel: Add message queue & pipe to poll docs The polling API can be used to wait on data in a FIFO, message queue, or pipe, but the docs were not clear that message queues and pipes are supported. Add to the docs to make it clear message queues and pipes can be used with the polling API. Signed-off-by: Ben Marsh --- doc/kernel/services/polling.rst | 37 ++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/doc/kernel/services/polling.rst b/doc/kernel/services/polling.rst index 84f7dbf4b6f..71937648a93 100644 --- a/doc/kernel/services/polling.rst +++ b/doc/kernel/services/polling.rst @@ -24,6 +24,8 @@ There is a limited set of such conditions: - a semaphore becomes available - a kernel FIFO contains data ready to be retrieved +- a kernel message queue contains data ready to be retrieved +- a kernel pipe contains data ready to be retrieved - a poll signal is raised A thread that wants to wait on multiple conditions must define an array of @@ -87,20 +89,26 @@ ignored, most likely temporarily, its type can be set to K_POLL_TYPE_IGNORE. .. code-block:: c - struct k_poll_event events[2] = { + struct k_poll_event events[4] = { K_POLL_EVENT_STATIC_INITIALIZER(K_POLL_TYPE_SEM_AVAILABLE, K_POLL_MODE_NOTIFY_ONLY, &my_sem, 0), K_POLL_EVENT_STATIC_INITIALIZER(K_POLL_TYPE_FIFO_DATA_AVAILABLE, K_POLL_MODE_NOTIFY_ONLY, &my_fifo, 0), + K_POLL_EVENT_STATIC_INITIALIZER(K_POLL_TYPE_MSGQ_DATA_AVAILABLE, + K_POLL_MODE_NOTIFY_ONLY, + &my_msgq, 0), + K_POLL_EVENT_STATIC_INITIALIZER(K_POLL_TYPE_PIPE_DATA_AVAILABLE, + K_POLL_MODE_NOTIFY_ONLY, + &my_pipe, 0), }; or at runtime .. code-block:: c - struct k_poll_event events[2]; + struct k_poll_event events[4]; void some_init(void) { k_poll_event_init(&events[0], @@ -113,6 +121,16 @@ or at runtime K_POLL_MODE_NOTIFY_ONLY, &my_fifo); + k_poll_event_init(&events[2], + K_POLL_TYPE_MSGQ_DATA_AVAILABLE, + K_POLL_MODE_NOTIFY_ONLY, + &my_msgq); + + k_poll_event_init(&events[3], + K_POLL_TYPE_PIPE_DATA_AVAILABLE, + K_POLL_MODE_NOTIFY_ONLY, + &my_pipe); + // tags are left uninitialized if unused } @@ -145,6 +163,12 @@ In case of success, :c:func:`k_poll` returns 0. If it times out, it returns } else if (events[1].state == K_POLL_STATE_FIFO_DATA_AVAILABLE) { data = k_fifo_get(events[1].fifo, 0); // handle data + } else if (events[2].state == K_POLL_STATE_MSGQ_DATA_AVAILABLE) { + ret = k_msgq_get(events[2].msgq, buf, K_NO_WAIT); + // handle data + } else if (events[3].state == K_POLL_STATE_PIPE_DATA_AVAILABLE) { + ret = k_pipe_get(events[3].pipe, buf, bytes_to_read, &bytes_read, min_xfer, K_NO_WAIT); + // handle data } } else { // handle timeout @@ -165,9 +189,16 @@ to :c:macro:`K_POLL_STATE_NOT_READY` by the user. } else if (events[1].state == K_POLL_STATE_FIFO_DATA_AVAILABLE) { data = k_fifo_get(events[1].fifo, 0); // handle data - } + } else if (events[2].state == K_POLL_STATE_MSGQ_DATA_AVAILABLE) { + ret = k_msgq_get(events[2].msgq, buf, K_NO_WAIT); + // handle data + } else if (events[3].state == K_POLL_STATE_PIPE_DATA_AVAILABLE) { + ret = k_pipe_get(events[3].pipe, buf, bytes_to_read, &bytes_read, min_xfer, K_NO_WAIT); + // handle data events[0].state = K_POLL_STATE_NOT_READY; events[1].state = K_POLL_STATE_NOT_READY; + events[2].state = K_POLL_STATE_NOT_READY; + events[3].state = K_POLL_STATE_NOT_READY; } }