Kernel Configuration
About 529 wordsAbout 2 min
2025-12-21
The Core Principle
You should never edit the kernel source or .config file directly. Every manual edit to .config is lost on the next bitbake -c clean. Yocto provides a reproducible, version-controlled workflow.
How linux-yocto Works
linux-yocto is Yocto's reference kernel recipe. It uses a two-branch git model to separate kernel source from configuration:
linux-yocto git repository
├── standard branch (v6.6/standard/base)
│ └── actual kernel C source code
└── meta branch (v6.6/standard/base + meta)
└── .scc and .cfg files (kernel metadata/config fragments)
└── KMACHINE definitions
└── BSP-specific config fragments
└── feature fragmentsKMACHINE maps the Yocto MACHINE name to the kernel's internal BSP name:
# In a machine.conf:
KMACHINE:my-board = "my-board-kmachine" # matches the entry in the kernel meta branchMethod 1: Config Fragments (Recommended)
Config fragments are small .cfg files containing only the delta from the base defconfig. This is the correct, maintainable approach.
# Step 1: Open the interactive kernel config menu
bitbake -c menuconfig virtual/kernel
# Step 2: Make your changes in the TUI (e.g., enable CONFIG_USB_CDC_ACM)
# Step 3: Generate the fragment (diff vs base config)
bitbake -c diffconfig virtual/kernel
# Output: .../linux-yocto/<ver>/defconfig (contains only your changes)
# Example content of the fragment:
# CONFIG_USB_CDC_ACM=y
# CONFIG_USB_SERIAL=m
# Step 4: Copy the fragment to your layer
cp .../defconfig meta-myproduct/recipes-kernel/linux/linux-yocto/enable-usb-cdc.cfg
# Step 5: Create a .bbappend to apply the fragment
cat > meta-myproduct/recipes-kernel/linux/linux-yocto_%.bbappend << 'EOF'
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://enable-usb-cdc.cfg"
EOF
# Step 6: Rebuild the kernel
bitbake -c cleansstate virtual/kernel
bitbake virtual/kernel
# Step 7: Verify the option was applied
grep USB_CDC_ACM tmp/work/*/linux-yocto/*/build/.configMethod 2: Custom defconfig
For boards where you want to own the complete kernel configuration (common with BSP-specific kernels):
# Step 1: Place your defconfig in the layer
mkdir -p meta-myproduct/recipes-kernel/linux/linux-yocto/
cp my_board_defconfig meta-myproduct/recipes-kernel/linux/linux-yocto/
# Step 2: .bbappend picks it up
# meta-myproduct/recipes-kernel/linux/linux-yocto_%.bbappend:
FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://my_board_defconfig"
KBUILD_DEFCONFIG = "my_board_defconfig"
KCONFIG_MODE = "--alldefconfig" # use defconfig, not combining with baseMethod 3: SCC Feature Files (linux-yocto only)
For linux-yocto, .scc files are the native way to group config fragments into named "features" that can be conditionally included:
# meta-myproduct/recipes-kernel/linux/linux-yocto/features/usb-cdc/usb-cdc.scc
define KFEATURE_DESCRIPTION "USB CDC ACM serial support"
define KFEATURE_COMPATIBILITY all
kconf hardware usb-cdc.cfg # references usb-cdc.cfg in the same directory# In .bbappend:
SRC_URI += "file://features/usb-cdc/usb-cdc.scc"Kernel Recipe Structure in a BSP Layer
meta-myproduct/
└── recipes-kernel/
└── linux/
├── linux-yocto_%.bbappend ← apply fragments to upstream recipe
└── linux-yocto/ ← directory named after the recipe
├── enable-cdc-acm.cfg ← config fragment: CONFIG_USB_CDC_ACM=y
├── disable-ipv6.cfg ← config fragment: # CONFIG_IPV6 is not set
└── my-board.scc ← groups fragments for this machineVerification Commands
# Check the final .config that was actually used
cat tmp/work/*/linux-yocto/*/build/.config | grep CONFIG_USB
# Ensure a specific fragment was included
bitbake -e virtual/kernel | grep ^SRC_URI
# Validate config against what was requested (catches typos in option names)
bitbake -c kernel_configcheck virtual/kernel 2>&1 | grep -i error
# Full rebuild from clean state
bitbake -c cleanall virtual/kernel
bitbake virtual/kernel