1/*
2 * FreeRTOS Kernel <DEVELOPMENT BRANCH>
3 * Copyright (C) 2021 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 *
5 * SPDX-License-Identifier: MIT
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a copy of
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
20 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
21 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23 *
24 * https://www.FreeRTOS.org
25 * https://github.com/FreeRTOS
26 *
27 */
28
29/*
30 * The FreeRTOS kernel's RISC-V port is split between the the code that is
31 * common across all currently supported RISC-V chips (implementations of the
32 * RISC-V ISA), and code which tailors the port to a specific RISC-V chip:
33 *
34 * + The code that is common to all RISC-V chips is implemented in
35 *   FreeRTOS\Source\portable\GCC\RISC-V\portASM.S.  There is only one
36 *   portASM.S file because the same file is used no matter which RISC-V chip is
37 *   in use.
38 *
39 * + The code that tailors the kernel's RISC-V port to a specific RISC-V
40 *   chip is implemented in freertos_risc_v_chip_specific_extensions.h.  There
41 *   is one freertos_risc_v_chip_specific_extensions.h that can be used with any
42 *   RISC-V chip that both includes a standard CLINT and does not add to the
43 *   base set of RISC-V registers.  There are additional
44 *   freertos_risc_v_chip_specific_extensions.h files for RISC-V implementations
45 *   that do not include a standard CLINT or do add to the base set of RISC-V
46 *   registers.
47 *
48 * CARE MUST BE TAKEN TO INCLDUE THE CORRECT
49 * freertos_risc_v_chip_specific_extensions.h HEADER FILE FOR THE CHIP
50 * IN USE.  To include the correct freertos_risc_v_chip_specific_extensions.h
51 * header file ensure the path to the correct header file is in the assembler's
52 * include path.
53 *
54 * This freertos_risc_v_chip_specific_extensions.h is for use on RISC-V chips
55 * that include a standard CLINT and do not add to the base set of RISC-V
56 * registers.
57 *
58 */
59
60#include "portContext.h"
61
62/* Check the freertos_risc_v_chip_specific_extensions.h and/or command line
63definitions. */
64#if defined( portasmHAS_CLINT ) && defined( portasmHAS_MTIME )
65    #error The portasmHAS_CLINT constant has been deprecated.  Please replace it with portasmHAS_MTIME.  portasmHAS_CLINT and portasmHAS_MTIME cannot both be defined at once.  See https://www.FreeRTOS.org/Using-FreeRTOS-on-RISC-V.html
66#endif
67
68#ifdef portasmHAS_CLINT
69    #warning The portasmHAS_CLINT constant has been deprecated.  Please replace it with portasmHAS_MTIME and portasmHAS_SIFIVE_CLINT.  For now portasmHAS_MTIME and portasmHAS_SIFIVE_CLINT are derived from portasmHAS_CLINT.  See https://www.FreeRTOS.org/Using-FreeRTOS-on-RISC-V.html
70    #define portasmHAS_MTIME portasmHAS_CLINT
71    #define portasmHAS_SIFIVE_CLINT portasmHAS_CLINT
72#endif
73
74#ifndef portasmHAS_MTIME
75    #error freertos_risc_v_chip_specific_extensions.h must define portasmHAS_MTIME to either 1 (MTIME clock present) or 0 (MTIME clock not present).  See https://www.FreeRTOS.org/Using-FreeRTOS-on-RISC-V.html
76#endif
77
78#ifndef portasmHAS_SIFIVE_CLINT
79    #define portasmHAS_SIFIVE_CLINT 0
80#endif
81
82.global xPortStartFirstTask
83.global pxPortInitialiseStack
84.global freertos_risc_v_trap_handler
85.global freertos_risc_v_exception_handler
86.global freertos_risc_v_interrupt_handler
87.global freertos_risc_v_mtimer_interrupt_handler
88
89.extern vTaskSwitchContext
90.extern xTaskIncrementTick
91.extern pullMachineTimerCompareRegister
92.extern pullNextTime
93.extern uxTimerIncrementsForOneTick /* size_t type so 32-bit on 32-bit core and 64-bits on 64-bit core. */
94.extern xTaskReturnAddress
95
96.weak freertos_risc_v_application_exception_handler
97.weak freertos_risc_v_application_interrupt_handler
98/*-----------------------------------------------------------*/
99
100.macro portUPDATE_MTIMER_COMPARE_REGISTER
101    load_x a0, pullMachineTimerCompareRegister  /* Load address of compare register into a0. */
102    load_x a1, pullNextTime                     /* Load the address of ullNextTime into a1. */
103
104    #if( __riscv_xlen == 32 )
105
106        /* Update the 64-bit mtimer compare match value in two 32-bit writes. */
107        li a4, -1
108        lw a2, 0(a1)                /* Load the low word of ullNextTime into a2. */
109        lw a3, 4(a1)                /* Load the high word of ullNextTime into a3. */
110        sw a4, 0(a0)                /* Low word no smaller than old value to start with - will be overwritten below. */
111        sw a3, 4(a0)                /* Store high word of ullNextTime into compare register.  No smaller than new value. */
112        sw a2, 0(a0)                /* Store low word of ullNextTime into compare register. */
113        lw t0, uxTimerIncrementsForOneTick  /* Load the value of ullTimerIncrementForOneTick into t0 (could this be optimized by storing in an array next to pullNextTime?). */
114        add a4, t0, a2              /* Add the low word of ullNextTime to the timer increments for one tick (assumes timer increment for one tick fits in 32-bits). */
115        sltu t1, a4, a2             /* See if the sum of low words overflowed (what about the zero case?). */
116        add t2, a3, t1              /* Add overflow to high word of ullNextTime. */
117        sw a4, 0(a1)                /* Store new low word of ullNextTime. */
118        sw t2, 4(a1)                /* Store new high word of ullNextTime. */
119
120    #endif /* __riscv_xlen == 32 */
121
122    #if( __riscv_xlen == 64 )
123
124        /* Update the 64-bit mtimer compare match value. */
125        ld t2, 0(a1)                /* Load ullNextTime into t2. */
126        sd t2, 0(a0)                /* Store ullNextTime into compare register. */
127        ld t0, uxTimerIncrementsForOneTick  /* Load the value of ullTimerIncrementForOneTick into t0 (could this be optimized by storing in an array next to pullNextTime?). */
128        add t4, t0, t2              /* Add ullNextTime to the timer increments for one tick. */
129        sd t4, 0(a1)                /* Store ullNextTime. */
130
131    #endif /* __riscv_xlen == 64 */
132    .endm
133/*-----------------------------------------------------------*/
134
135/*
136 * Unlike other ports pxPortInitialiseStack() is written in assembly code as it
137 * needs access to the portasmADDITIONAL_CONTEXT_SIZE constant.  The prototype
138 * for the function is as per the other ports:
139 * StackType_t *pxPortInitialiseStack( StackType_t *pxTopOfStack, TaskFunction_t pxCode, void *pvParameters );
140 *
141 * As per the standard RISC-V ABI pxTopOfStack is passed in in a0, pxCode in
142 * a1, and pvParameters in a2.  The new top of stack is passed out in a0.
143 *
144 * RISC-V maps registers to ABI names as follows (X1 to X31 integer registers
145 * for the 'I' profile, X1 to X15 for the 'E' profile, currently I assumed).
146 *
147 * Register      ABI Name    Description                       Saver
148 * x0            zero        Hard-wired zero                   -
149 * x1            ra          Return address                    Caller
150 * x2            sp          Stack pointer                     Callee
151 * x3            gp          Global pointer                    -
152 * x4            tp          Thread pointer                    -
153 * x5-7          t0-2        Temporaries                       Caller
154 * x8            s0/fp       Saved register/Frame pointer      Callee
155 * x9            s1          Saved register                    Callee
156 * x10-11        a0-1        Function Arguments/return values  Caller
157 * x12-17        a2-7        Function arguments                Caller
158 * x18-27        s2-11       Saved registers                   Callee
159 * x28-31        t3-6        Temporaries                       Caller
160 *
161 * The RISC-V context is saved to FreeRTOS tasks in the following stack frame,
162 * where the global and thread pointers are currently assumed to be constant so
163 * are not saved:
164 *
165 * xCriticalNesting
166 * x31
167 * x30
168 * x29
169 * x28
170 * x27
171 * x26
172 * x25
173 * x24
174 * x23
175 * x22
176 * x21
177 * x20
178 * x19
179 * x18
180 * x17
181 * x16
182 * x15
183 * x14
184 * x13
185 * x12
186 * x11
187 * pvParameters
188 * x9
189 * x8
190 * x7
191 * x6
192 * x5
193 * portTASK_RETURN_ADDRESS
194 * [FPU registers (when enabled/available) go here]
195 * [VPU registers (when enabled/available) go here]
196 * [chip specific registers go here]
197 * mstatus
198 * pxCode
199 */
200pxPortInitialiseStack:
201    addi a0, a0, -portWORD_SIZE         /* Space for critical nesting count. */
202    store_x x0, 0(a0)                   /* Critical nesting count starts at 0 for every task. */
203
204#ifdef __riscv_32e
205    addi a0, a0, -(6 * portWORD_SIZE)   /* Space for registers x10-x15. */
206#else
207    addi a0, a0, -(22 * portWORD_SIZE)  /* Space for registers x10-x31. */
208#endif
209    store_x a2, 0(a0)                   /* Task parameters (pvParameters parameter) goes into register x10/a0 on the stack. */
210
211    addi a0, a0, -(6 * portWORD_SIZE)   /* Space for registers x5-x9 + taskReturnAddress (register x1). */
212    load_x t0, xTaskReturnAddress
213    store_x t0, 0(a0)                   /* Return address onto the stack. */
214
215    addi t0, x0, portasmADDITIONAL_CONTEXT_SIZE /* The number of chip specific additional registers. */
216chip_specific_stack_frame:              /* First add any chip specific registers to the stack frame being created. */
217    beq t0, x0, 1f                      /* No more chip specific registers to save. */
218    addi a0, a0, -portWORD_SIZE         /* Make space for chip specific register. */
219    store_x x0, 0(a0)                   /* Give the chip specific register an initial value of zero. */
220    addi t0, t0, -1                     /* Decrement the count of chip specific registers remaining. */
221    j chip_specific_stack_frame         /* Until no more chip specific registers. */
2221:
223    csrr t0, mstatus                    /* Obtain current mstatus value. */
224    andi t0, t0, ~0x8                   /* Ensure interrupts are disabled when the stack is restored within an ISR.  Required when a task is created after the scheduler has been started, otherwise interrupts would be disabled anyway. */
225    addi t1, x0, 0x188                  /* Generate the value 0x1880, which are the MPIE=1 and MPP=M_Mode in mstatus. */
226    slli t1, t1, 4
227    or t0, t0, t1                       /* Set MPIE and MPP bits in mstatus value. */
228
229#if( configENABLE_FPU == 1 )
230    /* Mark the FPU as clean in the mstatus value. */
231    li t1, ~MSTATUS_FS_MASK
232    and t0, t0, t1
233    li t1, MSTATUS_FS_CLEAN
234    or t0, t0, t1
235#endif
236
237#if( configENABLE_VPU == 1 )
238    /* Mark the VPU as clean in the mstatus value. */
239    li t1, ~MSTATUS_VS_MASK
240    and t0, t0, t1
241    li t1, MSTATUS_VS_CLEAN
242    or t0, t0, t1
243#endif
244
245    addi a0, a0, -portWORD_SIZE
246    store_x t0, 0(a0)                   /* mstatus onto the stack. */
247
248    addi a0, a0, -portWORD_SIZE
249    store_x a1, 0(a0)                   /* mret value (pxCode parameter) onto the stack. */
250    ret
251/*-----------------------------------------------------------*/
252
253xPortStartFirstTask:
254    load_x  sp, pxCurrentTCB            /* Load pxCurrentTCB. */
255    load_x  sp, 0( sp )                 /* Read sp from first TCB member. */
256
257    load_x  x1, 0( sp ) /* Note for starting the scheduler the exception return address is used as the function return address. */
258
259    load_x  x5, 1 * portWORD_SIZE( sp ) /* Initial mstatus into x5 (t0). */
260    addi    x5, x5, 0x08                /* Set MIE bit so the first task starts with interrupts enabled - required as returns with ret not eret. */
261    csrw    mstatus, x5                 /* Interrupts enabled from here! */
262
263    portasmRESTORE_ADDITIONAL_REGISTERS /* Defined in freertos_risc_v_chip_specific_extensions.h to restore any registers unique to the RISC-V implementation. */
264
265    load_x  x7,  5  * portWORD_SIZE( sp )   /* t2 */
266    load_x  x8,  6  * portWORD_SIZE( sp )   /* s0/fp */
267    load_x  x9,  7  * portWORD_SIZE( sp )   /* s1 */
268    load_x  x10, 8  * portWORD_SIZE( sp )   /* a0 */
269    load_x  x11, 9  * portWORD_SIZE( sp )   /* a1 */
270    load_x  x12, 10 * portWORD_SIZE( sp )   /* a2 */
271    load_x  x13, 11 * portWORD_SIZE( sp )   /* a3 */
272    load_x  x14, 12 * portWORD_SIZE( sp )   /* a4 */
273    load_x  x15, 13 * portWORD_SIZE( sp )   /* a5 */
274#ifndef __riscv_32e
275    load_x  x16, 14 * portWORD_SIZE( sp )   /* a6 */
276    load_x  x17, 15 * portWORD_SIZE( sp )   /* a7 */
277    load_x  x18, 16 * portWORD_SIZE( sp )   /* s2 */
278    load_x  x19, 17 * portWORD_SIZE( sp )   /* s3 */
279    load_x  x20, 18 * portWORD_SIZE( sp )   /* s4 */
280    load_x  x21, 19 * portWORD_SIZE( sp )   /* s5 */
281    load_x  x22, 20 * portWORD_SIZE( sp )   /* s6 */
282    load_x  x23, 21 * portWORD_SIZE( sp )   /* s7 */
283    load_x  x24, 22 * portWORD_SIZE( sp )   /* s8 */
284    load_x  x25, 23 * portWORD_SIZE( sp )   /* s9 */
285    load_x  x26, 24 * portWORD_SIZE( sp )   /* s10 */
286    load_x  x27, 25 * portWORD_SIZE( sp )   /* s11 */
287    load_x  x28, 26 * portWORD_SIZE( sp )   /* t3 */
288    load_x  x29, 27 * portWORD_SIZE( sp )   /* t4 */
289    load_x  x30, 28 * portWORD_SIZE( sp )   /* t5 */
290    load_x  x31, 29 * portWORD_SIZE( sp )   /* t6 */
291#endif
292
293    load_x  x5, portCRITICAL_NESTING_OFFSET * portWORD_SIZE( sp )    /* Obtain xCriticalNesting value for this task from task's stack. */
294    load_x  x6, pxCriticalNesting           /* Load the address of xCriticalNesting into x6. */
295    store_x x5, 0( x6 )                     /* Restore the critical nesting value for this task. */
296
297    load_x  x5, 3 * portWORD_SIZE( sp )     /* Initial x5 (t0) value. */
298    load_x  x6, 4 * portWORD_SIZE( sp )     /* Initial x6 (t1) value. */
299
300    addi    sp, sp, portCONTEXT_SIZE
301    ret
302/*-----------------------------------------------------------*/
303
304freertos_risc_v_application_exception_handler:
305    csrr t0, mcause     /* For viewing in the debugger only. */
306    csrr t1, mepc       /* For viewing in the debugger only */
307    csrr t2, mstatus    /* For viewing in the debugger only */
308    j .
309/*-----------------------------------------------------------*/
310
311freertos_risc_v_application_interrupt_handler:
312    csrr t0, mcause     /* For viewing in the debugger only. */
313    csrr t1, mepc       /* For viewing in the debugger only */
314    csrr t2, mstatus    /* For viewing in the debugger only */
315    j .
316/*-----------------------------------------------------------*/
317
318.section .text.freertos_risc_v_exception_handler
319freertos_risc_v_exception_handler:
320    portcontextSAVE_EXCEPTION_CONTEXT
321    /* a0 now contains mcause. */
322    li t0, 11                           /* 11 == environment call. */
323    bne a0, t0, other_exception         /* Not an M environment call, so some other exception. */
324    call vTaskSwitchContext
325    portcontextRESTORE_CONTEXT
326
327other_exception:
328    call freertos_risc_v_application_exception_handler
329    portcontextRESTORE_CONTEXT
330/*-----------------------------------------------------------*/
331
332.section .text.freertos_risc_v_interrupt_handler
333freertos_risc_v_interrupt_handler:
334    portcontextSAVE_INTERRUPT_CONTEXT
335    call freertos_risc_v_application_interrupt_handler
336    portcontextRESTORE_CONTEXT
337/*-----------------------------------------------------------*/
338
339.section .text.freertos_risc_v_mtimer_interrupt_handler
340freertos_risc_v_mtimer_interrupt_handler:
341    portcontextSAVE_INTERRUPT_CONTEXT
342    portUPDATE_MTIMER_COMPARE_REGISTER
343    call xTaskIncrementTick
344    beqz a0, exit_without_context_switch    /* Don't switch context if incrementing tick didn't unblock a task. */
345    call vTaskSwitchContext
346exit_without_context_switch:
347    portcontextRESTORE_CONTEXT
348/*-----------------------------------------------------------*/
349
350.section .text.freertos_risc_v_trap_handler
351.align 8
352freertos_risc_v_trap_handler:
353    portcontextSAVE_CONTEXT_INTERNAL
354
355    csrr a0, mcause
356    csrr a1, mepc
357
358    bge a0, x0, synchronous_exception
359
360asynchronous_interrupt:
361    store_x a1, 0( sp )                 /* Asynchronous interrupt so save unmodified exception return address. */
362    load_x sp, xISRStackTop             /* Switch to ISR stack. */
363    j handle_interrupt
364
365synchronous_exception:
366    addi a1, a1, 4                      /* Synchronous so update exception return address to the instruction after the instruction that generated the exeption. */
367    store_x a1, 0( sp )                 /* Save updated exception return address. */
368    load_x sp, xISRStackTop             /* Switch to ISR stack. */
369    j handle_exception
370
371handle_interrupt:
372#if( portasmHAS_MTIME != 0 )
373
374    test_if_mtimer:                     /* If there is a CLINT then the mtimer is used to generate the tick interrupt. */
375        addi t0, x0, 1
376        slli t0, t0, __riscv_xlen - 1   /* LSB is already set, shift into MSB.  Shift 31 on 32-bit or 63 on 64-bit cores. */
377        addi t1, t0, 7                  /* 0x8000[]0007 == machine timer interrupt. */
378        bne a0, t1, application_interrupt_handler
379
380        portUPDATE_MTIMER_COMPARE_REGISTER
381        call xTaskIncrementTick
382        beqz a0, processed_source       /* Don't switch context if incrementing tick didn't unblock a task. */
383        call vTaskSwitchContext
384        j processed_source
385
386#endif /* portasmHAS_MTIME */
387
388application_interrupt_handler:
389    call freertos_risc_v_application_interrupt_handler
390    j processed_source
391
392handle_exception:
393    /* a0 contains mcause. */
394    li t0, 11                                   /* 11 == environment call. */
395    bne a0, t0, application_exception_handler   /* Not an M environment call, so some other exception. */
396    call vTaskSwitchContext
397    j processed_source
398
399application_exception_handler:
400    call freertos_risc_v_application_exception_handler
401    j processed_source                  /* No other exceptions handled yet. */
402
403processed_source:
404    portcontextRESTORE_CONTEXT
405/*-----------------------------------------------------------*/
406