contrib/wpa_supplicant/doc/porting.doxygen

   1 /**
   2 \page porting Porting to different target boards and operating systems
   3
   4 %wpa_supplicant was designed to be easily portable to different
   5 hardware (board, CPU) and software (OS, drivers) targets. It is
   6 already used with number of operating systems and numerous wireless
   7 card models and drivers. The main %wpa_supplicant repository includes
   8 support for Linux, FreeBSD, and Windows. In addition, at least VxWorks
   9 and PalmOS are supported in separate repositories. On the hardware
  10 side, %wpa_supplicant is used on various systems: desktops, laptops,
  11 PDAs, and embedded devices with CPUs including x86, PowerPC,
  12 arm/xscale, and MIPS. Both big and little endian configurations are
  13 supported.
  14
  15
  16 \section driver_iface_porting Driver interface
  17
  18 Unless the target OS and driver is already supported, most porting
  19 projects have to implement a driver wrapper. This may be done by
  20 adding a new driver interface module or modifying an existing module
  21 (driver_*.c) if the new target is similar to one of them. \ref
  22 driver_wrapper "Driver wrapper implementation" describes the details
  23 of the driver interface and discusses the tasks involved in porting
  24 this part of %wpa_supplicant.
  25
  26
  27 \section l2_packet_porting l2_packet (link layer access)
  28
  29 %wpa_supplicant needs to have access to sending and receiving layer 2
  30 (link layer) packets with two Ethertypes: EAP-over-LAN (EAPOL) 0x888e
  31 and RSN pre-authentication 0x88c7. l2_packet.h defines the interfaces
  32 used for this in the core %wpa_supplicant implementation.
  33
  34 If the target operating system supports a generic mechanism for link
  35 layer access, that is likely the best mechanism for providing the
  36 needed functionality for %wpa_supplicant. Linux packet socket is an
  37 example of such a generic mechanism. If this is not available, a
  38 separate interface may need to be implemented to the network stack or
  39 driver. This is usually an intermediate or protocol driver that is
  40 operating between the device driver and the OS network stack. If such
  41 a mechanism is not feasible, the interface can also be implemented
  42 directly in the device driver.
  43
  44 The main %wpa_supplicant repository includes l2_packet implementations
  45 for Linux using packet sockets (l2_packet_linux.c), more portable
  46 version using libpcap/libdnet libraries (l2_packet_pcap.c; this
  47 supports WinPcap, too), and FreeBSD specific version of libpcap
  48 interface (l2_packet_freebsd.c).
  49
  50 If the target operating system is supported by libpcap (receiving) and
  51 libdnet (sending), l2_packet_pcap.c can likely be used with minimal or
  52 no changes. If this is not a case or a proprietary interface for link
  53 layer is required, a new l2_packet module may need to be
  54 added. Alternatively, struct wpa_driver_ops::send_eapol() handler can
  55 be used to override the l2_packet library if the link layer access is
  56 integrated with the driver interface implementation.
  57
  58
  59 \section eloop_porting Event loop
  60
  61 %wpa_supplicant uses a single process/thread model and an event loop
  62 to provide callbacks on events (registered timeout, received packet,
  63 signal). eloop.h defines the event loop interface. eloop.c is an
  64 implementation of such an event loop using select() and sockets. This
  65 is suitable for most UNIX/POSIX systems. When porting to other
  66 operating systems, it may be necessary to replace that implementation
  67 with OS specific mechanisms that provide similar functionality.
  68
  69
  70 \section ctrl_iface_porting Control interface
  71
  72 %wpa_supplicant uses a \ref ctrl_iface_page "control interface"
  73 to allow external processed
  74 to get status information and to control the operations. Currently,
  75 this is implemented with socket based communication; both UNIX domain
  76 sockets and UDP sockets are supported. If the target OS does not
  77 support sockets, this interface will likely need to be modified to use
  78 another mechanism like message queues. The control interface is
  79 optional component, so it is also possible to run %wpa_supplicant
  80 without porting this part.
  81
  82 The %wpa_supplicant side of the control interface is implemented in
  83 ctrl_iface.c. Matching client side is implemented as a control
  84 interface library in wpa_ctrl.c.
  85
  86
  87 \section entry_point Program entry point
  88
  89 %wpa_supplicant defines a set of functions that can be used to
  90 initialize main supplicant processing. Each operating system has a
  91 mechanism for starting new processing or threads. This is usually a
  92 function with a specific set of arguments and calling convention. This
  93 function is responsible on initializing %wpa_supplicant.
  94
  95 main.c includes an entry point for UNIX-like operating system, i.e.,
  96 main() function that uses command line arguments for setting
  97 parameters for %wpa_supplicant. When porting to other operating
  98 systems, similar OS-specific entry point implementation is needed. It
  99 can be implemented in a new file that is then linked with
 100 %wpa_supplicant instead of main.o. main.c is also a good example on
 101 how the initialization process should be done.
 102
 103 The supplicant initialization functions are defined in
 104 wpa_supplicant_i.h. In most cases, the entry point function should
 105 start by fetching configuration parameters. After this, a global
 106 %wpa_supplicant context is initialized with a call to
 107 wpa_supplicant_init(). After this, existing network interfaces can be
 108 added with wpa_supplicant_add_iface(). wpa_supplicant_run() is then
 109 used to start the main event loop. Once this returns at program
 110 termination time, wpa_supplicant_deinit() is used to release global
 111 context data.
 112
 113 wpa_supplicant_add_iface() and wpa_supplicant_remove_iface() can be
 114 used dynamically to add and remove interfaces based on when
 115 %wpa_supplicant processing is needed for them. This can be done, e.g.,
 116 when hotplug network adapters are being inserted and ejected. It is
 117 also possible to do this when a network interface is being
 118 enabled/disabled if it is desirable that %wpa_supplicant processing
 119 for the interface is fully enabled/disabled at the same time.
 120
 121 */