micropython · dpgeorge · Mar 15, 2024 · Nov 13, 2023 · Feb 20, 2024 · Feb 20, 2024
diff --git a/.github/workflows/ports_stm32.yml b/.github/workflows/ports_stm32.yml
@@ -25,6 +25,7 @@ jobs:
         ci_func:  # names are functions in ci.sh
           - stm32_pyb_build
           - stm32_nucleo_build
+          - stm32_misc_build
     runs-on: ubuntu-20.04
     steps:
     - uses: actions/checkout@v4

diff --git a/.gitmodules b/.gitmodules
@@ -59,3 +59,9 @@
 [submodule "lib/protobuf-c"]
 	path = lib/protobuf-c
 	url = https://github.com/protobuf-c/protobuf-c.git
+[submodule "lib/open-amp"]
+	path = lib/open-amp
+	url = https://github.com/OpenAMP/open-amp.git
+[submodule "lib/libmetal"]
+	path = lib/libmetal
+	url = https://github.com/OpenAMP/libmetal.git
diff --git a/LICENSE b/LICENSE
@@ -48,12 +48,14 @@ used during the build process and is not part of the compiled source code.
         /cmsis (BSD-3-clause)
         /crypto-algorithms (NONE)
         /libhydrogen (ISC)
+        /libmetal (BSD-3-clause)
         /littlefs (BSD-3-clause)
         /lwip (BSD-3-clause)
         /mynewt-nimble (Apache-2.0)
         /nrfx (BSD-3-clause)
         /nxp_driver (BSD-3-Clause)
         /oofatfs (BSD-1-clause)
+        /open-amp (BSD-3-clause)
         /pico-sdk (BSD-3-clause)
         /re15 (BSD-3-clause)
         /stm32lib (BSD-3-clause)

diff --git a/docs/library/index.rst b/docs/library/index.rst
@@ -103,6 +103,7 @@ the following libraries.
    micropython.rst
    neopixel.rst
    network.rst
+   openamp.rst
    uctypes.rst
    vfs.rst
 

diff --git a/docs/library/openamp.rst b/docs/library/openamp.rst
@@ -0,0 +1,115 @@
+:mod:`openamp` -- provides standard Asymmetric Multiprocessing (AMP) support
+============================================================================
+
+.. module:: openamp
+   :synopsis: provides standard Asymmetric Multiprocessing (AMP) support
+
+The ``openamp`` module provides a standard inter-processor communications infrastructure
+for MicroPython. The module handles all of the details of OpenAMP, such as setting up
+the shared resource table, initializing vrings, etc. It provides an API for using the
+RPMsg bus infrastructure with the `Endpoint` class, and provides processor Life Cycle
+Management (LCM) support, such as loading firmware and starting and stopping a remote
+core, via the `RemoteProc` class.
+
+Example usage::
+
+    import openamp
+
+    def ept_recv_callback(src, data):
+        print("Received message on endpoint", data)
+
+    # Create a new RPMsg endpoint to communicate with the remote core.
+    ept = openamp.Endpoint("vuart-channel", callback=ept_recv_callback)
+
+    # Create a RemoteProc object, load its firmware and start it.
+    rproc = openamp.RemoteProc("virtual_uart.elf") # Or entry point address (ex 0x081E0000)
+    rproc.start()
+
+    while True:
+        if ept.is_ready():
+            ept.send("data")
+
+Functions
+---------
+
+.. function:: new_service_callback(ns_callback)
+
+    Set the new service callback.
+
+    The *ns_callback* argument is a function that will be called when the remote processor
+    announces new services. At that point the host processor can choose to create the
+    announced endpoint, if this particular service is supported, or ignore it if it's
+    not. If this function is not set, the host processor should first register the
+    endpoint locally, and it will be automatically bound when the remote announces
+    the service.
+
+Endpoint class
+--------------
+
+.. class:: Endpoint(name, callback, src=ENDPOINT_ADDR_ANY, dest=ENDPOINT_ADDR_ANY)
+
+   Construct a new RPMsg Endpoint. An endpoint is a bidirectional communication
+   channel between two cores.
+
+   Arguments are:
+
+        - *name* is the name of the endpoint.
+        - *callback* is a function that is called when the endpoint receives data with the
+          source address of the remote point, and the data as bytes passed by reference.
+        - *src* is the endpoint source address. If none is provided one will be assigned
+          to the endpoint by the library.
+        - *dest* is the endpoint destination address. If the endpoint is created from the
+          new_service_callback, this must be provided and it must match the remote endpoint's
+          source address. If the endpoint is registered locally, before the announcement, the
+          destination address will be assigned by the library when the endpoint is bound.
+
+.. method:: Endpoint.deinit()
+
+   Destroy the endpoint and release all of its resources.
+
+.. method:: Endpoint.is_ready()
+
+   Returns True if the endpoint is ready to send (i.e., has both a source and destination addresses)
+
+.. method:: Endpoint.send(src=-1, dest=-1, timeout=-1)
+
+   Send a message to the remote processor over this endpoint.
+
+   Arguments are:
+
+        - *src* is the source endpoint address of the message. If none is provided, the
+          source address the endpoint is bound to is used.
+        - *dest* is the destination endpoint address of the message. If none is provided,
+          the destination address the endpoint is bound to is used.
+        - *timeout* specifies the time in milliseconds to wait for a free buffer. By default
+          the function is blocking.
+
+RemoteProc class
+----------------
+
+.. class:: RemoteProc(entry)
+
+   The RemoteProc object provides processor Life Cycle Management (LCM) support, such as
+   loading firmware, starting and stopping a remote core.
+
+   The *entry* argument can be a path to firmware image, in which case the firmware is
+   loaded from file to its target memory, or an entry point address, in which case the
+   firmware must be loaded already at the given address.
+
+.. method:: RemoteProc.start()
+
+   Starts the remote processor.
+
+.. method:: RemoteProc.stop()
+
+   Stops the remote processor. The exact behavior is platform-dependent. On the STM32H7 for
+   example it's not possible to stop and then restart the Cortex-M4 core, so a complete
+   system reset is performed on a call to this function.
+
+.. method:: RemoteProc.shutdown()
+
+   Shutdown stops the remote processor and releases all of its resources. The exact behavior
+   is platform-dependent, however typically it disables power and clocks to the remote core.
+   This function is also used as the finaliser (i.e., called when ``RemoteProc`` object is
+   collected). Note that on the STM32H7, it's not possible to stop and then restart the
+   Cortex-M4 core, so a complete system reset is performed on a call to this function.
diff --git a/extmod/extmod.mk b/extmod/extmod.mk
@@ -31,6 +31,9 @@ SRC_EXTMOD_C += \
 	extmod/modmachine.c \
 	extmod/modnetwork.c \
 	extmod/modonewire.c \
+	extmod/modopenamp.c \
+	extmod/modopenamp_remoteproc.c \
+	extmod/modopenamp_remoteproc_store.c \
 	extmod/modos.c \
 	extmod/modplatform.c\
 	extmod/modrandom.c \
@@ -515,3 +518,58 @@ include $(TOP)/extmod/btstack/btstack.mk
 endif
 
 endif
+
+################################################################################
+# openamp
+
+ifeq ($(MICROPY_PY_OPENAMP),1)
+OPENAMP_DIR = lib/open-amp
+LIBMETAL_DIR = lib/libmetal
+GIT_SUBMODULES += $(LIBMETAL_DIR) $(OPENAMP_DIR)
+include $(TOP)/extmod/libmetal/libmetal.mk
+
+INC += -I$(TOP)/$(OPENAMP_DIR)
+CFLAGS += -DMICROPY_PY_OPENAMP=1
+
+ifeq ($(MICROPY_PY_OPENAMP_REMOTEPROC),1)
+CFLAGS += -DMICROPY_PY_OPENAMP_REMOTEPROC=1
+endif
+
+CFLAGS_THIRDPARTY += \
+    -I$(BUILD)/openamp \
+    -I$(TOP)/$(OPENAMP_DIR) \
+    -I$(TOP)/$(OPENAMP_DIR)/lib/include/ \
+    -DMETAL_INTERNAL \
+    -DVIRTIO_DRIVER_ONLY \
+    -DNO_ATOMIC_64_SUPPORT \
+    -DRPMSG_BUFFER_SIZE=512 \
+
+# OpenAMP's source files.
+SRC_OPENAMP_C += $(addprefix $(OPENAMP_DIR)/lib/,\
+	rpmsg/rpmsg.c \
+	rpmsg/rpmsg_virtio.c \
+	virtio/virtio.c \
+	virtio/virtqueue.c \
+	virtio_mmio/virtio_mmio_drv.c \
+	)
+
+# OpenAMP's remoteproc source files.
+ifeq ($(MICROPY_PY_OPENAMP_REMOTEPROC),1)
+SRC_OPENAMP_C += $(addprefix $(OPENAMP_DIR)/lib/remoteproc/,\
+	elf_loader.c \
+	remoteproc.c \
+	remoteproc_virtio.c \
+	rsc_table_parser.c \
+	)
+endif # MICROPY_PY_OPENAMP_REMOTEPROC
+
+# Disable compiler warnings in OpenAMP (variables used only for assert).
+$(BUILD)/$(OPENAMP_DIR)/lib/rpmsg/rpmsg_virtio.o: CFLAGS += -Wno-unused-but-set-variable
+$(BUILD)/$(OPENAMP_DIR)/lib/virtio_mmio/virtio_mmio_drv.o: CFLAGS += -Wno-unused-but-set-variable
+
+# We need to have generated libmetal before compiling OpenAMP.
+$(addprefix $(BUILD)/, $(SRC_OPENAMP_C:.c=.o)): $(BUILD)/openamp/metal/config.h
+
+SRC_THIRDPARTY_C += $(SRC_LIBMETAL_C) $(SRC_OPENAMP_C)
+
+endif # MICROPY_PY_OPENAMP
diff --git a/extmod/libmetal/libmetal.mk b/extmod/libmetal/libmetal.mk
@@ -0,0 +1,51 @@
+# Makefile directives for libmetal
+
+# libmetal is intended to run through a pre-processor (as part of its CMake-based build system).
+# This replicates the basic functionality of the pre-processor, including adding a "micropython"
+# platform that is almost identical to the built-in "generic" platform with a few small changes
+# provided by the files in extmod/libmetal.
+$(BUILD)/openamp: $(BUILD)
+	$(MKDIR) -p $@
+
+$(BUILD)/openamp/metal: $(BUILD)/openamp
+	$(MKDIR) -p $@
+
+$(BUILD)/openamp/metal/config.h: $(BUILD)/openamp/metal $(TOP)/$(LIBMETAL_DIR)/lib/config.h
+	@$(ECHO) "GEN $@"
+	@for file in $(TOP)/$(LIBMETAL_DIR)/lib/*.c $(TOP)/$(LIBMETAL_DIR)/lib/*.h; do $(SED) -e "s/@PROJECT_SYSTEM@/micropython/g" -e "s/@PROJECT_PROCESSOR@/arm/g" $$file > $(BUILD)/openamp/metal/$$(basename $$file); done
+	$(MKDIR) -p $(BUILD)/openamp/metal/processor/arm
+	@$(CP) $(TOP)/$(LIBMETAL_DIR)/lib/processor/arm/*.h $(BUILD)/openamp/metal/processor/arm
+	$(MKDIR) -p $(BUILD)/openamp/metal/compiler/gcc
+	@$(CP) $(TOP)/$(LIBMETAL_DIR)/lib/compiler/gcc/*.h $(BUILD)/openamp/metal/compiler/gcc
+	$(MKDIR) -p $(BUILD)/openamp/metal/system/micropython
+	@$(CP) $(TOP)/$(LIBMETAL_DIR)/lib/system/generic/*.c $(TOP)/$(LIBMETAL_DIR)/lib/system/generic/*.h $(BUILD)/openamp/metal/system/micropython
+	@$(CP) $(TOP)/extmod/libmetal/metal/system/micropython/* $(BUILD)/openamp/metal/system/micropython
+	@$(CP) $(TOP)/extmod/libmetal/metal/config.h $(BUILD)/openamp/metal/config.h
+
+# libmetal's source files.
+SRC_LIBMETAL_C := $(addprefix $(BUILD)/openamp/metal/,\
+	device.c \
+	dma.c \
+	init.c \
+	io.c \
+	irq.c \
+	log.c \
+	shmem.c \
+	softirq.c \
+	version.c \
+	device.c \
+	system/micropython/condition.c \
+	system/micropython/device.c \
+	system/micropython/io.c \
+	system/micropython/irq.c \
+	system/micropython/shmem.c \
+	system/micropython/time.c \
+	)
+
+# These files are generated by the rule above (along with config.h), so we need to make the .c
+# files depend on that step -- can't use the .o files as the target because the .c files don't
+# exist yet.
+$(SRC_LIBMETAL_C): $(BUILD)/openamp/metal/config.h
+
+# Qstr processing will include the generated libmetal headers, so add them as a qstr requirement.
+QSTR_GLOBAL_REQUIREMENTS += $(BUILD)/openamp/metal/config.h
diff --git a/extmod/libmetal/metal/config.h b/extmod/libmetal/metal/config.h
@@ -0,0 +1,81 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2024 Arduino SA
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * MicroPython libmetal config.
+ */
+#ifndef MICROPY_INCLUDED_METAL_MICROPYTHON_H
+#define MICROPY_INCLUDED_METAL_MICROPYTHON_H
+
+#include <stdlib.h>
+
+// Port-specific config.
+#include "mpmetalport.h"
+
+// Library major version number.
+#define METAL_VER_MAJOR     1
+
+// Library minor version number.
+#define METAL_VER_MINOR     5
+
+// Library patch level.
+#define METAL_VER_PATCH     0
+
+// Library version string.
+#define METAL_VER           "1.5.0"
+
+#if METAL_HAVE_STDATOMIC_H
+#define HAVE_STDATOMIC_H
+#endif
+
+#if METAL_HAVE_FUTEX_H
+#define HAVE_FUTEX_H
+#endif
+
+#ifndef METAL_MAX_DEVICE_REGIONS
+#define METAL_MAX_DEVICE_REGIONS 1
+#endif
+
+// generic/log.h
+#if METAL_LOG_HANDLER_ENABLE
+#include "py/mphal.h"
+#undef metal_log
+#define metal_log(level, ...) mp_printf(&mp_plat_print, __VA_ARGS__)
+#endif
+
+static inline void *__metal_allocate_memory(unsigned int size) {
+    return m_tracked_calloc(1, size);
+}
+
+static inline void __metal_free_memory(void *ptr) {
+    m_tracked_free(ptr);
+}
+
+// The following functions must be provided by the port (in mpmetalport.h / mpmetalport.c).
+int __metal_sleep_usec(unsigned int usec);
+void sys_irq_enable(unsigned int vector);
+void sys_irq_disable(unsigned int vector);
+void sys_irq_restore_enable(unsigned int flags);
+unsigned int sys_irq_save_disable(void);
+#endif // MICROPY_INCLUDED_METAL_MICROPYTHON_H
diff --git a/extmod/libmetal/metal/system/micropython/alloc.h b/extmod/libmetal/metal/system/micropython/alloc.h
@@ -0,0 +1 @@
+#include <metal/config.h>
diff --git a/extmod/libmetal/metal/system/micropython/log.h b/extmod/libmetal/metal/system/micropython/log.h
@@ -0,0 +1 @@
+#include <metal/config.h>
diff --git a/extmod/libmetal/metal/system/micropython/sleep.h b/extmod/libmetal/metal/system/micropython/sleep.h
@@ -0,0 +1 @@
+#include <metal/config.h>
diff --git a/extmod/libmetal/metal/system/micropython/sys.h b/extmod/libmetal/metal/system/micropython/sys.h
@@ -0,0 +1,5 @@
+#include <metal/config.h>
+
+struct metal_state {
+    struct metal_common_state common;
+};