1/** 2\page porting Porting to different target boards and operating systems 3 4wpa_supplicant was designed to be easily portable to different 5hardware (board, CPU) and software (OS, drivers) targets. It is 6already used with number of operating systems and numerous wireless 7card models and drivers. The main wpa_supplicant repository includes 8support for Linux, FreeBSD, and Windows. In addition, the code has been 9ported to number of other operating systems like VxWorks, PalmOS, 10Windows CE, and Windows Mobile. On the hardware 11side, wpa_supplicant is used on various systems: desktops, laptops, 12PDAs, and embedded devices with CPUs including x86, PowerPC, 13arm/xscale, and MIPS. Both big and little endian configurations are 14supported. 15 16 17\section ansi_c_extra Extra functions on top of ANSI C 18 19wpa_supplicant is mostly using ANSI C functions that are available on 20most targets. However, couple of additional functions that are common 21on modern UNIX systems are used. Number of these are listed with 22prototypes in \ref common.h (the \verbatim #ifdef CONFIG_ANSI_C_EXTRA \endverbatim 23block). These functions may need to be implemented or at least defined 24as macros to native functions in the target OS or C library. 25 26Many of the common ANSI C functions are used through a wrapper 27definitions in \ref os.h to allow these to be replaced easily with a 28platform specific version in case standard C libraries are not 29available. In addition, \ref os.h defines couple of common platform 30specific functions that are implemented in \ref os_unix.c for UNIX like 31targets and in \ref os_win32.c for Win32 API. If the target platform does 32not support either of these examples, a new os_*.c file may need to be 33added. 34 35Unless OS_NO_C_LIB_DEFINES is defined, the standard ANSI C and POSIX 36functions are used by defining the os_*() wrappers to use them 37directly in order to avoid extra cost in size and speed. If the target 38platform needs different versions of the functions, \ref os.h can be 39modified to define the suitable macros or alternatively, 40OS_NO_C_LIB_DEFINES may be defined for the build and the wrapper 41functions can then be implemented in a new os_*.c wrapper file. 42 43\ref common.h defines number of helper macros for handling integers of 44different size and byte order. Suitable version of these definitions 45may need to be added for the target platform. 46 47 48\section configuration_backend Configuration backend 49 50wpa_supplicant implements a configuration interface that allows the 51backend to be easily replaced in order to read configuration data from 52a suitable source depending on the target platform. \ref config.c 53implements the generic code that can be shared with all configuration 54backends. Each backend is implemented in its own config_*.c file. 55 56The included \ref config_file.c backend uses a text file for configuration 57and \ref config_winreg.c uses Windows registry. These files can be used as 58an example for a new configuration backend if the target platform uses 59different mechanism for configuration parameters. In addition, 60\ref config_none.c can be used as an empty starting point for building a 61new configuration backend. 62 63 64\section driver_iface_porting Driver interface 65 66Unless the target OS and driver is already supported, most porting 67projects have to implement a driver wrapper. This may be done by 68adding a new driver interface module or modifying an existing module 69(driver_*.c) if the new target is similar to one of them. \ref 70driver_wrapper "Driver wrapper implementation" describes the details 71of the driver interface and discusses the tasks involved in porting 72this part of wpa_supplicant. 73 74 75\section l2_packet_porting l2_packet (link layer access) 76 77wpa_supplicant needs to have access to sending and receiving layer 2 78(link layer) packets with two Ethertypes: EAP-over-LAN (EAPOL) 0x888e 79and RSN pre-authentication 0x88c7. \ref l2_packet.h defines the interfaces 80used for this in the core wpa_supplicant implementation. 81 82If the target operating system supports a generic mechanism for link 83layer access, that is likely the best mechanism for providing the 84needed functionality for wpa_supplicant. Linux packet socket is an 85example of such a generic mechanism. If this is not available, a 86separate interface may need to be implemented to the network stack or 87driver. This is usually an intermediate or protocol driver that is 88operating between the device driver and the OS network stack. If such 89a mechanism is not feasible, the interface can also be implemented 90directly in the device driver. 91 92The main wpa_supplicant repository includes l2_packet implementations 93for Linux using packet sockets (\ref l2_packet_linux.c), more portable 94version using libpcap/libdnet libraries (\ref l2_packet_pcap.c; this 95supports WinPcap, too), and FreeBSD specific version of libpcap 96interface (\ref l2_packet_freebsd.c). 97 98If the target operating system is supported by libpcap (receiving) and 99libdnet (sending), \ref l2_packet_pcap.c can likely be used with minimal or 100no changes. If this is not a case or a proprietary interface for link 101layer is required, a new l2_packet module may need to be 102added. Alternatively, for hostapd, 103struct \ref wpa_driver_ops::hapd_send_eapol() handler can 104be used to override the l2_packet library if the link layer access is 105integrated with the driver interface implementation. 106 107 108\section eloop_porting Event loop 109 110wpa_supplicant uses a single process/thread model and an event loop 111to provide callbacks on events (registered timeout, received packet, 112signal). eloop.h defines the event loop interface. \ref eloop.c is an 113implementation of such an event loop using select() and sockets. This 114is suitable for most UNIX/POSIX systems. When porting to other 115operating systems, it may be necessary to replace that implementation 116with OS specific mechanisms that provide similar functionality. 117 118 119\section ctrl_iface_porting Control interface 120 121wpa_supplicant uses a \ref ctrl_iface_page "control interface" 122to allow external processed 123to get status information and to control the operations. Currently, 124this is implemented with socket based communication; both UNIX domain 125sockets and UDP sockets are supported. If the target OS does not 126support sockets, this interface will likely need to be modified to use 127another mechanism like message queues. The control interface is 128optional component, so it is also possible to run wpa_supplicant 129without porting this part. 130 131The wpa_supplicant side of the control interface is implemented in 132\ref wpa_supplicant/ctrl_iface.c. Matching client side is implemented as a control 133interface library in \ref wpa_ctrl.c. 134 135 136\section entry_point Program entry point 137 138wpa_supplicant defines a set of functions that can be used to 139initialize main supplicant processing. Each operating system has a 140mechanism for starting new processing or threads. This is usually a 141function with a specific set of arguments and calling convention. This 142function is responsible on initializing wpa_supplicant. 143 144\ref wpa_supplicant/main.c includes an entry point for UNIX-like 145operating system, i.e., main() function that uses command line arguments 146for setting parameters for wpa_supplicant. When porting to other 147operating systems, similar OS-specific entry point implementation is 148needed. It can be implemented in a new file that is then linked with 149wpa_supplicant instead of main.o. \ref wpa_supplicant/main.c is also a 150good example on how the initialization process should be done. 151 152The supplicant initialization functions are defined in 153\ref wpa_supplicant_i.h. In most cases, the entry point function should 154start by fetching configuration parameters. After this, a global 155wpa_supplicant context is initialized with a call to 156\ref wpa_supplicant_init(). After this, existing network interfaces can be 157added with \ref wpa_supplicant_add_iface(). \ref wpa_supplicant_run() is then 158used to start the main event loop. Once this returns at program 159termination time, \ref wpa_supplicant_deinit() is used to release global 160context data. 161 162\ref wpa_supplicant_add_iface() and \ref wpa_supplicant_remove_iface() can be 163used dynamically to add and remove interfaces based on when 164wpa_supplicant processing is needed for them. This can be done, e.g., 165when hotplug network adapters are being inserted and ejected. It is 166also possible to do this when a network interface is being 167enabled/disabled if it is desirable that wpa_supplicant processing 168for the interface is fully enabled/disabled at the same time. 169 170 171\section simple_build Simple build example 172 173One way to start a porting project is to begin with a very simple 174build of wpa_supplicant with WPA-PSK support and once that is 175building correctly, start adding features. 176 177Following command can be used to build very simple version of 178wpa_supplicant: 179 180\verbatim 181cc -o wpa_supplicant config.c eloop.c common.c md5.c rc4.c sha1.c \ 182 config_none.c l2_packet_none.c tls_none.c wpa.c preauth.c \ 183 aes_wrap.c wpa_supplicant.c events.c main_none.c drivers.c 184\endverbatim 185 186The end result is not really very useful since it uses empty functions 187for configuration parsing and layer 2 packet access and does not 188include a driver interface. However, this is a good starting point 189since the build is complete in the sense that all functions are 190present and this is easy to configure to a build system by just 191including the listed C files. 192 193Once this version can be build successfully, the end result can be 194made functional by adding a proper program entry point (main*.c), 195driver interface (driver_*.c and matching CONFIG_DRIVER_* define for 196registration in \ref drivers.c), configuration parser/writer (config_*.c), 197and layer 2 packet access implementation (l2_packet_*.c). After these 198components have been added, the end result should be a working 199WPA/WPA2-PSK enabled supplicant. 200 201After the basic functionality has been verified to work, more features 202can be added by linking in more files and defining C pre-processor 203defines. Currently, the best source of information for what options 204are available and which files needs to be included is in the Makefile 205used for building the supplicant with make. Similar configuration will 206be needed for build systems that either use different type of make 207tool or a GUI-based project configuration. 208 209*/ 210
