/**\page porting Porting to different target boards and operating systems%wpa_supplicant was designed to be easily portable to differenthardware (board, CPU) and software (OS, drivers) targets. It isalready used with number of operating systems and numerous wirelesscard models and drivers. The main %wpa_supplicant repository includessupport for Linux, FreeBSD, and Windows. In addition, at least VxWorks,PalmOS, Windows CE, and Windows Mobile are supported in separaterepositories. On the hardwareside, %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 aresupported.\section ansi_c_extra Extra functions on top of ANSI C%wpa_supplicant is mostly using ANSI C functions that are available onmost targets. However, couple of additional functions that are commonon modern UNIX systems are used. Number of these are listed withprototypes in common.h (the #ifdef CONFIG_ANSI_C_EXTRA block). Thesefunctions may need to be implemented or at least defined as macros tonative functions in the target OS or C library.Many of the common ANSI C functions are used through a wrapperdefinitions in os.h to allow these to be replaced easily with aplatform specific version in case standard C libraries are notavailable. In addition, os.h defines couple of common platformspecific functions that are implemented in os_unix.c for UNIX liketargets and in os_win32.c for Win32 API. If the target platform doesnot support either of these examples, a new os_*.c file may need to beadded.Unless OS_NO_C_LIB_DEFINES is defined, the standard ANSI C and POSIXfunctions are used by defining the os_*() wrappers to use themdirectly in order to avoid extra cost in size and speed. If the targetplatform needs different versions of the functions, os.h can bemodified to define the suitable macros or alternatively,OS_NO_C_LIB_DEFINES may be defined for the build and the wrapperfunctions can then be implemented in a new os_*.c wrapper file.common.h defines number of helper macros for handling integers ofdifferent size and byte order. Suitable version of these definitionsmay need to be added for the target platform.\section configuration_backend Configuration backend%wpa_supplicant implements a configuration interface that allows thebackend to be easily replaced in order to read configuration data froma suitable source depending on the target platform. config.cimplements the generic code that can be shared with all configurationbackends. Each backend is implemented in its own config_*.c file.The included config_file.c backend uses a text file for configurationand config_winreg.c uses Windows registry. These files can be used asan example for a new configuration backend if the target platform usesdifferent mechanism for configuration parameters. In addition,config_none.c can be used as an empty starting point for building anew configuration backend.\section driver_iface_porting Driver interfaceUnless the target OS and driver is already supported, most portingprojects have to implement a driver wrapper. This may be done byadding a new driver interface module or modifying an existing module(driver_*.c) if the new target is similar to one of them. \refdriver_wrapper "Driver wrapper implementation" describes the detailsof the driver interface and discusses the tasks involved in portingthis part of %wpa_supplicant.\section l2_packet_porting l2_packet (link layer access)%wpa_supplicant needs to have access to sending and receiving layer 2(link layer) packets with two Ethertypes: EAP-over-LAN (EAPOL) 0x888eand RSN pre-authentication 0x88c7. l2_packet.h defines the interfacesused for this in the core %wpa_supplicant implementation.If the target operating system supports a generic mechanism for linklayer access, that is likely the best mechanism for providing theneeded functionality for %wpa_supplicant. Linux packet socket is anexample of such a generic mechanism. If this is not available, aseparate interface may need to be implemented to the network stack ordriver. This is usually an intermediate or protocol driver that isoperating between the device driver and the OS network stack. If sucha mechanism is not feasible, the interface can also be implementeddirectly in the device driver.The main %wpa_supplicant repository includes l2_packet implementationsfor Linux using packet sockets (l2_packet_linux.c), more portableversion using libpcap/libdnet libraries (l2_packet_pcap.c; thissupports WinPcap, too), and FreeBSD specific version of libpcapinterface (l2_packet_freebsd.c).If the target operating system is supported by libpcap (receiving) andlibdnet (sending), l2_packet_pcap.c can likely be used with minimal orno changes. If this is not a case or a proprietary interface for linklayer is required, a new l2_packet module may need to beadded. Alternatively, struct wpa_driver_ops::send_eapol() handler canbe used to override the l2_packet library if the link layer access isintegrated with the driver interface implementation.\section eloop_porting Event loop%wpa_supplicant uses a single process/thread model and an event loopto provide callbacks on events (registered timeout, received packet,signal). eloop.h defines the event loop interface. eloop.c is animplementation of such an event loop using select() and sockets. Thisis suitable for most UNIX/POSIX systems. When porting to otheroperating systems, it may be necessary to replace that implementationwith OS specific mechanisms that provide similar functionality.\section ctrl_iface_porting Control interface%wpa_supplicant uses a \ref ctrl_iface_page "control interface"to allow external processedto get status information and to control the operations. Currently,this is implemented with socket based communication; both UNIX domainsockets and UDP sockets are supported. If the target OS does notsupport sockets, this interface will likely need to be modified to useanother mechanism like message queues. The control interface isoptional component, so it is also possible to run %wpa_supplicantwithout porting this part.The %wpa_supplicant side of the control interface is implemented inctrl_iface.c. Matching client side is implemented as a controlinterface library in wpa_ctrl.c.\section entry_point Program entry point%wpa_supplicant defines a set of functions that can be used toinitialize main supplicant processing. Each operating system has amechanism for starting new processing or threads. This is usually afunction with a specific set of arguments and calling convention. Thisfunction is responsible on initializing %wpa_supplicant.main.c includes an entry point for UNIX-like operating system, i.e.,main() function that uses command line arguments for settingparameters for %wpa_supplicant. When porting to other operatingsystems, similar OS-specific entry point implementation is needed. Itcan be implemented in a new file that is then linked with%wpa_supplicant instead of main.o. main.c is also a good example onhow the initialization process should be done.The supplicant initialization functions are defined inwpa_supplicant_i.h. In most cases, the entry point function shouldstart by fetching configuration parameters. After this, a global%wpa_supplicant context is initialized with a call towpa_supplicant_init(). After this, existing network interfaces can beadded with wpa_supplicant_add_iface(). wpa_supplicant_run() is thenused to start the main event loop. Once this returns at programtermination time, wpa_supplicant_deinit() is used to release globalcontext data.wpa_supplicant_add_iface() and wpa_supplicant_remove_iface() can beused dynamically to add and remove interfaces based on when%wpa_supplicant processing is needed for them. This can be done, e.g.,when hotplug network adapters are being inserted and ejected. It isalso possible to do this when a network interface is beingenabled/disabled if it is desirable that %wpa_supplicant processingfor the interface is fully enabled/disabled at the same time.\section simple_build Simple build exampleOne way to start a porting project is to begin with a very simplebuild of %wpa_supplicant with WPA-PSK support and once that isbuilding correctly, start adding features.Following command can be used to build very simple version of%wpa_supplicant:\verbatimcc -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\endverbatimThe end result is not really very useful since it uses empty functionsfor configuration parsing and layer 2 packet access and does notinclude a driver interface. However, this is a good starting pointsince the build is complete in the sense that all functions arepresent and this is easy to configure to a build system by justincluding the listed C files.Once this version can be build successfully, the end result can bemade functional by adding a proper program entry point (main*.c),driver interface (driver_*.c and matching CONFIG_DRIVER_* define forregistration in drivers.c), configuration parser/writer (config_*.c),and layer 2 packet access implementation (l2_packet_*.c). After thesecomponents have been added, the end result should be a workingWPA/WPA2-PSK enabled supplicant.After the basic functionality has been verified to work, more featurescan be added by linking in more files and defining C pre-processordefines. Currently, the best source of information for what optionsare available and which files needs to be included is in the Makefileused for building the supplicant with make. Similar configuration willbe needed for build systems that either use different type of maketool or a GUI-based project configuration.*/