aboutsummaryrefslogtreecommitdiffstats
path: root/doc/porting.doxygen
diff options
context:
space:
mode:
Diffstat (limited to 'doc/porting.doxygen')
-rw-r--r--doc/porting.doxygen208
1 files changed, 0 insertions, 208 deletions
diff --git a/doc/porting.doxygen b/doc/porting.doxygen
deleted file mode 100644
index 7ea6a34..0000000
--- a/doc/porting.doxygen
+++ /dev/null
@@ -1,208 +0,0 @@
-/**
-\page porting Porting to different target boards and operating systems
-
-%wpa_supplicant was designed to be easily portable to different
-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, the code has been
-ported to number of other operating systems like VxWorks, PalmOS,
-Windows CE, and Windows Mobile. 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 \verbatim #ifdef CONFIG_ANSI_C_EXTRA \endverbatim
-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
-projects have to implement a driver wrapper. This may be done by
-adding a new driver interface module or modifying an existing module
-(driver_*.c) if the new target is similar to one of them. \ref
-driver_wrapper "Driver wrapper implementation" describes the details
-of the driver interface and discusses the tasks involved in porting
-this 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) 0x888e
-and RSN pre-authentication 0x88c7. l2_packet.h defines the interfaces
-used for this in the core %wpa_supplicant implementation.
-
-If the target operating system supports a generic mechanism for link
-layer access, that is likely the best mechanism for providing the
-needed functionality for %wpa_supplicant. Linux packet socket is an
-example of such a generic mechanism. If this is not available, a
-separate interface may need to be implemented to the network stack or
-driver. This is usually an intermediate or protocol driver that is
-operating between the device driver and the OS network stack. If such
-a mechanism is not feasible, the interface can also be implemented
-directly in the device driver.
-
-The main %wpa_supplicant repository includes l2_packet implementations
-for Linux using packet sockets (l2_packet_linux.c), more portable
-version using libpcap/libdnet libraries (l2_packet_pcap.c; this
-supports WinPcap, too), and FreeBSD specific version of libpcap
-interface (l2_packet_freebsd.c).
-
-If the target operating system is supported by libpcap (receiving) and
-libdnet (sending), l2_packet_pcap.c can likely be used with minimal or
-no changes. If this is not a case or a proprietary interface for link
-layer is required, a new l2_packet module may need to be
-added. Alternatively, struct wpa_driver_ops::send_eapol() handler can
-be used to override the l2_packet library if the link layer access is
-integrated with the driver interface implementation.
-
-
-\section eloop_porting Event loop
-
-%wpa_supplicant uses a single process/thread model and an event loop
-to provide callbacks on events (registered timeout, received packet,
-signal). eloop.h defines the event loop interface. eloop.c is an
-implementation of such an event loop using select() and sockets. This
-is suitable for most UNIX/POSIX systems. When porting to other
-operating systems, it may be necessary to replace that implementation
-with 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 processed
-to get status information and to control the operations. Currently,
-this is implemented with socket based communication; both UNIX domain
-sockets and UDP sockets are supported. If the target OS does not
-support sockets, this interface will likely need to be modified to use
-another mechanism like message queues. The control interface is
-optional component, so it is also possible to run %wpa_supplicant
-without porting this part.
-
-The %wpa_supplicant side of the control interface is implemented in
-ctrl_iface.c. Matching client side is implemented as a control
-interface library in wpa_ctrl.c.
-
-
-\section entry_point Program entry point
-
-%wpa_supplicant defines a set of functions that can be used to
-initialize main supplicant processing. Each operating system has a
-mechanism for starting new processing or threads. This is usually a
-function with a specific set of arguments and calling convention. This
-function 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 setting
-parameters for %wpa_supplicant. When porting to other operating
-systems, similar OS-specific entry point implementation is needed. It
-can be implemented in a new file that is then linked with
-%wpa_supplicant instead of main.o. main.c is also a good example on
-how the initialization process should be done.
-
-The supplicant initialization functions are defined in
-wpa_supplicant_i.h. In most cases, the entry point function should
-start by fetching configuration parameters. After this, a global
-%wpa_supplicant context is initialized with a call to
-wpa_supplicant_init(). After this, existing network interfaces can be
-added with wpa_supplicant_add_iface(). wpa_supplicant_run() is then
-used to start the main event loop. Once this returns at program
-termination time, wpa_supplicant_deinit() is used to release global
-context data.
-
-wpa_supplicant_add_iface() and wpa_supplicant_remove_iface() can be
-used 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 is
-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.
-
-*/