Copying a board directory, as we did for EP-Falcon in the last lecture, doesn’t make it
buildable. U-Boot has to know your board exists, which images to build for it, and which config
options apply to which of those images. That’s Kconfig and defconfig’s job, and it’s the subject of
this lecture in our free linux kernel development course.
u-boot defconfig
free linux kernel development course
spl and tpl images
What You Will Learn
- Why U-Boot can produce up to three separate binaries from one configuration
- What the SPL/TPL target-scope prefixes in a defconfig mean and when to use each
- How to create a working defconfig for a new board
- How to add a board’s target option to its architecture’s Kconfig menu
Prerequisites
- elch3_20 — Porting U-Boot To New Boards (we continue the EP-Falcon example from there)
- Basic familiarity with Linux kernel-style Kconfig, if you’ve taken our device driver lectures
One Config, Up To Three Binaries
Most SoCs that need U-Boot at all can’t jump straight from ROM code into the full U-Boot binary —
there isn’t enough on-chip SRAM to hold it, or DRAM isn’t initialized yet. So a build can produce up
to three separate images from one configuration pass:
- The normal
u-boot.bin— the full-featured bootloader, running from DRAM - A Secondary Program Loader (SPL) — a tiny image that fits in on-chip SRAM,
whose only job is to init DRAM and load the next stage - A Tertiary Program Loader (TPL) — an even earlier, smaller stage some SoCs need
before SPL can even run
Because each of these three images is compiled with a different, much tighter size budget, some
Kconfig options should only apply to one image, some to two, and some to all three. U-Boot’s
defconfig format handles that with a line prefix:
| Prefix | Applies To |
|---|---|
| (none) | Normal image only |
S: |
SPL image only |
T: |
TPL image only |
ST: |
SPL and TPL images |
+S: |
Normal and SPL images |
+T: |
Normal and TPL images |
+ST: |
Normal, SPL, and TPL images |
│ loads a tiny image into on-chip SRAM
▼
SPL — inits DRAM clocking, loads next stage
│
▼
u-boot.bin — runs from DRAM, full command shell,
loads and boots the Linux kernel
Writing EP-Falcon’s Defconfig
Continuing our EP-Falcon example from the previous lecture, each board has a default configuration
stored as configs/<board name>_defconfig. We create
configs/ep_falcon_defconfig with the settings that decide which images get built and
which board target is selected:
CONFIG_SPL=y
CONFIG_SYS_EXTRA_OPTIONS="SERIAL2,CONS_INDEX=1,SDMMC_BOOT"
+S:CONFIG_ARM=y
+S:CONFIG_TARGET_EP_FALCON=yReading this line by line: CONFIG_SPL=y tells the build system to produce the SPL
binary in addition to the normal image. CONFIG_ARM=y, prefixed +S:, pulls
in arch/arm/Kconfig for both the normal and SPL images — it has to apply to both because
both are ARM binaries. CONFIG_TARGET_EP_FALCON=y, also +S:, is what
actually selects our board as the build target, and again needs to take effect for both images since
both need to know which board they’re building for.
Registering The Board In Kconfig
A defconfig alone isn’t enough — CONFIG_TARGET_EP_FALCON has to actually exist as a
Kconfig option before the defconfig can select it. That means adding a menu entry to the
architecture’s Kconfig file (for ARM, that’s under arch/arm/Kconfig):
config TARGET_EP_FALCON
bool "Support EP-Falcon board"Once this is in place, running U-Boot’s config tooling against our new defconfig should succeed
and produce a working .config:
$ make ep_falcon_defconfig
$ make -j$(nproc)If the option was never added to the architecture Kconfig, the first command fails immediately
with an unknown symbol error — that’s the single most common first mistake when registering a new
board, and it’s worth checking first whenever make <board>_defconfig doesn’t
behave as expected.
Common Mistakes And Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
make ep_falcon_defconfig fails with an unknown config symbol |
Board’s TARGET_* option was never added to the architecture Kconfig |
Add the config TARGET_... block before running defconfig again |
| SPL builds but hangs before reaching u-boot.bin | A setting that should have been +S: was left unprefixed, so SPL never got it |
Re-check which settings SPL actually needs and add the correct prefix |
| Normal image builds fine but SPL fails to build | An option needed by SPL was accidentally scoped (none) instead of +S: |
Move the setting to the correct SPL-inclusive prefix |
Best Practices
- Start every new board’s defconfig from the closest reference board’s defconfig, not from a
blank file — the prefix choices are usually already correct for shared SoC-level options. - Change one option at a time when first bringing up a defconfig, rebuilding after each change,
so a broken build points at exactly one line. - Keep the Kconfig
booldescription short and identifiable — it’s what shows up in
make menuconfigwhen someone else browses available boards later.
Summary And Key Takeaways
- A single U-Boot configuration can drive up to three binaries: normal, SPL, and TPL.
- Defconfig line prefixes (
S:,T:,ST:,+S:,
+T:,+ST:) control which of those images each line applies to. - A board’s
TARGET_*option must be registered in the architecture Kconfig before
any defconfig can select it.
Conclusion
With configs/ep_falcon_defconfig in place and TARGET_EP_FALCON
registered, EP-Falcon is now a buildable U-Boot target — even before its board-specific C files have
been touched. The next lecture finishes the port by adjusting the board directory’s own files and the
per-board configuration header.
Frequently Asked Questions
Do all boards need an SPL stage?
No — only SoCs that can’t run the full U-Boot binary directly from ROM/flash, typically because
DRAM must be initialized first by a small on-chip-SRAM-resident stage.
What does the ST: prefix mean versus +ST:?
ST: applies a line to SPL and TPL only, while +ST: applies it to the
normal image as well as SPL and TPL — the leading + adds the normal image to the
scope.
Why does the board Kconfig option need a separate step from the defconfig?
The defconfig only selects options that already exist; it can’t invent a new
TARGET_* symbol, so the architecture Kconfig has to define it first.
Can I have both an SPL and a TPL for the same board?
Yes, some SoCs require both — an even smaller TPL that runs first, followed by SPL, followed by
the normal image.
Is CONFIG_SYS_EXTRA_OPTIONS required?
No — it’s a convenience string some boards use to bundle several legacy header-based options
together; increasingly, individual boards express the same settings as native Kconfig options
instead.
Continue The Free Linux Kernel Development Course
Next: finishing the EP-Falcon port with board files and its configuration header.