esp_ipc: Move to new component

This commit moves esp_ipc into a separate component.

components/esp_ipc/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "ipc.c"
+                    INCLUDE_DIRS "include")

components/esp_ipc/component.mk

@@ -0,0 +1,3 @@
+#
+# Component Makefile
+#

components/esp_ipc/include/esp_ipc.h

@@ -0,0 +1,93 @@
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#ifndef __ESP_IPC_H__
+#define __ESP_IPC_H__
+
+#include <esp_err.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+/** @cond */
+typedef void (*esp_ipc_func_t)(void* arg);
+/** @endcond */
+/*
+ * Inter-processor call APIs
+ *
+ * FreeRTOS provides several APIs which can be used to communicate between
+ * different tasks, including tasks running on different CPUs.
+ * This module provides additional APIs to run some code on the other CPU.
+ *
+ * These APIs can only be used when FreeRTOS scheduler is running.
+ */
+
+/**
+ * @brief Execute a function on the given CPU
+ *
+ * Run a given function on a particular CPU. The given function must accept a
+ * void* argument and return void. The given function is run in the context of
+ * the IPC task of the CPU specified by the cpu_id parameter. The calling task
+ * will be blocked until the IPC task begins executing the given function. If
+ * another IPC call is ongoing, the calling task will block until the other IPC
+ * call completes. The stack size allocated for the IPC task can be configured
+ * in the "Inter-Processor Call (IPC) task stack size" setting in menuconfig.
+ * Increase this setting if the given function requires more stack than default.
+ *
+ * @note In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1.
+ *
+ * @param[in]   cpu_id  CPU where the given function should be executed (0 or 1)
+ * @param[in]   func    Pointer to a function of type void func(void* arg) to be executed
+ * @param[in]   arg     Arbitrary argument of type void* to be passed into the function
+ *
+ * @return
+ *      - ESP_ERR_INVALID_ARG if cpu_id is invalid
+ *      - ESP_ERR_INVALID_STATE if the FreeRTOS scheduler is not running
+ *      - ESP_OK otherwise
+ */
+esp_err_t esp_ipc_call(uint32_t cpu_id, esp_ipc_func_t func, void* arg);
+
+
+/**
+ * @brief Execute a function on the given CPU and blocks until it completes
+ *
+ * Run a given function on a particular CPU. The given function must accept a
+ * void* argument and return void. The given function is run in the context of
+ * the IPC task of the CPU specified by the cpu_id parameter. The calling task
+ * will be blocked until the IPC task completes execution of the given function.
+ * If another IPC call is ongoing, the calling task will block until the other
+ * IPC call completes. The stack size allocated for the IPC task can be
+ * configured in the "Inter-Processor Call (IPC) task stack size" setting in
+ * menuconfig. Increase this setting if the given function requires more stack
+ * than default.
+ *
+ * @note    In single-core mode, returns ESP_ERR_INVALID_ARG for cpu_id 1.
+ *
+ * @param[in]   cpu_id  CPU where the given function should be executed (0 or 1)
+ * @param[in]   func    Pointer to a function of type void func(void* arg) to be executed
+ * @param[in]   arg     Arbitrary argument of type void* to be passed into the function
+ *
+ * @return
+ *      - ESP_ERR_INVALID_ARG if cpu_id is invalid
+ *      - ESP_ERR_INVALID_STATE if the FreeRTOS scheduler is not running
+ *      - ESP_OK otherwise
+ */
+esp_err_t esp_ipc_call_blocking(uint32_t cpu_id, esp_ipc_func_t func, void* arg);
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __ESP_IPC_H__ */

components/esp_ipc/ipc.c

@@ -0,0 +1,146 @@
+// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <stddef.h>
+#include <stdlib.h>
+#include <string.h>
+#include <assert.h>
+#include "esp_err.h"
+#include "esp_ipc.h"
+#include "esp_attr.h"
+
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+
+static TaskHandle_t s_ipc_task_handle[portNUM_PROCESSORS];
+static SemaphoreHandle_t s_ipc_mutex[portNUM_PROCESSORS];    // This mutex is used as a global lock for esp_ipc_* APIs
+static SemaphoreHandle_t s_ipc_sem[portNUM_PROCESSORS];      // Two semaphores used to wake each of ipc tasks
+static SemaphoreHandle_t s_ipc_ack[portNUM_PROCESSORS];      // Semaphore used to acknowledge that task was woken up,
+                                                             //   or function has finished running
+static volatile esp_ipc_func_t s_func[portNUM_PROCESSORS];   // Function which should be called by high priority task
+static void * volatile s_func_arg[portNUM_PROCESSORS];       // Argument to pass into s_func
+typedef enum {
+    IPC_WAIT_FOR_START,
+    IPC_WAIT_FOR_END
+} esp_ipc_wait_t;
+
+static volatile esp_ipc_wait_t s_ipc_wait[portNUM_PROCESSORS];// This variable tells high priority task when it should give
+                                                             //   s_ipc_ack semaphore: before s_func is called, or
+                                                             //   after it returns
+
+static void IRAM_ATTR ipc_task(void* arg)
+{
+    const uint32_t cpuid = (uint32_t) arg;
+    assert(cpuid == xPortGetCoreID());
+    while (true) {
+        // Wait for IPC to be initiated.
+        // This will be indicated by giving the semaphore corresponding to
+        // this CPU.
+        if (xSemaphoreTake(s_ipc_sem[cpuid], portMAX_DELAY) != pdTRUE) {
+            // TODO: when can this happen?
+            abort();
+        }
+
+        esp_ipc_func_t func = s_func[cpuid];
+        void* arg = s_func_arg[cpuid];
+
+        if (s_ipc_wait[cpuid] == IPC_WAIT_FOR_START) {
+            xSemaphoreGive(s_ipc_ack[cpuid]);
+        }
+        (*func)(arg);
+        if (s_ipc_wait[cpuid] == IPC_WAIT_FOR_END) {
+            xSemaphoreGive(s_ipc_ack[cpuid]);
+        }
+    }
+    // TODO: currently this is unreachable code. Introduce esp_ipc_uninit
+    // function which will signal to both tasks that they can shut down.
+    // Not critical at this point, we don't have a use case for stopping
+    // IPC yet.
+    // Also need to delete the semaphore here.
+    vTaskDelete(NULL);
+}
+
+/*
+ * Initialize inter-processor call module. This function is called automatically
+ * on CPU start and should not be called from the application.
+ *
+ * This function start two tasks, one on each CPU. These tasks are started
+ * with high priority. These tasks are normally inactive, waiting until one of
+ * the esp_ipc_call_* functions to be used. One of these tasks will be
+ * woken up to execute the callback provided to esp_ipc_call_nonblocking or
+ * esp_ipc_call_blocking.
+ */
+static void esp_ipc_init(void) __attribute__((constructor));
+
+static void esp_ipc_init(void)
+{
+    char task_name[15];
+    for (int i = 0; i < portNUM_PROCESSORS; ++i) {
+        snprintf(task_name, sizeof(task_name), "ipc%d", i);
+        s_ipc_mutex[i] = xSemaphoreCreateMutex();
+        s_ipc_ack[i] = xSemaphoreCreateBinary();
+        s_ipc_sem[i] = xSemaphoreCreateBinary();
+        portBASE_TYPE res = xTaskCreatePinnedToCore(ipc_task, task_name, CONFIG_ESP_IPC_TASK_STACK_SIZE, (void*) i,
+                                                    configMAX_PRIORITIES - 1, &s_ipc_task_handle[i], i);
+        assert(res == pdTRUE);
+    }
+}
+
+static esp_err_t esp_ipc_call_and_wait(uint32_t cpu_id, esp_ipc_func_t func, void* arg, esp_ipc_wait_t wait_for)
+{
+    if (cpu_id >= portNUM_PROCESSORS) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    if (xTaskGetSchedulerState() != taskSCHEDULER_RUNNING) {
+        return ESP_ERR_INVALID_STATE;
+    }
+
+#ifdef CONFIG_ESP_IPC_USES_CALLERS_PRIORITY
+    TaskHandle_t task_handler = xTaskGetCurrentTaskHandle();
+    UBaseType_t priority_of_current_task = uxTaskPriorityGet(task_handler);
+    UBaseType_t priority_of_running_ipc_task = uxTaskPriorityGet(s_ipc_task_handle[cpu_id]);
+    if (priority_of_running_ipc_task < priority_of_current_task) {
+        vTaskPrioritySet(s_ipc_task_handle[cpu_id], priority_of_current_task);
+    }
+
+    xSemaphoreTake(s_ipc_mutex[cpu_id], portMAX_DELAY);
+    vTaskPrioritySet(s_ipc_task_handle[cpu_id], priority_of_current_task);
+#else
+    xSemaphoreTake(s_ipc_mutex[0], portMAX_DELAY);
+#endif
+
+    s_func[cpu_id] = func;
+    s_func_arg[cpu_id] = arg;
+    s_ipc_wait[cpu_id] = wait_for;
+    xSemaphoreGive(s_ipc_sem[cpu_id]);
+    xSemaphoreTake(s_ipc_ack[cpu_id], portMAX_DELAY);
+#ifdef CONFIG_ESP_IPC_USES_CALLERS_PRIORITY
+    xSemaphoreGive(s_ipc_mutex[cpu_id]);
+#else
+    xSemaphoreGive(s_ipc_mutex[0]);
+#endif
+    return ESP_OK;
+}
+
+esp_err_t esp_ipc_call(uint32_t cpu_id, esp_ipc_func_t func, void* arg)
+{
+    return esp_ipc_call_and_wait(cpu_id, func, arg, IPC_WAIT_FOR_START);
+}
+
+esp_err_t esp_ipc_call_blocking(uint32_t cpu_id, esp_ipc_func_t func, void* arg)
+{
+    return esp_ipc_call_and_wait(cpu_id, func, arg, IPC_WAIT_FOR_END);
+}
+

components/esp_ipc/test/CMakeLists.txt

@@ -0,0 +1,6 @@
+if(IDF_TARGET STREQUAL "esp32")
+    idf_component_register(SRC_DIRS "."
+                    PRIV_INCLUDE_DIRS "."
+                    PRIV_REQUIRES unity test_utils)
+endif()
+

components/esp_ipc/test/component.mk

@@ -0,0 +1 @@
+COMPONENT_ADD_LDFLAGS = -Wl,--whole-archive -l$(COMPONENT_NAME) -Wl,--no-whole-archive

components/esp_ipc/test/test_ipc.c

@@ -0,0 +1,127 @@
+#include <stdio.h>
+#include "sdkconfig.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"
+#include "freertos/semphr.h"
+#include "unity.h"
+#if !CONFIG_FREERTOS_UNICORE
+#include "esp_ipc.h"
+#endif
+#include "esp_log.h"
+
+#if !CONFIG_FREERTOS_UNICORE
+static void test_func_ipc_cb(void *arg)
+{
+    vTaskDelay(50);
+    int *val = (int *)arg;
+    *val = 0xa5a5;
+}
+
+TEST_CASE("Test blocking IPC function call", "[ipc]")
+{
+    int val = 0x5a5a;
+    esp_ipc_call_blocking(!xPortGetCoreID(), test_func_ipc_cb, &val);
+    TEST_ASSERT_EQUAL_HEX(val, 0xa5a5);
+}
+
+#ifdef CONFIG_ESP_IPC_USES_CALLERS_PRIORITY
+static volatile bool exit_flag;
+
+static void task1(void *sema)
+{
+    ESP_LOGI("task1", "start");
+    ets_delay_us(3000000);
+    vTaskDelay(1);
+    while (exit_flag == false) {
+
+    }
+    ESP_LOGI("task1", "finish");
+    vTaskDelete(NULL);
+}
+
+static UBaseType_t func_ipc_priority;
+
+static void test_func_ipc(void *sema)
+{
+    ets_delay_us(1000000 + xPortGetCoreID() * 100);
+    func_ipc_priority = uxTaskPriorityGet(NULL);
+    xSemaphoreGive(*(xSemaphoreHandle *)sema);
+    ets_printf("test_func_ipc: [%d, %d]\n", func_ipc_priority, xPortGetCoreID());
+}
+
+TEST_CASE("Test ipc_task works with the priority of the caller's task", "[ipc]")
+{
+    UBaseType_t priority = 18;
+    func_ipc_priority = 0;
+    vTaskPrioritySet(NULL, priority);
+
+    xSemaphoreHandle sema_ipc_done = xSemaphoreCreateBinary();
+
+    exit_flag = false;
+    xTaskCreatePinnedToCore(task1, "task1", 4096, NULL, priority + 2, NULL, 1);
+    vTaskDelay(100 / portTICK_PERIOD_MS);
+
+    ESP_LOGI("test", "Start IPC call in IPC_WAIT_FOR_START mode");
+    esp_ipc_call(1, test_func_ipc, &sema_ipc_done);
+    ESP_LOGI("test", "Waiting for IPC finish");
+    xSemaphoreTake(sema_ipc_done, 4000 / portTICK_PERIOD_MS);
+    ESP_LOGI("test", "Stop task1");
+    exit_flag = true;
+    xSemaphoreTake(sema_ipc_done, portMAX_DELAY);
+    vSemaphoreDelete(sema_ipc_done);
+    ESP_LOGI("test", "Check ipc_priority with priority caller's task. Should be the same");
+    vTaskPrioritySet(NULL, 5);
+    TEST_ASSERT_EQUAL(priority, func_ipc_priority);
+}
+
+static void test_func2_ipc(void *arg)
+{
+    int callers_priority = *(int *)arg;
+    ets_delay_us(1000000 + xPortGetCoreID() * 100);
+    UBaseType_t priority = uxTaskPriorityGet(NULL);
+    ets_printf("test_func2_ipc: [callers_priority = %d, priority = %d, cpu = %d]\n", callers_priority, priority, xPortGetCoreID());
+}
+
+static void task(void *sema)
+{
+    int priority = uxTaskPriorityGet(NULL);
+    ESP_LOGI("task", "start [priority = %d, cpu = %d]", priority, xPortGetCoreID());
+    xSemaphoreTake(*(xSemaphoreHandle *)sema, portMAX_DELAY);
+    esp_ipc_call_blocking(!xPortGetCoreID(), test_func2_ipc, &priority);
+    xSemaphoreGive(*(xSemaphoreHandle *)sema);
+    ESP_LOGI("task", "finish [priority = %d, cpu = %d]", priority, xPortGetCoreID());
+    vTaskDelete(NULL);
+}
+
+TEST_CASE("Test multiple ipc_calls", "[ipc]")
+{
+    const int max_tasks = 5;
+    UBaseType_t priority = uxTaskPriorityGet(NULL);
+    ESP_LOGI("test", "priority = %d, cpu = %d", priority, xPortGetCoreID());
+    xSemaphoreHandle sema_ipc_done[max_tasks * portNUM_PROCESSORS];
+
+    for (int task_num = 0; task_num < max_tasks; ++task_num) {
+        ++priority;
+        ESP_LOGI("test", "task prio = %d", priority);
+        for (int cpu_num = 0; cpu_num < portNUM_PROCESSORS; ++cpu_num) {
+            sema_ipc_done[task_num * 2 + cpu_num] = xSemaphoreCreateBinary();
+            xTaskCreatePinnedToCore(task, "task", 4096, &sema_ipc_done[task_num * 2 + cpu_num], priority, NULL, cpu_num);
+        }
+    }
+
+    for (int task_num = 0; task_num < max_tasks; ++task_num) {
+        for (int cpu_num = 0; cpu_num < portNUM_PROCESSORS; ++cpu_num) {
+            xSemaphoreGive(sema_ipc_done[task_num * 2 + cpu_num]);
+        }
+    }
+
+    for (int task_num = 0; task_num < max_tasks; ++task_num) {
+        for (int cpu_num = 0; cpu_num < portNUM_PROCESSORS; ++cpu_num) {
+            xSemaphoreTake(sema_ipc_done[task_num * 2 + cpu_num], portMAX_DELAY);
+            vSemaphoreDelete(sema_ipc_done[task_num * 2 + cpu_num]);
+        }
+    }
+}
+#endif /* CONFIG_ESP_IPC_USE_CALLERS_PRIORITY */
+
+#endif /* !CONFIG_FREERTOS_UNICORE */