This should be an introduction into building the hardware support for a specific device into Lede.
It is based on ar7xxx/ar9xxx devices, and probably only applicable to those.
More information can be found (probably outdated for Lede) on the OpenWRT-Wiki:
https://wiki.openwrt.org/doc/devel/add.new.device
Collect:
Hardware information:
Used chipset
Wifi chipset
Switches
Bootlog via serial console
If you have access to the firmware on the device, collect the dmesg output
...
Build a kernel with an initramfs for this device. This allows booting the device without installing a permanent firmware. Checkout the current Lede git, and select in the menuconfig the following:
Atheros ar7xxxx/ar9xxx
subtarget generic
target profile all drivers
(similar for other devices) the resulting lede-ar71xx-generic-vmlinux-initramfs.bin can then be copied to the tftp server as ifs.bin. Then, use the uboot console to boot the kernel built for the target SoC(or a similar device).
For TP-Link devices, type "tpl" while the "Autobooting in 1 second" message is displayed, for other devices press any key during that time (ubiquity, for example). This will allow access to the uboot bootloader.
Use a tftp server and the tftpboot command to boot the kernel:
"tftpboot 0x80060000 ifs.bin"
#### ifs.bin gets copied to the device
"go 0x80060000 console=ttyS0,115200"
# kernel should start booting up
0x80060000 is an address at the start of the RAM (on many ar71xx/Tplink devices - it may be good to check the bootlog/dmesg output, to see the RAM mappings for your device!)
If all goes well, you should see Linux console output on your serial console. To further check if any other profiles already fit for this device, you can use the "board" boot parameter:
"go 0x80060000 console=ttyS0,115200 board=TL-WR1043ND-v4"
(this will boot the device profile for the tl-wr1043nd-v4 - other profiles can be found in the Lede sourcecode) If you have a working console, and a way to transfer data (working wifi/Lan), now might be a good time to dump the flash as a backup and for further dissection:
cat /dev/mtd0 > /tmp/mtd0 # dumps the flash memory
now scp or tranfser to another pc, or use serial console (might take a while)
If you have a running ram image on the device, and some functions like wifi/lan/leds are not working, it would be now prudent to build a new target profile for the device. The files needed can be seen in the following commit:
https://github.com/lede-project/source/pull/613/commits/3bb87787c230012d80e723704a74f8ee7103a9ca
Main file is target/linux/ar71xx/files/arch/mips/ath79/mach-tl-wr1043nd-v4.c . (the mach file) Here the drivers and other setup steps take place. If an existing device has some parts of the new device working (for example the switch or wifi) it might be good to take a look at those parts and integrate them into a new profile for the new device. If an existing device profile fits already, it might be more efficient to just add the new device to the other profile as a new target.
A small compilation about files to edit:
-
target/linux/ar71xx/base-files/lib/ar71xx.sh
Machine names are set here - matched string corresponds to argument 3 of MIPS_MACHINE() from mach file If forgotten, some settings in other files will not take effect - switch port config for example, or firmware file loading
-
target/linux/ar71xx/files/arch/mips/ath79/machtypes.h
Machine type specification list, add argument one of MIPS_MACHINE() if needed
-
target/linux/ar71xx/image/[imagetype].mk
Device definition regarding image files, partitions, and the boardname which is argument 2 of MIPS_MACHINE() Don't forget to add the new device with TARGET_DEVICES += !
-
target/linux/ar71xx/base-files/etc/board.d/02_network
Switch and network config is set here. Docu for ucidef_add_switch [switchname] [port] [port] port is either [portnum]:[role]:[index] or [portnum]@[netdev] [index] is optional and merely used for influencing the display order in luci [portnum] is the internal swconfig port number, [portnum]@[netdev] denotes a "CPU port"
ucidef_set_interfaces_lan_wan [LANIF] [WANIF]
-
target/linux/ar71xx/base-files/lib/upgrade/platform.sh
Needed for sysupgrade to work.
-
target/linux/ar71xx/config-X.X
The Kernel config(s) - if the ATH_XXX Config option is not entered here, the build will stop and ask for the new config option - not good for automated builds...
If the LEDS and switch/USB ports are not working, the GPIO mapping is not yet correctly defined.
To test this, use the follwing procedure: (If the device has an USB Port, or several, plug in a device that will light up if it gets power - some GPIOs may toggle the USB-power!)
echo 1 > /sys/class/gpio/export # enable/export the gpio number 1
cat /sys/class/gpio/gpio1/value # see what value it has. press buttons and see if value changes. if it does, you just found the gpio for this button. Note and repeat with next gpio
# if no change then, it might be an outgoing gpio:
echo "out" > /sys/class/gpio/gpio1/direction # set outgoing
echo "1" > /sys/class/gpio/gpio1/value # echo 1 or 0, then see if any leds switch state or if usb has power.
# if nothing happens, it might be the gpio for the switch, wifi or not used
It can happen that some gpios are forcing a reset or similar, just continue with the next gpio. The numbers of the gpios might be in a different range for your device, again check similar devices to see which range you might want to try. (200-230, 1-25, etc)
The found numbers then can be added to the mach file, see the struct "gpio_led".
On Atheros based devices, the mac adresses usually reside inside a config or ART partition. This partition (or more rpecise, the address to the Calibration data) has to be given to the driver in the mach file, along with the mac address location(s). If you have your flashdump and a hex editor ready, you can take a look at the partition table and search for the mac address locations (the address should be know, search the packaging/device). Then, use the found location and provide the driver with it:
KSEG1ADDR + ath79_register_wmac / ath79_init_mac
if there is a separate mac for lan and wan on the same switch (initialisation is one device in mach file), load lan address in mach file, then set mac for wan in "/target/linux/ar71xx/base-files/etc/board.d/02_network"
If you are lucky, one of the standard image formats for your device will work, try to look at the other profiles and see if the resulting image is similar to the image you can aquire from the manufacturer.
After merging relevant commits, please run the follwing script to check for any style/formating issues:
git format-patch --stdout -1 | ./scripts/checkpatch.pl -
This will check the last commit for any codestyle violations.
- All new entries sorted correctly into alphabetical order in listings?
-
git checkout -b branchname
create new branch
-
git checkout filename
revert file to original
-
git rebase -i HEAD~2
allows to merge/fix the last 2 commits, use to fixup an existing commit use HEAD~1 and reword(r) to fix commit messages
-
git push origin branchname --force
force push branch if you did a fixup (pull requests, etc - destroys the history!)