samples: cmsis_rtos_v2: Demo with Dining Philosopher's algorithm
The sample application to demonstrate dining philosopher's problem
implementation using CMSIS RTOS V2 APIs with semaphores and mutexes
as resources (forks).
The application makes use of CMSIS_RTOS_V2 APIs on threads, semaphores
and mutexes.
Signed-off-by: Spoorthi K <spoorthi.k@intel.com>
diff --git a/samples/portability/cmsis_rtos_v2/philosophers/CMakeLists.txt b/samples/portability/cmsis_rtos_v2/philosophers/CMakeLists.txt
new file mode 100644
index 0000000..f2038ea
--- /dev/null
+++ b/samples/portability/cmsis_rtos_v2/philosophers/CMakeLists.txt
@@ -0,0 +1,6 @@
+cmake_minimum_required(VERSION 3.8.2)
+include($ENV{ZEPHYR_BASE}/cmake/app/boilerplate.cmake NO_POLICY_SCOPE)
+project(philosophers)
+
+target_include_directories(app PRIVATE $ENV{ZEPHYR_BASE}/include/cmsis_rtos_v2)
+target_sources(app PRIVATE src/main.c)
diff --git a/samples/portability/cmsis_rtos_v2/philosophers/README.rst b/samples/portability/cmsis_rtos_v2/philosophers/README.rst
new file mode 100644
index 0000000..416d848
--- /dev/null
+++ b/samples/portability/cmsis_rtos_v2/philosophers/README.rst
@@ -0,0 +1,56 @@
+.. _cmsis_rtos_v2-sample:
+
+Dining Philosophers (CMSI RTOS V2 APIs)
+#######################################
+
+Overview
+********
+This sample implements a solution to the `Dining Philosophers problem
+<https://en.wikipedia.org/wiki/Dining_philosophers_problem>`_ (a classic
+multi-thread synchronization problem) using CMSIS RTOS V2 APIs. This particular
+implementation demonstrates the usage of multiple preemptible and cooperative
+threads of differing priorities, as well as mutex/semaphore and thread sleeping
+which uses CMSIS RTOS V2 API implementation in Zephyr.
+
+The philosopher always tries to get the lowest fork first (f1 then f2). When
+done, he will give back the forks in the reverse order (f2 then f1). If he
+gets two forks, he is EATING. Otherwise, he is THINKING. Transitional states
+are shown as well, such as STARVING when the philosopher is hungry but the
+forks are not available, and HOLDING ONE FORK when a philosopher is waiting
+for the second fork to be available.
+
+Each Philosopher will randomly alternate between the EATING and THINKING state.
+
+
+Building and Running
+********************
+
+This project outputs to the console. It can be built and executed
+on QEMU as follows:
+
+.. zephyr-app-commands::
+ :zephyr-app: samples/philosophers
+ :host-os: unix
+ :board: qemu_x86
+ :goals: run
+ :compact:
+
+Sample Output
+=============
+
+.. code-block:: console
+
+ Philosopher 0 [P: 8] HOLDING ONE FORK
+ Philosopher 1 [P: 9] HOLDING ONE FORK
+ Philosopher 2 [P: 10] EATING [ 575 ms ]
+ Philosopher 3 [P: 11] THINKING [ 225 ms ]
+ Philosopher 4 [P: 12] THINKING [ 425 ms ]
+ Philosopher 5 [P: 13] THINKING [ 325 ms ]
+
+ Demo Description
+ ----------------
+ An implementation of a solution to the Dining Philosophers
+ problem (a classic multi-thread synchronization problem) using
+ CMSIS RTOS V2 APIs. This particular implementation demonstrates the
+ usage of multiple preemptible threads of differing
+ priorities, as well as semaphores and thread sleeping.
diff --git a/samples/portability/cmsis_rtos_v2/philosophers/prj.conf b/samples/portability/cmsis_rtos_v2/philosophers/prj.conf
new file mode 100644
index 0000000..89753bb
--- /dev/null
+++ b/samples/portability/cmsis_rtos_v2/philosophers/prj.conf
@@ -0,0 +1,13 @@
+CONFIG_STDOUT_CONSOLE=n
+CONFIG_SYS_CLOCK_TICKS_PER_SEC=100
+CONFIG_ASSERT=y
+CONFIG_ASSERT_LEVEL=2
+CONFIG_CMSIS_RTOS_V2=y
+CONFIG_NUM_PREEMPT_PRIORITIES=56
+CONFIG_HEAP_MEM_POOL_SIZE=256
+CONFIG_THREAD_NAME=y
+CONFIG_THREAD_STACK_INFO=y
+CONFIG_THREAD_MONITOR=y
+CONFIG_INIT_STACKS=y
+CONFIG_POLL=y
+CONFIG_SCHED_SCALABLE=y
diff --git a/samples/portability/cmsis_rtos_v2/philosophers/sample.yaml b/samples/portability/cmsis_rtos_v2/philosophers/sample.yaml
new file mode 100644
index 0000000..7a515f1
--- /dev/null
+++ b/samples/portability/cmsis_rtos_v2/philosophers/sample.yaml
@@ -0,0 +1,24 @@
+sample:
+ name: CMSIS_RTOS_V2 Dining Philosophers
+common:
+ extra_args: "-DDEBUG_PRINTF=1"
+ tags: cmsis_rtos_v2_philosopher
+ min_ram: 32
+ min_flash: 34
+ platform_exclude: qemu_xtensa
+ harness: console
+ harness_config:
+ type: multi_line
+ ordered: false
+ regex:
+ - ".*STARVING.*"
+ - ".*DROPPED ONE FORK.*"
+ - ".*THINKING.*"
+ - ".*EATING.*"
+tests:
+ sample.philosopher:
+ tags: cmsis_rtos_v2_philosopher
+ sample.philosopher.same_prio:
+ extra_args: "-DSAME_PRIO=1"
+ sample.philosopher.semaphores:
+ extra_args: "-DFORKS=SEMAPHORES"
diff --git a/samples/portability/cmsis_rtos_v2/philosophers/src/main.c b/samples/portability/cmsis_rtos_v2/philosophers/src/main.c
new file mode 100644
index 0000000..6c5e5c0
--- /dev/null
+++ b/samples/portability/cmsis_rtos_v2/philosophers/src/main.c
@@ -0,0 +1,271 @@
+/*
+ * Copyright (c) 2018 Intel Corporation
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ *
+ * Dining philosophers demo
+ *
+ * The demo can be configured to use SEMAPHORES or MUTEXES as object types for its
+ * synchronization. To configure a specific object, set the value of FORKS to one
+ * of these.
+ *
+ * By default, the demo uses MUTEXES.
+ *
+ * The demo can be configured to work with threads of the same priority or
+ * not. If using different priorities of preemptible threads; if using one
+ * priority, there will be six preemptible threads of priority normal.
+ *
+ * By default, the demo uses different priorities.
+ *
+ * The number of threads is set via NUM_PHIL. The demo has only been tested
+ * with six threads. In theory it should work with any number of threads, but
+ * not without making changes to the thread attributes and corresponding kernel
+ * object attributes array in the phil_obj_abstract.h
+ * header file.
+ */
+
+#include <zephyr.h>
+#include <kernel.h>
+#include <cmsis_os2.h>
+
+#if defined(CONFIG_STDOUT_CONSOLE)
+#include <stdio.h>
+#else
+#include <misc/printk.h>
+#endif
+
+#include <misc/__assert.h>
+
+#include "phil_obj_abstract.h"
+
+#define SEMAPHORES 1
+#define MUTEXES 2
+
+/**************************************/
+/* control the behaviour of the demo **/
+
+#ifndef DEBUG_PRINTF
+#define DEBUG_PRINTF 0
+#endif
+
+#ifndef FORKS
+#define FORKS MUTEXES
+#if 0
+#define FORKS SEMAPHORES
+#endif
+#endif
+
+#ifndef SAME_PRIO
+#define SAME_PRIO 0
+#endif
+
+#ifndef NUM_PHIL
+#define NUM_PHIL 6
+#endif
+
+/* end - control behaviour of the demo */
+/***************************************/
+osSemaphoreId_t forks[NUM_PHIL];
+
+#define fork(x) (forks[x])
+
+#define STACK_SIZE 512
+static K_THREAD_STACK_ARRAY_DEFINE(stacks, NUM_PHIL, STACK_SIZE);
+static osThreadAttr_t thread_attr[] = {
+ {
+ .name = "Thread0",
+ .stack_mem = &stacks[0][0],
+ .stack_size = STACK_SIZE,
+ .priority = osPriorityHigh
+ },
+ {
+ .name = "Thread1",
+ .stack_mem = &stacks[1][0],
+ .stack_size = STACK_SIZE,
+ .priority = osPriorityHigh
+ },
+ {
+ .name = "Thread2",
+ .stack_mem = &stacks[2][0],
+ .stack_size = STACK_SIZE,
+ .priority = osPriorityHigh
+ },
+ {
+ .name = "Thread3",
+ .stack_mem = &stacks[3][0],
+ .stack_size = STACK_SIZE,
+ .priority = osPriorityHigh
+ },
+ {
+ .name = "Thread4",
+ .stack_mem = &stacks[4][0],
+ .stack_size = STACK_SIZE,
+ .priority = osPriorityHigh
+ },
+ {
+ .name = "Thread5",
+ .stack_mem = &stacks[5][0],
+ .stack_size = STACK_SIZE,
+ .priority = osPriorityHigh
+ }
+};
+
+
+/*
+ * There are multiple threads doing printfs and they may conflict.
+ * Therefore use puts() instead of printf().
+ */
+#if defined(CONFIG_STDOUT_CONSOLE)
+#define PRINTF(...) { char output[256]; \
+ sprintf(output, __VA_ARGS__); puts(output); }
+#else
+#define PRINTF(...) printk(__VA_ARGS__)
+#endif
+
+#if DEBUG_PRINTF
+#define PR_DEBUG PRINTF
+#else
+#define PR_DEBUG(...)
+#endif
+
+#include "phil_obj_abstract.h"
+
+static void set_phil_state_pos(int id)
+{
+#if !DEBUG_PRINTF
+ PRINTF("\x1b[%d;%dH", id + 1, 1);
+#endif
+}
+
+#include <stdarg.h>
+static void print_phil_state(int id, const char *fmt, s32_t delay)
+{
+ int prio = osThreadGetPriority(osThreadGetId());
+
+ set_phil_state_pos(id);
+
+ PRINTF("Philosopher %d [%s:%s%d] ",
+ id, prio < 0 ? "C" : "P",
+ prio < 0 ? "" : " ",
+ prio);
+
+ if (delay) {
+ PRINTF(fmt, delay < 1000 ? " " : "", delay);
+ } else {
+ PRINTF(fmt, "");
+ }
+
+ PRINTF("\n");
+}
+
+static s32_t get_random_delay(int id, int period_in_ms)
+{
+ /*
+ * The random delay is unit-less, and is based on the philosopher's ID
+ * and the current uptime to create some pseudo-randomness. It produces
+ * a value between 0 and 31.
+ */
+ s32_t delay = (k_uptime_get_32()/100 * (id + 1)) & 0x1f;
+
+ /* add 1 to not generate a delay of 0 */
+ s32_t ms = (delay + 1) * period_in_ms;
+
+ return ms;
+}
+
+static inline int is_last_philosopher(int id)
+{
+ return id == (NUM_PHIL - 1);
+}
+
+void philosopher(void *id)
+{
+ fork_t fork1;
+ fork_t fork2;
+
+ int my_id = (int)id;
+
+ /* Djkstra's solution: always pick up the lowest numbered fork first */
+ if (is_last_philosopher(my_id)) {
+ fork1 = fork(0);
+ fork2 = fork(my_id);
+ } else {
+ fork1 = fork(my_id);
+ fork2 = fork(my_id + 1);
+ }
+
+ while (1) {
+ s32_t delay;
+
+ print_phil_state(my_id, " STARVING ", 0);
+ take(fork1);
+ print_phil_state(my_id, " HOLDING ONE FORK ", 0);
+ take(fork2);
+
+ delay = get_random_delay(my_id, 25);
+ print_phil_state(my_id, " EATING [ %s%d ms ] ", delay);
+ osDelay(delay);
+
+ drop(fork2);
+ print_phil_state(my_id, " DROPPED ONE FORK ", 0);
+ drop(fork1);
+
+ delay = get_random_delay(my_id, 25);
+ print_phil_state(my_id, " THINKING [ %s%d ms ] ", delay);
+ osDelay(delay);
+ }
+
+}
+
+static int new_prio(int phil)
+{
+#if SAME_PRIO
+ return osPriorityNormal;
+#else
+ return osPriorityLow + phil;
+#endif
+}
+
+static void init_objects(void)
+{
+ for (int i = 0; i < NUM_PHIL; i++) {
+ forks[i] = fork_init(i);
+ }
+}
+
+static void start_threads(void)
+{
+ for (int i = 0; i < NUM_PHIL; i++) {
+ int prio = new_prio(i);
+ thread_attr[i].priority = prio;
+ osThreadNew(philosopher, (void *)i, &thread_attr[i]);
+ }
+}
+
+#define DEMO_DESCRIPTION \
+ "\x1b[2J\x1b[15;1H" \
+ "Demo Description\n" \
+ "----------------\n" \
+ "An implementation of a solution to the Dining Philosophers\n" \
+ "problem (a classic multi-thread synchronization problem) using\n" \
+ "CMSIS RTOS V2 APIs. This particular implementation demonstrates the\n" \
+ "usage of multiple preemptible threads of differing\n" \
+ "priorities, as well as %s and thread sleeping.\n", fork_type_str
+
+static void display_demo_description(void)
+{
+#if !DEBUG_PRINTF
+ PRINTF(DEMO_DESCRIPTION);
+#endif
+}
+
+void main(void)
+{
+ display_demo_description();
+ init_objects();
+ start_threads();
+}
diff --git a/samples/portability/cmsis_rtos_v2/philosophers/src/phil_obj_abstract.h b/samples/portability/cmsis_rtos_v2/philosophers/src/phil_obj_abstract.h
new file mode 100644
index 0000000..e1cfcd7
--- /dev/null
+++ b/samples/portability/cmsis_rtos_v2/philosophers/src/phil_obj_abstract.h
@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2018 Intel Corporation
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ *
+ * Object type abstraction.
+ *
+ * Each object type that can be used as a "fork" provides:
+ *
+ * - a definition for fork_t (a reference to a fork) and fork_obj_t (an
+ * instance of the fork object)
+ * - a 'fork_init' function that initializes the object
+ * - a 'take' function that simulates taking the fork (eg. k_sem_take)
+ * - a 'drop' function that simulates dropping the fork (eg. k_mutex_unlock)
+ * - a 'fork_type_str' string defining the object type
+ *
+ * When using dynamic objects, the instances of the fork objects are placed
+ * automatically in the fork_objs[] array . References to these are in turn
+ * placed automatically in the forks[] array, the array of references to the
+ * forks.
+ *
+ * When using static objects, references to each object must be put by hand in
+ * the forks[] array.
+ */
+
+#include <cmsis_os2.h>
+
+#ifndef phil_obj_abstract__h
+#define phil_obj_abstract__h
+
+#if FORKS == SEMAPHORES
+ osSemaphoreAttr_t sema_attr[] = {
+ {"sema0", 0, NULL, 0U},
+ {"sema1", 0, NULL, 0U},
+ {"sema2", 0, NULL, 0U},
+ {"sema3", 0, NULL, 0U},
+ {"sema4", 0, NULL, 0U},
+ {"sema5", 0, NULL, 0U}
+ };
+
+ #define fork_init(x) osSemaphoreNew(1, 1, &sema_attr[x])
+ #define take(x) osSemaphoreAcquire(x, osWaitForever)
+ #define drop(x) osSemaphoreRelease(x)
+ #define fork_type_str "semaphores"
+ #define fork_t osSemaphoreId_t
+
+#elif FORKS == MUTEXES
+ osMutexAttr_t mutex_attr[x] = {
+ {"Mutex0", osMutexRecursive | osMutexPrioInherit, NULL, 0U},
+ {"Mutex1", osMutexRecursive | osMutexPrioInherit, NULL, 0U},
+ {"Mutex2", osMutexRecursive | osMutexPrioInherit, NULL, 0U},
+ {"Mutex3", osMutexRecursive | osMutexPrioInherit, NULL, 0U},
+ {"Mutex4", osMutexRecursive | osMutexPrioInherit, NULL, 0U},
+ {"Mutex5", osMutexRecursive | osMutexPrioInherit, NULL, 0U}
+ };
+
+ #define fork_init(x) osMutexNew(&mutex_attr[x])
+ #define take(x) osMutexAcquire(x, osWaitForever)
+ #define drop(x) osMutexRelease(x)
+ #define fork_type_str "mutexes"
+ #define fork_t osMutexAttr_t
+#else
+ #error unknown fork type
+#endif
+#endif /* phil_obj_abstract__h */
