diff options
Diffstat (limited to 'contrib/wpa_supplicant/doc/porting.doxygen')
-rw-r--r-- | contrib/wpa_supplicant/doc/porting.doxygen | 91 |
1 files changed, 89 insertions, 2 deletions
diff --git a/contrib/wpa_supplicant/doc/porting.doxygen b/contrib/wpa_supplicant/doc/porting.doxygen index db64a11..581da48 100644 --- a/contrib/wpa_supplicant/doc/porting.doxygen +++ b/contrib/wpa_supplicant/doc/porting.doxygen @@ -5,14 +5,62 @@ hardware (board, CPU) and software (OS, drivers) targets. It is already used with number of operating systems and numerous wireless card models and drivers. The main %wpa_supplicant repository includes -support for Linux, FreeBSD, and Windows. In addition, at least VxWorks -and PalmOS are supported in separate repositories. On the hardware +support for Linux, FreeBSD, and Windows. In addition, at least VxWorks, +PalmOS, Windows CE, and Windows Mobile are supported in separate +repositories. On the hardware side, %wpa_supplicant is used on various systems: desktops, laptops, PDAs, and embedded devices with CPUs including x86, PowerPC, arm/xscale, and MIPS. Both big and little endian configurations are supported. +\section ansi_c_extra Extra functions on top of ANSI C + +%wpa_supplicant is mostly using ANSI C functions that are available on +most targets. However, couple of additional functions that are common +on modern UNIX systems are used. Number of these are listed with +prototypes in common.h (the #ifdef CONFIG_ANSI_C_EXTRA block). These +functions may need to be implemented or at least defined as macros to +native functions in the target OS or C library. + +Many of the common ANSI C functions are used through a wrapper +definitions in os.h to allow these to be replaced easily with a +platform specific version in case standard C libraries are not +available. In addition, os.h defines couple of common platform +specific functions that are implemented in os_unix.c for UNIX like +targets and in os_win32.c for Win32 API. If the target platform does +not support either of these examples, a new os_*.c file may need to be +added. + +Unless OS_NO_C_LIB_DEFINES is defined, the standard ANSI C and POSIX +functions are used by defining the os_*() wrappers to use them +directly in order to avoid extra cost in size and speed. If the target +platform needs different versions of the functions, os.h can be +modified to define the suitable macros or alternatively, +OS_NO_C_LIB_DEFINES may be defined for the build and the wrapper +functions can then be implemented in a new os_*.c wrapper file. + +common.h defines number of helper macros for handling integers of +different size and byte order. Suitable version of these definitions +may need to be added for the target platform. + + +\section configuration_backend Configuration backend + +%wpa_supplicant implements a configuration interface that allows the +backend to be easily replaced in order to read configuration data from +a suitable source depending on the target platform. config.c +implements the generic code that can be shared with all configuration +backends. Each backend is implemented in its own config_*.c file. + +The included config_file.c backend uses a text file for configuration +and config_winreg.c uses Windows registry. These files can be used as +an example for a new configuration backend if the target platform uses +different mechanism for configuration parameters. In addition, +config_none.c can be used as an empty starting point for building a +new configuration backend. + + \section driver_iface_porting Driver interface Unless the target OS and driver is already supported, most porting @@ -118,4 +166,43 @@ also possible to do this when a network interface is being enabled/disabled if it is desirable that %wpa_supplicant processing for the interface is fully enabled/disabled at the same time. + +\section simple_build Simple build example + +One way to start a porting project is to begin with a very simple +build of %wpa_supplicant with WPA-PSK support and once that is +building correctly, start adding features. + +Following command can be used to build very simple version of +%wpa_supplicant: + +\verbatim +cc -o wpa_supplicant config.c eloop.c common.c md5.c rc4.c sha1.c \ + config_none.c l2_packet_none.c tls_none.c wpa.c preauth.c \ + aes_wrap.c wpa_supplicant.c events.c main_none.c drivers.c +\endverbatim + +The end result is not really very useful since it uses empty functions +for configuration parsing and layer 2 packet access and does not +include a driver interface. However, this is a good starting point +since the build is complete in the sense that all functions are +present and this is easy to configure to a build system by just +including the listed C files. + +Once this version can be build successfully, the end result can be +made functional by adding a proper program entry point (main*.c), +driver interface (driver_*.c and matching CONFIG_DRIVER_* define for +registration in drivers.c), configuration parser/writer (config_*.c), +and layer 2 packet access implementation (l2_packet_*.c). After these +components have been added, the end result should be a working +WPA/WPA2-PSK enabled supplicant. + +After the basic functionality has been verified to work, more features +can be added by linking in more files and defining C pre-processor +defines. Currently, the best source of information for what options +are available and which files needs to be included is in the Makefile +used for building the supplicant with make. Similar configuration will +be needed for build systems that either use different type of make +tool or a GUI-based project configuration. + */ |