diff options
Diffstat (limited to 'user')
52 files changed, 622 insertions, 245 deletions
diff --git a/user/bld/index.rst b/user/bld/index.rst index 18092d2..dbad167 100644 --- a/user/bld/index.rst +++ b/user/bld/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019, 2020 embedded brains GmbH +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2019, 2020 Sebastian Huber .. index:: BSP build system @@ -25,7 +25,7 @@ RTEMS sources * the `waf <https://waf.io/>`_ meta build system command line tool, -* a `wscript <https://git.rtems.org/rtems/tree/wcript>`_ file used by ``waf``, +* a `wscript <https://git.rtems.org/rtems/tree/wscript>`_ file used by ``waf``, and * a diff --git a/user/bsps/aarch64/xilinx-zynqmp.rst b/user/bsps/aarch64/xilinx-zynqmp.rst index 1fef7a4..4de0115 100644 --- a/user/bsps/aarch64/xilinx-zynqmp.rst +++ b/user/bsps/aarch64/xilinx-zynqmp.rst @@ -253,7 +253,7 @@ as well as the physical ARM PL011 PrimeCell UART in the ZynqMP hardware. SDHCI Driver ------------ -The ZynqMP bsp has an SDHCI driver which allows reading to and writing from SD +The ZynqMP bsp has an SDHCI driver which allows writing to and reading from SD cards. These can be tested in qemu using the "-sd" option. For example: .. code-block:: shell diff --git a/user/bsps/arm/altera-cyclone-v.rst b/user/bsps/arm/altera-cyclone-v.rst index eaa02e3..12e563e 100644 --- a/user/bsps/arm/altera-cyclone-v.rst +++ b/user/bsps/arm/altera-cyclone-v.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2017, 2019 embedded brains GmbH +.. Copyright (C) 2017, 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2017, 2019 Sebastian Huber altera-cyclone-v (Intel Cyclone V) diff --git a/user/bsps/arm/fvp.rst b/user/bsps/arm/fvp.rst index a1e186a..b938e30 100644 --- a/user/bsps/arm/fvp.rst +++ b/user/bsps/arm/fvp.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2022 embedded brains GmbH +.. Copyright (C) 2022 embedded brains GmbH & Co. KG fvp (Fixed Virtual Platform) ============================ diff --git a/user/bsps/arm/imx.rst b/user/bsps/arm/imx.rst index f0ac928..47ad503 100644 --- a/user/bsps/arm/imx.rst +++ b/user/bsps/arm/imx.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2017, 2019 embedded brains GmbH +.. Copyright (C) 2017, 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2017, 2019 Sebastian Huber imx (NXP i.MX) diff --git a/user/bsps/arm/imxrt.rst b/user/bsps/arm/imxrt.rst index b4f37fd..30b1437 100644 --- a/user/bsps/arm/imxrt.rst +++ b/user/bsps/arm/imxrt.rst @@ -1,19 +1,22 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2020 Christian Mauderer imxrt (NXP i.MXRT) ================== -This BSP offers only one variant, the `imxrt1052`. This variant supports the -i.MXRT 1052 processor on a IMXRT1050-EVKB (tested with rev A1). You can also -configure it to work with custom boards. +This BSP offers multiple variants. The `imxrt1052` supports the i.MXRT 1052 +processor on a IMXRT1050-EVKB (tested with rev A1). Some possibilities to adapt +it to a custom board are described below. NOTE: The IMXRT1050-EVKB has an backlight controller that must not be enabled without load. Make sure to either attach a load, disable it by software or disable it by removing the 0-Ohm resistor on it's input. +The `imxrt1166-cm7-saltshaker` supports an application specific board. Adapting +it to another i.MXRT1166 based board works similar like for the `imxrt1052` BSP. + Build Configuration Options --------------------------- @@ -22,8 +25,24 @@ for that. You can generate a default set of options with:: ./waf bspdefaults --rtems-bsps=arm/imxrt1052 > config.ini -Boot Process ------------- +Adapting to a different board +----------------------------- + +This is only a short overview for the most important steps to adapt the BSP to +another board. Details for most steps follow further below. + +#. The device tree has to be adapted to fit the target hardware. +#. A matching clock configuration is necessary (simplest method is to generate + it with the NXP PinMux tool) +#. The `dcd_data` has to be adapted. That is used for example to initialize + SDRAM. +#. `imxrt_flexspi_config` has to be adapted to match the Flash connected to + FlexSPI (if that is used). +#. `BOARD_InitDEBUG_UARTPins` should be adapted to match the used system + console. + +Boot Process of IMXRT1050-EVKB +------------------------------ There are two possible boot processes supported: @@ -82,18 +101,19 @@ ones that need different values): You can find the default definitions in `bsps/arm/imxrt/start/flash-*.c`. Take a look at the `i.MX RT1050 Processor Reference Manual, Rev. 4, 12/2019` chapter -`9.7 Program image` for details about the contents. +`9.7 Program image` or `i.MX RT1166 Processor Reference Manual, Rev. 0, 05/2021` +chapter `10.7 Program image` for details about the contents. FDT --- The BSP uses a FDT based initialization. The FDT is linked into the application. -You can find the default FDT used in the BSP in -`bsps/arm/imxrt/dts/imxrt1050-evkb.dts`. The FDT is split up into two parts. The -core part is put into an `dtsi` file and is installed together with normal -headers into `${PREFIX}/arm-rtems@rtems-ver-major@/imxrt1052/lib/include`. You -can use that to create your own device tree based on that. Basically use -something like:: +You can find the default FDT used in the BSPs in `bsps/arm/imxrt/dts`. The FDT +is split up into two parts. The controller specific part is put into an `dtsi` +file. The board specific one is in the dts file. Both are installed together +with normal headers into +`${PREFIX}/arm-rtems@rtems-ver-major@/${BSP}/lib/include`. You can use that to +create your own device tree based on that. Basically use something like:: /dts-v1/; @@ -137,26 +157,6 @@ You'll get a C file which defines the `imxrt_dtb` array. Make sure that your new C file is compiled and linked into the application. It will overwrite the existing definition of the `imxrt_dtb` in RTEMS. -PLL Settings ------------- - -The commercial variant of the i.MXRT1052 on the evaluation board allows a clock -up to 600MHz for the ARM core. For some industrial variants only up to 528MHz -are specified. To make it possible to adapt to these variants the application -can overwrite the following constant: - -.. code-block:: c - - #include "fsl_clock_config.h" - - const clock_arm_pll_config_t armPllConfig_BOARD_BootClockRUN = { - .loopDivider = 100, - .src = 0, - }; - -With the default configuration of a 24MHz oscillator, the loopDivider has to be -88 for the 528MHz. - Clock Driver ------------ @@ -198,10 +198,38 @@ Note that the SPI-pins on the evaluation board are shared with the SD card. Populate R278, R279, R280, R281 on the IMXRT1050-EVKB (Rev A) to use the SPI pins on the Arduino connector. +By default, the native chip selects are used. If you want to use GPIOs as chip +select instead, you can use the `cs-gpios` and `num-cs` attributes just like on +a Linux SPI controller. A maximum of `IMXRT_LPSPI_MAX_CS` pins can be used. + +The hardware doesn't support selecting no native chip select during a transfer. +Therefore one native chip select has to be reserved as a dummy if you want to be +able to use GPIOs. The pin function for this chip select must not be configured +on any pin. Dummy will be the first of the first four chip selects that is not a +native one. Example configuration:: + + &lpspi4 { + status = "okay"; + pinctrl-0 = <&my_pinctrl_lpspi4>; + cs-gpios = <0>, <0>, <&gpio1 1 0>, <0>, <&gpio11 5 1>; + num-cs = <5>; + } + +In this case, CS2 will be the dummy chip select and no pin must be configured +with that function. CS0, CS1 and CS3 are just native chip selects and should be +used via pin functions. GPIO1.1 is used as a high active CS and GPIO11.5 a low +active one. + Limitations: * Only a basic SPI driver is implemented. This is mostly a driver limitation and not a hardware one. +* GPIO CS pins on i.MXRT10xx are not tested. The chip has a lot of errate so + they might not work. +* Switching from one mode (CPOL/CPHA) to another one can lead to single wrong + edges on the CLK line if GPIO CS pins are involved. Make sure to stuff a dummy + transfer with `SPI_NO_CS` set if you use multiple modes together with a GPIO + CS. Network Interface Driver ------------------------ @@ -225,13 +253,58 @@ the SDK. But please note that they are not tested and maybe won't work out of the box. Everything that works with interrupts most likely needs some special treatment. -Caveats -------- +The SDK files are imported to RTEMS from the NXP mcux-sdk git repository that +you can find here: https://github.com/nxp-mcuxpresso/mcux-sdk/ + +The directory structure has been preserved and all files are in a +`bsps/arm/imxrt/mcux-sdk` directory. All patches to the files are marked with +`#ifdef __rtems__` markers. + +The suggested method to import new or updated files is to apply all RTEMS +patches to the mcux-sdk repository, rebase them to the latest mcux-sdk release +and re-import the files. The new base revision should be mentioned in the commit +description to make future updates simpler. + +A import helper script (that might or might not work on newer releases of the +mcux-sdk) can be found here: +https://raw.githubusercontent.com/c-mauderer/nxp-mcux-sdk/d21c3e61eb8602b2cf8f45fed0afa50c6aee932f/export_to_RTEMS.py + +Clocks and SDRAM +---------------- The clock configuration support is quite rudimentary. The same is true for SDRAM. It mostly relies on the DCD and on a static clock configuration that is taken from the NXP SDK example projects. -The MPU settings are currently quite permissive. +If you need to adapt the DCD or clock config to support a different hardware, +you should generate these files using the NXP MCUXpresso Configuration Tools. +You can add the generated files to your application to overwrite the default +RTEMS ones or you can add them to RTEMS in a new BSP variant. + +As a special case, the imxrt1052 BSP will adapt it's PLL setting based on the +chip variant. The commercial variant of the i.MXRT1052 will use a core clock of +600MHz for the ARM core. The industrial variants only uses 528MHz. For other +chip or BSP variants, you should adapt the files generated with the MCUXpresso +Configuration Tools. + +Caveats +------- + +* The MPU settings are currently quite permissive. + +* There is no power management support. + +* On the i.MXRT1166, sleeping of the Cortex M7 can't be disabled even for + debugging purposes. That makes it hard for a debugger to access the + controller. To make debugging a bit easier, it's possible to overwrite the + idle thread with the following one in the application: + + .. code-block:: c -There is no power management support. + void * _CPU_Thread_Idle_body(uintptr_t ignored) + { + (void)ignored; + while (true) { + /* void */ + } + } diff --git a/user/bsps/arm/lpc24xx.rst b/user/bsps/arm/lpc24xx.rst index ecf1d84..f287dc8 100644 --- a/user/bsps/arm/lpc24xx.rst +++ b/user/bsps/arm/lpc24xx.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2017, 2019 embedded brains GmbH +.. Copyright (C) 2017, 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2017, 2019 Sebastian Huber lpc24xx (NXP LPC17XX/LPC24XX/LPC40XX) diff --git a/user/bsps/arm/realview-pbx-a9.rst b/user/bsps/arm/realview-pbx-a9.rst index 15d1fbf..bbe0269 100644 --- a/user/bsps/arm/realview-pbx-a9.rst +++ b/user/bsps/arm/realview-pbx-a9.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG realview-pbx-a9 =============== diff --git a/user/bsps/arm/stm32h7.rst b/user/bsps/arm/stm32h7.rst index 9f1f082..cdf4d43 100644 --- a/user/bsps/arm/stm32h7.rst +++ b/user/bsps/arm/stm32h7.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2022 Karel Gardas <karel@functional.vision> @@ -248,7 +248,7 @@ installed. Please go to its *bin* directory. E.g. $ cd plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin Now, you will need to edit provided *config.txt* file inside the -directory. Use your favorite editor. Open the file and scrolls +directory. Use your favorite editor. Open the file and scroll down to its end. You will see following comment: .. code-block:: none diff --git a/user/bsps/arm/xilinx-zynqmp-rpu.rst b/user/bsps/arm/xilinx-zynqmp-rpu.rst new file mode 100644 index 0000000..0dfb77e --- /dev/null +++ b/user/bsps/arm/xilinx-zynqmp-rpu.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2024 On-Line Applications Research Corporation (OAR) + +.. _BSP_arm_xilinx_zynqmp_rpu: + +Xilinx ZynqMP RPU +================= + +This BSP supports the Cortex-R5 processor on the Xilinx Zynq UltraScale+ MPSoC +platform. Basic hardware initialization is performed by the Cortex-R5 FSBL and +the BSP. This BSP supports the GICv2 interrupt controller available to the +Cortex-R5 subsystem. Since the Cortex-R5 subsystem only varies in speed, this +BSP should be functional across all chip variants as well as on Xilinx's QEMU +branch. SMP operation is not currently supported. + +Clock Driver +------------ + +The clock driver uses one of the available triple timer counters (TTCs) as the +timer interrupt source. + +Console Driver +-------------- + +The console driver supports the default Qemu emulated ARM PL011 PrimeCell UART +as well as the physical ARM PL011 PrimeCell UART in the ZynqMP hardware. + +Boot on ZynqMP Hardware +----------------------- + +On the ZynqMP RPU, RTEMS can be started by Cortes-R5 u-boot, Cortex-A53 u-boot, +via JTAG, or directly as part of BOOT.bin. For quick turnaround during testing, +it is recommended to use Cortex-A53 u-boot to avoid repeated BOOT.bin +generation since the provided Cortex-R5 u-boot is highly limited and has no +network or MMC/SD access. + +Note that if the RPU image is started by the Cortex-A53 u-boot, the program +sections located at ZYNQMP_RPU_RAM_INT_0_ORIGIN and ZYNQMP_RPU_RAM_INT_1_ORIGIN +must be manually relocated from DDR to TCM since the TCMs are not directly +available to the Cortex-A53 cores at their Cortex-R5 internal addresses. This +can be accomplished by disabling dcache in u-boot and using u-boot's "cp" +command. Once this is done, the program can be started at 0x0 by using u-boot's +"cpu" command to first disable core 4 and then release it in split mode. + +Hardware Boot Image Generation +------------------------------ + +When generating BOOT.bin from components, the BIF file should include at least +entries for the Cortex-R5 FSBL ([bootloader,destination_cpu=r5-0]) and the +Cortex-R5 application ([destination_cpu=r5-0]). The Cortex-R5 application should +be either a u-boot or RTEMS ELF binary. The Cortex-R5 u-boot binary can be +obtained by building it from Xilinx's u-boot repository. The Cortex-R5 FSBL can +be obtained setting up an appropriate platform project in Xilinx's current +development system. + +Boot on QEMU +------------ +The executable image is booted by Qemu in ELF format. + +Running Executables on QEMU +--------------------------- + +Xilinx's qemu-devicetrees repository must be used in conjunction with the Xilinx +QEMU available via RSB. Executables generated by this BSP can be run using the +following command: + +.. code-block:: shell + + qemu-system-aarch64 -no-reboot -nographic -M arm-generic-fdt -serial null \ + -serial mon:stdio -device loader,file=example.exe,cpu-num=4 \ + -device loader,addr=0xff5e023c,data=0x80088fde,data-len=4 \ + -device loader,addr=0xff9a0000,data=0x80000218,data-len=4 \ + -hw-dtb /xlnx-qemu-devtrees-path/LATEST/SINGLE_ARCH/board-zynqmp-zcu102.dtb \ + -m 4096 -display none + +Debugging Executables on QEMU +----------------------------- + +Debugging the RPU cores under QEMU presents unique challenges due to requiring +the AArch64 QEMU to emulate the entire processing subsystem. Debugging requires +a multi-arch GDB which can be created by adding "--enable-targets=all" to the +normal GDB configure line and then building as normal. + +To attach to the RPU core once QEMU is started with "-s -S", The following steps +are required: + +.. code-block:: shell + + aarch64-rtems6-gdb + (gdb) tar ext :1234 + (gdb) add-inferior + (gdb) inferior 2 + (gdb) file example.exe + (gdb) attach 2 diff --git a/user/bsps/arm/xilinx-zynqmp.rst b/user/bsps/arm/xilinx-zynqmp.rst index 9a605bb..fa60470 100644 --- a/user/bsps/arm/xilinx-zynqmp.rst +++ b/user/bsps/arm/xilinx-zynqmp.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG xilinx-zynqmp ============= diff --git a/user/bsps/bsps-aarch64.rst b/user/bsps/bsps-aarch64.rst index f3aa15c..f99843a 100644 --- a/user/bsps/bsps-aarch64.rst +++ b/user/bsps/bsps-aarch64.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG aarch64 (AArch64) ***************** diff --git a/user/bsps/bsps-arm.rst b/user/bsps/bsps-arm.rst index d9b5d01..bd335fa 100644 --- a/user/bsps/bsps-arm.rst +++ b/user/bsps/bsps-arm.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2017, 2019 embedded brains GmbH +.. Copyright (C) 2017, 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2017, 2019 Sebastian Huber arm (ARM) @@ -31,3 +31,4 @@ arm (ARM) arm/xen.rst arm/xilinx-zynq.rst arm/xilinx-zynqmp.rst + arm/xilinx-zynqmp-rpu.rst diff --git a/user/bsps/bsps-bfin.rst b/user/bsps/bsps-bfin.rst index db7f721..eeb426e 100644 --- a/user/bsps/bsps-bfin.rst +++ b/user/bsps/bsps-bfin.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG bfin (Blackfin) *************** diff --git a/user/bsps/bsps-i386.rst b/user/bsps/bsps-i386.rst index 0b273ee..81f5fd8 100644 --- a/user/bsps/bsps-i386.rst +++ b/user/bsps/bsps-i386.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG i386 **** diff --git a/user/bsps/bsps-lm32.rst b/user/bsps/bsps-lm32.rst index 2db5b12..98ffb91 100644 --- a/user/bsps/bsps-lm32.rst +++ b/user/bsps/bsps-lm32.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG lm32 (LatticeMicro32) ********************* diff --git a/user/bsps/bsps-m68k.rst b/user/bsps/bsps-m68k.rst index bdb516b..a820d96 100644 --- a/user/bsps/bsps-m68k.rst +++ b/user/bsps/bsps-m68k.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG m68k (Motorola 68000 / ColdFire) ******************************** diff --git a/user/bsps/bsps-microblaze.rst b/user/bsps/bsps-microblaze.rst index 32aad90..6fe4891 100644 --- a/user/bsps/bsps-microblaze.rst +++ b/user/bsps/bsps-microblaze.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG .. Copyright (C) 2022 On-Line Applications Research Corporation (OAR) microblaze (MicroBlaze) @@ -21,13 +21,21 @@ Clock Driver ------------ The clock driver supports the QEMU emulated Xilinx AXI Timer v2.0. It is -implemented as a simple downcounter. +implemented as a simple downcounter. If device tree support is enabled in the +build configuration, the clock driver will use the node that is compatible with +`xlnx,xps-timer-1.00.a` from the device tree to configure the clock. The +following device tree node properties are used to configure the clock driver: +``reg``, ``clock-frequency``, and ``interrupts``. Console Driver -------------- The console driver supports the QEMU emulated Xilinx AXI UART Lite v2.0. It is -initialized to a baud rate of 115200. +initialized to a baud rate of 115200. If device tree support is enabled in the +build configuration, the console driver will use the node that is compatible +with `xlnx,xps-uartlite-1.00.a` from the device tree to configure the console. +The following device tree node properties are used to configure the console +driver: ``reg``, ``status``, ``port-number``, and ``interrupts``. Network Driver -------------- @@ -61,6 +69,18 @@ to include it in the BSP build. BSP_MICROBLAZE_FPGA_DTB_HEADER_PATH = /path/to/my_dtb.c +QSPI NOR JFFS2 Driver +--------------------- + +The QSPI NOR JFFS2 driver supports the QEMU emulated n25q512a11 QSPI NOR flash +device. It is initialized to a page size of 256 bytes and a sector size of 64 +KiB. If device tree support is enabled in the build configuration, the QSPI NOR +JFFS2 driver will use the node that is compatible with `xlnx,xps-spi-2.00.a` +from the device tree to configure the QSPI NOR JFFS2 driver. The following +device tree node properties are used to configure the QSPI NOR JFFS2 driver: +``reg`` and ``interrupts``. + + Running Executables ------------------- @@ -114,12 +134,21 @@ Clock Driver ------------ The clock driver supports the Xilinx AXI Timer v2.0. It is implemented as a -simple downcounter. +simple downcounter. If device tree support is enabled in the +build configuration, the clock driver will use the node that is compatible with +`xlnx,xps-timer-1.00.a` from the device tree to configure the clock. The +following device tree node properties are used to configure the clock driver: +``reg``, ``clock-frequency``, and ``interrupts``. Console Driver -------------- -The console driver supports the Xilinx AXI UART Lite v2.0. +The console driver supports the Xilinx AXI UART Lite v2.0. It is initialized to +a baud rate of 115200. If device tree support is enabled in the build +configuration, the console driver will use the node that is compatible with +`xlnx,xps-uartlite-1.00.a` from the device tree to configure the console. The +following device tree node properties are used to configure the console driver: +``reg``, ``status``, ``port-number``, and ``interrupts``. Debugging --------- diff --git a/user/bsps/bsps-mips.rst b/user/bsps/bsps-mips.rst index 9f83811..f90732a 100644 --- a/user/bsps/bsps-mips.rst +++ b/user/bsps/bsps-mips.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG mips (MIPS) *********** diff --git a/user/bsps/bsps-moxie.rst b/user/bsps/bsps-moxie.rst index eab88cc..8548777 100644 --- a/user/bsps/bsps-moxie.rst +++ b/user/bsps/bsps-moxie.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG moxie ***** diff --git a/user/bsps/bsps-nios2.rst b/user/bsps/bsps-nios2.rst index ad21dd3..5280025 100644 --- a/user/bsps/bsps-nios2.rst +++ b/user/bsps/bsps-nios2.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG nios2 (Nios II) *************** diff --git a/user/bsps/bsps-or1k.rst b/user/bsps/bsps-or1k.rst index 6295c23..e7d9a10 100644 --- a/user/bsps/bsps-or1k.rst +++ b/user/bsps/bsps-or1k.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG or1k (OpenRISC 1000) ******************** diff --git a/user/bsps/bsps-powerpc.rst b/user/bsps/bsps-powerpc.rst index 3d1ce88..6b63936 100644 --- a/user/bsps/bsps-powerpc.rst +++ b/user/bsps/bsps-powerpc.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG powerpc (PowerPC) ***************** diff --git a/user/bsps/bsps-riscv.rst b/user/bsps/bsps-riscv.rst index 2ef8327..263796e 100644 --- a/user/bsps/bsps-riscv.rst +++ b/user/bsps/bsps-riscv.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG riscv (RISC-V) ************** @@ -8,7 +8,8 @@ riscv (RISC-V) riscv ===== -This BSP offers 15 variants: +**Each variant in this first group corresponds to a GCC multilib option with +different RISC-V standard extensions.** * rv32i @@ -26,29 +27,30 @@ This BSP offers 15 variants: * rv64imac -* rv64imac_medany - * rv64imafd -* rv64imafd_medany - * rv64imafdc -* rv64imafdc_medany +Each variant reflects an ISA with ABI and code model choice. All rv64 BSPs have +medany code model by default, while rv32 BSPs are medlow. The reason is that +RV32 medlow can access the entire 32-bit address space, while RV64 medlow can +only access addresses below 0x80000000. With RV64 medany, it's possible to +perform accesses above 0x80000000. The BSP must be started in machine mode. -* frdme310arty +The reference platforms for the rv* variants include the QEMU `virt` and +`spike` machines and the Spike RISC-V ISA simulator. -* mpfs64imafdc +**The BSP also provides the following variants for specific hardware targets:** -Each variant corresponds to a GCC multilib. A particular variant reflects an -ISA with ABI and code model choice. +* frdme310arty - The reference platform for this variant is the Arty FPGA board + with the SiFive Freedom E310 reference design. -The BSP must be started im machine mode. +* mpfs64imafdc - The reference platform for this variant is the Microchip + PolarFire SoC Icicle Kit. -The reference platform for this BSP is the QEMU `virt` machine. +* kendrytek210 - The reference platform for this variant is the Kendryte K210 + SoC on the Sipeed MAiX BiT or Maixduino board. -The reference platform for the mpfs64imafdc BSP variant is the Microchip -PolarFire SoC Icicle Kit. Build Configuration Options --------------------------- @@ -79,35 +81,41 @@ configuration INI file. The ``waf`` defaults can be used to inspect the values. The path to the header file containing the device tree blob. ``BSP_CONSOLE_BAUD`` - The default baud for console driver devices (default 115200). + The default baud for console driver devices (default is 115200). ``RISCV_MAXIMUM_EXTERNAL_INTERRUPTS`` The maximum number of external interrupts supported by the BSP (default - 64). + is 64). ``RISCV_ENABLE_HTIF_SUPPORT`` - Enables the HTIF support if defined to a non-zero value, otherwise it is - disabled (disabled by default). + Enable the Host/Target Interface (HTIF) support (enabled by default). ``RISCV_CONSOLE_MAX_NS16550_DEVICES`` - The maximum number of NS16550 devices supported by the console driver (2 - by default). + The maximum number of NS16550 devices supported by the console driver + (default is 2). + +``RISCV_ENABLE_SIFIVE_UART_SUPPORT`` + Enable the SiFive console UART (disabled by default). ``RISCV_RAM_REGION_BEGIN`` - The begin of the RAM region for linker command file (default is 0x70000000 - for 64-bit with -mcmodel=medlow and 0x80000000 for all other). + The begin of the RAM region for linker command file + (default is 0x80000000). ``RISCV_RAM_REGION_SIZE`` The size of the RAM region for linker command file (default 64MiB). ``RISCV_ENABLE_FRDME310ARTY_SUPPORT`` Enables support sifive Freedom E310 Arty board if defined to a non-zero - value,otherwise it is disabled (disabled by default) + value,otherwise it is disabled (disabled by default). ``RISCV_ENABLE_MPFS_SUPPORT`` Enables support Microchip PolarFire SoC if defined to a non-zero value, otherwise it is disabled (disabled by default). +``RISCV_ENABLE_KENDRYTE_K210_SUPPORT`` + Enables support for the Kendtryte K210 SoC if defined to a non-zero + value, otherwise it is disabled (disabled by default). + ``RISCV_BOOT_HARTID`` The boot hartid (processor number) of risc-v cpu by default 0. @@ -127,15 +135,15 @@ The clock driver uses the CLINT timer. Console Driver -------------- -The console driver supports devices compatible to +The console driver supports devices compatible to: * "ucb,htif0" (depending on the ``RISCV_ENABLE_HTIF_SUPPORT`` BSP option), -* "ns16550a" (see ``RISCV_CONSOLE_MAX_NS16550_DEVICES`` BSP option), and +* "ns16550a" (see ``RISCV_CONSOLE_MAX_NS16550_DEVICES`` BSP option), -* "ns16750" (see ``RISCV_CONSOLE_MAX_NS16550_DEVICES`` BSP option). +* "ns16750" (see ``RISCV_CONSOLE_MAX_NS16550_DEVICES`` BSP option), and -* "sifive,uart0" (see ``RISCV_ENABLE_FRDME310ARTY_SUPPORT`` BSP option). +* "sifive,uart0" (see ``RISCV_ENABLE_SIFIVE_UART_SUPPORT`` BSP option). They are initialized according to the device tree. The console driver does not configure the pins or peripheral clocks. The console device is selected @@ -144,28 +152,53 @@ according to the device tree "/chosen/stdout-path" property value. QEMU ---- -All of the BSP variants that start with rv can be run on QEMU's virt machine. -For instance, to run the ``rv64imafdc_medany`` BSP with the following -"config.ini" file: +All of the BSP variants that start with rv can be run on QEMU's virt +and spike machines. For instance, to run the ``rv64imafdc`` BSP with the +following "config.ini" file. .. code-block:: none - [riscv/rv64imafdc_medany] -Run the following QEMU command: + [riscv/rv64imafdc] + +Run the following QEMU command. .. code-block:: shell + $ qemu-system-riscv64 -M virt -nographic -bios $RTEMS_EXE + $ qemu-system-riscv64 -M spike -nographic -bios $RTEMS_EXE + +Spike +---- + +All of the BSP variants that start with rv can be run on Spike. For instance, +to run the ``rv64imafdc`` BSP with the following "config.ini" file. + +.. code-block:: none + + [riscv/rv64imafdc] + +Run the following Spike command. + +.. code-block:: shell + + $ spike --isa=rv64imafdc $RTEMS_EXE + +Unlike QEMU, Spike supports enabling/disabling a subset of the imafdc +extensions and has support for further RISC-V extensions as well. A fault will +be triggered if an executable built with rv64imafdc RISC-V's -march option run +on Spike with --isa=rv64i option. If no --isa option is specified, the default +is rv64imafdc. Microchip PolarFire SoC ----------------------- -The PolarFire SoC is the 4x 64-bit RISC-V U54 cores and a 64-bit RISC-V -E51 monitor core SoC from the Microchip. +The PolarFire SoC is the 4x 64-bit RISC-V U54 cores and a 64-bit RISC-V E51 +monitor core SoC from the Microchip. The ``mpfs64imafdc`` BSP variant supports the U54 cores but not the E51 because -the E51 monitor core is reserved for the first stage bootloader -(Hart Software Services). In order to boot from the first U54 core, -``RISCV_BOOT_HARTID`` is set to 1 by default. +the E51 monitor core is reserved for the first stage bootloader (Hart Software +Services). In order to boot from the first U54 core, ``RISCV_BOOT_HARTID`` is +set to 1 by default. The device tree blob is embedded in the ``mpfs64imafdc`` BSP variant by default with the ``BSP_DTB_IS_SUPPORTED`` enabled and the DTB header path @@ -188,14 +221,14 @@ Build RTEMS. .. code-block:: shell - $ ./waf configure --prefix=$HOME/rtems-start/rtems/6 + $ ./waf configure --prefix=$HOME/rtems-start/rtems/@rtems-ver-major@ $ ./waf Convert .exe to .elf file. .. code-block:: shell - $ riscv-rtems6-objcopy build/riscv/mpfs64imafdc/testsuites/smptests/smp01.exe build/riscv/mpfs64imafdc/testsuites/smptests/smp01.elf + $ riscv-rtems@rtems-ver-major@-objcopy build/riscv/mpfs64imafdc/testsuites/smptests/smp01.exe build/riscv/mpfs64imafdc/testsuites/smptests/smp01.elf Generate a payload for the `smp01.elf` using the `hss-payload-generator <https://github.com/polarfire-soc/hart-software-services/blob/master/tools/hss-payload-generator>`_. @@ -261,14 +294,135 @@ Serial terminal UART1 displays the SMP example messages *** END OF TEST SMP 1 *** +Kendryte K210 +------------- + +The Kendryte K210 SoC is a dual core 64-bit RISC-V SoC with an AI NPU, built in +SRAM, and a variety of peripherals. Currently just the console UART, interrupt +controller, and timer are supported. + +The device tree blob is embedded in the ``kendrytek210`` BSP variant by +default. When the kendrytek210 BSP variant is selected, +``BSP_DTB_IS_SUPPORTED`` enabled and the DTB header path +``BSP_DTB_HEADER_PATH`` is set to ``bsp/kendryte-k210-dtb.h``. + +The ``kendrytek210`` BSP variant has been tested on the following simulator and +boards: + +* Renode.io simulator using the Kendrtye k210 model +* Sipeed MAiX BiT board +* Sipeed Maixduino board +* Sipeed MAiX Dock board + +**Building the Kendryte K210 BSP** + +Configuration file ``config.ini``: + +.. code-block:: none + + [riscv/kendrytek210] + RTEMS_SMP = True + +Build RTEMS: + +.. code-block:: shell + + $ ./waf configure --prefix=$HOME/rtems-start/rtems/@rtems-ver-major@ + $ ./waf + +**Flash an executable to a supported K210 board** + +Binary images can be flashed to the Sipeed boards through the USB port using +the ``kflash.py`` utility available from the python pip utility. + +.. code-block:: shell + + $ riscv-rtems@rtems-ver-major@-objcopy -Obinary ticker.exe ticker.bin + $ kflash.py --uart /dev/ttyUSB0 ticker.bin + +After the image is flashed, the RTEMS image will automatically boot. It will +also run when the board is reset or powered through the USB cable. The USB port +provides the power and console UART. Plug the USB cable into a host PC and +bring up a terminal emulator at 115200 baud, 8 data bits, 1 stop bit, no +parity, and no flow control. On Linux the UART device is often +``/dev/ttyUSB0``. + +**Run a RTEMS application on the Renode.io simulator** + +RTEMS executables compiled with the kendrytek210 BSP can run on the renode.io +simulator using the built-in K210 model. The simulator currently supports the +console UART, interrupt controller, and timer. + +To install renode.io please refer to the `installation instructions <https://github.com/renode/renode#installation>`_. +Once installed, save the following file as `k210_rtems.resc`. + +.. code-block:: shell + + using sysbus + + $bin?=@ticker.exe + + mach create "K210" + + machine LoadPlatformDescription @platforms/cpus/kendryte_k210.repl + + showAnalyzer uart + + sysbus Tag <0x50440000 0x10000> "SYSCTL" + sysbus Tag <0x50440018 0x4> "pll_lock" 0xFFFFFFFF + sysbus Tag <0x5044000C 0x4> "pll1" + sysbus Tag <0x50440008 0x4> "pll0" + sysbus Tag <0x50440020 0x4> "clk_sel0" + sysbus Tag <0x50440028 0x4> "clk_en_cent" + sysbus Tag <0x5044002c 0x4> "clk_en_peri" + + macro reset + """ + sysbus LoadELF $bin + """ + runMacro $reset + +After saving the above file in in the same directory as your RTEMS ELF images, +start renode and load the `k210_rtems.resc` script to start the emulation. + +.. code-block:: shell + + (monitor) s @k210_rtems.resc + +You should see a renode UART window and the RTEMS ticker example output. If you +want to run a different RTEMS image, you can edit the file or enter the +following on the renode console. + +.. code-block:: shell + + (monitor) $bin=@smp08.exe + (monitor) s @k210_rtems.resc + +The above example will run the SMP08 example instead of ticker. + +**Generating the Device Tree Header** + +The kendrytek210 BSP uses a built in device tree blob. If additional peripheral +support is added to the BSP, the device tree may need to be updated. After +editing the device tree source, compile it to a device tree blob with the +following command: + +.. code-block:: shell + + $ dtc -O dtb -b 0 -o kendryte-k210.dtb kendryte-k210.dts + +The dtb file can then be converted to a C array using the rtems-bin2c tool. +The data for the device tree binary can then replace the existing device tree +binary data in the ``kendryte-k210-dtb.h`` header file. + noel ==== -This BSP supports the `NOEL-V <https://gaisler.com/noel-v>`_ systems from Cobham -Gaisler. The NOEL-V is a synthesizable VHDL model of a processor that -implements the RISC-V architecture. It is part of the open source -`GRLIB <https://gaisler.com/grlib>`_ IP Library. The following BSP -variants correspond to common NOEL-V configurations: +This BSP supports the `NOEL-V <https://gaisler.com/noel-v>`_ systems from +Cobham Gaisler. The NOEL-V is a synthesizable VHDL model of a processor that +implements the RISC-V architecture. It is part of the open source `GRLIB +<https://gaisler.com/grlib>`_ IP Library. The following BSP variants correspond +to common NOEL-V configurations: * noel32im @@ -280,20 +434,18 @@ variants correspond to common NOEL-V configurations: * noel64imafdc -The start of the memory is set to 0x0 to match a standard NOEL-V system, -but can be changed using the ``RISCV_RAM_REGION_BEGIN`` configuration -option. The size of the memory is taken from the information available -in the device tree. +The start of the memory is set to 0x0 to match a standard NOEL-V system, but +can be changed using the ``RISCV_RAM_REGION_BEGIN`` configuration option. The +size of the memory is taken from the information available in the device tree. Reference Designs ----------------- -The BSP has been tested with NOEL-V reference designs for -`Digilent Arty A7 <https://gaisler.com/noel-artya7>`_, -`Microchip PolarFire Splash Kit <https://gaisler.com/noel-pf>`_, -and `Xilinx KCU105 <https://gaisler.com/noel-xcku>`_. -See the accompanying quickstart guide for each reference design -to determine which BSP configuration to use. +The BSP has been tested with NOEL-V reference designs for `Digilent Arty A7 +<https://gaisler.com/noel-artya7>`_, `Microchip PolarFire Splash Kit +<https://gaisler.com/noel-pf>`_, and `Xilinx KCU105 +<https://gaisler.com/noel-xcku>`_. See the accompanying quickstart guide for +each reference design to determine which BSP configuration to use. Build Configuration Options --------------------------- diff --git a/user/bsps/bsps-sh.rst b/user/bsps/bsps-sh.rst index b147251..8c245c4 100644 --- a/user/bsps/bsps-sh.rst +++ b/user/bsps/bsps-sh.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG sh (SuperH) *********** diff --git a/user/bsps/bsps-sparc.rst b/user/bsps/bsps-sparc.rst index 3ffd079..325c7fa 100644 --- a/user/bsps/bsps-sparc.rst +++ b/user/bsps/bsps-sparc.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG .. Copyright (C) 2020 Chris Johns sparc (SPARC / LEON) diff --git a/user/bsps/bsps-sparc64.rst b/user/bsps/bsps-sparc64.rst index e7be4ea..7b598b7 100644 --- a/user/bsps/bsps-sparc64.rst +++ b/user/bsps/bsps-sparc64.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG sparc64 (SPARC V9) ****************** diff --git a/user/bsps/bsps-v850.rst b/user/bsps/bsps-v850.rst index 39973db..220ccc0 100644 --- a/user/bsps/bsps-v850.rst +++ b/user/bsps/bsps-v850.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG v850 (V850) *********** diff --git a/user/bsps/bsps-x86_64.rst b/user/bsps/bsps-x86_64.rst index a7f7326..38d84e4 100644 --- a/user/bsps/bsps-x86_64.rst +++ b/user/bsps/bsps-x86_64.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 .. Copyright (C) 2018 Amaan Cheval <amaan.cheval@gmail.com> -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG x86_64 ****** diff --git a/user/bsps/index.rst b/user/bsps/index.rst index bf590e0..5c1b3b7 100644 --- a/user/bsps/index.rst +++ b/user/bsps/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG .. _BSPs: diff --git a/user/exe/initialization.rst b/user/exe/initialization.rst index f4b5d7e..1100006 100644 --- a/user/exe/initialization.rst +++ b/user/exe/initialization.rst @@ -83,13 +83,12 @@ initialization is performed before multitasking is started. The RTEMS Tool ``rtems-exeinfo`` can provide some detail about the registered handlers. The following shows the initialization handlers for the Hello World -sample application in the RTEMS kernel's testsuite:: +sample application in the RTEMS kernel's testsuite: .. code-block:: none $ rtems-exeinfo --init arm-rtems@rtems-ver-major@/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe RTEMS Executable Info @rtems-ver-major@.5416cfa39dd6 - $ rtems-exeinfo --init arm-rtems@rtems-ver-major@/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe exe: arm-rtems@rtems-ver-major@/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe Compilation: diff --git a/user/exe/loader.rst b/user/exe/loader.rst index be2e78e..fdc54a8 100644 --- a/user/exe/loader.rst +++ b/user/exe/loader.rst @@ -844,6 +844,7 @@ The following architectures are supported: - Intel x86 (i386) - LM32 - M68K + - MicroBlaze - MIPS - Moxie - PowerPC diff --git a/user/hardware/architectures.rst b/user/hardware/architectures.rst index b604782..2e0cb9e 100644 --- a/user/hardware/architectures.rst +++ b/user/hardware/architectures.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org> diff --git a/user/hosts/macos.rst b/user/hosts/macos.rst index 78cef88..75ac5a3 100644 --- a/user/hosts/macos.rst +++ b/user/hosts/macos.rst @@ -7,18 +7,105 @@ Apple macOS =========== -Apple's macOS is fully supported. You need to download and install a recent -version of the Apple developer application Xcode. Xocde is available in the App -Store. Make sure you install the Command Line Tools add on available for -download within Xcode and once installed open a Terminal shell and enter the -command ``cc`` and accept the license agreement. +Apple's macOS is supported. You need to download and install a recent +version of the Apple developer application Xcode. Xcode is available +in the App Store. Make sure you install the Command Line Tools add on +available for download within Xcode and once installed open a Terminal +shell and enter the command ``cc`` and accept the license agreement. -The normal prefix when working on macOS as a user is under your home directory. -Prefixes of :file:`$HOME/development/rtems` or :file:`$HOME/rtems` are -suitable. +The normal prefix when working on macOS as a user is under your home +directory. Prefixes of :file:`$HOME/development/rtems` or +:file:`$HOME/rtems` are suitable. :ref:`QuickStartPrefixes` details using Prefixes to manage the installation. +Homebrew and Macports should work but are not tested by the project as +they are rolling releases making it difficult to reproduce any +problems there may be. We recommend reaching out to those projects for +support. + +Intel and Apple silicon is supported. + +Python +~~~~~~ + +Building GDB requires the installation of Python's development +libraries. Building GDB includes the Python runtime header +``Python.h`` and linking to the Python runtime libraries. The RSB +detects a valid header and libraries before starting a GDB +build. + +It is recommended you run the RSB in a Python virtual environment. A +virtual environment manages paths for you, provides a ``python`` +executable mapped to the version the virtual environment is built with +and a command to find the appropiate runtime header and library files +GDB needs. Virtual environments make it easier to update Python to a +newer version if this is needed. + +Apple has removed support for Python's development libraries from +recent versions of MacOS as users can manage Python using the +installer packages provided by the Python project. + +To install: + +#. Download a Python installer for MacOS from https://www.python.org/. + +#. Run the installer and install Python. + +#. Open a terminal and update your shell profile using the command + Python provides. For Python 3.12 the command is: + + .. code-block:: shell + + /Applications/Python\ 3.12/Update\ Shell\ Profile.command + + Check with: + + .. code-block:: shell + + % type python3.12 + python3.12 is /Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12 + +#. Create a virtual environment: + + .. code-block:: shell + + mkdir $HOME/development/rtems + cd $HOME/development/rtems + python3.12 -m venv py3.12 + + Activate the virtual environment: + + .. code-block:: shell + + . $HOME/development/rtems/py3.12/bin/activate + + You are now ready to the build the tools within the virtual + environment. + +.. _Sonoma: + +Sonoma +~~~~~~ + +The RSB is supported on Sonoma and Applie silicon. + +.. _Ventura: + +Ventura +~~~~~~~ + +The RSB is supported on Ventura and Intel silicon. + +.. _Monterey: + +Monterey +~~~~~~~~ + +The RSB is supported on Ventura and Intel silicon. + +.. _Catalina: + Catalina ~~~~~~~~ @@ -30,6 +117,8 @@ also Due to the deprecated Python 2.7 support, we recommend to install and use the `latest Python 3 release from python.org <https://www.python.org/downloads/mac-osx/>`_. +.. _Sierra: + Sierra ~~~~~~ diff --git a/user/hosts/posix.rst b/user/hosts/posix.rst index d263247..d79e183 100644 --- a/user/hosts/posix.rst +++ b/user/hosts/posix.rst @@ -137,16 +137,16 @@ prefix under your home directory as recommended and end up on the SD card. Ubuntu ~~~~~~ -The latest version is Ubuntu 20.04.3 LTS 64-bit. This section also includes +The latest version is Ubuntu 22.04 LTS 64-bit. This section also includes Xubuntu. A minimal installation was used and the following packages installed: .. code-block:: none - $ sudo apt-get build-dep build-essential gcc-defaults g++ gdb unzip \ - pax bison flex texinfo python3-dev libpython2-dev libncurses5-dev \ - zlib1g-dev + $ sudo apt install build-essential g++ gdb unzip pax bison flex texinfo \ + python3-dev python-is-python3 libpython2-dev libncurses5-dev zlib1g-dev \ + ninja-build pkg-config -Note that in previous versions of Ubuntu, the package libpython2-dev was +Note that in older versions of Ubuntu, the package libpython2-dev was python2.7-dev. The name of packages changes over time. You need the package with Python development libraries for C/C++ programs. The following is needed for recent versions: diff --git a/user/index.rst b/user/index.rst index 38ade81..5b7f3ce 100644 --- a/user/index.rst +++ b/user/index.rst @@ -18,7 +18,7 @@ RTEMS User Manual (|version|). | |copy| 2018 Shashvat Jain | |copy| 2018 Vidushi Vashishth | |copy| 2017 Tanu Hari Dixit - | |copy| 2016, 2019 embedded brains GmbH + | |copy| 2016, 2019 embedded brains GmbH & Co. KG | |copy| 2016, 2019 Sebastian Huber | |copy| 2012, 2022 Chris Johns | |copy| 2012, 2020 Gedare Bloom diff --git a/user/migration/v4_11-to-v5.rst b/user/migration/v4_11-to-v5.rst index bde84c2..2dc97ec 100644 --- a/user/migration/v4_11-to-v5.rst +++ b/user/migration/v4_11-to-v5.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 .. Copyright (C) 2020 Chris Johns -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. _Migration_4_11_to_5: diff --git a/user/migration/v5-to-v6.rst b/user/migration/v5-to-v6.rst index 079f640..98c7366 100644 --- a/user/migration/v5-to-v6.rst +++ b/user/migration/v5-to-v6.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) +.. Copyright (C) 2020 embedded brains GmbH & Co. KG .. _Migration_5_to_6: diff --git a/user/start/app.rst b/user/start/app.rst index ce9a44d..0599305 100644 --- a/user/start/app.rst +++ b/user/start/app.rst @@ -209,7 +209,7 @@ Run the executable: .. code-block:: none - $HOME/quick-start/rtems/@rtems-ver-major@/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems@rtems-ver-major@-erc32/hello.exe + rtems-run --rtems-bsps=erc32-sis build/sparc-rtems@rtems-ver-major@-erc32/hello.exe The output will be something close to: diff --git a/user/start/bsp-build.rst b/user/start/bsp-build.rst index 8401d71..962cd43 100644 --- a/user/start/bsp-build.rst +++ b/user/start/bsp-build.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. _QuickStartBSPBuild: @@ -45,7 +45,7 @@ To build the BSP with all the tests run this command: cd $HOME/quick-start/src/rsb/rtems ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \ - --target=sparc-rtems@rtems-ver-major@ --with-rtems-bsp=erc32 --with-rtems-tests=yes @rtems-ver-major@/rtems-kernel + --target=sparc-rtems@rtems-ver-major@ --with-rtems-bsp=sparc/erc32 --with-rtems-tests=yes @rtems-ver-major@/rtems-kernel This command should output something like: @@ -99,16 +99,9 @@ If you have built a BSP with the RSB, you can move on to Manual BSP Build ---------------- -We manually build the BSP in four steps. The first step is to create a build -directory. It must be separate from the RTEMS source directory. We use -:file:`$HOME/quick-start/build/b-erc32`. - -.. code-block:: none - - mkdir -p $HOME/quick-start/build/b-erc32 - -The second step is to set your path. Prepend the RTEMS tool suite binary -directory to your ``$PATH`` throughout the remaining steps. Run the command: +We manually build the BSP in four steps. The first step is to set your path. +Prepend the RTEMS tool suite binary directory to your ``$PATH`` throughout the +remaining steps. Run the command: .. code-block:: none @@ -133,7 +126,7 @@ has not been correctly set. Check the contents of the path file cannot be found return to :ref:`QuickStartTools` and install the tools again. -The first step is to configure the BSP. There are various BSP build +The second step is to configure the BSP. There are various BSP build configuration options available. Some options are BSP-specific. Each section in the INI-style configuration file ``config.ini`` instructs the build system to build a particular BSP variant (`sparc/erc32` in our case). We enable the build @@ -179,7 +172,7 @@ by ``$BASE``. Checking for program 'xz' : $BASE/anaconda3/bin/xz 'configure' finished successfully (0.414s) -Building the BSP is the second step. +Building the BSP is the third step. .. code-block:: none diff --git a/user/start/bsp-test.rst b/user/start/bsp-test.rst index 575f19e..a354663 100644 --- a/user/start/bsp-test.rst +++ b/user/start/bsp-test.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. _QuickStartBSPTest: diff --git a/user/start/prefixes.rst b/user/start/prefixes.rst index 826ce85..aee7440 100644 --- a/user/start/prefixes.rst +++ b/user/start/prefixes.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org> diff --git a/user/start/preparation.rst b/user/start/preparation.rst index 3670885..4bfc214 100644 --- a/user/start/preparation.rst +++ b/user/start/preparation.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 .. Copyright (C) 2018 Shashvat Jain -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. Copyright (C) 2020 Chris Johns .. Copyright (C) 2020 Gedare Bloom diff --git a/user/start/sources.rst b/user/start/sources.rst index 6585e3d..a6e66df 100644 --- a/user/start/sources.rst +++ b/user/start/sources.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. Copyright (C) 2020 Chris Johns diff --git a/user/start/tools.rst b/user/start/tools.rst index 2706f71..3656867 100644 --- a/user/start/tools.rst +++ b/user/start/tools.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. Copyright (C) 2020 Chris Johns .. Copyright (C) 2020 Utkarsh Rai diff --git a/user/support/bugs.rst b/user/support/bugs.rst index d75c9b4..02788d9 100644 --- a/user/support/bugs.rst +++ b/user/support/bugs.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. Copyright (C) 2015 Chris Johns <chrisj@rtems.org> .. Copyright (C) 2012 Gedare Bloom diff --git a/user/support/contrib.rst b/user/support/contrib.rst index c42d41b..5d61b46 100644 --- a/user/support/contrib.rst +++ b/user/support/contrib.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. Copyright (C) 2018 Joel Sherill .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org> diff --git a/user/support/index.rst b/user/support/index.rst index 6147c06..5320488 100644 --- a/user/support/index.rst +++ b/user/support/index.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. index:: support diff --git a/user/support/support-project.rst b/user/support/support-project.rst index b782029..4aef902 100644 --- a/user/support/support-project.rst +++ b/user/support/support-project.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH +.. Copyright (C) 2019 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. Copyright (C) 2016 Chris Johns <chrisj@rtems.org> diff --git a/user/tracing/captureengine.rst b/user/tracing/captureengine.rst index a8bca53..137c555 100644 --- a/user/tracing/captureengine.rst +++ b/user/tracing/captureengine.rst @@ -14,22 +14,22 @@ runtime and does not require RTEMS or your application to be rebuilt in order to use it. The Capture Engine's sample testcase for the `sparc/erc32` is available in -build directory created when building RTEMS in the path -file: `sparc-rtems5/c/erc32/testsuites/samples`. In order to access the capture -testcase perform the following set of operations inside the RTEMS build -directory. +build directory created when building RTEMS in the path file: +`sparc-rtems@rtems-ver-major@/c/erc32/testsuites/samples`. In order to access +the capture testcase perform the following set of operations inside the RTEMS +build directory. .. code-block:: none - $ cd /sparc-rtems5/c/erc32/testsuites/samples - $ sparc-rtems5-run ./capture.exe + $ cd /sparc-rtems@rtems-ver-major@/c/erc32/testsuites/samples + $ sparc-rtems@rtems-ver-major@-run ./capture.exe *** BEGIN OF TEST CAPTURE ENGINE *** - *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 + *** TEST VERSION: @rtems-ver-major@.@rtems-ver-minor@.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 *** TEST STATE: USER_INPUT *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API - *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0) + *** TEST TOOLS: 7.3.0 20180125 (RTEMS @rtems-ver-major@, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0) Press any key to start capture engine (20s remaining) Press any key to start capture engine (19s remaining) Press any key to start capture engine (18s remaining) @@ -101,10 +101,10 @@ number of context switches between tasks we are not interested in. .. code-block:: none *** BEGIN OF TEST CAPTURE ENGINE *** - *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 + *** TEST VERSION: @rtems-ver-major@.@rtems-ver-minor@.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 *** TEST STATE: USER_INPUT *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API - *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0) + *** TEST TOOLS: 7.3.0 20180125 (RTEMS @rtems-ver-major@, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0) Press any key to start capture engine (20s remaining) Press any key to start capture engine (19s remaining) Press any key to start capture engine (18s remaining) diff --git a/user/tracing/eventrecording.rst b/user/tracing/eventrecording.rst index 7130658..c011000 100644 --- a/user/tracing/eventrecording.rst +++ b/user/tracing/eventrecording.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019, 2020 embedded brains GmbH +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. _EventRecording: @@ -48,8 +48,11 @@ The application enables the event recording support via the configuration option :c:macro:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS`. The configuration option :c:macro:`CONFIGURE_RECORD_EXTENSIONS_ENABLED` enables the generation of thread create, start, restart, delete, switch, begin, exitted and terminate -events. Dumps of the event records in a fatal error handler can be enabled by -the mutually exclusive :c:macro:`CONFIGURE_RECORD_FATAL_DUMP_BASE64` and +events. The configuration option +:c:macro:`CONFIGURE_RECORD_INTERRUPTS_ENABLED` enables the generation of +interrupt entry and exit events. Dumps of the event records in a fatal error +handler can be enabled by the mutually exclusive +:c:macro:`CONFIGURE_RECORD_FATAL_DUMP_BASE64` and :c:macro:`CONFIGURE_RECORD_FATAL_DUMP_BASE64_ZLIB` configuration options. Custom events can be recorded for example with the @@ -98,64 +101,6 @@ instrumented functions: ); } -To generate interrupt handler entry/exit events, the following patch can be -used: - -.. code-block:: diff - - diff --git a/bsps/arm/shared/clock/clock-armv7m.c b/bsps/arm/shared/clock/clock-armv7m.c - index 255de1ca42..0d37c63ac6 100644 - --- a/bsps/arm/shared/clock/clock-armv7m.c - +++ b/bsps/arm/shared/clock/clock-armv7m.c - @@ -29,6 +29,7 @@ - #include <bsp/clock-armv7m.h> - - #include <rtems.h> - +#include <rtems/record.h> - #include <rtems/sysinit.h> - - #ifdef ARM_MULTILIB_ARCH_V7M - @@ -45,9 +46,11 @@ static uint32_t _ARMV7M_TC_get_timecount(struct timecounter *base) - - void _ARMV7M_Clock_handler(void) - { - + rtems_record_produce(RTEMS_RECORD_INTERRUPT_ENTRY, ARMV7M_VECTOR_SYSTICK); - _ARMV7M_Interrupt_service_enter(); - Clock_isr(NULL); - _ARMV7M_Interrupt_service_leave(); - + rtems_record_produce(RTEMS_RECORD_INTERRUPT_EXIT, ARMV7M_VECTOR_SYSTICK); - } - - static void _ARMV7M_Clock_handler_install(void) - diff --git a/bsps/include/bsp/irq-generic.h b/bsps/include/bsp/irq-generic.h - index 31835d07ba..2ab2f78b65 100644 - --- a/bsps/include/bsp/irq-generic.h - +++ b/bsps/include/bsp/irq-generic.h - @@ -30,6 +30,7 @@ - #include <stdbool.h> - - #include <rtems/irq-extension.h> - +#include <rtems/record.h> - #include <rtems/score/assert.h> - - #ifdef RTEMS_SMP - @@ -258,6 +259,7 @@ void bsp_interrupt_vector_disable(rtems_vector_number vector); - */ - static inline void bsp_interrupt_handler_dispatch(rtems_vector_number vector) - { - + rtems_record_produce(RTEMS_RECORD_INTERRUPT_ENTRY, vector); - if (bsp_interrupt_is_valid_vector(vector)) { - const bsp_interrupt_handler_entry *e = - &bsp_interrupt_handler_table [bsp_interrupt_handler_index(vector)]; - @@ -276,6 +278,7 @@ static inline void bsp_interrupt_handler_dispatch(rtems_vector_number vector) - } else { - bsp_interrupt_handler_default(vector); - } - + rtems_record_produce(RTEMS_RECORD_INTERRUPT_EXIT, vector); - } - - /** - Transfer of Event Records to the Host Computer ---------------------------------------------- diff --git a/user/tracing/examples.rst b/user/tracing/examples.rst index 2b673d4..ed0c722 100644 --- a/user/tracing/examples.rst +++ b/user/tracing/examples.rst @@ -48,19 +48,19 @@ BSP is configured with the following command - .. code-block:: none - ../rtems/configure --target=sparc-rtems5 --prefix=/development/rtems/5 \ + ../rtems/configure --target=sparc-rtems@rtems-ver-major@ --prefix=/development/rtems/5 \ --enable-networking --enable-tests --enable-rtemsbsp=erc32 --enable-cxx The next two commands are used to link the fileio executable.The `-B` option signifies the use of the complete path to the required directory or file. Write -the full path instead of the path file: `sparc-rtems5/erc32/lib/` in the +the full path instead of the path file: `sparc-rtems@rtems-ver-major@/erc32/lib/` in the following commands according to your installation. Also confirm the path of the fileio's executable and object files in the last line of the command according to your installation. .. code-block:: none - sparc-rtems5-gcc -Bsparc-rtems5/erc32/lib/ \ + sparc-rtems@rtems-ver-major@-gcc -Bsparc-rtems@rtems-ver-major@/erc32/lib/ \ -qrtems -mcpu=cypress -O2 -g -ffunction-sections \ -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration \ -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress \ @@ -97,10 +97,10 @@ The output from the above commands will be as follows: .. code-block:: none *** BEGIN OF TEST FILE I/O *** - *** TEST VERSION: 5.0.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 + *** TEST VERSION: @rtems-ver-major@.@rtems-ver-minor@.0.de9b7d712bf5da6593386fd4fbca0d5f8b8431d8 *** TEST STATE: USER_INPUT *** TEST BUILD: RTEMS_NETWORKING RTEMS_POSIX_API - *** TEST TOOLS: 7.3.0 20180125 (RTEMS 5, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0) + *** TEST TOOLS: 7.3.0 20180125 (RTEMS @rtems-ver-major@, RSB a3a6c34c150a357e57769a26a460c475e188438f, Newlib 3.0.0) Press any key to start file I/O sample (20s remaining) Press any key to start file I/O sample (19s remaining) Press any key to start file I/O sample (18s remaining) @@ -128,7 +128,7 @@ The output from the above commands will be as follows: starting shell ========================= - Welcome to rtems-5.0.0 (SPARC/w/FPU/erc32) + Welcome to rtems-@rtems-ver-major@.@rtems-ver-minor@.0 (SPARC/w/FPU/erc32) COPYRIGHT (c) 1989-2008. On-Line Applications Research Corporation (OAR). |