Adding a Target

Step-by-step guide to adding support for a new hardware platform in OpenWrt.

Adding a new target involves creating the directory structure under target/linux/<target>/, writing a target Makefile, providing kernel configuration fragments, Device Tree Sources, and defining image generation rules.

Adding a target from scratch is non-trivial. Start by reading the Makefiles of the closest existing target to understand patterns and conventions.

Required Files

At minimum, a new target needs:

File	Purpose
target/linux/<target>/Makefile	Declares architecture, features, subtargets, default packages
target/linux/<target>/config-<version>	Kernel config fragment for the target
target/linux/<target>/image/Makefile	Image generation rules
target/linux/<target>/dts/*.dts	Device Tree Sources for individual boards

Optional but common:

File	Purpose
target/linux/<target>/base-files/	Overlay files copied into the rootfs
target/linux/<target>/patches-<version>/	Kernel patches specific to this target
target/linux/<target>/modules.mk	Additional kernel module selections

Step-by-Step

1. Create the target directory

   mkdir -p target/linux/mytarget/image
   mkdir -p target/linux/mytarget/dts
   mkdir -p target/linux/mytarget/base-files/etc
   
2. Write the target Makefile

   Create target/linux/mytarget/Makefile:

   include $(TOPDIR)/rules.mk
   
   ARCH:=aarch64
   BOARD:=mytarget
   BOARDNAME:=My New Target
   CPU_TYPE:=cortex-a53
   SUBTARGETS:=generic
   
   FEATURES:=squashfs ext4 ramdisk
   
   KERNEL_PATCHVER:=6.12
   
   include $(INCLUDE_DIR)/target.mk
   
   DEFAULT_PACKAGES += kmod-gpio-button-hotplug
   
   $(eval $(call BuildTarget))
   
3. Create a kernel config fragment

   Create target/linux/mytarget/config-6.12 with the kernel options required by your SoC:

   CONFIG_ARCH_MYHARDWARE=y
   CONFIG_SMP=y
   CONFIG_NR_CPUS=4
   CONFIG_ARM64=y
   # CONFIG_VIRTUALIZATION is not set
   

   This fragment is merged on top of the generic kernel config during the build.

4. Add Device Tree Sources

   Place .dts files for each board variant in target/linux/mytarget/dts/. These follow the upstream Linux DTS format.

   // target/linux/mytarget/dts/my-board-v1.dts
   /dts-v1/;
   #include "my-soc.dtsi"
   
   / {
       model = "My Board v1";
       compatible = "myvendor,my-board-v1", "myvendor,my-soc";
   };
   
5. Define image generation

   Create target/linux/mytarget/image/Makefile to define how firmware images are built for each device:

   include $(TOPDIR)/rules.mk
   include $(INCLUDE_DIR)/image.mk
   
   define Device/my-board-v1
     DEVICE_VENDOR := MyVendor
     DEVICE_MODEL := My Board
     DEVICE_VARIANT := v1
     DEVICE_DTS := my-board-v1
     IMAGES := sysupgrade.bin factory.bin
     IMAGE/sysupgrade.bin := append-kernel | pad-to 64k | append-rootfs | pad-rootfs | check-size
     IMAGE/factory.bin    := append-kernel | pad-to 64k | append-rootfs | pad-rootfs
   endef
   TARGET_DEVICES += my-board-v1
   
   $(eval $(call BuildImage))
   
6. Register the target

   The build system automatically discovers targets from target/linux/. Run make menuconfig and verify your target appears under Target System.

Target Makefile Variables

Variable	Description	Example
ARCH	CPU architecture name (used by GCC)	mips, arm, aarch64, x86_64
BOARD	Short target identifier used in path names	ath79, x86, mediatek
BOARDNAME	Human-readable name shown in menuconfig	Atheros ATH79
CPU_TYPE	CPU type passed to -march=	24kc, cortex-a53
SUBTARGETS	Space-separated list of subtarget names	generic nand tiny
FEATURES	Supported image/filesystem features	squashfs ext4 ramdisk
KERNEL_PATCHVER	Linux kernel version to use	6.12
DEFAULT_PACKAGES	Packages included in every image for this target	kmod-ath9k uboot-envtools

FEATURES Values

Common values for the FEATURES variable:

Feature	Meaning
squashfs	Build SquashFS rootfs images
ext4	Build ext4 rootfs images
ramdisk	Support initramfs images
vdi	Build VirtualBox disk images
vmdk	Build VMware disk images
fpu	Target has hardware floating-point unit
usbgadget	USB gadget / device-mode support
boot-part	Separate boot partition for kernel
rootfs-part	Separate rootfs partition

Kernel Config Fragments

Kernel configuration is assembled by merging multiple fragments in order:

1. target/linux/generic/config-<version> — base config shared across all targets
2. target/linux/<target>/config-<version> — target-specific additions
3. target/linux/<target>/<subtarget>/config-<version> — subtarget-specific additions (if present)

Fragments use standard Linux Kconfig syntax. Only lines that differ from upstream defaults need to be included.

Use make kernel_menuconfig to interactively configure the kernel and then make kernel_menuconfig CONTROL=save or compare the generated config to extract your changes into the fragment file.

Submitting Upstream

New target submissions should:

• Follow the OpenWrt contribution guidelines
• Include at minimum one working device definition with tested factory and sysupgrade images
• Pass CI build checks
• Be sent as a patch series to the openwrt-devel mailing list or as a GitHub pull request