doc: add more doc about iar compiler support and porting notes

Signed-off-by: Huaqi Fang <[email protected]>

README.md

@@ -23,6 +23,8 @@ We also integrated many RTOSes into Nuclei SDK, which are **FreeRTOS**, **UCOSII
 
 Wanner to take a try with **Nuclei SDK for Nuclei 200/300/600/900/1000 series CPU**, click [Quick Start with Nuclei SDK](https://doc.nucleisys.com/nuclei_sdk/quickstart.html) to start up.
 
+> If you want to check how to use with IAR compiler, please check [ideprojects/iar/README.md](ideprojects/iar/README.md).
+
 Wanner to take a try with **Nuclei N100 SDK for Nuclei 100 series CPU**, click [Quick Start with Nuclei N100 SDK](https://doc.nucleisys.com/nuclei_n100_sdk/quickstart.html) to start up.
 
 ## Requirements

SoC/evalsoc/Board/nuclei_fpga_eval/Source/IAR/iar_evalsoc_ddr.icf

@@ -8,7 +8,7 @@ define exported symbol _max_vector = 4096;
 
 define memory mem with size = 4G;
 
-/* Set memory region information according to your device */
+/* TODO: Set memory region information according to your device */
 /* For this case, ROM and RAM are both DDR region */
 define region ROM_region32 = mem:[from 0xA0000000 size 0x08000000];
 define region RAM_region32 = mem:[from 0xA8000000 size 0x08000000];

SoC/evalsoc/Board/nuclei_fpga_eval/Source/IAR/iar_evalsoc_flashxip.icf

@@ -8,7 +8,7 @@ define exported symbol _link_file_version_2 = 1;
 define memory mem with size = 4G;
 define exported symbol _max_vector = 4096;
 
-/* Set memory region information according to your device */
+/* TODO: Set memory region information according to your device */
 /* For this case, ROM is the flashxip region, and ILM is the ILM region, RAM is the DLM region */
 define region ROM_region32 = mem:[from 0x20000000 size 0x800000];
 define region ILM_region32 = mem:[from 0x80000000 size 0x10000];

SoC/evalsoc/Board/nuclei_fpga_eval/Source/IAR/iar_evalsoc_ilm.icf

@@ -8,7 +8,7 @@ define exported symbol _max_vector = 4096;
 
 define memory mem with size = 4G;
 
-/* Set memory region information according to your device */
+/* TODO: Set memory region information according to your device */
 /* For this case, ROM is the ILM region, RAM is the DLM region */
 define region ROM_region32 = mem:[from 0x80000000 size 0x10000];
 define region RAM_region32 = mem:[from 0x90000000 size 0x10000];

SoC/evalsoc/Board/nuclei_fpga_eval/Source/IAR/iar_evalsoc_sram.icf

@@ -8,7 +8,7 @@ define exported symbol _max_vector = 4096;
 
 define memory mem with size = 4G;
 
-/* Set memory region information according to your device */
+/* TODO: Set memory region information according to your device */
 /* For this case, ROM and RAM are both SRAM region */
 define region ROM_region32 = mem:[from 0xA0000000 size 0x20000];
 define region RAM_region32 = mem:[from 0xA0020000 size 0x20000];

SoC/evalsoc/Common/Source/IAR/startup_evalsoc.c

@@ -155,7 +155,7 @@ __weak int smp_main(void)
     return 0;
 }
 
-// TODO: Currently only single core is supported
+// NOTE: __lower_level_init will directly call main or smp_main and not return
 int __low_level_init(void)
 {
     unsigned long hartid = __get_hart_id();

SoC/evalsoc/Common/Source/Stubs/iardlib/stubs.c

@@ -2,12 +2,14 @@
 
 // #define UART_AUTO_ECHO
 
-// uncomment it if you want to print via IAR Breakpoint(C-SPY emulated IO)
+// TODO uncomment it if you want to print via IAR Breakpoint(C-SPY emulated IO)
 // You need to set Library Configuration -> Stdout/Stderr -> Via IAR Breakpoint
 // #define DEBUG_IAR_BREAKPOINT
 
 // For more iar dlib stub function
 
+// TODO Implement your own uart_write and uart_read for your debug uart device
+
 #ifndef DEBUG_IAR_BREAKPOINT
 // By default print via uart io
 int putchar(int ch)

SoC/evalsoc/Common/Source/Stubs/libncrt/stubs.c

@@ -8,6 +8,8 @@
 // When see issue above, please don't link -lm library
 // math library is already provided in libncrt library, no need to link -lm
 
+// TODO Implement your own uart_write and uart_read for your debug uart device
+
 __USED int metal_tty_putc(int c)
 {
     if (c == '\n') {

SoC/evalsoc/Common/Source/Stubs/newlib/stubs.c

@@ -16,6 +16,8 @@ extern int errno;
 /* Key stub function for uart io via printf/scanf and heap management */
 #undef putchar
 
+// TODO Implement your own uart_write and uart_read for your debug uart device
+
 int putchar(int dat)
 {
     if (dat == '\n') {

application/baremetal/demo_cidu/iar_evalsoc_smp.icf

@@ -10,6 +10,7 @@ define exported symbol __HEAP_SIZE = HEAP_SIZE;
 
 define memory mem with size = 4G;
 
+// TODO: Set memory region information according to your device
 define region ROM_region32 = mem:[from 0xA0000000 size 0x2000000];
 define region RAM_region32 = mem:[from 0xA2000000 size 0x2000000];
 

application/baremetal/demo_pmp/iar_evalsoc_ilm.icf

@@ -8,6 +8,7 @@ define exported symbol _max_vector = 4096;
 
 define memory mem with size = 4G;
 
+// TODO: Set memory region information according to your device
 define region ROM_region32 = mem:[from 0x80000000 size 0x10000];
 define region RAM_region32 = mem:[from 0x90000000 size 0x10000];
 

application/baremetal/demo_spmp/iar_evalsoc_ilm.icf

@@ -8,6 +8,7 @@ define exported symbol _max_vector = 4096;
 
 define memory mem with size = 4G;
 
+// TODO: Set memory region information according to your device
 define region ROM_region32 = mem:[from 0x80000000 size 0x10000];
 define region RAM_region32 = mem:[from 0x90000000 size 0x10000];
 

application/baremetal/smphello/iar_evalsoc_smp.icf

@@ -10,6 +10,7 @@ define exported symbol __HEAP_SIZE = HEAP_SIZE;
 
 define memory mem with size = 4G;
 
+// TODO: Set memory region information according to your device
 define region ROM_region32 = mem:[from 0xA0000000 size 0x2000000];
 define region RAM_region32 = mem:[from 0xA2000000 size 0x2000000];
 

application/freertos/smpdemo/iar_evalsoc_smp.icf

@@ -10,6 +10,7 @@ define exported symbol __HEAP_SIZE = HEAP_SIZE;
 
 define memory mem with size = 4G;
 
+// TODO: Set memory region information according to your device
 define region ROM_region32 = mem:[from 0xA0000000 size 0x2000000];
 define region RAM_region32 = mem:[from 0xA2000000 size 0x2000000];
 

doc/source/changelog.rst

@@ -6,7 +6,11 @@ Changelog
 V0.8.0
 ------
 
-This is version ``0.7.1`` of Nuclei SDK which is still in development.
+This is version ``0.8.0`` of Nuclei SDK which is still in development.
+
+* SoC
+
+  - Add more documentation about IAR compiler support and porting notes, especially the vector table alignment with the ``MTVT`` CSR.
 
 
 V0.7.1
@@ -27,7 +31,7 @@ This is release version ``0.7.1`` of Nuclei SDK.
 * Misc
 
   - Fix various typos found in source code and doc
-  - Recommend evalsoc user to run :ref:`cpuinfo` to check cpu features it present
+  - Recommend evalsoc user to run :ref:`design_app_cpuinfo` to check cpu features it present
   - If you want to do openocd rtos aware debug, you need to follow note in commit b7ed34e96
   - Evalsoc uart eclic irq maybe not working due to different cpu configuration
 

doc/source/design/soc/evalsoc.rst

@@ -80,6 +80,10 @@ Usage
 If you want to use this **Nuclei Evaluation SoC** in Nuclei SDK, you need to set the
 :ref:`develop_buildsystem_var_soc` Makefile variable to ``evalsoc``.
 
+.. note::
+
+    IAR support is done by prebuilt IAR projects not through Makefile based build system, please check https://github.com/Nuclei-Software/nuclei-sdk/blob/master/ideprojects/iar/README.md for detailed usage.
+
 Extra make variables supported only in this SoC and used internally only by Nuclei, not designed for widely used:
   * **RUNMODE**: it is used internally by Nuclei, used to control ILM/DLM/ICache/DCache enable or disable
     via make variable, please check ``SoC/evalsoc/runmode.mk`` for details. It is not functional by default,

doc/source/develop/buildsystem.rst

@@ -584,15 +584,15 @@ This variable is used to select different toolchain to compile application.
 Currently we support 3 toolchain in Nuclei SDK.
 
 * **nuclei_gnu**: default, it will choose nuclei gnu toolchain, distributed with Nuclei Toolchain.
-* **nuclei_llvm**: still in experiment, nuclei customized extensions not yet supported, distributed with Nuclei Toolchain.
-* **terapines**: still in experiment, it depends on the toolchain vendor about the supported extensions, if you want to take a try with it, just visit https://www.terapines.com/ and request an terapines toolchain evaluation.
+* **nuclei_llvm**: supported, nuclei customized extensions not yet supported, distributed with Nuclei Toolchain.
+* **terapines**: supported, it depends on the toolchain vendor about the supported extensions, if you want to take a try with it, just visit https://www.terapines.com/ and request an terapines toolchain evaluation.
 
 For **nuclei_gnu/nuclei_llvm** toolchain both newlib and libncrt library are supported,
 but nuclei_llvm toolchain multilib selection mechanism is not as good as gnu toolchain,
 you need to take care of the arch isa string order, please see ``riscv64-unknown-unknown-elf-clang -v`` output for supported multilib and its isa string order.
 
-And IAR compiler support is also done in Nuclei SDK, you can take a try with it
-via ``ideprojects/iar`` folder provided prebuilt ide projects.
+And **IAR compiler** support is also done in Nuclei SDK, you can take a try with it
+via `ideprojects/iar`_ folder provided prebuilt ide projects.
 
 If you want to use old Nuclei GNU Toolchain <= 2022.12 in Nuclei SDK 0.5.0, you need to pass extra ``COMPILE_PREFIX=riscv-nuclei-elf-`` when build any application, such as ``make CORE=n300fd COMPILE_PREFIX=riscv-nuclei-elf-  STDCLIB=libncrt_small clean all``, but this is not recommended, and will be deprecated in future any time.
 
@@ -1828,3 +1828,4 @@ For example, ``LINKER_SCRIPT := gcc.ld``.
 .. _zfh extension: https://wiki.riscv.org/display/HOME/Recently+Ratified+Extensions
 .. _zvfh extension: https://github.com/riscv/riscv-v-spec/releases/tag/zvfh
 .. _Nuclei Toolchain 2023.10: https://github.com/riscv-mcu/riscv-gnu-toolchain/releases/tag/nuclei-2023.10
+.. _ideprojects/iar: https://github.com/Nuclei-Software/nuclei-sdk/blob/master/ideprojects/iar/README.md

doc/source/quickstart.rst

@@ -600,7 +600,8 @@ For more advanced usage, please follow the items as below:
       2. Now **Terapines ZCC Lite** is deeply integrated in **Nuclei Studio >= 2024.06**, so you just need to
          follow :ref:`quickstart_get_set_nuclei_sdk` to setup PATH for Terapines ZCC, and in Nuclei SDK,
          you can just pass **TOOCHAIN=terapines** during make to take a try with Terapines ZCC.
-         From 0.7.0 release, you can create project in Nuclei Studio >= 2024.06 using Terapines ZCC.
+         From 0.7.0 release, you can create project in Nuclei Studio >= 2024.06 using Terapines ZCC, see
+         `Using Terapines ZCC Toolchain in Nuclei Studio`_.
 
       3. You can take a try using IAR workbench, we provided prebuilt projects directly in Nuclei SDK,
          just check the `ideprojects/iar/README.md`_ to learn about it.
@@ -614,7 +615,7 @@ For more advanced usage, please follow the items as below:
          to play with PlatformIO for Nuclei.
 
       6. You can also use source code in Nuclei SDK as base, and easily integrate with other IDE tools,
-         such as ZStudio IDE, Compiler-IDE and others.
+         such as `ZStudio IDE`_, `Compiler IDE`_ and others.
 
 
 .. _GDB User Manual: https://www.gnu.org/software/gdb/documentation/
@@ -626,3 +627,6 @@ For more advanced usage, please follow the items as below:
 .. _Nuclei Toolchain 2023.10: https://github.com/riscv-mcu/riscv-gnu-toolchain/releases/tag/nuclei-2023.10
 .. _ideprojects/iar/README.md: https://github.com/Nuclei-Software/nuclei-sdk/blob/master/ideprojects/iar/README.md
 .. _Nuclei Studio 2024.06: https://github.com/Nuclei-Software/nuclei-studio/releases/tag/2024.06
+.. _Using Terapines ZCC Toolchain in Nuclei Studio: https://1nfinite.ai/t/nuclei-studio-2024-06-ide-terapines-zcc/113
+.. _ZStudio IDE: https://1nfinite.ai/t/zstudio-ide-risc-v/71
+.. _Compiler IDE: https://www.compiler-dev.com/

ideprojects/iar/README.md

@@ -8,6 +8,10 @@ In this folder, we provided a prebuilt IAR workspace with baremetal and rtos pro
 
 > If you want to evaluate Nuclei N300 DSP feature(P-ext 0.5.4), you can change the file `C:\Program Files\IAR Systems\Embedded Workbench 9.2\riscv\config\devices\Nuclei\N300.menu`, change `RV32IMAFDCB_Zkn_Zks_Zcb_Zcmp` to `RV32IMAFDCB_Zkn_Zks_Zcb_Zcmp_Xandesdsp`, `Xandesdsp` is based on P-ext 0.5.0, there are some intruction encoding updates from 0.5.0 to 0.5.4, and we use IAR custom instruction intrinsic to implement the different instructions, please check `NMSIS/Core/core_feature_dsp.h` for details, and in future, we will co-operate with IAR to support full Nuclei DSP feature including(N1/N2/N3 custom enhancement instructions).
 
+> [!NOTE]
+> You can check all the IAR related files by command: `find . -iname "*iar*"` and take a look at the file
+> and directory content, and use case-insensitive grep todo items(`grep -irn todo /path/to/file`), if you want to port to your environment, you must modify the iar link script file `*.icf` to match your system memory map.
+
 These projects demostrated the following features:
 
 - Provide support for Nuclei Evaluation SoC which is a prototype and evaluation SoC mainly
@@ -27,10 +31,11 @@ These projects demostrated the following features:
   code use a lot of heap or stack, the application may crash, you need to increase stack or heap size on demand.
 
 > [!NOTE]
-> SMP is now supported in IAR workbench since Nuclei SDK 0.6.0, please refer to `smphello` or `demo_cidu` project.
-> `smphello` IAR IDE project by default should run on UX900FD x 4 SMP CORE, and program run on DDR memory.
-> `demo_cidu` IAR IDE project by default should run on UX900FD x 2 SMP CORE, and CIDU feature, and program run on DDR memory.
-> `freertos_smpdemo` IAR IDE project by default should run on NX900FD x 2 SMP CORE, with ECLIC present, and run on DDR memory to demostrate FreeRTOS with SMP feature, you can configure how smp cores used in this demo, by modify the project properties **configNUMBER_OF_CORES** and **SMP_CPU_CNT** in `C/C++ Compiler and Assembler -> Preprocessor -> Defined symbols(one per line)` and **SMP_CPU_CNT** in `Linker -> Config -> Configuration file symbol definitions:(one per line)`.
+> - In IAR, the eclic interrupt vector table is not placed in the start of ilm/rom start address, so you need to take care the vector table must be placed to be aligned to match the align requirement of `MTVT` CSR, see `startup_evalsoc.c`
+> - SMP is now supported in IAR workbench since Nuclei SDK 0.6.0, please refer to `smphello` or `demo_cidu` project.
+> - `smphello` IAR IDE project by default should run on UX900FD x 4 SMP CORE, and program run on DDR memory.
+> - `demo_cidu` IAR IDE project by default should run on UX900FD x 2 SMP CORE, and CIDU feature, and program run on DDR memory.
+> - `freertos_smpdemo` IAR IDE project by default should run on NX900FD x 2 SMP CORE, with ECLIC present, and run on DDR memory to demostrate FreeRTOS with SMP feature, you can configure how smp cores used in this demo, by modify the project properties **configNUMBER_OF_CORES** and **SMP_CPU_CNT** in `C/C++ Compiler and Assembler -> Preprocessor -> Defined symbols(one per line)` and **SMP_CPU_CNT** in `Linker -> Config -> Configuration file symbol definitions:(one per line)`.
 
 - SMP application is now supported in IAR project see `smphello`, to support SMP, you should use different startup asm code
   and different linker file provided in this repo, see `SoC/evalsoc/Common/Source/IAR/startup.S`, and for the linker file,