|
|
@@ -0,0 +1,102 @@
|
|
|
+Adding support for new hardware
|
|
|
+===============================
|
|
|
+This page will give a short overview on how to add support
|
|
|
+for new hardware to Gluon.
|
|
|
+
|
|
|
+Hardware requirements
|
|
|
+---------------------
|
|
|
+Having an ath9k (or ath10k) based WLAN adapter is highly recommended,
|
|
|
+although other chipsets may also work. VAP (multiple SSID) support
|
|
|
+is a requirement. At the moment, Gluon's scripts can't handle devices
|
|
|
+without WLAN adapters (although such environments may also be interesting,
|
|
|
+e.g. for automated testing in virtual machines).
|
|
|
+
|
|
|
+.. _hardware-adding-profiles:
|
|
|
+
|
|
|
+Adding profiles
|
|
|
+---------------
|
|
|
+The vast majority of devices with ath9k WLAN uses the ar71xx target of OpenWrt.
|
|
|
+If the hardware you want to add support for is also ar71xx, adding a new profile
|
|
|
+is enough.
|
|
|
+
|
|
|
+Profiles are defined in ``targets/<target>-<subtarget>/profiles.mk``. There are two macros
|
|
|
+used to define which images are generated: ``GluonProfile`` and ``GluonModel``. The following examples
|
|
|
+are taken from ``profiles.mk`` of the ``ar71xx-generic`` target::
|
|
|
+
|
|
|
+ $(eval $(call GluonProfile,TLWR1043))
|
|
|
+ $(eval $(call GluonModel,TLWR1043,tl-wr1043nd-v1-squashfs,tp-link-tl-wr1043n-nd-v1))
|
|
|
+ $(eval $(call GluonModel,TLWR1043,tl-wr1043nd-v2-squashfs,tp-link-tl-wr1043n-nd-v2))
|
|
|
+
|
|
|
+The ``GluonProfile`` macro takes at least one parameter, the profile name as it is
|
|
|
+defined in the Makefiles of OpenWrt (``openwrt/target/linux/<target>/<subtarget>/profiles/*``
|
|
|
+and ``openwrt/target/linux/<target>/image/Makefile``). If the target you are on doesn't define
|
|
|
+profiles (e.g. on x86), just add a single profile called ``Generic`` or similar.
|
|
|
+
|
|
|
+It may optionally take a second parameter which defines additional packages to include for the profile
|
|
|
+(e.g. ath10k). The additional packages defined in ``openwrt/target/linux/<target>/<subtarget>/profiles/*``
|
|
|
+aren't used.
|
|
|
+
|
|
|
+The ``GluonModel`` macro takes three parameters: The profile name, the suffix of the image file
|
|
|
+generated by OpenWrt (without the file extension), and the final image name of the Gluon image.
|
|
|
+The final image name must be the same that is returned by the following command.
|
|
|
+
|
|
|
+::
|
|
|
+
|
|
|
+ lua -e 'print(require("platform_info").get_image_name())'
|
|
|
+
|
|
|
+
|
|
|
+This is so the autoupdater can work. On targets with aren't supported by the autoupdater,
|
|
|
+``require("platform_info").get_image_name()`` will just return ``nil`` and the final image name
|
|
|
+may be defined arbitrarily.
|
|
|
+
|
|
|
+On devices with multiple WLAN adapters, care must also be taken that the primary MAC address is
|
|
|
+configured correctly. ``/lib/gluon/core/sysconfig/primary_mac`` should contain the MAC address which
|
|
|
+can be found on a label on most hardware; if it does not, ``/lib/gluon/upgrade/core/initial/001-sysconfig``
|
|
|
+in ``gluon-core`` might need a fix. (There have also been cases in which the address was incorrect
|
|
|
+even on devices with only one WLAN adapter, in these cases an OpenWrt bug was the cause).
|
|
|
+
|
|
|
+Adding support for new hardware targets
|
|
|
+---------------------------------------
|
|
|
+Adding a new target is much more complex than adding a new profile. There are two basic steps
|
|
|
+required for adding a new target:
|
|
|
+
|
|
|
+Adjust packages
|
|
|
+'''''''''''''''
|
|
|
+One package that definitely needs adjustments for every new target added is ``lua-platform-info``. Just
|
|
|
+start with a copy of an existing platform info script, adjust it for the new target, and add the new target
|
|
|
+to the list of supported targets in the package Makefile.
|
|
|
+
|
|
|
+On many targets, Gluon's network setup scripts (mainly in the packages ``gluon-core`` and ``gluon-mesh-batman-adv-core``)
|
|
|
+won't run correctly without some adjustments, so better double check that everything is fine there (and the files
|
|
|
+``primary_mac``, ``lan_ifname`` and ``wan_ifname`` in ``/lib/gluon/core/sysconfig/`` contain sensible values).
|
|
|
+
|
|
|
+Add support to the build system
|
|
|
+'''''''''''''''''''''''''''''''
|
|
|
+A directory for the new target must be created under ``targets``, and it must be added
|
|
|
+to ``targets/targets.mk``. In the new target directory, four files must be created:
|
|
|
+
|
|
|
+* config
|
|
|
+* kernel-config
|
|
|
+* kernel-vermagic
|
|
|
+* profiles.mk
|
|
|
+
|
|
|
+The file ``config`` can be used to add additional, target-specific options to the OpenWrt config. If such options
|
|
|
+aren't necessary, it can be left empty. For ``profiles.mk``, see :ref:`hardware-adding-profiles`.
|
|
|
+
|
|
|
+The files ``kernel-config`` and ``kernel-vermagic`` must have the correct content so kernel modules from the upstream repositories
|
|
|
+can be easily installed. The OpenWrt version a Gluon release is based on is defined by the upstream package repo URL in ``include/gluon.mk``
|
|
|
+(in the variable ``CONFIG_VERSION_REPO``); at the time this documentation was written, this was ``barrier_breaker/14.07-rc3``; whenever
|
|
|
+the package repo is updated, all ``kernel-config`` and ``kernel-vermagic`` files must be updated as well.
|
|
|
+
|
|
|
+The file ``kernel-vermagic`` just contains a hash which is part of the version number of the kernel package. So in the case of ``ar71xx-generic`` on
|
|
|
+``barrier_breaker/14.07-rc3``, we look in the directory ``https://downloads.openwrt.org/barrier_breaker/14.07-rc3/ar71xx/generic/packages/`` and
|
|
|
+find that the kernel package is called ``kernel_3.10.49-1-94831e5bcf361d1c03e87a15e152b0e8_ar71xx.ipk``. This makes the ``kernel-vermagic`` the
|
|
|
+string ``94831e5bcf361d1c03e87a15e152b0e8``.
|
|
|
+
|
|
|
+For ``kernel-config``, the OpenWrt image builder must be downloaded. Again, for ``ar71xx-generic`` on
|
|
|
+``barrier_breaker/14.07-rc3``, we download ``OpenWrt-SDK-ar71xx-for-linux-x86_64-gcc-4.8-linaro_uClibc-0.9.33.2.tar.bz2``
|
|
|
+from ``https://downloads.openwrt.org/barrier_breaker/14.07-rc3/ar71xx/generic/``. After unpacking it, we use the file
|
|
|
+``OpenWrt-ImageBuilder-ar71xx_generic-for-linux-x86_64/build_dir/target-mips_34kc_uClibc-0.9.33.2/linux-ar71xx_generic/linux-3.10.49/.config``
|
|
|
+as our ``kernel-config``.
|
|
|
+
|
|
|
+After this, is should be sufficient to call ``make GLUON_TARGET=<target>-<subtarget>`` to build the images for the new target.
|
Matthias Schiffer