diff --git a/docs/files/dt-overlay/compile-dtb-lk-4.14.patch b/docs/files/dt-overlay/compile-dtb-lk-4.14.patch new file mode 100644 index 0000000..13e97d5 --- /dev/null +++ b/docs/files/dt-overlay/compile-dtb-lk-4.14.patch @@ -0,0 +1,14 @@ +diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib +index aac94d96..d22bb79d 100644 +--- a/scripts/Makefile.lib ++++ b/scripts/Makefile.lib +@@ -270,6 +270,9 @@ cmd_gzip = (cat $(filter-out FORCE,$^) | gzip -n -f -9 > $@) || \ + # --------------------------------------------------------------------------- + DTC ?= $(objtree)/scripts/dtc/dtc + ++# Enable overlay support ++DTC_FLAGS += -@ ++ + # Disable noisy checks by default + ifeq ($(KBUILD_ENABLE_EXTRA_GCC_CHECKS),) + DTC_FLAGS += -Wno-unit_address_vs_reg \ diff --git a/docs/files/dt-overlay/compile-dtb-lk-4.19.patch b/docs/files/dt-overlay/compile-dtb-lk-4.19.patch new file mode 100644 index 0000000..1eb431e --- /dev/null +++ b/docs/files/dt-overlay/compile-dtb-lk-4.19.patch @@ -0,0 +1,14 @@ +diff --git a/scripts/Makefile.lib b/scripts/Makefile.lib +index 61e596650..fdb066e51 100644 +--- a/scripts/Makefile.lib ++++ b/scripts/Makefile.lib +@@ -244,6 +244,9 @@ cmd_gzip = (cat $(filter-out FORCE,$^) | gzip -n -f -9 > $@) || \ + # --------------------------------------------------------------------------- + DTC ?= $(objtree)/scripts/dtc/dtc + ++# Enable overlay support ++DTC_FLAGS += -@ ++ + # Disable noisy checks by default + ifeq ($(findstring 1,$(KBUILD_ENABLE_EXTRA_GCC_CHECKS)),) + DTC_FLAGS += -Wno-unit_address_vs_reg \ diff --git a/docs/files/dt-overlay/dtc b/docs/files/dt-overlay/dtc new file mode 100755 index 0000000..f8e6435 Binary files /dev/null and b/docs/files/dt-overlay/dtc differ diff --git a/docs/gpio.md b/docs/gpio.md index 297bd73..5d737cd 100644 --- a/docs/gpio.md +++ b/docs/gpio.md @@ -132,3 +132,244 @@ echo 511 | sudo tee -a /sys/class/gpio/export echo "out" | sudo tee -a /sys/class/gpio/gpio511/direction echo 1 | sudo tee -a /sys/class/gpio/gpio511/value ``` + +## Use GPIO with Device Tree Overlay + +!!! info + Device Tree Compiler (dtc) from OS package manager usually is too old, use the one from kernel source or download binary version for Arm [here](/files/dt-overlay/dtc). + +Another way to use the GPIO is by using device tree. In device tree the user accessible +GPIO is labelled as [expander0](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/arch/arm/boot/dts/armada-388-helios4.dts#n155). + +Instead of directly modifying the Helios4 device tree source (*armada-388-helios4.dts*) and recompiling, +Linux and U-Boot provide a mechanism called device tree overlay. With overlay, user just needs +to create simple device tree that would be overlay'd on top of base device tree. + +For example, to use **IO0_2** as power off button input, create following device tree source +and save it as power-button.dts + +``` +/dts-v1/; +/plugin/; + +/ { + fragment@0 { + target-path = "/gpio-keys"; + __overlay__ { + power-button { + label = "Soft Power Off"; + linux,code = <116>; + gpios = <&expander0 2 1>; + }; + }; + }; +}; + +``` +Download dtc and compile device tree with this command + +``` +wget https://wiki.kobol.io/files/dt-overlay/dtc +chmod 755 dtc +./dtc -I dts -O dtb -o power-button.dtbo power-button.dts +``` + +***Button Wiring*** + +![button wiring](/img/gpio/power_button_sch.png) + +The GPIO has internal pull up resistor, when the button is not pressed the input read as High and when the button is pressed the input read as Low, therefore we use active low flag. + +---- + +In the above example you will find the 2 following lines + +``` +linux,code = <116>; +gpios = <&expander0 2 1>; +``` + +For **linux,code** property, you can use one of the following values. For complete even code list refer to [input-event-codes.h](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/plain/include/uapi/linux/input-event-codes.h). + +| Event Code Name | Event Code | Description | +|-------------|-------|---------------| +| KEY_POWER | 116 | Power Button | +| KEY_SLEEP | 142 | Sleep Button | +| KEY_WAKEUP | 116 | Power Button | +| BTN_0 | 0x100 | User Button 0 | +| BTN_1 | 0x101 | User Button 1 | +| BTN_2 | 0x102 | User Button 2 | +| BTN_3 | 0x103 | User Button 3 | +| BTN_4 | 0x104 | User Button 4 | +| BTN_5 | 0x105 | User Button 5 | +| BTN_6 | 0x106 | User Button 6 | +| BTN_7 | 0x107 | User Button 7 | +| BTN_8 | 0x108 | User Button 8 | +| BTN_9 | 0x109 | User Button 9 | + +For **gpios** properties, the syntax is as follow + +`<&expander0 index flag>` + +Where *index* is one of the following values + +| Port Number | Index | +|-------|----| +| IO0_2 | 2 | +| IO0_3 | 3 | +| IO0_4 | 4 | +| IO0_7 | 7 | +| IO1_0 | 8 | +| IO1_1 | 9 | +| IO1_2 | 10 | +| IO1_3 | 11 | +| IO1_4 | 12 | +| IO1_5 | 13 | +| IO1_6 | 14 | +| IO1_7 | 15 | + +And *flag* is one of the following values + +| Flag | Property | +|------|-----------| +| 0 | GPIO line is active high | +| 1 | GPIO line is active low | + +For more info please refer to +[gpio-keys binding](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/plain/Documentation/devicetree/bindings/input/gpio-keys.txt). + +### Device Tree Overlay under Armbian + +Create */boot/overlay-user/* to store the overlay and copy the overlay to the folder + +``` +sudo mkdir -p /boot/overlay-user +sudo cp power-button.dtbo /boot/overlay-user/ +``` + +Then edit */boot/armbianEnv.txt* and append the overlay filename (without dtbo extension) to *user_overlays* + +`user_overlays=power-button` + +Reboot the system to load the overlay. + + +!!! notes + If there is more than one overlay file, separate it by space. For example + + `user_overlays=power-button sleep-button` + +---- + +***Additional Steps for U-Boot 2018.11 (Armbian Default)*** + +Bootscript (**boot.scr**) used in Armbian Default does not have routine to automatically load overlay from */boot/overlay-user* therefore **/boot/boot.cmd** need to be modified. + +Append the following block + +``` +fdt addr ${fdt_addr} +fdt resize 65536 + +for overlay_file in ${user_overlays}; do + if load ${boot_interface} 0:1 ${loadaddr} ${prefix}overlay-user/${overlay_file}.dtbo; then + echo "Applying user provided DT overlay ${overlay_file}.dtbo" + fdt apply ${loadaddr} || setenv overlay_error "true" + fi +done + +if test "${overlay_error}" = "true"; then + echo "Error applying DT overlays, restoring original DT" + load ${boot_interface} 0:1 ${fdt_addr} ${prefix}dtb/${fdtfile} +fi +``` + +before + +`bootz ${kernel_addr_r} ${ramdisk_addr_r} ${fdt_addr}` + +so it become + +``` +fdt addr ${fdt_addr} +fdt resize 65536 + +for overlay_file in ${user_overlays}; do + if load ${boot_interface} 0:1 ${loadaddr} ${prefix}overlay-user/${overlay_file}.dtbo; then + echo "Applying user provided DT overlay ${overlay_file}.dtbo" + fdt apply ${loadaddr} || setenv overlay_error "true" + fi +done + +if test "${overlay_error}" = "true"; then + echo "Error applying DT overlays, restoring original DT" + load ${boot_interface} 0:1 ${fdt_addr} ${prefix}dtb/${fdtfile} +fi + +bootz ${kernel_addr_r} ${ramdisk_addr_r} ${fdt_addr} +``` + +Recompile with + +`mkimage -C none -A arm -T script -d /boot/boot.cmd /boot/boot.scr` + +---- + +### Device Tree Overlay under Other Distro + +#### Compile Helios4 DTB with Symbol Support + +Download Linux Kernel source code and extract it to *~/src/linux*. Change directory to *~/src/linux* + +Download and apply kernel patch for + +- Linux Kernel 4.14 + +``` +wget https://wiki.kobol.io/files/dt-overlay/compile-dtb-lk-4.14.patch +git apply --apply compile-dtb-lk-4.14.patch +``` + +- Linux Kernel 4.19 + +``` +wget https://wiki.kobol.io/files/dt-overlay/compile-dtb-lk-4.19.patch +git apply --apply compile-dtb-lk-4.19.patch +``` + +Compile Helios4 device tree + +`make armada-388-helios4.dtb` + +Copy the dtb to boot folder (eg. /boot/dtb/) + +`sudo cp arch/arm/boot/dts/armada-388-helios4.dtb /boot/dtb/` + +Copy the overlay also to the same folder. + +#### Apply overlay on U-Boot + +To apply overlay to base dtb, the procedure is + +1. Load Helios4 dtb to memory +2. Set fdt address to dtb address +3. Resize the fdt +4. Load overlay to memory +5. Apply from overlay address +6. Boot the kernel + +Example command + +``` +load mmc 0:1 ${ramdisk_addr_r} /boot/uInitrd +load mmc 0:1 ${kernel_addr_r} /boot/zImage + +load mmc 0:1 ${fdt_addr_r} /boot/dtb/${fdtfile} +fdt addr ${fdt_addr_r} +fdt resize 65536 +load mmc 0:1 0x300000 /boot/dtb/power-button.dtbo +fdt apply 0x300000 + +bootz ${kernel_addr_r} ${ramdisk_addr_r} ${fdt_addr_r} + +``` diff --git a/docs/img/gpio/power_button_sch.png b/docs/img/gpio/power_button_sch.png new file mode 100644 index 0000000..257f768 Binary files /dev/null and b/docs/img/gpio/power_button_sch.png differ