sample: msgq: adding a sample code for message queue base usage

this commit adds a sample code to illustrate the base usage
of message queues. a producer and a consumer thread work
together, exchanging messages in a FIFO (for normal payloads)
and LIFO (for higher priority payloads) schemes.

Signed-off-by: Alexander Paschoaletto <[email protected]>

Author: alexpaschoaletto

samples/kernel/msg_queue/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(msg_queue)
+
+target_sources(app PRIVATE src/main.c)

samples/kernel/msg_queue/README.rst

@@ -0,0 +1,52 @@
+.. zephyr:code-sample:: msg_queue
+   :name: Message Queue
+
+   Implements a basic message queue producer/consumer thread pair.
+
+Overview
+********
+
+A sample demonstrating the basic usage of Zephyr message queues.
+A producer thread sends both normal and urgent messages to be retrieved
+by a consumer thread.
+
+Building and Running
+********************
+
+This application can be built and executed on QEMU as follows:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/kernel/msg_queue
+   :host-os: unix
+   :board: qemu_x86
+   :goals: run
+   :compact:
+
+To build for another board target, replace "qemu_x86" above with it.
+
+Sample Output
+=============
+
+Every normal message is put at the end of the queue, and they are delivered
+in FIFO order. Every "urgent" message is put at the beginning of the queue,
+and it is delivered first as long as no other "urgent" message comes in after
+it.
+
+In this sample, one producer thread sends 1 urgent message for each 2 normal
+ones. Note that message C is the first retrieved because it was the last one
+sent as "urgent".
+
+.. code-block:: console
+
+   [producer] sending: 0
+   [producer] sending: 1
+   [producer] sending: A (urgent)
+   [producer] sending: 2
+   [producer] sending: 3
+   [producer] sending: B (urgent)
+   [producer] sending: 4
+   [producer] sending: 5
+   [producer] sending: C (urgent)
+   [consumer] got sequence: CBA012345
+
+Exit QEMU by pressing :kbd:`CTRL+A` :kbd:`x`.

samples/kernel/msg_queue/prj.conf

@@ -0,0 +1 @@
+# nothing here

samples/kernel/msg_queue/sample.yaml

@@ -0,0 +1,15 @@
+sample:
+  description: Message queue demo sample
+  name: message queue
+common:
+  tags:
+    - message_queue
+tests:
+  sample.kernel.msgqueue:
+    integration_platforms:
+      - native_sim
+    harness: console
+    harness_config:
+      type: one_line
+      regex:
+        - ".*CBA012345"

samples/kernel/msg_queue/src/main.c

@@ -0,0 +1,68 @@
+/*
+ * Copyright (c) 2025 Instituto Superior de Engenharia do Porto (ISEP).
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/kernel.h>
+
+#define BUF_SIZE 10
+#define INACTIVE -1
+#define PRIORITY 5
+
+K_MSGQ_DEFINE(my_msgq, sizeof(char), BUF_SIZE, 1);
+
+void producer_function(void *rec, void *p2, void *p3)
+{
+	k_tid_t receiving_thread = (k_tid_t) rec;
+
+	char normal_data = '0';
+	char urgent_data = 'A';
+	int total_sent = 0;
+
+	/*
+	 * sends messages every 100 msec, in repeating
+	 * sequence: normal, normal, urgent, ...
+	 */
+	while (total_sent < (BUF_SIZE - 1)) {
+		for (int i = 0; i < 2; i++) {
+			printk("[producer] sending: %c\n", normal_data);
+			k_msgq_put(&my_msgq, &normal_data, K_NO_WAIT);
+			k_sleep(K_MSEC(100));
+			normal_data++;
+		}
+		printk("[producer] sending: %c (urgent)\n", urgent_data);
+		k_msgq_put_front(&my_msgq, &urgent_data, K_NO_WAIT);
+		k_sleep(K_MSEC(100));
+		urgent_data++;
+
+		total_sent += 3;
+	}
+
+	/*
+	 * finished sending messages, now start the receiving thread.
+	 * keep in mind both threads can be running at the same time,
+	 * but in this example we wish to see the queue accumulate some
+	 * messages before the receiver thread starts reading them out.
+	 */
+	k_thread_start(receiving_thread);
+}
+
+void consumer_function(void *p1, void *p2, void *p3)
+{
+	char received[BUF_SIZE];
+
+	for (int i = 0; i < (BUF_SIZE - 1); i++) {
+		k_msgq_get(&my_msgq, &received[i], K_NO_WAIT);
+	}
+
+	received[BUF_SIZE - 1] = '\0';
+	/* we expect to see CBA012345... */
+	printk("[consumer] got sequence: %s\n", received);
+}
+
+K_THREAD_DEFINE(consumer_thread, 2048, consumer_function,
+	NULL, NULL, NULL, PRIORITY, 0, INACTIVE);
+
+K_THREAD_DEFINE(producer_thread, 2048, producer_function,
+	((void *) consumer_thread), NULL, NULL, PRIORITY, 0, 0);