commit 0b2e2546ec93da6f699f29d9a5706661b35fce77 Author: nbd Date: Sun Jun 14 17:57:16 2015 +0000 add chaos_calmer branch git-svn-id: svn://svn.openwrt.org/openwrt/branches/chaos_calmer@45974 3c298f89-4303-0410-b956-a3cf2f4a3e73 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..fa1385d --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* -text diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..cd86e34 --- /dev/null +++ b/.gitignore @@ -0,0 +1,26 @@ +*.o +.DS_Store +.*.swp +/env +/dl +/.config +/.config.old +/bin +/build_dir +/staging_dir +/tmp +/logs +/feeds +/feeds.conf +/files +/package/feeds +/package/openwrt-packages +key-build* +*.orig +*.rej +*~ +.#* +*# +.emacs.desktop* +TAGS*~ +git-src diff --git a/BSDmakefile b/BSDmakefile new file mode 100644 index 0000000..c6a0425 --- /dev/null +++ b/BSDmakefile @@ -0,0 +1,7 @@ +# Copyright (C) 2006 OpenWrt.org +# +# This is free software, licensed under the GNU General Public License v2. +# See /LICENSE for more information. +# +world ${.TARGETS}: + @gmake $@ diff --git a/Config.in b/Config.in new file mode 100644 index 0000000..d30c048 --- /dev/null +++ b/Config.in @@ -0,0 +1,34 @@ +# Copyright (C) 2006-2013 OpenWrt.org +# +# This is free software, licensed under the GNU General Public License v2. +# See /LICENSE for more information. +# + +mainmenu "OpenWrt Configuration" + +config MODULES + option modules + bool + default y + +config HAVE_DOT_CONFIG + bool + default y + +source "target/Config.in" + +source "config/Config-images.in" + +source "config/Config-build.in" + +source "config/Config-devel.in" + +source "toolchain/Config.in" + +source "target/imagebuilder/Config.in" + +source "target/sdk/Config.in" + +source "target/toolchain/Config.in" + +source "tmp/.config-package.in" diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d60c31a --- /dev/null +++ b/LICENSE @@ -0,0 +1,340 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..a12e3ea --- /dev/null +++ b/Makefile @@ -0,0 +1,91 @@ +# Makefile for OpenWrt +# +# Copyright (C) 2007 OpenWrt.org +# +# This is free software, licensed under the GNU General Public License v2. +# See /LICENSE for more information. +# + +TOPDIR:=${CURDIR} +LC_ALL:=C +LANG:=C +export TOPDIR LC_ALL LANG + +empty:= +space:= $(empty) $(empty) +$(if $(findstring $(space),$(TOPDIR)),$(error ERROR: The path to the OpenWrt directory must not include any spaces)) + +world: + +include $(TOPDIR)/include/host.mk + +ifneq ($(OPENWRT_BUILD),1) + _SINGLE=export MAKEFLAGS=$(space); + + override OPENWRT_BUILD=1 + export OPENWRT_BUILD + GREP_OPTIONS= + export GREP_OPTIONS + include $(TOPDIR)/include/debug.mk + include $(TOPDIR)/include/depends.mk + include $(TOPDIR)/include/toplevel.mk +else + include rules.mk + include $(INCLUDE_DIR)/depends.mk + include $(INCLUDE_DIR)/subdir.mk + include target/Makefile + include package/Makefile + include tools/Makefile + include toolchain/Makefile + +$(toolchain/stamp-install): $(tools/stamp-install) +$(target/stamp-compile): $(toolchain/stamp-install) $(tools/stamp-install) $(BUILD_DIR)/.prepared +$(package/stamp-compile): $(target/stamp-compile) $(package/stamp-cleanup) +$(package/stamp-install): $(package/stamp-compile) +$(target/stamp-install): $(package/stamp-compile) $(package/stamp-install) + +printdb: + @true + +prepare: $(target/stamp-compile) + +clean: FORCE + rm -rf $(BUILD_DIR) $(STAGING_DIR) $(BIN_DIR) $(BUILD_LOG_DIR) + +dirclean: clean + rm -rf $(STAGING_DIR_HOST) $(TOOLCHAIN_DIR) $(BUILD_DIR_HOST) $(BUILD_DIR_TOOLCHAIN) + rm -rf $(TMP_DIR) + +ifndef DUMP_TARGET_DB +$(BUILD_DIR)/.prepared: Makefile + @mkdir -p $$(dirname $@) + @touch $@ + +tmp/.prereq_packages: .config + unset ERROR; \ + for package in $(sort $(prereq-y) $(prereq-m)); do \ + $(_SINGLE)$(NO_TRACE_MAKE) -s -r -C package/$$package prereq || ERROR=1; \ + done; \ + if [ -n "$$ERROR" ]; then \ + echo "Package prerequisite check failed."; \ + false; \ + fi + touch $@ +endif + +# check prerequisites before starting to build +prereq: $(target/stamp-prereq) tmp/.prereq_packages + @if [ ! -f "$(INCLUDE_DIR)/site/$(ARCH)" ]; then \ + echo 'ERROR: Missing site config for architecture "$(ARCH)" !'; \ + echo ' The missing file will cause configure scripts to fail during compilation.'; \ + echo ' Please provide a "$(INCLUDE_DIR)/site/$(ARCH)" file and restart the build.'; \ + exit 1; \ + fi + +prepare: .config $(tools/stamp-install) $(toolchain/stamp-install) +world: prepare $(target/stamp-compile) $(package/stamp-compile) $(package/stamp-install) $(target/stamp-install) FORCE + $(_SINGLE)$(SUBMAKE) -r package/index + +.PHONY: clean dirclean prereq prepare world package/symlinks package/symlinks-install package/symlinks-clean + +endif diff --git a/README b/README new file mode 100644 index 0000000..4cbe563 --- /dev/null +++ b/README @@ -0,0 +1,35 @@ +This is the buildsystem for the OpenWrt Linux distribution. + +Please use "make menuconfig" to configure your appreciated +configuration for the toolchain and firmware. + +You need to have installed gcc, binutils, bzip2, flex, python, perl, make, +find, grep, diff, unzip, gawk, getopt, subversion, libz-dev and libc headers. + +Run "./scripts/feeds update -a" to get all the latest package definitions +defined in feeds.conf / feeds.conf.default respectively +and "./scripts/feeds install -a" to install symlinks of all of them into +package/feeds/. + +Use "make menuconfig" to configure your image. + +Simply running "make" will build your firmware. +It will download all sources, build the cross-compile toolchain, +the kernel and all choosen applications. + +You can use "scripts/flashing/flash.sh" for remotely updating your embedded +system via tftp. + +The OpenWrt system is documented in docs/. You will need a LaTeX distribution +and the tex4ht package to build the documentation. Type "make -C docs/" to build it. + +To build your own firmware you need to have access to a Linux, BSD or MacOSX system +(case-sensitive filesystem required). Cygwin will not be supported because of +the lack of case sensitiveness in the file system. + + +Sunshine! + Your OpenWrt Project + http://openwrt.org + + diff --git a/config/Config-build.in b/config/Config-build.in new file mode 100644 index 0000000..69fb708 --- /dev/null +++ b/config/Config-build.in @@ -0,0 +1,288 @@ +# Copyright (C) 2006-2013 OpenWrt.org +# +# This is free software, licensed under the GNU General Public License v2. +# See /LICENSE for more information. +# + +menu "Global build settings" + + config ALL_KMODS + bool "Select all kernel module packages by default" + default ALL + + config ALL + bool "Select all userspace packages by default" + default n + + config SIGNED_PACKAGES + bool "Cryptographically signed package lists" + default y + + comment "General build options" + + config DISPLAY_SUPPORT + bool "Show packages that require graphics support (local or remote)" + default n + + config BUILD_PATENTED + default y + bool "Compile with support for patented functionality" + help + When this option is disabled, software which provides patented functionality + will not be built. In case software provides optional support for patented + functionality, this optional support will get disabled for this package. + + config BUILD_NLS + default n + bool "Compile with full language support" + help + When this option is enabled, packages are built with the full versions of + iconv and GNU gettext instead of the default OpenWrt stubs. If uClibc is + used, it is also built with locale support. + + config SHADOW_PASSWORDS + bool + prompt "Enable shadow password support" + default y + help + Enable shadow password support. + + config CLEAN_IPKG + bool + prompt "Remove ipkg/opkg status data files in final images" + default n + help + This removes all ipkg/opkg status data files from the target directory + before building the root filesystem. + + config COLLECT_KERNEL_DEBUG + bool + prompt "Collect kernel debug information" + select KERNEL_DEBUG_INFO + default n + help + This collects debugging symbols from the kernel and all compiled modules. + Useful for release builds, so that kernel issues can be debugged offline + later. + + comment "Kernel build options" + + source "config/Config-kernel.in" + + comment "Package build options" + + config DEBUG + bool + prompt "Compile packages with debugging info" + default n + help + Adds -g3 to the CFLAGS. + + config IPV6 + bool + prompt "Enable IPv6 support in packages" + default y + help + Enable IPv6 support in packages (passes --enable-ipv6 to configure scripts). + + config PKG_BUILD_PARALLEL + bool + prompt "Compile certain packages parallelized" + default y + help + This adds a -jX option to certain packages that are known to behave well + for parallel build. By default, the package make processes use the main + jobserver, in which case this option only takes effect when you add -jX + to the make command. + + If you are unsure, select N. + + config PKG_BUILD_USE_JOBSERVER + bool + prompt "Use top-level make jobserver for packages" + depends on PKG_BUILD_PARALLEL + default y + help + This passes the main make process jobserver fds to package builds, + enabling full parallelization across different packages. + + Note that disabling this may overcommit CPU resources depending on the + -j level of the main make process, the number of package submake jobs + selected below and the number of actual CPUs present. + Example: If the main make is passed a -j4 and the submake -j + is also set to 4, we may end up with 16 parallel make processes + in the worst case. + + config PKG_BUILD_JOBS + int + prompt "Number of package submake jobs (2-512)" + range 2 512 + default 2 + depends on PKG_BUILD_PARALLEL && !PKG_BUILD_USE_JOBSERVER + help + The number of jobs (-jX) to pass to packages submake. + + config PKG_DEFAULT_PARALLEL + bool + prompt "Parallelize the default package build rule (May break build)" + depends on PKG_BUILD_PARALLEL + depends on BROKEN + default n + help + Always set the default package build rules to parallel build. + + WARNING: This may break build or kill your cat, as it builds packages + with multiple jobs that are probably not tested in a parallel build + environment. + + Only say Y if you don't mind fixing broken packages. Before reporting + build bugs, set this to N and re-run the build. + + comment "Stripping options" + + choice + prompt "Binary stripping method" + default USE_STRIP if EXTERNAL_TOOLCHAIN + default USE_STRIP if USE_GLIBC || USE_MUSL + default USE_SSTRIP + help + Select the binary stripping method you wish to use. + + config NO_STRIP + bool "none" + help + This will install unstripped binaries (useful for native + compiling/debugging). + + config USE_STRIP + bool "strip" + help + This will install binaries stripped using strip from binutils. + + + config USE_SSTRIP + bool "sstrip" + depends on !DEBUG + depends on !USE_GLIBC + help + This will install binaries stripped using sstrip. + endchoice + + config STRIP_ARGS + string + prompt "Strip arguments" + depends on USE_STRIP + default "--strip-unneeded --remove-section=.comment --remove-section=.note" if DEBUG + default "--strip-all" + help + Specifies arguments passed to the strip command when stripping binaries. + + config STRIP_KERNEL_EXPORTS + bool "Strip unnecessary exports from the kernel image" + help + Reduces kernel size by stripping unused kernel exports from the kernel + image. Note that this might make the kernel incompatible with any kernel + modules that were not selected at the time the kernel image was created. + + config USE_MKLIBS + bool "Strip unnecessary functions from libraries" + help + Reduces libraries to only those functions that are necessary for using all + selected packages (including those selected as ). Note that this will + make the system libraries incompatible with most of the packages that are + not selected during the build process. + + choice + prompt "Preferred standard C++ library" + default USE_LIBSTDCXX if USE_GLIBC + default USE_UCLIBCXX + help + Select the preferred standard C++ library for all packages that support this. + + config USE_UCLIBCXX + bool "uClibc++" + + config USE_LIBSTDCXX + bool "libstdc++" + endchoice + + comment "Hardening build options" + + config PKG_CHECK_FORMAT_SECURITY + bool + prompt "Enable gcc format-security" + default n + help + Add -Wformat -Werror=format-security to the CFLAGS. You can disable + this per package by adding PKG_CHECK_FORMAT_SECURITY:=0 in the package + Makefile. + + choice + prompt "User space Stack-Smashing Protection" + default PKG_CC_STACKPROTECTOR_NONE + help + Enable GCC Stack Smashing Protection (SSP) for userspace applications + config PKG_CC_STACKPROTECTOR_NONE + bool "None" + config PKG_CC_STACKPROTECTOR_REGULAR + bool "Regular" + select SSP_SUPPORT + depends on KERNEL_CC_STACKPROTECTOR_REGULAR + config PKG_CC_STACKPROTECTOR_STRONG + bool "Strong" + select SSP_SUPPORT + depends on GCC_VERSION_4_9_LINARO + depends on KERNEL_CC_STACKPROTECTOR_STRONG + endchoice + + choice + prompt "Kernel space Stack-Smashing Protection" + default KERNEL_CC_STACKPROTECTOR_NONE + help + Enable GCC Stack-Smashing Protection (SSP) for the kernel + config KERNEL_CC_STACKPROTECTOR_NONE + bool "None" + config KERNEL_CC_STACKPROTECTOR_REGULAR + bool "Regular" + config KERNEL_CC_STACKPROTECTOR_STRONG + depends on GCC_VERSION_4_9_LINARO + bool "Strong" + endchoice + + choice + prompt "Enable buffer-overflows detection (FORTIFY_SOURCE)" + help + Enable the _FORTIFY_SOURCE macro which introduces additional + checks to detect buffer-overflows in the following standard library + functions: memcpy, mempcpy, memmove, memset, strcpy, stpcpy, + strncpy, strcat, strncat, sprintf, vsprintf, snprintf, vsnprintf, + gets. "Conservative" (_FORTIFY_SOURCE set to 1) only introduces + checks that shouldn't change the behavior of conforming programs, + while "aggressive" (_FORTIFY_SOURCES set to 2) some more checking is + added, but some conforming programs might fail. + config PKG_FORTIFY_SOURCE_NONE + bool "None" + config PKG_FORTIFY_SOURCE_1 + bool "Conservative" + config PKG_FORTIFY_SOURCE_2 + bool "Aggressive" + endchoice + + choice + prompt "Enable RELRO protection" + help + Enable a link-time protection known as RELRO (Relocation Read Only) + which helps to protect from certain type of exploitation techniques + altering the content of some ELF sections. "Partial" RELRO makes the + .dynamic section not writeable after initialization, introducing + almost no performance penalty, while "full" RELRO also marks the GOT + as read-only at the cost of initializing all of it at startup. + config PKG_RELRO_NONE + bool "None" + config PKG_RELRO_PARTIAL + bool "Partial" + config PKG_RELRO_FULL + bool "Full" + endchoice + +endmenu diff --git a/config/Config-devel.in b/config/Config-devel.in new file mode 100644 index 0000000..d096c18 --- /dev/null +++ b/config/Config-devel.in @@ -0,0 +1,111 @@ +# Copyright (C) 2006-2013 OpenWrt.org +# +# This is free software, licensed under the GNU General Public License v2. +# See /LICENSE for more information. +# + +menuconfig DEVEL + bool "Advanced configuration options (for developers)" + default n + + config BROKEN + bool "Show broken platforms / packages" if DEVEL + default n + + config BINARY_FOLDER + string "Binary folder" if DEVEL + default "" + help + Store built firmware images and filesystem images in this directory. + If not set, uses './bin/$(BOARD)' + + config DOWNLOAD_FOLDER + string "Download folder" if DEVEL + default "" + help + Store downloaded source bundles in this directory. + If not set then defaults to './dl', which is removed by operations such as + 'git clean -xdf' or 'make distclean'. + This option is useful if you have a low bandwidth Internet connection, and by + setting a path outside the OpenWrt tree downloads will be saved. + + config LOCALMIRROR + string "Local mirror for source packages" if DEVEL + default "" + + config AUTOREBUILD + bool "Automatic rebuild of packages" if DEVEL + default y + help + Automatically rebuild packages when their files change. + + config BUILD_SUFFIX + string "Build suffix to append to the target BUILD_DIR variable" if DEVEL + default "" + help + Build suffix to append to the BUILD_DIR variable, i.e: './build_dir/{target-build-dir}_$(BUILD_SUFFIX)'. + This allows you to switch to a different .config whilst retaining all the build + objects generated by the first .config + + config TARGET_ROOTFS_DIR + string "Override the default TARGET_ROOTFS_DIR variable" if DEVEL + default "" + help + Override the default TARGET_ROOTFS_DIR variable content $(BUILD_DIR) with + custom path. Use this option to re-define the location of the target + root filesystem directory. + + config CCACHE + bool "Use ccache" if DEVEL + default n + help + Compiler cache; see http://ccache.samba.org/. + + config EXTERNAL_KERNEL_TREE + string "Use external kernel tree" if DEVEL + default "" + + config KERNEL_GIT_CLONE_URI + string "Enter git repository to clone" if DEVEL + default "" + help + Enter the full git repository path i.e.: + git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git + This will create a git clone of the kernel in your build directory. + + config KERNEL_GIT_LOCAL_REPOSITORY + string "Enter path to local reference repository" if DEVEL + depends on (KERNEL_GIT_CLONE_URI != "") + default "" + help + Enter a full pathname to a local reference git repository. + In this instance, the --reference option of git clone will + be used thus creating a quick local clone of your repo. + + config KERNEL_GIT_BRANCH + string "Enter git branch to clone" if DEVEL + depends on (KERNEL_GIT_CLONE_URI != "") + default "" + help + Enter the branch name to checkout after cloning the git repository. + In this instance, the --branch option of git clone will be used. + If unused, the clone's repository HEAD will be checked-out. + + config BUILD_LOG + bool "Enable log files during build process" if DEVEL + help + If enabled, log files will be written to the ./log directory. + + config SRC_TREE_OVERRIDE + bool "Enable package source tree override" if DEVEL + help + If enabled, you can force a package to use a git tree as source + code instead of the normal tarball. Create a symlink 'git-src' + in the package directory, pointing to the .git tree that you want + to pull the source code from. + + config EXTRA_OPTIMIZATION + string "Additional compiler options" if DEVEL + default "-fno-caller-saves" + help + Extra target-independent optimizations to use when building for the target. diff --git a/config/Config-images.in b/config/Config-images.in new file mode 100644 index 0000000..a60dd50 --- /dev/null +++ b/config/Config-images.in @@ -0,0 +1,315 @@ +# Copyright (C) 2006-2013 OpenWrt.org +# +# This is free software, licensed under the GNU General Public License v2. +# See /LICENSE for more information. +# + +menu "Target Images" + + menuconfig TARGET_ROOTFS_INITRAMFS + bool "ramdisk" + default y if USES_INITRAMFS + help + Embed the root filesystem into the kernel (initramfs). + + choice + prompt "Compression" + default TARGET_INITRAMFS_COMPRESSION_LZMA if TARGET_ar71xx + default TARGET_INITRAMFS_COMPRESSION_LZMA if TARGET_ramips + default TARGET_INITRAMFS_COMPRESSION_NONE + depends on TARGET_ROOTFS_INITRAMFS + help + Select ramdisk compression. + + config TARGET_INITRAMFS_COMPRESSION_NONE + bool "none" + + config TARGET_INITRAMFS_COMPRESSION_GZIP + bool "gzip" + + config TARGET_INITRAMFS_COMPRESSION_BZIP2 + bool "bzip2" + + config TARGET_INITRAMFS_COMPRESSION_LZMA + bool "lzma" + + config TARGET_INITRAMFS_COMPRESSION_LZO + bool "lzo" + + config TARGET_INITRAMFS_COMPRESSION_LZ4 + bool "lz4" + + config TARGET_INITRAMFS_COMPRESSION_XZ + bool "xz" + endchoice + + config EXTERNAL_CPIO + string + prompt "Use external cpio" if TARGET_ROOTFS_INITRAMFS + default "" + help + Kernel uses specified external cpio as INITRAMFS_SOURCE. + + comment "Root filesystem archives" + + config TARGET_ROOTFS_CPIOGZ + bool "cpio.gz" + default y if USES_CPIOGZ + help + Build a compressed cpio archive of the root filesystem. + + config TARGET_ROOTFS_TARGZ + bool "tar.gz" + default y if USES_TARGZ + help + Build a compressed tar archive of the root filesystem. + + comment "Root filesystem images" + + menuconfig TARGET_ROOTFS_EXT4FS + bool "ext4" + default y if USES_EXT4 + help + Build an ext4 root filesystem. + + config TARGET_EXT4_MAXINODE + int "Maximum number of inodes in root filesystem" + depends on TARGET_ROOTFS_EXT4FS + default 6000 + help + Select the maximum number of inodes in the root filesystem. + + config TARGET_EXT4_RESERVED_PCT + int "Percentage of reserved blocks in root filesystem" + depends on TARGET_ROOTFS_EXT4FS + default 0 + help + Select the percentage of reserved blocks in the root filesystem. + + choice + prompt "Root filesystem block size" + default TARGET_EXT4_BLOCKSIZE_4K + depends on TARGET_ROOTFS_EXT4FS + help + Select the block size of the root filesystem. + + config TARGET_EXT4_BLOCKSIZE_4K + bool "4k" + + config TARGET_EXT4_BLOCKSIZE_2K + bool "2k" + + config TARGET_EXT4_BLOCKSIZE_1K + bool "1k" + endchoice + + config TARGET_EXT4_BLOCKSIZE + int + default 4096 if TARGET_EXT4_BLOCKSIZE_4K + default 2048 if TARGET_EXT4_BLOCKSIZE_2K + default 1024 if TARGET_EXT4_BLOCKSIZE_1K + depends on TARGET_ROOTFS_EXT4FS + + config TARGET_EXT4_JOURNAL + bool "Create a journaling filesystem" + depends on TARGET_ROOTFS_EXT4FS + default n + help + Create an ext4 filesystem with a journal. + + config TARGET_ROOTFS_ISO + bool "iso" + default n + depends on TARGET_x86_generic + help + Create a bootable ISO image. + + config TARGET_ROOTFS_JFFS2 + bool "jffs2" + default y if USES_JFFS2 + help + Build a JFFS2 root filesystem. + + config TARGET_ROOTFS_JFFS2_NAND + bool "jffs2 for NAND" + default y if USES_JFFS2_NAND + depends on USES_JFFS2_NAND + help + Build a JFFS2 root filesystem for NAND flash. + + menuconfig TARGET_ROOTFS_SQUASHFS + bool "squashfs" + default y if USES_SQUASHFS + help + Build a squashfs-lzma root filesystem. + + config TARGET_SQUASHFS_BLOCK_SIZE + int "Block size (in KiB)" + depends on TARGET_ROOTFS_SQUASHFS + default 64 if LOW_MEMORY_FOOTPRINT + default 256 + + menuconfig TARGET_ROOTFS_UBIFS + bool "ubifs" + default y if USES_UBIFS + depends on USES_UBIFS + help + Build a UBIFS root filesystem. + + choice + prompt "compression" + default TARGET_UBIFS_COMPRESSION_ZLIB + depends on TARGET_ROOTFS_UBIFS + help + Select compression type + + config TARGET_UBIFS_COMPRESSION_NONE + bool "none" + + config TARGET_UBIFS_COMPRESSION_LZO + bool "lzo" + + config TARGET_UBIFS_COMPRESSION_ZLIB + bool "zlib" + endchoice + + config TARGET_UBIFS_FREE_SPACE_FIXUP + bool "free space fixup" if TARGET_ROOTFS_UBIFS + default y + help + The filesystem free space has to be fixed up on first mount. + + config TARGET_UBIFS_JOURNAL_SIZE + string + prompt "journal size" if TARGET_ROOTFS_UBIFS + default "" + + config GRUB_IMAGES + bool "Build GRUB images (Linux x86 or x86_64 host only)" + depends on TARGET_x86_64 || (TARGET_x86 && !TARGET_x86_rdc) + depends on TARGET_ROOTFS_EXT4FS || TARGET_ROOTFS_ISO || TARGET_ROOTFS_JFFS2 || TARGET_ROOTFS_SQUASHFS + select PACKAGE_grub2 + default y + + config GRUB_CONSOLE + bool "Use Console Terminal (in addition to Serial)" + depends on GRUB_IMAGES + default n if (TARGET_x86_generic_Soekris45xx || TARGET_x86_generic_Soekris48xx || TARGET_x86_net5501 || TARGET_x86_geos || TARGET_x86_alix2) + default y + + config GRUB_SERIAL + string "Serial port device" + depends on GRUB_IMAGES + default "hvc0" if TARGET_x86_xen_domu + default "ttyS0" if ! TARGET_x86_xen_domu + + config GRUB_BAUDRATE + int "Serial port baud rate" + depends on GRUB_IMAGES + default 38400 if TARGET_x86_generic + default 38400 if TARGET_x86_geode + default 115200 + + config GRUB_BOOTOPTS + string "Extra kernel boot options" + depends on GRUB_IMAGES + default "xencons=hvc" if TARGET_x86_xen_domu + help + If you don't know, just leave it blank. + + config GRUB_TIMEOUT + string "Seconds to wait before booting the default entry" + depends on GRUB_IMAGES + default "5" + help + If you don't know, 5 seconds is a reasonable default. + + config VDI_IMAGES + bool "Build VirtualBox image files (VDI)" + depends on TARGET_x86 || TARGET_x86_64 + select GRUB_IMAGES + select TARGET_IMAGES_PAD + select PACKAGE_kmod-e1000 + + config VMDK_IMAGES + bool "Build VMware image files (VMDK)" + depends on TARGET_x86 || TARGET_x86_64 + select GRUB_IMAGES + select TARGET_IMAGES_PAD + select PACKAGE_kmod-e1000 + + config TARGET_IMAGES_PAD + bool "Pad images to filesystem size (for JFFS2)" + depends on GRUB_IMAGES + + config TARGET_IMAGES_GZIP + bool "GZip images" + depends on TARGET_IMAGES_PAD || TARGET_ROOTFS_EXT4FS + default y + + comment "Image Options" + + source "target/linux/*/image/Config.in" + + config TARGET_KERNEL_PARTSIZE + int "Kernel partition size (in MB)" + depends on GRUB_IMAGES + default 4 + + config TARGET_ROOTFS_PARTSIZE + int "Root filesystem partition size (in MB)" + depends on GRUB_IMAGES || TARGET_ROOTFS_EXT4FS || TARGET_rb532 + default 48 + help + Select the root filesystem partition size. + + config TARGET_ROOTFS_PARTNAME + string "Root partition on target device" + depends on GRUB_IMAGES + help + Override the root partition on the final device. If left empty, + it will be mounted by PARTUUID which makes the kernel find the + appropriate disk automatically. + + + menuconfig TARGET_ROOTFS_INCLUDE_KERNEL + bool "Include kernel in root filesystem" + depends on TARGET_ROOTFS_UBIFS || TARGET_ROOTFS_EXT4FS + default n + help + Include the kernel image in the rootfs. Typically, the image is placed + below /boot. + + config TARGET_ROOTFS_INCLUDE_UIMAGE + bool "include uImage" if TARGET_ROOTFS_INCLUDE_KERNEL + default y + help + This option might not apply to all targets. Make sure + to check target/linux//image/Makefile to + see if this option will have any effect. + + config TARGET_ROOTFS_INCLUDE_ZIMAGE + bool "include zImage" if TARGET_ROOTFS_INCLUDE_KERNEL + default y + help + This option might not apply to all targets. Make sure + to check target/linux//image/Makefile to + see if this option will have any effect. + + config TARGET_ROOTFS_INCLUDE_FIT + bool "include FIT" if TARGET_ROOTFS_INCLUDE_KERNEL + default y + help + This option might not apply to all targets. Make sure + to check target/linux//image/Makefile to + see if this option will have any effect. + + config TARGET_ROOTFS_INCLUDE_DTB + bool "Include DTB in root filesystem" + depends on USES_DEVICETREE && (TARGET_ROOTFS_UBIFS || TARGET_ROOTFS_EXT4FS) + default n + help + Include the device tree blob file(s) in the rootfs. Typically the DTBs + are placed below /boot. + +endmenu diff --git a/config/Config-kernel.in b/config/Config-kernel.in new file mode 100644 index 0000000..cc8df5a --- /dev/null +++ b/config/Config-kernel.in @@ -0,0 +1,546 @@ +# Copyright (C) 2006-2014 OpenWrt.org +# +# This is free software, licensed under the GNU General Public License v2. +# See /LICENSE for more information. +# + +config KERNEL_PRINTK + bool "Enable support for printk" + default y + +config KERNEL_CRASHLOG + bool "Crash logging" + depends on !(arm || powerpc || sparc || TARGET_uml) + default y + +config KERNEL_SWAP + bool "Support for paging of anonymous memory (swap)" + default y + +config KERNEL_DEBUG_FS + bool "Compile the kernel with debug filesystem enabled" + default y + help + debugfs is a virtual file system that kernel developers use to put + debugging files into. Enable this option to be able to read and + write to these files. Many common debugging facilities, such as + ftrace, require the existence of debugfs. + +config KERNEL_PERF_EVENTS + bool + default n + +config KERNEL_PROFILING + bool "Compile the kernel with profiling enabled" + default n + select KERNEL_PERF_EVENTS + help + Enable the extended profiling support mechanisms used by profilers such + as OProfile. + +config KERNEL_KALLSYMS + bool "Compile the kernel with symbol table information" + default y + help + This will give you more information in stack traces from kernel oopses. + +config KERNEL_FTRACE + bool "Compile the kernel with tracing support" + depends on !TARGET_uml + default n + +config KERNEL_FTRACE_SYSCALLS + bool "Trace system calls" + depends on KERNEL_FTRACE + default n + +config KERNEL_ENABLE_DEFAULT_TRACERS + bool "Trace process context switches and events" + depends on KERNEL_FTRACE + default n + +config KERNEL_FUNCTION_TRACER + bool "Function tracer" + depends on KERNEL_FTRACE + default n + +config KERNEL_FUNCTION_GRAPH_TRACER + bool "Function graph tracer" + depends on KERNEL_FUNCTION_TRACER + default n + +config KERNEL_DYNAMIC_FTRACE + bool "Enable/disable function tracing dynamically" + depends on KERNEL_FUNCTION_TRACER + default n + +config KERNEL_FUNCTION_PROFILER + bool "Function profiler" + depends on KERNEL_FUNCTION_TRACER + default n + +config KERNEL_DEBUG_KERNEL + bool + default n + +config KERNEL_DEBUG_INFO + bool "Compile the kernel with debug information" + default y + select KERNEL_DEBUG_KERNEL + help + This will compile your kernel and modules with debug information. + +config KERNEL_DEBUG_LL_UART_NONE + bool + default n + depends on arm + +config KERNEL_DEBUG_LL + bool + default n + depends on arm + select KERNEL_DEBUG_LL_UART_NONE + help + ARM low level debugging. + +config KERNEL_DYNAMIC_DEBUG + bool "Compile the kernel with dynamic printk" + select KERNEL_DEBUG_FS + default n + help + Compiles debug level messages into the kernel, which would not + otherwise be available at runtime. These messages can then be + enabled/disabled based on various levels of scope - per source file, + function, module, format string, and line number. This mechanism + implicitly compiles in all pr_debug() and dev_dbg() calls, which + enlarges the kernel text size by about 2%. + +config KERNEL_EARLY_PRINTK + bool "Compile the kernel with early printk" + default y if TARGET_bcm53xx + default n + depends on arm + select KERNEL_DEBUG_KERNEL + select KERNEL_DEBUG_LL if arm + help + Compile the kernel with early printk support. This is only useful for + debugging purposes to send messages over the serial console in early boot. + Enable this to debug early boot problems. + +config KERNEL_KPROBES + bool "Compile the kernel with kprobes support" + default n + select KERNEL_FTRACE + select KERNEL_PERF_EVENTS + help + Compiles the kernel with KPROBES support, which allows you to trap + at almost any kernel address and execute a callback function. + register_kprobe() establishes a probepoint and specifies the + callback. Kprobes is useful for kernel debugging, non-intrusive + instrumentation and testing. + If in doubt, say "N". + +config KERNEL_KPROBE_EVENT + bool + default y if KERNEL_KPROBES + +config KERNEL_AIO + bool "Compile the kernel with asynchronous IO support" + default n + +config KERNEL_DIRECT_IO + bool "Compile the kernel with direct IO support" + default n + +config KERNEL_FHANDLE + bool "Compile the kernel with support for fhandle syscalls" + default n + +config KERNEL_FANOTIFY + bool "Compile the kernel with modern file notification support" + default n + +config KERNEL_BLK_DEV_BSG + bool "Compile the kernel with SCSI generic v4 support for any block device" + default n + +config KERNEL_MAGIC_SYSRQ + bool "Compile the kernel with SysRq support" + default y + +config KERNEL_COREDUMP + bool + +config KERNEL_ELF_CORE + bool "Enable process core dump support" + select KERNEL_COREDUMP + default y + +config KERNEL_PROVE_LOCKING + bool "Enable kernel lock checking" + select KERNEL_DEBUG_KERNEL + default n + +config KERNEL_PRINTK_TIME + bool "Enable printk timestamps" + default y + +config KERNEL_SLUB_DEBUG + bool + +config KERNEL_SLUB_DEBUG_ON + bool + +config KERNEL_SLABINFO + select KERNEL_SLUB_DEBUG + select KERNEL_SLUB_DEBUG_ON + bool "Enable /proc slab debug info" + +config KERNEL_PROC_PAGE_MONITOR + bool "Enable /proc page monitoring" + +config KERNEL_RELAY + bool + +config KERNEL_KEXEC + bool "Enable kexec support" + +config USE_RFKILL + bool "Enable rfkill support" + default RFKILL_SUPPORT + +config USE_SPARSE + bool "Enable sparse check during kernel build" + default n + +config KERNEL_DEVTMPFS + bool "Compile the kernel with device tmpfs enabled" + default n + help + devtmpfs is a simple, kernel-managed /dev filesystem. The kernel creates + devices nodes for all registered devices ti simplify boot, but leaves more + complex tasks to userspace (e.g. udev). + +if KERNEL_DEVTMPFS + + config KERNEL_DEVTMPFS_MOUNT + bool "Automatically mount devtmpfs after root filesystem is mounted" + default n + +endif + +# +# CGROUP support symbols +# + +config KERNEL_CGROUPS + bool "Enable kernel cgroups" + default n + +if KERNEL_CGROUPS + + config KERNEL_CGROUP_DEBUG + bool "Example debug cgroup subsystem" + default n + help + This option enables a simple cgroup subsystem that + exports useful debugging information about the cgroups + framework. + + config KERNEL_FREEZER + bool + default y if KERNEL_CGROUP_FREEZER + + config KERNEL_CGROUP_FREEZER + bool "Freezer cgroup subsystem" + default y + help + Provides a way to freeze and unfreeze all tasks in a + cgroup. + + config KERNEL_CGROUP_DEVICE + bool "Device controller for cgroups" + default y + help + Provides a cgroup implementing whitelists for devices which + a process in the cgroup can mknod or open. + + config KERNEL_CPUSETS + bool "Cpuset support" + default n + help + This option will let you create and manage CPUSETs which + allow dynamically partitioning a system into sets of CPUs and + Memory Nodes and assigning tasks to run only within those sets. + This is primarily useful on large SMP or NUMA systems. + + config KERNEL_PROC_PID_CPUSET + bool "Include legacy /proc//cpuset file" + default n + depends on KERNEL_CPUSETS + + config KERNEL_CGROUP_CPUACCT + bool "Simple CPU accounting cgroup subsystem" + default n + help + Provides a simple Resource Controller for monitoring the + total CPU consumed by the tasks in a cgroup. + + config KERNEL_RESOURCE_COUNTERS + bool "Resource counters" + default n + help + This option enables controller independent resource accounting + infrastructure that works with cgroups. + + config KERNEL_MM_OWNER + bool + default y if KERNEL_MEMCG + + config KERNEL_MEMCG + bool "Memory Resource Controller for Control Groups" + default n + depends on KERNEL_RESOURCE_COUNTERS + help + Provides a memory resource controller that manages both anonymous + memory and page cache. (See Documentation/cgroups/memory.txt) + + Note that setting this option increases fixed memory overhead + associated with each page of memory in the system. By this, + 20(40)bytes/PAGE_SIZE on 32(64)bit system will be occupied by memory + usage tracking struct at boot. Total amount of this is printed out + at boot. + + Only enable when you're ok with these tradeoffs and really + sure you need the memory resource controller. Even when you enable + this, you can set "cgroup_disable=memory" at your boot option to + disable memory resource controller and you can avoid overheads + (but lose benefits of memory resource controller). + + This config option also selects MM_OWNER config option, which + could in turn add some fork/exit overhead. + + config KERNEL_MEMCG_SWAP + bool "Memory Resource Controller Swap Extension" + default n + depends on KERNEL_MEMCG + help + Add swap management feature to memory resource controller. When you + enable this, you can limit mem+swap usage per cgroup. In other words, + when you disable this, memory resource controller has no cares to + usage of swap...a process can exhaust all of the swap. This extension + is useful when you want to avoid exhaustion swap but this itself + adds more overheads and consumes memory for remembering information. + Especially if you use 32bit system or small memory system, please + be careful about enabling this. When memory resource controller + is disabled by boot option, this will be automatically disabled and + there will be no overhead from this. Even when you set this config=y, + if boot option "swapaccount=0" is set, swap will not be accounted. + Now, memory usage of swap_cgroup is 2 bytes per entry. If swap page + size is 4096bytes, 512k per 1Gbytes of swap. + + config KERNEL_MEMCG_SWAP_ENABLED + bool "Memory Resource Controller Swap Extension enabled by default" + default n + depends on KERNEL_MEMCG_SWAP + help + Memory Resource Controller Swap Extension comes with its price in + a bigger memory consumption. General purpose distribution kernels + which want to enable the feature but keep it disabled by default + and let the user enable it by swapaccount boot command line + parameter should have this option unselected. + + Those who want to have the feature enabled by default should + select this option (if, for some reason, they need to disable it, + then swapaccount=0 does the trick). + + + config KERNEL_MEMCG_KMEM + bool "Memory Resource Controller Kernel Memory accounting (EXPERIMENTAL)" + default n + depends on KERNEL_MEMCG + help + The Kernel Memory extension for Memory Resource Controller can limit + the amount of memory used by kernel objects in the system. Those are + fundamentally different from the entities handled by the standard + Memory Controller, which are page-based, and can be swapped. Users of + the kmem extension can use it to guarantee that no group of processes + will ever exhaust kernel resources alone. + + config KERNEL_CGROUP_PERF + bool "Enable perf_event per-cpu per-container group (cgroup) monitoring" + select KERNEL_PERF_EVENTS + default n + help + This option extends the per-cpu mode to restrict monitoring to + threads which belong to the cgroup specified and run on the + designated cpu. + + menuconfig KERNEL_CGROUP_SCHED + bool "Group CPU scheduler" + default n + help + This feature lets CPU scheduler recognize task groups and control CPU + bandwidth allocation to such task groups. It uses cgroups to group + tasks. + + if KERNEL_CGROUP_SCHED + + config KERNEL_FAIR_GROUP_SCHED + bool "Group scheduling for SCHED_OTHER" + default n + + config KERNEL_CFS_BANDWIDTH + bool "CPU bandwidth provisioning for FAIR_GROUP_SCHED" + default n + depends on KERNEL_FAIR_GROUP_SCHED + help + This option allows users to define CPU bandwidth rates (limits) for + tasks running within the fair group scheduler. Groups with no limit + set are considered to be unconstrained and will run with no + restriction. + See tip/Documentation/scheduler/sched-bwc.txt for more information. + + config KERNEL_RT_GROUP_SCHED + bool "Group scheduling for SCHED_RR/FIFO" + default n + help + This feature lets you explicitly allocate real CPU bandwidth + to task groups. If enabled, it will also make it impossible to + schedule realtime tasks for non-root users until you allocate + realtime bandwidth for them. + + endif + + config KERNEL_BLK_CGROUP + bool "Block IO controller" + default y + help + Generic block IO controller cgroup interface. This is the common + cgroup interface which should be used by various IO controlling + policies. + + Currently, CFQ IO scheduler uses it to recognize task groups and + control disk bandwidth allocation (proportional time slice allocation) + to such task groups. It is also used by bio throttling logic in + block layer to implement upper limit in IO rates on a device. + + This option only enables generic Block IO controller infrastructure. + One needs to also enable actual IO controlling logic/policy. For + enabling proportional weight division of disk bandwidth in CFQ, set + CONFIG_CFQ_GROUP_IOSCHED=y; for enabling throttling policy, set + CONFIG_BLK_DEV_THROTTLING=y. + + config KERNEL_DEBUG_BLK_CGROUP + bool "Enable Block IO controller debugging" + default n + depends on KERNEL_BLK_CGROUP + help + Enable some debugging help. Currently it exports additional stat + files in a cgroup which can be useful for debugging. + + config KERNEL_NET_CLS_CGROUP + bool "Control Group Classifier" + default y + + config KERNEL_NETPRIO_CGROUP + bool "Network priority cgroup" + default y + +endif + +# +# Namespace support symbols +# + +config KERNEL_NAMESPACES + bool "Enable kernel namespaces" + default n + +if KERNEL_NAMESPACES + + config KERNEL_UTS_NS + bool "UTS namespace" + default y + help + In this namespace, tasks see different info provided + with the uname() system call. + + config KERNEL_IPC_NS + bool "IPC namespace" + default y + help + In this namespace, tasks work with IPC ids which correspond to + different IPC objects in different namespaces. + + config KERNEL_USER_NS + bool "User namespace (EXPERIMENTAL)" + default y + help + This allows containers, i.e. vservers, to use user namespaces + to provide different user info for different servers. + + config KERNEL_PID_NS + bool "PID Namespaces" + default y + help + Support process id namespaces. This allows having multiple + processes with the same pid as long as they are in different + pid namespaces. This is a building block of containers. + + config KERNEL_NET_NS + bool "Network namespace" + default y + help + Allow user space to create what appear to be multiple instances + of the network stack. + +endif + +# +# LXC related symbols +# + +config KERNEL_LXC_MISC + bool "Enable miscellaneous LXC related options" + default n + +if KERNEL_LXC_MISC + + config KERNEL_DEVPTS_MULTIPLE_INSTANCES + bool "Support multiple instances of devpts" + default y + help + Enable support for multiple instances of devpts filesystem. + If you want to have isolated PTY namespaces (eg: in containers), + say Y here. Otherwise, say N. If enabled, each mount of devpts + filesystem with the '-o newinstance' option will create an + independent PTY namespace. + + config KERNEL_POSIX_MQUEUE + bool "POSIX Message Queues" + default y + help + POSIX variant of message queues is a part of IPC. In POSIX message + queues every message has a priority which decides about succession + of receiving it by a process. If you want to compile and run + programs written e.g. for Solaris with use of its POSIX message + queues (functions mq_*) say Y here. + + POSIX message queues are visible as a filesystem called 'mqueue' + and can be mounted somewhere if you want to do filesystem + operations on message queues. + +endif + +config KERNEL_SECCOMP_FILTER + bool + default n + +config KERNEL_SECCOMP + bool "Enable seccomp support" + depends on !(TARGET_uml) + select KERNEL_SECCOMP_FILTER + default n + help + Build kernel with support for seccomp. diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..421e6d3 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,15 @@ +*.log +*.aux +*.toc +*.out +*.lg +*.dvi +*.idv +*.4ct +*.4tc +*.xref +*.tmp +*.dvi +*.html +*.css +*.pdf diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..c113d62 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,48 @@ +ifeq ($(TOPDIR),) + TOPDIR:=${CURDIR}/.. +endif +PKG_NAME=docs + +all: compile + +include $(TOPDIR)/rules.mk +include $(INCLUDE_DIR)/prereq.mk + +MAIN = openwrt.tex +DEPS = $(MAIN) Makefile config.tex network.tex network-scripts.tex network-scripts.tex wireless.tex build.tex adding.tex bugs.tex debugging.tex $(TMP_DIR)/.prereq-docs + +compile: $(TMP_DIR)/.prereq-docs + $(NO_TRACE_MAKE) cleanup + latex $(MAIN) + $(NO_TRACE_MAKE) openwrt.pdf openwrt.html + $(NO_TRACE_MAKE) cleanup + +$(TMP_DIR)/.prereq-docs: + mkdir -p $(TMP_DIR) + $(NO_TRACE_MAKE) prereq + touch $@ + +openwrt.html: $(DEPS) + htlatex $(MAIN) + +openwrt.pdf: $(DEPS) + pdflatex $(MAIN) + +clean: cleanup + rm -f openwrt.pdf openwrt.html openwrt.css + +cleanup: FORCE + rm -f *.log *.aux *.toc *.out *.lg *.dvi *.idv *.4ct *.4tc *.xref *.tmp *.dvi + +$(eval $(call RequireCommand,latex, \ + You need to install LaTeX to build the OpenWrt documentation \ +)) +$(eval $(call RequireCommand,pdflatex, \ + You need to install PDFLaTeX to build the OpenWrt documentation \ +)) +$(eval $(call RequireCommand,htlatex, \ + You need to install tex4ht to build the OpenWrt documentation \ +)) + +FORCE: +.PHONY: FORCE diff --git a/docs/adding.tex b/docs/adding.tex new file mode 100644 index 0000000..97547ac --- /dev/null +++ b/docs/adding.tex @@ -0,0 +1,590 @@ +Linux is now one of the most widespread operating system for embedded devices due +to its openess as well as the wide variety of platforms it can run on. Many +manufacturer actually use it in firmware you can find on many devices: DVB-T +decoders, routers, print servers, DVD players ... Most of the time the stock +firmware is not really open to the consumer, even if it uses open source software. + +You might be interested in running a Linux based firmware for your router for +various reasons: extending the use of a network protocol (such as IPv6), having +new features, new piece of software inside, or for security reasons. A fully +open-source firmware is de-facto needed for such applications, since you want to +be free to use this or that version of a particular reason, be able to correct a +particular bug. Few manufacturers do ship their routers with a Sample Development Kit, +that would allow you to create your own and custom firmware and most of the time, +when they do, you will most likely not be able to complete the firmware creation process. + +This is one of the reasons why OpenWrt and other firmware exists: providing a +version independent, and tools independent firmware, that can be run on various +platforms, known to be running Linux originally. + +\subsection{Which Operating System does this device run?} + +There is a lot of methods to ensure your device is running Linux. Some of them do +need your router to be unscrewed and open, some can be done by probing the device +using its external network interfaces. + +\subsubsection{Operating System fingerprinting and port scanning} + +A large bunch of tools over the Internet exists in order to let you do OS +fingerprinting, we will show here an example using \textbf{nmap}: + +\begin{Verbatim} +nmap -P0 -O +Starting Nmap 4.20 ( http://insecure.org ) at 2007-01-08 11:05 CET +Interesting ports on 192.168.2.1: +Not shown: 1693 closed ports +PORT STATE SERVICE +22/tcp open ssh +23/tcp open telnet +53/tcp open domain +80/tcp open http +MAC Address: 00:13:xx:xx:xx:xx (Cisco-Linksys) +Device type: broadband router +Running: Linksys embedded +OS details: Linksys WRT54GS v4 running OpenWrt w/Linux kernel 2.4.30 +Network Distance: 1 hop +\end{Verbatim} + +nmap is able to report whether your device uses a Linux TCP/IP stack, and if so, +will show you which Linux kernel version is probably runs. This report is quite +reliable and it can make the distinction between BSD and Linux TCP/IP stacks and others. + +Using the same tool, you can also do port scanning and service version discovery. +For instance, the following command will report which IP-based services are running +on the device, and which version of the service is being used: + +\begin{verbatim} +nmap -P0 -sV +Starting Nmap 4.20 ( http://insecure.org ) at 2007-01-08 11:06 CET +Interesting ports on 192.168.2.1: +Not shown: 1693 closed ports +PORT STATE SERVICE VERSION +22/tcp open ssh Dropbear sshd 0.48 (protocol 2.0) +23/tcp open telnet Busybox telnetd +53/tcp open domain ISC Bind dnsmasq-2.35 +80/tcp open http OpenWrt BusyBox httpd +MAC Address: 00:13:xx:xx:xx:xx (Cisco-Linksys) +Service Info: Device: WAP +\end{verbatim} + +The web server version, if identified, can be determining in knowing the Operating +System. For instance, the \textbf{BOA} web server is typical from devices running +an open-source Unix or Unix-like. + +\subsubsection{Wireless Communications Fingerprinting} + +Although this method is not really known and widespread, using a wireless scanner +to discover which OS your router or Access Point run can be used. We do not have +a clear example of how this could be achieved, but you will have to monitor raw +802.11 frames and compare them to a very similar device running a Linux based firmware. + +\subsubsection{Web server security exploits} + +The Linksys WRT54G was originally hacked by using a "ping bug" discovered in the +web interface. This tip has not been fixed for months by Linksys, allowing people +to enable the "boot\_wait" helper process via the web interface. Many web servers +used in firmwares are open source web server, thus allowing the code to be audited +to find an exploit. Once you know the web server version that runs on your device, +by using \textbf{nmap -sV} or so, you might be interested in using exploits to reach +shell access on your device. + +\subsubsection{Native Telnet/SSH access} + +Some firmwares might have restricted or unrestricted Telnet/SSH access, if so, +try to log in with the web interface login/password and see if you can type in +some commands. This is actually the case for some Broadcom BCM963xx based firmwares +such as the one in Neuf/Cegetel ISP routers, Club-Internet ISP CI-Box and many +others. Some commands, like \textbf{cat} might be left here and be used to +determine the Linux kernel version. + +\subsubsection{Analysing a binary firmware image} + +You are very likely to find a firmware binary image on the manufacturer website, +even if your device runs a proprietary operating system. If so, you can download +it and use an hexadecimal editor to find printable words such as \textbf{vmlinux}, +\textbf{linux}, \textbf{ramdisk}, \textbf{mtd} and others. + +Some Unix tools like \textbf{hexdump} or \textbf{strings} can be used to analyse +the firmware. Below there is an example with a binary firmware found other the Internet: + +\begin{verbatim} +hexdump -C | less (more) +00000000 46 49 52 45 32 2e 35 2e 30 00 00 00 00 00 00 00 |FIRE2.5.0.......| +00000010 00 00 00 00 31 2e 30 2e 30 00 00 00 00 00 00 00 |....1.0.0.......| +00000020 00 00 00 00 00 00 00 38 00 43 36 29 00 0a e6 dc |.......8.C6)..??| +00000030 54 49 44 45 92 89 54 66 1f 8b 08 08 f8 10 68 42 |TIDE..Tf....?.hB| +00000040 02 03 72 61 6d 64 69 73 6b 00 ec 7d 09 bc d5 d3 |..ramdisk.?}.???| +00000050 da ff f3 9b f7 39 7b ef 73 f6 19 3b 53 67 ea 44 |???.?9{?s?.;Sg?D| +\end{verbatim} + +Scroll over the firmware to find printable words that can be significant. + +\subsubsection{Amount of flash memory} + +Linux can hardly fit in a 2MB flash device, once you have opened the device and +located the flash chip, try to find its characteristics on the Internet. If +your flash chip is a 2MB or less device, your device is most likely to run a +proprietary OS such as WindRiver VxWorks, or a custom manufacturer OS like Zyxel ZynOS. + +OpenWrt does not currently run on devices which have 2MB or less of flash memory. +This limitation will probably not be worked around since those devices are most +of the time micro-routers, or Wireless Access Points, which are not the main +OpenWrt target. + +\subsubsection{Pluging a serial port} + +By using a serial port and a level shifter, you may reach the console that is being shown by the device +for debugging or flashing purposes. By analysing the output of this device, you can +easily notice if the device uses a Linux kernel or something different. + +\subsection{Finding and using the manufacturer SDK} + +Once you are sure your device run a Linux based firmware, you will be able to start +hacking on it. If the manufacturer respected the GPL, it will have released a Sample +Development Kit with the device. + +\subsubsection{GPL violations} + +Some manufacturers do release a Linux based binary firmware, with no sources at all. +The first step before doing anything is to read the license coming with your device, +then write them about this lack of Open Source code. If the manufacturer answers +you they do not have to release a SDK containing Open Source software, then we +recommend you get in touch with the gpl-violations.org community. + +You will find below a sample letter that can be sent to the manufacturer: + +\begin{verse} +Miss, Mister, + +I am using a , and I cannot find neither on your website nor on the +CD-ROM the open source software used to build or modify the firmware. + +In conformance to the GPL license, you have to release the following sources: + +\begin{itemize} +\item complete toolchain that made the kernel and applications be compiled (gcc, binutils, libc) +\item tools to build a custom firmware (mksquashfs, mkcramfs ...) +\item kernel sources with patches to make it run on this specific hardware, this does not include binary drivers +\end{itemize} + +Thank you very much in advance for your answer. + +Best regards, +\end{verse} + +\subsubsection{Using the SDK} + +Once the SDK is available, you are most likely not to be able to build a complete +or functional firmware using it, but parts of it, like only the kernel, or only +the root filesystem. Most manufacturers do not really care releasing a tool that +do work every time you uncompress and use it. + +You should anyway be able to use the following components: + +\begin{itemize} +\item kernel sources with more or less functional patches for your hardware +\item binary drivers linked or to be linked with the shipped kernel version +\item packages of the toolchain used to compile the whole firmware: gcc, binutils, libc or uClibc +\item binary tools to create a valid firmware image +\end{itemize} + +Your work can be divided into the following tasks: + +\begin{itemize} +\item create a clean patch of the hardware specific part of the linux kernel +\item spot potential kernel GPL violations especially on netfilter and USB stack stuff +\item make the binary drivers work, until there are open source drivers +\item use standard a GNU toolchain to make working executables +\item understand and write open source tools to generate a valid firmware image +\end{itemize} + +\subsubsection{Creating a hardware specific kernel patch} + +Most of the time, the kernel source that comes along with the SDK is not really +clean, and is not a standard Linux version, it also has architecture specific +fixes backported from the \textbf{CVS} or the \textbf{git} repository of the +kernel development trees. Anyway, some parts can be easily isolated and used as +a good start to make a vanilla kernel work your hardware. + +Some directories are very likely to have local modifications needed to make your +hardware be recognized and used under Linux. First of all, you need to find out +the linux kernel version that is used by your hardware, this can be found by +editing the \textbf{linux/Makefile} file. + +\begin{verbatim} +head -5 linux-2.x.x/Makefile +VERSION = 2 +PATCHLEVEL = x +SUBLEVEL = y +EXTRAVERSION = z +NAME=A fancy name +\end{verbatim} + +So now, you know that you have to download a standard kernel tarball at +\textbf{kernel.org} that matches the version being used by your hardware. + +Then you can create a \textbf{diff} file between the two trees, especially for the +following directories: + +\begin{verbatim} +diff -urN linux-2.x.x/arch/ linux-2.x.x-modified/arch/ > 01-architecture.patch +diff -urN linux-2.x.x/include/ linux-2.x.x-modified/include > 02-includes.patch +diff -urN linux-2.x.x/drivers/ linux-2.x.x-modified/drivers > 03-drivers.patch +\end{verbatim} + +This will constitute a basic set of three patches that are very likely to contain +any needed modifications that has been made to the stock Linux kernel to run on +your specific device. Of course, the content produced by the \textbf{diff -urN} +may not always be relevant, so that you have to clean up those patches to only +let the "must have" code into them. + +The first patch will contain all the code that is needed by the board to be +initialized at startup, as well as processor detection and other boot time +specific fixes. + +The second patch will contain all useful definitions for that board: addresses, +kernel granularity, redefinitions, processor family and features ... + +The third patch may contain drivers for: serial console, ethernet NIC, wireless +NIC, USB NIC ... Most of the time this patch contains nothing else than "glue" +code that has been added to make the binary driver work with the Linux kernel. +This code might not be useful if you plan on writing drivers from scratch for +this hardware. + +\subsubsection{Using the device bootloader} + +The bootloader is the first program that is started right after your device has +been powered on. This program, can be more or less sophisticated, some do let you +do network booting, USB mass storage booting ... The bootloader is device and +architecture specific, some bootloaders were designed to be universal such as +RedBoot or U-Boot so that you can meet those loaders on totally different +platforms and expect them to behave the same way. + +If your device runs a proprietary operating system, you are very likely to deal +with a proprietary boot loader as well. This may not always be a limitation, +some proprietary bootloaders can even have source code available (i.e : Broadcom CFE). + +According to the bootloader features, hacking on the device will be more or less +easier. It is very probable that the bootloader, even exotic and rare, has a +documentation somewhere over the Internet. In order to know what will be possible +with your bootloader and the way you are going to hack the device, look over the +following features : + +\begin{itemize} +\item does the bootloader allow net booting via bootp/DHCP/NFS or tftp +\item does the bootloader accept loading ELF binaries ? +\item does the bootloader have a kernel/firmware size limitation ? +\item does the bootloader expect a firmware format to be loaded with ? +\item are the loaded files executed from RAM or flash ? +\end{itemize} + +Net booting is something very convenient, because you will only have to set up network +booting servers on your development station, and keep the original firmware on the device +till you are sure you can replace it. This also prevents your device from being flashed, +and potentially bricked every time you want to test a modification on the kernel/filesystem. + +If your device needs to be flashed every time you load a firmware, the bootlader might +only accept a specific firmware format to be loaded, so that you will have to +understand the firmware format as well. + +\subsubsection{Making binary drivers work} + +As we have explained before, manufacturers do release binary drivers in their GPL +tarball. When those drivers are statically linked into the kernel, they become GPL +as well, fortunately or unfortunately, most of the drivers are not statically linked. +This anyway lets you a chance to dynamically link the driver with the current kernel +version, and try to make them work together. + +This is one of the most tricky and grey part of the fully open source projects. +Some drivers require few modifications to be working with your custom kernel, +because they worked with an earlier kernel, and few modifications have been made +to the kernel in-between those versions. This is for instance the case with the +binary driver of the Broadcom BCM43xx Wireless Chipsets, where only few differences +were made to the network interface structures. + +Some general principles can be applied no matter which kernel version is used in +order to make binary drivers work with your custom kernel: + +\begin{itemize} +\item turn on kernel debugging features such as: +\begin{itemize} +\item CONFIG\_DEBUG\_KERNEL +\item CONFIG\_DETECT\_SOFTLOCKUP +\item CONFIG\_DEBUG\_KOBJECT +\item CONFIG\_KALLSYMS +\item CONFIG\_KALLSYMS\_ALL +\end{itemize} +\item link binary drivers when possible to the current kernel version +\item try to load those binary drivers +\item catch the lockups and understand them +\end{itemize} + +Most of the time, loading binary drivers will fail, and generate a kernel oops. +You can know the last symbol the binary drivers attempted to use, and see in the +kernel headers file, if you do not have to move some structures field before or +after that symbol in order to keep compatibily with both the binary driver and +the stock kernel drivers. + +\subsubsection{Understanding the firmware format} + +You might want to understand the firmware format, even if you are not yet capable +of running a custom firmware on your device, because this is sometimes a blocking +part of the flashing process. + +A firmware format is most of the time composed of the following fields: + +\begin{itemize} +\item header, containing a firmware version and additional fields: Vendor, Hardware version ... +\item CRC32 checksum on either the whole file or just part of it +\item Binary and/or compressed kernel image +\item Binary and/or compressed root filesystem image +\item potential garbage +\end{itemize} + +Once you have figured out how the firmware format is partitioned, you will have +to write your own tool that produces valid firmware binaries. One thing to be very +careful here is the endianness of either the machine that produces the binary +firmware and the device that will be flashed using this binary firmware. + +\subsubsection{Writing a flash map driver} + +The flash map driver has an important role in making your custom firmware work +because it is responsible of mapping the correct flash regions and associated +rights to specific parts of the system such as: bootloader, kernel, user filesystem. + +Writing your own flash map driver is not really a hard task once you know how your +firmware image and flash is structured. You will find below a commented example +that covers the case of the device where the bootloader can pass to the kernel its partition plan. + +First of all, you need to make your flash map driver be visible in the kernel +configuration options, this can be done by editing the file \ +\textbf{linux/drivers/mtd/maps/Kconfig}: + +\begin{verbatim} +config MTD_DEVICE_FLASH + tristate "Device Flash device" + depends on ARCHITECTURE && DEVICE + help + Flash memory access on DEVICE boards. Currently only works with + Bootloader Foo and Bootloader Bar. +\end{verbatim} + +Then add your source file to the \textbf{linux/drivers/mtd/maps/Makefile}, so +that it will be compiled along with the kernel. + +\begin{verbatim} +obj-\$(CONFIG_MTD_DEVICE_FLASH) += device-flash.o +\end{verbatim} + +You can then write the kernel driver itself, by creating a +\textbf{linux/drivers/mtd/maps/device-flash.c} C source file. + +\begin{verbatim} +// Includes that are required for the flash map driver to know of the prototypes: +#include +#include +#include +#include +#include +#include +#include + +// Put some flash map definitions here: +#define WINDOW_ADDR 0x1FC00000 /* Real address of the flash */ +#define WINDOW_SIZE 0x400000 /* Size of flash */ +#define BUSWIDTH 2 /* Buswidth */ + +static void __exit device_mtd_cleanup(void); + +static struct mtd_info *device_mtd_info; + +static struct map_info devicd_map = { + .name = "device", + .size = WINDOW_SIZE, + .bankwidth = BUSWIDTH, + .phys = WINDOW_ADDR, +}; + +static int __init device_mtd_init(void) +{ + // Display that we found a flash map device + printk("device: 0x\%08x at 0x\%08x\n", WINDOW_SIZE, WINDOW_ADDR); + // Remap the device address to a kernel address + device_map.virt = ioremap(WINDOW_ADDR, WINDOW_SIZE); + + // If impossible to remap, exit with the EIO error + if (!device_map.virt) { + printk("device: Failed to ioremap\n"); + return -EIO; + } + + // Initialize the device map + simple_map_init(&device_map); + + /* MTD informations are closely linked to the flash map device + you might also use "jedec_probe" "amd_probe" or "intel_probe" */ + device_mtd_info = do_map_probe("cfi_probe", &device_map); + + if (device_mtd_info) { + device_mtd_info->owner = THIS_MODULE; + + int parsed_nr_parts = 0; + + // We try here to use the partition schema provided by the bootloader specific code + if (parsed_nr_parts == 0) { + int ret = parse_bootloader_partitions(device_mtd_info, &parsed_parts, 0); + if (ret > 0) { + part_type = "BootLoader"; + parsed_nr_parts = ret; + } + } + + add_mtd_partitions(devicd_mtd_info, parsed_parts, parsed_nr_parts); + + return 0; + } + iounmap(device_map.virt); + + return -ENXIO; +} + +// This function will make the driver clean up the MTD device mapping +static void __exit device_mtd_cleanup(void) +{ + // If we found a MTD device before + if (device_mtd_info) { + // Delete every partitions + del_mtd_partitions(device_mtd_info); + // Delete the associated map + map_destroy(device_mtd_info); + } + + // If the virtual address is already in use + if (device_map.virt) { + // Unmap the physical address to a kernel space address + iounmap(device_map.virt); + // Reset the structure field + device_map.virt = 0; + } +} + + +// Macros that indicate which function is called on loading/unloading the module +module_init(device_mtd_init); +module_exit(device_mtd_cleanup); + + +// Macros defining license and author, parameters can be defined here too. +MODULE_LICENSE("GPL"); +MODULE_AUTHOR("Me, myself and I $(KDIR)/vmlinux.bin.gz + $(STAGING_DIR_HOST)/bin/lzma e $(KDIR)/vmlinux $(KDIR)/vmlinux.bin.l7 + dd if=$(KDIR)/vmlinux.bin.l7 of=$(BIN_DIR)/openwrt-$(BOARD)-vmlinux.lzma bs=65536 conv=sync + dd if=$(KDIR)/vmlinux.bin.gz of=$(BIN_DIR)/openwrt-$(BOARD)-vmlinux.gz bs=65536 conv=sync +endef + +define Image/Build/squashfs + $(call prepare_generic_squashfs,$(KDIR)/root.squashfs) +endef + +define Image/Build + $(call Image/Build/$(1)) + dd if=$(KDIR)/root.$(1) of=$(BIN_DIR)/openwrt-$(BOARD)-root.$(1) bs=128k conv=sync + + -$(STAGING_DIR_HOST)/bin/mkfwimage \ + -B XS2 -v XS2.ar2316.OpenWrt \ + -k $(BIN_DIR)/openwrt-$(BOARD)-vmlinux.lzma \ + -r $(BIN_DIR)/openwrt-$(BOARD)-root.$(1) \ + -o $(BIN_DIR)/openwrt-$(BOARD)-ubnt2-$(1).bin +endef + +$(eval $(call BuildImage)) + +\end{Verbatim} + +\begin{itemize} + \item \texttt{Image/BuildKernel} \\ + This template defines changes to be made to the ELF kernel file + \item \texttt{Image/Build} \\ + This template defines the final changes to apply to the rootfs and kernel, either combined or separated + firmware creation tools can be called here as well. +\end{itemize} diff --git a/docs/bugs.tex b/docs/bugs.tex new file mode 100644 index 0000000..9c46b5a --- /dev/null +++ b/docs/bugs.tex @@ -0,0 +1,52 @@ +OpenWrt as an open source software opens its development to the community by +having a publicly browseable subversion repository. The Trac software which +comes along with a Subversion frontend, a Wiki and a ticket reporting system +is used as an interface between developers, users and contributors in order to +make the whole development process much easier and efficient. + +We make distinction between two kinds of people within the Trac system: + +\begin{itemize} +\item developers, able to report, close and fix tickets +\item reporters, able to add a comment, patch, or request ticket status +\end{itemize} + +\subsubsection{Opening a ticket} + +A reporter might want to open a ticket for the following reasons: + +\begin{itemize} +\item a bug affects a specific hardware and/or software and needs to be fixed +\item a specific software package would be seen as part of the official OpenWrt repository +\item a feature should be added or removed from OpenWrt +\end{itemize} + +Regarding the kind of ticket that is open, a patch is welcome in those cases: + +\begin{itemize} +\item new package to be included in OpenWrt +\item fix for a bug that works for the reporter and has no known side effect +\item new features that can be added by modifying existing OpenWrt files +\end{itemize} + +Once the ticket is open, a developer will take care of it, if so, the ticket is marked +as "accepted" with the developer name. You can add comments at any time to the ticket, +even when it is closed. + +\subsubsection{Closing a ticket} + +A ticket might be closed by a developer because: + +\begin{itemize} +\item the problem is already fixed (wontfix) +\item the problem described is not judged as valid, and comes along with an explanation why (invalid) +\item the developers know that this bug will be fixed upstream (wontfix) +\item the problem is very similar to something that has already been reported (duplicate) +\item the problem cannot be reproduced by the developers (worksforme) +\end{itemize} + +At the same time, the reporter may want to get the ticket closed since he is not +longer able to trigger the bug, or found it invalid by himself. + +When a ticket is closed by a developer and marked as "fixed", the comment contains +the subversion changeset which corrects the bug. diff --git a/docs/build.tex b/docs/build.tex new file mode 100644 index 0000000..6e1539a --- /dev/null +++ b/docs/build.tex @@ -0,0 +1,594 @@ +One of the biggest challenges to getting started with embedded devices is that you +cannot just install a copy of Linux and expect to be able to compile a firmware. +Even if you did remember to install a compiler and every development tool offered, +you still would not have the basic set of tools needed to produce a firmware image. +The embedded device represents an entirely new hardware platform, which is +most of the time incompatible with the hardware on your development machine, so in a process called +cross compiling you need to produce a new compiler capable of generating code for +your embedded platform, and then use it to compile a basic Linux distribution to +run on your device. + +The process of creating a cross compiler can be tricky, it is not something that is +regularly attempted and so there is a certain amount of mystery and black magic +associated with it. In many cases when you are dealing with embedded devices you will +be provided with a binary copy of a compiler and basic libraries rather than +instructions for creating your own -- it is a time saving step but at the same time +often means you will be using a rather dated set of tools. Likewise, it is also common +to be provided with a patched copy of the Linux kernel from the board or chip vendor, +but this is also dated and it can be difficult to spot exactly what has been +modified to make the kernel run on the embedded platform. + +\subsection{Building an image} + +OpenWrt takes a different approach to building a firmware; downloading, patching +and compiling everything from scratch, including the cross compiler. To put it +in simpler terms, OpenWrt does not contain any executables or even sources, it is an +automated system for downloading the sources, patching them to work with the given +platform and compiling them correctly for that platform. What this means is that +just by changing the template, you can change any step in the process. + +As an example, if a new kernel is released, a simple change to one of the Makefiles +will download the latest kernel, patch it to run on the embedded platform and produce +a new firmware image -- there is no work to be done trying to track down an unmodified +copy of the existing kernel to see what changes had been made, the patches are +already provided and the process ends up almost completely transparent. This does not +just apply to the kernel, but to anything included with OpenWrt -- It is this one +simple understated concept which is what allows OpenWrt to stay on the bleeding edge +with the latest compilers, latest kernels and latest applications. + +So let's take a look at OpenWrt and see how this all works. + + +\subsubsection{Download OpenWrt} + +OpenWrt can be downloaded via subversion using the following command: + +\begin{Verbatim} +$ svn checkout svn://svn.openwrt.org/openwrt/trunk openwrt-trunk +\end{Verbatim} + +Additionally, there is a trac interface on \href{https://dev.openwrt.org/}{https://dev.openwrt.org/} +which can be used to monitor svn commits and browse the source repository. + + +\subsubsection{The directory structure} + +There are four key directories in the base: + +\begin{itemize} + \item \texttt{tools} + \item \texttt{toolchain} + \item \texttt{package} + \item \texttt{target} +\end{itemize} + +\texttt{tools} and \texttt{toolchain} refer to common tools which will be +used to build the firmware image, the compiler, and the C library. +The result of this is three new directories, \texttt{build\_dir/host}, which is a temporary +directory for building the target independent tools, \texttt{build\_dir/toolchain-\textit{}*} +which is used for building the toolchain for a specific architecture, and +\texttt{staging\_dir/toolchain-\textit{}*} where the resulting toolchain is installed. +You will not need to do anything with the toolchain directory unless you intend to +add a new version of one of the components above. + +\begin{itemize} + \item \texttt{build\_dir/host} + \item \texttt{build\_dir/toolchain-\textit{}*} +\end{itemize} + +\texttt{package} is for exactly that -- packages. In an OpenWrt firmware, almost everything +is an \texttt{.ipk}, a software package which can be added to the firmware to provide new +features or removed to save space. Note that packages are also maintained outside of the main +trunk and can be obtained from subversion using the package feeds system: + +\begin{Verbatim} +$ ./scripts/feeds update +\end{Verbatim} + +Those packages can be used to extend the functionality of the build system and need to be +symlinked into the main trunk. Once you do that, the packages will show up in the menu for +configuration. You would do something like this: + +\begin{Verbatim} +$ ./scripts/feeds search nmap +Search results in feed 'packages': +nmap Network exploration and/or security auditing utility + +$ ./scripts/feeds install nmap +\end{Verbatim} + +To include all packages, issue the following command: + +\begin{Verbatim} +$ make package/symlinks +\end{Verbatim} + +\texttt{target} refers to the embedded platform, this contains items which are specific to +a specific embedded platform. Of particular interest here is the "\texttt{target/linux}" +directory which is broken down by platform \textit{} and contains the patches to the +kernel, profile config, for a particular platform. There's also the "\texttt{target/image}" directory +which describes how to package a firmware for a specific platform. + +Both the target and package steps will use the directory "\texttt{build\_dir/\textit{}}" +as a temporary directory for compiling. Additionally, anything downloaded by the toolchain, +target or package steps will be placed in the "\texttt{dl}" directory. + +\begin{itemize} + \item \texttt{build\_dir/\textit{}} + \item \texttt{dl} +\end{itemize} + +\subsubsection{Building OpenWrt} + +While the OpenWrt build environment was intended mostly for developers, it also has to be +simple enough that an inexperienced end user can easily build his or her own customized firmware. + +Running the command "\texttt{make menuconfig}" will bring up OpenWrt's configuration menu +screen, through this menu you can select which platform you're targeting, which versions of +the toolchain you want to use to build and what packages you want to install into the +firmware image. Note that it will also check to make sure you have the basic dependencies for it +to run correctly. If that fails, you will need to install some more tools in your local environment +before you can begin. + +Similar to the linux kernel config, almost every option has three choices, +\texttt{y/m/n} which are represented as follows: + +\begin{itemize} + \item{\texttt{<*>} (pressing y)} \\ + This will be included in the firmware image + \item{\texttt{} (pressing m)} \\ + This will be compiled but not included (for later install) + \item{\texttt{< >} (pressing n)} \\ + This will not be compiled +\end{itemize} + +After you've finished with the menu configuration, exit and when prompted, save your +configuration changes. + +If you want, you can also modify the kernel config for the selected target system. +simply run "\texttt{make kernel\_menuconfig}" and the build system will unpack the kernel sources +(if necessary), run menuconfig inside of the kernel tree, and then copy the kernel config +to \texttt{target/linux/\textit{}/config} so that it is preserved over +"\texttt{make clean}" calls. + +To begin compiling the firmware, type "\texttt{make}". By default +OpenWrt will only display a high level overview of the compile process and not each individual +command. + +\subsubsection{Example:} + +\begin{Verbatim} +make[2] toolchain/install +make[3] -C toolchain install +make[2] target/compile +make[3] -C target compile +make[4] -C target/utils prepare + +[...] +\end{Verbatim} + +This makes it easier to monitor which step it's actually compiling and reduces the amount +of noise caused by the compile output. To see the full output, run the command +"\texttt{make V=99}". + +During the build process, buildroot will download all sources to the "\texttt{dl}" +directory and will start patching and compiling them in the "\texttt{build\_dir/\textit{}}" +directory. When finished, the resulting firmware will be in the "\texttt{bin}" directory +and packages will be in the "\texttt{bin/packages}" directory. + + +\subsection{Creating packages} + +One of the things that we've attempted to do with OpenWrt's template system is make it +incredibly easy to port software to OpenWrt. If you look at a typical package directory +in OpenWrt you'll find several things: + +\begin{itemize} + \item \texttt{package/\textit{}/Makefile} + \item \texttt{package/\textit{}/patches} + \item \texttt{package/\textit{}/files} +\end{itemize} + +The patches directory is optional and typically contains bug fixes or optimizations to +reduce the size of the executable. The package makefile is the important item, provides +the steps actually needed to download and compile the package. + +The files directory is also optional and typicall contains package specific startup scripts or default configuration files that can be used out of the box with OpenWrt. + +Looking at one of the package makefiles, you'd hardly recognize it as a makefile. +Through what can only be described as blatant disregard and abuse of the traditional +make format, the makefile has been transformed into an object oriented template which +simplifies the entire ordeal. + +Here for example, is \texttt{package/bridge/Makefile}: + +\begin{Verbatim}[frame=single,numbers=left] + +include $(TOPDIR)/rules.mk + +PKG_NAME:=bridge +PKG_VERSION:=1.0.6 +PKG_RELEASE:=1 + +PKG_SOURCE:=bridge-utils-$(PKG_VERSION).tar.gz +PKG_SOURCE_URL:=@SF/bridge +PKG_MD5SUM:=9b7dc52656f5cbec846a7ba3299f73bd +PKG_CAT:=zcat + +PKG_BUILD_DIR:=$(BUILD_DIR)/bridge-utils-$(PKG_VERSION) + +include $(INCLUDE_DIR)/package.mk + +define Package/bridge + SECTION:=net + CATEGORY:=Base system + TITLE:=Ethernet bridging configuration utility + URL:=http://bridge.sourceforge.net/ +endef + +define Package/bridge/description + Manage ethernet bridging: + a way to connect networks together to form a larger network. +endef + +define Build/Configure + $(call Build/Configure/Default, \ + --with-linux-headers="$(LINUX_DIR)" \ + ) +endef + +define Package/bridge/install + $(INSTALL_DIR) $(1)/usr/sbin + $(INSTALL_BIN) $(PKG_BUILD_DIR)/brctl/brctl $(1)/usr/sbin/ +endef + +$(eval $(call BuildPackage,bridge)) +\end{Verbatim} + +As you can see, there's not much work to be done; everything is hidden in other makefiles +and abstracted to the point where you only need to specify a few variables. + +\begin{itemize} + \item \texttt{PKG\_NAME} \\ + The name of the package, as seen via menuconfig and ipkg + \item \texttt{PKG\_VERSION} \\ + The upstream version number that we are downloading + \item \texttt{PKG\_RELEASE} \\ + The version of this package Makefile + \item \texttt{PKG\_SOURCE} \\ + The filename of the original sources + \item \texttt{PKG\_SOURCE\_URL} \\ + Where to download the sources from (no trailing slash), you can add multiple download sources by separating them with a \\ and a carriage return. + \item \texttt{PKG\_MD5SUM} \\ + A checksum to validate the download + \item \texttt{PKG\_CAT} \\ + How to decompress the sources (zcat, bzcat, unzip) + \item \texttt{PKG\_BUILD\_DIR} \\ + Where to compile the package +\end{itemize} + +The \texttt{PKG\_*} variables define where to download the package from; +\texttt{@SF} is a special keyword for downloading packages from sourceforge. There is also +another keyword of \texttt{@GNU} for grabbing GNU source releases. If any of the above mentionned download source fails, the OpenWrt mirrors will be used as source. + +The md5sum (if present) is used to verify the package was downloaded correctly and +\texttt{PKG\_BUILD\_DIR} defines where to find the package after the sources are +uncompressed into \texttt{\$(BUILD\_DIR)}. + +At the bottom of the file is where the real magic happens, "BuildPackage" is a macro +set up by the earlier include statements. BuildPackage only takes one argument directly -- +the name of the package to be built, in this case "\texttt{bridge}". All other information +is taken from the define blocks. This is a way of providing a level of verbosity, it's +inherently clear what the contents of the \texttt{description} template in +\texttt{Package/bridge} is, which wouldn't be the case if we passed this information +directly as the Nth argument to \texttt{BuildPackage}. + +\texttt{BuildPackage} uses the following defines: + +\textbf{\texttt{Package/\textit{}}:} \\ + \texttt{\textit{}} matches the argument passed to buildroot, this describes + the package the menuconfig and ipkg entries. Within \texttt{Package/\textit{}} + you can define the following variables: + + \begin{itemize} + \item \texttt{SECTION} \\ + The section of package (currently unused) + \item \texttt{CATEGORY} \\ + Which menu it appears in menuconfig: Network, Sound, Utilities, Multimedia ... + \item \texttt{TITLE} \\ + A short description of the package + \item \texttt{URL} \\ + Where to find the original software + \item \texttt{MAINTAINER} (optional) \\ + Who to contact concerning the package + \item \texttt{DEPENDS} (optional) \\ + Which packages must be built/installed before this package. To reference a dependency defined in the + same Makefile, use \textit{}. If defined as an external package, use + \textit{+}. For a kernel version dependency use: \textit{@LINUX\_2\_} + \item \texttt{BUILDONLY} (optional) \\ + Set this option to 1 if you do NOT want your package to appear in menuconfig. + This is useful for packages which are only used as build dependencies. + \end{itemize} + +\textbf{\texttt{Package/\textit{}/conffiles} (optional):} \\ + A list of config files installed by this package, one file per line. + +\textbf{\texttt{Build/Prepare} (optional):} \\ + A set of commands to unpack and patch the sources. You may safely leave this + undefined. + +\textbf{\texttt{Build/Configure} (optional):} \\ + You can leave this undefined if the source doesn't use configure or has a + normal config script, otherwise you can put your own commands here or use + "\texttt{\$(call Build/Configure/Default,\textit{})}" as above to + pass in additional arguments for a standard configure script. The first list of arguments will be passed + to the configure script like that: \texttt{--arg 1} \texttt{--arg 2}. The second list contains arguments that should be + defined before running the configure script such as autoconf or compiler specific variables. + + To make it easier to modify the configure command line, you can either extend or completely override the following variables: + \begin{itemize} + \item \texttt{CONFIGURE\_ARGS} \\ + Contains all command line arguments (format: \texttt{--arg 1} \texttt{--arg 2}) + \item \texttt{CONFIGURE\_VARS} \\ + Contains all environment variables that are passed to ./configure (format: \texttt{NAME="value"}) + \end{itemize} + +\textbf{\texttt{Build/Compile} (optional):} \\ + How to compile the source; in most cases you should leave this undefined. + + As with \texttt{Build/Configure} there are two variables that allow you to override + the make command line environment variables and flags: + \begin{itemize} + \item \texttt{MAKE\_FLAGS} \\ + Contains all command line arguments (typically variable overrides like \texttt{NAME="value"} + \item \texttt{MAKE\_VARS} \\ + Contains all environment variables that are passed to the make command + \end{itemize} + +\textbf{\texttt{Build/InstallDev} (optional):} \\ + If your package provides a library that needs to be made available to other packages, + you can use the \texttt{Build/InstallDev} template to copy it into the staging directory + which is used to collect all files that other packages might depend on at build time. + When it is called by the build system, two parameters are passed to it. \texttt{\$(1)} points to + the regular staging dir, typically \texttt{staging\_dir/\textit{ARCH}}, while \texttt{\$(2)} points + to \texttt{staging\_dir/host}. The host staging dir is only used for binaries, which are + to be executed or linked against on the host and its \texttt{bin/} subdirectory is included + in the \texttt{PATH} which is passed down to the build system processes. + Please use \texttt{\$(1)} and \texttt{\$(2)} here instead of the build system variables + \texttt{\$(STAGING\_DIR)} and \texttt{\$(STAGING\_DIR\_HOST)}, because the build system behavior + when staging libraries might change in the future to include automatic uninstallation. + +\textbf{\texttt{Package/\textit{}/install}:} \\ + A set of commands to copy files out of the compiled source and into the ipkg + which is represented by the \texttt{\$(1)} directory. Note that there are currently + 4 defined install macros: + \begin{itemize} + \item \texttt{INSTALL\_DIR} \\ + install -d -m0755 + \item \texttt{INSTALL\_BIN} \\ + install -m0755 + \item \texttt{INSTALL\_DATA} \\ + install -m0644 + \item \texttt{INSTALL\_CONF} \\ + install -m0600 + \end{itemize} + +The reason that some of the defines are prefixed by "\texttt{Package/\textit{}}" +and others are simply "\texttt{Build}" is because of the possibility of generating +multiple packages from a single source. OpenWrt works under the assumption of one +source per package Makefile, but you can split that source into as many packages as +desired. Since you only need to compile the sources once, there's one global set of +"\texttt{Build}" defines, but you can add as many "Package/" defines as you want +by adding extra calls to \texttt{BuildPackage} -- see the dropbear package for an example. + +After you have created your \texttt{package/\textit{}/Makefile}, the new package +will automatically show in the menu the next time you run "make menuconfig" and if selected +will be built automatically the next time "\texttt{make}" is run. + +\subsection{Creating binary packages} + +You might want to create binary packages and include them in the resulting images as packages. +To do so, you can use the following template, which basically sets to nothing the Configure and +Compile templates. + +\begin{Verbatim}[frame=single,numbers=left] + +include $(TOPDIR)/rules.mk + +PKG_NAME:=binpkg +PKG_VERSION:=1.0 +PKG_RELEASE:=1 + +PKG_SOURCE:=binpkg-$(PKG_VERSION).tar.gz +PKG_SOURCE_URL:=http://server +PKG_MD5SUM:=9b7dc52656f5cbec846a7ba3299f73bd +PKG_CAT:=zcat + +include $(INCLUDE_DIR)/package.mk + +define Package/binpkg + SECTION:=net + CATEGORY:=Network + TITLE:=Binary package +endef + +define Package/bridge/description + Binary package +endef + +define Build/Configure +endef + +define Build/Compile +endef + +define Package/bridge/install + $(INSTALL_DIR) $(1)/usr/sbin + $(INSTALL_BIN) $(PKG_BUILD_DIR)/* $(1)/usr/sbin/ +endef + +$(eval $(call BuildPackage,bridge)) +\end{Verbatim} + +Provided that the tarball which contains the binaries reflects the final +directory layout (/usr, /lib ...), it becomes very easy to get your package +look like one build from sources. + +Note that using the same technique, you can easily create binary pcakages +for your proprietary kernel modules as well. + +\subsection{Creating kernel modules packages} + +The OpenWrt distribution makes the distinction between two kind of kernel modules, those coming along with the mainline kernel, and the others available as a separate project. We will see later that a common template is used for both of them. + +For kernel modules that are part of the mainline kernel source, the makefiles are located in \textit{package/kernel/modules/*.mk} and they appear under the section "Kernel modules" + +For external kernel modules, you can add them to the build system just like if they were software packages by defining a KernelPackage section in the package makefile. + +Here for instance the Makefile for the I2C subsytem kernel modules : + +\begin{Verbatim}[frame=single,numbers=left] + +I2CMENU:=I2C Bus + +define KernelPackage/i2c-core + TITLE:=I2C support + DESCRIPTION:=Kernel modules for i2c support + SUBMENU:=$(I2CMENU) + KCONFIG:=CONFIG_I2C_CORE CONFIG_I2C_DEV + FILES:=$(MODULES_DIR)/kernel/drivers/i2c/*.$(LINUX_KMOD_SUFFIX) + AUTOLOAD:=$(call AutoLoad,50,i2c-core i2c-dev) +endef +$(eval $(call KernelPackage,i2c-core)) +\end{Verbatim} + +To group kernel modules under a common description in menuconfig, you might want to define a \textit{MENU} variable on top of the kernel modules makefile. + +\begin{itemize} + \item \texttt{TITLE} \\ + The name of the module as seen via menuconfig + \item \texttt{DESCRIPTION} \\ + The description as seen via help in menuconfig + \item \texttt{SUBMENU} \\ + The sub menu under which this package will be seen + \item \texttt{KCONFIG} \\ + Kernel configuration option dependency. For external modules, remove it. + \item \texttt{FILES} \\ + Files you want to inlude to this kernel module package, separate with spaces. + \item \texttt{AUTOLOAD} \\ + Modules that will be loaded automatically on boot, the order you write them is the order they would be loaded. +\end{itemize} + +After you have created your \texttt{package/kernel/modules/\textit{}.mk}, the new kernel modules package +will automatically show in the menu under "Kernel modules" next time you run "make menuconfig" and if selected +will be built automatically the next time "\texttt{make}" is run. + +\subsection{Conventions} + +There are a couple conventions to follow regarding packages: + +\begin{itemize} + \item \texttt{files} + \begin{enumerate} + \item configuration files follow the convention \\ + \texttt{\textit{}.conf} + \item init files follow the convention \\ + \texttt{\textit{}.init} + \end{enumerate} + \item \texttt{patches} + \begin{enumerate} + \item patches are numerically prefixed and named related to what they do + \end{enumerate} +\end{itemize} + +\subsection{Troubleshooting} + +If you find your package doesn't show up in menuconfig, try the following command to +see if you get the correct description: + +\begin{Verbatim} + TOPDIR=$PWD make -C package/ DUMP=1 V=99 +\end{Verbatim} + +If you're just having trouble getting your package to compile, there's a few +shortcuts you can take. Instead of waiting for make to get to your package, you can +run one of the following: + +\begin{itemize} + \item \texttt{make package/\textit{}/clean V=99} + \item \texttt{make package/\textit{}/install V=99} +\end{itemize} + +Another nice trick is that if the source directory under \texttt{build\_dir/\textit{}} +is newer than the package directory, it won't clobber it by unpacking the sources again. +If you were working on a patch you could simply edit the sources under the +\texttt{build\_dir/\textit{}/\textit{}} directory and run the install command above, +when satisfied, copy the patched sources elsewhere and diff them with the unpatched +sources. A warning though - if you go modify anything under \texttt{package/\textit{}} +it will remove the old sources and unpack a fresh copy. + +Other useful targets include: + +\begin{itemize} + \item \texttt{make package/\textit{}/prepare V=99} + \item \texttt{make package/\textit{}/compile V=99} + \item \texttt{make package/\textit{}/configure V=99} +\end{itemize} + + +\subsection{Using build environments} +OpenWrt provides a means of building images for multiple configurations +which can use multiple targets in one single checkout. These \emph{environments} +store a copy of the .config file generated by \texttt{make menuconfig} and the contents +of the \texttt{./files} folder. +The script \texttt{./scripts/env} is used to manage these environments, it uses +\texttt{git} (which needs to be installed on your system) as backend for version control. + +The command +\begin{Verbatim} + ./scripts/env help +\end{Verbatim} +produces a short help text with a list of commands. + +To create a new environment named \texttt{current}, run the following command +\begin{Verbatim} + ./scripts/env new current +\end{Verbatim} +This will move your \texttt{.config} file and \texttt{./files} (if it exists) to +the \texttt{env/} subdirectory and create symlinks in the base folder. + +After running make menuconfig or changing things in files/, your current state will +differ from what has been saved before. To show these changes, use: +\begin{Verbatim} + ./scripts/env diff +\end{Verbatim} + +If you want to save these changes, run: +\begin{Verbatim} + ./scripts/env save +\end{Verbatim} +If you want to revert your changes to the previously saved copy, run: +\begin{Verbatim} + ./scripts/env revert +\end{Verbatim} + +If you want, you can now create a second environment using the \texttt{new} command. +It will ask you whether you want to make it a clone of the current environment (e.g. +for minor changes) or if you want to start with a clean version (e.g. for selecting +a new target). + +To switch to a different environment (e.g. \texttt{test1}), use: +\begin{Verbatim} + ./scripts/env switch test1 +\end{Verbatim} + +To rename the current branch to a new name (e.g. \texttt{test2}), use: +\begin{Verbatim} + ./scripts/env rename test2 +\end{Verbatim} + +If you want to get rid of environment switching and keep everything in the base directory +again, use: +\begin{Verbatim} + ./scripts/env clear +\end{Verbatim} diff --git a/docs/config.tex b/docs/config.tex new file mode 100644 index 0000000..08318b4 --- /dev/null +++ b/docs/config.tex @@ -0,0 +1,101 @@ +\subsubsection{Structure of the configuration files} + +The config files are divided into sections and options/values. + +Every section has a type, but does not necessarily have a name. +Every option has a name and a value and is assigned to the section +it was written under. + +Syntax: + +\begin{Verbatim} +config [""] # Section + option "" # Option +\end{Verbatim} + +Every parameter needs to be a single string and is formatted exactly +like a parameter for a shell function. The same rules for Quoting and +special characters also apply, as it is parsed by the shell. + +\subsubsection{Parsing configuration files in custom scripts} + +To be able to load configuration files, you need to include the common +functions with: + +\begin{Verbatim} +. /lib/functions.sh +\end{Verbatim} + +Then you can use \texttt{config\_load \textit{}} to load config files. The function +first checks for \textit{} as absolute filename and falls back to loading +it from \texttt{/etc/config} (which is the most common way of using it). + +If you want to use special callbacks for sections and/or options, you +need to define the following shell functions before running \texttt{config\_load} +(after including \texttt{/lib/functions.sh}): + +\begin{Verbatim} +config_cb() { + local type="$1" + local name="$2" + # commands to be run for every section +} + +option_cb() { + # commands to be run for every option +} +\end{Verbatim} + +You can also alter \texttt{option\_cb} from \texttt{config\_cb} based on the section type. +This allows you to process every single config section based on its type +individually. + +\texttt{config\_cb} is run every time a new section starts (before options are being +processed). You can access the last section through the \texttt{CONFIG\_SECTION} +variable. Also an extra call to \texttt{config\_cb} (without a new section) is generated +after \texttt{config\_load} is done. +That allows you to process sections both before and after all options were +processed. + +Another way of iterating on config sections is using the \texttt{config\_foreach} command. + +Syntax: +\begin{Verbatim} +config_foreach [] [] +\end{Verbatim} + +This command will run the supplied function for every single config section in the currently +loaded config. The section name will be passed to the function as argument 1. +If the section type is added to the command line, the function will only be called for +sections of the given type. + + +You can access already processed options with the \texttt{config\_get} command +Syntax: + +\begin{Verbatim} +# print the value of the option +config_get