OpenPicoRTOS: initial release

Author: jnaulet

.gitignore

@@ -50,3 +50,6 @@ modules.order
 Module.symvers
 Mkfile.old
 dkms.conf
+
+# documentation
+docs/*

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to picoRTOS
+
+In order to contribute to picoRTOS, here are the steps to follow:
+
+## Step 1
+
+Make your port in the corresponding arch subdirectory. It must provide at least 3
+files :
+ - picoRTOS_types.h
+ - picoRTOS_port.c
+ - picoRTOS_portasm.S (or any asm extension required by your compiler)
+
+The reason for this assembly file is not to mix C and assembly language, as it makes
+the static analysis difficult if not impossible.
+
+Don't use inline assembly, especially with parameters.
+The ASM macro is tolerated if stubbed to allow error-free splint analysis.
+
+## Step 2
+
+Provide a demo for your board in the demo subdirectory. This will serve as a basic
+test for your port. A blink test is usually more than enough.
+If you provide support for atomic operations, try to use IPCs in your demo, too.
+
+Your code should build with no errors and no warnings.
+
+## Step 3
+
+Add a splint target for your new arch to the root Makefile.
+Your code must pass the static analysis with zero errors and zero warnings.
+
+If you use any external libraries or SDKs, the calls must be stubbed and the defines
+re-defined (wrapped in ifdefs) to allow splint to do its job properly.
+
+## Step 4
+
+Unless you spot a real bug or see a huge improvement to be made, don't touch to the
+common code (picoRTOS.c, picoRTOS-SMP.c and ipc/, notably).
+Any modification in these files will affect all ports, and you shouldn't make your
+port work at the expense of others.
+
+## Step 5
+
+run ./uncrustify at the root of the project to ensure your code complies with
+the coding standard.
+
+On some systems, depending on your version, uncrustify will affect some common header
+files like picoRTOS.h and ipc/picoRTOS_cond.h. Please don't commit them.
+
+## Step 6
+
+Commit on your fork (in a dedicated branch) and make a pull request.
+
+## Final word
+
+I understand these guidelines might seem extremely severe, potentially starving this
+project from talents, but they are here to garantee error-free software.
+
+This is extremely important in safety critical applications for which this RTOS
+has been designed in the first place.

Makefile

@@ -0,0 +1,13 @@
+# Helps uncrustifying and generating documentation
+
+uncrustify:
+	find . -name "*.[ch]" -exec uncrustify -c \
+	  etc/uncrustify.cfg \
+	  --replace --no-backup {} +
+
+naturaldocs:
+	naturaldocs -i . -xi docs \
+	  -p etc/naturaldocs \
+	  -o HTML docs
+
+.PHONY: uncrustify naturaldocs

README.md

@@ -1 +1,128 @@
-# OenPicoRTOS
+# OpenPicoRTOS [![Latest Release](https://img.shields.io/github/release-date/jnaulet/OpenPicoRTOS)](https://img.shields.io) [![Commits since](https://img.shields.io/github/commits-since/jnaulet/OpenPicoRTOS/latest/v1.5.x)](https://img.shields.io)
+
+Very small, lightning fast, yet portable preemptive RTOS with SMP suppport.
+
+## Presentation
+
+picoRTOS is a teeny tiny RTOS with as little overhead as humanely possible.
+
+## Documentation
+
+HTML documentation of the complete API is available in the documentation directory and
+at the following address: https://jnaulet.github.io/OpenPicoRTOS
+
+## Supported architectures
+
+### Single core
+
+ - ARM Cortex-M0+
+ - ARM Cortex-M3
+ - AVR6
+ - AVR5
+
+### Multi-core SMP
+ - RP2040 SMP
+
+### Simulation
+
+ - POSIX threads / Linux
+ - WIN32 threads / Windows
+
+## Featured devices
+
+ - Atmel ATMega2560
+ - Atmel ATMega328P
+ - Atmel ATSAM3X8E
+ - Raspberry Pico RP2040
+
+## Working principle
+
+On every new schedule (tick) task 0 is executed first.
+Any call to a sleeping function (picoRTOS_schedule, picoRTOS_sleep or
+picoRTOS_sleep_until) will allow the scheduler to move to the next task until
+it reaches idle or a new tick occurs and the cycle starts over.
+
+To increase speed and predictability, every task is identified by its exclusive
+level of priority, no round robin support is offered.
+
+No memory management is offered, everything is static, which makes the static analyzer's
+job much easier for critical applications.
+
+## Advanced features
+
+IPCs are available to architectures that support the correct associated atomic operations.
+A small infringement has been made to the hard real time philosophy of the project by supporting
+the CONFIG_ARCH_EMULATE_ATOMIC on platforms that don't support native atomic operations. This is
+not recommended, though.
+
+### The following IPCs are provided:
+
+ - futexes (require arch_test_and_set)
+ - re-entrant mutexes (require arch_compare_and_swap)
+ - conditions (require mutexes)
+ - queues (doesn't require atomic ops)
+
+## Interrupt management
+
+Version 1.5 introduces contextual interrupt management as an experimental feature.
+
+All architectures are supported (at least partially) at the moment.
+
+This feature should be used with care, as interrupts tend to destroy the real-time part in
+"RTOS".
+
+## How to use
+
+Copy the picoRTOS directory in your project.
+
+Create a picoRTOSConfig.h file in the include path of your project.
+
+Sample configs are available for every supported archs in arch/x/y/samples and in the
+demo directory.
+
+Then, add the relevant arch files to your build using the provided devices build files.
+
+Example for ATMega2560:
+
+    PICORTOS_DIR := ./picoRTOS
+    -include $(PICORTOS_DIR)/devices/atmel/atmega2560/Makefile.in
+
+IPCs are not in the build files by default, you need to add them manually to your build:
+
+    INCLUDE += -I$(PICORTOS_DIR)/ipc
+    SRC_C += $(PICORTOS_DIR)/ipc/picoRTOS_futex.c
+
+---
+
+Code-wise, using picoRTOS is quite straightforward :
+
+    #include "picoRTOS.h"
+    
+    void main(void)
+    {
+        picoRTOS_init();
+    
+        struct picoRTOS_task task0;
+        struct picoRTOS_task task1;
+        static picoRTOS_stack_t stack0[CONFIG_DEFAULT_STACK_COUNT];
+        static picoRTOS_stack_t stack1[CONFIG_DEFAULT_STACK_COUNT];
+        ...
+    
+        picoRTOS_task_init(&task0, task0_main, &task0_context, stack0, CONFIG_DEFAULT_TASK_COUNT);
+        picoRTOS_task_init(&task1, task1_main, &task1_context, stack1, CONFIG_DEFAULT_TASK_COUNT);
+        ...
+    
+        picoRTOS_add_task(&task0, TASK0_PRIO);
+        picoRTOS_add_task(&task1, TASK1_PRIO);
+        ...
+    
+        picoRTOS_start();
+    }
+
+Hint: tasks are converted to internal structures in picoRTOS_add_task and can be local
+but stacks need to be persistant (prefer static to globals to reduce scope).
+
+## Demo
+
+Some demo code is available under the demo directory for every supported architecture
+so you can see for yourself if this software suits your needs.

RELEASE_NOTES.md

@@ -0,0 +1,15 @@
+# Release notes
+
+## picoRTOS v1.5.4
+### What's new ?
+
+picoRTOS is back ! Version 1.5.3 has seen the project being retired for professionnal use, so this
+one is a brand new architecture that has been re-written from the ground up.
+
+Unfortunately older users of picoRTOS on PowerPC and C2000 cannot update because despite similar
+user interfaces, the port API has been fundamentally rewritten and is not compatible anymore.
+
+Anyway, some features left us, but new features have been added, like "dynamic" priority assignment,
+syscalls, queues and much more.
+
+picoRTOS is now safer, faster and more complete, enjoy !