If you read the “BSP and Drivers Guide” it references the “BSP Developer’s Manual” and links it here: http://rtems.org/onlinedocs/doc-current/share/rtems/html/bsp_howto/index.html which is ‘page not found’.
I was trying to figure out how linker scripts are embedded in the BSP
It’s located here RTEMS BSP and Driver Guide (7.5ece2a4). — RTEMS BSP and Driver Guide 7.5ece2a4 (12th June 2026) documentation
But you’ve also pointed out that we don’t even have the howto guide linked from our main docs page.
Can you open an issue for this in the docs repo?
Linker scripts can some from a range of sources depending on the BSP. Some can be based on a file in the bsps tree of files and some can be generated. This makes a single documented way of approaching linkcmds files confusing.
The simplest approach is to build an existing BSP. It can be one you are interested in or close to one you want to use and change. The default configuration INI file will build the samples. Build the samples.
Find the hello.exe executable file, delete it then rebuild with a verbose waf build:
$ find build -name hello.exe
build/aarch64/k26/testsuites/samples/hello.exe
build/arm/xilinx_zynq_microzed/testsuites/samples/hello.exe
$ rm build/aarch64/k26/testsuites/samples/hello.exe
$ ./waf -v
Waf: Entering directory `/opt/work/chris/rtems/kernel/rtems.git/build'
Waf: Leaving directory `/opt/work/chris/rtems/kernel/rtems.git/build'
'build' finished successfully (0.054s)
Waf: Entering directory `/opt/work/chris/rtems/kernel/rtems.git/build/arm/xilinx_zynq_microzed'
10:52:19 runner 'git ls-files --modified'
10:52:19 runner 'git rev-parse HEAD'
Waf: Leaving directory `/opt/work/chris/rtems/kernel/rtems.git/build/arm/xilinx_zynq_microzed'
'build_arm/xilinx_zynq_microzed' finished successfully (0.332s)
Waf: Entering directory `/opt/work/chris/rtems/kernel/rtems.git/build/aarch64/k26'
[1542/1560] Linking build/aarch64/k26/testsuites/samples/hello.exe
10:52:20 runner ['/opt/work/rtems/7/bin/aarch64-rtems7-gcc', 'testsuites/samples/hello/init.c.119.o', '-o/opt/work/chris/rtems/kernel/rtems.git/build/aarch64/k26/testsuites/samples/hello.exe', '-Wl,-Bstatic', '-L.', '-lrtemscpu', '-lrtemsbsp', '-lrtemstest', '-Wl,-Bdynamic', '-qrtems', '-mno-outline-atomics', '-mcpu=cortex-a53', '-mfix-cortex-a53-835769', '-mfix-cortex-a53-843419', '-Wl,--gc-sections', '-L/opt/work/chris/rtems/kernel/rtems.git/bsps/aarch64/shared/start', '-L/opt/work/chris/rtems/kernel/rtems.git/bsps/aarch64/xilinx-zynqmp/start', '-Wl,--wrap=printf', '-Wl,--wrap=puts', '-Wl,--wrap=putchar']
Waf: Leaving directory `/opt/work/chris/rtems/kernel/rtems.git/build/aarch64/k26'
'build_aarch64/k26' finished successfully (0.469s)
You can see the command line waf used to build the executable for my BSP. It is for a ZynqMP on a K26 SOM. The important part is -qrtems. It tells GCC to enable the RTEMS specific specs files.
Hang on you say … specs? Ok this can be a little confusing because GCC has specs files and RTEMS has them as well. They are not the same thing. Here we are interested in the GCC spec files.
The -qrtems option references the GCC built in spec file. You can view the built in spec file with the -dumpspecs option and if you look for rtems you can see the parts RTEMS uses. The command is:
/opt/work/rtems/7/bin/aarch64-rtems7-gcc -dumpspecs
We are only interested in the linker script so a grep helps isolate that piece:
$ /opt/work/rtems/7/bin/aarch64-rtems7-gcc -dumpspecs | grep linkcmds
%{qrtems:crtend%O%s crtn%O%s %{!qnolinkcmds:-T linkcmds%s}}
You can see an RTEMS built GCC internally adds -T linkcmds if no command line linker script option is provided. Now I know the default script file name is linkcmds so I can find the one my BSP uses:
$ find build -name linkcmds
build/aarch64/k26/linkcmds
build/arm/xilinx_zynq_microzed/linkcmds
I have two for the 2 BSPs I am building at the moment.
When waf installs the BSP the linkcmd file is installed.
lnkcmds file come from?The file can be taken from the BSP or it can be generated. To count the scripts in the BSPs run the following command:
$ find bsps -name linkcmds | wc -l
38
Remove the wc command to see the list.
Generated files can use a base that may have pieces added for specific BSPs:
$ find bsps -name linkcmds.base | wc -l
6
The configuration options in the INI file you configure your BSP can contain settings that are used in a generated linkcmds file. For example the base address of RAM, the size of RAM or flash details are handled by RTEMS spec files. Again these are not GCC specs files but are YAML fragments the RTEMS waf build system uses to generate files like linkcmds as well as control the files built for a BSP.
The list of linkcmds references for AARCH64 BSPs is:
$ grep -r linkcmd spec | grep aarch
spec/build/bsps/aarch64/xilinx-zynqmp/bspapu.yml: uid: linkcmds_lp64
spec/build/bsps/aarch64/xilinx-zynqmp/linkcmds_ilp32.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/xilinx-zynqmp/linkcmds_ilp32.yml:target: linkcmds
spec/build/bsps/aarch64/xilinx-zynqmp/bspcfc400x.yml: uid: linkcmds_lp64
spec/build/bsps/aarch64/xilinx-zynqmp/bspqemu.yml: uid: linkcmds_lp64
spec/build/bsps/aarch64/xilinx-zynqmp/bspapuilp32.yml: uid: linkcmds_ilp32
spec/build/bsps/aarch64/xilinx-zynqmp/bspqemuilp32.yml: uid: linkcmds_ilp32
spec/build/bsps/aarch64/xilinx-zynqmp/linkcmds_lp64.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/xilinx-zynqmp/linkcmds_lp64.yml:target: linkcmds
spec/build/bsps/aarch64/frdm-imx93/linkercmds.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/frdm-imx93/linkercmds.yml:target: linkcmds
spec/build/bsps/aarch64/raspberrypi/linkercmds.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/raspberrypi/linkercmds.yml:target: linkcmds
spec/build/bsps/aarch64/raspberrypi5/linkercmds.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/raspberrypi5/linkercmds.yml:target: linkcmds
spec/build/bsps/aarch64/xilinx-versal/linkcmds_lp64.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/xilinx-versal/linkcmds_lp64.yml:target: linkcmds
spec/build/bsps/aarch64/xilinx-versal/bspqemu.yml: uid: linkcmds_lp64
spec/build/bsps/aarch64/xilinx-versal/bspvck190.yml: uid: linkcmds_lp64
spec/build/bsps/aarch64/xilinx-versal/bspaiedge.yml: uid: linkcmds_lp64
spec/build/bsps/aarch64/grp.yml: - bsps/aarch64/shared/start/linkcmds.base
spec/build/bsps/aarch64/a53/bspa53ilp32qemu.yml: uid: linkcmds_ilp32
spec/build/bsps/aarch64/a53/bspa53lp64qemu.yml: uid: linkcmds_lp64
spec/build/bsps/aarch64/a53/linkcmds_ilp32.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/a53/linkcmds_ilp32.yml:target: linkcmds
spec/build/bsps/aarch64/a53/linkcmds_lp64.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/a53/linkcmds_lp64.yml:target: linkcmds
spec/build/bsps/aarch64/xen/linkcmds.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/xen/linkcmds.yml:target: linkcmds
spec/build/bsps/aarch64/xen/bspxen.yml: uid: linkcmds
spec/build/bsps/aarch64/rk3399/linkcmds.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/rk3399/linkcmds.yml:target: linkcmds
spec/build/bsps/aarch64/rk3399/bsprockpro64.yml: uid: linkcmds
spec/build/bsps/aarch64/a72/linkcmds_ilp32.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/a72/linkcmds_ilp32.yml:target: linkcmds
spec/build/bsps/aarch64/a72/bspa72lp64qemu.yml: uid: linkcmds_lp64
spec/build/bsps/aarch64/a72/linkcmds_lp64.yml: INCLUDE linkcmds.base
spec/build/bsps/aarch64/a72/linkcmds_lp64.yml:target: linkcmds
spec/build/bsps/aarch64/a72/bspa72ilp32qemu.yml: uid: linkcmds_ilp32
How these specs files work is out of scope for here and I suggest the best place to get some hints is the Software Engineering Manual. We also do not have a tool to in the project help navigate these files and I tend to use grep. Others in the project may have better ways to manage the spec files.
Gitlab won’t allow me to create issues, so no I can’t create an issue at this time.
Please come into #gitlab-support on Discord thanks.
And issue added. Thanks for walking me through to how you can add issues in the new gitlab UI!