This directory contains the implementation of Genode's x86 platform driver.
Behavior
--------
On startup the driver scans the PCI bus hierarchy and stores the found devices.
Per client a policy must be configured that states which client can
access certain devices to form a virtual pci bus per client. The client may
iterate through the virtual pci bus using the 'first' and 'next' methods of
the platform_session interface to discover all available devices of the virtual
bus. Non PCI devices may be discovered by using 'device' of the
platform_session interface. As a result of the discovery a client obtains a
device capability.
With the device capability the resources of the devices can be obtained, e.g.
io_port, io_mem and irq of the platform_device interface.
Policy usage
------------
A policy may contain several nodes describing several devices. The entries of
a policy may describe PCI devices as non PCI devices. A PCI device is
explicitly configured by the triple 'bus', 'device', 'function':
!<start name="platform_drv">
! <resource name="RAM" quantum="8M" constrain_phys="yes"/>
! ...
! <config>
! <policy label="usb_drv">
! <pci bus="0" device="19" function="0"/>
! <pci bus="0" device="18" function="3"/>
! </policy>
! </config>
! ...
or more fuzzy by a device class alias:
!<start name="platform_drv">
! <resource name="RAM" quantum="8M" constrain_phys="yes"/>
! ...
! <config>
! <policy label="usb_drv">
! <pci class="USB"/>
! </policy>
! </config>
! ...
Non PCI devices, as the PS2 controller are named by a "device" node in the policy:
!<start name="platform_drv">
! <resource name="RAM" quantum="8M" constrain_phys="yes"/>
! <config>
! <policy label="ps_drv">
! <device name="PS2/>
! </policy>
! </config>
! ...
The first entry ('pci' or 'dev') of the policy node that matches will grant
access of a device or device class to the client. Subsequent entries will not
be checked. If a 'bus', 'device', 'function' triple was specified in one of the
policies and in another policy a fuzzy pci class alias which would include
the device specified by the triple, the device will not appear during device
discovery by the client with the fuzzy pci class policy.
By default the driver will try to use MSIs if the device and the used kernel
supports it. This behaviour can be overwritten:
!<start name="platform_drv">
! <resource name="RAM" quantum="8M" constrain_phys="yes"/>
! <config>
! <policy label="nic_drv" irq_mode="nomsi">
! ...
! </policy>
! </config>
! ...
The constrain_phys attribute is evaluated by init. If set to "yes" it
permits a component, the platform driver, to restrict the allocation of memory to
specific physical RAM ranges. The platform driver uses this feature to ensure that
the allocation of DMA capable memory consider several restrictions. For
example, some drivers, as the UHCI controller, requires a
physical memory address below 4G. Another example is that on 32bit hosts
physical to virtual identical mappings of DMA memory for the device_pd
(required when IOMMU is used) must be below the kernel memory boundary (3G).
By default the platform driver waits on startup on a report of the acpi driver,
which conatins further information about the platform the platform driver can
not discover (e.g. IRQ re-routing information, pci config extended space
information).
A specific route to a report_rom service named 'acpi_report_rom' looks as
in the following:
!<start name="platform_drv">
! ...
! <route>
! <service name="ROM">
! <if-arg key="label" value="acpi"/> <child name="acpi_report_rom"/>
! </service>
! ...
! </route>
! ...
For platforms which don't support or require the ACPI information -
e.g. base-okl4, base-pistachio, base-fiasco - the platform driver can be
configured to not wait for the acpi report:
!<start name="platform_drv">
! ...
! <config acpi="no">
! ...
! </config>
! ...
Supported PCI class aliases
---------------------------
The following class names are supported which corresponds to the
specified PCI class(C), subclass(S) and programming interface(P):
alias C S P
*********************
ALL 0x0 0x00 0x0
AHCI 0x1 0x06 0x0
AUDIO 0x4 0x00 0x0
ETHERNET 0x2 0x00 0x0
USB 0xc 0x03 0x0
VGA 0x3 0x00 0x0
WIFI 0x2 0x80 0x0
Supported non PCI devices
-------------------------
The driver provides for the PS2 controller the IO_PORT and IRQ resources.
!<start name="platform_drv">
! <resource name="RAM" quantum="8M" constrain_phys="yes"/>
! <config>
! <policy label="ps_drv">
! <dev name="PS2/>
! </policy>
! </config>
!</start>
