diff options
Diffstat (limited to 'user')
90 files changed, 6546 insertions, 1479 deletions
diff --git a/user/bld/index.rst b/user/bld/index.rst new file mode 100644 index 0000000..dbad167 --- /dev/null +++ b/user/bld/index.rst @@ -0,0 +1,372 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG +.. Copyright (C) 2019, 2020 Sebastian Huber + +.. index:: BSP build system +.. index:: build system + +.. _BSPBuildSystem: + +BSP Build System +**************** + +The purpose of the build system is to produce and install artefacts from the +RTEMS sources such as static libraries, start files, linker command files, +configuration header files, header files, test programs, package description +files, and third-party build system support files for a specific BSP in a user +controlled configuration. + +Overview +======== + +The build system consists of three components which are all included in the +RTEMS sources + +* the `waf <https://waf.io/>`_ meta build system command line tool, + +* a `wscript <https://git.rtems.org/rtems/tree/wscript>`_ file used by ``waf``, + and + +* a + `set of build specification items <https://git.rtems.org/rtems/tree/spec/build>`_ + maintained by a text editor just like other source files. + +The build system is controlled by the user through + +* commands passed to the ``waf`` command line tool, + +* command line options passed to ``waf``, and + +* configuration files (e.g. ``config.ini``) used by ``wscript`` through ``waf`` + invocations. + +Configurable things which are subject to a local installation variant such as +paths to tools are intended to be passed as command line options to the ``waf`` +command line tool. Which BSPs are built and how they are configured by means of +options is placed in configuration files (e.g. ``config.ini``). The +configuration files may reside anywhere in the file system and the goal is to +have it under version control by the user. + +Work Flow +========= + +There are five steps necessary to build and install one or more BSPs. + +1. Select which BSPs you want to build. See also :ref:`BSPs` and + ``./waf bsplist``. + +2. Write a BSP build configuration file (e.g. ``config.ini``) which determines + which BSPs are built and how they are configured. + +3. Run the ``./waf configure`` command to generate the build + environment. + +4. Build the BSP artefacts with ``./waf``. The build uses the build environment + created by ``./waf configure``. The BSP build configuration file (e.g. + ``config.ini``) is no longer used and may be deleted. + +5. Install the BSP artefacts with ``./waf install``. + +Commands +======== + +The build system is controlled by invocations of the ``./waf`` command line +tool instead of the well known ``make``. Since waf is written in Python, a +standard Python 2.7 or 3 installation without third-party packages is required +to run it. The ``./waf`` command line tool must be invoked in the RTEMS source +tree top-level directory. + +Some commands accept the ``--rtems-specs`` command line option. This option +specifies paths to build specification items. It is an advanced option and +there is normally no need to use it. It may be used to customize the build at +the level of the build specification. For more information see the +`Build System` chapter of the +`RTEMS Software Engineering <https://docs.rtems.org/branches/master/eng/build-system.rst>`_ +guide. + +Help +---- + +Use ``./waf --help`` to get a list of commands and options. + +BSP List +-------- + +The BSP list command ``./waf bsplist`` loads the build specification items and +generates a list of base BSPs from it. The list is sorted by architecture and +base BSP name. Which base BSPs are listed can be controlled by the +``--rtems-bsps`` command line option. It expects a comma-separated list of +`Python regular expressions <https://docs.python.org/3/library/re.html#regular-expression-syntax>`_ +which select the desired BSP variants. The path to the build specification +items can be specified by the ``--rtems-specs`` command line option. + +.. code-block:: none + + $ ./waf bsplist --rtems-bsps=sparc/ + sparc/at697f + sparc/erc32 + sparc/gr712rc + sparc/gr740 + sparc/leon2 + sparc/leon3 + sparc/ut699 + sparc/ut700 + +.. code-block:: none + + $ ./waf bsplist --rtems-bsps='/leon,/rv64imac$' + riscv/rv64imac + sparc/leon2 + sparc/leon3 + +BSP Defaults +------------ + +The BSP defaults command ``./waf bspdefaults`` loads the build specification +items and generates a list options with default values for each base BSP from +it. The list is sorted by architecture and base BSP name. Which base BSPs are +listed can be controlled by the ``--rtems-bsps`` command line option. Default +values may depend on the selected compiler. The compiler can be specified by +the ``--rtems-compiler`` command line option. The path to the build +specification items can be specified by the ``--rtems-specs`` command line +option. + +.. code-block:: none + + $ ./waf bspdefaults --rtems-bsps=gr712rc --rtems-compiler=gcc | grep ABI_FLAGS + ABI_FLAGS = -mcpu=leon3 -mfix-gr712rc + +.. code-block:: none + + $ ./waf bspdefaults --rtems-bsps=gr712rc --rtems-compiler=clang | grep ABI_FLAGS + ABI_FLAGS = -mcpu=gr712rc + +Configure +--------- + +The configure command ``./waf configure`` loads the BSP build configuration +files and the build specification items and configures the build environment +accordingly. The configuration files can be specified by the ``--rtems-config`` +command line option. It expects a comma-separated list of paths to the +configuration files. By default, the file ``config.ini`` is used. The paths to +RTEMS tools can be specified by the ``--rtems-tools`` command line option. It +expects a comma-separated list of prefix paths to tools, e.g. compiler, linker, +etc. By default, the installation prefix is used for the RTEMS tools. Tools +are searched in the prefix path and also in a ``bin`` subdirectory of the prefix +path. The path to the build specification items can be specified by the +``--rtems-specs`` command line option. + +Build, Clean, and Install +------------------------- + +The commands ``./waf``, ``./waf clean``, and ``./waf install`` load the build +specification items according to the specification paths stored in the build +environment. The BSP build configuration files (e.g. ``config.ini``) used by +the ``./waf configure`` command to create the build environment are not longer +used and may be deleted. The build commands perform a dependency tracking and +re-build artefacts if input sources changed. Input sources are also the build +specification. + +Configuration +============= + +The BSP build configuration is done via INI-style configuration files. The +configuration files are consumed by the ``./waf configure`` command. By +default, the file ``config.ini`` is used. You can specify other configuration +files with the ``--rtems-config`` command line option. The configuration files +consist of sections and options (key-value pairs). + +To build a particular BSP, you have to create a section with the BSP variant +name. + +.. code-block:: ini + + [sparc/erc32] + +This one line configuration file is sufficient to build the base BSP +`sparc/erc32` with default values for all options. The base BSPs are determined +by the build specification. The ``./waf bsplist`` command lists all base BSPs. +You can create your own BSP names. However, in this case you have to inherit +from a base BSP. The inheritance works only within an architecture, e.g. a +`riscv` BSP cannot inherit options from an `arm` BSP. + +.. code-block:: ini + + [sparc/foobar] + INHERIT = erc32 + +The inheritance works recursively and must end up in a base BSP. + +.. code-block:: ini + + [sparc/foo] + INHERIT = erc32 + + [sparc/bar] + INHERIT = foo + +A child BSP variant inherits all options from the parent BSP variant. The child +BSP can override the inherited options. + +You can determine the compiler used to build the BSP with the ``COMPILER`` +option. + +.. code-block:: ini + + [sparc/gr740_gcc] + INHERIT = gr740 + COMPILER = gcc + + [sparc/gr740_clang] + INHERIT = gr740 + COMPILER = clang + +Use the ``./waf bspdefaults`` command to get a list of all configuration +options with default values. + +.. code-block:: none + + $ ./waf bspdefaults --rtems-bsps=sparc/erc32 + [sparc/erc32] + # Flags passed to the library archiver + ARFLAGS = crD + # Warning flags passed to the C compiler + CC_WARNING_FLAGS = -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs + # Warning flags passed to the C++ compiler + CXX_WARNING_FLAGS = + # Flags passed to the linker (GNU ld) + LDFLAGS = -Wl,--gc-sections + # Enable the Ada support + __RTEMS_ADA__ = False + # Enable the RTEMS internal debug support + RTEMS_DEBUG = False + ... + # Install the legacy application Makefile framework. + INSTALL_LEGACY_MAKEFILES = True + +It is not recommended to blindly add all the options obtained through the +``./waf bspdefaults`` command to custom configuration files. The specified +options should be kept at the necessary minimum to get the desired build. + +Some projects may still want to specify all options in a configuration file to +be independent of changes in the base BSP. You can review differences between +the user and base BSP values with the ``diff`` command. + +.. code-block:: none + + $ ./waf bspdefaults --rtems-bsps=sparc/erc32 > config.ini + $ sed -i 's/BUILD_TESTS = False/BUILD_TESTS = True/' config.ini + $ ./waf bspdefaults --rtems-bsps=sparc/erc32 | diff -u - config.ini + --- config.ini 2019-12-04 08:21:36.049335872 +0100 + +++ - 2019-12-04 08:21:41.187432405 +0100 + @@ -31,7 +31,7 @@ + # Build the Ada test programs (may be also enabled by BUILD_TESTS) + BUILD_ADATESTS = False + # Build the test programs + -BUILD_TESTS = False + +BUILD_TESTS = True + # Build the benchmark programs (may be also enabled by BUILD_TESTS) + BUILD_BENCHMARKS = False + # Build the file system test programs (may be also enabled by + +There is a special section ``DEFAULT`` which can be used to specify default +values for all other sections of the configuration file. In the following +example configuration file, building of the tests is enabled for the +`sparc/erc32` and the `riscv/griscv` BSP. + +.. code-block:: ini + + [DEFAULT] + BUILD_TESTS = True + + [sparc/erc32] + + [riscv/griscv] + +Migration from Autoconf/Automake +================================ + +The Autoconf/Automake based build system used a ``configure`` command to +configure a single target architecture and one or more BSPs. The ``make`` +command was used to build it. The ``configure`` command is replaced by a +``./waf configure`` invocation with configuration file. The ``make`` command +is replaced by ``./waf`` and ``make install`` is replaced by ``./waf install``. + +Here are some hints for how a configure command line can be converted to +options in the configuration file of the ``waf`` based build system. BSP +options given at the configure command line have to be added to the BSP section +in the configuration file. + +``--target=${arch}-rtems6`` ``--enable-rtembsp=${bsp}`` + To build a BSP add ``[${arch}/${bsp}]`` to the configuration file. + +``--enable-ada`` | ``--disable-ada`` + Set ``__RTEMS_ADA__`` to ``True`` or ``False`` in the BSP section of + the configuration file. + +``--enable-multiprocessing`` | ``--disable-multiprocessing`` + Set ``RTEMS_MULTIPROCESSING`` to ``True`` or ``False`` in the BSP + section of the configuration file. + +``--enable-paravirt`` | ``--disable-paravirt`` + Set ``RTEMS_PARAVIRT`` to ``True`` or ``False`` in the BSP section of + the configuration file. + +``--enable-profiling`` | ``--disable-profiling`` + Set ``RTEMS_PROFILING`` to ``True`` or ``False`` in the BSP section of + the configuration file. + +``--enable-posix`` | ``--disable-posix`` + Set ``RTEMS_POSIX_API`` to ``True`` or ``False`` in the BSP section of + the configuration file. + +``--enable-rtems-debug`` | ``--disable-rtems-debug`` + Set ``RTEMS_DEBUG`` to ``True`` or ``False`` in the BSP section of the + configuration file. + +``--enable-smp`` | ``--disable-smp`` + Set ``RTEMS_SMP`` to ``True`` or ``False`` in the BSP section of the + configuration file. + +``--enable-tests`` | ``--disable-tests`` + Set ``BUILD_TESTS`` to ``True`` or ``False`` in the BSP section of the + configuration file. + +``--enable-tests=samples`` + Set ``BUILD_SAMPLES`` to ``True`` or ``False`` in the BSP section of + the configuration file. + +Please have a look at the following example configuration file. + +.. code-block:: ini + + # --target=sparc-rtems6 --enable-rtemsbsp=erc32 + [sparc/erc32] + + # --enable-ada + __RTEMS_ADA__ = True + + # --enable-multiprocessing + RTEMS_MULTIPROCESSING = False + + # --disable-paravirt + RTEMS_PARAVIRT = False + + # --enable-profiling + RTEMS_PROFILING = True + + # --disable-posix + RTEMS_POSIX_API = False + + # --enable-rtems-debug + RTEMS_DEBUG = True + + # --disable-smp + RTEMS_SMP = False + + # --enable-tests + BUILD_TESTS = True + + # BSP_POWER_DOWN_AT_FATAL_HALT= + BSP_POWER_DOWN_AT_FATAL_HALT = False diff --git a/user/bsps/aarch64/a53.rst b/user/bsps/aarch64/a53.rst new file mode 100644 index 0000000..9d8e1ce --- /dev/null +++ b/user/bsps/aarch64/a53.rst @@ -0,0 +1,37 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 On-Line Applications Research Corporation (OAR) + +.. _BSP_aarch64_qemu_a53_ilp32: +.. _BSP_aarch64_qemu_a53_lp64: + +Qemu A53 +======== + +This BSP supports two variants, `qemu_a53_ilp32` and `qemu_a53_lp64`. The basic +hardware initialization is performed by the BSP. These BSPs support the GICv3 +interrupt controller. + +Boot via ELF +------------ +The executable image is booted by Qemu in ELF format. + +Clock Driver +------------ + +The clock driver uses the `ARM Generic Timer`. + +Console Driver +-------------- + +The console driver supports the default Qemu emulated ARM PL011 PrimeCell UART. + +Running Executables +------------------- + +Executables generated by these BSPs can be run using the following command: + +.. code-block:: shell + + qemu-system-aarch64 -no-reboot -nographic -serial mon:stdio \ + -machine virt,gic-version=3 -cpu cortex-a53 -m 4096 -kernel example.exe diff --git a/user/bsps/aarch64/a72.rst b/user/bsps/aarch64/a72.rst new file mode 100644 index 0000000..e8e4b3d --- /dev/null +++ b/user/bsps/aarch64/a72.rst @@ -0,0 +1,35 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 On-Line Applications Research Corporation (OAR) + +.. _BSP_aarch64_qemu_a72_ilp32: +.. _BSP_aarch64_qemu_a72_lp64: + +Qemu A72 +======== + +This BSP supports two variants, `qemu_a72_ilp32` and `qemu_a72_lp64`. The basic +hardware initialization is performed by the BSP. These BSPs support the GICv3 +interrupt controller. + +Boot via ELF +------------ +The executable image is booted by Qemu in ELF format. + +Clock Driver +------------ + +The clock driver uses the `ARM Generic Timer`. + +Console Driver +-------------- + +The console driver supports the default Qemu emulated ARM PL011 PrimeCell UART. + +Running Executables +------------------- + +Executables generated by these BSPs can be run using the following command:: + +qemu-system-aarch64 -no-reboot -nographic -serial mon:stdio \ + -machine virt,gic-version=3 -cpu cortex-a72 -m 4096 -kernel example.exe diff --git a/user/bsps/aarch64/raspberrypi4.rst b/user/bsps/aarch64/raspberrypi4.rst new file mode 100644 index 0000000..efb09b6 --- /dev/null +++ b/user/bsps/aarch64/raspberrypi4.rst @@ -0,0 +1,109 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Mohd Noor Aman + +.. _BSP_aarch64_Raspberrypi_4: + +Raspberry Pi 4B +=============== + +The 'raspberrypi4b' BSP currently supports only the LP64 ABI. ILP32 is not +supported. Raspberry pi 4B all variants and Raspberry Pi 400 are supported. The +default bootloader which is used by the Raspbian OS or other OS can be used to +boot RTEMS. SMP is currently not supported. + +Raspberry Pi 4B has 2 types of interrupt controller, GIC-400 (GICv2) and ARM +legacy generic controller. Both are supported. By default, raspberrypi 4B uses +ARM legacy generic controller. Set ``enable_gic=1`` in the ``config.txt`` file +to enable GIC. + +Clock Driver +------------ + +The clock driver uses the `ARM Generic Timer`. + +Console Driver +-------------- + +Raspberry pi 4B has 2 types of UARTs, ARM PL011 and Mini-uart. The PL011 is a +capable, broadly 16550-compatible UART, while the mini UART has a reduced +feature set. The console driver supports the default Qemu emulated ARM PL011 +PrimeCell UART as well as the physical ARM PL011 PrimeCell UART in the +raspberrypi hardware. Mini-uart is not supported. + +Preparing to boot +------------------ + +Raspberry Pi uses a different mechanism to boot when compared with any ARM SoC. +First the GPU initializes, loads the bootloader (Raspberry pi firmware) and then +looks for the kernel img. This whole process is done by the GPU (VideoCore IV) +till the kernel is loaded. More information can be found on the `Raspberry pi +documentation page +<https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#boot-sequence>`_. +By default the arm64 mode looks for the ``kernel8.img``. Any other kernel can be +loaded by adding ``kernel=<img_name>`` to the ``config.txt`` file. + +The Firmware files are required in order to boot RTEMS. The latest firmware can +be downloaded from the `Raspberry Pi Firmware Repository +<https://github.com/raspberrypi/firmware/>`_. USB boot is supported. All the +files (Firmwares and kernel) must be place in the FAT32 partition only. Add +``arm_64bit=1`` in the ``config.txt`` file in order to boot the BSP in 64bit +kernel mode. + + +UART Setup +^^^^^^^^^^ + +Connect your serial device to the GPIO15 and GPIO14. Add the following to the +``config.txt`` file in order to use the PL011 UART0 and thus disabling the +default Mini-uart. + +.. code-block:: none + + # if user wants to enable GIC, uncomment the next line + # enable_gic=1 + arm_64bit=1 + dtoverlay = disable-bt + enable_uart=1 + +.. note:: + The Raspberry Pi 4B and 400 have an additional four PL011 UARTs. They are not + supported. + +Generating kernel image +^^^^^^^^^^^^^^^^^^^^^^^ + +The following steps show how to run ``hello.exe`` on the BSP. Other executables +can be processed in a similar way. + +To create the kernel image: + +.. code-block:: shell + + $ aarch64-rtems@rtems-ver-major@-objcopy -Obinary hello.exe kernel8.img + +Copy the kernel image to the SD card. + +JTAG Setup +---------- + +The Raspberry Pi 4 doesn't have dedicated JTAG pins. Instead, you must configure +the GPIO pins (GPIO22-GPIO27) to activate the JTAG functionality. The RPi 4 +documentation refers to this as Alt4 functions of those pins. Alt5 does exist +too, which goes from GPIO4, 5, 6, 12 and 13. you can check this out from +`pinout.xyz <https://pinout.xyz/pinout/jtag#>`_ or `eLinux +<https://elinux.org/RPi_BCM2835_GPIOs>`_ + +One more thing to note on JTAG with Raspberry pi 4B is that, by default, All the +GPIO pins are pulled down, according to the `BCM2711 documentation +<https://datasheets.raspberrypi.com/bcm2711/bcm2711-peripherals.pdf>`_. This +wasn't the case in the earlier models. So in order to let the data flow freely, +we will have to disable them. + +.. code-block:: none + + # Disable pull downs + gpio=22-27=np + + # Enable jtag pins (i.e. GPIO22-GPIO27) + enable_jtag_gpio=1 diff --git a/user/bsps/aarch64/xilinx-versal.rst b/user/bsps/aarch64/xilinx-versal.rst new file mode 100644 index 0000000..51489f2 --- /dev/null +++ b/user/bsps/aarch64/xilinx-versal.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2021 Gedare Bloom + +.. _BSP_aarch64_qemu_xilinx_versal_ilp32_qemu: +.. _BSP_aarch64_qemu_xilinx_versal_lp64_qemu: + +Qemu Xilinx Versal +================== + +This BSP supports two variants, `xilinx-versal-ilp32-qemu` and +`xilinx-versal-lp64-qemu`. The basic hardware initialization is performed by the +BSP. These BSPs support the GICv3 interrupt controller present in the Xilinx +Versal Adaptive Compute Acceleration Platform (ACAP) systems. The BSPs +currently only work when started in the secure mode. + +Boot via ELF +------------ +The executable image is booted by Qemu in ELF format. + +Clock Driver +------------ + +The clock driver uses the `ARM Generic Timer`. + +Console Driver +-------------- + +The console driver supports the default Qemu emulated ARM PL011 PrimeCell UART. +There are some differences between the PL011 and the UART used by actual Versal +ACAP hardware systems. + +Running Executables +------------------- + +Executables generated by these BSPs can be run using the following command:: + +qemu-system-aarch64 -no-reboot -nographic -serial mon:stdio \ + -machine xlnx-versal-virt -m 4096 -kernel example.exe diff --git a/user/bsps/aarch64/xilinx-zynqmp.rst b/user/bsps/aarch64/xilinx-zynqmp.rst new file mode 100644 index 0000000..4de0115 --- /dev/null +++ b/user/bsps/aarch64/xilinx-zynqmp.rst @@ -0,0 +1,295 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 On-Line Applications Research Corporation (OAR) + +.. _BSP_aarch64_qemu_xilinx_zynqmp_ilp32_qemu: +.. _BSP_aarch64_qemu_xilinx_zynqmp_lp64_qemu: +.. _BSP_aarch64_qemu_xilinx_zynqmp_ilp32_zu3eg: +.. _BSP_aarch64_qemu_xilinx_zynqmp_lp64_zu3eg: +.. _BSP_aarch64_qemu_xilinx_zynqmp_lp64_cfc400x: + +Qemu Xilinx ZynqMP +================== + +This BSP family supports the following variants: + +* `xilinx-zynqmp-ilp32-qemu` + +* `xilinx-zynqmp-lp64-qemu` + +* `xilinx-zynqmp-ilp32-zu3eg` + +* `xilinx-zynqmp-lp64-zu3eg` + +* `xilinx-zynqmp-lp64-cfc400x` + +Platform-specific hardware initialization is performed by ARM Trusted Firmware +(ATF). Other basic hardware initialization is performed by the BSP. These BSPs +support the GICv2 interrupt controller present in all ZynqMP systems. The zu3eg +BSPs have also been tested to be fully functional on zu2cg boards and should +also work on any other ZynqMP chip variant since the Processing Subsystem (PS) +does not vary among chip variants other than the number of CPU cores available. + +This BSP family has been tested on the following hardware: + +* `Avnet UltraZed-EG SOM` + +* `Innoflight CFC-400X` + +* `Trenz TE0802` + +* `Xilinx ZCU102` + +Boot on QEMU +------------ +The executable image is booted by Qemu in ELF format. + +Boot on ZynqMP Hardware +----------------------- + +On ZynqMP hardware, RTEMS can be started at EL1, EL2, or EL3 by u-boot or +directly as part of BOOT.bin. Regardless of the exception level at boot, RTEMS +will drop to EL1 for execution. For quick turnaround during testing, it is +recommended to use the u-boot BOOT.bin that comes with the PetaLinux prebuilts +for the board in question. + +Some systems such as the CFC-400X may require a bitstream to be loaded into the +FPGA portion of the chip to operate as expected. This bitstream must be loaded +before RTEMS begins operation since accesses to programmable logic (PL) memory +space can cause the CPU to hang if the FPGA is not initialized. This can be +performed as part of BOOT.bin or by a bootloader such as u-boot. Loading +bitstreams from RTEMS has not been tested on the ZynqMP platform and requires +additional libraries from Xilinx. + +Hardware Boot Image Generation +------------------------------ + +RTEMS expects some hardware initialization to be performed by ATF and expects +the services it provides to be present, so this must be included when generating +a direct-boot RTEMS BOOT.bin. + +When booting via u-boot, RTEMS must be packaged into a u-boot image or booted +as a raw binary since u-boot does not currently support ELF64 which is required +for AArch64 ELF binaries. + +Example: Booting a RTEMS image on the ZCU102 ZynqMP board +--------------------------------------------------------- + +This example will walk through the steps needed for booting RTEMS from a SD card +on the +`ZCU102 ZynqMP board. <https://www.xilinx.com/products/boards-and-kits/ek-u1-zcu102-g.html>`_ +The reference for setting up a SD card and obtaining pre-built boot images is +`here. <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18841858/Board+bring+up+using+pre-built+images>`_ + +Hardware Setup +^^^^^^^^^^^^^^ + +Set the dip switch SW6 according to the table below. This will allow the board +to boot from the SD card. Connect a Micro-USB cable to the USB UART interface +J83. This is a quad USB UART interface which will show up on the development +host computer as four different serial or tty devices. Use the first channel +for the console UART. It should be set to 115k baud. + ++---------------------------+ +| Dip Switch JW6 | ++------+------+------+------+ +| ON | OFF | OFF | OFF | ++------+------+------+------+ + +Prepare a SD card with a bootable partition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The goal is to have a bootable SD card with a partition that is formatted with +the FAT file system. The file system will contain the boot artifacts including +BOOT.bin and the u-boot image. The RTEMS image will be placed on this volume. To +create the bootable SD card, follow the directions +`here. <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/18842385/How+to+format+SD+card+for+SD+boot>`_ + +Once you have the card formatted correctly, you need to place the files from +`this archive <https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/2202763266/2021.2+Release#Downloads>`_ +on the FAT partition. The following file was used for this example: +`xilinx-vck190-v2021.2-final.bsp <https://www.xilinx.com/member/forms/download/xef.html?filename=xilinx-vck190-v2021.2-final.bsp>`_ + +In order to download these files, you need to have a Xilinx account login. As an +alternative, you can download a bootable image for Ubuntu 20.04 and write it to +an SD card using a utility such as `Balena Etcher <https://www.balena.io/etcher>`_ +or dd. The Ubuntu image is available `here. <https://ubuntu.com/download/xilinx>`_ +Download the image for the Zynq Ultrascale+ MPSoC Development boards, uncompress +it and write it to the SD card. This image creates multiple partitions, but we +only need to use the FAT partition with the boot artifacts on it. + +Verify that the board can boot from the SD card +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is worth booting the board from the SD card before trying to boot RTEMS. +Insert the card and power on the board. You should see the messages on the first +console indicating the various boot loader stages and eventually the Linux +kernel. The goal is to interrupt u-boot when given the chance to access the +u-boot command prompt. + +Build RTEMS with examples +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Build the RTEMS `xilinx-zynqmp-lp64-zu3eg` BSP. Use the ticker.exe sample which +can be found in the directory: + +.. code-block:: shell + + build/aarch64/xilinx-zynqmp-lp64-zu3eg/testsuites/samples + +Prepare the RTEMS image +^^^^^^^^^^^^^^^^^^^^^^^ + +Prepare your RTEMS image to boot from u-boot with the following commands: + +.. code-block:: shell + + $ aarch64-rtems@rtems-ver-major@-objcopy -Obinary ticker.exe ticker.bin + $ gzip -9 ticker.bin + $ mkimage -A arm64 -O rtems -T kernel -a 0x10000000 -e 0x10000000 -n RTEMS -d ticker.bin.gz rtems.img + +Boot the RTEMS image +^^^^^^^^^^^^^^^^^^^^ +Copy the prepared RTEMS image to the SD card and insert the SD crd in the ZCU102 +board. Power on the board. When you see the prompt on the console to interupt +u-boot, hit a key to bring up the u-boot command prompt. On the u-boot command +prompt you can boot your RTEMS image: + +.. code-block:: shell + + Zynq-MP> fatload mmc 0:1 0x1000 rtems.img + Zynq-MP> bootm 0x1000 + +This is the entire boot sequence: + +.. code-block:: shell + + Pre-FSBL boot Started + Xilinx Zynq MP First Stage Boot Loader + Release 2020.2 Nov 18 2020 - 11:46:01 + NOTICE: ATF running on XCZU9EG/silicon v1/RTL5.1 at 0xfffea000 + NOTICE: BL31: v2.2(release):xilinx_rebase_v2.2_2020.1-10-ge6eea88b1 + NOTICE: BL31: Built : 12:28:45, Nov 17 2020 + + U-Boot 2020.01 (Jun 15 2021 - 14:24:32 +0000) + + Model: ZynqMP ZCU102 Rev1.0 + Board: Xilinx ZynqMP + DRAM: 4 GiB + PMUFW: v1.1 + EL Level: EL2 + Chip ID: zu9eg + NAND: 0 MiB + MMC: mmc@ff170000: 0 + In: serial@ff000000 + Out: serial@ff000000 + Err: serial@ff000000 + Bootmode: SD_MODE1 + Reset reason: SOFT + Net: + ZYNQ GEM: ff0e0000, mdio bus ff0e0000, phyaddr 12, interface rgmii-id + + Warning: ethernet@ff0e0000 (eth0) using random MAC address - 82:32:1d:80:d9:c9 + eth0: ethernet@ff0e0000 + Hit any key to stop autoboot: 0 + + ZynqMP> fatload mmc 0:1 0x1000 rtems.img + 46669 bytes read in 27 ms (1.6 MiB/s) + ZynqMP> bootm 0x1000 + ## Booting kernel from Legacy Image at 00001000 ... + Image Name: RTEMS + Image Type: AArch64 RTEMS Kernel Image (gzip compressed) + Data Size: 46605 Bytes = 45.5 KiB + Load Address: 10000000 + Entry Point: 10000000 + Verifying Checksum ... OK + Uncompressing Kernel Image + ## Transferring control to RTEMS (at address 10000000) ... + + *** BEGIN OF TEST CLOCK TICK *** + *** TEST VERSION: @rtems-version@.f381e9bab29278e4434b1a93e70d17a7562dc64c + *** TEST STATE: EXPECTED_PASS + *** TEST BUILD: RTEMS_POSIX_API RTEMS_SMP + *** TEST TOOLS: 10.3.1 20210409 (RTEMS 6, RSB ad54d1dd3cf8249d9d39deb1dd28b2f294df062d, Newlib eb03ac1) + TA1 - rtems_clock_get_tod - 09:00:00 12/31/1988 + TA2 - rtems_clock_get_tod - 09:00:00 12/31/1988 + TA3 - rtems_clock_get_tod - 09:00:00 12/31/1988 + TA1 - rtems_clock_get_tod - 09:00:05 12/31/1988 + TA2 - rtems_clock_get_tod - 09:00:10 12/31/1988 + TA1 - rtems_clock_get_tod - 09:00:10 12/31/1988 + TA1 - rtems_clock_get_tod - 09:00:15 12/31/1988 + TA3 - rtems_clock_get_tod - 09:00:15 12/31/1988 + TA2 - rtems_clock_get_tod - 09:00:20 12/31/1988 + TA1 - rtems_clock_get_tod - 09:00:20 12/31/1988 + TA1 - rtems_clock_get_tod - 09:00:25 12/31/1988 + TA2 - rtems_clock_get_tod - 09:00:30 12/31/1988 + TA1 - rtems_clock_get_tod - 09:00:30 12/31/1988 + TA3 - rtems_clock_get_tod - 09:00:30 12/31/1988 + + *** END OF TEST CLOCK TICK *** + + [ RTEMS shutdown ] + + +Follow up +^^^^^^^^^ + +This is just one possible way to boot the RTEMS image. For a development +environment you may wish to configure u-boot to boot the RTEMS image from a TFTP +server. For a production environment, you may wish to download, configure, and +build u-boot, or develop a BOOT.BIN image with the RTEMS application. + +Clock Driver +------------ + +The clock driver uses the `ARM Generic Timer`. + +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. + +SDHCI Driver +------------ + +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 + + qemu-system-aarch64 -no-reboot -nographic -serial mon:stdio \ + -machine xlnx-zcu102 -m 4096 -kernel media01.exe -sd example.img + +The SD card image should have an MSDOS partition table with a single partition +containing a FAT file system. + +Network Configuration +--------------------- + +When used with LibBSD, these BSP variants support networking via the four +Cadence GEM instances present on all ZynqMP hardware variants. All interfaces +are enabled by default, but only interfaces with operational MII busses will be +recognized and usable in RTEMS. Most ZynqMP dev boards use RGMII with CGEM3. + +When used with lwIP from the rtems-lwip integration repository, these BSP +variants support networking via CGEM0 and one of the other CGEM* instances +simultaneously. This is a limitation of the Xilinx driver, specifically +in code referring directly to XPAR_XEMACPS_0_BASEADDR. Attempting to use more +than two interfaces simultaneously may cause unexpected behavior. Attempting to +use a set of two interfaces that does not include CGEM0 may cause unexpected +behavior. + +The interfaces will not come up by default under lwIP and must be configured +manually. There are examples of this in the start_networking() implementation +in netstart.c as used by the network tests. + +Running Executables on QEMU +--------------------------- + +Executables generated by these BSPs can be run using the following command: + +.. code-block:: shell + + qemu-system-aarch64 -no-reboot -nographic -serial mon:stdio \ + -machine xlnx-zcu102 -m 4096 -kernel example.exe diff --git a/user/bsps/arm/altera-cyclone-v.rst b/user/bsps/arm/altera-cyclone-v.rst index 14c026c..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) @@ -27,7 +27,7 @@ image. Use the following commands: .. code-block:: none - arm-rtems5-objcopy -O binary app.exe app.bin + arm-rtems@rtems-ver-major@-objcopy -O binary app.exe app.bin gzip -9 -f -c app.bin > app.bin.gz mkimage -A arm -O linux -T kernel -a 0x00300000 -e 0x00300000 -n RTEMS -d app.bin.gz app.img diff --git a/user/bsps/arm/beagle.rst b/user/bsps/arm/beagle.rst index fe2dc6f..55f75c0 100644 --- a/user/bsps/arm/beagle.rst +++ b/user/bsps/arm/beagle.rst @@ -2,6 +2,12 @@ .. Copyright (C) 2019 Vijay Kumar Banerjee +.. _BSP_arm_beagle: +.. _BSP_arm_beagleboardorig: +.. _BSP_arm_beagleboardxm: +.. _BSP_arm_beagleboneblack: +.. _BSP_arm_beaglebonewhite: + beagle ====== @@ -26,7 +32,7 @@ To boot via uboot, the ELF must be converted to a U-Boot image like below: .. code-block:: none - arm-rtems5-objcopy hello.exe -O binary app.bin + arm-rtems@rtems-ver-major@-objcopy hello.exe -O binary app.bin gzip -9 app.bin mkimage -A arm -O linux -T kernel -a 0x80000000 -e 0x80000000 -n RTEMS -d app.bin.gz rtems-app.img @@ -61,23 +67,39 @@ Add the following to a file named uEnv.txt: I2C Driver ---------- -The Beagle has the `i2c-0` device registered at initialization. For registering -`i2c-1` and `i2c-2` ``bbb_register_i2c_1()`` and -``bbb_register_i2c_2()`` wrapper functions are respectively used. +The Beagle i2c initialization is based on the device tree. To initialize a i2c +device, the user has to enable the respective node in the device tree using +overlays. -For registering an I2C device with a custom path (say `/dev/i2c-3`) the -function ``am335x_i2c_bus_register()`` has to be used. +For registering an I2C device with a custom path (say `/dev/i2c-eeprom`) an +overlay has to be provided. The overlay must add an additional attribute +`rtems,path` with the custom path as value to the respective i2c node. -The function prototype is given below: +For example, + +.. code-block:: none + + /dts-v1/; + + / { + compatible = "ti,am335x-bone-black", "ti,am335x-bone", "ti,am33xx"; -.. code-block:: C + fragment@0 { + target = <0xffffffff>; - int am335x_i2c_bus_register( - const char *bus_path, - uintptr_t register_base, - uint32_t input_clock, - rtems_vector_number irq - ); + __overlay__ { + compatible = "rtems,bsp-i2c", "ti,omap4-i2c"; + status = "okay"; + rtems,path = "/dev/i2c-eeprom"; + }; + }; + + __fixups__ { + i2c0 = "/fragment@0:target:0"; + }; + }; + +The above example registers a custom path `/dev/i2c-eeprom` for i2c0. SPI Driver ---------- @@ -88,10 +110,134 @@ For registering with a custom path, the ``bsp_register_spi()`` can be used. The function prototype is given below: -.. code-block:: C +.. code-block:: c rtems_status_code bsp_register_spi( const char *bus_path, uintptr_t register_base, rtems_vector_number irq ); + +Debugging using libdebugger +--------------------------- + +RTEMS's ``libdebugger`` requires the ARM debug resources be enabled for it to +work. The TI SOC used on the ``beagleboneblack`` board provides no access for +software to the ARM defined debug enable signal ``DBGEN``. The signal is +negated on power up locking software out of the ARM debug hardware. The signal +can only be accessed via the JTAG interface. + +The ``beagleboneblack`` BSP provides a low level solution to enable the +``DBGEN`` signal via the JTAG interface if the board has the following +hardware modification installed. The modification requires the addition of two +small wire links soldered to the pads of the JTAG connect on the underside of +the board. A small length of fine wire, a fine tip soldering iron, some good +quality solder and a pair of fine tip pliers are required. If you are new to +soldering I suggest you find something to practice on first. + +The modification details and software driver can be found in the BSP in the +file ``bsps/arm/beagle/start/bspdebug.c``. The driver is automatically run +and the ``DBGEN`` is asserted via JTAG when ``libdebugger`` is started. + +The modification is: + +1. Locate P2 on the bottom side of the board. It is the JTAG connector + pads. If you look at the underside of the board with the SD card holder to + the right the pads are top center left. There are 20 pads in two + columns. The pads are numbered 1 at the top left then 2 top right, 3 is + second top on the left, 4 is second top to the right, then the pin number + increments as you move left then right down the pads. + +2. Connect P2 to P5. + +3. Connect P7 to P13. + +The resulting wiring is: + +.. code-block:: none + + 1 === /--=== 2 + 3 === | === 4 + 5 ===--/ === 6 + 7 ===--\ === 8 + 9 === | === 10 + 11 === | === 12 + 13 ===--/ === 14 + 15 === === 16 + 17 === === 18 + 19 === === 20 + +.. figure:: ../../../images/user/bbb-p2-debug-mod.jpg + :width: 50% + :align: center + :alt: BeagleBone Black JTAG Hardware Modification + + BeagleBone Black JTAG Hardware Modification + +If ``libdebugger`` fails to detect the registers open the ``bspdebug.c`` +source and change ``has_tdo`` to ``1``, save then rebuild and install the +BSP. This will turn on an internal feeback to check the JTAG logic. Discard +the edit once the hardware is working. + +Debugging Beagle Bone Black using a JTAG debugger and gdb +--------------------------------------------------------- + +Debugging a Beagle Bone Black (or variants) is also possible using a hardware +JTAG debugger. The JTAG is available via P2. The footprint is for an ARM 20 pin +cTI connector. That connector should be used, if it is necessary to have access +to commercially available adapters. + +For hand-made cables and adapters a standard 1.27mm pitch header and a 0.635mm +ribbon cable can be much cheaper. But note that even if it looks compatible, +it's not the same pin out as a ARM Cortex 20 pin connector! + +A lot of JTAG adapters that are working together with OpenOCD will work. There +are also commercially available systems (like Segger J-Link) that work well with +the Beagle. Note that the JTAG debugger has to be compatible with ARM Cortex A8. +Cortex M only debuggers (like the Segger J-Link Edu Mini) won't work. + +If the debugger offers a gdb server (like OpenOCD or Segger J-Link) the +following gdb start script can be used: + +.. code-block:: none + + define reset + echo -- Reset target and wait for U-Boot to start kernel.\n + monitor reset + # RTEMS U-Boot starts at this address. + tbreak *0x80000000 + # Linux starts here. + tbreak *0x82000000 + continue + + echo -- Disable watchdog.\n + set *(uint32_t*)0x44e35048=0xAAAA + while (*(uint32_t*)0x44e35034 != 0) + end + set *(uint32_t*)0x44e35048=0x5555 + while (*(uint32_t*)0x44e35034 != 0) + end + + echo -- Overwrite kernel with application to debug.\n + load + end + + target remote :2331 + +Note that you might have to replace the ``monitor reset`` by some other command +that resets the target using your specific debugger. You also have to replace +the ``target remote :2331`` to match the port of your gdb server. + +The script expects that the Beagle Bone Black starts some application from an SD +card or from eMMC. It defines a ``reset`` command that does the following: + + * reset the target + * let U-Boot run, initialize the base system, load an FDT and an application + * break at the application entry point + * disable the watchdog + * overwrite the application that has been loaded by U-Boot with the application + provided as an command line argument to gdb + +This method has the advantage that the application is executed in nearly the +same environment like it would be executed if loaded by U-Boot directly (except +for the watchdog). diff --git a/user/bsps/arm/bsp-csb337.rst b/user/bsps/arm/csb337.rst index 6f7d927..6f7d927 100644 --- a/user/bsps/arm/bsp-csb337.rst +++ b/user/bsps/arm/csb337.rst diff --git a/user/bsps/arm/fvp.rst b/user/bsps/arm/fvp.rst new file mode 100644 index 0000000..b938e30 --- /dev/null +++ b/user/bsps/arm/fvp.rst @@ -0,0 +1,39 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 embedded brains GmbH & Co. KG + +fvp (Fixed Virtual Platform) +============================ + +The BSP for the +`Arm Fixed Virtual Platforms <https://developer.arm.com/Tools%20and%20Software/Fixed%20Virtual%20Platforms>`_ +offers one variant. You need a license from Arm to run the simulator. The +`fvp_cortex_r52` variant supports a simulation of the Cortex-R52 processor. +The BSP supports the SMP configuration. + +Run an Executable +----------------- + +To run an executable on a single Cortex-R52 processor use: + +.. code-block:: none + + FVP_BaseR_Cortex-R52x1 -C bp.vis.disable_visualisation=1 -a build/arm/fvp_cortex_r52/testsuites/samples/ticker.exe + +To run an executable on a four Cortex-R52 processors use: + +.. code-block:: none + + FVP_BaseR_Cortex-R52x4 -C bp.vis.disable_visualisation=1 -a build/arm/fvp_cortex_r52/testsuites/samples/ticker.exe + +Clock Driver +------------ + +The clock driver uses the `ARMv7-AR Generic Timer`. + +Console Driver +-------------- + +The console driver uses the +`semihosting <https://developer.arm.com/documentation/dui0471/g/Semihosting/Semihosting-operations?lang=en>`_ +``SYS_READC`` and ``SYS_WRITEC`` system calls. diff --git a/user/bsps/arm/gdbarmsim.rst b/user/bsps/arm/gdbarmsim.rst deleted file mode 100644 index 26ea90c..0000000 --- a/user/bsps/arm/gdbarmsim.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2019 TBD - -gdbarmsim -========= - -TODO. diff --git a/user/bsps/arm/imx.rst b/user/bsps/arm/imx.rst index bc93ae3..47ad503 100644 --- a/user/bsps/arm/imx.rst +++ b/user/bsps/arm/imx.rst @@ -1,20 +1,23 @@ .. 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) ============== This BSP offers only one variant, the `imx7`. This variant supports the i.MX -7Dual processor. The basic hardware initialization is not performed by the -BSP. A boot loader with device tree support must be used to start the BSP, -e.g. U-Boot. +7Dual processor and the i.MX 6UL/ULL processor family (with slightly different +clock settings). The basic hardware initialization is not performed by the BSP. +A boot loader with device tree support must be used to start the BSP, e.g. +U-Boot or barebox. Build Configuration Options --------------------------- -The following options are available at the configure command line. +The following options can be used in the BSP section of the waf +configuration INI file. The waf defaults can be used to inspect the +values. ``BSP_PRESS_KEY_FOR_RESET`` If defined to a non-zero value, then print a message and wait until pressed @@ -40,9 +43,30 @@ The following options are available at the configure command line. ``IMX_CCM_UART_HZ`` The UART clock frequency in Hz (default is 24000000). +``IMX_CCM_ECSPI_HZ`` + The ECSPI clock frequency in Hz (default is 67500000). + ``IMX_CCM_AHB_HZ`` The AHB clock frequency in Hz (default is 135000000). +``IMX_CCM_SDHCI_HZ`` + The SDHCI clock frequency in Hz (default is 196363000). + +Clock settings for different boards +----------------------------------- + +The default clock settings are targeted for an i.MX 7Dual evaluation board using +U-Boot. Some other boards with different boot loaders need different settings: + + * Phytec phyCORE-i.MX 6ULL (system on module) with MCIMX6Y2CVM08AB and a + barebox bootloader (version ``2019.01.0-bsp-yocto-i.mx6ul-pd19.1.0``): + + * IMX_CCM_IPG_HZ=66000000 + * IMX_CCM_UART_HZ=80000000 + * IMX_CCM_AHB_HZ=66000000 + * IMX_CCM_SDHCI_HZ=198000000 + * IMX_CCM_ECSPI_HZ=60000000 + Boot via U-Boot --------------- @@ -51,7 +75,7 @@ image. Use the following commands: .. code-block:: none - arm-rtems5-objcopy -O binary app.exe app.bin + arm-rtems@rtems-ver-major@-objcopy -O binary app.exe app.bin gzip -9 -f -c app.bin > app.bin.gz mkimage -A arm -O linux -T kernel -a 0x80200000 -e 0x80200000 -n RTEMS -d app.bin.gz app.img @@ -65,6 +89,14 @@ The ``loadfdt`` command may be not defined in your U-Boot environment. Just replace it with the appropriate commands to load the device tree at ``${fdt_addr}``. +Boot via barebox +---------------- + +The same command like for U-Boot can be used to generate an application image. +In a default configuration barebox expects an fdt image called `oftree` and a +kernel image called `zImage` in the root folder of the bootable medium (e.g. an +SD card). + Clock Driver ------------ @@ -133,6 +165,34 @@ system controls: A value of zero for the time or count disables the interrupt coalescing in the corresponding direction. +On the Phytec phyCORE-i.MX 6ULL modules the PHY needs an initialization for the +clock. A special PHY driver handles that (``ksz8091rnb``). Add it to your libbsd +config like that: + +.. code-block:: c + + #define RTEMS_BSD_CONFIG_BSP_CONFIG + #define RTEMS_BSD_CONFIG_INIT + SYSINIT_DRIVER_REFERENCE(ksz8091rnb, miibus); + #include <machine/rtems-bsd-config.h> + +On chips with two Ethernet controllers, the MDIO lines are shared between the +two controllers for a number of chips variants. This is currently supported with +some restrictions on the initialization order. For this configuration to work, +you have to make sure that the pins are assigned to the Ethernet controller that +is initialized first. The initialization order in `libbsd` depends on the order +of the Ethernet controllers in the device tree. So if (for example) `fec2` is +defined in the device tree sources before `fec1`, make sure that the MDIO lines +are routed to `fec2` and that the Ethernet PHYs are a sub-node of `fec2` in the +device tree. + +Note that the clock for the second Ethernet controller is not necessarily +enabled in the `CCM`. On the i.MX6UL/ULL, the clock will be enabled by the +startup code if the node that is compatible with `fsl,imx6ul-anatop` can be +found in the device tree. If you have trouble with the second Ethernet +controller make sure that the `ENET2_125M_EN` bit in the `CCM_ANALOG_PLL_ENET` +register is set as expected. + MMC/SDCard Driver ----------------- diff --git a/user/bsps/arm/imxrt.rst b/user/bsps/arm/imxrt.rst new file mode 100644 index 0000000..30b1437 --- /dev/null +++ b/user/bsps/arm/imxrt.rst @@ -0,0 +1,310 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG +.. Copyright (C) 2020 Christian Mauderer + +imxrt (NXP i.MXRT) +================== + +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 +--------------------------- + +Please see the documentation of the `IMXRT_*` and `BSP_*` configuration options +for that. You can generate a default set of options with:: + + ./waf bspdefaults --rtems-bsps=arm/imxrt1052 > config.ini + +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: + +1) The ROM code loads a configuration from HyperFlash (connected to FlexSPI), + does some initialization (based on device configuration data (DCD)) and then + starts the application. This is the default case. `linkcmds.flexspi` is used + for this case. + +2) Some custom bootloader does the basic initialization, loads the application + to SDRAM and starts it from there. Select the `linkcmds.sdram` for this. + +For programming the HyperFlash in case 1, you can use the on board debugger +integrated into the IMXRT1050-EVKB. You can generate a flash image out of a +compiled RTEMS application with for example:: + + arm-rtems@rtems-ver-major@-objcopy -O binary build/arm/imxrt1052/testsuites/samples/hello.exe hello.bin + +Then just copy the generated binary to the mass storage provided by the +debugger. Wait a bit till the mass storage vanishes and re-appears. After that, +reset the board and the newly programmed application will start. + +NOTE: It seems that there is a bug on at least some of the on board debuggers. +They can't write more than 1MB to the HyperFlash. If your application is bigger +than that (like quite some of the applications in libbsd), you should use an +external debugger or find some alternative programming method. + +For debugging: Create a special application with a `while(true)` loop at end of +`bsp_start_hook_1`. Load that application into flash. Then remove the loop +again, build your BSP for SDRAM and use a debugger to load the application into +SDRAM after the BSP started from flash did the basic initialization. + +Flash Image +----------- + +For booting from a HyperFlash (or other storage connected to FlexSPI), the ROM +code of the i.MXRT first reads some special flash header information from a +fixed location of the connected flash device. This consists of the Image vector +table (IVT), Boot data and Device configuration data (DCD). + +In RTEMS, these flash headers are generated using some C-structures. If you use +a board other than the IMXRT1050-EVKB, those structures have to be adapted. To +do that re-define the following variables in your application (you only need the +ones that need different values): + +.. code-block:: c + + #include <bsp/flash-headers.h> + const uint8_t imxrt_dcd_data[] = + { /* Your DCD data here */ }; + const ivt imxrt_image_vector_table = + { /* Your IVT here */ }; + const BOOT_DATA_T imxrt_boot_data = + { /* Your boot data here */ }; + const flexspi_nor_config_t imxrt_flexspi_config = + { /* Your FlexSPI config here */ }; + +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` 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 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/; + + #include <imxrt/imxrt1050-pinfunc.h> + #include <imxrt/imxrt1050.dtsi> + + &lpuart1 { + pinctrl-0 = <&pinctrl_lpuart1>; + status = "okay"; + }; + + &chosen { + stdout-path = &lpuart1; + }; + + /* put your further devices here */ + + &iomuxc { + pinctrl_lpuart1: lpuart1grp { + fsl,pins = < + IMXRT_PAD_GPIO_AD_B0_12__LPUART1_TX 0x8 + IMXRT_PAD_GPIO_AD_B0_13__LPUART1_RX 0x13000 + >; + }; + + /* put your further pinctrl groups here */ + }; + +You can then convert your FDT into a C file with (replace `YOUR.dts` and similar +with your FDT source names): + +.. code-block:: none + + sh> arm-rtems@rtems-ver-major@-cpp -P -x assembler-with-cpp \ + -I ${PREFIX}/arm-rtems@rtems-ver-major@/imxrt1052/lib/include \ + -include "YOUR.dts" /dev/null | \ + dtc -O dtb -o "YOUR.dtb" -b 0 -p 64 + sh> rtems-bin2c -A 8 -C -N imxrt_dtb "YOUR.dtb" "YOUR.c" + +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. + +Clock Driver +------------ + +The clock driver uses the generic `ARMv7-M Clock`. + +IOMUX +----- + +The i.MXRT IOMUXC is initialized based on the FDT. For that, the `pinctrl-0` +fields of all devices with a status of `ok` or `okay` will be parsed. + +Console Driver +-------------- + +LPUART drivers are registered based on the FDT. The special `rtems,path` +attribute defines where the device file for the console is created. + +The `stdout-path` in the `chosen` node determines which LPUART is used for the +console. + +I2C Driver +---------- + +I2C drivers are registered based on the FDT. The special `rtems,path` attribute +defines where the device file for the I2C bus is created. + +Limitations: + +* Only basic I2C is implemented. This is mostly a driver limitation and not a + hardware one. + +SPI Driver +---------- + +SPI drivers are registered based on the FDT. The special `rtems,path` attribute +defines where the device file for the SPI bus is created. + +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 +------------------------ + +The network interface driver is provided by the `libbsd`. It is initialized +according to the device tree. + +Note on the hardware: The i.MXRT1050 EVKB maybe has a wrong termination of the +RXP, RXN, TXP and TXN lines. The resistors R126 through R129 maybe shouldn't be +populated because the used KSZ8081RNB already has an internal termination. +Ethernet does work on short distance anyway. But keep it in mind in case you +have problems. Source: +https://community.nxp.com/t5/i-MX-RT/Error-in-IMXRT1050-EVKB-and-1060-schematic-ethernet/m-p/835540#M1587 + +NXP SDK files +------------- + +A lot of peripherals are currently not yet supported by RTEMS drivers. The NXP +SDK offers drivers for these. For convenience, the BSP compiles the drivers from +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. + +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. + +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 + + 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/raspberrypi.rst b/user/bsps/arm/raspberrypi.rst index 72889a5..8f40e92 100644 --- a/user/bsps/arm/raspberrypi.rst +++ b/user/bsps/arm/raspberrypi.rst @@ -5,13 +5,14 @@ raspberrypi =========== -This BSP supports `Raspberry Pi 1` and `Raspberry Pi 2` currently. -The support for `Raspberry Pi 3` is work under progress. +The 'raspberrypi' BSP supports the single core models (Zero, Zero W, A+, B+), +and the 'raspberrypi2' BSP supports the Raspberry Pi 2, Raspberry Pi 3 A+, and Raspberry Pi 3. +The Raspberry Pi 4 is not supported currently. The default bootloader on the Raspberry Pi which is used to boot Raspbian or other OS can be also used to boot RTEMS. U-boot can also be used. Setup SD card ----------------- +------------- The Raspberry Pis have an unconventional booting mechanism. The GPU boots first, initializes itself, runs the bootloader and starts the CPU. @@ -19,11 +20,13 @@ The bootloader looks for a kernel image, by default the kernel images must have a name of the form ``kernel*.img`` but this can be changed by adding `kernel=<img_name>` to ``config.txt``. -You must provide the required files for the GPU to proceed. These files -can be downloaded from -`the Raspberry Pi Firmware Repository <https://github.com/raspberrypi/firmware/tree/master/boot>`_. -You can remove the ``kernel*.img`` files if you want too, but don't touch -the other files. +You must provide the required firmware files on the SD card for the GPU to +proceed, and thereby to boot RTEMS. The BSP currently boots up with an older +version of the official firmware. These files can be downloaded from `the +Raspberry Pi Firmware Repository +<https://github.com/raspberrypi/firmware/tree/1.20200601/boot>`_. You can +remove the ``kernel*.img`` files if you want to, but don't touch the other +files. Copy these files in to a SD card with FAT filesystem. @@ -38,7 +41,7 @@ To create the kernel image: .. code-block:: none - $ arm-rtems5-objcopy -Obinary hello.exe kernel.img + $ xsarm-rtems@rtems-ver-major@-objcopy -Obinary hello.exe kernel.img Copy the kernel image to the SD card. @@ -46,10 +49,46 @@ Make sure you have these lines below, in your ``config.txt``. .. code-block:: none - enable-uart=1 + dtoverlay=disable-bt kernel_address=0x200000 kernel=kernel.img +SPI Driver +---------- + +SPI drivers are registered by the ``rpi_spi_init(bool bidirectional_mode)`` function. + +.. code-block:: none + + #include <assert.h> + #include <bsp.h> + + void spi_init(void) + { + int rv; + + rv = rpi_spi_init(false); + assert(rv == 0); + } + +I2C Driver +---------- + +I2C drivers are registered by the ``rpi_setup_i2c_bus()`` function. + +.. code-block:: none + + #include <assert.h> + #include <bsp.h> + + void i2c_init(void) + { + int rv; + + rv = rpi_setup_i2c_bus(); + assert(rv == 0); + } + Testing using QEMU ------------------ @@ -93,7 +132,7 @@ In a new terminal, run GDB using .. code-block:: none - $ arm-rtems5-gdb hello.exe + $ arm-rtems@rtems-ver-major@-gdb hello.exe This will open GDB and will load the symbol table from hello.exe. Issue the following commands in the GDB prompt. diff --git a/user/bsps/arm/realview-pbx-a9.rst b/user/bsps/arm/realview-pbx-a9.rst index 96710a0..bbe0269 100644 --- a/user/bsps/arm/realview-pbx-a9.rst +++ b/user/bsps/arm/realview-pbx-a9.rst @@ -1,8 +1,20 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 TBD +.. Copyright (C) 2020 embedded brains GmbH & Co. KG realview-pbx-a9 =============== -TODO. +The ``arm/realview_pbx_a9_qemu`` BSP is intended to be used with Qemu. The +Qemu ``realview-pbx-a9`` machine can be used to run SMP tests using for example +the Qemu ``-smp 4`` command line option. + +The command line to execute an ELF file :file:`app.exe` on this Qemu machine +is: + +.. code-block:: none + + export QEMU_AUDIO_DRV="none" + qemu-system-arm -net none -nographic -M realview-pbx-a9 -m 256M -kernel app.exe + +You do not need to specify a device tree blob. diff --git a/user/bsps/arm/bsp-stm32f4.rst b/user/bsps/arm/stm32f4.rst index 23e764e..23e764e 100644 --- a/user/bsps/arm/bsp-stm32f4.rst +++ b/user/bsps/arm/stm32f4.rst diff --git a/user/bsps/arm/stm32h7.rst b/user/bsps/arm/stm32h7.rst new file mode 100644 index 0000000..cdf4d43 --- /dev/null +++ b/user/bsps/arm/stm32h7.rst @@ -0,0 +1,587 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. Copyright (C) 2022 Karel Gardas <karel@functional.vision> + +stm32h7 +======= + +This BSP supports the +`STM32H7 Series <https://www.st.com/en/microcontrollers-microprocessors/stm32h7-series.html>`_. + +The BSP is known to run on these boards on specified core with using specified BSP variant. + +.. table:: + + +----------------------------------------------------------------------------------+-----------+------------------------+ + | Board name | Core name | BSP variant name | + +==================================================================================+===========+========================+ + |`STM32H743I-EVAL 2 <https://www.st.com/en/evaluation-tools/stm32h743i-eval.html>`_| M7 | arm/stm32h7 | + +----------------------------------------------------------------------------------+-----------+------------------------+ + |`STM32H743ZI-Nucleo <https://www.st.com/en/evaluation-tools/nucleo-h743zi.html>`_ | M7 | arm/nucleo-h743zi | + +----------------------------------------------------------------------------------+-----------+------------------------+ + |`STM32H7B3I-DK <https://www.st.com/en/evaluation-tools/stm32h7b3i-dk.html>`_ | M7 | arm/stm32h7b3i-dk | + +----------------------------------------------------------------------------------+-----------+------------------------+ + |`STM32H757I-EVAL <https://www.st.com/en/evaluation-tools/stm32h757i-eval.html>`_ | M7 | arm/stm32h757i-eval | + | +-----------+------------------------+ + | | M4 | arm/stm32h757i-eval-m4 | + +----------------------------------------------------------------------------------+-----------+------------------------+ + |`STM32H747I-DISCO <https://www.st.com/en/evaluation-tools/stm32h747i-disco.html>`_| M7 | arm/stm32h747i-disco | + | +-----------+------------------------+ + | | M4 | arm/stm32h747i-disco-m4| + +----------------------------------------------------------------------------------+-----------+------------------------+ + + +Clock Driver +------------ + +The clock driver uses the `ARMv7-M Systick` module. The HSE (external +oscillator) value can also be different for different evaluation or custom +boards, so it is recommended to check the default values of the BSP. + +Console Driver +-------------- + +The console driver supports the on-chip UART and USART modules. Even +the MCU supports about 10 U(S)ARTs, only those supported by the chosen +board are enabled by default configuration. The board needs to support +some kind of connector-based connection to the U(S)ART in order for the +feature to be considered supported here. +.. +.. Leaving previous notes here as a comment. They may still be useful +.. and incorporated into the later version of the document. +.. +.. Different board variations use different GPIO pins and blocks for the default +.. communication UART and it is recommended to check whether the default +.. configuration provided is valid in the BSP. + +.. To specify that the BSP should be built for the STM32H743ZI-Nucleo board, +.. users can supply ``STM32H743ZI_NUCLEO = True`` to ``config.ini`` when +.. building the BSP. + +.. Alternatively, users can supply the configuration structs defined in ``hal.h`` +.. in the application for other boards. For the console driver, the +.. ``stm32h7_usartX_config`` structs are used to configure the GPIO pins and other +.. parameters. The default implementations can be found in +.. ``bsps/arm/stm32ht/console`` in the RTEMS sources. + +Network Interface Driver +------------------------ + +The network interface driver ``if_stmac`` is provided by the ``libbsd``. + +USB Host Driver +--------------- + +The USB host driver ``dwc_otg`` is provided by the ``libbsd``. + +SD/MMC Driver +------------- + +The SDMMC driver ``st_sdmmc`` is provided by the ``libbsd``. + +The default initialization is done for the STM32H743I-EVAL 2 board. + +To use different pins, you can create a ``HAL_SD_MspInit()`` function in your +application that overwrites the default one defined in ``RTEMS``. If you don't +have direction lines like on the evaluation board, you can just skip +initializing these pins. + +If you want to use a different number of data lines, another polarity for the +data direction pins, a different voltage or similar, you have to redefine +``st_sdmmc_get_config()`` (normally provided by ``libbsd``) in your application. + +Known limitations: + +* Currently 1.8V signaling is not implemented. Therefore higher speeds like used + for UHS cards are not available. All cards fall back to High Speed transfers. +* The driver uses the IDMA only. MDMA is currently not implemented. For SDMMC1 + that means that the memory buffers can only come from AXI SRAM, QSPI memory, + Flash or the FMC (SDRAM, ...). The internal SRAM1, SRAM2, SRAM3 and SRAM4 are + not supported. SDMMC2 should not have that limitation. See ST AN5200 "Getting + started with STM32H7 Series SDMMC host controller" for more details. + + +How to run RTEMS on the board +----------------------------- +Following few paragraphs save a purpose of simple HOWTO or a quick +starting guide for the users not versed in STM32 toolchain and their +boards workflow. + +Board hardware setup +^^^^^^^^^^^^^^^^^^^^ +Connect board with the host computer using micro-USB cable connected +to micro-USB connector on the board marked with 'ST-LINK V3E' in case of evaluation +and discovery boards or with 'USB PWR' in case of Nucleo board. + +STM32CubeIDE installation +^^^^^^^^^^^^^^^^^^^^^^^^^ +Download and install STM32CubeIDE from +https://www.st.com/en/development-tools/stm32cubeide.html. Install the +software into the user directory. On Linux install with 'sudo' command +to install as a root since as part of the installation USB permissions +rules for ST-Link GDB server are also installed. The reason for +installing into the user directory is that the IDE is based on +Eclipse, which provides +its own update method and this will not work well in case of read-only +access to the installation directory. In case of any troubles consult +installation manual provided by ST here https://www.st.com/resource/en/user_manual/um2563-stm32cubeide-installation-guide-stmicroelectronics.pdf. +Although we will not used full fledged IDE here, the package provides ST-Link GDB Server which will be used for uploading RTEMS binaries to the board +memory. + +STM32CubeProgrammer installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Download and install STM32CubeProgrammer from +https://www.st.com/en/development-tools/stm32cubeprog.html. We will +use this software for board setup required for RTEMS and later when +something goes wrong to delete content of the MCU flash memory. The +software is also internally used by the ST-Link GDB Server from +STM32CubeIDE so it is crucial to have it installed. + +Board ST-Link firmware upgrade +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Download ST-Link board firmware upgrade package from +https://www.st.com/en/development-tools/stsw-link007.html. The +software is distributed in a form of Java jar file for Linux and Mac +OSX and in a form of Windows binary for MS Windows. Unpack it +somewhere and run it with + +.. code-block:: shell + + $ unzip en.stsw-link007-v3-9-3_v3.9.3.zip + $ cd stsw-link007/AllPlatforms + $ java -jar STLinkUpgrade.jar + +Click on *Open in update mode* button and then if *Version* and *Update +to Firmware* version information are different in shown version number/code, click on *Upgrade* +button and wait till upgrade finishes. + +.. note: On Linux you will need to have libusb library installed in + order to make upgrade process working. On Ubuntu 20.04 LTS you can do + that with following command. + +.. code-block:: shell + + $ sudo apt install libusb-1.0-0 + + +Dual core board setup for RTEMS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Current RTEMS BSP supports +running MCU in a single-core mode only on either M7 core or M4 +core. That means that to not leave other core interfering with the +system we either need to upload short infinite loop code to it or we +may switch off the core completely. The second option is what is +described here. The board by default switches on and starts both +cores. Based on chosen BSP variant you may like to switch off other +core with using STMCubeProgrammer tool. +Go to the directory where you have installed STMCubeProgrammer +software and run it with + +.. code-block:: shell + + $ cd bin + $ ./STM32CubeProgrammer + + +.. important:: It is absolutely necessary you will do that from inside the bin + directory where STM32CubeProgrammer binary resides. If you don't, then + programmer UI will crash on attempt to connect to the board. Probable + reason is a bug in the programmer which is not able to correctly locate + its C dynamic library responsible for connecting to the ST-Link board + interface. Version 2.9.0 of the programmer is described here. Other + versions may behave a bit differently. + +When you start the programmer application, the UI window of the programmer will +appear. +Click on green *Connect* button in the right upper corner of +the UI. This will connect programmer to the board. +Then click on *OB* +icon in the left upper corner. Actually this is hidden menu item which you +can un-hide by clicking on menu icon (three horizontal stripes) in the +upper left corner. +When you click on *OB* or *Option bytes* in un-hidden state, then +click on *User Configuration* in the options list and when the user +configuration list opens +unselect preselected *BCM4* item inside it to switch off M4 core or +unselect preselected *BCM7* item to switch off M7 core from +starting up. The action needs to be saved by clicking on *Apply* button +below the option table. + +.. warning:: Be careful! Wrong setup in STM32H7 configuration may result in + *bricked* board. + +Do not forget to disconnect the programmer application from the board by clicking on green *Disconnect* button +in the upper right corner and then close the programmer UI. + +.. important:: If you keep programmer connected then you will not be able + to connect ST-Link GDB server to the board and upload RTEMS binary to + it. + + +STM32CubeIDE ST-Link GDB Server setup +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +In order to use STM provided ST-Link GDB server externally, that is +not from inside the IDE, we need to configure it. Please go to the +directory where you have installed STM32CubeIDE software. Look for +file containing *ST-LINK* string inside its name. Following shell +command sequence shows example about how to find it. + +.. code-block:: shell + + $ cd $HOME/sfw/stm32cubeide_1.8.0 + $ find . -name 'ST-LINK*' + ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin/ST-LINK_gdbserver.sh + ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin/ST-LINK_gdbserver + ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin/ST-LINK_gdbserver.sh + ./plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin/ST-LINK_gdbserver + +Notice that in this particular installation case we already have two +versions of GDB server installed. This is due to fact that version +1.8.0 of the IDE was later upgraded to 1.9.0 version. Anyway, we will choose +to use the latest one, or if there is only one, then the only one +installed. Please go to its *bin* directory. E.g. + +.. code-block:: shell + + $ 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 scroll +down to its end. You will see following comment: + +.. code-block:: none + + ############################################################### + # -cp <path> : Path to STM32CubeProgrammer + # Modify to correct path + # for STM32_Programmer_CLI executable + ############################################################### + -cp + +and here you will need to place path where your STM32CubeProgrammer is +installed directly behind the *-cp* parameter. E.g. + +.. code-block:: none + + ############################################################### + # -cp <path> : Path to STM32CubeProgrammer + # Modify to correct path + # for STM32_Programmer_CLI executable + ############################################################### + -cp /home/karel/sfw/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.linux64_2.0.200.202202231230/tools/bin + +Once you are done with it, you can save the file and close the +editor. Let's verify that GDB server is configured and running well by starting +it inside the shell. Please go inside the directory where +ST-LINK_gdbserver.sh is located and run it by: + +.. code-block:: shell + + $ ./ST-LINK_gdbserver.sh + +If everything is all right and if you have board still connected to +the host computer then you should see output like following: + +.. code-block:: shell + + $ ./ST-LINK_gdbserver.sh + + STMicroelectronics ST-LINK GDB server. Version 6.1.0 + Copyright (c) 2022, STMicroelectronics. All rights reserved. + + Starting server with the following options: + Persistent Mode : Enabled + LogFile Name : debug.log + Logging Level : 31 + Listen Port Number : 61234 + Status Refresh Delay : 15s + Verbose Mode : Disabled + SWD Debug : Enabled + + COM frequency = 24000 kHz + Target connection mode: Default + Reading ROM table for AP 0 @0xe00fefd0 + Hardware watchpoint supported by the target + ST-LINK Firmware version : V3J9M3 + Device ID: 0x450 + PC: 0x8028fa4 + ST-LINK device status: HALT_MODE + ST-LINK detects target voltage = 3.28 V + ST-LINK device status: HALT_MODE + ST-LINK device initialization OK + Stm32Device, pollAndNotify running... + SwvSrv state change: 0 -> 1 + Waiting for connection on port 61235... + Waiting for debugger connection... + Waiting for connection on port 61234... + +In output above you can see ST-Link GDB server waiting for debugger +connection. If this is the case in your case, then you can finish GDB server by hitting +*Ctrl-C* key combination. + +RTEMS BSP samples build and run +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +We will use STM32H747I-DISCO board as an example hereafter. If you use +different board please adjust configuration steps in BSP configuration +accordingly. You should use BSP variant name specified for your +particular board in the table above. + +Generate default configuration for the board: + +.. code-block:: shell + + $ ./waf bspdefaults --rtems-bsps=arm/stm32h747i-disco > stm32h747i-disco.ini + Regenerate build specification cache (needs a couple of seconds)... + +To run basic hello world or ticker samples you do not need to modify +default BSP configuration here as the compilation of basic RTEMS demo samples is +enabled by default. Let's continue with configuration of +the RTEMS source by running following command. Please change the RTEMS +tools installation prefix to suite your installation. + +.. code-block:: shell + + $ ./waf configure --rtems-bsps=arm/stm32h747i-disco --rtems-config=./stm32h747i-disco.ini --rtems-tools=$HOME/workspace/rtems-tools + Setting top to : /home/rtems/workspace/rtems + Setting out to : /home/rtems/workspace/rtems/build + Configure board support package (BSP) : arm/stm32h747i-disco + Checking for program 'arm-rtems6-gcc' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-gcc + Checking for program 'arm-rtems6-g++' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-g++ + Checking for program 'arm-rtems6-ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar + Checking for program 'arm-rtems6-ld' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ld + Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar + Checking for program 'g++, c++' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-g++ + Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar + Checking for program 'gas, gcc' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-gcc + Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar + Checking for program 'gcc, cc' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-gcc + Checking for program 'ar' : /home/rtems/workspace/rtems-tools/bin/arm-rtems6-ar + Checking for asm flags '-MMD' : yes + Checking for c flags '-MMD' : yes + Checking for cxx flags '-MMD' : yes + 'configure' finished successfully (0.454s) + +Build the BSP including samples using *build* command: + +.. code-block:: shell + + $ ./waf build + +the command outputs a lot of information about files being compiled +and ends with output like: + +.. code-block:: shell + + Waf: Leaving directory `/home/rtems/workspace/rtems/build/arm/stm32h747i-disco' + 'build_arm/stm32h747i-disco' finished successfully (12.086s) + +As your RTEMS BSP including samples is compiled, we will proceed with +running the hello world sample on the board now. +Open 3 shell windows for the test on the host computer. Also make sure +board is connected to the computer and is running. It does not matter +if manufacturer's demo is running there or if you navigated to some +demo part and left it there. ST-Link GDB server always takes over the +board when connected to it. + +Start GDB server in the first window by switching to GDB server +directory and running the shell script. This is from testing machine +installation, the path to GDB server will probably look different in your +installation case. + +.. code-block:: shell + + $ cd sfw/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.200.202202231230/tools/bin + $ ./ST-LINK_gdbserver.sh + + STMicroelectronics ST-LINK GDB server. Version 6.1.0 + Copyright (c) 2022, STMicroelectronics. All rights reserved. + + Starting server with the following options: + Persistent Mode : Enabled + LogFile Name : debug.log + Logging Level : 31 + Listen Port Number : 61234 + Status Refresh Delay : 15s + Verbose Mode : Disabled + SWD Debug : Enabled + + COM frequency = 24000 kHz + Target connection mode: Default + Reading ROM table for AP 0 @0xe00fefd0 + Hardware watchpoint supported by the target + ST-LINK Firmware version : V3J9M3 + Device ID: 0x450 + PC: 0x8028fa4 + ST-LINK device status: HALT_MODE + ST-LINK detects target voltage = 3.28 V + ST-LINK device status: HALT_MODE + ST-LINK device initialization OK + Stm32Device, pollAndNotify running... + SwvSrv state change: 0 -> 1 + Waiting for connection on port 61235... + Waiting for debugger connection... + Waiting for connection on port 61234... + +In second shell window you will need to run your terminal program and +connect to the board virtual serial port. Following steps describes +how to do that on the Ubuntu 20.04. The recommended way here is to use minicom. Let's install it +first by: + +.. code-block:: shell + + $ sudo apt install minicom + +And run it with root privileges to be able to reach USB serial port +provided by board: + +.. code-block:: shell + + $ sudo minicom -s + +The minicom is invoked with configuration menu open. Go into the +*Serial port setup* and hit *a* key to select *Serial Device* +setup. Change */dev/modem* from there into */dev/ttyACM0* and hit +*Enter* key. Hit *f* key to change hardware flow control from *Yes* to +*No*. When you are done with it, you can hit *Enter* key to finish +this part of configuration and then scrolls in menu to *Exit* and hit +*Enter* key on it. The minicom will switch to terminal mode with just +provided configuration. + +In the third shell window navigate into the BSP build directory and start +RTEMS GDB with the hello.exe sample. + +.. code-block:: shell + + $ arm-rtems6-gdb build/arm/stm32h747i-disco/testsuites/samples/hello.exe + GNU gdb (GDB) 10.1.90.20210409-git + Copyright (C) 2021 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + Type "show copying" and "show warranty" for details. + This GDB was configured as "--host=x86_64-linux-gnu --target=arm-rtems6". + Type "show configuration" for configuration details. + For bug reporting instructions, please see: + <https://www.gnu.org/software/gdb/bugs/>. + Find the GDB manual and other documentation resources online at: + <http://www.gnu.org/software/gdb/documentation/>. + + For help, type "help". + Type "apropos word" to search for commands related to "word"... + Reading symbols from build/arm/stm32h747i-disco/testsuites/samples/hello.exe... + (gdb) + +Now, you need to connect GDB with the ST's GDB server by: + +.. code-block:: shell + + (gdb) target extended-remote :61234 + Remote debugging using :61234 + 0x08028fa4 in ?? () + (gdb) + +and finally you will need to load hello.exe binary into the board +memory by: + +.. code-block:: shell + + (gdb) load + Loading section .start, size 0x458 lma 0x24000000 + Loading section .text, size 0xfca8 lma 0x24000480 + Loading section .init, size 0xc lma 0x24010128 + Loading section .fini, size 0xfecc lma 0x24010134 + Loading section .rodata, size 0x1aab lma 0x24020000 + Loading section .ARM.exidx, size 0x8 lma 0x24021aac + Loading section .eh_frame, size 0x4 lma 0x24021ab4 + Loading section .init_array, size 0x4 lma 0x24021ab8 + Loading section .fini_array, size 0x4 lma 0x24021abc + Loading section .rtemsroset, size 0x540 lma 0x24021ac0 + Loading section .data, size 0x6a4 lma 0x24022000 + Start address 0x24000400, load size 140923 + Transfer rate: 684 KB/sec, 2562 bytes/write. + (gdb) + +If everything went fine, then you can run the RTEMS binary by using +*cont* GDB command. + +.. note:: Memory address values in the load output in the gdb shows + that we have loaded our application into the AXI + SRAM. Memory addresses will be different when loading into + different part of MCU memory. + +.. code-block:: shell + + (gdb) cont + Continuing. + +Note that this command should never finish. To see the actual output +from RTEMS switch to +the second shell window with minicom (or other terminal emulation +program) running and you should see hello output +there: + +.. code-block:: none + + *** BEGIN OF TEST HELLO WORLD *** + *** TEST VERSION: 6.0.0.50ce036cfbd9807a54af47eb60eadb6a33a9e82d + *** TEST STATE: EXPECTED_PASS + *** TEST BUILD: + *** TEST TOOLS: 10.3.1 20220224 (RTEMS 6, RSB 49e3dac17765fa82ce2f754da839638ee352f95c, Newlib 64b2081) + Hello World + + *** END OF TEST HELLO WORLD *** + + + [ RTEMS shutdown ] + RTEMS version: 6.0.0.50ce036cfbd9807a54af47eb60eadb6a33a9e82d + RTEMS tools: 10.3.1 20220224 (RTEMS 6, RSB 49e3dac17765fa82ce2f754da839638ee352f95c, Newlib 64b2081) + executing thread ID: 0x08a010001 + +Since default RTEMS BSP configuration resets the board after run +immediately you can also see output from the immediately started ST +demo: + +.. code-block:: none + + STM32H747I-DISCO_MB1248: Out Of the Box Demonstration V1.0.1 (Build Aug 22 2019 at 11:56:22) + STM32H747I-DISCO_MB1248: ST Menu Launcher V1.1.0 + CPU running at 400MHz, Peripherals at 100MHz/100Mz + +which is not a problem here at all. Later we can reconfigure BSP to +not reset board to prevent demo output here. + +How to load binary file into the QSPI NOR +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Connect the board to your host computer using micro-USB +cable. Start STM32CubeProgrammer and connect it to the board by +clicking on *Connect* button which is located in the right upper +corner of the programmer application UI. For accessing QSPI connected +memory you will need to configure programmer's external loader which +needs to match your target board. Click on *EL* icon (or *External +loaders*) in the left sidebar menu. Either go thorough the list of +external loaders or just search for your board by typing board +name (or part of the name) into the search bar located on top of the table view. When +you find your board, select it by selecting rectangle in the *Select* +table column. That's what is needed to make programmer ready to +program your board memory. +For uploading file to the board, you need to continue with clicking on +*Erase & programming* menu item in the left sidebar menu. It's second item +from the top. Now, let's select +your file to upload by clicking on *Browse* button and selecting the +file name from your host computer filesystem. The most important thing here is +to specify start address of flashing process. You need to do that by +typing start address into the *Start address* field. + +.. note:: Usually external memory connected to QSPI has 0x90000000 starting + address. + +When all is set you can click on *Start Programming* button. + +.. important:: Cube programmer is very picky about files it shows in the file list. The only recognized suffixes are: elf, bin, hex and + similar. Also do not try to fool programmer by renaming let's say text + file to bin file. It'll detect file type as ascii text and will not + show it in the list of files to flash. So bin file type is really for + media types like avi, jpeg, mpeg or for binary dumps from elf + files. If you need to save text file, convert it to hex file first. diff --git a/user/bsps/arm/xen.rst b/user/bsps/arm/xen.rst index c7085ce..d7538f0 100644 --- a/user/bsps/arm/xen.rst +++ b/user/bsps/arm/xen.rst @@ -42,13 +42,13 @@ The ``ticker.exe`` file can be found in the BSP build tree at: .. code-block:: none - arm-rtems5/c/xen_virtual/testsuites/samples/ticker.exe + arm-rtems@rtems-ver-major@/c/xen_virtual/testsuites/samples/ticker.exe The ``ticker.exe`` elf file must be translated to a binary format. .. code-block:: none - arm-rtems5-objcopy -O binary ticker.exe ticker.bin + arm-rtems@rtems-ver-major@-objcopy -O binary ticker.exe ticker.bin Then place the ``ticker.bin`` file on the dom0 filesystem. diff --git a/user/bsps/arm/xilinx-zynq.rst b/user/bsps/arm/xilinx-zynq.rst index 909b23e..0ac4487 100644 --- a/user/bsps/arm/xilinx-zynq.rst +++ b/user/bsps/arm/xilinx-zynq.rst @@ -1,8 +1,146 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 TBD +.. Copyright (C) 2015, 2020 Chris Johns (chrisj@rtems.org) xilinx-zynq =========== -TODO. +This BSP supports the Xilinx Zynq range of devices. This family of +devices contain the same ARM hard IP and the different parts have +different sizes of programable logic. + +The BSP defaults may need to be adjusted using ``configure`` BSP +options to match the size of memory your board may have. + +Bootloader +---------- + +The bootloader initialises the Zynq device. The Xilinx tool provide an +interface to configure the hardware. This is includes the buses, +clocks, memory and UART board rate. The output of this is called +``ps7_init`` and it a C file. The Xilinx SDK builds a first stage boot +loader (FSBL) using this file. + +The U-Boot boot loader has it's own FSBL called ``MLO`` to initialise +the hardware. + +Clocks +------ + +An application can provide a function called: + +.. code-block:: none + + uint32_t a9mpcore_clock_periphclk(void); + +to return the peripheral clock. Normally this is half the CPU +clock. This function is declared ``weak`` so you can override the +default behaviour by providing it in your application. + +Console +------- + +The console driver for the UARTs will always be initialized to a +baud rate of 115200 with 8 bit characters, 1 stop bit and no parity +bits during start up. +Previous configurations programmed into the hardware by the Xilinx +tools or a bootloader will be overwritten. + +The settings for the console driver can be changed by the user +application through the termios API afterwards. + +Network +------- + +The Cadence network interface driver of LibBSD works on the Xilinx Zynq +platform. The hardware checksum support works on real hardware but does not +seem to be supported on Qemu therefore the default state is to disable +``IFCAP_TXCSUM`` and ``IFCAP_RXCSUM`` and this can be enabled from the shell +with: + +.. code-block:: none + + ifconfig cgem0 rxcsum txcsum + +or with an ``ioctl()`` call to the network interface driver with ``SIOCSIFCAP`` +and the mask ``IFCAP_TXCSUM`` and ``IFCAP_RXCSUM`` set. + +Debugging with xilinx_zynq_a9_qemu +---------------------------------- + +To debug an application add the QEMU options ``-s``. If you need to +debug an initialisation issue also add ``-S``. For example to debug a +networking application you could use: + +.. code-block:: none + + qemu-system-arm -M xilinx-zynq-a9 -m 256M -no-reboot -serial \ + null -serial mon:stdio -nographic \ + -net nic,model=cadence_gem -net vde,id=vde0,sock=/tmp/vde1 \ + -kernel myapp.exe \ + -s -S + +Start GDB with the same executable QEMU is running and connect to the +QEMU GDB server: + +.. code-block:: none + + (gdb) target remote :1234 + +If your application is crashing set a breakpoint on the fatal error +handler: + +.. code-block:: none + + (gdb) b bsp_fatal_extension + +Enter continue to run the application. Running QEMU loads the +executable and initialises the CPU. If the ``-S`` option is provided +the CPU is held in reset. Without the option the CPU runs starting +RTEMS. Either way you are connecting to set up target and all you need +to do is continue: + +.. code-block:: none + + (gdb) c + +If you have a crash and the breakpoint on ``bsp_fatal_extension`` is +hit, load the following a GDB script: + +.. code-block:: none + + define arm-crash + set $code = $arg0 + set $r0 = ((const rtems_exception_frame *) $code)->register_r0 + set $r1 = ((const rtems_exception_frame *) $code)->register_r1 + set $r2 = ((const rtems_exception_frame *) $code)->register_r2 + set $r3 = ((const rtems_exception_frame *) $code)->register_r3 + set $r4 = ((const rtems_exception_frame *) $code)->register_r4 + set $r5 = ((const rtems_exception_frame *) $code)->register_r5 + set $r6 = ((const rtems_exception_frame *) $code)->register_r6 + set $r7 = ((const rtems_exception_frame *) $code)->register_r7 + set $r8 = ((const rtems_exception_frame *) $code)->register_r8 + set $r9 = ((const rtems_exception_frame *) $code)->register_r9 + set $r10 = ((const rtems_exception_frame *) $code)->register_r10 + set $r11 = ((const rtems_exception_frame *) $code)->register_r11 + set $r12 = ((const rtems_exception_frame *) $code)->register_r12 + set $sp = ((const rtems_exception_frame *) $code)->register_sp + set $lr = ((const rtems_exception_frame *) $code)->register_lr + set $pc = ((const rtems_exception_frame *) $code)->register_pc + set $cpsr = ((const rtems_exception_frame *) $code)->register_cpsr + end + +Enter the command: + +.. code-block:: none + + (gdb) arm-crash code + + +Enter ``bt`` to see the stack back trace. + +The script moves the context back to the crash location. You should be +able to view variables and inspect the stack. + +The fatal error handler runs inside an exception context that is not +the one than generated the exception. 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 4b2e749..f99843a 100644 --- a/user/bsps/bsps-aarch64.rst +++ b/user/bsps/bsps-aarch64.rst @@ -1,8 +1,12 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 embedded brains GmbH +.. Copyright (C) 2018 embedded brains GmbH & Co. KG aarch64 (AArch64) ***************** -There are no AArch64 BSPs yet. +.. include:: aarch64/a53.rst +.. include:: aarch64/a72.rst +.. include:: aarch64/xilinx-versal.rst +.. include:: aarch64/xilinx-zynqmp.rst +.. include:: aarch64/raspberrypi4.rst
\ No newline at end of file diff --git a/user/bsps/bsps-arm.rst b/user/bsps/bsps-arm.rst index 5401f67..bd335fa 100644 --- a/user/bsps/bsps-arm.rst +++ b/user/bsps/bsps-arm.rst @@ -1,30 +1,34 @@ .. 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) ********* -.. include:: arm/altera-cyclone-v.rst -.. include:: arm/atsam.rst -.. include:: arm/beagle.rst -.. include:: arm/csb336.rst -.. include:: arm/csb337.rst -.. include:: arm/edb7312.rst -.. include:: arm/gdbarmsim.rst -.. include:: arm/gumstix.rst -.. include:: arm/imx.rst -.. include:: arm/lm3s69xx.rst -.. include:: arm/lpc176x.rst -.. include:: arm/imx.rst -.. include:: arm/lpc32xx.rst -.. include:: arm/raspberrypi.rst -.. include:: arm/realview-pbx-a9.rst -.. include:: arm/rtl22xx.rst -.. include:: arm/smdk2410.rst -.. include:: arm/stm32f4.rst -.. include:: arm/tms570.rst -.. include:: arm/xen.rst -.. include:: arm/xilinx-zynq.rst -.. include:: arm/xilinx-zynqmp.rst +.. toctree:: + + arm/altera-cyclone-v.rst + arm/atsam.rst + arm/beagle.rst + arm/csb336.rst + arm/csb337.rst + arm/edb7312.rst + arm/fvp.rst + arm/gumstix.rst + arm/imx.rst + arm/imxrt.rst + arm/lm3s69xx.rst + arm/lpc176x.rst + arm/lpc24xx.rst + arm/raspberrypi.rst + arm/realview-pbx-a9.rst + arm/rtl22xx.rst + arm/smdk2410.rst + arm/stm32f4.rst + arm/stm32h7.rst + arm/tms570.rst + 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-epiphany.rst b/user/bsps/bsps-epiphany.rst deleted file mode 100644 index 82b05e6..0000000 --- a/user/bsps/bsps-epiphany.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2018 embedded brains GmbH - -epiphany (Epiphany) -******************* - -epiphany_sim -============ - -TODO. diff --git a/user/bsps/bsps-i386.rst b/user/bsps/bsps-i386.rst index a29edf6..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 **** @@ -8,4 +8,421 @@ i386 pc386 ===== -TODO. +This BSP supports a standard Intel/AMD PC on i386 and up CPUs. If run +on a Pentium or above, the TSC register is used for timing calibration +purposes rather than relying entirely on the i8254. +Partial support is implemented for more modern PCs which do not have a +complete complement of legacy peripherals. + +The BSP is able to utilize up to 3 GB of available RAM and up to 16 +CPUs. Hyper-threading is supported, but may not be detected by the +BSP successfully. + +.. note:: BSP capability to detect target hardware SMP details is + limited due to fact the SMP support is implemented based on + Intel Multi-Processor Specification (MPS). Final version of + the specification is version 1.4 which was released on July + 1, 1995. On most newer machines the MPS functionality was + more or less supplanted by more modern ACPI (Advanced + Configuration and Power Interface). Still, on some machine + SMP support may be fragile at least at the platform + detection and initialization state depending on the target + BIOS/ACPI/MPS compatibility implementation. + +There are several BSP variants provided which differ only in the target CPU +optimization. The most general is `pc386` which is tuned for i386. The `pc486` +variant is tuned for i486, `pc585` is tuned for Pentium, `pc586-sse` is tuned +for Pentium processor supporting SSE instructions. Finally `pc686` is tuned +for Pentium Pro processor, but generating only instructions for Pentium +and `pcp4` is tuned and generating instructions for Pentium4 processor +including SSE3 instructions. + + +Build Configuration Options +--------------------------- + +``BSP_PRESS_KEY_FOR_RESET`` + If defined to a non-zero value, then print a message and wait until + any key is pressed before resetting board when application + terminates (disabled by default). + +``BSP_RESET_BOARD_AT_EXIT`` + If defined to a non-zero value, then reset the board when the + application terminates (enabled by default). + +``BSP_PRINT_EXCEPTION_CONTEXT`` + If defined to a non-zero value, then print the exception context + when an unexpected exception occurs (enabled by default). + +``BSP_VERBOSE_FATAL_EXTENSION`` + If defined to a non-zero value, then print more information in case + of a fatal error (enabled by default). + +``BSP_ENABLE_VGA`` + Enables VGA console driver (enabled by default). + +``BSP_ENABLE_COM1_COM4`` + Enables support of COM1 thorough COM4 (enabled by default). + +``USE_COM1_AS_CONSOLE`` + Enforces usage of COM1 as a console device (disabled by default). + +``BSP_ENABLE_IDE`` + Enables legacy IDE driver (enabled by default). + +``IDE_USE_PRIMARY_INTERFACE`` + Allows RTEMS to use storage drive(s) connected to the primary IDE + interface. Disable if (i) the target hardware does not have primary + IDE interface or (ii) it does not have any drive attached to the + primary IDE interface or (iii) there is no need to use drive(s) + attached to the primary IDE interface at all (enabled by default). + +``IDE_USE_SECONDARY_INTERFACE`` + Allows RTEMS to use storage drive(s) connected to the secondary IDE + interface. Enable if (i) the target hardware does have secondary IDE + interface and (ii) there is at least one drive attached to the + secondary IDE interface and (iii) there is a need to use drive(s) + attached to the secondary IDE interface (disabled by default). + +``BSP_VIDEO_80x50`` + Sets the VGA display to 80x50 character mode (disabled by default). + +``CLOCK_DRIVER_USE_TSC`` + Enforces clock driver to use TSC register available on Pentium and + higher class CPUs. If disabled and ``CLOCK_DRIVER_USE_8243`` is + disabled too, then BSP will choose clock driver mechanism itself + during the runtime (disabled by default). + +``CLOCK_DRIVER_USE_8254`` + Enforces clock driver to use 8254 chip. If disabled and + ``CLOCK_DRIVER_USE_TSC`` is disabled too, then BSP will choose clock + driver mechanism itself during the runtime (disabled by default). + +``NUM_APP_DRV_GDT_DESCRIPTORS`` + Defines how many descriptors in GDT may be allocated for the + application or driver usage. + +``USE_CIRRUS_GD5446`` + Enables usage of Cirrus GD5446 graphic card for RTEMS frame-buffer + (disabled by default). + +``USE_VGA`` + Enables usage of generic VGA graphic card for RTEMS frame-buffer + (disabled by default). + +``USE_VBE_RM`` + Enables usage of graphic card implementing VESA BIOS Extensions for + RTEMS frame-buffer (enabled by default). + +``BSP_GDB_STUB`` + Enables GDB support for debugging over serial port (enabled by + default). + +Runtime Options +--------------- +The BSP supports several runtime options. They may be used by either setting +during boot by using target hardware bootloader or by using Qemu's +``-append`` command-line parameter in case BSP application is run +inside the Qemu emulator. + +.. option:: --console=<dev> + + specifies console + device. E.g. ``--console=/dev/com1``. COM device name may + also be followed by a baud rate like ``--console=/dev/com2,19200`` + +The pc386 BSP family uses 9600 as a default baud rate +for console over UART (/dev/comX) with 8 data bits, no parity and 1 stop bit. + +.. option:: --printk=<dev> + + specifies target device for printk/getk + calls. E.g. ``--printk=/dev/vgacons`` + +If the specified console device is not present then suitable fallback +device is selected based on the device order specified in `Console Drivers`. + +.. option:: --video=<mode> + + specifies required video mode. The options applies only to + the systems supporting VESA BIOS Extensions. Choices are + ``auto`` which selects graphic mode automatically or + ``none``/``off`` which disables initialization of the + graphic driver or direct specification of resolution + and/or color depth by + ``<resX>x<resY>[-<bpp>]``. E.g. ``--video=none`` disables + graphic driver. Using ``--video=1280x1024`` sets video + mode to 1280x1024 pixels mode while ``--video=800x600-32`` + sets video mode to 800x600 pixels with 32bit color depth. + +.. option:: --disable-com1-com4 + + disables usage of COM1 thorough COM4. + +.. option:: --gdb=<dev> + + specifies UART device for communication between BSP's + GDB stub and GDB running on a host system. Option accepts device + and baud rate like the ``--console`` option above. + E.g. ``--gdb=/dev/com2,115200`` instructs BSP to use COM2 device + for GDB stub/host communication with the speed of 115200 bauds. + +The default GDB stub/host is similar to console over UART, i.e., +9600 baud rate, 8 data bits, no parity and 1 stop bit. + +.. option:: --gdb-break + + halts BSP execution at a break point in the BSP initialization code + and waits for GDB connection. + +.. option:: --gdb-remote-debug + + outputs the GDB remote protocol data to printk. + +Testing with Qemu +----------------- + +To test with Qemu, we need to: + +- Build / install Qemu (most distributions should have it available on the + package manager). + +Booting RTEMS in Qemu +^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + $ qemu-system-i386 -m 128 -no-reboot -append \ + "--video=off --console=/dev/com1" -nographic -kernel ./hello.exe + +This command boots ``hello.exe`` application located in current +directory and sets Qemu to provide 128MB RAM and to switch both Qemu's +and BSP's video off. + +Booting RTEMS in KVM accelerated Qemu +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +When the Qemu host hardware and OS support KVM, it is possible to use it +to accelerate BSP run by using ``-machine type=q35,accel=kvm`` Qemu option. +Depending on the Qemu host configuration it may or may not require +administrator privileges to run the command. + +.. code-block:: none + + $ sudo qemu-system-i386 -machine type=q35,accel=kvm -m 128 -no-reboot \ + -append "--video=off --console=/dev/com1" -nographic -kernel \ + ./dhrystone.exe + +This command boots ``dhrystone.exe`` application and sets Qemu to use +KVM acceleration. + + +Running on a PC hardware +---------------------- + +There are several ways how to start RTEMS BSP application on the real +PC hardware. + +Booting with GRUB boot-loader +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In case the target machine does already have Linux with GRUB boot +loader installed, then the most easy way to load and boot RTEMS is +to use GRUB. This may be done in following steps: + +(i) prepare RTEMS binary and save it either to Linux + partition/directory accessible from GRUB or to an USB stick. + +(ii) boot machine to GRUB menu. + +.. note:: Some Linux installations hide GRUB menu by default and + quickly continues with booting default Linux option. If this + is the case, then during the boot hold down 'Shift' key to + un-hide the menu. + +(iii) press ``c`` key to get into the GRUB's command-line mode. + +(iv) use ``ls`` command to observe drives and partitions on them. If + unsure, use 'ls' command with drive/partition description to show + the target file system content. E.g. ``ls (hd1,msdos1)/`` will list + files on the second drive, first partition which is formatted + using fat/vfat file-system. + +.. note:: Use `ls (hdX, partY)` without a slash at the end to show + information about the partition. + +(v) use ``multiboot`` command to load the RTEMS application binary for + boot. E.g. ``multiboot (hd1,msdos2)/rtems/ticker.exe`` will load + ticker.exe from the second drive, second partition with fat/vfat + file-system and its rtems directory. + +(vi) use ``boot`` command to boot loaded binary. + +.. note:: Advantage of using GRUB for booting RTEMS is the GRUB's + support for both classical BIOS and UEFI boot. This way + RTEMS may be booted even on UEFI only systems. + +Booting with PXE/iPXE +^^^^^^^^^^^^^^^^ +PXE booting is more complex than GRUB based booting and hence requires +more infrastructure configuration. The booting may be done in two +possible ways: + +(i) using iPXE booted from an USB stick or a hard drive + +It may be done using following steps: + +- Download iPXE ISO image from http://boot.ipxe.org/ipxe.iso +- Either record it to CD/DVD or copy it to an USB stick +- boot from the medium above on the target hardware +- wait for ``Press Ctrl-B for the iPXE command line...`` prompt and once + it appears press ``Ctrl-B`` key. +- use 'dhcp' command to configure network interface card +- use 'boot' command to boot RTEMS application from specified tftp + server. E.g. ``boot tftp://10.0.0.5/hello.exe`` will boot hello.exe + application from the tftp server on host with 10.0.0.5 IP address. + +Whole interaction may look as: + +.. code-block:: none + + Press Ctrl-B for the iPXE command line... + iPXE> dhcp + Configuring (net0 <mac address>)..... ok + iPXE> boot tftp://10.0.0.5/hello.exe + + +(ii) using built in network card's PXE BIOS to boot into iPXE + +This way is more complex and requires network infrastructure +configuration changes which description is out of the scope of this +documentation. Generic steps how to achieve this are: + +- use target hardware BIOS/SETUP to enable PXE booting on the board +- setup network router to announce tftp server and file on it as a + part of the router's BOOTP/DHCP protocol reply. You should use + http://boot.ipxe.org/undionly.kpxe as a payload for non-UEFI based + booting. Put that file into tftp server served/root directory. +- reboot target hardware and it should run network card PXE BIOS which + should obtain IP address from the network router and load + undionly.kpxe file from the tftp server. Once this is done, familiar + iPXE UI appears. Follow steps described in previous paragraph to + boot RTEMS application. + +.. note:: It is not possible to use UEFI based PXE booting. Neither + directly by the network card PXE BIOS nor indirectly by + booting into iPXE. UEFI booting in both cases is not + currently supported. + +Clock Drivers +------------- + +The BSP supports two clock drivers. If there is no build option used +(see `Build Configuration Options`) for selecting particular clock +driver, then the decision which is used is done during the runtime. + +- i8254 based driver. It is used on pre-Pentium CPUs by default. +- TSC register based driver. It is used on Pentium and later CPUs by + default. + +Console Drivers +--------------- + +The BSP console supports device drivers for a variety of devices +including VGA/keyboard and a number of serial ports. The default +console is selected based on which devices are present in the +following order of priority: + +- VGA with PS/2 keyboard +- COM1 thorough COM4 +- Any COM devices on the PCI bus including IO and memory mapped + +PCI-based UART devices are named ``/dev/pcicom<number>`` as they are +probed and found. The numbers sequence starts with 1. E.g. first PCI +UART device found is accessible with ``/dev/pcicom1`` name. + +Besides supporting generic devices above, the BSP also support +specific UART chips. The drivers for those are not initialized +automatically, but requires initialization from the application code: + +- Exar 17d15x (NS16550 compatible multiport PCI UART) + +Frame-Buffer Drivers +-------------------- + +The BSP supports several drivers implementing RTEMS frame-buffer +API. The default driver is for card(s) implementing VESA BIOS +Extensions. Others may be enabled by using appropriate build option +(see `Build Configuration Options`). Available drivers support: + +- generic VGA graphic card +- Cirrus Logic GD5446 +- generic graphic card supporting VESA BIOS Extensions + +Network Interface Drivers +------------------------- + +The network interface drivers are provided by the `libbsd`. + +USB Host Drivers +---------------- + +The USB host drivers are provided by the `libbsd`. + +RTC Drivers +----------- + +There are several real time clock devices supported by drivers in the +BSP. + +- Maxim DS1375 +- Mostek M48T08/M48T18 (Maxim/Dallas Semiconductor DS1643 compatible) +- Motorola MC146818A +- Renesas ICM7170 + +I2C Drivers +----------- +There are several drivers for various I2C bus connected peripherals +supported by the BSP. Supported peripherals are: + +- EEPROM +- Maxim DS1621 temperature sensor +- Semtech SC620 Octal LED Driver + +SPI Drivers +----------- +There are several devices which connect to serial peripheral interfaces +supported by the BSP. + +- M25P40 flash +- FM25L256 fram +- memory devices +- SD card + +Legacy Drivers +-------------- + +The BSP source code provides legacy drivers for storage and network +devices. +The usage of legacy drivers is discouraged and description of such use +is out of the scope of this documentation. Interested users should +consult BSP source code directly but use legacy driver only when it is +not possible to use similar driver provided by `libbsd`. + +Storage Drivers +^^^^^^^^^^^^^^^ +- IDE/ATA +- AM26LV160/M29W160D flash + +Network Drivers +^^^^^^^^^^^^^^^ +- 3Com 3c509 +- 3Com 3c90x (Etherlink XL family) +- Novell NE2000 +- Western Digital WD8003 +- Intel 82586 +- Intel EtherExpress PRO/100 +- Cirrus Logic CS8900 +- DEC/Intel 21140 +- SMC 91111 +- Opencores Ethernet Controller +- National Semiconductor SONIC DP83932 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 60882fb..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) ******************************** @@ -53,7 +53,19 @@ TODO. mcf5329 ======= -TODO. +Overview +-------- + +This BSP is heavily based on the MCF5235 BSP. The MCF5329EVB is a Motorola +evaluation board (Zoom) with a LogicPD MCF5329-10 SODIMM-144 card. The +development kit features the MCF5329 based Fire Engine, as well as a plug-in +system-on-module containing 32 MB of DDR-SDRAM. The board also includes 2 MB of +boot flash, 16 MB of NAND flash, a core frequency of 240MHz, an onboard 800x600 +LCD controller, FEC, USB, uarts, CAN bus, QSPI, I2C, and 10/100 Ethernet. + +You can find the link to MCF5329 Reference Manual below: + +* `MCF5329 Reference Manual <https://www.nxp.com/docs/en/reference-manual/MCF5329RM.pdf>`_ mrm332 ====== @@ -73,7 +85,181 @@ TODO. mvme162 ======= -TODO. +Overview +-------- + +The MVME162 family provides OEMs and solution developers an ideal platform for +embedded monitoring and control apllications it allows an OEM to minimize +engineering expenses while integrating value-added hardware and software +applications onto an off-the-shelf product. In order to provide the wide range +of solutions, the MVME162 allows a variety of MPU, memory, and interface +options such as floating-point, Ethernet, SCSI, and VME. The result is a +variation of the MVME162 which most closely fits the application requirement. + +There are a large number of model variations on this board. This was the first +user submitted BSP and continues to be a fairly popular simply because at one +point it was the highest selling VMEBus board of all time. + +Board Setup +----------- + +We will setup the RTEMS Lab Board initally to proceed further for the setup +of TFTP transfer. + +The env settings are: + +.. code-block:: none + + MPU Clock Speed =25Mhz + 162-Bug>env + Bug or System environment [B/S] = B? + Field Service Menu Enable [Y/N] = N? + Remote Start Method Switch [G/M/B/N] = B? + Probe System for Supported I/O Controllers [Y/N] = Y? + Negate VMEbus SYSFAIL* Always [Y/N] = N? + Local SCSI Bus Reset on Debugger Startup [Y/N] = N? + Local SCSI Bus Negotiations Type [A/S/N] = A? + Industry Pack Reset on Debugger Startup [Y/N] = Y? + Ignore CFGA Block on a Hard Disk Boot [Y/N] = Y? + Auto Boot Enable [Y/N] = N? + Auto Boot at power-up only [Y/N] = Y? + Auto Boot Controller LUN = 00? + Auto Boot Device LUN = 00? + Auto Boot Abort Delay = 15? + Auto Boot Default String [NULL for a empty string] = ? + ROM Boot Enable [Y/N] = N? + ROM Boot at power-up only [Y/N] = Y? + ROM Boot Enable search of VMEbus [Y/N] = N? + ROM Boot Abort Delay = 0? + ROM Boot Direct Starting Address = FF800000? + ROM Boot Direct Ending Address = FFDFFFFC? + Network Auto Boot Enable [Y/N] = N? + Network Auto Boot at power-up only [Y/N] = Y? + Network Auto Boot Controller LUN = 00? + Network Auto Boot Device LUN = 00? + Network Auto Boot Abort Delay = 5? + Network Auto Boot Configuration Parameters Pointer (NVRAM) = FFE0FF00? + Memory Search Starting Address = 00000000? + Memory Search Ending Address = 01000000? + Memory Search Increment Size = 00010000? + Memory Search Delay Enable [Y/N] = N? + Memory Search Delay Address = FFFFD20F? + Memory Size Enable [Y/N] = Y? + Memory Size Starting Address = 00000000? + Memory Size Ending Address = 01000000? + Base Address of Dynamic Memory = 00000000? + Size of Parity Memory = 00000000? + Size of ECC Memory Board #0 = 01000000? + Size of ECC Memory Board #1 = 00000000? + Base Address of Static Memory = FFE00000? + Size of Static Memory = 00020000? + Slave Enable #1 [Y/N] = Y? + Slave Starting Address #1 = 00000000? + Slave Ending Address #1 = 00FFFFFF? + Slave Address Translation Address #1 = 00000000? + Slave Address Translation Select #1 = 00000000? + Slave Control #1 = 03FF? + Slave Enable #2 [Y/N] = N? + Slave Starting Address #2 = 00000000? + Slave Ending Address #2 = 00000000? + Slave Address Translation Address #2 = 00000000? + Slave Address Translation Select #2 = 00000000? + Slave Control #2 = 0000? + Master Enable #1 [Y/N] = Y? + Master Starting Address #1 = 01000000? + Master Ending Address #1 = EFFFFFFF? + Master Control #1 = 0D? + Master Enable #2 [Y/N] = N? + Master Starting Address #2 = 00000000? + Master Ending Address #2 = 00000000? + Master Control #2 = 00? + Master Enable #3 [Y/N] = N? + Master Starting Address #3 = 00000000? + Master Ending Address #3 = 00000000? + Master Control #3 = 00? + Master Enable #4 [Y/N] = N? + Master Starting Address #4 = 00000000? + Master Ending Address #4 = 00000000? + Master Address Translation Address #4 = 00000000? + Master Address Translation Select #4 = 00000000? + Master Control #4 = 00? + Short I/O (VMEbus A16) Enable [Y/N] = Y? + Short I/O (VMEbus A16) Control = 01? + F-Page (VMEbus A24) Enable [Y/N] = Y? + F-Page (VMEbus A24) Control = 02? + ROM Access Time Code = 03? + FLASH Access Time Code = 02? + MCC Vector Base = 05? + VMEC2 Vector Base #1 = 06? + VMEC2 Vector Base #2 = 07? + VMEC2 GCSR Group Base Address = D2? + VMEC2 GCSR Board Base Address = 00? + VMEbus Global Time Out Code = 01? + Local Bus Time Out Code = 02? + VMEbus Access Time Out Code = 02? + IP A Base Address = 00000000? + IP B Base Address = 00000000? + IP C Base Address = 00000000? + IP D Base Address = 00000000? + IP D/C/B/A Memory Size = 00000000? + IP D/C/B/A General Control = 00000000? + IP D/C/B/A Interrupt 0 Control = 00000000? + IP D/C/B/A Interrupt 1 Control = 00000000? + +To setup the Server/Client IP Addresses for the TFTP Transfer, we will use the +NIOT command. NIOT (Network I/O Teach) is a 162-Bug's debugger command commonly +used to setup the Server/Client IP Addresses for the TFTP Transfer. + +The NIOT command goes something like this: + +.. code-block:: none + + 162-Bug>niot + Controller LUN =00? + Device LUN =00? + Node Control Memory Address =FFE10000? + Client IP Address =192.168.1.245? + Server IP Address =192.168.1.92? + Subnet IP Address Mask =255.255.255.0? + Broadcast IP Address =192.168.1.255? + Gateway IP Address =0.0.0.0? + Boot File Name ("NULL" for None) =/mvme162.img? + Argument File Name ("NULL" for None) =? + Boot File Load Address =00020000? + Boot File Execution Address =00020000? + Boot File Execution Delay =00000000? + Boot File Length =00000000? + Boot File Byte Offset =00000000? + BOOTP/RARP Request Retry =00? + TFTP/ARP Request Retry =00? + Trace Character Buffer Address =00000000? + BOOTP/RARP Request Control: Always/When-Needed (A/W)=A? + BOOTP/RARP Reply Update Control: Yes/No (Y/N) =Y? + +Downloading and Executing +-------------------------- +Download from the TFTP server using the 162-Bug's "NBO" +(Network Boot Operating System) command: + +.. code-block:: none + + 162-Bug>nbo + Network Booting from: VME162, Controller 0, Device 0 + Loading: /mvme162.img + + Client IP Address = 192.168.1.245 + Server IP Address = 192.168.1.92 + Gateway IP Address = 0.0.0.0 + Subnet IP Address Mask = 255.255.255.0 + Boot File Name = /mvme162.img + Argument File Name = + + Network Boot File load in progress... To abort hit <BREAK> + + Bytes Received =&356528, Bytes Loaded =&356528 + Bytes/Second =&89132, Elapsed Time =4 Second(s) + +The program will automatically run when download is complete. mvme167 ======= diff --git a/user/bsps/bsps-microblaze.rst b/user/bsps/bsps-microblaze.rst index dbb574f..6fe4891 100644 --- a/user/bsps/bsps-microblaze.rst +++ b/user/bsps/bsps-microblaze.rst @@ -1,8 +1,182 @@ .. 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) +microblaze (MicroBlaze) *********************** -There are no Microblaze BSPs yet. +KCU105 QEMU +=========== + +The basic hardware initialization is performed by the BSP. This BSP supports the +QEMU emulated Xilinx AXI Interrupt Controller v4.1. + +Boot via ELF +------------ + +The executable image is booted by QEMU in ELF format. + +Clock Driver +------------ + +The clock driver supports the QEMU emulated Xilinx AXI Timer v2.0. It is +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. 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 +-------------- + +Support for networking is provided by the libbsd library. Network interface +configuration is extracted from the device tree binary which, by default, is +in `<bsp/microblaze-dtb.h> <https://git.rtems.org/rtems/tree/bsps/microblaze/microblaze_fpga/include/bsp/microblaze-dtb.h>`_. +The device tree source for the default device tree is at `dts/system.dts <https://git.rtems.org/rtems/tree/bsps/microblaze/microblaze_fpga/dts/system.dts>`_. + +To replace the default device tree with your own, assuming ``my_device_tree.dts`` +is the name of your device tree source file, first you must convert your device +tree to .dtb format. + +.. code-block:: none + + $ dtc -I dts -O dtb my_device_tree.dts > my_device_tree.dtb + +The device tree blob, ``my_device_tree.dtb``, can now be converted to a C file. +The name ``system_dtb`` is significant as it is the name expected by the BSP. + +.. code-block:: none + + $ rtems-bin2c -C -A 8 -N system_dtb my_device_tree.dtb my_dtb + +The ``BSP_MICROBLAZE_FPGA_DTB_HEADER_PATH`` BSP configuration option can then be +set to the path of the resulting source file, ``my_dtb.c``, in the waf INI file +to include it in the BSP build. + +.. code-block:: none + + 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 +------------------- + +A ``.dtb`` (device tree blob) file should be provided to QEMU via the ``-hw-dtb`` +option. In the example command below, the device tree blob comes from the Xilinx +Petalinux KCU105 MicroBlaze BSP (https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/embedded-design-tools.html). + +Executables generated by this BSP can be run using the following command: + +.. code-block:: none + + $ qemu-system-microblazeel -no-reboot -nographic -M microblaze-fdt-plnx -m 256 \ + -serial mon:stdio -display none -hw-dtb system.dtb -kernel example.exe + +Debugging with QEMU +------------------- + +To debug an application, add the option ``-s`` to make QEMU listen for GDB +connections on port 1234. Add the ``-S`` option to also stop execution until +a connection is made. + +For example, to debug the hello sample and break at ``Init``, first start QEMU. + +.. code-block:: none + + $ qemu-system-microblazeel -no-reboot -nographic -M microblaze-fdt-plnx -m 256 \ + -serial mon:stdio -display none -hw-dtb system.dtb -kernel \ + build/microblaze/kcu105_qemu/testsuites/samples/hello.exe -s -S + +Then start GDB and connect to QEMU. + +.. code-block:: none + + $ microblaze-rtems@rtems-ver-major@-gdb build/microblaze/kcu105_qemu/testsuites/samples/hello.exe + (gdb) target remote localhost:1234 + (gdb) break Init + (gdb) continue + +KCU105 +====== + +The basic hardware initialization is performed by the BSP. This BSP supports the +Xilinx AXI Interrupt Controller v4.1. + +This BSP was tested using the Xilinx Kintex UltraScale FPGA KCU105 board +configured with the default Petalinux KCU105 MicroBlaze BSP. The defaults may +need to be adjusted using BSP configuration options to match the memory layout +and configuration of your board. + +Clock Driver +------------ + +The clock driver supports the Xilinx AXI Timer v2.0. It is 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 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 +--------- + +The following debugging procedure was used for debugging RTEMS applications +running on the Xilinx KCU105 board using GDB. + +First send an FPGA bitstream to the board using OpenOCD. + +.. code-block:: none + + $ openocd -f board/kcu105.cfg -c "init; pld load 0 system.bit; exit" + +After the board has been programmed, start the Vivado ``hw_server`` application +to serve as the debug server. Leave it running in the background for the rest of +the process. + +.. code-block:: none + + $ tools/Xilinx/Vivado/2020.2/bin/hw_server + +With the debug server running, connect to the debug server with GDB, load the +application, and debug as usual. By default the GDB server listens on port 3002. + +.. code-block:: none + + $ microblaze-rtems@rtems-ver-major@-gdb example.exe + (gdb) target extended-remote localhost:3002 + (gdb) load + (gdb) break Init + (gdb) continue 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 80edfae..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) ***************** @@ -36,10 +36,10 @@ image. Use the following commands: .. code-block:: none - powerpc-rtems5-objcopy -O binary -R .comment -S ticker.exe rtems + powerpc-rtems@rtems-ver-major@-objcopy -O binary -R .comment -S ticker.exe rtems gzip -9 -f rtems - powerpc-rtems5-ld -o ticker.boot bootloader.o --just-symbols=ticker.exe -b binary rtems.gz -T ppcboot.lds -no-warn-mismatch - powerpc-rtems5-objcopy -O binary ticker.boot ticker.bin + powerpc-rtems@rtems-ver-major@-ld -o ticker.boot bootloader.o --just-symbols=ticker.exe -b binary rtems.gz -T ppcboot.lds -no-warn-mismatch + powerpc-rtems@rtems-ver-major@-objcopy -O binary ticker.boot ticker.bin mpc55xxevb ========== @@ -107,7 +107,7 @@ image. Use the following commands: .. code-block:: none - powerpc-rtems5-objcopy -O binary app.exe app.bin + powerpc-rtems@rtems-ver-major@-objcopy -O binary app.exe app.bin gzip -9 -f -c app.bin > app.bin.gz mkimage -A ppc -O linux -T kernel -a 0x4000 -e 0x4000 -n RTEMS -d app.bin.gz app.img diff --git a/user/bsps/bsps-riscv.rst b/user/bsps/bsps-riscv.rst index 0799ad6..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 13 variants: +**Each variant in this first group corresponds to a GCC multilib option with +different RISC-V standard extensions.** * rv32i @@ -26,31 +27,36 @@ This BSP offers 13 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. + +The reference platforms for the rv* variants include the QEMU `virt` and +`spike` machines and the Spike RISC-V ISA simulator. + +**The BSP also provides the following variants for specific hardware targets:** -* frdme310arty +* frdme310arty - The reference platform for this variant is the Arty FPGA board + with the SiFive Freedom E310 reference design. -Each variant corresponds to a GCC multilib. A particular variant reflects an -ISA with ABI and code model choice. +* mpfs64imafdc - The reference platform for this variant is the Microchip + PolarFire SoC Icicle Kit. -The basic hardware initialization is not performed by the BSP. A boot loader -with device tree support must be used to start the BSP, e.g. BBL. The BSP must -be started im machine mode. +* kendrytek210 - The reference platform for this variant is the Kendryte K210 + SoC on the Sipeed MAiX BiT or Maixduino board. -The reference platform for this BSP is the Qemu `virt` machine. Build Configuration Options --------------------------- -The following options are available at the configure command line. +The following options can be used in the BSP section of the ``waf`` +configuration INI file. The ``waf`` defaults can be used to inspect the values. ``BSP_PRESS_KEY_FOR_RESET`` If defined to a non-zero value, then print a message and wait until pressed @@ -67,31 +73,51 @@ The following options are available at the configure command line. ``BSP_FDT_BLOB_SIZE_MAX`` The maximum size of the device tree blob in bytes (default is 65536). +``BSP_DTB_IS_SUPPORTED`` + If defined to a non-zero value, then the device tree blob is embedded in + the BSP. + +``BSP_DTB_HEADER_PATH`` + 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. Interrupt Controller -------------------- @@ -109,20 +135,341 @@ 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 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 +and spike machines. For instance, to run the ``rv64imafdc`` BSP with the +following "config.ini" file. + +.. code-block:: none + + [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 ``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 device tree blob is embedded in the ``mpfs64imafdc`` BSP variant by default +with the ``BSP_DTB_IS_SUPPORTED`` enabled and the DTB header path +``BSP_DTB_HEADER_PATH`` is set to bsp/mpfs-dtb.h. + +**SMP test procedure for the Microchip PolarFire Icicle Kit:** + +The "config.ini" file. + +.. code-block:: none + + [riscv/mpfs64imafdc] + BUILD_TESTS = True + RTEMS_POSIX_API=True + RTEMS_SMP = True + BSP_START_COPY_FDT_FROM_U_BOOT=False + BSP_VERBOSE_FATAL_EXTENSION = False + +Build RTEMS. + +.. code-block:: shell + + $ ./waf configure --prefix=$HOME/rtems-start/rtems/@rtems-ver-major@ + $ ./waf + +Convert .exe to .elf file. + +.. code-block:: shell + + $ 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>`_. + +* Copy `smp01.elf` file to the HSS/tools/hss-payload-generator/test directory. + +* Go to hss-payload-generator source directory. + +.. code-block:: shell + + $ cd hart-software-services/tools/hss-payload-generator + +* Edit test/uboot.yaml file for the hart entry points and correct name of the + binary file. + +.. code-block:: none + + set-name: 'PolarFire-SoC-HSS::RTEMS' + hart-entry-points: {u54_1: '0x1000000000', u54_2: '0x1000000000', u54_3: '0x1000000000', u54_4: '0x1000000000'} + payloads: + test/smp01.elf: {exec-addr: '0x1000000000', owner-hart: u54_1, secondary-hart: u54_2, secondary-hart: u54_3, secondary-hart: u54_4, priv-mode: prv_m, skip-opensbi: true} + +* Generate payload + +.. code-block:: shell + + $ ./hss-payload-generator -c test/uboot.yaml payload.bin + +Once the payload binary is generated, it should be copied to the eMMC/SD. + +`FPGA design with HSS programming file <https://github.com/polarfire-soc/polarfire-soc-documentation/blob/master/boards/mpfs-icicle-kit-es/updating-icicle-kit/updating-icicle-kit-design-and-linux.md>`_. + +Program the eMMC/SD with the payload binary. + +* Power Cycle the Microchip PolarFire Icicle Kit and stop at the HSS. + +* type "mmc" and then "usbdmsc" on the HSS terminal(UART0). + +* Load the payload.bin from the Host PC. + +.. code-block:: shell + + $ sudo dd if=payload.bin of=/dev/sdb bs=512 + +Reset the Microchip PolarFire SoC Icicle Kit. + +Serial terminal UART1 displays the SMP example messages + +.. code-block:: none + + *** BEGIN OF TEST SMP 1 *** + *** TEST VERSION: 6.0.0.ef33f861e16de9bf4190a36e4d18062c7300986c + *** TEST STATE: EXPECTED_PASS + *** TEST BUILD: RTEMS_POSIX_API RTEMS_SMP + *** TEST TOOLS: 12.1.1 20220622 (RTEMS 6, RSB 3cb78b0b815ba05d17f5c6 + 5865d246a8333aa087, Newlib ea99f21) + + CPU 3 start task TA0 + CPU 2 running Task TA0 + CPU 3 start task TA1 + CPU 1 running Task TA1 + CPU 3 start task TA2 + CPU 0 running Task TA2 + + *** 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: + +* noel32im + +* noel32imafd + +* noel64imac + +* noel64imafd + +* 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. + +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. + +Build Configuration Options +--------------------------- + +The following options can be used in the BSP section of the ``waf`` +configuration INI file. The ``waf`` defaults can be used to inspect the values. + +``BSP_CONSOLE_USE_INTERRUPTS`` + Use the Termios interrupt mode in the console driver (true by default). + +``BSP_FDT_BLOB_SIZE_MAX`` + The maximum size of the device tree blob in bytes (262144 by default). + +``RISCV_CONSOLE_MAX_APBUART_DEVICES`` + The maximum number of APBUART devices supported by the console driver + (2 by default). + +``RISCV_RAM_REGION_BEGIN`` + The begin of the RAM region for linker command file (0x0 by default). + +``RISCV_MAXIMUM_EXTERNAL_INTERRUPTS`` + The maximum number of external interrupts supported by the BSP (64 by + default). + griscv ====== 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 7d98c50..325c7fa 100644 --- a/user/bsps/bsps-sparc.rst +++ b/user/bsps/bsps-sparc.rst @@ -1,21 +1,100 @@ .. 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) ******************** + + +.. _BSP_sparc_erc32: + erc32 ===== TODO. +.. _BSP_sparc_leon2: + leon2 ===== -TODO. +This BSP supports LEON2 systems, in particular the `Microchip AT697F +<https://www.microchip.com/en-us/product/AT697F>`_. The following +default build configurations are provided: + +* leon2 - A generic LEON2 system with memory at 0x4000000. + +* at697f - For the AT697F. Built with ``-mcpu=leon -mfix-at697f``. + +The BSP contains UART, timer, and interrupt controller drivers. +Drivers for PCI are available through the :ref:`driver manager <BSP_sparc_leon3_drv_mgr>`. + +.. _BSP_sparc_leon3: leon3 ===== -TODO. +This BSP supports the LEON3/4/5 systems from Cobham Gaisler. +The following default build configurations are provided: + +* leon3 - A generic `LEON3/4/5 <https://www.gaisler.com/leon5>`_ system with memory at 0x4000000. + +* ut700 - For the `UT700 <https://caes.com/product/ut700>`_. Built with ``-mcpu=leon3 -mfix-ut700``. + +* ut699 - For the `UT699 <https://caes.com/product/ut699>`_. Built with ``-mcpu=leon -mfix-ut699``. + +* gr712rc - For the `GR712RC <https://www.gaisler.com/gr712rc>`_. Built with ``-mcpu=leon3 -mfix-gr712rc``. + +* gr740 - For the `GR740 <https://www.gaisler.com/gr740>`_. Memory located at address 0x0. + +The BSP contains UART, timer, and interrupt controller drivers. Drivers for additional +peripherals are available through the driver manager. + +.. _BSP_sparc_leon3_drv_mgr: + +Driver Manager +-------------- + +The leon3 BSP includes an optional driver manager that handles drivers and +devices on the AMBA and PCI Plug & Play buses. The driver manager can either +be initialized manually by the user, or started automatically on startup by +setting the ``RTEMS_DRVMGR_STARTUP`` option. It can be configured to +automatically instantiate a driver for each hardware device found. + +Drivers for the following devices are provided and handled via the driver manager: + +* SpaceWire (GRSPW, GRSPW2, GRSPW2_DMA) +* SpaceWire Router (GRSPWROUTER) +* SpaceWire Time Distribution Protocol (SPWTDP) +* CAN - non-DMA (OCCAN) and DMA (GRCAN, GRCANFD) +- GPIO (GRGPIO) +- L2 Cache (L2CACHE) +- IOMMU (GRIOMMU) +- ADC/DAC (GRADCDAC) +- Timers (GPTIMER, GRTIMER) +- 1553 BC, RT and BM support (GR1553B) +- I2C Master (I2CMST) +- PCI (GRPCI2, GRPCI, PCIF) +- Memory Controller (MCTRL) +- Memory Scrubber (MEMSCRUB) +- Pulse Width Modulation Generator (GRPWM) +- CCSDS/ECSS Telemetry Encoder/Decoder (GRTM/GRTC) +- CSDS Time Manager (GRCTM) +- Ethernet (GRETH 10/100/1000) (requires network stack) +- Performance counters (L4STAT) +- Serial Peripheral Interface (AHBSTAT) +- AHB Status (AHBSTAT) + +Build Configuration Options +--------------------------- + +The following options can be used in the BSP section of the ``waf`` +configuration INI file. The ``waf`` defaults can be used to inspect the values. + +``CONSOLE_USE_INTERRUPTS`` + Use the Termios interrupt mode in the console driver (false by default). + +``RTEMS_DRVMGR_STARTUP`` + Enable the Driver Manager at startup (false by default). 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 eefffab..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 ****** @@ -20,7 +20,7 @@ in the RTEMS testsuite. Build Configuration Options --------------------------- -There are no options available to ``configure`` at build time, at the moment. +There are no BSP configuration options available at build time. Testing with QEMU ----------------- diff --git a/user/bsps/index.rst b/user/bsps/index.rst index 0c3b2f6..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: @@ -27,7 +27,6 @@ You can see the current BSP list in the RTEMS sources by asking RTEMS with: bsps-aarch64 bsps-arm bsps-bfin - bsps-epiphany bsps-i386 bsps-lm32 bsps-m68k diff --git a/user/deployment/index.rst b/user/deployment/index.rst new file mode 100644 index 0000000..d1315af --- /dev/null +++ b/user/deployment/index.rst @@ -0,0 +1,426 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2022 Chris Johns + +.. _BSPs: + +Deployment +********** +.. index:: Deployment +.. index:: packages + +Deployment is a process companies, organizations or teams use to +control and manage delivery of RTEMS tools, kernels and third party +libraries. Deployed tools, kernels and libraries are packaged and +controlled so the same tools and libraries are used in all phases of a +project. + +The Quick Start guide details how tools are built using the RSB. The +tools are installed on your development computer and available for you +to build applications. That build can be viewed as the simplest form +of deployment because it is simple and easy however it does not +scale. Building the tools and kernel on each development machine in a +project or company is time consuming, difficult to get right and +costly to audit. + +This section covers the building of tools, kernels and third party +libraries using the RSB for deployment. Custom RSB buildset files are +supported across releases giving you an easy update path. The RSB can +generate a single tarfile for any prefix without needing to install +the pieces built helping ease integration with packaging systems and +continuous integration (CI) for automated workflows. + +RSB Deployment +-------------- + +The RSB provides support for deployment using custom buildset files. A +custom buildset file resides outside the RSB and can build tools for a +number of architectures and kernels for BSPs. Deployment can include +third party libraries if a single BSP is being built. + +The RSB ``--no-install`` option builds the tools and kernel without +the final installation phase. A prefix that is not accessible when +running the RSB can be used. This is important if a CI flow is being +used. + +The buildset tar file option ``--bset-tar-file`` packages the build's +staging directory tree into a single tar file. The tar file can be +used as the input source to a packaging system. + +Buildset configuration files can be tested by adding the ``--dry-run`` +option to the ``sb-set-builder`` command line. + +The buildset examples that follow assume the prefix path used does not +exist or is not writable and the environment path does not include any +RTEMS tools. + +Deployment Repository +^^^^^^^^^^^^^^^^^^^^^ + +Create a repository to hold a project's buildset configuration +files: + +.. code-block:: none + + $ mkdir a-project + $ cd a-project + $ git init + +Add the RSB as a sub-module: + +.. code-block:: none + + $ git submodule add git://git.rtems.org/rtems-source-builder.git + +Create a configuration directory: + +.. code-block:: none + + $ mkdir config + $ git add config + +Tools Configuration +^^^^^^^^^^^^^^^^^^^ + +This example will build a single tool set with a local configuration +file. + +Create a configuration file for the ``project``: + +.. code-block:: none + + $ vi config/project-tools.bset + +Add the following to the buildset configuration file: + +.. code-block:: none + + # + # Project Tools + # + @rtems-ver-major@/rtems-aarch64 + +Commit the changes to the repository: + +.. code-block:: none + + $ git add config/project-tools.bset + $ git commit -m "Add project aarch64 tools buildset" + +Build a tarfile containing the tools using the RSB submodule: + +.. code-block:: none + + $ ./rtems-source-builder/source-builder/sb-set-builder \ + --prefix=/opt/project --log=project.txt \ + --bset-tar-file --no-install \ + project-tools + +Once the build has finished the ``tar`` directory will contain the +``project`` tools in a tarfile: + +.. code-block:: none + + $ ls tar + project-tools.tar.bz2 + +Inspect the tarfile to check the path matches the prefix used to build +the tools (sizes may vary): + +.. code-block:: none + + $ tar Jtvf tar/project-tools.tar.bz2 | less + drwxr-xr-x 0 chris eng 0 Sep 6 14:27 opt/project/bin/ + -rwxr-xr-x 0 chris eng 1320888 Sep 6 14:20 opt/project/bin/aarch64-rtems@rtems-ver-major@-addr2line + -rwxr-xr-x 0 chris eng 1358688 Sep 6 14:20 opt/project/bin/aarch64-rtems@rtems-ver-major@-ar + -rwxr-xr-x 0 chris eng 2381976 Sep 6 14:20 opt/project/bin/aarch64-rtems@rtems-ver-major@-as + -rwxr-xr-x 0 chris eng 1328440 Sep 6 14:27 opt/project/bin/aarch64-rtems@rtems-ver-major@-c++ + -rwxr-xr-x 0 chris eng 1316240 Sep 6 14:20 opt/project/bin/aarch64-rtems@rtems-ver-major@-c++filt + -rwxr-xr-x 0 chris eng 1328440 Sep 6 14:27 opt/project/bin/aarch64-rtems@rtems-ver-major@-cpp + -rwxr-xr-x 0 chris eng 60792 Sep 6 14:20 opt/project/bin/aarch64-rtems@rtems-ver-major@-elfedit + -rwxr-xr-x 0 chris eng 1328440 Sep 6 14:27 opt/project/bin/aarch64-rtems@rtems-ver-major@-g++ + -rwxr-xr-x 0 chris eng 1328440 Sep 6 14:27 opt/project/bin/aarch64-rtems@rtems-ver-major@-gcc + -rwxr-xr-x 0 chris eng 1328440 Sep 6 14:27 opt/project/bin/aarch64-rtems@rtems-ver-major@-gcc-12.1.1 + -rwxr-xr-x 0 chris eng 48568 Sep 6 14:27 opt/project/bin/aarch64-rtems@rtems-ver-major@-gcc-ar + -rwxr-xr-x 0 chris eng 48568 Sep 6 14:27 opt/project/bin/aarch64-rtems@rtems-ver-major@-gcc-nm + -rwxr-xr-x 0 chris eng 48576 Sep 6 14:27 opt/project/bin/aarch64-rtems@rtems-ver-major@-gcc-ranlib + ..... + +Tools and Kernel +^^^^^^^^^^^^^^^^ + +This example builds a single tool set and an RTEMS kernel for a BSP +using a buildset defined BSP settings. + +We use the same ``a-project`` repository from the previous example and +add a new configuration. Add a configuration file to build the tools +and a BSP: + +.. code-block:: none + + $ vi config/project-tools-bsp.bset + +Add the following to the buildset configuration file and save: + +.. code-block:: none + + # + # Project Tools and BSP + # + %define with_rtems_bsp aarch64/xilinx_versal_aiedge + %define with_rtems_bspopts BSP_XILINX_VERSAL_NOCACHE_LENGTH=0x4000000 \ + BSP_XILINX_VERSAL_RAM_LENGTH=0x200000000 + @rtems-ver-major@/rtems-aarch64 + @rtems-ver-major@/rtems-kernel + +The configuration provides BSP options. Commit the changes to the +repository: + +.. code-block:: none + + $ git add config/project-tools-bsp.bset + $ git commit -m "Add project tools and BSP buildset" + +Build a tarfile of the tools and BSP using the RSB submodule: + +.. code-block:: none + + $ ./rtems-source-builder/source-builder/sb-set-builder \ + --prefix=/opt/project --log=project.txt \ + --bset-tar-file --no-install \ + project-tools-bsp + +A buildset configuration file that uses buildset BSP defines is +limited to a single architecture and the tools built need to match the +architecture of the BSP. + +You can specify more than one BSP to be built. An updated +configuration could be: + +.. code-block:: none + + %define with_rtems_bsp aarch64/xilinx_versal_aiedge \ + aarch64/xilinx_zynqmp_lp64_zu3eg + +This is useful when deploying more than one BSP. If you need multiple +architectures and BSPs consider the Tools and Kernel With Config +example. + +Buildset BSP options are applied to all BSPs in the BSP list. If they +are specific to a BSP only specify a single BSP in the BSP define. + +RTEMS 5 supports this type of buildset file. + +Tools and Kernel with Config +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This example builds tool sets for different architectures and multiple +BSPs for the architectures using a kernel configuration INI file. + +Tools for the ``arch64`` and ``arm`` architectures are built and three +BSPs each with different options. + +We use the same ``a-project`` repository from the previous example and +add the new configurations. Add a configuration file to build the +tools and BSPs: + +.. code-block:: none + + $ vi config/project-tools-bsp-config.bset + +Add the following to the buildset configuration file and save: + +.. code-block:: none + + # + # Project Tools and BSPs + # + %define with_rtems_bsp_config config/project-bsps.ini + @rtems-ver-major@/rtems-aarch64 + @rtems-ver-major@/rtems-arm + @rtems-ver-major@/rtems-kernel + +Add a kernel configuration INI file: + +.. code-block:: none + + $ vi config/project-bsps.bset + +Add the following to the kernel configuration INI file and save: + +.. code-block:: none + + # + # Project BSPs + # + [DEFAULT] + RTEMS_POSIX_API = True + BUILD_SAMPLES = True + BUILD_TESTS = False + + [aarch64/xilinx_versal_aiedge] + BSP_XILINX_VERSAL_NOCACHE_LENGTH = 0x4000000 + BSP_XILINX_VERSAL_RAM_LENGTH = 0x200000000 + + [aarch64/xilinx_zynqmp_lp64_zu3eg] + RTEMS_SMP = True + + [arm/xilinx_zynq_zc706] + RTEMS_SMP = True + BSP_XILINX_VERSAL_NOCACHE_LENGTH = 0x4000000 + BSP_XILINX_VERSAL_RAM_LENGTH = 0x200000000 + +Commit the changes to the repository: + +.. code-block:: none + + $ git add config/project-tools-bsp-config.bset + $ git add config/project-bsps.ini + $ git commit -m "Add project tools and BSPs buildset and kernel config" + +Build a tarfile of the tools and BSPs using the RSB submodule: + +.. code-block:: none + + $ ./rtems-source-builder/source-builder/sb-set-builder \ + --prefix=/opt/project --log=project.txt \ + --bset-tar-file --no-install \ + project-tools-bsp-config + +Tools, Kernel and Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Third party libraries can be built as part of a single RSB +configuration if only one BSP is built at a time. The RSB support for +building packages does not support building for multiple BSPs. + +We use the same ``a-project`` repository from the previous example and +add a new configuration. Add a configuration file to build the tools, +BSPs and LibBSD: + +.. code-block:: none + + $ vi config/project-aarch64-tools-bsp-libbsd.bset + +Add the following to the buildset configuration file and save: + +.. code-block:: none + + # + # Project Tools, BSP and LibBSD + # + %define with_rtems_bsp aarch64/xilinx_versal_aiedge + %define with_rtems_bspopts BSP_XILINX_VERSAL_NOCACHE_LENGTH=0x4000000 \ + BSP_XILINX_VERSAL_RAM_LENGTH=0x200000000 + 6/rtems-aarch64 + 6/rtems-kernel + 6/rtems-libbsd + +Commit the changes to the repository: + +.. code-block:: none + + $ git add config/project-aarch64-tools-bsp-libbsd.bset + $ git commit -m "Add project aarch64 tools, BSP and libbsd" + +Build a tarfile of the tools, BSP and LibBSD using the RSB +submodule: + +.. code-block:: none + + $ ./rtems-source-builder/source-builder/sb-set-builder \ + --prefix=/opt/project --log=project.txt \ + --bset-tar-file --no-install \ + project-aarch64-tools-bsp-libbsd + +The tarfile can be reviewed to see the BSP libraries built (sizes may vary): + +.. code-block:: none + + $ tar jtvf tar/project-aarch64-tools-bsp-libbsd.tar.bz2 | \ + grep -e '\.a$' | grep -e 'xilinx_versal_aiedge' + -rw-r--r-- 0 chris eng 138936312 Sep 7 14:58 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/libbsd.a + -rw-r--r-- 0 chris eng 686190 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/libdebugger.a + -rw-r--r-- 0 chris eng 164086 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/libftpd.a + -rw-r--r-- 0 chris eng 107560 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/libftpfs.a + -rw-r--r-- 0 chris eng 978812 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/libjffs2.a + -rw-r--r-- 0 chris eng 412354 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/libmghttpd.a + -rw-r--r-- 0 chris eng 2099962 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/librtemsbsp.a + -rw-r--r-- 0 chris eng 29693496 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/librtemscpu.a + -rw-r--r-- 0 chris eng 435236 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/librtemscxx.a + -rw-r--r-- 0 chris eng 141234 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/librtemsdefaultconfig.a + -rw-r--r-- 0 chris eng 856514 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/librtemstest.a + -rw-r--r-- 0 chris eng 159004 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/libtelnetd.a + -rw-r--r-- 0 chris eng 137386 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/libtftpfs.a + -rw-r--r-- 0 chris eng 476692 Sep 7 14:56 opt/project/aarch64-rtems@rtems-ver-major@/xilinx_versal_aiedge/lib/libz.a + +Tools, Kernel with Config and Packages +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This example builds the tools, kernel and LibBSD using an RSB +configuration file and a kernel configuration file. The kernel +configuration provides easier kernel and BSP option management. + +Third party libraries can be built as part of a single RSB +configuration if only one BSP is built at a time. The RSB support for +building packages does not support building for multiple BSPs. + +We use the same ``a-project`` repository from the previous example and +add a new configuration. Add a configuration file to build the tools, +BSPs and LibBSD: + +.. code-block:: none + + $ vi config/project-aarch-tools-bsp-libbsd-config.bset + +Add the following to the buildset configuration file and save: + +.. code-block:: none + + # + # Project Tools, BSP and LibBSD + # + %define with_rtems_bsp_config config/project-aarch64-bsp.ini + 6/rtems-aarch64 + 6/rtems-kernel + 6/rtems-libbsd + +Add a kernel configuration INI file: + +.. code-block:: none + + $ vi config/project-aarch64-bsp.bset + +Add the following kernel configuration INI file and save: + +.. code-block:: none + + # + # Project Versal AI Edge BSP + # + [DEFAULT] + RTEMS_POSIX_API = True + BUILD_SAMPLES = True + BUILD_TESTS = False + + [aarch64/xilinx_versal_aiedge] + BSP_XILINX_VERSAL_NOCACHE_LENGTH = 0x4000000 + BSP_XILINX_VERSAL_RAM_LENGTH = 0x200000000 + +Commit the changes to the repository: + +.. code-block:: none + + $ git add config/project-aarch64-tools-bsp-libbsd-config.bset + $ git add config/project-aarch64-bsp.ini + $ git commit -m "Add project aarch64 tools, BSP (with config) and libbsd" + +Build the tarfile of the tools, BSP and LibBSD using the RSB +submodule: + +.. code-block:: none + + $ ./rtems-source-builder/source-builder/sb-set-builder \ + --prefix=/opt/project --log=project.txt \ + --bset-tar-file --no-install \ + project-aarch64-tools-bsp-libbsd-config diff --git a/user/exe/initialization.rst b/user/exe/initialization.rst index cfe39d6..1100006 100644 --- a/user/exe/initialization.rst +++ b/user/exe/initialization.rst @@ -82,20 +82,19 @@ system is based on the `FreeBSD SYSINT Framework 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:: +handlers. The following shows the initialization handlers for the Hello World +sample application in the RTEMS kernel's testsuite: .. code-block:: none - $ rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe - RTEMS Executable Info 5.5416cfa39dd6 - $ rtems-exeinfo --init arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe - exe: arm-rtems5/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe + $ rtems-exeinfo --init arm-rtems@rtems-ver-major@/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe + RTEMS Executable Info @rtems-ver-major@.5416cfa39dd6 + exe: arm-rtems@rtems-ver-major@/c/xilinx_zynq_zedboard/testsuites/samples/hello.exe Compilation: Producers: 2 | GNU AS 2.31.1: 14 objects - | GNU C11 7.3.0 20180125 (RTEMS 5, RSB e55769c64cf1a201588565a5662deafe3f1ccdcc, Newlib 103b055035fea328f8bc7826801760fb1c055683): 284 objects + | GNU C11 7.3.0 20180125 (RTEMS @rtems-ver-major@, RSB e55769c64cf1a201588565a5662deafe3f1ccdcc, Newlib 103b055035fea328f8bc7826801760fb1c055683): 284 objects Common flags: 4 | -march=armv7-a -mthumb -mfpu=neon -mfloat-abi=hard diff --git a/user/exe/loader.rst b/user/exe/loader.rst index c11f363..fdc54a8 100644 --- a/user/exe/loader.rst +++ b/user/exe/loader.rst @@ -458,9 +458,9 @@ into the base image. .. code-block:: none - $ sparc-rtems5-gcc -mcpu=cypress foo.o -lrtemsbsp -lrtemscpu -o foo.pre - $ rtems-syms -e -C sparc-rtems5-gcc -c "-mcpu=cypress" -o foo-sym.o foo.pre - $ sparc-rtems5-gcc -mcpu=cypress foo.o foo-sym.o -lrtemsbsp -lrtemscpu -o foo.exe + $ sparc-rtems@rtems-ver-major@-gcc -mcpu=cypress foo.o -lrtemsbsp -lrtemscpu -o foo.pre + $ rtems-syms -e -C sparc-rtems@rtems-ver-major@-gcc -c "-mcpu=cypress" -o foo-sym.o foo.pre + $ sparc-rtems@rtems-ver-major@-gcc -mcpu=cypress foo.o foo-sym.o -lrtemsbsp -lrtemscpu -o foo.exe The link command line steps in this example are not complete. @@ -486,8 +486,8 @@ file. First create the symbol table's executable object file: .. code-block:: none - $ sparc-rtems5-gcc -mcpu=cypress foo.o -lrtemsbsp -lrtemscpu -o foo.exe - $ rtems-syms -C sparc-rtems5-gcc -c "-mcpu=cypress" -o foo-sym.o foo.exe + $ sparc-rtems@rtems-ver-major@-gcc -mcpu=cypress foo.o -lrtemsbsp -lrtemscpu -o foo.exe + $ rtems-syms -C sparc-rtems@rtems-ver-major@-gcc -c "-mcpu=cypress" -o foo-sym.o foo.exe The link command line steps in this example are not complete. @@ -632,7 +632,7 @@ in a library with a single command. .. code-block:: none - $ sparc-rtems5-strip libc.a + $ sparc-rtems@rtems-ver-major@-strip libc.a Large Memory ------------ @@ -837,22 +837,33 @@ Architectures The following architectures are supported: + - AArch64 - ARM - Blackfin - H8300 - Intel x86 (i386) - LM32 - M68K + - MicroBlaze - MIPS - Moxie - PowerPC - SPARC - V850 +AArch64 +^^^^^^^ + +The AArch64 relocation backend supports veneers which is trampolines. + +The veneer implementation is two instructions and a 64bit target address +making the overhead 16 bytes for each veneer. The performance overhead is two +instructions. + ARM ^^^ -The ARM relocation backend supports veneers which is trampolines. +The ARM relocation backend supports veneers. The veneer implementation is a single instruction and a 32bit target address making the overhead 8 bytes for each veneer. The performance overhead is a 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/index.rst b/user/hosts/index.rst index 5588339..29de1ce 100644 --- a/user/hosts/index.rst +++ b/user/hosts/index.rst @@ -15,11 +15,11 @@ development computer, more often called the host computer. These are typically your desktop machine or a special build server. All RTEMS tools and runtime libraries are built from source on your host machine. The RTEMS Project does not maintain binary builds of the tools. This differs to what you normally -experience with host operating systems, and it is, however this approach works -well. RTEMS is not a host operating system and it is not a -distrbution. Deploying binary packages for every possible host operating system -is too big a task for the RTEMS Project and it is not a good use of core -developer time. Their time is better spent making RTEMS better and faster. +experience with host operating systems however this approach works well. RTEMS +is not a host operating system and it is not a distrbution. Deploying binary +packages for every possible host operating system is too big a task for the +RTEMS Project and it is not a good use of core developer time. Their time is +better spent making RTEMS better and faster. The RTEMS Project's aim is to give you complete freedom to decide on the languages used in your project, which version control system, and the build @@ -37,14 +37,16 @@ engineer a development environment that suites you. The basic specs are: RTEMS makes no demands on graphics. -If you are using a VM or your host computer is not a fast modern machine do not -be concerned. The tools may take longer to build than faster hardware however -building tools is something you do once. Once the tools and RTEMS is built all -your time can be spent writing and developing your application. Over an hour -can happen and for the ARM architecture and with all BSPs it can be many hours. +If you are using a VM or your host computer is not a fast modern machine do +not be concerned. The tools may take longer to build than faster hardware +however building tools is something you do once. Once the tools and RTEMS are +built all your time can be spent writing and developing your application. It +may take longer than an hour for the ARM architecture and with all BSPs it can +be many hours. .. toctree:: + python os posix macos 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/os.rst b/user/hosts/os.rst index 4bb873e..49d7e7e 100644 --- a/user/hosts/os.rst +++ b/user/hosts/os.rst @@ -79,4 +79,4 @@ proven over the years to be difficult to manage in production systems. $ git checkout -t origin/4.11 - Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS. + Branches are available for the 4.9, 4.10, 4.11 and 5 versions of RTEMS. diff --git a/user/hosts/posix.rst b/user/hosts/posix.rst index b46497c..d79e183 100644 --- a/user/hosts/posix.rst +++ b/user/hosts/posix.rst @@ -74,13 +74,29 @@ provide a manual override: CentOS ~~~~~~ -The following packages are required on a minimal CentOS 6.3 64bit installation: +The following packages are required on a minimal CentOS 6.3 or CentOS 7 +64-bit installation: .. code-block:: none - # yum install autoconf automake binutils gcc gcc-c++ gdb make patch \ + # yum install autoconf automake binutils gcc gcc-c++ gdb make patch pax \ bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git +On CentOS 8, the ``pax`` command is now provided by the ``spax`` package, +you need to enable the PowerTools repository. and use Python3. On a +fresh install, the following commands should install everything you +need for RTEMS development: + +.. code-block:: none + + # dnf install yum-utils + # dnf config-manager --set-enabled PowerTools + # dnf update + # dnf groupinstall "Development Tools" + # dnf install python3 python3-pip python3-setuptools python3-devel + # dnf install texinfo spax + # alternatives --set python /usr/bin/python3 + The minimal CentOS distribution is a specific DVD that installs a minimal system. If you use a full system some of these packages may have been installed. @@ -121,23 +137,23 @@ prefix under your home directory as recommended and end up on the SD card. Ubuntu ~~~~~~ -The latest version is Ubuntu 18.04.1 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 git \ - unzip pax bison flex texinfo unzip python3-dev libpython-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 libpython-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: .. code-block:: none - $ sudo apt-get install python-dev + $ sudo apt-get install python git It is likely necessary that you will have to enable the Ubuntu Source Repositories. Users have suggested the following web pages which have @@ -163,8 +179,19 @@ than the usual zlib-dev): openSUSE ~~~~~~~~ -This has been reported to work but no instructions were provided. This is an -opportunity to contribute. Please submit any guidance you can provide. +The RTEMS Source Builder has been tested on openSUSE Leap 15.4 64bit. +Starting with a clean install with source repositories enabled, the following +zypper command installs the required packages: + +.. code-block:: none + + # sudo zypper in -t pattern devel_C_C++ devel_python3 + +In addition, the following command can set python3 as the default python interpreter: + +.. code-block:: none + + # sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 1 .. _FreeBSD: @@ -172,36 +199,44 @@ FreeBSD ------- The RTEMS Source Builder has been tested on FreeBSD 9.1, 10.3, 11 and -12 64bit version. You need to install some ports. They are: +12 64bit versions. You need to install some ports. They are: + +.. code-block:: none + + # pkg install -y python + # pkg install -y gsed + +For FreeBSD 13, you will need to install the packages listed above, as well as +the following additional ones. They are: .. code-block:: none - # cd /usr/ports - # portinstall --batch lang/python27 + # pkg install -y bison texinfo gmake binutils + +FreeBSD's default C compiler is LLVM and installing the host's GCC compiler +package may break building GCC. We recommend you do not install the GCC +package and you use the default C compiler. If you wish to build Windows (mingw32) tools please install the following ports: .. code-block:: none - # cd /usr/ports - # portinstall --batch devel/mingw32-binutils devel/mingw32-gcc - # portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads + # pkg install -y mingw32-binutils mingw32-gcc + # pkg install -y mingw32-zlib mingw32-pthreads -The +zlip+ and +pthreads+ ports for MinGW32 are used for builiding a Windows +The *zlip* and *pthreads* ports for MinGW32 are used when builiding a Windows QEMU. -If you are on FreeBSD 10.0 and you have pkgng installed you can use 'pkg -install' rather than 'portinstall'. - -We recommend you run as root the following command to speed up Python -3's subprocess support: +Check if your kernel has a ``/dev/fd`` directory. If it does not we recommend +you run as root the following command to speed up Python 3's subprocess +support: .. code-block:: none # mount -t fdescfs none /dev/fd -This speeds up closing file descriptors when creating subprocesses. +The support speeds up closing file descriptors when creating subprocesses. .. _NetBSD: diff --git a/user/hosts/python.rst b/user/hosts/python.rst new file mode 100644 index 0000000..7da0f1c --- /dev/null +++ b/user/hosts/python.rst @@ -0,0 +1,137 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 Chris Johns <chrisj@rtems.org> + +.. _host-os: + +Python +====== + +RTEMS uses Python in a range of host tools for users and +developer. RTEMS supports: + +#. Python3 and Python2 for user tools, + +#. Python3 for developer tools. + +Python2 is now **end of life** however the RTEMS Project will continue to +provide support for its user commands. We do this to support older host +operating systems some users may be forced to use. At some point the +project will drop support for Python2 so we recommend users look at ways to +transition to Python3 if it is not easily available. + +Developers of RTEMS are required to have Python3 available. RTEMS tools used +by developers for the development and maintenance of RTEMS are Python3 only. + +All RTEMS Tools that can be invoked from the command line start with the +following line: + +.. code-block:: + + #! /usr/bin/env python + +The ``env`` command is available on all POSIX host operating systems and it +searches the ``$PATH`` environment variable for the ``python`` command invoking +it with the script as the first argument. This means you need to have a +suitable ``python`` command on your host to run the RTEMS user tools. Not all +hosts provide a ``python`` command. If your host does not you need to find a +way to provide one. The following are some examples you can use to solve this +problem. + +Python2 by default always provides a ``python`` command. + +Virtual Environment +~~~~~~~~~~~~~~~~~~~ + +Python3 provides virtual environment support. This is a great way to manage +Python on a single host. You can have a number of virtual environments with a +different mix of installed Python packages with different versions that do not +clash. + +Virtual environment always provide a ``python`` command. This makes it ideal +if your host only provides Python3 and there is no default ``python`` command. + +A virtual environment is created once and when you need to use it you activate +it and when finished you deactivate it. + +The following shows how to create a virtual environment using different +methods. You can select the method that best suites you. + +To create a virtual environment using the Python3 ``venv`` module: + +.. code-block:: none + + python3 -m venv rtems-py + +To create a virtual environment for a specific version of Python3 you +can enter the command: + +.. code-block:: none + + python3.7 -m venv rtems-py + +You can also install the ``virtualenv`` package on your host if it is +avaliable then enter the following create command: + +.. code-block:: none + + virtualenv rtems-py + +To activate the virtual environment: + +.. code-block:: none + + . rtems-py/bin/activate + +You will see your prompt change to reflect the virtual environment you +have active. To check if you now have a ``python`` command enter: + +.. code-block:: none + + type python + +The output will be something similar to the following: + +.. code-block:: none + + (rtems-py) $ type python + python is /home/chris/development/rtems-py/bin/python + +Symbolic Link +~~~~~~~~~~~~~ + +If your host does not provide the ``python`` command you can add a symbolic +link to it. + +.. note:: + + We recommend you do not add the symbolic link in any of your operating + system controlled directories as it is changing your operating system. + +We suggest you add the symbolic link to a directory under your home directory +adding that directory to your environment's ``PATH`` variable. The following +commands show how to do this: + +.. code-block:: none + + cd + mkdir bin + cd bin + ln -s `command -v python3` python + export PATH=$HOME/bin:$PATH + +.. note:: + + You will need to modify your shell's initialization scripts to make the + ``PATH`` change permanent. + +Directly Invoking Python +~~~~~~~~~~~~~~~~~~~~~~~~ + +It is valid to specifically invoke any python script directly. To do this +simply prepend the specific version of python you wish to use. For example to +run the ``waf`` build system command with Python3 use: + +.. code-block:: none + + python3 ./waf diff --git a/user/hosts/windows.rst b/user/hosts/windows.rst index fac1366..fd7ff55 100644 --- a/user/hosts/windows.rst +++ b/user/hosts/windows.rst @@ -156,6 +156,7 @@ The packages we require are: * python * mingw-w64-x86_64-python2 * mingw-w64-x86_64-gcc +* flex * git * bison * cvs @@ -176,7 +177,7 @@ Install the packages using ``pacman``: .. code-block:: none $ pacman -S python mingw-w64-x86_64-python2 mingw-w64-x86_64-gcc \ - bison cvs diffutils git make patch tar texinfo unzip + bison flex cvs diffutils git make patch tar texinfo unzip resolving dependencies... looking for conflicting packages... .... output shortened for brevity .... diff --git a/user/index.rst b/user/index.rst index 0e644c9..5b7f3ce 100644 --- a/user/index.rst +++ b/user/index.rst @@ -10,15 +10,18 @@ RTEMS User Manual (|version|). .. topic:: Copyrights and License + | |copy| 2020 Niteesh Babu + | |copy| 2020 Utkarsh Rai | |copy| 2019 Vijay Kumar Banerjee | |copy| 2018 Amaan Cheval | |copy| 2018 Marçal Comajoan Cara + | |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, 2019 Chris Johns - | |copy| 2012 Gedare Bloom + | |copy| 2012, 2022 Chris Johns + | |copy| 2012, 2020 Gedare Bloom | |copy| 1988, 2018 On-Line Applications Research Corporation (OAR) .. include:: ../common/license.rst @@ -34,14 +37,18 @@ RTEMS User Manual (|version|). support/index hosts/index installation/index + deployment/index hardware/index + bld/index bsps/index exe/index testing/index tracing/index + migration/index + tools/index rsb/index diff --git a/user/installation/developer.rst b/user/installation/developer.rst index 541e04b..8acd68c 100644 --- a/user/installation/developer.rst +++ b/user/installation/developer.rst @@ -34,8 +34,8 @@ you can do this without needing to be root. You can also use The location used to install the tools and kernel is called the `prefix`. It is best to have a `prefix` for each different version of RTEMS you are using. If -you are using RTEMS 4.11 in production it is not a good idea to install a -development version of 5 over the top. A separate `prefix` for each version +you are using RTEMS 5 in production it is not a good idea to install a +development version of 6 over the top. A separate `prefix` for each version avoids this. The RTEMS tool chain changes less often than the RTEMS kernel. One method of @@ -84,7 +84,7 @@ requires: $ cd rsb $ ./source-builder/sb-check - RTEMS Source Builder - Check, 5 (089327b5dcf9) + RTEMS Source Builder - Check, @rtems-ver-major@ (089327b5dcf9) Environment is ok If you are unsure how to specify the build set for the architecture you wish to @@ -93,58 +93,102 @@ build, just ask the tool: .. code-block:: none $ ../source-builder/sb-set-builder --list-bsets <1> - RTEMS Source Builder - Set Builder, v4.11.0 + RTEMS Source Builder - Set Builder, 6 (7d80719f7472) Examining: config - Examining: ../source-builder/config <2> - 4.10/rtems-all.bset <3> - 4.10/rtems-arm.bset <4> - 4.10/rtems-autotools.bset - 4.10/rtems-avr.bset - 4.10/rtems-bfin.bset - 4.10/rtems-h8300.bset - 4.10/rtems-i386.bset - 4.10/rtems-lm32.bset - 4.10/rtems-m32c.bset - 4.10/rtems-m32r.bset - 4.10/rtems-m68k.bset - 4.10/rtems-mips.bset - 4.10/rtems-nios2.bset - 4.10/rtems-powerpc.bset - 4.10/rtems-sh.bset - 4.10/rtems-sparc.bset - 4.11/rtems-all.bset - 4.11/rtems-arm.bset - 4.11/rtems-autotools.bset - 4.11/rtems-avr.bset - 4.11/rtems-bfin.bset - 4.11/rtems-h8300.bset - 4.11/rtems-i386.bset - 4.11/rtems-lm32.bset - 4.11/rtems-m32c.bset - 4.11/rtems-m32r.bset - 4.11/rtems-m68k.bset - 4.11/rtems-microblaze.bset - 4.11/rtems-mips.bset - 4.11/rtems-moxie.bset - 4.11/rtems-nios2.bset - 4.11/rtems-powerpc.bset - 4.11/rtems-sh.bset - 4.11/rtems-sparc.bset - 4.11/rtems-sparc64.bset - 4.11/rtems-v850.bset - 4.9/rtems-all.bset - 4.9/rtems-arm.bset - 4.9/rtems-autotools.bset - 4.9/rtems-i386.bset - 4.9/rtems-m68k.bset - 4.9/rtems-mips.bset - 4.9/rtems-powerpc.bset - 4.9/rtems-sparc.bset + Examining: ../source-builder/config <2> + Examining: ../bare/config + 6/rtems-aarch64.bset + 6/rtems-all.bset <3> + 6/rtems-arm.bset <4> + 6/rtems-base.bset + 6/rtems-bfin.bset + 6/rtems-default.bset + 6/rtems-i386.bset + 6/rtems-kernel.bset + 6/rtems-libbsd.bset + 6/rtems-llvm.bset + 6/rtems-lm32.bset + 6/rtems-m68k.bset + 6/rtems-microblaze.bset + 6/rtems-mips.bset + 6/rtems-moxie.bset + 6/rtems-net-legacy.bset + 6/rtems-nios2.bset + 6/rtems-or1k.bset + 6/rtems-packages.bset + 6/rtems-powerpc.bset + 6/rtems-riscv.bset + 6/rtems-sh.bset + 6/rtems-sparc.bset + 6/rtems-sparc64.bset + 6/rtems-tools.bset + 6/rtems-v850.bset + 6/rtems-x86_64.bset + 7/rtems-aarch64.bset + 7/rtems-all.bset + 7/rtems-arm.bset + 7/rtems-base.bset + 7/rtems-bfin.bset + 7/rtems-default.bset + 7/rtems-i386.bset + 7/rtems-lm32.bset + 7/rtems-m68k.bset + 7/rtems-microblaze.bset + 7/rtems-mips.bset + 7/rtems-moxie.bset + 7/rtems-nios2.bset + 7/rtems-or1k.bset + 7/rtems-powerpc.bset + 7/rtems-riscv.bset + 7/rtems-sh.bset + 7/rtems-sparc.bset + 7/rtems-sparc64.bset + 7/rtems-v850.bset + 7/rtems-x86_64.bset + bsps/atsamv.bset + bsps/beagleboneblack.bset + bsps/erc32.bset + bsps/gr712rc.bset + bsps/gr740.bset + bsps/imx7.bset + bsps/pc.bset + bsps/qoriq_e500.bset + bsps/qoriq_e6500_32.bset + bsps/qoriq_e6500_64.bset + bsps/raspberrypi2.bset + bsps/xilinx_zynq_zc702.bset + bsps/xilinx_zynq_zc706.bset + bsps/xilinx_zynq_zedboard.bset + databases/sqlite.bset + devel/autotools-base.bset + devel/autotools-internal.bset + devel/autotools.bset + devel/capstone.bset + devel/dtc.bset + devel/libtool.bset + devel/libusb.bset + devel/or1ksim.bset + devel/qemu-couverture.bset + devel/qemu-xilinx.bset + devel/qemu.bset + devel/sis.bset + devel/spike.bset + devel/swig.bset + ftp/curl.bset gnu-tools-4.6.bset - rtems-4.10-base.bset <5> - rtems-4.11-base.bset - rtems-4.9-base.bset - rtems-base.bset <5> + gnu-tools-4.8.2.bset + graphics/freetype2.bset + graphics/graphics-all.bset + graphics/libjpeg.bset + graphics/libpng.bset + graphics/libtiff.bset + graphics/microwindows.bset + graphics/nxlib.bset + graphics/t1lib.bset + lang/gcc491.bset + net-mgmt/net-snmp.bset + net/lwip.bset + net/ntp.bset .. topic:: Items: @@ -152,142 +196,15 @@ build, just ask the tool: 2. The paths inspected. See :ref:`Configuration`. - 3. A build set to build all RTEMS 4.10 supported architectures. + 3. A build set to build all RTEMS @rtems-ver-major@ supported architectures. - 4. The build set for the ARM architecture on RTEMS 4.10. - - 5. Support build set file with common functionality included by other build - set files. + 4. The build set for the ARM architecture on RTEMS @rtems-ver-major@. Build a tool chain for the SPARC architecture. We are using the SPARC -architecture because GDB has a good simulator that lets us run and test the -samples RTEMS builds by default. The current development version -is `5` and is on master: - -.. code-block:: none +architecture because GDB has a good simulator that lets us run and +test the samples RTEMS builds by default. The development version is +one more than ``@rtems-ver-major@` and is on the ``master`` branch: - $ cd rtems - $ ../source-builder/sb-set-builder --prefix=/usr/home/chris/development/rtems/5 5/rtems-sparc - RTEMS Source Builder - Set Builder, 5 (089327b5dcf9) - Build Set: 5/rtems-sparc - Build Set: 5/rtems-autotools.bset - Build Set: 5/rtems-autotools-internal.bset - config: tools/rtems-autoconf-2.69-1.cfg - package: autoconf-2.69-x86_64-linux-gnu-1 - Creating source directory: sources - download: ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz -> sources/autoconf-2.69.tar.gz - downloading: sources/autoconf-2.69.tar.gz - 1.8MB of 1.8MB (100%) - building: autoconf-2.69-x86_64-linux-gnu-1 - config: tools/rtems-automake-1.12.6-1.cfg - package: automake-1.12.6-x86_64-linux-gnu-1 - download: ftp://ftp.gnu.org/gnu/automake/automake-1.12.6.tar.gz -> sources/automake-1.12.6.tar.gz - downloading: sources/automake-1.12.6.tar.gz - 2.0MB of 2.0MB (100%) - Creating source directory: patches - download: https://git.rtems.org/rtems-tools/plain/tools/5/automake/automake-1.12.6-bugzilla.redhat.com-1239379.diff -> patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff - downloading: patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff - 408.0 bytes of 408.0 bytes (100%) - building: automake-1.12.6-x86_64-linux-gnu-1 - cleaning: autoconf-2.69-x86_64-linux-gnu-1 - cleaning: automake-1.12.6-x86_64-linux-gnu-1 - Build Set: Time 0:00:12.713221 - Build Set: 5/rtems-autotools-base.bset - config: tools/rtems-autoconf-2.69-1.cfg - package: autoconf-2.69-x86_64-linux-gnu-1 - building: autoconf-2.69-x86_64-linux-gnu-1 - reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-linux-gnu-1.txt - reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-linux-gnu-1.xml - config: tools/rtems-automake-1.12.6-1.cfg - package: automake-1.12.6-x86_64-linux-gnu-1 - building: automake-1.12.6-x86_64-linux-gnu-1 - reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-linux-gnu-1.txt - reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-linux-gnu-1.xml - installing: autoconf-2.69-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5 - installing: automake-1.12.6-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5 - cleaning: autoconf-2.69-x86_64-linux-gnu-1 - cleaning: automake-1.12.6-x86_64-linux-gnu-1 - Build Set: Time 0:00:09.105363 - Build Set: Time 0:00:21.822083 - config: devel/expat-2.1.0-1.cfg - package: expat-2.1.0-x86_64-linux-gnu-1 - download: http://downloads.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz -> sources/expat-2.1.0.tar.gz - redirect: https://vorboss.dl.sourceforge.net/project/expat/expat/2.1.0/expat-2.1.0.tar.gz - downloading: sources/expat-2.1.0.tar.gz - 549.4kB of 549.4kB (100%) - building: expat-2.1.0-x86_64-linux-gnu-1 - reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-linux-gnu-1.txt - reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-linux-gnu-1.xml - config: tools/rtems-binutils-2.29-1.cfg - package: sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1 - download: ftp://ftp.gnu.org/gnu/binutils/binutils-2.29.tar.bz2 -> sources/binutils-2.29.tar.bz2 - downloading: sources/binutils-2.29.tar.bz2 - 27.7MB of 27.7MB (100%) - download: https://devel.rtems.org/raw-attachment/ticket/3091/0001-Fix-Binutils-2.29-PR21884.patch -> patches/0001-Fix-Binutils-2.29-PR21884.patch - downloading: patches/0001-Fix-Binutils-2.29-PR21884.patch - 8.8kB of 8.8kB (100%) - building: sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1 - reporting: tools/rtems-binutils-2.29-1.cfg -> sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1.txt - reporting: tools/rtems-binutils-2.29-1.cfg -> sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1.xml - config: tools/rtems-gcc-7.2.0-newlib-2.5.0.20170922-1.cfg - package: sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1 - download: https://ftp.gnu.org/gnu/gcc/gcc-7.2.0/gcc-7.2.0.tar.xz -> sources/gcc-7.2.0.tar.xz - downloading: sources/gcc-7.2.0.tar.xz - 59.4MB of 59.4MB (100%) - download: https://gcc.gnu.org/git/?p=gcc.git;a=commitdiff_plain;h=62ffbcb7502f0ff88ff7566cd6d7c59c0483ecc0 -> patches/gcc-62ffbcb7502f0ff88ff7566cd6d7c59c0483ecc0.patch - downloading: patches/gcc-62ffbcb7502f0ff88ff7566cd6d7c59c0483ecc0.patch - 1.8kB - download: https://gcc.gnu.org/git/?p=gcc.git;a=blobdiff_plain;f=gcc/config.gcc;h=593631849bb5e0df5cc4ff42c1a1cc34b7eec2f8;hp=a9196cd26d9ec24c2e3f6026f63348cae3734861;hb=e840389000b8339a63bee56d8b3...<see log> -> patches/gcc-593631849bb5e0df5cc4ff42c1a1cc34b7eec2f8.patch - downloading: patches/gcc-593631849bb5e0df5cc4ff42c1a1cc34b7eec2f8.patch - 806.0 bytes - download: https://gcc.gnu.org/git/?p=gcc.git;a=blobdiff_plain;f=gcc/config/rs6000/rtems.h;h=7ea9ebdb77b6a9b7060ad2362318e0e12b9058ae;hp=8a62fdcbaf321d616021c4c396619b7f56cf5ed2;hb=e840389000b8339a...<see log> -> patches/gcc-7ea9ebdb77b6a9b7060ad2362318e0e12b9058ae.patch - downloading: patches/gcc-7ea9ebdb77b6a9b7060ad2362318e0e12b9058ae.patch - 3.2kB - download: ftp://sourceware.org/pub/newlib/newlib-2.5.0.20170922.tar.gz -> sources/newlib-2.5.0.20170922.tar.gz - downloading: sources/newlib-2.5.0.20170922.tar.gz - 17.3MB of 17.3MB (100%) - download: https://devel.rtems.org/raw-attachment/ticket/2514/0001-RTEMS-Self-contained-POSIX-objects.patch -> patches/0001-RTEMS-Self-contained-POSIX-objects.patch - downloading: patches/0001-RTEMS-Self-contained-POSIX-objects.patch - 5.7kB of 5.7kB (100%) - download: https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;a=patch;h=c165a27c0147471977377acd8918ab3b446f947a -> patches/newlib-cygwin-git-c165a27c0147471977377acd8918ab3b446f947a.patch - downloading: patches/newlib-cygwin-git-c165a27c0147471977377acd8918ab3b446f947a.patch - 986.0 bytes - download: https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;a=patch;h=ce189d8afef720b0977b5cae7f9eabf5d49b530c -> patches/newlib-cygwin-git-ce189d8afef720b0977b5cae7f9eabf5d49b530c.patch - downloading: patches/newlib-cygwin-git-ce189d8afef720b0977b5cae7f9eabf5d49b530c.patch - 3.4kB - download: https://ftp.gnu.org/gnu/mpfr/mpfr-3.1.4.tar.bz2 -> sources/mpfr-3.1.4.tar.bz2 - downloading: sources/mpfr-3.1.4.tar.bz2 - 1.2MB of 1.2MB (100%) - download: https://ftp.gnu.org/gnu/mpc/mpc-1.0.3.tar.gz -> sources/mpc-1.0.3.tar.gz - downloading: sources/mpc-1.0.3.tar.gz - 654.2kB of 654.2kB (100%) - download: https://ftp.gnu.org/gnu/gmp/gmp-6.1.0.tar.bz2 -> sources/gmp-6.1.0.tar.bz2 - downloading: sources/gmp-6.1.0.tar.bz2 - 2.3MB of 2.3MB (100%) - building: sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1 - reporting: tools/rtems-gcc-7.2.0-newlib-2.5.0.20170922-1.cfg -> sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1.txt - reporting: tools/rtems-gcc-7.2.0-newlib-2.5.0.20170922-1.cfg -> sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1.xml - config: tools/rtems-gdb-8.0.1-1.cfg - package: sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1 - download: http://ftp.gnu.org/gnu/gdb/gdb-8.0.1.tar.xz -> sources/gdb-8.0.1.tar.xz - downloading: sources/gdb-8.0.1.tar.xz - 18.7MB of 18.7MB (100%) - download: https://gaisler.org/gdb/gdb-8.0.1-sis-leon2-leon3.diff -> patches/gdb-8.0.1-sis-leon2-leon3.diff - downloading: patches/gdb-8.0.1-sis-leon2-leon3.diff - 224.5kB of 224.5kB (100%) - building: sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1 - reporting: tools/rtems-gdb-8.0.1-1.cfg -> sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1.txt - reporting: tools/rtems-gdb-8.0.1-1.cfg -> sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1.xml - config: tools/rtems-tools-5-1.cfg - package: rtems-tools-HEAD-1 - Creating source directory: sources/git - git: clone: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git - git: reset: git://git.rtems.org/rtems-tools.git - git: fetch: git://git.rtems.org/rtems-tools.git -> sources/git/rtems-tools.git - git: checkout: git://git.rtems.org/rtems-tools.git => HEAD - git: pull: git://git.rtems.org/rtems-tools.git - building: rtems-tools-HEAD-1 - reporting: tools/rtems-tools-5-1.cfg -> rtems-tools-HEAD-1.txt - reporting: tools/rtems-tools-5-1.cfg -> rtems-tools-HEAD-1.xml - config: tools/rtems-kernel-5.cfg - package: sparc-rtems5-kernel-5-1 - building: sparc-rtems5-kernel-5-1 - reporting: tools/rtems-kernel-5.cfg -> sparc-rtems5-kernel-5-1.txt - reporting: tools/rtems-kernel-5.cfg -> sparc-rtems5-kernel-5-1.xml - installing: expat-2.1.0-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5 - installing: sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5 - installing: sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5 - installing: sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1 -> /usr/home/chris/development/rtems/5 - installing: rtems-tools-HEAD-1 -> /usr/home/chris/development/rtems/5 - installing: sparc-rtems5-kernel-5-1 -> /usr/home/chris/development/rtems/5 - cleaning: expat-2.1.0-x86_64-linux-gnu-1 - cleaning: sparc-rtems5-binutils-2.29-x86_64-linux-gnu-1 - cleaning: sparc-rtems5-gcc-7.2.0-newlib-2.5.0.20170922-x86_64-linux-gnu-1 - cleaning: sparc-rtems5-gdb-8.0.1-x86_64-linux-gnu-1 - cleaning: rtems-tools-HEAD-1 - cleaning: sparc-rtems5-kernel-5-1 - Build Set: Time 0:39:33.988995 .. _windows-tool-chain: Windows Host Tool Chain @@ -559,7 +476,6 @@ Then we generate the pre-install header file automake make files: Generating ./c/src/lib/libbsp/arm/csb336/preinstall.am Generating ./c/src/lib/libbsp/arm/csb337/preinstall.am Generating ./c/src/lib/libbsp/arm/edb7312/preinstall.am - Generating ./c/src/lib/libbsp/arm/gdbarmsim/preinstall.am ....... Generating ./cpukit/score/cpu/mips/preinstall.am Generating ./cpukit/score/cpu/moxie/preinstall.am @@ -577,12 +493,12 @@ Then we generate the pre-install header file automake make files: Generating ./cpukit/zlib/preinstall.am /c/opt/rtems/kernel/rtems -Finally we run the RSB's parallel ``bootstrap`` command: +Finally we run the parallel ``bootstrap`` command: .. code-block:: none - $ /c/opt/rtems/rsb/source-builder/sb-bootstrap - RTEMS Source Builder - RTEMS Bootstrap, 4.11 (76188ee494dd) + $ ./rtems-bootstrap + RTEMS Bootstrap, 4.11 (76188ee494dd) 1/139: autoreconf: configure.ac 2/139: autoreconf: c/configure.ac 3/139: autoreconf: c/src/configure.ac diff --git a/user/installation/kernel.rst b/user/installation/kernel.rst index f8c3c6f..d61f17f 100644 --- a/user/installation/kernel.rst +++ b/user/installation/kernel.rst @@ -18,10 +18,9 @@ Create a new location to build the RTEMS kernel: .. code-block:: none - $ cd - $ cd development/rtems - $ mkdir kernel - $ cd kernel + $ cd $HOME/development/rtems + $ mkdir src + $ cd src Clone the RTEMS respository: @@ -36,209 +35,72 @@ Clone the RTEMS respository: Resolving deltas: 100% (390053/390053), done. Checking connectivity... done. -Tools Path Set Up ------------------ - -We need to set our path to include the RTEMS tools we built in the previous -section. The RTEMS tools needs to be first in your path because RTEMS provides -specific versions of the ``autoconf`` and ``automake`` tools. We want to use -the RTEMS version and not your host's versions: - -.. code-block:: none - - $ export PATH=$HOME/development/rtems/5/bin:$PATH - -.. _bootstrapping: - -Bootstrapping -------------- - -The developers version of the code from git requires we ``bootstrap`` the -source code. This is an ``autoconf`` and ``automake`` bootstrap to create the -various files generated by ``autoconf`` and ``automake``. RTEMS does not keep -these generated files under version control. The bootstrap process is slow so -to speed it up the RSB provides a command that can perform the bootstrap in -parallel using your available cores. We need to enter the cloned source -directory then run the bootstrap commands: - -.. code-block:: none - - $ cd rtems - $ ./bootstrap -c && $HOME/development/rtems/rsb/source-builder/sb-bootstrap - removing automake generated Makefile.in files - removing configure files - removing aclocal.m4 files - RTEMS Source Builder - RTEMS Bootstrap, 5 (089327b5dcf9) - 1/139: autoreconf: configure.ac - 2/139: autoreconf: cpukit/configure.ac - 3/139: autoreconf: tools/cpu/configure.ac - 4/139: autoreconf: tools/cpu/generic/configure.ac - 5/139: autoreconf: tools/cpu/sh/configure.ac - 6/139: autoreconf: tools/cpu/nios2/configure.ac - 7/139: autoreconf: tools/build/configure.ac - 8/139: autoreconf: doc/configure.ac - ...... - 124/139: autoreconf: c/src/make/configure.ac - 125/139: autoreconf: c/src/librtems++/configure.ac - 126/139: autoreconf: c/src/ada-tests/configure.ac - 127/139: autoreconf: testsuites/configure.ac - 128/139: autoreconf: testsuites/libtests/configure.ac - 129/139: autoreconf: testsuites/mptests/configure.ac - 130/139: autoreconf: testsuites/fstests/configure.ac - 131/139: autoreconf: testsuites/sptests/configure.ac - 132/139: autoreconf: testsuites/tmtests/configure.ac - 133/139: autoreconf: testsuites/smptests/configure.ac - 134/139: autoreconf: testsuites/tools/configure.ac - 135/139: autoreconf: testsuites/tools/generic/configure.ac - 136/139: autoreconf: testsuites/psxtests/configure.ac - 137/139: autoreconf: testsuites/psxtmtests/configure.ac - 138/139: autoreconf: testsuites/rhealstone/configure.ac - 139/139: autoreconf: testsuites/samples/configure.ac - Bootstrap time: 0:02:47.398824 - Building a BSP -------------- -We build RTEMS in a directory outside of the source tree we have just cloned -and ``bootstrapped``. You cannot build RTEMS while in the source tree. Lets -create a suitable directory using the name of the BSP we are going to build: +We build RTEMS in a directory within the source tree we have just cloned. For +the details, see the :ref:`BSPBuildSystem`. We will build for the ``erc32`` +BSP with POSIX enabled. Firstly, create the file :file:`config.ini` in the +source tree root directory with the BSP build configuration, for example: -.. code-block:: none +.. code-block:: ini - $ cd .. - $ mkdir erc32 - $ cd erc32 + [sparc/erc32] + RTEMS_POSIX_API = True -Configure RTEMS using the ``configure`` command. We use a full path to -``configure`` so the object files built contain the absolute path of the source -files. If you are source level debugging you will be able to access the source -code to RTEMS from the debugger. We will build for the ``erc32`` BSP with POSIX -enabled and the networking stack disabled: +Configure RTEMS using the ``waf configure`` command: .. code-block:: none - $ $HOME/development/rtems/kernel/rtems/configure --prefix=$HOME/development/rtems/5 \ - --target=sparc-rtems5 --enable-rtemsbsp=erc32 --enable-posix \ - --disable-networking - checking for gmake... no - checking for make... make - checking for RTEMS Version... 4.11.99.0 - checking build system type... x86_64-pc-linux-gnu - checking host system type... x86_64-pc-linux-gnu - checking target system type... sparc-unknown-rtems5 - checking for a BSD-compatible install... /usr/bin/install -c - checking whether build environment is sane... yes - checking for a thread-safe mkdir -p... /bin/mkdir -p - checking for gawk... no - checking for mawk... mawk - checking whether make sets $(MAKE)... yes - checking whether to enable maintainer-specific portions of Makefiles... no - checking that generated files are newer than configure... done - ...... - checking target system type... sparc-unknown-rtems5 - checking rtems target cpu... sparc - checking for a BSD-compatible install... /usr/bin/install -c - checking whether build environment is sane... yes - checking for sparc-rtems5-strip... sparc-rtems5-strip - checking for a thread-safe mkdir -p... /bin/mkdir -p - checking for gawk... no - checking for mawk... mawk - checking whether make sets $(MAKE)... yes - checking whether to enable maintainer-specific portions of Makefiles... no - checking that generated files are newer than configure... done - configure: creating ./config.status - config.status: creating Makefile - - target architecture: sparc. - available BSPs: erc32. - 'make all' will build the following BSPs: erc32. - other BSPs can be built with 'make RTEMS_BSP="bsp1 bsp2 ..."' - - config.status: creating Makefile - -Build RTEMS using two cores: + $ cd $HOME/development/rtems/src/rtems + $ ./waf configure --prefix=$HOME/development/rtems/6 + Setting top to : $HOME/development/rtems/src/rtems + Setting out to : $HOME/development/rtems/src/rtems/build + Regenerate build specification cache (needs a couple of seconds)... + Configure board support package (BSP) : sparc/erc32 + Checking for program 'sparc-rtems6-gcc' : $HOME/development/rtems/6/bin/sparc-rtems6-gcc + Checking for program 'sparc-rtems6-g++' : $HOME/development/rtems/6/bin/sparc-rtems6-g++ + Checking for program 'sparc-rtems6-ar' : $HOME/development/rtems/6/bin/sparc-rtems6-ar + Checking for program 'sparc-rtems6-ld' : $HOME/development/rtems/6/bin/sparc-rtems6-ld + Checking for program 'ar' : $HOME/development/rtems/6/bin/sparc-rtems6-ar + Checking for program 'g++, c++' : $HOME/development/rtems/6/bin/sparc-rtems6-g++ + Checking for program 'ar' : $HOME/development/rtems/6/bin/sparc-rtems6-ar + Checking for program 'gas, gcc' : $HOME/development/rtems/6/bin/sparc-rtems6-gcc + Checking for program 'ar' : $HOME/development/rtems/6/bin/sparc-rtems6-ar + Checking for program 'gcc, cc' : $HOME/development/rtems/6/bin/sparc-rtems6-gcc + Checking for program 'ar' : $HOME/development/rtems/6/bin/sparc-rtems6-ar + Checking for asm flags '-MMD' : yes + Checking for c flags '-MMD' : yes + Checking for cxx flags '-MMD' : yes + Checking for program 'rtems-bin2c' : $HOME/development/rtems/6/bin/rtems-bin2c + Checking for program 'gzip' : /usr/bin/gzip + Checking for program 'xz' : /usr/bin/xz + Checking for program 'rtems-ld' : $HOME/development/rtems/6/bin/rtems-ld + Checking for program 'rtems-syms' : $HOME/development/rtems/6/bin/rtems-syms + Checking for program 'rtems-bin2c' : $HOME/development/rtems/6/bin/rtems-bin2c + Checking for program 'gzip' : /usr/bin/gzip + Checking for program 'xz' : /usr/bin/xz + 'configure' finished successfully (7.996s) + +Build RTEMS: .. code-block:: none - $ make -j 2 - Making all in tools/build - make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build' - make all-am - make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build' - gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build -g -O2 -MT cklength.o -MD -MP -MF .deps/cklength.Tpo -c -o cklength.o /home/chris/development/rtems/kernel/rtems/tools/build/cklength.c - gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build -g -O2 -MT eolstrip.o -MD -MP -MF .deps/eolstrip.Tpo -c -o eolstrip.o /home/chris/development/rtems/kernel/rtems/tools/build/eolstrip.c - mv -f .deps/cklength.Tpo .deps/cklength.Po - mv -f .deps/eolstrip.Tpo .deps/eolstrip.Po - gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build -g -O2 -MT compat.o -MD -MP -MF .deps/compat.Tpo -c -o compat.o /home/chris/development/rtems/kernel/rtems/tools/build/compat.c - gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build -g -O2 -MT packhex.o -MD -MP -MF .deps/packhex.Tpo -c -o packhex.o /home/chris/development/rtems/kernel/rtems/tools/build/packhex.c - mv -f .deps/compat.Tpo .deps/compat.Po - gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build -g -O2 -MT unhex.o -MD -MP -MF .deps/unhex.Tpo -c -o unhex.o /home/chris/development/rtems/kernel/rtems/tools/build/unhex.c - mv -f .deps/packhex.Tpo .deps/packhex.Po - gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build -g -O2 -MT rtems-bin2c.o -MD -MP -MF .deps/rtems-bin2c.Tpo -c -o rtems-bin2c.o /home/chris/development/rtems/kernel/rtems/tools/build/rtems-bin2c.c - mv -f .deps/unhex.Tpo .deps/unhex.Po - gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build -g -O2 -MT binpatch.o -MD -MP -MF .deps/binpatch.Tpo -c -o binpatch.o /home/chris/development/rtems/kernel/rtems/tools/build/binpatch.c - mv -f .deps/rtems-bin2c.Tpo .deps/rtems-bin2c.Po - gcc -g -O2 -o cklength cklength.o - mv -f .deps/binpatch.Tpo .deps/binpatch.Po - gcc -g -O2 -o eolstrip eolstrip.o compat.o - gcc -g -O2 -o packhex packhex.o - gcc -g -O2 -o rtems-bin2c rtems-bin2c.o compat.o - gcc -g -O2 -o unhex unhex.o compat.o - gcc -g -O2 -o binpatch binpatch.o - make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build' - make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build' - Making all in tools/cpu - make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' - Making all in generic - make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic' - make[2]: Nothing to be done for 'all'. - make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic' - make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' - make[2]: Nothing to be done for 'all-am'. - make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' - make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' - Making all in testsuites/tools - make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools' - Making all in generic - make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools/generic' - make[2]: Nothing to be done for 'all'. - make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools/generic' - make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools' - make[2]: Nothing to be done for 'all-am'. - make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools' - make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools' - Making all in sparc-rtems5/c - make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c' - Making all in . - make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c' - Configuring RTEMS_BSP=erc32 - checking for gmake... no - checking for make... make - checking build system type... x86_64-pc-linux-gnu - checking host system type... sparc-unknown-rtems5 - ...... - sparc-rtems5-gcc -B../../../../../erc32/lib/ -specs bsp_specs -qrtems -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs -I.. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/../support/include -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -MT init.o -MD -MP -MF .deps/init.Tpo -c -o init.o /home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs/init.c - sparc-rtems5-gcc -B../../../../../erc32/lib/ -specs bsp_specs -qrtems -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs -I.. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/../support/include -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -MT empty.o -MD -MP -MF .deps/empty.Tpo -c -o empty.o /home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs/empty.c - mv -f .deps/empty.Tpo .deps/empty.Po - mv -f .deps/init.Tpo .deps/init.Po - sparc-rtems5-gcc -B../../../../../erc32/lib/ -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress -o nsecs.exe init.o empty.o - sparc-rtems5-nm -g -n nsecs.exe > nsecs.num - sparc-rtems5-size nsecs.exe - text data bss dec hex filename - 121392 1888 6624 129904 1fb70 nsecs.exe - cp nsecs.exe nsecs.ralf - make[6]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites/samples/nsecs' - make[5]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites/samples' - make[4]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites/samples' - make[4]: Entering directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites' - make[4]: Nothing to be done for 'all-am'. - make[4]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites' - make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32/testsuites' - make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/ c/erc32' - make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c' - make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32' - make[1]: Nothing to be done for 'all-am'. - make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32' + $ ./waf + Waf: Entering directory `$HOME/development/rtems/src/rtems/build' + Waf: Leaving directory `$HOME/development/rtems/src/rtems/build' + 'build' finished successfully (0.051s) + Waf: Entering directory `$HOME/development/rtems/src/rtems/build/sparc/erc32' + [ 1/1524] Compiling bsps/shared/dev/serial/mc68681_reg2.c + [ 2/1524] Compiling bsps/shared/dev/rtc/mc146818a_ioreg.c + [ 3/1524] Compiling bsps/shared/dev/flash/am29lv160.c + ... + [1521/1524] Linking $HOME/development/rtems/src/rtems/build/sparc/erc32/libz.a + [1522/1524] Linking $HOME/development/rtems/src/rtems/build/sparc/erc32/librtemscxx.a + [1523/1524] Linking $HOME/development/rtems/src/rtems/build/sparc/erc32/testsuites/samples/paranoia.exe + [1524/1524] Linking $HOME/development/rtems/src/rtems/build/sparc/erc32/libmghttpd.a + Waf: Leaving directory `$HOME/development/rtems/src/rtems/build/sparc/erc32' + 'build_sparc/erc32' finished successfully (4.894s) Installing A BSP ---------------- @@ -252,46 +114,20 @@ RTEMS with the following command: .. code-block:: none - $ make install - Making install in tools/build - make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build' - make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build' - /bin/mkdir -p '/home/chris/development/rtems/5/bin' - /usr/bin/install -c cklength eolstrip packhex unhex rtems-bin2c '/home/chris/development/rtems/5/bin' - /bin/mkdir -p '/home/chris/development/rtems/5/bin' - /usr/bin/install -c install-if-change '/home/chris/development/rtems/5/bin' - make[2]: Nothing to be done for 'install-data-am'. - make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build' - make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build' - Making install in tools/cpu - make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' - Making install in generic - make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic' - make[3]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic' - make[3]: Nothing to be done for 'install-exec-am'. - make[3]: Nothing to be done for 'install-data-am'. - make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic' - make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic' - make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' - make[3]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' - make[3]: Nothing to be done for 'install-exec-am'. - make[3]: Nothing to be done for 'install-data-am'. - make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' - make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' - make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu' - .... - make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems5/c' - make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32' - make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32' - make[2]: Nothing to be done for 'install-exec-am'. - /bin/mkdir -p '/home/chris/development/rtems/5/make' - /usr/bin/install -c -m 644 /home/chris/development/rtems/kernel/rtems/make/main.cfg /home/chris/development/rtems/kernel/rtems/make/leaf.cfg '/home/chris/development/rtems/5/make' - /bin/mkdir -p '/home/chris/development/rtems/5/share/rtems5/make/Templates' - /usr/bin/install -c -m 644 /home/chris/development/rtems/kernel/rtems/make/Templates/Makefile.dir /home/chris/development/rtems/kernel/rtems/make/Templates/Makefile.leaf /home/chris/development/rtems/kernel/rtems/make/Templates/Makefile.lib '/home/chris/development/rtems/5/share/rtems5/make/Templates' - /bin/mkdir -p '/home/chris/development/rtems/5/make/custom' - /usr/bin/install -c -m 644 /home/chris/development/rtems/kernel/rtems/make/custom/default.cfg '/home/chris/development/rtems/5/make/custom' - make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32' - make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32' + $ ./waf install + Waf: Entering directory `$HOME/development/rtems/src/rtems/build' + Waf: Leaving directory `$HOME/development/rtems/src/rtems/build' + 'install' finished successfully (0.074s) + Waf: Entering directory `$HOME/development/rtems/src/rtems/build/sparc/erc32' + + install $HOME/development/rtems/6/sparc-rtems6/erc32/lib/include/libchip/am29lv160.h (from bsps/include/libchip/am29lv160.h) + + install $HOME/development/rtems/6/sparc-rtems6/erc32/lib/include/libchip/mc146818a.h (from bsps/include/libchip/mc146818a.h) + + install $HOME/development/rtems/6/sparc-rtems6/erc32/lib/include/libchip/mc68681.h (from bsps/include/libchip/mc68681.h) + ... + + install $HOME/development/rtems/6/sparc-rtems6/erc32/lib/include/rtems/version.h (from cpukit/include/rtems/version.h) + + install $HOME/development/rtems/6/sparc-rtems6/erc32/lib/include/rtems/vmeintr.h (from cpukit/include/rtems/vmeintr.h) + + install $HOME/development/rtems/6/sparc-rtems6/erc32/lib/include/rtems/watchdogdrv.h (from cpukit/include/rtems/watchdogdrv.h) + Waf: Leaving directory `$HOME/development/rtems/src/rtems/build/sparc/erc32' + 'install_sparc/erc32' finished successfully (0.637s) Contributing Patches -------------------- @@ -313,7 +149,7 @@ has changed: .. code-block:: none - $ cd ../rtems + $ cd $HOME/development/rtems/src/rtems $ git status On branch master Your branch is up-to-date with 'origin/master'. diff --git a/user/installation/project-sandboxing.rst b/user/installation/project-sandboxing.rst index 248a136..bba7e8a 100644 --- a/user/installation/project-sandboxing.rst +++ b/user/installation/project-sandboxing.rst @@ -18,11 +18,12 @@ directory suitable permissions to be writable by you as a user. Lets create a project sandbox for my *Box Sorter* project. First create a project directory called :file:`/bd/projects/box-sorter`. Under this create -:file:`rtems` and under that create :file:`rtems-4.11.0`. Under this path you -can follow the :ref:`released-version` procedure to build a tool set using the -prefix of :file:`/bd/projects/box-sorter/rtems/4.11.0`. You are free to create -your project specific directories under :file:`/bd/projects/box-sorter`. The -top level directories would be: +:file:`rtems` and under that create :file:`rtems-@rtems-ver-majminrev@`. Under +this path you can follow the :ref:`released-version` procedure to build a tool +set using the prefix of +:file:`/bd/projects/box-sorter/rtems/@rtems-ver-majminrev@`. You are free to +create your project specific directories under +:file:`/bd/projects/box-sorter`. The top level directories would be: :file:`/bd/projects` Project specific development trees. @@ -30,9 +31,9 @@ top level directories would be: :file:`/bd/projects/box-sorter` Box Sorter project sandbox. -:file:`/bd/projects/box-sorter/rtems/4.11.0` - Project prefix for RTEMS 4.11.0 compiler, debuggers, tools and installed - Board Support Package (BSP). +:file:`/bd/projects/box-sorter/rtems/@rtems-ver-majminrev@` + Project prefix for RTEMS @rtems-ver-majminrev@ compiler, debuggers, tools and + installed Board Support Package (BSP). A variation is to use the ``--without-rtems`` option with the RSB to not build the BSPs when building the tools and to build RTEMS specifically for each @@ -43,8 +44,9 @@ RTEMS. The top level directories would be: :file:`/bd/rtems` The top path to production tools. -:file:`/bd/rtems/4.11.0` - Production prefix for RTEMS 4.11.0 compiler, debuggers and tools. +:file:`/bd/rtems/@rtems-ver-majminrev@` + Production prefix for RTEMS @rtems-ver-majminrev@ compiler, debuggers and + tools. :file:`/bd/projects` Project specific development trees. @@ -62,14 +64,16 @@ up with: :file:`/bd/rtems` The top path to production tools and kernels. -:file:`/bd/rtems/4.11.0` - Production prefix for RTEMS 4.11.0. +:file:`/bd/rtems/@rtems-ver-majminrev@` + Production prefix for RTEMS @rtems-ver-majminrev@. -:file:`/bd/rtems/4.11.0/tools` - Production prefix for RTEMS 4.11.0 compiler, debuggers and tools. +:file:`/bd/rtems/@rtems-ver-majminrev@/tools` + Production prefix for RTEMS @rtems-ver-majminrev@ compiler, debuggers and + tools. -:file:`/bd/rtems/4.11.0/bsps` - Production prefix for RTEMS 4.11.0 Board Support Packages (BSPs). +:file:`/bd/rtems/@rtems-ver-majminrev@/bsps` + Production prefix for RTEMS @rtems-ver-majminrev@ Board Support Packages + (BSPs). :file:`/bd/projects` Project specific development trees. @@ -84,9 +88,9 @@ directories would be: :file:`/bd/rtems` The top path to production tools and kernels. -:file:`/bd/rtems/4.11.0` - Production prefix for RTEMS 4.11.0 compiler, debuggers, tools and Board - Support Packages (BSPs). +:file:`/bd/rtems/@rtems-ver-majminrev@` + Production prefix for RTEMS @rtems-ver-majminrev@ compiler, debuggers, tools + and Board Support Packages (BSPs). :file:`/bd/projects` Project specific development trees. diff --git a/user/installation/releases.rst b/user/installation/releases.rst index a20f948..6694806 100644 --- a/user/installation/releases.rst +++ b/user/installation/releases.rst @@ -30,11 +30,11 @@ more detail about path lengths on Windows. The location used to install the tools and kernel is called the `prefix`. :ref:`QuickStartPrefixes` explains prefixes and how to use them. It is best to have a `prefix` for each different version of RTEMS you are using. If you are -using RTEMS 4.11 in production it is **not** a good idea to install a -development version of 5 over the top by using the same `prefix` as the 4.11 -build. A separate `prefix` for each version avoids this. +using RTEMS in production it is **not** a good idea to install a development +version of over the top by using the same `prefix`. A separate `prefix` for each +version avoids this. -Released versions of the RTEMS Source Builder (RSB) downloads all source code +Released versions of the RTEMS Source Builder (RSB) download all source code for all packages from the :r:url:`ftp` rather than from the package's home site. Hosting all the source on the :r:url:`ftp` ensures the source is present for the life of the release on the :r:url:`ftp`. If there is a problem @@ -47,9 +47,8 @@ shosted here. It has excellent internet access and performance. .. note:: **Controlling the RTEMS Kernel Build** - Building releases by default does not build the RTEMS kernel. To - build the RTEMS kernel add the ``--with-rtems`` option to the RSB - command line. + Building RSB releases by default does not build the RTEMS kernel. To build + the RTEMS kernel add the ``--with-rtems`` option to the RSB command line. By default all the BSPs for an architecture are built. If you only wish to have a specific BSP built you can specify the BSP list by providing to the @@ -86,33 +85,33 @@ Download the RTEMS Source Builder (RSB) from the RTEMS FTP server: .. code-block:: none - $ wget https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-source-builder-4.11.0.tar.xz - --2016-03-21 10:50:04-- https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-source-builder-4.11.0.tar.xz + $ wget https://ftp.rtems.org/pub/rtems/releases/@rtems-ver-major@/@rtems-ver-majminrev@/rtems-source-builder-@rtems-ver-majminrev@.tar.xz + --2016-03-21 10:50:04-- https://ftp.rtems.org/pub/rtems/releases/@rtems-ver-major/@rtems-ver-majminrev@/rtems-source-builder-@rtems-ver-majminrev@.tar.xz Resolving ftp.rtems.org (ftp.rtems.org)... 140.211.10.151 Connecting to ftp.rtems.org (ftp.rtems.org)|140.211.10.151|:443... connected. HTTP request sent, awaiting response... 200 OK Length: 967056 (944K) [application/x-xz] - Saving to: 'rtems-source-builder-4.11.0.tar.xz' + Saving to: 'rtems-source-builder-@rtems-ver-majminrev@.tar.xz' - rtems-source-builder-4.1 100%[====================================>] 944.39K 206KB/s in 5.5s + rtems-source-builder-@rtems-ver-majminrev@ 100%[====================================>] 944.39K 206KB/s in 5.5s - 2016-03-21 10:50:11 (173 KB/s) - 'rtems-source-builder-4.11.0.tar.xz' saved [967056/967056] + 2016-03-21 10:50:11 (173 KB/s) - 'rtems-source-builder-@rtems-ver-majminrev@.tar.xz' saved [967056/967056] On Unix unpack the RSB release tar file using: .. code-block:: none - $ tar Jxf rtems-source-builder-4.11.0.tar.xz - $ cd rtems-source-builder-4.11.0/rtems/ + $ tar Jxf rtems-source-builder-@rtems-ver-majminrev@.tar.xz + $ cd rtems-source-builder-@rtems-ver-majminrev@/rtems/ On Windows you need to shorten the path (See :ref:`windows-path-length`) after you have unpacked the tar file: .. code-block:: none - $ tar Jxf rtems-source-builder-4.11.0.tar.xz - $ mv rtems-source-builder-4.11.0 4.110 - $ cd 4.11.0 + $ tar Jxf rtems-source-builder-@rtems-ver-majminrev@.tar.xz + $ mv rtems-source-builder-@rtems-ver-majminrev@ @rtems-ver-majminrev@ + $ cd @rtems-ver-majminrev@ Build a tool chain for the SPARC architecure. We are using the SPARC architecture in our example because GDB has a good simulator that lets us run @@ -124,164 +123,6 @@ discussed in :ref:`msys2_parallel_builds`. .. code-block:: none $ ../source-builder/sb-set-builder \ - --prefix=/opt/rtems/4.11 4.11/rtems-sparc - Build Set: 4.11/rtems-sparc - Build Set: 4.11/rtems-autotools.bset - Build Set: 4.11/rtems-autotools-internal.bset - config: tools/rtems-autoconf-2.69-1.cfg - package: autoconf-2.69-x86_64-freebsd10.1-1 - Creating source directory: sources - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/autoconf-2.69.tar.gz -> sources/autoconf-2.69.tar.gz - downloading: sources/autoconf-2.69.tar.gz - 1.8MB of 1.8MB (100%) - building: autoconf-2.69-x86_64-freebsd10.1-1 - config: tools/rtems-automake-1.12.6-1.cfg - package: automake-1.12.6-x86_64-freebsd10.1-1 - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/automake-1.12.6.tar.gz -> sources/automake-1.12.6.tar.gz - downloading: sources/automake-1.12.6.tar.gz - 2.0MB of 2.0MB (100%) - Creating source directory: patches - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/automake-1.12.6-bugzilla.redhat.com-1239379.diff -> patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff - downloading: patches/automake-1.12.6-bugzilla.redhat.com-1239379.diff - 408.0 bytes of 408.0 bytes (100%) - building: automake-1.12.6-x86_64-freebsd10.1-1 - cleaning: autoconf-2.69-x86_64-freebsd10.1-1 - cleaning: automake-1.12.6-x86_64-freebsd10.1-1 - Build Set: Time 0:00:32.749337 - Build Set: 4.11/rtems-autotools-base.bset - config: tools/rtems-autoconf-2.69-1.cfg - package: autoconf-2.69-x86_64-freebsd10.1-1 - building: autoconf-2.69-x86_64-freebsd10.1-1 - reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-freebsd10.1-1.txt - reporting: tools/rtems-autoconf-2.69-1.cfg -> autoconf-2.69-x86_64-freebsd10.1-1.xml - config: tools/rtems-automake-1.12.6-1.cfg - package: automake-1.12.6-x86_64-freebsd10.1-1 - building: automake-1.12.6-x86_64-freebsd10.1-1 - reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-freebsd10.1-1.txt - reporting: tools/rtems-automake-1.12.6-1.cfg -> automake-1.12.6-x86_64-freebsd10.1-1.xml - installing: autoconf-2.69-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 - installing: automake-1.12.6-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 - cleaning: autoconf-2.69-x86_64-freebsd10.1-1 - cleaning: automake-1.12.6-x86_64-freebsd10.1-1 - Build Set: Time 0:00:15.619219 - Build Set: Time 0:00:48.371085 - config: devel/expat-2.1.0-1.cfg - package: expat-2.1.0-x86_64-freebsd10.1-1 - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/expat-2.1.0.tar.gz -> sources/expat-2.1.0.tar.gz - downloading: sources/expat-2.1.0.tar.gz - 549.4kB of 549.4kB (100%) - building: expat-2.1.0-x86_64-freebsd10.1-1 - reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-freebsd10.1-1.txt - reporting: devel/expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-freebsd10.1-1.xml - config: tools/rtems-binutils-2.26-1.cfg - package: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1 - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/binutils-2.26.tar.bz2 -> sources/binutils-2.26.tar.bz2 - downloading: sources/binutils-2.26.tar.bz2 - 24.4MB of 24.4MB (100%) - building: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1 - reporting: tools/rtems-binutils-2.26-1.cfg -> - sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1.txt - reporting: tools/rtems-binutils-2.26-1.cfg -> - sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1.xml - config: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg - package: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1 - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gcc-4.9.3.tar.bz2 -> sources/gcc-4.9.3.tar.bz2 - downloading: sources/gcc-4.9.3.tar.bz2 - 85.8MB of 85.8MB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/newlib-2.2.0.20150423.tar.gz -> sources/newlib-2.2.0.20150423.tar.gz - downloading: sources/newlib-2.2.0.20150423.tar.gz - 16.7MB of 16.7MB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/mpfr-3.0.1.tar.bz2 -> sources/mpfr-3.0.1.tar.bz2 - downloading: sources/mpfr-3.0.1.tar.bz2 - 1.1MB of 1.1MB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/mpc-0.8.2.tar.gz -> sources/mpc-0.8.2.tar.gz - downloading: sources/mpc-0.8.2.tar.gz - 535.5kB of 535.5kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gmp-5.0.5.tar.bz2 -> sources/gmp-5.0.5.tar.bz2 - downloading: sources/gmp-5.0.5.tar.bz2 - 2.0MB of 2.0MB (100%) - building: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1 - reporting: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg -> - sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1.txt - reporting: tools/rtems-gcc-4.9.3-newlib-2.2.0-20150423-1.cfg -> - sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1.xml - config: tools/rtems-gdb-7.9-1.cfg - package: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1 - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gdb-7.9.tar.xz -> sources/gdb-7.9.tar.xz - downloading: sources/gdb-7.9.tar.xz - 17.0MB of 17.0MB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0001-sim-erc32-Disassembly-in-stand-alone-mode-did-not-wo.patch -> patches/0001-sim-erc32-Disassembly-in-stand-alone-mode-did-not-wo.patch - downloading: patches/0001-sim-erc32-Disassembly-in-stand-alone-mode-did-not-wo.patch - 1.9kB of 1.9kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0002-sim-erc32-Corrected-wrong-CPU-implementation-and-ver.patch -> patches/0002-sim-erc32-Corrected-wrong-CPU-implementation-and-ver.patch - downloading: patches/0002-sim-erc32-Corrected-wrong-CPU-implementation-and-ver.patch - 827.0 bytes of 827.0 bytes (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0003-sim-erc32-Perform-pseudo-init-if-binary-linked-to-no.patch -> patches/0003-sim-erc32-Perform-pseudo-init-if-binary-linked-to-no.patch - downloading: patches/0003-sim-erc32-Perform-pseudo-init-if-binary-linked-to-no.patch - 2.6kB of 2.6kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0004-sim-erc32-Use-fenv.h-for-host-FPU-access.patch -> patches/0004-sim-erc32-Use-fenv.h-for-host-FPU-access.patch - downloading: patches/0004-sim-erc32-Use-fenv.h-for-host-FPU-access.patch - 4.9kB of 4.9kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0005-sim-erc32-Remove-unused-defines-in-Makefile-and-swit.patch -> patches/0005-sim-erc32-Remove-unused-defines-in-Makefile-and-swit.patch - downloading: patches/0005-sim-erc32-Remove-unused-defines-in-Makefile-and-swit.patch - 871.0 bytes of 871.0 bytes (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0006-sim-erc32-Fix-incorrect-simulator-performance-report.patch -> patches/0006-sim-erc32-Fix-incorrect-simulator-performance-report.patch - downloading: patches/0006-sim-erc32-Fix-incorrect-simulator-performance-report.patch - 5.6kB of 5.6kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0007-sim-erc32-File-loading-via-command-line-did-not-work.patch -> patches/0007-sim-erc32-File-loading-via-command-line-did-not-work.patch - downloading: patches/0007-sim-erc32-File-loading-via-command-line-did-not-work.patch - 1.0kB of 1.0kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0008-sim-erc32-Added-v-command-line-switch-for-verbose-ou.patch -> patches/0008-sim-erc32-Added-v-command-line-switch-for-verbose-ou.patch - downloading: patches/0008-sim-erc32-Added-v-command-line-switch-for-verbose-ou.patch - 3.6kB of 3.6kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0009-sim-erc32-Removed-type-mismatch-compiler-warnings.patch -> patches/0009-sim-erc32-Removed-type-mismatch-compiler-warnings.patch - downloading: patches/0009-sim-erc32-Removed-type-mismatch-compiler-warnings.patch - 1.9kB of 1.9kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0010-sim-erc32-Switched-emulated-memory-to-host-endian-or.patch -> patches/0010-sim-erc32-Switched-emulated-memory-to-host-endian-or.patch - downloading: patches/0010-sim-erc32-Switched-emulated-memory-to-host-endian-or.patch - 16.0kB of 16.0kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0011-sim-erc32-use-SIM_AC_OPTION_HOSTENDIAN-to-probe-for-.patch -> patches/0011-sim-erc32-use-SIM_AC_OPTION_HOSTENDIAN-to-probe-for-.patch - downloading: patches/0011-sim-erc32-use-SIM_AC_OPTION_HOSTENDIAN-to-probe-for-.patch - 14.8kB of 14.8kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0012-sim-erc32-Use-memory_iread-function-for-instruction-.patch -> patches/0012-sim-erc32-Use-memory_iread-function-for-instruction-.patch - downloading: patches/0012-sim-erc32-Use-memory_iread-function-for-instruction-.patch - 3.8kB of 3.8kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0013-sim-erc32-Fix-a-few-compiler-warnings.patch-> patches/0013-sim-erc32-Fix-a-few-compiler-warnings.patch - downloading: patches/0013-sim-erc32-Fix-a-few-compiler-warnings.patch - 2.2kB of 2.2kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0014-sim-erc32-Use-gdb-callback-for-UART-I-O-when-linked-.patch -> patches/0014-sim-erc32-Use-gdb-callback-for-UART-I-O-when-linked-.patch - downloading: patches/0014-sim-erc32-Use-gdb-callback-for-UART-I-O-when-linked-.patch - 9.2kB of 9.2kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0015-sim-erc32-Access-memory-subsystem-through-struct-mem.patch -> patches/0015-sim-erc32-Access-memory-subsystem-through-struct-mem.patch - downloading: patches/0015-sim-erc32-Access-memory-subsystem-through-struct-mem.patch - 22.9kB of 22.9kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0016-sim-erc32-Use-readline.h-for-readline-types-and-func.patch -> patches/0016-sim-erc32-Use-readline.h-for-readline-types-and-func.patch - downloading: patches/0016-sim-erc32-Use-readline.h-for-readline-types-and-func.patch - 1.5kB of 1.5kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0017-sim-erc32-Move-local-extern-declarations-into-sis.h.patch -> patches/0017-sim-erc32-Move-local-extern-declarations-into-sis.h.patch - downloading: patches/0017-sim-erc32-Move-local-extern-declarations-into-sis.h.patch - 5.8kB of 5.8kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0018-sim-erc32-Add-support-for-LEON3-processor-emulation.patch -> patches/0018-sim-erc32-Add-support-for-LEON3-processor-emulation.patch - downloading: patches/0018-sim-erc32-Add-support-for-LEON3-processor-emulation.patch - 66.7kB of 66.7kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0019-sim-erc32-Add-support-for-LEON2-processor-emulation.patch -> patches/0019-sim-erc32-Add-support-for-LEON2-processor-emulation.patch - downloading: patches/0019-sim-erc32-Add-support-for-LEON2-processor-emulation.patch - 26.1kB of 26.1kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0020-sim-erc32-Updated-documentation.patch -> patches/0020-sim-erc32-Updated-documentation.patch - downloading: patches/0020-sim-erc32-Updated-documentation.patch - 16.1kB of 16.1kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0021-sim-erc32-Add-data-watchpoint-support.patch -> patches/0021-sim-erc32-Add-data-watchpoint-support.patch - downloading: patches/0021-sim-erc32-Add-data-watchpoint-support.patch - 10.1kB of 10.1kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0022-Add-watchpoint-support-to-gdb-simulator-interface.patch -> patches/0022-Add-watchpoint-support-to-gdb-simulator-interface.patch - downloading: patches/0022-Add-watchpoint-support-to-gdb-simulator-interface.patch - 25.5kB of 25.5kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/0023-sim-erc32-ELF-loading-could-fail-on-unaligned-sectio.patch -> patches/0023-sim-erc32-ELF-loading-could-fail-on-unaligned-sectio.patch - downloading: patches/0023-sim-erc32-ELF-loading-could-fail-on-unaligned-sectio.patch - 1.3kB of 1.3kB (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gdb-sim-arange-inline.diff -> patches/gdb-sim-arange-inline.diff - downloading: patches/gdb-sim-arange-inline.diff - 761.0 bytes of 761.0 bytes (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/gdb-sim-cgen-inline.diff -> patches/gdb-sim-cgen-inline.diff - downloading: patches/gdb-sim-cgen-inline.diff - 706.0 bytes of 706.0 bytes (100%) - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/sources/patch-gdb-python-python-config.py -> patches/patch-gdb-python-python-config.py - downloading: patches/patch-gdb-python-python-config.py - 449.0 bytes of 449.0 bytes (100%) - building: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1 - reporting: tools/rtems-gdb-7.9-1.cfg -> - sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1.txt - reporting: tools/rtems-gdb-7.9-1.cfg -> - sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1.xml - config: tools/rtems-tools-4.11-1.cfg - package: rtems-tools-4.11.0-1 - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-tools-4.11.0.tar.xz -> sources/rtems-tools-4.11.0.tar.xz - downloading: sources/rtems-tools-4.11.0.tar.xz - 1.6MB of 1.6MB (100%) - building: rtems-tools-4.11.0-1 - reporting: tools/rtems-tools-4.11-1.cfg -> rtems-tools-4.11.0-1.txt - reporting: tools/rtems-tools-4.11-1.cfg -> rtems-tools-4.11.0-1.xml - config: tools/rtems-kernel-4.11.cfg - package: sparc-rtems4.11-kernel-4.11.0-1 - download: ftp://ftp.rtems.org/pub/rtems/releases/4.11/4.11.0/rtems-4.11.0.tar.xz -> sources/rtems-4.11.0.tar.xz - downloading: sources/rtems-4.11.0.tar.xz - 9.3MB of 9.3MB (100%) - building: sparc-rtems4.11-kernel-4.11.0-1 - reporting: tools/rtems-kernel-4.11.cfg -> sparc-rtems4.11-kernel-4.11.0-1.txt - reporting: tools/rtems-kernel-4.11.cfg -> sparc-rtems4.11-kernel-4.11.0-1.xml - installing: expat-2.1.0-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 - installing: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 - installing: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 - installing: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1 -> /opt/work/rtems/4.11.0 - installing: rtems-tools-4.11.0-1 -> /opt/work/rtems/4.11.0 - installing: sparc-rtems4.11-kernel-4.11.0-1 -> /opt/work/rtems/4.11.0 - cleaning: expat-2.1.0-x86_64-freebsd10.1-1 - cleaning: sparc-rtems4.11-binutils-2.26-x86_64-freebsd10.1-1 - cleaning: sparc-rtems4.11-gcc-4.9.3-newlib-2.2.0.20150423-x86_64-freebsd10.1-1 - cleaning: sparc-rtems4.11-gdb-7.9-x86_64-freebsd10.1-1 - cleaning: rtems-tools-4.11.0-1 - cleaning: sparc-rtems4.11-kernel-4.11.0-1 - Build Set: Time 0:19:15.713662 + --prefix=/opt/rtems/@rtems-ver-major@ @rtems-ver-major@/rtems-sparc You can now build a third-party library or an application as defaulted in TBD. diff --git a/user/migration/index.rst b/user/migration/index.rst new file mode 100644 index 0000000..06af484 --- /dev/null +++ b/user/migration/index.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 Chris Johns + +.. index:: Migration + +.. _Migration: + +Changing Versions +***************** + +Follow the sections provide support help when migratiing applications +from one version of RTEMS to a new version. + +.. toctree:: + + v4_11-to-v5 + v5-to-v6 diff --git a/user/migration/v4_11-to-v5.rst b/user/migration/v4_11-to-v5.rst new file mode 100644 index 0000000..2dc97ec --- /dev/null +++ b/user/migration/v4_11-to-v5.rst @@ -0,0 +1,174 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 Chris Johns +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. _Migration_4_11_to_5: + +RTEMS 4.11 to RTEMS 5 +===================== + +This section provides helpful information when migrating from RTEMS 4.11 to +RTEMS 5. + +Application Configuration Options +--------------------------------- + +The evaluation of application configuration options in ``<rtems/confdefs.h>`` +was reworked during the RTEMS 5 development cycle. All options which let the +user define data structures were removed, this includes + +* ``CONFIGURE_HAS_OWN_CONFIGURATION_TABLE``, + +* ``CONFIGURE_HAS_OWN_BDBUF_TABLE``, + +* ``CONFIGURE_HAS_OWN_DEVICE_DRIVER_TABLE``, + +* ``CONFIGURE_HAS_OWN_FILESYSTEM_TABLE``, + +* ``CONFIGURE_HAS_OWN_INIT_TABLE``, + +* ``CONFIGURE_HAS_OWN_MOUNT_TABLE``, + +* ``CONFIGURE_HAS_OWN_MULTIPROCESSING_TABLE``, and + +* ``CONFIGURE_POSIX_HAS_OWN_INIT_THREAD_TABLE``. + +The configuration of SMP schedulers changed. For example, +:c:func:`RTEMS_SCHEDULER_EDF_SMP` has now only one parameter. Please read +section `Clustered Scheduler Configuration` in the `RTEMS Classic API Guide`. + +A number of configurations options have moved or are obsolete as a result of +internal changes in RTEMS. Some of these will produce a warning indicating the +new configuration settings you need to define. If you need to run an application +on RTEMS 4.11 and RTEMS 5 the following code example shows how to conditionally +define the settings. The example is: + +.. code-block:: c + + #include <rtems.h> + + #if __RTEMS_MAJOR__ < 5 + #define CONFIGURE_MAXIMUM_FIFOS 10 + #define CONFIGURE_MAXIMUM_PIPES 10 + #else + #define CONFIGURE_IMFS_ENABLE_MKFIFO + #endif + + #define MAX_FILE_DESCRIPTORS 200 + #if __RTEMS_MAJOR__ < 5 + #define CONFIGURE_LIBIO_MAXIMUM_FILE_DESCRIPTORS MAX_FILE_DESCRIPTORS + #else + #define CONFIGURE_MAXIMUM_FILE_DESCRIPTORS MAX_FILE_DESCRIPTORS + #endif + +Clock Manager +------------- + +The directive :c:func:`rtems_clock_get` was removed. See section +`Transition Advice for the Removed rtems_clock_get()` in the +`RTEMS Classic API Guide` for alternatives. + +File Descriptors +---------------- + +In RTEMS 5.1, the list of free file descriptors has a LIFO ordering in contrast +to previous versions where it was a FIFO. This means if an application +regularly opens and closes files (or sockets) it sees the whole range of file +descriptors. The reason for this change was to increase the time before file +descriptors are reused to more likely catch a file descriptor use after close. + +This change may surface application issues. If the configured file descriptor +maximum (``CONFIGURE_MAXIMUM_FILE_DESCRIPTORS``) is greater than the +``FD_SETSIZE`` defined by Newlib to 64, then calls to ``select()`` are undefined +behaviour and may corrupt the thread stack. In particular, ``FD_SET()`` may +result in an out of bounds access. It is possible to define a custom +``FD_SETSIZE``. The application must ensure that the custom ``FD_SETSIZE`` is +defined before ``<sys/select.h>`` is included in all modules used by the +application, for example via a global compiler command line define. This +applies also to all third-party libraries used by the application. + +Networking +---------- + +The following code samples provides a simple way to initialise and start +networking with the BSD Library's (``libbsd``) networking stack. The simplest +method to configure the networking stack is to provide a :file:`/etc/rc,conf` +file on your target. If your target has no non-volatile media for a file system +create the :file:`rc.conf` file each time your application starts. + +The :file:`rc.conf` support in ``libbsd`` provides a number of needed support +settings. We recommend you search for FreeBSD and ``rc.conf`` to view the +available online documentation that FreeBSD provides. + +In this example the network interface is ``cgem0``, replace with your +interface name. + +.. code-block:: c + + static const char* rc_conf = + "# /etc/rc.conf\n" \ + "hostname=\"rtems5-libbsd\"\n" \ + "ifconfig_cgem0=\"inet 10.1.2.3 netmask 255.255.255.0 rxcsum txcsum\"\n" \ + "ifconfig_cgem0_alias0=\"ether 00:80:81:82:83:84\"\n" \ + "defaultrouter=\"10.1.2.1\"\n" \ + "telnetd_enable=\"YES\"\n"; + + void start_network(void) + { + FILE *rc; + int r; + + /* + * Initialise libbsd. + */ + rtems_bsd_initialize(); + + /* + * Create the /etc/rc,conf, assume /etc exists. + */ + rc = fopen("/etc/rc.conf", "w"); + if (rc_conf == NULL) { + printf("error: cannot create /etc/rc.conf\n"); + exit(1); + } + + fprintf(rc, rc_conf); + fclose(rc); + + /* + * Arguments are timeout and trace + */ + r = rtems_bsd_run_etc_rc_conf(30, false); + if (r < 0) { + printf("error: loading /etc/rc.conf failed: %s\n",strerror(errno)); + exit(1); + } + } + +Shell Environment +----------------- + +To address resource leaks in the RTEMS shell, the management of shell +environments changed. This change may break existing code. Here is an example +how a broken Telnet shell can be fixed: + +.. code-block:: c + + static void + telnet_shell( char *name, void *arg ) + { + rtems_shell_env_t env; + + /* Previous WRONG approach: memset( &env, 0, sizeof( env) ); */ + + /* Correct way to initialize the shell environment */ + rtems_shell_dup_current_env( &env ); + + env.devname = name; + env.taskname = "TLNT"; + env.login_check = NULL; + env.forever = false; + + rtems_shell_main_loop( &env ); + } diff --git a/user/migration/v5-to-v6.rst b/user/migration/v5-to-v6.rst new file mode 100644 index 0000000..98c7366 --- /dev/null +++ b/user/migration/v5-to-v6.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 embedded brains GmbH & Co. KG + +.. _Migration_5_to_6: + +RTEMS 5 to RTEMS 6 +================== + +This section provides helpful information when migrating from RTEMS 5 to +RTEMS 6. + +Update to GCC 10 and Later +-------------------------- + +The tool suite for RTEMS 6 uses at least GCC 10. GCC 10 and later enable +``-fno-common`` by default. Code bases which never used this option before may +observe now multiple definition linker errors. For example, if global +variables are declared and defined in header files (usually a missing +``extern`` in the header file). + +No -specs bsp_specs GCC Option +------------------------------ + +The ``-spec bsp_specs`` GCC Option is no longer needed to build RTEMS +applications and there is no :file:`bsp_specs` file installed. If you use this +option, then you get an error like this: + +.. code-block:: none + + sparc-rtems6-gcc: fatal error: cannot read spec file 'bsp_specs': No such file or directory + +You can remove this GCC option from your build to fix this error. +Alternatively, you can add an empty :file:`bsp_specs` file. + +Replacements for Removed APIs +----------------------------- + +* The ``rtems_iterate_over_all_threads()`` directive was removed. Use + ``rtems_task_iterate()`` instead. + +* The ``rtems_get_current_processor()`` directive was removed. Use + ``rtems_scheduler_get_processor()`` instead. + +* The ``rtems_get_processor_count()`` directive was removed. Use + ``rtems_scheduler_get_processor_maximum()`` instead. + +* The ``boolean`` type was removed. Use ``bool`` instead. + +* The ``single_precision`` type was removed. Use ``float`` instead. + +* The ``double_precision`` type was removed. Use ``double`` instead. + +* The ``proc_ptr`` type was removed. Use a proper function pointer type. + +* The ``rtems_context`` type was removed. If you need this type in your + applications, please ask on the :r:list:`devel`. + +* The ``rtems_context_fp`` type was removed. If you need this type in your + applications, please ask on the :r:list:`devel`. + +* The ``rtems_extension`` type was removed. Use ``void`` instead. + +* The ``rtems_io_lookup_name()`` directive was removed. Use ``stat()`` instead. + +* The ``region_information_block`` type was removed. Use + ``Heap_Information_block`` instead. + +* The ``rtems_thread_cpu_usage_t`` type was removed. Use ``struct timespec`` + instead. + +* The ``rtems_rate_monotonic_period_time_t`` type was removed. Use ``struct + timespec`` instead. + +* The ``_Copyright_Notice`` constant was removed from the API. Use + ``rtems_get_copyright_notice()`` instead. + +* The ``_RTEMS_version`` constant was removed from the API. Use + ``rtems_get_version_string()`` instead. + +* The ``RTEMS_MAXIMUM_NAME_LENGTH`` define was removed. Use + ``sizeof( rtems_name )`` instead. + +* The ``<rtems/system.h>`` header file was removed. Include ``<rtems.h>`` + instead. diff --git a/user/overview/index.rst b/user/overview/index.rst index 550724a..16389d9 100644 --- a/user/overview/index.rst +++ b/user/overview/index.rst @@ -355,6 +355,7 @@ sophisticated real-time applications are significantly reduced. .. [#] Thread-local storage requires some support by the tool chain and the RTEMS architecture support, e.g. context-switch code. It is supported - at least on ARM, PowerPC, RISC-V, SPARC and m68k. Check the - `RTEMS CPU Architecture Supplement <https://docs.rtems.org/branches/master/cpu-supplement.pdf>`_ - if it is supported. + at least on ARM, AArch64, PowerPC, RISC-V, SPARC, MicroBlaze, Nios II, + and m68k. Check the `RTEMS CPU Architecture Supplement + <https://docs.rtems.org/branches/master/cpu-supplement.pdf>`_ if it is + supported. diff --git a/user/rsb/commands.rst b/user/rsb/commands.rst index b85692d..4048568 100644 --- a/user/rsb/commands.rst +++ b/user/rsb/commands.rst @@ -199,22 +199,22 @@ The ``arguments`` are a list of build sets to build. Path to the configuration directory. This overrides the built in defaults. ``--builddir path``: - Path to the build directory. This overrides the default of +build+. + Path to the build directory. This overrides the default of `build`. ``--sourcedir path``: - Path to the source directory. This overrides the default of +source+. + Path to the source directory. This overrides the default of `source`. ``--patchdir path``: - Path to the patches directory. This overrides the default of +patches+. + Path to the patches directory. This overrides the default of `patches`. ``--tmppath path``: - Path to the temporary directory. This overrides the default of +tmp+. + Path to the temporary directory. This overrides the default of `tmp`. ``--macros files``: Macro files to load. The configuration directory path is searched. ``--log file``: - Log all the output from the build process. The output is directed to +stdout+ + Log all the output from the build process. The output is directed to `stdout` if no log file is provided. ``--url url``: @@ -296,42 +296,83 @@ The ``arguments`` are a list of build sets to build. Print a list of dependent files used by a build set. Dependent files have a ``dep[?]` prefix where ``?`` is a number. The files are listed alphabetically. -Set Builder (sb-builder) -^^^^^^^^^^^^^^^^^^^^^^^^ +Track (sb-track) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This command checks build sets and configurations reporting any errors, the +dependencies and which files are referenced. The command can list all the +configuration files not referenced. If this option is used when checking all +build set files a list of all configuration files not referenced can be +found. The list can be used to purge the RSB of old and unused configurations. -This command builds a configuration as described in a configuration -file. Configuration files have the extension of ``.cfg``: +The check runs a build set through a number of host configurations. This +checks any logic that is specific to a host. + +The command reports a dependency tree for a build set in the output +report. For example the dependency tree for the ``database/sqlite`` build set +is: .. code-block:: none - $ ./source-builder/sb-builder --help - sb-builder: [options] [args] - RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns - Options and arguments: - --force : Force the build to proceed - --quiet : Quiet output (not used) - --trace : Trace the execution - --dry-run : Do everything but actually run the build - --warn-all : Generate warnings - --no-clean : Do not clean up the build tree - --always-clean : Always clean the build tree, even with an error - --jobs : Run with specified number of jobs, default: num CPUs. - --host : Set the host triplet - --build : Set the build triplet - --target : Set the target triplet - --prefix path : Tools build prefix, ie where they are installed - --topdir path : Top of the build tree, default is $PWD - --configdir path : Path to the configuration directory, default: ./config - --builddir path : Path to the build directory, default: ./build - --sourcedir path : Path to the source directory, default: ./source - --patchdir path : Path to the patches directory, default: ./patches - --tmppath path : Path to the temp directory, default: ./tmp - --macros file[,[file] : Macro format files to load after the defaults - --log file : Log file where all build out is written too - --url url[,url] : URL to look for source - --targetcflags flags : List of C flags for the target code - --targetcxxflags flags : List of C++ flags for the target code - --libstdcxxflags flags : List of C++ flags to build the target libstdc++ code - --with-<label> : Add the --with-<label> to the build - --without-<label> : Add the --without-<label> to the build - --list-configs : List available configurations + +-- rtems/config/databases/sqlite.bset + +-- rtems/config/databases/sqlite-3.31.1-1.cfg + +-- rtems/config/rtems-bsp.cfg + +-- source-builder/config/sqlite-3-1.cfg + +-- rtems/config/rtems-package.bset + +-- rtems/config/rtems-urls.bset + +-- rtems/config/rtems-version.bset + +The comnmand is: + +.. code-block:: none + + $ ../source-builder/sb-track --help + usage: sb-dep-check [-h] [--rtems-version RTEMS_VERSION] [--list-hosts] + [--list-bsets] [--output OUTPUT] [--log LOG] [--trace] + [--not-referenced] + [bsets [bsets ...]] + + RTEMS Track Dependencies a build set has for all hosts. + + positional arguments: + bsets Build sets. + + optional arguments: + -h, --help show this help message and exit + --rtems-version RTEMS_VERSION + Set the RTEMS version. + --list-hosts List the hosts. + --list-bsets List the hosts. + --output OUTPUT Output file. + --log LOG Log file. + --trace Enable trace logging for debugging. + --not-referenced Write out the list of config files not referenced. + +The ``bsets`` are a list of build sets to check. If none are provided all +build sets are checked. + +**Options**: + +``-h, --help``: + The command's help. + +``--rtems-version``: + Set the RTEMS version number. + +``--list-hosts``: + List the hosts each build set of check against. + +``--list-bsets``: + List all the build set files. + +``--output``: + Write the report to the output file. + +``--log``: + The log file the build set check processing is written too. + +``--trace``: + Enable trace debugging. + +``--not-referenced``: + List the configration files not referenced by a build set in the output. diff --git a/user/rsb/configuration.rst b/user/rsb/configuration.rst index fc387a1..1403c4f 100644 --- a/user/rsb/configuration.rst +++ b/user/rsb/configuration.rst @@ -1,5 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2020 Gedare Bloom <gedare@rtems.org> .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org> .. _Configuration: @@ -39,8 +40,7 @@ The configuration search path is a macro variable and is reference as Build set files have the file extension ``.bset`` and the package build configuration files have the file extension of ``.cfg``. The ``sb-set-builder`` -command will search for *build sets* and the ``sb-builder`` commands works with -package build configuration files. +command will search for *build sets*. Both types of configuration files use the ``#`` character as a comment character. Anything after this character on the line is ignored. There is no @@ -113,8 +113,8 @@ supported compression formats are: ``zip``: ZIP -``xy``: - XY +``xz``: + XZ The output of the decompression tool is fed to the standard ``tar`` utility if not a ZIP file and unpacked into the build directory. ZIP files are unpacked by @@ -130,14 +130,16 @@ source is broken down in a number of smaller files and you require the full package. The source's ``setup`` command must reside in the ``%prep:`` section and it unpacks the source code ready to be built. -If the source URL references the GitHub API server https://api.github.com/ a -tarball of the specified version is download. For example the URL for the -STLINK project on GitHub and version is: +If the source URL references the GitHub API server a tarball of the specified +version is download. For example the URL for a Newlib snapshot GitHub is: .. code-block:: spec - %define stlink_version 3494c11 - %source set stlink https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz + %define newlib_version 08eab6396f678cf5e5968acaed0bae9fd129983b + %define newlib_external 1 + %define newlib_expand_name sourceware-mirror-newlib-cygwin-%{newlib_version} + %source set newlib --rsb-file=newlib-%{newlib_version}.tar.gz \ + https://codeload.github.com/RTEMS/sourceware-mirror-newlib-cygwin/tar.gz/%{newlib_version} GIT ~~~ @@ -181,35 +183,7 @@ errors that can arise. The protocol option lets you set a specific protocol. The ``git://`` prefix used by the RSB to select a git repository can be removed using *none* or -replaced with one of the standard git protcols. - -CVS -~~~ - -A CVS repository can be checked out. CVS is more complex than GIT to handle -because of the modules support. This can effect the paths the source ends up -in. The CVS URL only supports the CVS protocol. You can control the repository -via the URL by appending options and arguments to the CVS path. The options are -delimited by ``?`` and option arguments are delimited from the options with -``=``. The options are: - -``module``: - The module to checkout. - -``src-prefix``: - The path into the source where the module starts. - -``tag``: - The CVS tag to checkout. - -``date``: - The CVS date to checkout. - -The following is an example of checking out from a CVS repository: - -.. code-block:: spec - - %source set newlib cvs://pserver:anoncvs@sourceware.org/cvs/src?module=newlib?src-prefix=src +replaced with one of the standard git protocols. Macros and Defaults ^^^^^^^^^^^^^^^^^^^ @@ -315,7 +289,7 @@ Maps are declared anywhere in the map using the map directive: 1. The map is set to ``my-special-map``. -Any macro defintions following a map declaration are placed in that map and the +Any macro definitions following a map declaration are placed in that map and the default map is ``global`` when loading a file. Maps are selected in configuration files by using the ``%select`` directive: @@ -328,9 +302,10 @@ if present return that value else the ``global`` map is used. Any new macros or changes update only the ``global`` map. This may change in future releases so please make sure you use the ``override`` attribute. -The macro files specificed on the command line are looked for in the -``_configdir`` paths. See <<X1,``_configdir``>> variable for details. Included -files need to add the ``%{_configdir}`` macro to the start of the file. +The macro files specified on the command line are looked for in the +``_configdir`` paths. See the definition of ``_configdir`` in +:ref:`Configuration` for details. Included files need to add the +``%{_configdir}`` macro to the start of the file. Macro map files can include other macro map files using the ``%include`` directive. The macro map to build *binutils*, *gcc*, *newlib*, *gdb* and @@ -364,11 +339,26 @@ points to are loaded. The second is a file called ``.rsb_macros`` in your home directory. You need to have the environment variable ``HOME`` defined for this work. +Configuration Reports +^^^^^^^^^^^^^^^^^^^^^ + +A configuration report detailing a build configuration is generated by the +``sb-set-builder`` command. The report can also be generated separately from +the build process by invoking the ``sb-report`` command on the build set used +for the build, for example: + +.. code-block:: shell + + cd rtems + ../source-builder/sb-reports 5/rtems-sparc + less 5-rtems-sparc.txt + Report Mailing -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ -The build reports can be mailed to a specific email address to logging and -monitoring. Mailing requires a number of parameters to function. These are: +Configuration reports from a build can be mailed to a specific email address +for logging and monitoring. Mailing requires a number of parameters to +function. These are: - To mail address @@ -459,13 +449,12 @@ tools. File naming provides configuration management. A specific version of a package is captured in a specific set of configuration files. The top level -configuration file referenced in a *build set* or passed to the ``sb-builder`` -command relates to a specific configuration of the package being built. For -example the RTEMS configuration file ``rtems-gcc-4.7.2-newlib-2.0.0-1.cfg`` -creates an RTEMS GCC and Newlib package where the GCC version is 4.7.2, the -Newlib version is 2.0.0, plus any RTEMS specific patches that related to this -version. The configuration defines the version numbers of the various parts -that make up this package: +configuration file referenced in a *build set* relates to a specific +configuration of the package being built. For example the RTEMS configuration +file ``rtems-gcc-4.7.2-newlib-2.0.0-1.cfg`` creates an RTEMS GCC and Newlib +package where the GCC version is 4.7.2, the Newlib version is 2.0.0, plus any +RTEMS specific patches that related to this version. The configuration defines +the version numbers of the various parts that make up this package: .. code-block:: spec @@ -616,13 +605,13 @@ information is kept updated and accurate: Summary: Device Tree Compiler v%{dtc_version} for target %{_target} on host %{_host} Version: %{dtc_version} Release: %{release} - URL: http://www.jdl.com/software/ + URL: https://www.devicetree.org/ BuildRoot: %{_tmppath}/%{name}-root-%(%{__id_u} -n) The next section defines the source and any patches. In this case there is a single source package and it can be downloaded using the HTTP protocol. The RSB knows this is GZip'ped tar file. If more than one package is needed, add -them increasing the index. The ``gcc-4.8-1.cfg`` configuration contains +them increasing the index. The ``gcc-8-1.cfg`` configuration contains examples of more than one source package as well as conditionally including source packages based on the outer configuration options: @@ -631,13 +620,13 @@ source packages based on the outer configuration options: # # Source # - %source set dtc http://www.jdl.com/software/dtc-v%{dtc_version}.tgz + %source set dtc https://www.kernel.org/pub/software/utils/dtc/dtc-%{dtc_version}.tar.gz The remainder of the script is broken in to the various phases of a build. They are: -. Preperation -. Bulding +. Preparation +. Building . Installing, and . Cleaning @@ -713,8 +702,8 @@ installed into the prefix on the build host and you may not even have permissions to perform a real install. Most packages install to the ``prefix`` and the prefix is typically supplied via the command to the RSB or the package's default is used. The default can vary depending on the host's -operating system. To install to a path that is not the prefix the ``DESTDIR`` -make variable is used. Most packages should honour the ``DISTDIR`` make +operating system. To install to a path that is not the prefix the ``DESTDIR`` +make variable is used. Most packages should honour the ``DESTDIR`` make variables and you can typically specify it on the command line to make when invoking the install target. This results in the package being installed to a location that is not the prefix but one you can control. The RSB provides a @@ -745,28 +734,11 @@ Finally there is an optional clean section. The RSB will run this section if ``--no-clean`` has not been provided on the command line. The RSB does clean up for you. -Once we have the configuration files we can execute the build using the -``sb-builder`` command. The command will perform the build and create a tar file -in the ``tar`` directory: - -.. code-block:: none - - $ ../source-builder/sb-builder --prefix=/usr/local \ - --log=log_dtc devel/dtc-1.2.0 - RTEMS Source Builder, Package Builder v0.2.0 - config: devel/dtc-1.2.0 - package: dtc-1.2.0-x86_64-freebsd9.1-1 - download: http://www.jdl.com/software/dtc-v1.2.0.tgz -> sources/dtc-v1.2.0.tgz - building: dtc-1.2.0-x86_64-freebsd9.1-1 - $ ls tar - dtc-1.2.0-x86_64-freebsd9.1-1.tar.bz2 - -If you want to have the package installed automatically you need to create a -build set. A build set can build one or more packages from their configurations -at once to create a single package. For example the GNU tools is typically seen -as binutils, GCC and GDB and a build set will build each of these packages and -create a single build set tar file or install the tools on the host into the -prefix path. +To have a package installed automatically create a build set. A build set can +build one or more packages from their configurations at once to create a +single package. For example the GNU tools is typically seen as binutils, GCC +and GDB and a build set will build each of these packages and create a single +build set tar file or install the tools on the host into the prefix path. The DTC build set file is called ``dtc.bset`` and contains: @@ -799,8 +771,8 @@ To build this you can use something similar to: The build is for a FreeBSD host and the prefix is for user installed packages. In this example I cannot let the source builder perform the install -because I never run the RSB with root priviledges so a build set or bset tar -file is created. This can then be installed using root priviledges. +because I never run the RSB with root privileges so a build set or bset tar +file is created. This can then be installed using root privileges. The command also supplies the ``--trace`` option. The output in the log file will contain all the macros. @@ -971,10 +943,10 @@ expansions supported are: %prep ~~~~~ -The +%prep+ macro starts a block that continues until the next block macro. The +The `%prep` macro starts a block that continues until the next block macro. The *prep* or preparation block defines the setup of the package's source and is a mix of RTEMS Source Builder macros and shell scripting. The sequence is -typically +%source+ macros for source, +%patch+ macros to patch the source +typically `%source` macros for source, `%patch` macros to patch the source mixed with some shell commands to correct any source issues: .. code-block:: spec @@ -998,7 +970,7 @@ example: This URL is the primary location of the GNU GDB source code and the RTEMS Source Builder can download the file from this location and by inspecting the -file extension use ``bzip2`` decompression with +tar+. When the ``%prep`` +file extension use ``bzip2`` decompression with `tar`. When the ``%prep`` section is processed a check of the local ``source`` directory is made to see if the file has already been downloaded. If not found in the source cache directory the package is downloaded from the URL. You can append other base @@ -1039,9 +1011,9 @@ and set up with: Patching also occurs during the preparation stage. Patches are handled in a similar way to the source packages except you only ``add`` patches. Patches are -applied using the +setup+ command. The +setup+ command takes the default patch +applied using the `setup` command. The `setup` command takes the default patch option. You can provide options with each patch by adding them as arguments -before the patch URL. Patches with no options uses the +setup+ default. +before the patch URL. Patches with no options uses the `setup` default. .. code-block:: spec @@ -1600,12 +1572,10 @@ The ``%endif`` macro ends a conditional logic block. ~~~~~~~~~~~ The ``%bconf_with`` macro provides a way to test if the user has passed a -specific option on the command line with the ``--with-<label>`` option. This -option is only available with the ``sb-builder`` command. +specific option on the command line with the ``--with-<label>`` option. %bconf_without ~~~~~~~~~~~~~~ The ``%bconf_without`` macro provides a way to test if the user has passed a -specific option on the command line with the ``--without-<label>`` option. This -option is only available with the ``sb-builder`` command. +specific option on the command line with the ``--without-<label>`` option. diff --git a/user/rsb/cross-canadian-cross.rst b/user/rsb/cross-canadian-cross.rst index 8eceed3..7ccd6c3 100644 --- a/user/rsb/cross-canadian-cross.rst +++ b/user/rsb/cross-canadian-cross.rst @@ -37,7 +37,7 @@ To build the Curl package for RTEMS you enter the RSB command: 2. The ``--host`` command is the RTEMS architecture and version. - 3. The BSP is built and installed in the prefix. The arhcitecture must match + 3. The BSP is built and installed in the prefix. The architecture must match the ``--host`` architecture. .. note: Installing Into Different Directories diff --git a/user/rsb/index.rst b/user/rsb/index.rst index c307ebe..9bbc2e1 100644 --- a/user/rsb/index.rst +++ b/user/rsb/index.rst @@ -44,7 +44,7 @@ how to build that package from source and taught this tool. .. sidebar:: Setting up your Host - See :ref:`QuickStartHost` for details on setting up hosts. + See :ref:`QuickStartPreparation` for details on setting up hosts. The RTEMS Source Builder is known to work on: diff --git a/user/rsb/project-sets.rst b/user/rsb/project-sets.rst index 6eb8729..ce839c5 100644 --- a/user/rsb/project-sets.rst +++ b/user/rsb/project-sets.rst @@ -116,6 +116,15 @@ build sets: ``--with-objc`` Attempt to build a C++ compiler. +``--with-newlib-tls`` or ``--without-newlib-tls`` + Enable or disable the ``--enable-newlib-reent-thread-local`` Newlib + configuration option. This option is enabled by default on the aarch64, arm, + nios2, powerpc, riscv, and sparc targets. If this option is enabled, then + each member of the Newlib struct _reent is replaced by a dedicated + thread-local object. The thread-local objects are defined in translation + units which use the corresponding object so that only objects used by the + application are linked in. + The RSB provides build sets for some BSPs. These build sets will build: - Compiler, linker, debugger and RTEMS Tools. @@ -154,7 +163,7 @@ Patches are added to a component's name and in the ``%prep:`` section the patches can be set up, meaning they are applied to source. The patches are applied in the order they are added. If there is a dependency make sure you order the patches correctly when you add them. You can add any number of -patches and the RSB will handle them efficently. +patches and the RSB will handle them efficiently. Patches can have options. These are added before the patch URL. If no options are provided the patch's setup default options are used. diff --git a/user/rsb/third-party-packages.rst b/user/rsb/third-party-packages.rst index 0d9fa81..8610650 100644 --- a/user/rsb/third-party-packages.rst +++ b/user/rsb/third-party-packages.rst @@ -133,7 +133,7 @@ A custom RTEMS patch to an executate's source code can turn it into a function that can be called by the RTEMS shell. Users can call the function in their executables simulating the running of the package's command. If the package does not export the code in a suitable manner please contact the project's -commuinity and see if you can work with them to provide a way for the code to +community and see if you can work with them to provide a way for the code to be exported. This may be difficult because exporting internal headers and functions opens the project up to API compatibility issues they did not have before. In the simplest case attempting to get the code into a static library diff --git a/user/start/app.rst b/user/start/app.rst index fdf6bb7..0599305 100644 --- a/user/start/app.rst +++ b/user/start/app.rst @@ -1,11 +1,249 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2019 embedded brains GmbH -.. Copyright (C) 2019 Sebastian Huber +.. Copyright (C) 2020 Chris Johns .. _QuickStartAPP: Build Your Application ====================== -TODO +You tested a BSP in the previous section. We built the ``erc32`` BSP +and it is installed under :file:`$HOME/quick-start/rtems/@rtems-ver-major@`. + +We will now create a simple Hello World application with a Git +repository and using the `Waf <https://waf.io>`_ build system. + +The application is be created in :file:`$HOME/quick-start/app/hello`. + +In the output in this section the base directory :file:`$HOME/quick-start` was +replaced by ``$BASE``. + +The steps in this section assume you are in the directory +:file:`$HOME/quick-start/app/hello` after the first step changes to +it. + +Setup the application work space. Create a new Git repository, download +the Waf build system, and the `RTEMS Waf +<https://git.rtems.org/rtems_waf.git/tree/README>`_. + +Create the application directory and change into it: + +.. code-block:: none + + mkdir -p $HOME/quick-start/app/hello + cd $HOME/quick-start/app/hello + +Download the Waf build system and set it to executable: + +.. code-block:: none + + curl https://waf.io/waf-2.0.19 > waf + chmod +x waf + +Initialise a new Git repository: + +.. code-block:: none + + git init + +Add RTEMS Waf support as a Git sub-module and initialise it: + +.. code-block:: none + + git submodule add git://git.rtems.org/rtems_waf.git rtems_waf + +Create the application source files. Three files are created with an +editor of your choice. + +First create a C file that configures RTEMS. Using an editor create a +file called :file:`init.c` and copy the following configuration +settings: + +.. code-block:: c + + /* + * Simple RTEMS configuration + */ + + #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER + #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER + + #define CONFIGURE_UNLIMITED_OBJECTS + #define CONFIGURE_UNIFIED_WORK_AREAS + + #define CONFIGURE_RTEMS_INIT_TASKS_TABLE + + #define CONFIGURE_INIT + + #include <rtems/confdefs.h> + +Create the Hello World application source file. Using an editor +create :file:`hello.c` and copy the follow code: + +.. code-block:: c + + /* + * Hello world example + */ + #include <rtems.h> + #include <stdlib.h> + #include <stdio.h> + + rtems_task Init( + rtems_task_argument ignored + ) + { + printf( "\nHello World\n" ); + exit( 0 ); + } + +Finally create the Waf script. Using an editor create :file:`wscript` +and copy the Waf script: + +.. code-block:: python + + # + # Hello world Waf script + # + from __future__ import print_function + + rtems_version = "6" + + try: + import rtems_waf.rtems as rtems + except: + print('error: no rtems_waf git submodule') + import sys + sys.exit(1) + + def init(ctx): + rtems.init(ctx, version = rtems_version, long_commands = True) + + def bsp_configure(conf, arch_bsp): + # Add BSP specific configuration checks + pass + + def options(opt): + rtems.options(opt) + + def configure(conf): + rtems.configure(conf, bsp_configure = bsp_configure) + + def build(bld): + rtems.build(bld) + + bld(features = 'c cprogram', + target = 'hello.exe', + cflags = '-g -O2', + source = ['hello.c', + 'init.c']) + +Configure the application using Waf's ``configure`` command: + +.. code-block:: none + + ./waf configure --rtems=$HOME/quick-start/rtems/6 --rtems-bsp=sparc/erc32 + +The output will be something close to: + +.. code-block:: none + + Setting top to : $BASE/app/hello + Setting out to : $BASE/app/hello/build + RTEMS Version : @rtems-ver-major@ + Architectures : sparc-rtems@rtems-ver-major@ + Board Support Package (BSP) : sparc-rtems@rtems-ver-major@-erc32 + Show commands : no + Long commands : no + Checking for program 'sparc-rtems@rtems-ver-major@-gcc' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc + Checking for program 'sparc-rtems@rtems-ver-major@-g++' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-g++ + Checking for program 'sparc-rtems@rtems-ver-major@-gcc' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc + Checking for program 'sparc-rtems@rtems-ver-major@-ld' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ld + Checking for program 'sparc-rtems@rtems-ver-major@-ar' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar + Checking for program 'sparc-rtems@rtems-ver-major@-nm' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-nm + Checking for program 'sparc-rtems@rtems-ver-major@-objdump' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-objdump + Checking for program 'sparc-rtems@rtems-ver-major@-objcopy' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-objcopy + Checking for program 'sparc-rtems@rtems-ver-major@-readelf' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-readelf + Checking for program 'sparc-rtems6-strip' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-strip + Checking for program 'sparc-rtems6-ranlib' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ranlib + Checking for program 'rtems-ld' : $BASE/rtems/@rtems-ver-major@/bin/rtems-ld + Checking for program 'rtems-tld' : $BASE/rtems/@rtems-ver-major@/bin/rtems-tld + Checking for program 'rtems-syms' : $BASE/rtems/@rtems-ver-major@/bin/rtems-syms + Checking for program 'rtems-bin2c' : $BASE/rtems/@rtems-ver-major@/bin/rtems-bin2c + Checking for program 'tar' : /usr/bin/tar + Checking for program 'gcc, cc' : $BASE/rtems/6/bin/sparc-rtems6-gcc + Checking for program 'ar' : $BASE/rtems/6/bin/sparc-rtems6-ar + Checking for program 'g++, c++' : $BASE/rtems/6/bin/sparc-rtems6-g++ + Checking for program 'ar' : $BASE/rtems/6/bin/sparc-rtems6-ar + Checking for program 'gas, gcc' : $BASE/rtems/6/bin/sparc-rtems6-gcc + Checking for program 'ar' : $BASE/rtems/6/bin/sparc-rtems6-ar + Checking for c flags '-MMD' : yes + Checking for cxx flags '-MMD' : yes + Compiler version (sparc-rtems@rtems-ver-major@-gcc) : 10.2.1 20210309 (RTEMS @rtems-ver-major@, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9) + Checking for a valid RTEMS BSP installation : yes + Checking for RTEMS_DEBUG : no + Checking for RTEMS_MULTIPROCESSING : no + Checking for RTEMS_NEWLIB : yes + Checking for RTEMS_POSIX_API : no + Checking for RTEMS_SMP : no + Checking for RTEMS_NETWORKING : no + 'configure' finished successfully (1.142s) +Build the application: + +.. code-block:: none + + ./waf + +The output will be something close to: + +.. code-block:: none + + Waf: Entering directory `$BASE/app/hello/build/sparc-rtems@rtems-ver-major@-erc32' + [1/3] Compiling init.c + [2/3] Compiling hello.c + [3/3] Linking build/sparc-rtems@rtems-ver-major@-erc32/hello.exe + Waf: Leaving directory `$BASE/app/hello/build/sparc-rtems@rtems-ver-major@-erc32' + 'build-sparc-rtems@rtems-ver-major@-erc32' finished successfully (0.183s) + +Run the executable: + +.. code-block:: none + + rtems-run --rtems-bsps=erc32-sis build/sparc-rtems@rtems-ver-major@-erc32/hello.exe + +The output will be something close to: + +.. code-block:: none + + RTEMS Testing - Run, @rtems-ver-mjminrev@ + Command Line: $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems@rtems-ver-major@-erc32/hello.exe + Host: Linux 5.8.0-44-generic #50~20.04.1-Ubuntu SMP Wed Feb 10 21:07:30 UTC 2021 x86_64 + Python: 3.8.5 (default, Jan 27 2021, 15:41:15) [GCC 9.3.0] + Host: Linux-5.8.0-44-generic-x86_64-with-glibc2.29 (Linux 5.8.0-44-generic #50~20.04.1-Ubuntu SMP Wed Feb 10 21:07:30 UTC 2021 x86_64 x86_64) + + SIS - SPARC/RISCV instruction simulator 2.26, copyright Jiri Gaisler 2020 + Bug-reports to jiri@gaisler.se + + ERC32 emulation enabled + + Loaded build/sparc-rtems@rtems-ver-major@-erc32/hello.exe, entry 0x02000000 + + Hello World + + *** FATAL *** + fatal source: 5 (RTEMS_FATAL_SOURCE_EXIT) + fatal code: 0 (0x00000000) + RTEMS version: 6.0.0.586e06ec6222f1cd1f005aa8f4a34a8b33f5d862 + RTEMS tools: 10.2.1 20210309 (RTEMS @rtems-ver-major@, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9) + executing thread ID: 0x08a010001 + executing thread name: UI1 + cpu 0 in error mode (tt = 0x101) + 158479 0200d500: 91d02000 ta 0x0 + Run time : 0:00:00.259136 + +Commit the application to the repository: + +.. code-block:: none + + git add init.c hello.c wscript + git commit -m "My first RTEMS application." diff --git a/user/start/bootstrap.rst b/user/start/bootstrap.rst deleted file mode 100644 index 9fcf79b..0000000 --- a/user/start/bootstrap.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2019 embedded brains GmbH -.. Copyright (C) 2019 Sebastian Huber - -.. _QuickStartBootstrap: - -Bootstrap the RTEMS Sources -=========================== - -You installed the tool suite in your installation prefix and cloned two RTEMS -repositories in the previous sections. We installed the tool suite in -:file:`$HOME/quick-start/rtems/5` and cloned the repositories in -:file:`$HOME/quick-start/src`. - -If you use source archives of a released RTEMS version, then you can skip this -section. - -Before you can build a :ref:`Board Support Package (BSP) <BSPs>` for your -target hardware, you have to bootstrap the build system in the RTEMS sources. -This is only necessary, if you use a Git repository clone of the RTEMS sources. -You have to do this after a fresh repository clone and sometimes after build -system file updates (e.g. after a ``git pull``). If you are not a build -system expert, then do the bootstrap after each update of build system files. -This is a bit annoying, but improving the build system is a complex and time -consuming undertaking. Feel free to help the RTEMS Project to improve it. For -the bootstrap it is important that the right version of Autotools -(:file:`autoconf` and :file:`automake`) are in your ``$PATH``. The right -version of Autotools is shipped with the RTEMS tool suite you already -installed. - -.. code-block:: none - - cd $HOME/quick-start/src/rtems - export PATH=$HOME/quick-start/rtems/5/bin:"$PATH" - ./bootstrap -c - $HOME/quick-start/src/rsb/source-builder/sb-bootstrap - -These commands should output something like this (omitted lines are denoted by -...): - -.. code-block:: none - - removing automake generated Makefile.in files - removing configure files - removing aclocal.m4 files - $ $HOME/quick-start/src/rsb/source-builder/sb-bootstrap - RTEMS Source Builder - RTEMS Bootstrap, 5 (f07504d27192) - 1/120: autoreconf: configure.ac - 2/120: autoreconf: c/configure.ac - 3/120: autoreconf: c/src/configure.ac - 4/120: autoreconf: c/src/lib/libbsp/arm/configure.ac - ... - 120/120: autoreconf: testsuites/tmtests/configure.ac - Bootstrap time: 0:00:48.744222 diff --git a/user/start/bsp-build.rst b/user/start/bsp-build.rst index 3b9eb15..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: @@ -8,111 +8,200 @@ Build a Board Support Package (BSP) =================================== -You installed the tool suite in your installation prefix, cloned two RTEMS -repositories and bootstrapped the RTEMS sources in the previous sections. We -installed the tool suite in :file:`$HOME/quick-start/rtems/5` and cloned the -repositories in :file:`$HOME/quick-start/src`. We also bootstrapped the RTEMS -sources. +You installed the tool suite in your installation prefix, made ready the source +for two RTEMS source packages and if you are using a Git clone bootstrapped the +RTEMS sources in the previous sections. We installed the tool suite in +:file:`$HOME/quick-start/rtems/6` and unpacked the source in +:file:`$HOME/quick-start/src`. You are now able to build :ref:`Board Support Packages (BSPs) <BSPs>` for all -architectures where you have an RTEMS tool suite installed. To build -applications on top of RTEMS, you have to configure, build and install a BSP -for your target hardware. To select a proper BSP for your target hardware -consult the :ref:`BSPs <BSPs>` chapter. We select the `erc32` BSP. +architectures you have an installed RTEMS tool suite. To build applications on +top of RTEMS, you have to build and install a BSP for your target hardware. To +select a proper BSP for your target hardware consult the :ref:`BSPs <BSPs>` +chapter. We select the `erc32` BSP. The ``erc32`` BSP uses approximately 2.3G +bytes of disk space when the testsuite is built and 44M bytes of space when +installed. -We configure, build and install 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`. +We will first show how to build the BSP using the RSB and then we will show how +to build the same BSP `manually <QuickStartBSPBuild_Manual>`_. You only need to +use one of the listed methods to build the BSP. + +In the output in this section the base directory :file:`$HOME/quick-start` was +replaced by ``$BASE``. + +.. _QuickStartBSPBuild_RSB: + +RSB BSP Build +------------- + +The RSB build of RTEMS does not use the RTEMS source we made ready. It uses the +RSB source you downloaded in a previous section. If you are using a release RSB +source archive the BSP built is the released kernel image. If you are using a +Git clone of the RSB the BSP will be version referenced in the RSB clone. + +To build the BSP with all the tests run this command: .. code-block:: none - mkdir -p $HOME/quick-start/build/b-erc32 + 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=sparc/erc32 --with-rtems-tests=yes @rtems-ver-major@/rtems-kernel -The second step is to configure the BSP. There are various configuration -options available. Some configuration options are BSP-specific. Prepend the -RTEMS tool suite binary directory to your ``$PATH`` throughout the remaining -steps. +This command should output something like: .. code-block:: none - cd $HOME/quick-start/build/b-erc32 - export PATH=$HOME/quick-start/rtems/5/bin:"$PATH" - $HOME/quick-start/src/rtems/configure \ - --prefix=$HOME/quick-start/rtems/5 \ - --enable-maintainer-mode \ - --target=sparc-rtems5 \ - --enable-rtemsbsp=erc32 \ - --enable-tests + RTEMS Source Builder - Set Builder, @rtems-ver-majminver@ + Build Set: @rtems-ver-major@/rtems-kernel + config: tools/rtems-kernel-@rtems-ver-major@.cfg + package: sparc-rtems@rtems-ver-major@-kernel-erc32-1 + building: sparc-rtems@rtems-ver-major@-kernel-erc32-1 + sizes: sparc-rtems@rtems-ver-major@-kernel-erc32-1: 2.279GB (installed: 44.612MB) + cleaning: sparc-rtems@rtems-ver-major@-kernel-erc32-1 + reporting: tools/rtems-kernel-@rtems-ver-major@.cfg -> sparc-rtems@rtems-ver-major@-kernel-erc32-1.txt + reporting: tools/rtems-kernel-@rtems-ver-major@.cfg -> sparc-rtems@rtems-ver-major@-kernel-erc32-1.xml + installing: sparc-rtems@rtems-ver-major@-kernel-erc32-1 -> $BASE/ + cleaning: sparc-rtems@rtems-ver-major@-kernel-erc32-1 + Build Set: Time 0:03:09.896961 + +The RSB BSP build can be customised with following RSB command line options: + +``--with-rtems-tests``: + Build the test suite. If ``yes`` is provided all tests in the testsuite are + build. If ``no`` is provided no tests are built and if ``samples`` is + provided only the sample executables are built, e.g. + ``--with-rtems-tests=yes``. The test executables are install under the BSP + in the :file:`tests` directory and you can execute them with the + :ref:`tester and run command <rtems-tester-command>`. + +``--with-rtems-smp``: + Build with SMP support. The BSP has to have SMP support or this option will + fail with an error. + +``--with-rtems-legacy-network``: + Build the legacy network software. We recommend you use the current network + support in the RTEMS BSP Library (libbsd) unless you need to maintain a + legacy product. Do not use the legacy networking software for new + developments. + +``--with-rtems-bspopts``: + Build the BSP with BSP specific options. This is an advanced option. Please + refer to the BSP specific details in the :ref:`Board Support Packages + (BSPs)` of this manual or the BSP source code in the RTEMS source + directory. To supply a list of options quote then list with ``"``, e.g. + ``--with-rtems-bspopts="BSP_POWER_DOWN_AT_FATAL_HALT=1"`` + +If you have built a BSP with the RSB, you can move on to +:ref:`QuickStartBSPTest`. + +.. _QuickStartBSPBuild_Manual: + +Manual BSP Build +---------------- + +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: -This command should output something like this (omitted lines are denoted by -...): +.. code-block:: none + + export PATH=$HOME/quick-start/rtems/@rtems-ver-major@/bin:"$PATH" + +Check your installed tools can be found by running: .. code-block:: none - checking for gmake... gmake - checking for RTEMS Version... 5.0.0 - checking build system type... x86_64-unknown-freebsd12.0 - checking host system type... x86_64-unknown-freebsd12.0 - checking target system type... sparc-unknown-rtems5 - ... - config.status: creating Makefile + command -v sparc-rtems@rtems-ver-major@-gcc && echo "found" || echo "not found" + +The output should be: + +.. code-block:: none - target architecture: sparc. - available BSPs: erc32. - 'gmake all' will build the following BSPs: erc32. - other BSPs can be built with 'gmake RTEMS_BSP="bsp1 bsp2 ..."' + found - config.status: creating Makefile +If ``not found`` is printed the tools are not correctly installed or the path +has not been correctly set. Check the contents of the path +:file:`$HOME/quick-start/rtems/@rtems-ver-major@/bin` manually and if +:file:`sparc-rtems@rtems-ver-major@-gcc` is present the path is wrong. If the +file cannot be found return to :ref:`QuickStartTools` and install the tools +again. + +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 +of the tests with the ``BUILD_TESTS = True`` option and use default values for +everything else. For detailed information about the BSP build system, see +:ref:`BSPBuildSystem`. + +.. code-block:: none + + cd $HOME/quick-start/src/rtems + echo "[sparc/erc32]" > config.ini + echo "BUILD_TESTS = True" >> config.ini + ./waf configure --prefix=$HOME/quick-start/rtems/@rtems-ver-major@ + +The first invocation of ``./waf`` needs a bit of time (e.g. 10 seconds) since an +internal cache file is populated. This command should output something like +this. In this output the base directory :file:`$HOME/quick-start` was replaced +by ``$BASE``. + +.. code-block:: none + + Setting top to : $BASE/quick-start/src/rtems + Setting out to : $BASE/quick-start/src/rtems/build + Configure board support package (BSP) : sparc/erc32 + Checking for program 'sparc-rtems@rtems-ver-major@-gcc' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc + Checking for program 'sparc-rtems@rtems-ver-major@-g++' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-g++ + Checking for program 'sparc-rtems@rtems-ver-major@-ar' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar + Checking for program 'sparc-rtems@rtems-ver-major@-ld' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ld + Checking for program 'ar' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar + Checking for program 'g++, c++' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-g++ + Checking for program 'ar' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar + Checking for program 'gas, gcc' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc + Checking for program 'ar' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar + Checking for program 'gcc, cc' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc + Checking for program 'ar' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar + Checking for asm flags '-MMD' : yes + Checking for c flags '-MMD' : yes + Checking for cxx flags '-MMD' : yes + Checking for program 'rtems-bin2c' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-bin2c + Checking for program 'gzip' : /usr/bin/gzip + Checking for program 'rtems-ld' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-ld + Checking for program 'rtems-syms' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-syms + Checking for program 'xz' : $BASE/anaconda3/bin/xz + 'configure' finished successfully (0.414s) Building the BSP is the third step. .. code-block:: none - cd $HOME/quick-start/build/b-erc32 - make + cd $HOME/quick-start/src/rtems + ./waf This command should output something like this (omitted lines are denoted by -...). In this output the base directory :file:`$HOME/quick-start` was replaced -by ``$BASE``. +...). .. code-block:: none - Configuring RTEMS_BSP=erc32 - checking for gmake... gmake - checking build system type... x86_64-unknown-freebsd12.0 - checking host system type... sparc-unknown-rtems5 - checking rtems target cpu... sparc - checking for a BSD-compatible install... /usr/bin/install -c - checking whether build environment is sane... yes - checking for sparc-rtems5-strip... sparc-rtems5-strip - checking for a thread-safe mkdir -p... $BASE/src/rtems/c/src/../../install-sh -c -d - checking for gawk... no - checking for mawk... no - checking for nawk... nawk - checking whether gmake sets $(MAKE)... yes - checking whether to enable maintainer-specific portions of Makefiles... yes - checking for RTEMS_BSP... erc32 - checking whether CPU supports libposix... yes - configure: setting up make/custom - configure: creating make/erc32.cache - gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32' - ... - sparc-rtems5-gcc -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -B./../../lib/libbsp/sparc/erc32 -B$BASE/src/rtems/bsps/sparc/erc32/start -specs bsp_specs -qrtems -L./../../cpukit -L$BASE/src/rtems/bsps/sparc/shared/start -Wl,--wrap=printf -Wl,--wrap=puts -Wl,--wrap=putchar -Wl,--gc-sections -o spwkspace.exe spwkspace/spwkspace-init.o ./../../lib/libbsp/sparc/erc32/librtemsbsp.a ./../../cpukit/librtemscpu.a - gmake[5]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/testsuites/sptests' - gmake[4]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/testsuites' - gmake[3]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32' - gmake[2]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32' - gmake[1]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c' - gmake[1]: Entering directory '$BASE/build/b-erc32' - gmake[1]: Nothing to be done for 'all-am'. - gmake[1]: Leaving directory '$BASE/build/b-erc32' + Waf: Entering directory `$BASE/quick-start/src/rtems/build' + Waf: Leaving directory `$BASE/quick-start/src/rtems/build' + 'build' finished successfully (0.085s) + Waf: Entering directory `$BASE/quick-start/src/rtems/build/sparc/erc32' + [ 1/4093] Compiling bsps/shared/dev/serial/mc68681_reg2.c + [ 2/4093] Compiling bsps/shared/dev/rtc/mc146818a_ioreg.c + [ 3/4093] Compiling bsps/shared/dev/flash/am29lv160.c + ... + [4093/4093] Processing link: build/sparc/erc32/testsuites/libtests/dl01/dl01-tar.o build/sparc/erc32/testsuites/libtests/dl01/init.o build/sparc/erc32/testsuites/libtests/dl01/dl-load.o build/sparc/erc32/testsuites/libtests/dl01/dl01-sym.o -> build/sparc/erc32/testsuites/libtests/dl01.exe + Waf: Leaving directory `$BASE/quick-start/src/rtems/build/sparc/erc32' + 'build_sparc/erc32' finished successfully (2m14.111s) The last step is to install the BSP. .. code-block:: none - cd $HOME/quick-start/build/b-erc32 - make install + cd $HOME/quick-start/src/rtems + ./waf install This command should output something like this (omitted lines are denoted by ...). In this output the base directory :file:`$HOME/quick-start` was replaced @@ -120,27 +209,16 @@ by ``$BASE``. .. code-block:: none - Making install in sparc-rtems5/c - gmake[1]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c' - Making install in . - gmake[2]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c' - gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c' - gmake[3]: Nothing to be done for 'install-exec-am'. - gmake[3]: Nothing to be done for 'install-data-am'. - gmake[3]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c' - gmake[2]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c' - Making install in erc32 - gmake[2]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32' - gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32' - Making install-am in . - Making install-am in cpukit - gmake[4]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/cpukit' - gmake[5]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/cpukit' - gmake[5]: Nothing to be done for 'install-exec-am'. - $BASE/src/rtems/c/src/../../cpukit/../install-sh -c -d '$BASE/rtems/5/sparc-rtems5/erc32/lib/include' + Waf: Entering directory `$BASE/quick-start/src/rtems/build' + Waf: Leaving directory `$BASE/quick-start/src/rtems/build' + 'install' finished successfully (0.081s) + Waf: Entering directory `$BASE/quick-start/src/rtems/build/sparc/erc32' + + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/libchip/am29lv16.h (from bsps/include/libchip/am29lv1.h) + + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/libchip/mc146818a.h (from bsps/include/libchip/mc146818a.h) + + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/libchip/mc68681.h (from bsps/include/libchip/mc68681.h)) ... - $BASE/src/rtems/make/Templates/Makefile.lib '$BASE/rtems/5/share/rtems5/make/Templates' - $BASE/src/rtems/./install-sh -c -d '$BASE/rtems/5/make/custom' - /usr/bin/install -c -m 644 $BASE/src/rtems/make/custom/default.cfg '$BASE/rtems/5/make/custom' - gmake[2]: Leaving directory '$BASE/build/b-erc32' - gmake[1]: Leaving directory '$BASE/build/b-erc32' + + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/rtems/score/watchdogticks.h (from cpukit/include/rtems/score/watchdogticks.h) + + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/rtems/score/wkspace.h (from cpukit/include/rtems/score/wkspace.h) + + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/rtems/score/wkspacedata.h (from cpukit/include/rtems/score/wkspacedata.h) + Waf: Leaving directory `$BASE/quick-start/src/rtems/build/sparc/erc32' + 'install_sparc/erc32' finished successfully (1.834s)) diff --git a/user/start/bsp-test.rst b/user/start/bsp-test.rst index aefeeb9..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: @@ -8,20 +8,20 @@ Test a Board Support Package (BSP) ================================== -You built a BSP with tests in the previous section. We built the ``erc32`` BSP -in :file:`$HOME/quick-start/build/b-erc32`. +You built a BSP with tests in the previous section. We built the +``sparc/erc32`` BSP in :file:`$HOME/quick-start/src/rtems`. You should run the RTEMS test suite on your target hardware. The RTEMS Project provides some support to do this, see the :ref:`Testing <Testing>` chapter for the details. -On the ``erc32`` BSP we selected for this quick start chapter this is easy. -Just run this command: +On the ``sparc/erc32`` BSP we selected for this quick start chapter this is +easy. Just run this command: .. code-block:: none - cd $HOME/quick-start/build/b-erc32 - rtems-test --rtems-bsp=erc32-sis --rtems-tools=$HOME/quick-start/rtems/5 . + cd $HOME/quick-start/src/rtems + rtems-test --rtems-bsp=erc32-sis build/sparc/erc32 This command should output something like this (omitted lines are denoted by ...). In this output the base directory :file:`$HOME/quick-start` was replaced @@ -29,38 +29,44 @@ by ``$BASE``. .. code-block:: none - RTEMS Testing - Tester, 5.0.not_released - Command Line: $BASE/rtems/5/bin/rtems-test --rtems-bsp=erc32-sis --rtems-tools=$BASE/rtems/5 . - Python: 2.7.15 (default, Jan 10 2019, 01:14:47) [GCC 4.2.1 Compatible FreeBSD Clang 6.0.1 (tags/RELEASE_601/final 335540)] - Host: FreeBSD-12.0-RELEASE-p2-amd64-64bit-ELF (FreeBSD Build_FreeBSD12 12.0-RELEASE-p2 FreeBSD 12.0-RELEASE-p2 GENERIC amd64 amd64) - [ 1/589] p:0 f:0 u:0 e:0 I:0 B:0 t:0 i:0 W:0 | sparc/erc32: dhrystone.exe + RTEMS Testing - Tester, 5.1.0 + Command Line: $BASE/rtems/5/bin/rtems-test --rtems-bsp=erc32-sis build/sparc/erc32 + Host: Linux 5.8.0-44-generic #50~20.04.1-Ubuntu SMP Wed Feb 10 21:07:30 UTC 2021 x86_64 + Python: 3.8.5 (default, Jan 27 2021, 15:41:15) [GCC 9.3.0] + Host: Linux-5.8.0-44-generic-x86_64-with-glibc2.29 (Linux 5.8.0-44-generic #50~20.04.1-Ubuntu SMP Wed Feb 10 21:07:30 UTC 2021 x86_64 x86_64) + [ 1/570] p:0 f:0 u:0 e:0 I:0 B:0 t:0 L:0 i:0 W:0 | sparc/erc32: dhrystone.exe ... - [589/589] p:574 f:0 u:5 e:0 I:0 B:3 t:0 i:0 W:0 | sparc/erc32: tmtimer01.exe + [570/570] p:554 f:2 u:6 e:1 I:0 B:3 t:0 L:0 i:0 W:0 | sparc/erc32: ts-validation-1.exe - Passed: 580 - Failed: 0 - User Input: 5 - Expected Fail: 0 + Passed: 558 + Failed: 2 + User Input: 6 + Expected Fail: 1 Indeterminate: 0 Benchmark: 3 - Timeout: 1 + Timeout: 0 + Test too long: 0 Invalid: 0 Wrong Version: 0 Wrong Build: 0 Wrong Tools: 0 ------------------ - Total: 589 + Total: 570 + Failures: + dl06.exe + minimum.exe User Input: - monitor.exe - termios.exe - top.exe - fileio.exe - capture.exe + dl10.exe + monitor.exe + termios.exe + top.exe + capture.exe + fileio.exe + Expected Fail: + psxfenv01.exe Benchmark: - whetstone.exe - linpack.exe - dhrystone.exe - Timeouts: - pppd.exe - Average test time: 0:00:00.437773 - Testing time : 0:04:17.848557 + dhrystone.exe + linpack.exe + whetstone.exe + Average test time: 0:00:00.371256 + Testing time : 0:03:31.616055 diff --git a/user/start/gsoc.rst b/user/start/gsoc.rst new file mode 100644 index 0000000..64b15fa --- /dev/null +++ b/user/start/gsoc.rst @@ -0,0 +1,140 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 Niteesh Babu <niteesh.gs@gmail.com> + +.. _QuickStartGSoC: + +GSoC Getting Started +==================== + +The goal of this page is to help new users, especially students get RTEMS +compiled and running so they can start with the real work. + +Please join the :r:list:`users` and :r:list:`devel` and ask +questions. Help correct any deficiencies in the code or documentation you spot, +including those on the wiki. The ultimate goal of GSoC is to help you become +part of the open source community. + +This section will help you to quickly setup a development environment without +delving into the details. For more information you can go through the other +subsections under :ref:`Quick Start <QuickStart>` chapter or ask on the +:r:list:`devel`. + +We recommend new student developers use the current development (unreleased) +version. The :ref:`Quick Start Preparation <QuickStartPreparation>` should be +consulted for guidance. Some examples shown may use released versions, +which may not be recommended for your purposes. If you are unsure, feel free to +inquire on the :r:list:`devel`. + +You will be best served by using a GNU/Linux environment, which could be in a +virtual machine, for example that uses `Virtualbox <https://www.virtualbox.org/>`_ +and should run on most modern desktop systems. You should also be able to work +with a MacOS or Windows system, but might encounter more difficulty than a *nix +environment. + +Setting up a development environment consists of the following steps. + +1) Installing dependencies for your host operating system. +2) Choosing an installation prefix. +3) Downloading the source code. +4) Installing the tool suite. +5) Building the Board Support Package (BSP). +6) Testing the Board Support Package (BSP). + +Installing Dependencies +----------------------- + +You need tools for your host’s operating system to build the RTEMS tool suite +from source. Please have a look at the :ref:`host-computer` chapter for the +instructions to install the tools for your OS. + +Choosing an installation prefix +------------------------------- + +The term ``prefix`` refers to the path on your computer where the software is to +be installed. +You can refer to the :ref:`Prefix <QuickStartPrefixes>` section for details on +choosing an installation prefix. + +Downloading the Sources +----------------------- + +We will be using Git to clone the sources for RTEMS and RSB. This is the +preferred way if you are planning to make contributions to the RTEMS project. + +Please refer to the :ref:`QuickStartSources_Git` section for instructions on +obtaining sources using Git. + +Installing the Tool Suite +------------------------- + +The Tools suite is the collection of tools required to build the BSP. This +includes the compiler, debugger, assembler and other tools. These tools are +architecture-specific. We will be installing the SPARC tool suite since we are +building a SPARC based BSP. + +Please refer to the :ref:`QuickStartTools` section for instructions on +building and installing the tool suite. Remember to use the current version +associated with the RTEMS development head, see +:ref:`QuickStartPreparation_Version`. + +Building the Board Support Package +---------------------------------- + +There are two ways of building a BSP. We could either ask RSB to build the BSP +or manually build it. In this section will we be building it manually. +Please refer the :ref:`QuickStartBSPBuild_Manual` section for the +instructions. + +Testing the Board Support Package +--------------------------------- + +Testing is an essential part of RTEMS development process. The main reason for +choosing the SPARC erc32 BSP is that, it has very good simulator support. This +will allow you to test your changes without the need for SPARC hardware. + +Please refer to :ref:`QuickStartBSPTest` for instructions on testing the BSP. + +Prove You Can Work On RTEMS +--------------------------- + +This section is only for students interested in Google Summer of Code. + +You have to finish the following task to prove that you can work on RTEMS. + +Modify the hello world example to include a new different print statement. +Something like "Hello from The Dark Side!". Then send us enough to prove to us +that you did this. We want to know you can work with RTEMS. + +Create a patch of your changes and send it to :r:list:`devel` along with the +screenshot of the output. + +If you followed this guide, this hello world modification will likely need to be +made in ``$HOME/quick-start/src/rtems/testsuites/samples/hello/init.c``. +To test your changes, you have to build the BSP again. This could be done by +running `make` in the BSP build directory. + +.. code-block:: none + + cd $HOME/quick-start/src/rtems + ./waf + +If you are happy with your changes you can commit the changes and send the patch +to :r:list:`devel`. + +Creating and Sending Patches +---------------------------- + +Before sending patches, make sure that the changes you have made conforms to +RTEMS coding standards. +You can refer to :ref:`Contributing` section for instruction on creating and +sending patches. + +Here are a few pointers to keep in mind while creating the patches. + +* Make sure not to commit changes in the master branch. This is to avoid merge + conflicts when you are pulling the latest changes from the remote branch. +* Avoid trailing whitespace errors. +* The author name of the patch is your full name. +* The author email of the patch is your valid email address. +* Ensure that your patches build before sending them for review. diff --git a/user/start/host.rst b/user/start/host.rst deleted file mode 100644 index f891f5d..0000000 --- a/user/start/host.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. SPDX-License-Identifier: CC-BY-SA-4.0 - -.. Copyright (C) 2019 embedded brains GmbH -.. Copyright (C) 2019 Sebastian Huber - -.. _QuickStartHost: - -Prepare Your Host Computer -========================== - -The *host computer* is a computer you use to develop applications. It runs all -your tools, editors, documentation viewers, etc. To get started with RTEMS -development you need tools from your host's operating system to build the RTEMS -tool suite from source. This is not a one-click installation process, but -there are :ref:`good reasons <WhyBuildFromSource>` to build everything from -source. You need a native C, C++ and Python development environment. Please -make sure that you can build native C/C++ applications on your host computer. -You must be able to build native Python C modules. Usually, you have to -install a Python development package for this. Please have a look at the -:ref:`Host Computer <host-computer>` chapter for the gory details. In -particular :ref:`Microsoft Windows <microsoft-windows>` user should do this. diff --git a/user/start/index.rst b/user/start/index.rst index d6333f3..17c34e1 100644 --- a/user/start/index.rst +++ b/user/start/index.rst @@ -14,11 +14,12 @@ applications on top of RTEMS. .. toctree:: - host + preparation prefixes sources tools - bootstrap bsp-build bsp-test app + rsb-packages + gsoc diff --git a/user/start/prefixes.rst b/user/start/prefixes.rst index 9727503..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> @@ -21,32 +21,39 @@ path. Packages for your host computer typically use a default prefix of :file:`/usr/local` on FreeBSD and Linux. You have to select a prefix for your installation. You will build and install -the RTEMS tool suite, an RTEMS kernel for a BSP and you may build and install -third party libraries. You can build them all as a stack with a single prefix -or you can +the RTEMS tool suite, an RTEMS kernel for a BSP, and you may build and install +third party libraries. You can build all the parts as a stack with a single +prefix or you can separate various parts by providing different prefixes to +each part as it is built. Using separate prefixes is for experienced RTEMS +users. -The RTEMS tool suite consists of a cross tool chain (Binutils, GCC, GDB, -Newlib, etc.) for your target architecture and :ref:`other tools <HostTools>` -provided by the RTEMS Project. The RTEMS +Do not select a prefix that is under the top of any of the source trees. The +prefix collects the install output of the various build steps you take in this +guide and need to be kept separate from the sources used. +The RTEMS tool suite consists of a cross tool chain (Binutils, GCC, GDB, +Newlib, etc.) for your target architecture and :ref:`RTEMS tools <HostTools>` +provided by the RTEMS Project. The RTEMS Tools are a toolkit that help create +the RTEMS ecosystem and help support the building of embedded real-time +applications and systems. You build and install the tool suite with the :ref:`RTEMS Source Builder (RSB) <RSB>`. By default, the RSB will start the prefix path with a host operating -system specific path plus :file:`rtems` plus the RTEMS version, e.g. -:file:`/opt/rtems/5` on Linux and :file:`/usr/local/rtems/5` on FreeBSD and -macOS. +system specific path plus :file:`rtems`, and the RTEMS version, e.g. +:file:`/opt/rtems/6` on Linux, and :file:`/usr/local/rtems/6` on FreeBSD and +macOS. Placing the RTEMS version number in the path lets you manage and +migrate RTEMS versions as they are released. It is strongly recommended to run the RSB as a *normal user* and not with *root* privileges (also known as *super user* or *Administrator*). You have to make sure that your normal user has sufficient privileges to create files and directories under the prefix. For example, you can create a directory -:file:`/opt/rtems` and give it to a developer group with read, write and +:file:`/opt/rtems` and give it to a developer group with read, write, and execute permissions. Alternatively, you can choose a prefix in your home -directory, e.g. :file:`$HOME/rtems/5` or with a project-specific component -:file:`$HOME/project-x/rtems/5`. For more ideas, see the -:ref:`project sandboxing <ProjectSandboxing>` section. In this quick start -chapter, we will choose :file:`$HOME/quick-start/rtems/5` for the RTEMS tool -suite prefix. +directory, e.g. :file:`$HOME/rtems/6` or with a project-specific component +:file:`$HOME/project-x/rtems/6`. For more ideas, see the :ref:`project +sandboxing <ProjectSandboxing>` section. In this quick start chapter, we will +choose :file:`$HOME/quick-start/rtems/6` for the RTEMS tool suite prefix. .. warning:: diff --git a/user/start/preparation.rst b/user/start/preparation.rst new file mode 100644 index 0000000..4bfc214 --- /dev/null +++ b/user/start/preparation.rst @@ -0,0 +1,119 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2018 Shashvat Jain +.. Copyright (C) 2019 embedded brains GmbH & Co. KG +.. Copyright (C) 2019 Sebastian Huber +.. Copyright (C) 2020 Chris Johns +.. Copyright (C) 2020 Gedare Bloom + +.. _QuickStartPreparation: + +Preparation +=========== + +You need to perform some basic preparation to get started with RTEMS +development. You need tools from your host's operating system to build the +RTEMS tool suite from source. The RTEMS tools you build are used to build the +Board Support Package (BSP) libraries for your target hardware from source. The +BSP libraries contain the RTEMS operating system. This is not a one-click +installation process, but there are :ref:`good reasons <WhyBuildFromSource>` to +build everything from source. + +During this Quick Start guide you will: + +* Select a suitable place to install RTEMS. + +* Select if you download all the source code before you start building RTEMS or + the source is downloaded on demand as it is needed. If you do not have a + reliable internet connection we recommend you download all the source before + starting a build. + +* Build a tool suite. + +* Build and test a BSP. + +* Optionally build additional packages. + +Alternatively you can build a BSP as a package using the RSB. This is +covered in :ref:`QuickStartBSPPackages` + +Host Computer +------------- + +The *host computer* is a computer you use to develop applications. It runs all +your tools, editors, documentation viewers, etc. You need a native C, C++, and +Python development environment. Please make sure you can build native C/C++ +applications on your host computer. You must be able to build native Python C +modules as some RTEMS tools contain these modules. Usually, you have to +install a Python development package for this. The Python scripts of the RTEMS +Project expect on POSIX systems that a ``python`` command is available [1]_. +Please have a look at the :ref:`Host Computer <host-computer>` chapter for the +gory details. In particular :ref:`Microsoft Windows <microsoft-windows>` users +should do this. + +Selecting a BSP +--------------- + +If you are new to RTEMS and you are looking to try RTEMS then the best suited +Board Support Package (BSP) is the :ref:`SPARC ERC32 <BSP_sparc_erc32>` +(``erc32``). The SPARC ERC32 BSP has a robust simulator that runs the example +and test executables on your host computer. This Quick Start guide will build +the ``erc32`` BSP and run RTEMS tests executables in the simulator. The ERC32 +BSP is a SPARC architecture BSP so the tool suite name is ``sparc-rtems5``. + +If you are looking for a hardware target to run RTEMS on we recommend the +:ref:`BeagleBone Black <BSP_arm_beagleboneblack>` (``beagleboneblack``) +BSP. The BeagleBone Black support includes the RTEMS BSD Library (``libbsd``) +and networking. The BeagleBone Black BSP is an ARM architecture BSP so the tool +suite name is ``arm-rtems5``. + +.. _QuickStartPreparation_Version: + +Selecting a Version of RTEMS +---------------------------- + +In the examples of this manual we will often refer to a specific version of +RTEMS, which will usually be the version that accompanied the publication of +this documentation manual. That may not be the appropriate version for you to +use, for example, it may be too old (or too new) depending on what you are +trying to do. If you're not sure what version to use, we generally recommend +using the most recent release or the development head (master), and you may +want to consult with the same version of the documentation. We hope that newer +is better. + +An RTEMS *release* involves the creation of a single downloadable file, +normally a compressed tarball, that packages the source of all the repositories +in a state consistent with the time the release is created. +A release branch is a git branch pushed to the repositories named with the +numeric identifier of the branch. +A release branch release is a git tag on a release branch with +the tags pushed to the repositories. + +Numbering for RTEMS versions beginning with RTEMS 5 uses a format as follows. +The master branch has the version **N.0.0** with N being the next major release +number. The first release of this series has the version number **N.1.0.** and +there is exactly one commit with this version number in the corresponding +repository. The first bugfix release (minor release) of this series will have +the version number **N.2.0**. The release branch will have the version +number **N.M.1** with **M** being the last minor release of this series. + +For example: ++ 5.0.0 is the version number of the development master for the 5 series. ++ 5.1.0 is the first release of the 5 series. ++ 5.1.1 is the version number of the 5 series release branch right after + the 5.1.0 release until 5.2.0 is released. ++ 5.2.0 is the first bugfix release of the 5 series ++ 5.2.1 is the version number of the 5 series release branch right after + the 5.2.0 release until 5.3.0 is released. ++ 6.0.0 is the version number of the development master for the 6 series. + +RTEMS development tools use **N** as the version number and are expected to +work with all releases and the release branch of the N series. +So to build tools for compiling RTEMS version number 5.1.0 for SPARC use +``sparc-rtems5``. Despite the number not increasing, the tools may change +within a release branch, for example the tools packaged with 5.1.1 still use +the ``sparc-rtems5`` moniker, but are likely not the same as the tools used +in version 5.1.0. This tool mismatch can be a source of confusion. Be sure to +use the toolchain that matches your release. + +.. [1] The Python scripts use a shebang of ``#!/usr/bin/env python``. diff --git a/user/start/rsb-packages.rst b/user/start/rsb-packages.rst new file mode 100644 index 0000000..3119318 --- /dev/null +++ b/user/start/rsb-packages.rst @@ -0,0 +1,184 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2020 Contemporary Software +.. Copyright (C) 2020 Chris Johns + +.. _QuickStartBSPPackages: + +Build an RSB Package +==================== + +This section describes how to build an RTEMS package using the RSB. Before we +start to build a package with the RSB you need to complete these steps: + +- :ref:`QuickStartPrefixes` + +- :ref:`QuickStartSources`. + +Return to here once you have completed these steps. + +You have chosen an installation prefix, the BSP to build, the tool's +architecure and prepared the source for the RSB in the previous sections. We +have chosen :file:`$HOME/quick-start/rtems/5` as the installation prefix, the +``erc32`` BSP and the SPARC architecture name of ``sparc-rtems5``, and unpacked +the RSB source in :file:`$HOME/quick-start/src`. + +You are now able to build :ref:`BSP Packages` or 3rd party libraries of code if you +have built a BSP. + +RTEMS Packages +-------------- + +RTEMS Packages are source packages the RSB build to run on RTEMS. An installed +package is a set of header files and libraries. Your application include the +packages header files to make calls to the package's code and include the +libraries in it's linker options. + +RTEMS packages can be part of the RTEMS Project or they can be external +packages from 3rd parties. RTEMS Project packages include the BSPs and BSD +Library package called ``libbsd``. External 3rd party packages include +networking such has ``curl`` or ``libcurl`` to graphics libraries. + +Packages can depend on other packages and need to be build in the corret +order. For example the FreeBSD Library package depends on the BSP package and a +3rd party library such as ``curl`` depends on the FreeBSD Library package. We +call this layering a vertical software stack. + +RTEMS applications are cross-compiled and this adds complexity when building +libraries of code. RTEMS Packages build with the RSB manage this complexity for +you. + +Package are libraries so they will not be linked into your application until +you make calls to the the code and add the library to your application's linker +command line. + +.. QuickStartRSBPackage_BSPStack: + +BSP Stack Build +--------------- + +A BSP stack build is a single command that uses the RSB to build a BSP software +stack of: + +* Tool suite + +* BSP + +* Packages + +The packages built depend on the BSP and the default will build all packages for a +BSP. + +.. code-block:: none + + cd $HOME/quick-start/src/rsb/rtems + ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \ + --with-rtems-tests=yes bsps/erc32 + +This command should output something like this: + +.. code-block:: none + + RTEMS Source Builder - Set Builder, 5.1.0 + Build Set: bsps/erc32 + Build Set: 5/rtems-sparc.bset + Build Set: 5/rtems-autotools.bset + Build Set: 5/rtems-autotools-internal.bset + config: tools/rtems-autoconf-2.69-1.cfg + package: autoconf-2.69-x86_64-freebsd12.1-1 + building: autoconf-2.69-x86_64-freebsd12.1-1 + sizes: autoconf-2.69-x86_64-freebsd12.1-1: 7.505MB (installed: 0.000B) + ... + building: protobuf-2.6.1-sparc-rtems5-1 + sizes: protobuf-2.6.1-sparc-rtems5-1: 228.079MB (installed: 84.408MB) + cleaning: protobuf-2.6.1-sparc-rtems5-1 + reporting: net/protobuf-2.6.1-1.cfg -> protobuf-2.6.1-sparc-rtems5-1.txt + reporting: net/protobuf-2.6.1-1.cfg -> protobuf-2.6.1-sparc-rtems5-1.xml + staging: protobuf-2.6.1-sparc-rtems5-1 -> $HOME/quick-start/src/rsb/rtems/build/tmp/sb-500-staging + cleaning: protobuf-2.6.1-sparc-rtems5-1 + Build Set: Time 0:00:23.564992 + Build Set: Time 0:02:27.380299 + installing: bsps/erc32 -> $HOME/quick-start/rtems/ + clean staging: bsps/erc32 + Staging Size: 1.372GB + Build Set: Time 0:24:17.83979 + +The RSB BSP build can be customised with following RSB command line options: + +``--with-rtems-tests``: + Build the test suite. If ``yes`` is provided all tests in the testsuite are + build. If ``no`` is provided no tests are built and if ``samples`` is + provided only the sample executables are built, e.g. + ``--with-rtems-tests=yes``. + +``--with-rtems-smp``: + Build with SMP support. The BSP has to have SMP support or this option will + fail with an error. + +``--with-rtems-bspopts``: + Build the BSP with BSP specific options. This is an advanced option. Please + refer to the BSP specific details in the :ref:`Board Support Packages + (BSPs)` of this manual or the BSP source code in the RTEMS source + directory. To supply a list of options quote then list with ``"``, e.g. + ``--with-rtems-bspopts="BSP_POWER_DOWN_AT_FATAL_HALT=1"`` + +Only a limited number of BSPs have RSB support to build as a software stack. To +see which BSPs are supported run this command: + + +.. code-block:: none + + cd $HOME/quick-start/src/rsb/rtems + ../source-builder/sb-set-builder --list-bsets | grep bsps + +Package Build +------------- + +Packages are built using RSB build sets. A build set is a set of builds need to +build a packages. The build steps can be dependencies a package has or it could +be a stack of software to provide specific functionality, i.e. a build set can +be a list of build sets. To view the avaliable build sets run this command: + +.. code-block:: none + + cd $HOME/quick-start/src/rsb/rtems + ../source-builder/sb-set-builder --list-bsets + +RTEMS package naming is based on the naming FreeBSD uses in its ports +collection. + +This Quick Start Guide will build the BSD Library or :file:`5/rtems-libbsd`. + +An RTEMS package is hosted on RTEMS so the tool suite name needs to be supplied +using the ``--host`` option, e.g. ``--host=sparc-rtem5``. The BSP needs to be +provided using the ``--with-rtems-bsp`` option, +e.g. ``--with-rtems-bsp=erc32``. The commands to build ``libbsd`` for the +``erc32`` BSP are: + +.. code-block:: none + + cd $HOME/quick-start/src/rsb/rtems + ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \ + --host=sparc-rtems5 --with-rtems-bsp=erc32 5/rtems-libbsd + +This command should output something like this: + +.. code-block:: none + + RTEMS Source Builder - Set Builder, 5.1.0 + Build Set: 5/rtems-libbsd + config: tools/rtems-libbsd-5.cfg + package: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1 + building: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1 + sizes: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1: 1.199GB (installed: 116.541MB) + cleaning: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1 + reporting: tools/rtems-libbsd-5.cfg -> rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1.txt + reporting: tools/rtems-libbsd-5.cfg -> rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1.xml + installing: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1 -> $HOME/quick-start/rtems/5 + cleaning: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1 + Build Set: Time 0:00:51.898231 + +.. note:: + + Not all packages will build or run with all BSPs. Please ask on the + :r:list:`users` if you have any issues. diff --git a/user/start/sources.rst b/user/start/sources.rst index 692e2bc..a6e66df 100644 --- a/user/start/sources.rst +++ b/user/start/sources.rst @@ -1,7 +1,8 @@ .. 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 .. _QuickStartSources: @@ -9,44 +10,126 @@ Obtain the Sources ================== You have considered and chosen a suitable installation prefix in the previous -section. We have chosen :file:`$HOME/quick-start/rtems/5` as the installation -prefix. +section. We have chosen :file:`$HOME/quick-start/rtems/6` as the installation +prefix. We will show how to use a released version of RTEMS and then as an +alternative we will show you using the :ref:`RSB Git repository +<QuickStartSources_Git>`. Consider using a Git clone if you wish to make +contributions to the RTEMS Project. -You need at least two source archives or Git repositories to work with RTEMS. -You can download the source archives for a released RTEMS version or you can -clone Git repositories to get all versions of RTEMS including the development -head. +You need the RTEMS Source Builder (RSB) to work with RTEMS and we prefer you +use a released version. A released version of the RSB downloads all source code +from the RTEMS servers. Each release archives all the referenced source +providing long term stability as changes in upstream projects do not effect a +release's build. -We will clone the Git repositories into :file:`$HOME/quick-start/src`. +You will need approximately 1.5G bytes of disk space to build the tools, RTEMS +kernel, network stack and 3rd party packages for the ERC32 BSP. + +.. _QuickStartSources_Released: + +Releases +-------- + +You can download the source archives for a released RTEMS version from RTEMS' +servers. Releases can be view at https://ftp.rtems.org/pub/rtems/releases with +the releases listed as a series under a release's major number. For RTEMS 5.1 +the release series is `5 <https://ftp.rtems.org/pub/rtems/releases/5>`_ and the +release path is https://ftp.rtems.org/pub/rtems/releases/5/5.1. + +To work with the archives of a released RTEMS version, simply replace the +version number ``5`` used throughout this chapter with the version number you +selected, e.g. ``sparc-rtems4.11``, ``sparc-rtems6``, and so on. + +Download and unpack using the ``curl`` and ``tar`` command with these commands: .. code-block:: none mkdir -p $HOME/quick-start/src cd $HOME/quick-start/src - git clone git://git.rtems.org/rtems-source-builder.git rsb - git clone git://git.rtems.org/rtems.git + curl https://ftp.rtems.org/pub/rtems/releases/5/5.1/sources/rtems-source-builder-5.1.tar.xz | tar xJf - + +If ``curl`` does not work consider using ``wget`` or a browser. + +The RSB is unpacked under the path ``rtems-source-builder-5.1``. Rename this +to ``rsb`` to get shorter paths during the tool suite build. To do this run +these commands: + +.. code-block:: none + + cd $HOME/quick-start/src + mv rtems-source-builder-5.1 rsb + +.. _QuickStartSources_Released_RTEMS: + +If you wish to build the RTEMS kernel from source obtain the RTEMS kernel +sources: + +.. code-block:: none + + cd $HOME/quick-start/src + curl https://ftp.rtems.org/pub/rtems/releases/5/5.1/sources/rtems-5.1.tar.xz | tar xJf - + +.. _QuickStartSources_Git: + +Git +--- -The :file:`rsb` repository clone contains the -:ref:`RTEMS Source Builder (RSB) <RSB>`. We clone it into -:file:`rsb` to get shorter paths during the tool suite build. The -:file:`rtems` repository clone contains the RTEMS sources. These two -repositories are enough to get started. There are -`more repositories <https://git.rtems.org>`_ available. +Alternatively, clone the Git repositories into :file:`$HOME/quick-start/src`. -Alternatively, you can download the source archives of a released RTEMS -version. +A Git repository clone gives you some flexibility with the added complexity of +needing to use a Git branch to build a released version. With Git you can +switch between branches to try out different RTEMS versions and you have access +to the RTEMS source history. The RTEMS Project welcomes contributions. The Git +repositories enable you to easily create patches and track local changes. + +You can clone the Git repository to get all versions of RTEMS including the +development head. Release branches in Git are kept stable however they may +differ from a release's source archive. .. code-block:: none mkdir -p $HOME/quick-start/src cd $HOME/quick-start/src - curl https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.3/rtems-4.11.3.tar.xz | tar xJf - - curl https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.3/rtems-source-builder-4.11.3.tar.xz | tar xJf - - -This quick start chapter focuses on working with the Git repository clones -since this gives you some flexibility. You can switch between branches to try -out different RTEMS versions. You have access to the RTEMS source history. -The RTEMS Project welcomes contributions. The Git repositories enable you to -easily create patches and track local changes. If you prefer to work with -archives of a released RTEMS version, then simply replace the version number 5 -used throughout this chapter with the version number you selected, e.g. 4.11. + git clone git://git.rtems.org/rtems-source-builder.git rsb + git clone git://git.rtems.org/rtems.git + +The :file:`rsb` repository clone contains the :ref:`RTEMS Source Builder (RSB) +<RSB>`. We clone it into :file:`rsb` to get shorter paths during the tool +suite build. The :file:`rtems` repository clone contains the RTEMS sources. +These two repositories are enough to get started. There are `more repositories +<https://git.rtems.org>`_ available. + +Offline Download +---------------- + +If you have limited Internet access you can download the source before you +start building. If you are permanently connected to the Internet you do not +need to do this and the sources will be automatically download on demand when +needed. + +Once the sources have been downloaded you could disconnect your host computer +from the Internet. It is no longer required to work with RTEMS. To download +the sources to build the ERC 32 BSP before building run the following commands: + +.. code-block:: none + + cd $HOME/quick-start/src/rsb/rtems + ../source-builder/sb-set-builder --source-only-download 6/rtems-sparc + +This command should output something like this (omitted lines are denoted by +``...``): + +.. code-block:: none + + RTEMS Source Builder - Set Builder, 6 (5e449fb5c2cb) + Build Set: 6/rtems-sparc + Build Set: 6/rtems-autotools.bset + Build Set: 6/rtems-autotools-internal.bset + ... + download: https://git.rtems.org/rtems-tools/snapshot/rtems-tools-90342feb4dd63d188ce945adfb0a769...<see log> -> sources/rtems-tools-90342feb4dd63d188ce945adfb0a7694a42a65cd.tar.bz2 + ... + Build Sizes: usage: 0.000B total: 264.228MB (sources: 264.186MB, patches: 43.468KB, installed 0.000B) + Build Set: Time 0:06:34.357125 + +If you encounter errors, check your internet connection, firewall settings, +virus scanners and the availability of the download servers. diff --git a/user/start/tools.rst b/user/start/tools.rst index 07dc1e0..3656867 100644 --- a/user/start/tools.rst +++ b/user/start/tools.rst @@ -1,126 +1,114 @@ .. 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 .. _QuickStartTools: Install the Tool Suite ====================== -You have chosen an installation prefix and cloned two RTEMS repositories in the -previous sections. We have chosen :file:`$HOME/quick-start/rtems/5` as the -installation prefix and cloned the repositories in -:file:`$HOME/quick-start/src`. - -You must select the -:ref:`target architecture <TargetArchitectures>` for which you need a tool -suite. In this quick start chapter we choose `sparc-rtems5`. The -`sparc-rtems5` is the tool suite name for the SPARC architecture and RTEMS -version 5. The tool suite for RTEMS and the RTEMS sources are tightly coupled. -For example, do not use a RTEMS version 5 tool suite with RTEMS version 4.11 -sources and vice versa. We use the RSB in two steps. The first step is to -download additional sources and patches. Afterwards, you could disconnect your -host computer from the internet. It is no longer required to work with RTEMS. +You have chosen an installation prefix, the BSP to build, the tool's +architecure and prepared the source for the RSB in the previous sections. We +have chosen :file:`$HOME/quick-start/rtems/6` as the installation prefix, the +``erc32`` BSP and the SPARC architecture name of ``sparc-rtems6``, and unpacked +the RSB source in :file:`$HOME/quick-start/src`. + +The tool suite for RTEMS and the RTEMS sources are tightly coupled. For +example, do not use a RTEMS version 6 tool suite with RTEMS version 4.11 or 5 +sources and vice versa. + +Build and install the tool suite: .. code-block:: none cd $HOME/quick-start/src/rsb/rtems - ../source-builder/sb-set-builder --source-only-download 5/rtems-sparc + ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/6 6/rtems-sparc This command should output something like this (omitted lines are denoted by -...): +...). The build host appears as part of the name of the package being +built. The name you see may vary depending on the host you are using: .. code-block:: none - RTEMS Source Builder - Set Builder, 5 (98588a55961a) - warning: exe: absolute exe found in path: (__unzip) /usr/local/bin/unzip - Build Set: 5/rtems-sparc + RTEMS Source Builder - Set Builder, 6 (5e449fb5c2cb) + Build Set: 6/rtems-sparc ... - download: https://ftp.gnu.org/gnu/gcc/gcc-7.4.0/gcc-7.4.0.tar.xz -> sources/gcc-7.4.0.tar.xz - ... - Build Sizes: usage: 0.000B total: 141.738MB (sources: 141.559MB, patches: 183.888KB, installed 0.000B) - Build Set: Time 0:01:17.613061 + config: tools/rtems-binutils-2.36.cfg + package: sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1 + building: sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1 + sizes: sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1: 716.015MB (installed: 163.538MB) + cleaning: sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1 + reporting: tools/rtems-binutils-2.36.cfg -> sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1.txt + reporting: tools/rtems-binutils-2.36.cfg -> sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1.xml + config: tools/rtems-gcc-10-newlib-head.cfg + package: sparc-rtems6-gcc-6051af8-newlib-d10d0d9-x86_64-linux-gnu-1 + building: sparc-rtems6-gcc-6051af8-newlib-d10d0d9-x86_64-linux-gnu-1 + .... + Build Sizes: usage: 9.607GB total: 2.244GB (sources: 264.186MB, patches: 43.468KB, installed 1.986GB) + installing: 6/rtems-sparc -> $HOME/quick-start/rtems/6 + clean staging: 6/rtems-sparc + Staging Size: 5.292MB + Build Set: Time 1:01:48.019157 -If you encounter errors in the first step, check your internet connection, -firewall settings, virus scanners and the availability of the download servers. -The seconds step is to build and install the tool suite. +Once the build has successfully completed you can check if the cross C compiler +works with the following command: .. code-block:: none - cd $HOME/quick-start/src/rsb/rtems - ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 5/rtems-sparc + $HOME/quick-start/rtems/6/bin/sparc-rtems6-gcc --version -This command should output something like this (omitted lines are denoted by -...): +This command should output something like below. The version informtion helps +you to identify the exact sources used to build the cross compiler of your +RTEMS tool suite. In the output you see the version of RTEMS or the hash from +the RSB repository if you are building using a Git repository clone. The Newlib +hash is the version of Newlib in the RTEMS's github +`sourceware-mirror-newlib-cygwin +<https://github.com/RTEMS/sourceware-mirror-newlib-cygwin>`_ repository. The +``sources`` and ``patches`` directories created by the RSB contain all the +source code used. .. code-block:: none - RTEMS Source Builder - Set Builder, 5 (98588a55961a) - warning: exe: absolute exe found in path: (__unzip) /usr/local/bin/unzip - Build Set: 5/rtems-sparc - ... - config: tools/rtems-gcc-7.4.0-newlib-3e24fbf6f.cfg - package: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1 - building: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1 - sizes: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1: 4.651GB (installed: 879.191MB) - cleaning: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1 - .... - Build Sizes: usage: 5.618GB total: 1.105GB (sources: 141.559MB, patches: 185.823KB, installed 989.908MB) - Build Set: Time 0:22:02.262039 + sparc-rtems6-gcc (GCC) 10.2.1 20210309 (RTEMS 6, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9) + Copyright (C) 2020 Free Software Foundation, Inc. + This is free software; see the source for copying conditions. There is NO + warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. -In case the seconds step was successful, you can check if for example the cross -C compiler works with the following command: -.. code-block:: none - $HOME/quick-start/rtems/5/bin/sparc-rtems5-gcc --version --verbose +Add ``--verbose`` to the GCC command for the the verbose version details. -This command should output something like below. In this output the actual -prefix path was replaced by ``$PREFIX``. The ``compiled by`` line depends on -the native C++ compiler of your host computer. In the output you see the Git -hash of the RSB. This helps you to identify the exact sources which were used -to build the cross compiler of your RTEMS tool suite. +Need for RTEMS-Specific Cross-Compiler +--------------------------------------------------------- -.. code-block:: none +New users are often confused as to why they cannot use their distribution's +cross-compiler for their target on RTEMS, e.g., the riscv64-linux-gnu or the +arm-none-eabi-gcc. Below mentioned are some of the reasons for using +the RTEMS cross-compiler. - Using built-in specs. - COLLECT_GCC=$PREFIX/bin/sparc-rtems5-gcc - COLLECT_LTO_WRAPPER=$PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/lto-wrapper - sparc-rtems5-gcc (GCC) 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f) - Copyright (C) 2017 Free Software Foundation, Inc. - This is free software; see the source for copying conditions. There is NO - warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + Correct configuration of Newlib + Newlib is a C standard library implementation intended for use on embedded + systems. Most of the POSIX and libc support for RTEMS is derived from + Newlib. The RTEMS cross-compiler configures Newlib correctly for RTEMS. + + Threading in GCC support libraries + Several threading packages in GCC such as Go threads (libgo), OpenMP + (libgomp), and OpenACC need to be customized according to RTEMS. This is + done by the RTEMS specific cross-compiler. + Provide preprocessor define __rtems__ + The ``__rtems__`` preprocessor define is used to provide conditional code + compilation in source files that are shared with other projects e.g. in + Newlib or imported code from FreeBSD. - Target: sparc-rtems5 - Configured with: ../gcc-7.4.0/configure --prefix=$PREFIX --bindir=$PREFIX/bin --exec_prefix=$PREFIX --includedir=$PREFIX/include --libdir=$PREFIX/lib --libexecdir=$PREFIX/libexec --mandir=$PREFIX/share/man --infodir=$PREFIX/share/info --datadir=$PREFIX/share --build=x86_64-freebsd12.0 --host=x86_64-freebsd12.0 --target=sparc-rtems5 --disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib --disable-nls --without-included-gettext --disable-win32-registry --enable-version-specific-runtime-libs --disable-lto --enable-newlib-io-c99-formats --enable-newlib-iconv --enable-newlib-iconv-encodings=big5,cp775,cp850,cp852,cp855,cp866,euc_jp,euc_kr,euc_tw,iso_8859_1,iso_8859_10,iso_8859_11,iso_8859_13,iso_8859_14,iso_8859_15,iso_8859_2,iso_8859_3,iso_8859_4,iso_8859_5,iso_8859_6,iso_8859_7,iso_8859_8,iso_8859_9,iso_ir_111,koi8_r,koi8_ru,koi8_u,koi8_uni,ucs_2,ucs_2_internal,ucs_2be,ucs_2le,ucs_4,ucs_4_internal,ucs_4be,ucs_4le,us_ascii,utf_16,utf_16be,utf_16le,utf_8,win_1250,win_1251,win_1252,win_1253,win_1254,win_1255,win_1256,win_1257,win_1258 --enable-threads --disable-plugin --enable-libgomp --enable-languages=c,c++ - Thread model: rtems - gcc version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f) (GCC) - COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7' - $PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/cc1 -quiet -v -iprefix $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/ help-dummy -quiet -dumpbase help-dummy -mcpu=v7 -auxbase help-dummy -version --version -o /tmp//ccuAN1wc.s - GNU C11 (GCC) version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f) (sparc-rtems5) - compiled by GNU C version 4.2.1 Compatible FreeBSD Clang 6.0.1 (tags/RELEASE_601/final 335540), GMP version 6.1.0, MPFR version 3.1.4, MPC version 1.0.3, isl version isl-0.16.1-GMP - - GGC heuristics: --param ggc-min-expand=100 --param ggc-min-heapsize=131072 - COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7' - $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/as -v -s --version -o /tmp//ccFVgRAa.o /tmp//ccuAN1wc.s - GNU assembler version 2.32 (sparc-rtems5) using BFD version (GNU Binutils) 2.32 - GNU assembler (GNU Binutils) 2.32 - Copyright (C) 2019 Free Software Foundation, Inc. - This program is free software; you may redistribute it under the terms of - the GNU General Public License version 3 or later. - This program has absolutely no warranty. - This assembler was configured for a target of `sparc-rtems5'. - COMPILER_PATH=$PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/:$PREFIX/bin/../libexec/gcc/:$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/ - LIBRARY_PATH=$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/:$PREFIX/bin/../lib/gcc/:$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/ - COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7' - $PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/collect2 --version $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/crt0.o -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0 -L$PREFIX/bin/../lib/gcc -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib /tmp//ccFVgRAa.o -lgcc -lc -lgcc - collect2 version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f) - $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/ld --version $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/crt0.o -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0 -L$PREFIX/bin/../lib/gcc -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib /tmp//ccFVgRAa.o -lgcc -lc -lgcc - GNU ld (GNU Binutils) 2.32 - Copyright (C) 2019 Free Software Foundation, Inc. - This program is free software; you may redistribute it under the terms of - the GNU General Public License version 3 or (at your option) a later version. - This program has absolutely no warranty. - COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7' + Multilib variants to match the BSP + RTEMS configures GCC to create separate runtime libraries for each + supported instruction set, floating point unit, vector unit, word size + (e.g. 32-bit and 64-bit), endianness, ABI, processor errata workarounds, + and so on in the architecture. These libraries are termed as :ref:`Multilib + <TargetArchitectures>` variants. Multilib variants to match the BSP are set + by selecting a specific set of machine options using the RTEMS + cross-compiler. 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/testing/configuration.rst b/user/testing/configuration.rst index 9c65506..4d67482 100644 --- a/user/testing/configuration.rst +++ b/user/testing/configuration.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 -.. Copyright (C) 2018 Chris Johns <chrisj@rtems.org> +.. Copyright (C) 2018,2021 Chris Johns <chrisj@rtems.org> Tester Configuration -------------------- @@ -226,9 +226,10 @@ supported directives are: - ``%execute`` - ``%gdb`` - ``%tftp`` +- ``%wait`` -.. _tester-config-console: .. index:: Console, %console +.. _tester-config-console: Console ~~~~~~~ @@ -278,10 +279,12 @@ configuration script. If the ``%{console_stdio}`` is defined the console will be ``stdio`` else the console will be the BSP console or ``%{bsp_tty_dev}``. Telnet can be combined with the ``ser2net`` daemon to remotely access a -target's physical serial UART interface. +target's physical serial UART interface. The syntax is ``host:port``:: + + %define bsp_tty_dev 1.2.3.4:8989 -.. _tester-config-execute: .. index:: Execute, %execute +.. _tester-config-execute: Execute ~~~~~~~ @@ -297,8 +300,8 @@ An example is:: %execute %{run_cmd} %{run_opts} %{test_executable} %{test_executable_opts} -.. _tester-config-gdb: .. index:: GDB, %gdb +.. _tester-config-gdb: GDB ~~~ @@ -313,8 +316,8 @@ An example is:: %gdb %{gdb_cmd} %{test_executable} %{gdb_script} -.. _tester-config-tftp: .. index:: TFTP, %tftp +.. _tester-config-tftp: TFTP ~~~~ @@ -328,3 +331,72 @@ board running the test. An example is:: %tftp %{test_executable} %{tftp_port} + +The RTEMS Tester contains a TFTP server so an external TFTP is not +needed. It is recommended a TFTP Proxy is set up to handle the TFTP +sessions for your network. The internal TFTP server ignores the +requrest file and serves the next executable. If the target requires +the executable ne in a specific format provide a script via the +``target_pretest_command`` option in your user configuration file. + +The RTEMS Tools provides a TFTP protocol proxy server. It takes a list +of MAC addresses and proxies TFTP sessions for that MAC address to +another IP address and port. A proxy provides the following benefits: + +1. The TFTP proxy server is the only software required to run as root + +2. All hardware targets can be configured to serve from a single + machine and the proxy can distribute the sessions out to developer + machines + +3. There is no need to provide a globally writable file system a + central TFTP server acceses + +If you have a central TFTP server refer to the ``%wait`` directive. + +.. index:: Wait, %wait +.. _tester-config-wait: + +Wait +~~~~ + +The ``%wait`` directive waits the timeout period for a test to +complete. The directive monitors the console output and resets the +timeout timer if console output is seen. If the test runs for too long +while outputing data an error is reported. + +The wait directive can be used in systems where there is an external +mechanism being used to send the executable to the target hardware. + +An example is:: + + %wait + +Wait has no options. The timeouts are controlled in other ways. + +If you have an external system wide TFTP server with global access +wait can used by providing a `` script that places the file in the +location the TFTP server can see. This is done as the test start so if +networking loading there is normally enough time to get the executable +image in place before the transfer starts. The MVME2700 +(``powerpc/mvme2307``) is a BSP that supports the ``%wait`` directive. + +The following is an example user configuration file (see +``--user-config``):: + + # + # MVME2700 (mvme2307) + # + [mvme2307] + bsp_tty_dev = 1.2.3.4:5678 + target_pretest_command = mk-mvme2307-img @EXE@ /tftp/cjohns/rtems.img + target_exe_filter = /\.exe/.exe.img/ + target_on_command = pw-ctl 1.2.3.4 toggle-on 3 1 + target_off_command = pw-ctl 1.2.3.4 off 3 + target_reset_command = pw-ctl 1.2.3.4 toggle-on 3 1 + +The script ``mk-mvme2307-img`` converts the RTEMS ELF executable into +the PowerPC prep bootloader format and copies the file to the TFTP +server's network wide location. The MVME2700 is configured to request +``rtems.img`` from this location. The command ``pw-ctl`` is a command +to control the power to the board. diff --git a/user/testing/tftp.rst b/user/testing/tftp.rst index ade8f9a..4cb16ef 100644 --- a/user/testing/tftp.rst +++ b/user/testing/tftp.rst @@ -10,10 +10,14 @@ TFTP and U-Boot .. index:: TFTP, U-Boot, Testing TFTP and U-Boot provides a simple way to test RTEMS on a network capable -target. The RTEMS Tester starts a TFTP server for each test and the target's -boot monitor, in this case U-Boot request a file, any file, which the TFTP -server supplies. U-Boot loads the executable and boots it using a standard -U-Boot script. +target. The RTEMS Tester starts a TFTP server session for each test and the +target's boot monitor, in this case U-Boot request a file, any file, which the +TFTP server supplies. U-Boot loads the executable and boots it using a +standard U-Boot script. + +The RTEMS Tester contains a TFTP server so no external TFTP server or +configuration is required. If you have an external TFTP server and wish to use +that resource the :ref:`tester-config-wait` directive can be used. .. _fig-tester-tftp-u-boot: diff --git a/user/tools/boot-image.rst b/user/tools/boot-image.rst index 8e8f63d..c4c3766 100644 --- a/user/tools/boot-image.rst +++ b/user/tools/boot-image.rst @@ -36,7 +36,7 @@ The boot image tool can: The disk images are suitable for booting a range of hardware that have media interfaces, such as an SD card. The default partition type is -the Master Boot Record (MRB) and a single root DOS-FS partition is +the Master Boot Record (MBR) and a single root DOS-FS partition is created. Boot Loaders @@ -315,7 +315,7 @@ Create a disk image from a built U-Boot sandbox: Finished Cleaning up -Create a 32M byte SD card image with the testsuite's hello world +Create a 32M byte SD card image with the testsuite's Hello World executable (``hello.exe``): .. code-block:: none diff --git a/user/tools/tester.rst b/user/tools/tester.rst index c3c3fe2..5452856 100644 --- a/user/tools/tester.rst +++ b/user/tools/tester.rst @@ -10,31 +10,30 @@ RTEMS Tester and Run .. index:: Tools, rtems-test, rtems-run The RTEMS Tester is a test tool that provides a command line interface to run -test executable on supported targets. The tool provides back-end support for +test executables on supported targets. The tool provides back end support for common simulators, debuggers and boot loaders. Board support package (BSP) configurations for RTEMS are provided and can be used to run all the tests in -the RTEMS test suite. The tool and it's framework is not specific to RTEMS and +the RTEMS test suite. The tool and its framework is not specific to RTEMS and can be configured to run any suitable application. RTEMS is an embedded operating system and is cross-compiled on a range of host -machines. The executables run on the target hardware and this can vary widely -from open source simulators, commercial simulators, debuggers with simulators, -debuggers with hardware specific pods and devices to targe boot -loaders. Testing RTEMS requires the cross-compiled test executable is -transferred to the target hardware, executed and the output captured and -returned to the test host where it is analyzed to determine the test -result. +machines. The executables run on hardware which can vary widely from open +source simulators, commercial simulators, debuggers with simulators, debuggers +with hardware specific pods and devices, and targets with boot loaders. +Testing RTEMS requires that the cross-compiled test executable is transferred +to the target hardware, executed, the output captured and returned to the test +host where it is analyzed to determine the test result. Running the RTEMS tests on your target is very important. It provides you with a traceable record showing that your RTEMS version and its tools are working at the level the RTEMS development team expect when releasing RTEMS. Being able to -easily run the tests and verify the results is critical in maintaining a high -standard. +easily run the tests and verify the results is critical in maintaining high +standards. Available BSP testers --------------------- -You can list the available BSP testers with: +You can list the available BSP testers with (not all shown): .. code-block:: none @@ -62,11 +61,9 @@ You can list the available BSP testers with: project. Some of the BSPs may appear more than once in the list. These are aliased BSP -configurations that may use a different back-end. An example is the erc32 BSP. -There is the ``erc32`` tester which uses the GDB back-end and the -``erc32-run`` tester which uses the ``run`` command for erc32. We will show -how to use :program:`rtems-test` command with the erc32 BSP because it is easy -to build an use. +configurations that may use different back ends. We will show how to use +:program:`rtems-test` command with the erc32 BSP because it is easy to build +and use. .. _BuildingRTEMSTests: @@ -84,32 +81,21 @@ configure after running ``bootstrap``. --enable-tests --enable-rtemsbsp=erc32 $ make -Add the `-j` option to the make command with the number of cores to run a -parallel build. +Add the `-j` option to the make command with the number of parallel jobs to run a +parallel build (e.g. `-j 8`). Building all the tests takes time and it uses more disk so be patient. When -finished all the tests will have been built. Some BSPs may require a post-build -process to be run on the RTEMS ELF executable to create an image suitable for -execution. This can be built into the configuration script and the tester will -perform a pre-test command to covert the executable to a suitable format for -your target. +make finishes, all the tests will have been built. + +.. note:: Some BSPs may require a post-build process to be run on the RTEMS ELF + executable to create an image suitable for execution. This can be built + into the configuration script and the tester will perform a pre-test + command to convert the executable to a suitable format for your target. Before running all the tests it is a good idea to run the ``hello`` test. The ``hello`` test is an RTEMS version of the classic "Hello World" example and -running it shows you have a working tool chain and build of RTEMS ready to run -the tests. Using the run with the ERC32 BSP the command is: - -.. code-block:: none - - $ sparc-rtems5-run sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe - - *** BEGIN OF TEST HELLO WORLD *** - Hello World - *** END OF TEST HELLO WORLD *** - -The run command is the GDB simulator without the GDB part. - -Running the example using SIS: +running it shows you have a working toolchain and build of RTEMS ready to run +the tests. Running the example using SIS: .. code-block:: none @@ -145,14 +131,14 @@ Running the example using SIS: sis> q -The examples can also be run using GDB with SIS as the backend. SIS can be connected to +The examples can also be run using GDB with SIS as the back end. SIS can be connected to gdb through a network socket using the gdb remote interface. Either start SIS with ``-gdb``, or issue the ``gdb`` command inside SIS, and connect gdb with ``target remote:1234``. The default port is ``1234``, the port can be changed using the ``-port`` option. -Open a terminal and issue the command: +Open a terminal and issue the following command: .. code-block:: none @@ -163,7 +149,7 @@ Open a terminal and issue the command: gdb: listening on port 1234 -Now open another terminal and issue the command: +Now open another terminal and issue the following command: .. code-block:: none @@ -187,7 +173,7 @@ Now open another terminal and issue the command: (gdb) target remote:1234 The ``target remote:1234`` will tell gdb to connect to the sis simulator. After this -command the output of the first terminal will change to +command the output of the first terminal will change to: .. code-block:: none @@ -199,7 +185,7 @@ command the output of the first terminal will change to gdb: listening on port 1234 connected Before running the executable, it must be loaded, this is done using the -``load`` command in gdb, and to run, issue ``continue`` command. +``load`` command in gdb, and to run it, issue the ``continue`` command. .. code-block:: none @@ -259,9 +245,6 @@ You can see your executable running in the first terminal. For more information on the sis simulator refer to this doc: https://gaisler.se/sis/sis.pdf -The command ``r`` is used to debug set break points before issuing the GDB -``run`` command. - There are currently close to 500 separate tests and you can run them all with a single RTEMS Tester command. @@ -269,11 +252,11 @@ Running the Tests ----------------- The :program:`rtems-test` command line accepts a range of options. These are -discussed later in the manual. Any command line argument without a `--` prefix -is a test executable. You can pass more than one executable on the command -line. If the executable is a path to a directory the directories under that -path are searched for any file with a ``.exe`` extension. This is the default -extension for RTEMS executables built within RTEMS. +discussed later in the manual. Command line arguments without a `--` prefix are +test executables or paths to directories. When using a path to a directory, +the directories under that path are searched for any file with a ``.exe`` extension. +This is the default extension for RTEMS executables built within RTEMS. You can +pass more than one executable on the command line. To run the erc32 tests enter the following command from the top of the erc32 BSP build tree: @@ -281,9 +264,8 @@ BSP build tree: .. code-block:: none $ ~/development/rtems/test/rtems-tools.git/tester/rtems-test \ - --log=log_erc32_run \ - --rtems-bsp=erc32-run \ - --rtems-tools=$HOME/development/rtems/5 \ + --log=log_erc32_sis \ + --rtems-bsp=erc32-sis \ sparc-rtems5/c/erc32/testsuites/samples RTEMS Testing - Tester, 5.not_released [ 1/13] p:0 f:0 u:0 e:0 I:0 B:0 t:0 i:0 | sparc/erc32: base_sp.exe @@ -311,58 +293,67 @@ BSP build tree: Average test time: 0:00:27.963000 Testing time : 0:06:03.519012 +The output has been shortened so it fits nicely here. Following the order of +appearance above, we have the following: + * The RTEMS Tester's test command. In this example we are using an absolute path. * The ``--log`` option sends the output to a log file. By default only failed tests log the complete output. -* Select the erc32 BSP and use GDB. -* Path to the RTEMS tools so GDB can be found. -* Path to the erc32 BSP built with all tests to run. If you add subdirectories +* The ``--rtems-bsp`` option selects the erc32 BSP. +* The path to the erc32 BSP tests to run. If you add subdirectories to the path specific tests can be run. -* The output has been shortened so it fits nicely here. -* The test results shows passes, fails, timeouts, and invalid results. In - this run 13 tests passed and 5 tests timed out and 1 is invalid. The - timeouts are probably due to the tests not having enough execute time to - complete. The default timeout is 180 seconds and some of the interrupt tests - need longer. The amount of time depends on the performance of your host CPU - running the simulations. -* The output shows the average time per test and the total time taken to run - all the tests. -* If the path to the testsuites was put to +* The test results so far. See details below. +* Overall results of the run. In this run, 13 tests passed, 5 tests timed out + and 1 is invalid. The timeouts are probably due to the tests not having enough + time to complete. The default timeout is 180 seconds and some of the interrupt + tests need more time. The amount of time each test takes depends on the + performance of your host CPU when running the simulations. +* The average time per test and the total time taken to run all the tests. + +.. note:: If the path to the testsuites was set to ``sparc-rtems5/c/erc32/testsuites`` instead of ``sparc-rtems5/c/erc32/testsuites/samples`` then all the executables would have been tested and not just those in samples. -This BSP requires the ``--rtems-tools`` option because the SPARC GDB is the -``sparc-rtems4.11-gdb`` command that is part of the RTEMS tools. Not every BSP -will require this option so you will need to check the specifics of the BSP -configuration to determine if it is needed. +.. note:: Some BSPs require the use of the specific target architecture GDB + command (e.g. RTEMS 5 SPARC GDB command is ``sparc-rtems5-gdb``). + As this command is part of the RTEMS tools, the ``--rtems-tools`` + option should be added to the ``rtems-test`` command line, e.g. + ``--rtems-tools=$HOME/development/rtems/5``. + Not every BSP requires this option so you will need to check the + specifics of the BSP configuration you are using in order to + determine if this option is needed. -The output you see is each test starting to run. The :program:`rtems-test` +An output line is printed for each test that is executed. The :program:`rtems-test` command by default runs multiple tests in parallel so you will see a number -start quickly and then new tests start as others finish. The output shown here -is from an 8 core processor so the first 8 are started in parallel and the -status shows the order in which they actually started, which is not 1 to 8. +of tests starting quickly and then new tests start as others finish. For example, +the output shown above is from an 8-core processor. Thus, the first 8 tests +started in parallel and the status shows the order in which they actually started, +which is not necessarily sequential, as it happens in the example above where +test 8 started before test 7. -The test start line shows the current status of the tests. The status reported -is when the test starts and not the result of that test. A fail, timeout or -invalid count changing means a test running before this test started failed, -not the starting test. The status here has 7 tests passed, no failures, 5 -timeouts and 1 invalid test. +Each output line shows information about the current status of the tests. +The status reported in each line is the status when the test starts and not the +result of that particular test. Thus, a fail, timeout or invalid count changing +means a test running before this test failed. The overall status in the end +shows that 7 tests passed, no failures, 5 timeouts and 1 invalid test. + +Concerning the output of each line, we have the following: .. code-block:: none [ 5/13] p:2 f:0 u:0 e:0 I:0 B:0 t:0 i:0 | sparc/erc32: hello.exe -* [ 5/13] indicates the test number, in this case test 5 of 13 tests. -* ``p`` is the passed test count (2 in this case) -* ``f`` is the failed test count (0 in this case) -* ``u`` is the count for test marked as "user-input" as they expect input from - user -* ``e`` is the expected-fail count (tests that are expected to fail) -* ``I`` is the count for tests the results of which are indeterminate -* ``B`` is the count for benchmarked tests -* ``t`` is the timeout test count +* [ 5/13] indicates the test number, in this case test 5 out of 13 tests. +* ``p`` is the passed test count (2 in this case). +* ``f`` is the failed test count (0 in this case). +* ``u`` is the count for test marked as "user-input" (tests that expect input + from the user). +* ``e`` is the expected-fail count (tests that are expected to fail). +* ``I`` is the count for tests the results of which are indeterminate. +* ``B`` is the count for benchmarked tests. +* ``t`` is the timeout test count. * ``i`` is the invalid test count. * ``sparc/erc32`` is the architecture and BSP names. * ``hello.exe`` is the executable name. @@ -371,11 +362,11 @@ The test log records all the tests and results. The logging mode by default only provides the output history if a test fails, times out, or is invalid. The time taken by each test is also recorded. -The tests must complete in a specified time or the test is marked as timed -out. The default timeout is 3 minutes and can be globally changed using the +The tests must complete in a specified period of time or the test is marked as +timed out. The default timeout is 3 minutes and can be globally changed using the ``--timeout`` command line option. The time required to complete a test can -vary. When simulators are run in parallel the time taken depends on the -specifics of the host machine being used. A test per core is the most stable +vary. When simulators are run in parallel, the time taken depends on the resources +available on the host machine being used. A test per core is the most stable method even though more tests can be run than available cores. If your machine needs longer or you are using a VM you may need to lengthen the timeout. @@ -408,7 +399,7 @@ A test fails if the start marker is seen and there is no end marker. User-input ^^^^^^^^^^ -A test marked as "user-input" as it expects input from user +A test marked as "user-input" as it expects input from user. Expected-fail ^^^^^^^^^^^^^ @@ -442,7 +433,7 @@ The following modes of logging are available: * Failures (``failures``) * None (``none``) -The mode is controlled using the command line option ``--log-mode`` using +This mode is controlled using the command line option ``--log-mode`` using the values listed above. All @@ -530,19 +521,19 @@ Reporting --------- The RTEMS Tester supports output in a machine parsable format. This can be -enabled using the options "--report-path" and "--report-format". Currently, +enabled using the options ``--report-path`` and ``--report-format``. Currently, JSON output is supported using these options like so: -'--report-path="report" --report-format=json' +``--report-path="report" --report-format=json`` -This will produce a file "report.json" that contains output equivalent to the -"failure" logging mode. +This will produce a file ``report.json`` that contains output equivalent to the +``failure`` logging mode. Running Tests in Parallel ------------------------- The RTEMS Tester supports parallel execution of tests by default. This only -makes sense if the test back-end can run in parallel without resulting in -resource contention. Simulators are an example of back-ends that can run in +makes sense if the test back end can run in parallel without resulting in +resource contention. Simulators are an example of back ends that can run in parallel. A hardware debug tool like a BDM or JTAG pod can manage only a single test at once so the tests need to be run one at a time. @@ -554,29 +545,4 @@ Command Line Help ----------------- The :program:`rtems-test` command line accepts a range of options. You can -review the available option by the ``--help`` option: - -.. code-block:: none - - RTEMS Tools Project (c) 2012-2014 Chris Johns - Options and arguments: - --always-clean : Always clean the build tree, even with an error - --debug-trace : Debug trace based on specific flags - --dry-run : Do everything but actually run the build - --force : Force the build to proceed - --jobs=[0..n,none,half,full] : Run with specified number of jobs, default: num CPUs. - --keep-going : Do not stop on an error. - --list-bsps : List the supported BSPs - --log file : Log file where all build output is written to - --macros file[,file] : Macro format files to load after the defaults - --no-clean : Do not clean up the build tree - --quiet : Quiet output (not used) - --report-path : Report output base path (file extension will be added) - --report-format : Formats in which to report test results: json - --log-mode : Log modes, failures (default),all,none - --rtems-bsp : The RTEMS BSP to run the test on - --rtems-tools : The path to the RTEMS tools - --target : Set the target triplet - --timeout : Set the test timeout in seconds (default 180 seconds) - --trace : Trace the execution - --warn-all : Generate warnings +review the available options by using the ``--help`` option. 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 d799774..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 embedded brains GmbH +.. Copyright (C) 2019, 2020 embedded brains GmbH & Co. KG .. Copyright (C) 2019 Sebastian Huber .. _EventRecording: @@ -35,12 +35,29 @@ operations. The CPU counter is used to get the time of events. It is combined with periodic uptime events to synchronize it with the monotonic system clock (:c:macro:`CLOCK_MONOTONIC`). -The application must configure the event recording via the configuration options -:c:macro:`CONFIGURE_RECORD_PER_PROCESSOR_ITEMS` and -:c:macro:`CONFIGURE_RECORD_EXTENSIONS_ENABLED`. +To use the event recording three things come into play. Firstly, there is the +generation of event records on the target system (the application running with +RTEMS). Secondly, means to transfer the recorded events to the host computer +for analysis. Thirdly, the analysis of the recorded events on the host +computer. -Events can be recorded for example with the :c:func:`rtems_record_produce` -function. +Target System: Configuration and Event Generation +------------------------------------------------- + +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. 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 +:c:func:`rtems_record_produce`, :c:func:`rtems_record_line`, +:c:func:`rtems_record_caller`, etc. functions. .. code-block:: c @@ -49,10 +66,144 @@ function. void f( void ) { rtems_record_produce( RTEMS_RECORD_USER( 0 ), 123 ); + rtems_record_line(); + rtems_record_caller(); } -Recorded events can be sent to a host computer with a very simple record server -started by :c:func:`rtems_record_start_server` via a TCP connection. +The variants of :c:func:`rtems_record_line` and :c:func:`rtems_record_caller` +can be used to easily generate control flow events in the area of interest. +The :file:`rtems-record-lttng` tool can use these events to associate source +code files and line numbers to them using the ELF file of the application. + +The following code can be used together with the GCC option +``-finstrument-functions`` to generate function entry/exit events for +instrumented functions: + +.. code-block:: c + + __attribute__(( __no_instrument_function__ )) + void __cyg_profile_func_enter( void *this_fn, void *call_site ) + { + rtems_record_produce_2( + RTEMS_RECORD_CALLER, + (rtems_record_data) call_site, + RTEMS_RECORD_FUNCTION_ENTRY, + (rtems_record_data) this_fn + ); + } + + __attribute__(( __no_instrument_function__ )) + void __cyg_profile_func_exit( void *this_fn, void *call_site ) + { + rtems_record_produce( + RTEMS_RECORD_FUNCTION_EXIT, + (rtems_record_data) this_fn + ); + } + +Transfer of Event Records to the Host Computer +---------------------------------------------- + +Recorded events can be sent to a host computer with a record server started by +:c:func:`rtems_record_start_server` via a TCP connection. + +In the fatal error handler, the event records can be dumped via +:c:func:`rtems_putc` in Base64 encoding. Optionally, the event records can be +compressed via zlib before they are dumped in Base64 encoding. The compression +needs roughly 512KiB of statically allocated memory. + +Analysis of Event Records on the Host Computer +---------------------------------------------- + +Use the command line tool :file:`rtems-record-lttng` to get recorded events +from the record server running on the target system or from a file to convert +the event records into CTF. It can be also used to read the dumps in Base64 +encoding generated by the fatal error handler. The tool outputs the event +records in the `Common Trace Format (CTF) <https://diamon.org/ctf/>`_ with some +extra support for the +`Linux Trace Toolkit Next Generation (LTTng) <https://lttng.org/>`_. This +format can be analysed using `babeltrace <https://babeltrace.org/>`_ or +`Eclipse Trace Compass <https://www.eclipse.org/tracecompass/>`_. +The command line tool :file:`rtems-record-lttng` optionally uses +`LLVM <https://www.llvm.org/>`_ to translate addresses to functions and source +file locations. Make sure you have the LLVM development package installed when +you build the RTEMS Tools to enable this feature. + +For example, to get the event records from the record server running on the +target use: + +.. code-block:: none + + mkdir new-trace + cd new-trace + rtems-record-lttng -e application.exe -H 192.168.188.84 -l 100000 + +If everything is set up correctly, then the command produces a :file:`metadata` +file and one stream file :file:`stream_0`, etc. for each processor which +generated event records. + +.. code-block:: none + + $ ls -l + total 120 + -rw-r--r-- 1 user group 108339 Apr 11 15:28 metadata + -rw-r--r-- 1 user group 8701 Apr 11 15:28 stream_0 + +This output in CTF can be used by :file:`babeltrace` and +`Eclipse Trace Compass` for further analysis, for example: + +.. code-block:: none + + $ babeltrace . + [07:28:15.909340000] (+?.?????????) RTEMS THREAD_STACK_CURRENT: { cpu_id = 0 }, { data = 0xB10 } + [07:28:15.909340000] (+0.000000000) RTEMS sched_switch: { cpu_id = 0 }, { prev_comm = "UI1 ", prev_tid = 167837697, prev_prio = 0, prev_state = 0, next_comm = "IDLE/0", next_tid = 0, next_prio = 0 } + [07:28:15.909519999] (+0.000179999) RTEMS THREAD_STACK_CURRENT: { cpu_id = 0 }, { data = 0xD68 } + [07:28:15.909519999] (+0.000000000) RTEMS sched_switch: { cpu_id = 0 }, { prev_comm = "IDLE/0", prev_tid = 0, prev_prio = 0, prev_state = 1026, next_comm = "UI1 ", next_tid = 167837697, next_prio = 0 } + [07:28:15.909579999] (+0.000060000) RTEMS THREAD_STACK_CURRENT: { cpu_id = 0 }, { data = 0xB10 } + ... + [07:28:15.999940999] (+0.000000000) RTEMS USER_4: { cpu_id = 0 }, { data = 0x4000192C } + [07:28:15.999940999] (+0.000000000) RTEMS RETURN_0: { cpu_id = 0 }, { data = 0x0 } + [07:28:15.999940999] (+0.000000000) RTEMS RETURN_1: { cpu_id = 0 }, { data = 0x1 } + [07:28:15.999940999] (+0.000000000) RTEMS RETURN_2: { cpu_id = 0 }, { data = 0x2 } + [07:28:15.999940999] (+0.000000000) RTEMS RETURN_3: { cpu_id = 0 }, { data = 0x3 } + [07:28:15.999940999] (+0.000000000) RTEMS RETURN_4: { cpu_id = 0 }, { data = 0x4 } + [07:28:15.999940999] (+0.000000000) RTEMS RETURN_5: { cpu_id = 0 }, { data = 0x5 } + [07:28:15.999940999] (+0.000000000) RTEMS RETURN_6: { cpu_id = 0 }, { data = 0x6 } + [07:28:15.999940999] (+0.000000000) RTEMS RETURN_7: { cpu_id = 0 }, { data = 0x7 } + [07:28:15.999940999] (+0.000000000) RTEMS RETURN_8: { cpu_id = 0 }, { data = 0x8 } + [07:28:15.999940999] (+0.000000000) RTEMS RETURN_9: { cpu_id = 0 }, { data = 0x9 } + [07:28:15.999940999] (+0.000000000) RTEMS ISR_DISABLE: { cpu_id = 0 }, { code = "generate_events at init.c:154" } + [07:28:15.999940999] (+0.000000000) RTEMS ISR_ENABLE: { cpu_id = 0 }, { code = "Init at init.c:181" } + +A dump from the fatal error handler looks like this: + +.. code-block:: none + + *** BEGIN OF RECORDS BASE64 ZLIB *** + eNqtlE1vE1cUhsdJWgg0jU2GABILpxUVkaJcTxzH8QqThKpRKTIJlcoyeIKIhGCCEFnAAtAoKgXa + phqx6gKk/AAXWHTpTMYZlg0rdpBdF7Dvsuec91jYFEo+HOnq0b33Oe/9mOtks9ns7Y1TK5ZlJah1 + Uluw8HfJstqYA1b3WJG4a+p4aZpJbZzaXOlrw+4cte+p2Zcuz15kUstS3FhmZGiWOTs6nGM65Xye + 6TqZEeZQNnOOWZh1y8KZfEHG3ewMszyE+XJ2hHNyg7lBrs9lhtIZpuMUHObR9LDwuxNnppgDufQ0 + c2x6Ko35nLBcKOSEeXeYOXM+P8o8lR7oZ85dXJB1HDfN6+aGnbx4/YUR3t/+zgTfUaL3xMmJSe7v + 0X7ameTzX9N7m6d7WyNetqyOI93HVgx7xKOWtTdJHOSc7rElo6TxrgvEQfHGbxkl/PFb8F/2GSX8 + l33wX6WMEv6rlPjJ638YpfhE8ZM3Hhml+ETxUwdOG6X4RPFTB48bpfhE+E82jBL+kw34T9eNEv7T + dfH3leaNUnyi+PtOzxil+ET4r1NGCf91Cv6bhFHCf5MQv+fHR0YpPlH8njtLRik+UXz7iGOU4hPF + t7/qM0rxifCr60YJv7oOv/rX2aLVk1QetqvP5RFoP0N9/l2R95x/TG32SsTjo8Td4qE/0dDvFB/j + Z94zvqch58L/zO8ltqt3cxPeZ8QO9X/fgt9F/ETrqtuo+5z4qdb/vYP6bv7fZIcVyrFtInLCCnLC + CnLCCnLCCnLCCnLCCnLCSj0nSdytecUW5qX4/yyxt2gdGtD8b97p/2CHjy1dr3Hco3G8p/Bxm67f + OH+jYZ+N4/fes//G+YcfPN/qMrzVZfb+JMJbXYa3ulz3cA/N/otN+Li35rp/tlCH+26q3394G/X4 + Xs05EzvIwXdvzvNakId3FAXIjQLOfUhEbhQgNwqQGwXIjQLkRgFyowC5UYDcKKjn4n1GD9qRX2c9 + /91+fb0Pjdf38bH5+j436+l5aovwaz78mg+/5sOv+fBrvvo+zr/tOh/3tuN6H/feshwf36/leT7e + Q22xQ3LXrii9O5L/to/11jys9x/P+wnj3l3Zx0fnvXuyz0173n05z5Z972c5/7brvF/k3nZc7/0q + 9x6fR07sIid2kRO7yIld5MQucmIXObGLnNjVHHdJvl/L89zf5D3E7rdF6+BV4knJf1b6Uuqelb7g + df4FFmd4DQ== + *** END OF RECORDS BASE64 ZLIB *** + +Copy everything between the ``*** BEGIN OF RECORDS BASE64 ZLIB ***`` and the +``*** END OF RECORDS BASE64 ZLIB ***`` markers into a file, for example +:file:`dump.txt`. Use this command to convert the event records into the CTF +for further analysis: + +.. code-block:: none -On the host computer you may use the command line tool :file:`rtems-record` to -get recorded events from the record server running on the target system. + rtems-record-lttng -e application.exe -b -z dump.txt diff --git a/user/tracing/examples.rst b/user/tracing/examples.rst index d0bef0b..ed0c722 100644 --- a/user/tracing/examples.rst +++ b/user/tracing/examples.rst @@ -48,20 +48,20 @@ 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/ \ - -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \ + 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 \ -o sparc-rtems5/c/erc32/testsuites/samples/fileio.exe sparc-rtems5/c/erc32/\ @@ -75,7 +75,7 @@ the wrapper c file. .. code-block:: none rtems-tld -C fileio-trace.ini -W fileio-wrapper -- -Bsparc-rtems5/erc32/lib/ \ - -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections \ + -qrtems -mcpu=cypress -O2 -g -ffunction-sections \ -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration \ -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections -mcpu=cypress \ -o sparc-rtems5/c/erc32/testsuites/samples/fileio.exe sparc-rtems5/c/erc32/\ @@ -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). |