genode/repos/dde_linux/README

Device drivers ported from the Linux kernel

USB
###

Host controller
~~~~~~~~~~~~~~~

The driver will start all USB controller types a platform offers.

Please consult repos/dde_linux/drivers/usb_host/README for a description.

HID
~~~

Please consult repos/dde_linux/drivers/usb_hid/README for a description.

Storage
~~~~~~~

Please consult repos/os/src/drivers/usb_block/README for a description.

Network (Nic)
~~~~~~~~~~~~~

Please consolut repos/dde_linux/src/drivers/usb_net/README for a description.

LXIP
####

LXIP is a port of the Linux TCP/IP stack to Genode. It is build as a shared
library named 'lxip.lib.so'. The IP stack can be interfaced using Genode's
version of 'libc' by linking your application to 'lxip_libc' plugin in your
'target.mk' file.

WiFi
####

The wifi_drv component is a port of the Linux mac802.11 stack, including the
iwlwifi driver as well as libnl and wpa_supplicant, to Genode.

To start the component the following configuration snippet can be used:

!<start name="wifi_drv" caps="200">
!  <resource name="RAM" quantum="24M"/>
!  <provides><service name="Nic"/></provides>
!  <config>
!    <libc stdout="/dev/null" stderr="/dev/null" rtc="/dev/rtc"/>
!    <vfs>
!      <dir name="dev"> <log/> <null/> <rtc/>
!      <jitterentropy name="random"/>
!      <jitterentropy name="urandom"/>
!      </dir>
!    </vfs>
!  </config>
!  <route>
!    <service name="Rtc"> <any-child /> </service>
!    <any-service> <parent/> <any-child /> </any-service>
!  </route>
!</start

The driver will request access to the ROM module 'wifi_config' to
connect to a network:

!<wifi_config connected_scan_interval="30" scan_interval="10" rfkill="no">
!  <network ssid="Foobar" protection="WPA2" passphrase="allyourbase"/>
!</wifi_config>

To temporarily prevent any radio activity, the 'rfkill' attribute
can be set to 'true'.

If the network is protected by, e.g., WPA/WPA2, the protection type, either
'WPA' or 'WPA2' as well as the the passphrase have to be specified.
The 'bssid' attribute can be used to select a specifc accesspoint within a
network. Of all attributes only the 'ssid' attribute is mandatory, all others
are optional and should only be used when needed.

The configuration may contain more than one network. In This case the driver
will try to select the best one it gets a response from. To prevent it
from automatically joining the network the 'auto_connect' attribute must be
set to 'false'; the default value is 'true'. If the 'explicit_scan' attribute
is set, the driver will pro-actively scan for a hidden network with the given
SSID:

!<wifi_config connected_scan_interval="30" scan_interval="10">
!  <network ssid="Zero" protection="WPA2" passphrase="allyourbase"/>
!  <network ssid="Skynet" protection="WPA" passphrase="12345678"
!           explicit_scan="true" auto_connect="false"/>
!</wifi_config>

By default, the driver scans for available networks only when not
connected. This can be changed with the 'connected_scan_interval'
attribute, which specifies the interval for connected scans in
seconds and directly influences any roaming decision, i.e., select
a better fit accesspoint for the configured network.

Also, the driver can be switched to verbose logging during runtime
by setting the 'verbose' or 'verbose_state' attribute to 'true'.

The wifi_drv creates two distinct reports to communicate its state and
information about the wireless infrastructure to other components. The
first one is a list of all available accesspoints. The following examplary
report shows its general structure:

!<accesspoints>
!  <accesspoint ssid="skynet" bssid="00:01:02:03:04:05" quality="40"/>
!  <accesspoint ssid="foobar" bssid="01:02:03:04:05:06" quality="70" protection="WPA2"/>
!  <accesspoint ssid="foobar" bssid="01:02:03:04:05:07" quality="10" protection="WPA2"/>
!</accesspoints>

Each accesspoint node has attributes that contain the SSID and the BSSID
of the accesspoint as well as the link quality (signal strength). These
attributes are mandatory. If the network is protected, the node will also
have an attribute describing the type of protection in addition.

The second report provides information about the state of the connection
to the currently connected accesspoint:

!<state>
!  <accesspoint ssid="foobar" bssid="01:02:03:04:05:06" quality="70" freq="2418" state="connected"/>
!</state>

Valid state values are 'connected', 'disconnected', 'connecting'. Depending
on the state, there are additional attributes that can be checked. In case
of an authentication error, e.g. the passphrase is wrong, the 'auth_failure'
attribute will be set to 'true'. The 'rfkilled' attribute is set to 'true'
if a disconnect was triggered by disabling the radio activity via setting
the 'rfkill' attribute.

By subscribing to both reports and providing the required 'wifi_config' ROM
module, a component is able control the wireless driver.

Currently only WPA/WPA2 protection using a passphrase is supported and the the
SSID is copied verbatim. At the moment, there is no way to express or escape
non alphanumeric characters.

On certain cards, e.g. Intel Wireless 6200 ABG, it may be necessary to disable
the 11n mode. This can be achieved by setting the 'use_11n' attribute in
the 'wifi_config' node to 'no'.

The driver optionally reports the following information under the
label "devices" if requested in the config as depicted.

! <config> <report mac_address="true"/> </config>

! <devices> <nic mac_address="02:00:00:00:00:01"/> </devices>


lx_kit
######

The modular lx_kit seperates the required back end functionality of the Linux
emulation environment from the front end. Thereby each driver can reuse
specific parts or supply more suitable implementations by itself. It is used to
reduce the amount of redundant code in each driver.

The lx_kit is split into several layers whose structure is as follows:

The first layer in _repos/dde_linux/src/include/lx_emul_ contains those header
files that provide the structural definitions and function declarations of the
Linux API, e.g. _errno.h_ provides all error code values. The second layer in
_repos/dde_linux/src/include/lx_emul/impl_ contains the implementation of
selected functions, e.g. _slab.h_ provides the implementation of 'kmalloc()'.
The lx_kit back end API is the third layer and provides the _Lx::Malloc_
interface (_repos/dde_linux/src/include/lx_kit/malloc.h_) which is used to
implement 'kmalloc()'. There are several generic implementations of the lx_kit
interfaces that can be used by a driver.

A driver typically includes a 'lx_emul/impl/xyz.h' header once directly in its
lx_emul compilation unit. The lx_kit interface files are only included in those
compilation units that use or implement the interface. If a driver wants to use
a generic implementation it must add the source file to its source file list.
The generic implementations are located in _repos/dde_linux/src/lx_kit/_.

The modular lx_kit still depends on the private _lx_emul.h_ header file that is
tailored to each driver. Since the lx_kit already contains much of the
declarations and definitions that were originally placed in these private
header files, those files can now ommit a large amount of code.