Freertos xirq example (#585)

sw/example/demo_freeRTOS_xirq/FreeRTOSConfig.h

@@ -0,0 +1,157 @@
+/*
+    FreeRTOS V8.2.3 - Copyright (C) 2015 Real Time Engineers Ltd.
+    All rights reserved
+
+    VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION.
+
+    This file is part of the FreeRTOS distribution.
+
+    FreeRTOS is free software; you can redistribute it and/or modify it under
+    the terms of the GNU General Public License (version 2) as published by the
+    Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception.
+
+    ***************************************************************************
+    >>!   NOTE: The modification to the GPL is included to allow you to     !<<
+    >>!   distribute a combined work that includes FreeRTOS without being   !<<
+    >>!   obliged to provide the source code for proprietary components     !<<
+    >>!   outside of the FreeRTOS kernel.                                   !<<
+    ***************************************************************************
+
+    FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY
+    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+    FOR A PARTICULAR PURPOSE.  Full license text is available on the following
+    link: http://www.freertos.org/a00114.html
+
+    ***************************************************************************
+     *                                                                       *
+     *    FreeRTOS provides completely free yet professionally developed,    *
+     *    robust, strictly quality controlled, supported, and cross          *
+     *    platform software that is more than just the market leader, it     *
+     *    is the industry's de facto standard.                               *
+     *                                                                       *
+     *    Help yourself get started quickly while simultaneously helping     *
+     *    to support the FreeRTOS project by purchasing a FreeRTOS           *
+     *    tutorial book, reference manual, or both:                          *
+     *    http://www.FreeRTOS.org/Documentation                              *
+     *                                                                       *
+    ***************************************************************************
+
+    http://www.FreeRTOS.org/FAQHelp.html - Having a problem?  Start by reading
+    the FAQ page "My application does not run, what could be wrong?".  Have you
+    defined configASSERT()?
+
+    http://www.FreeRTOS.org/support - In return for receiving this top quality
+    embedded software for free we request you assist our global community by
+    participating in the support forum.
+
+    http://www.FreeRTOS.org/training - Investing in training allows your team to
+    be as productive as possible as early as possible.  Now you can receive
+    FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers
+    Ltd, and the world's leading authority on the world's leading RTOS.
+
+    http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products,
+    including FreeRTOS+Trace - an indispensable productivity tool, a DOS
+    compatible FAT file system, and our tiny thread aware UDP/IP stack.
+
+    http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate.
+    Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS.
+
+    http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High
+    Integrity Systems ltd. to sell under the OpenRTOS brand.  Low cost OpenRTOS
+    licenses offer ticketed support, indemnification and commercial middleware.
+
+    http://www.SafeRTOS.com - High Integrity Systems also provide a safety
+    engineered and independently SIL3 certified version for use in safety and
+    mission critical applications that require provable dependability.
+
+    1 tab == 4 spaces!
+*/
+
+
+#ifndef FREERTOS_CONFIG_H
+#define FREERTOS_CONFIG_H
+
+//#include "clock_config.h"
+
+/*-----------------------------------------------------------
+ * Application specific definitions.
+ *
+ * These definitions should be adjusted for your particular hardware and
+ * application requirements.
+ *
+ * THESE PARAMETERS ARE DESCRIBED WITHIN THE 'CONFIGURATION' SECTION OF THE
+ * FreeRTOS API DOCUMENTATION AVAILABLE ON THE FreeRTOS.org WEB SITE.
+ *
+ * See http://www.freertos.org/a00110.html.
+ *----------------------------------------------------------*/
+
+/* See https://www.freertos.org/Using-FreeRTOS-on-RISC-V.html */
+
+
+/******************************************************************************
+ * Modified for the NEORV32 processor by Stephan Nolting.
+ ******************************************************************************/
+#define configMTIME_BASE_ADDRESS 	( 0xFFFFFF90UL  )
+#define configMTIMECMP_BASE_ADDRESS ( 0xFFFFFF98UL  )
+
+#define configISR_STACK_SIZE_WORDS ( 128 )
+
+#define configUSE_PREEMPTION			1
+#define configUSE_IDLE_HOOK				1
+#define configUSE_TICK_HOOK				1
+#define configCPU_CLOCK_HZ				100000000
+#define configTICK_RATE_HZ				( ( TickType_t ) 100 )
+#define configMAX_PRIORITIES			( 5 )
+#define configMINIMAL_STACK_SIZE		( ( unsigned short ) 128 ) /* Can be as low as 60 but some of the demo tasks that use this constant require it to be higher. */
+#define configSUPPORT_DYNAMIC_ALLOCATION  1
+#define configTOTAL_HEAP_SIZE			( ( size_t ) ( 7 * 1024 ) )
+#define configMAX_TASK_NAME_LEN			( 16 )
+#define configUSE_TRACE_FACILITY		1
+#define configUSE_16_BIT_TICKS			0
+#define configIDLE_SHOULD_YIELD			0
+#define configUSE_MUTEXES				1
+#define configQUEUE_REGISTRY_SIZE		8
+#define configCHECK_FOR_STACK_OVERFLOW	2
+#define configUSE_RECURSIVE_MUTEXES		1
+#define configUSE_MALLOC_FAILED_HOOK	1
+#define configUSE_APPLICATION_TASK_TAG	0
+#define configUSE_COUNTING_SEMAPHORES	1
+#define configGENERATE_RUN_TIME_STATS	0
+#define configTASK_NOTIFICATION_ARRAY_ENTRIES 4
+#define configUSE_PORT_OPTIMISED_TASK_SELECTION 1
+
+/* Co-routine definitions. */
+#define configUSE_CO_ROUTINES 			0
+#define configMAX_CO_ROUTINE_PRIORITIES ( 2 )
+
+/* Software timer definitions. */
+#define configUSE_TIMERS				1
+#define configTIMER_TASK_PRIORITY		( configMAX_PRIORITIES - 1 )
+#define configTIMER_QUEUE_LENGTH		4
+#define configTIMER_TASK_STACK_DEPTH	( configMINIMAL_STACK_SIZE )
+
+/* Task priorities.  Allow these to be overridden. */
+#ifndef uartPRIMARY_PRIORITY
+	#define uartPRIMARY_PRIORITY		( configMAX_PRIORITIES - 3 )
+#endif
+
+/* Set the following definitions to 1 to include the API function, or zero
+to exclude the API function. */
+#define INCLUDE_vTaskPrioritySet			1
+#define INCLUDE_uxTaskPriorityGet			1
+#define INCLUDE_vTaskDelete					1
+#define INCLUDE_vTaskCleanUpResources		1
+#define INCLUDE_vTaskSuspend				1
+#define INCLUDE_vTaskDelayUntil				1
+#define INCLUDE_vTaskDelay					1
+#define INCLUDE_eTaskGetState				1
+#define INCLUDE_xTimerPendFunctionCall		1
+#define INCLUDE_xTaskAbortDelay				1
+#define INCLUDE_xTaskGetHandle				1
+#define INCLUDE_xSemaphoreGetMutexHolder	1
+
+/* Normal assert() semantics without relying on the provision of an assert.h
+header file. */
+#define configASSERT( x ) if( ( x ) == 0 ) { taskDISABLE_INTERRUPTS(); __asm volatile( "ebreak" ); for( ;; ); }
+
+#endif /* FREERTOS_CONFIG_H */

sw/example/demo_freeRTOS_xirq/README.md

@@ -0,0 +1,106 @@
+  # FreeRTOS Demo for the NEORV32 Processor
+
+This example shows how to run [FreeRTOS](https://www.freertos.org/) on the NEORV32 processor while using xirq's. See the comments in `main.c` and the according
+source files for more information.
+
+The chip-specific extensions folder (`chip_specific_extensions/neorv32`) should be in `$(FREERTOS_HOME)/Source/portable/GCC/RISC-V/chip_specific_extensions`,
+but is placed in this source directory for simplicity.
+
+**:information_source: Tested with FreeRTOS version V10.4.4+**
+
+
+## Requirements
+
+* Hardware
+  * DMEM/IMEM requirements depend on the actual application (for example: 16kB DMEM and 16kB IMEM for "blinky_demo")
+  * peripherals: MTIME (machine timer), UART0, GPIO
+
+* Software
+  * NEORV32 software framework
+  * RISC-V gcc
+  * FreeRTOS
+  * application-specific configuration of `FreeRTOSConfig.h` (especially `configCPU_CLOCK_HZ`)
+  * application-specific configuration of the NEORV32 linker script when using non-default IMEM or DMEM configurations (size!) 
+
+
+## Instructions
+
+Download FreeRTOS from the [official GitHub repository](https://github.com/FreeRTOS/FreeRTOS) or from the its official homepage.
+
+    $ git clone https://github.com/FreeRTOS/FreeRTOS.git
+
+Open the makefile from this example folder and configure the `FREERTOS_HOME` variable to point to your FreeRTOS home folder.
+
+    FREERTOS_HOME ?= /mnt/n/Projects/FreeRTOS
+
+Compile the NEORV32 executable. Do not forget the `RUN_FREERTOS_DEMO` switch.
+
+    $ make USER_FLAGS+=-DRUN_FREERTOS_DEMO clean_all exe
+
+Note: The *.c sources and the FreeRTOS-specific part of the makefile have (include) guards that test if `RUN_FREERTOS_DEMO` is defined.
+This has no practical usage for the user - it is just a work-around for the NEORV32 CI environment.
+
+Upload the executable (`neorv32_exe.bin`) to the processor via the bootloader and execute it.
+
+```
+CMD:> u
+Awaiting neorv32_exe.bin... OK
+CMD:> e
+Booting...
+
+FreeRTOS V10.4.4+ on NEORV32 Demo
+
+Hello
+<NEORV32-IRQ> mcause = 0x80000018,  Channel = 0 </NEORV32-IRQ>
+Hello
+<NEORV32-IRQ> mcause = 0x80000018,  Channel = 1 </NEORV32-IRQ>
+<NEORV32-IRQ> mcause = 0x80000018,  Channel = 2 </NEORV32-IRQ>
+<NEORV32-IRQ> mcause = 0x80000018,  Channel = 2 </NEORV32-IRQ>
+Hello
+Hello
+```
+
+## NEORV32-Specific Interrupts and Exceptions
+
+The `main.c` file provides two "trampolines" for NEORV32-specific interrupts/exceptions:
+
+```c
+/* Handle NEORV32-specific interrupts */
+void freertos_risc_v_application_interrupt_handler(void) {
+
+  // acknowledge XIRQ (FRIST!)
+  NEORV32_XIRQ->EIP = 0; // clear pending interrupt
+  uint32_t irq_channel = NEORV32_XIRQ->ESC; // store the channel before clearing it. 
+  NEORV32_XIRQ->ESC = 0; // acknowledge XIRQ interrupt
+
+  // acknowledge/clear ALL pending interrupt sources here - adapt this for your setup
+  neorv32_cpu_csr_write(CSR_MIP, 0);
+
+  // debug output - Use the value from the mcause CSR to call interrupt-specific handlers
+  neorv32_uart0_printf("\n<NEORV32-IRQ> mcause = 0x%x,  Channel = %d </NEORV32-IRQ>\n", neorv32_cpu_csr_read(CSR_MCAUSE), irq_channel);
+}
+
+/* Handle NEORV32-specific exceptions */
+void freertos_risc_v_application_exception_handler(void) {
+
+  // debug output
+  neorv32_uart0_printf("\n<NEORV32-EXC> mcause = 0x%x </NEORV32-EXC>\n", neorv32_cpu_csr_read(CSR_MCAUSE));
+}
+```
+
+This functions can be used to call specific handlers based on the value from the `mcause` CSR, which indicates
+the actual cause of the interrupt or exception (for example FIRQ channel or illegal instruction).
+
+
+## Notes
+
+The onfiguration of the FreeRTOS home folder (via `FREERTOS_HOME`) is corrupted if the compiler shows the following error:
+
+```
+main.c:36:10: fatal error: FreeRTOS.h: No such file or directory
+   36 | #include <FreeRTOS.h>
+      |          ^~~~~~~~~~~~
+compilation terminated.
+make: *** [makefile:203: main.c.o] Error 1
+```
+

sw/example/demo_freeRTOS_xirq/chip_specific_extensions/neorv32/freertos_risc_v_chip_specific_extensions.h

@@ -0,0 +1,72 @@
+/*
+ * FreeRTOS Kernel V10.3.1
+ * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
+ *
+ * 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.
+ *
+ * http://www.FreeRTOS.org
+ * http://aws.amazon.com/freertos
+ *
+ * 1 tab == 4 spaces!
+ */
+
+/*
+ * The FreeRTOS kernel's RISC-V port is split between the the code that is
+ * common across all currently supported RISC-V chips (implementations of the
+ * RISC-V ISA), and code that tailors the port to a specific RISC-V chip:
+ *
+ * + FreeRTOS\Source\portable\GCC\RISC-V-RV32\portASM.S contains the code that
+ *   is common to all currently supported RISC-V chips.  There is only one
+ *   portASM.S file because the same file is built for all RISC-V target chips.
+ *
+ * + Header files called freertos_risc_v_chip_specific_extensions.h contain the
+ *   code that tailors the FreeRTOS kernel's RISC-V port to a specific RISC-V
+ *   chip.  There are multiple freertos_risc_v_chip_specific_extensions.h files
+ *   as there are multiple RISC-V chip implementations.
+ *
+ * !!!NOTE!!!
+ * TAKE CARE TO INCLUDE THE CORRECT freertos_risc_v_chip_specific_extensions.h
+ * HEADER FILE FOR THE CHIP IN USE.  This is done using the assembler's (not the
+ * compiler's!) include path.  For example, if the chip in use includes a core
+ * local interrupter (CLINT) and does not include any chip specific register
+ * extensions then add the path below to the assembler's include path:
+ * FreeRTOS\Source\portable\GCC\RISC-V-RV32\chip_specific_extensions\RV32I_CLINT_no_extensions
+ *
+ */
+
+/*
+ * NEORV32 chip specific extensions
+ */
+
+
+#ifndef __FREERTOS_RISC_V_EXTENSIONS_H__
+#define __FREERTOS_RISC_V_EXTENSIONS_H__
+
+#define portasmHAS_SIFIVE_CLINT 0
+#define portasmHAS_MTIME 1
+#define portasmADDITIONAL_CONTEXT_SIZE 0 /* Must be even number on 32-bit cores. */
+
+.macro portasmSAVE_ADDITIONAL_REGISTERS
+	/* No additional registers to save, so this macro does nothing. */
+	.endm
+
+.macro portasmRESTORE_ADDITIONAL_REGISTERS
+	/* No additional registers to restore, so this macro does nothing. */
+	.endm
+
+#endif /* __FREERTOS_RISC_V_EXTENSIONS_H__ */