DragonFly On-Line Manual Pages
AHCI(4) DragonFly Kernel Interfaces Manual AHCI(4)
NAME
ahci - Advanced Host Controller Interface for Serial ATA
SYNOPSIS
To compile this driver into the kernel, place the following line in your
kernel configuration file:
device ahci
Alternatively, to load the driver as a module at boot time, place the
following line in loader.conf(5):
ahci_load="YES"
Note that DragonFly compiles this driver into the kernel by default, so
you normally do not have to do anything..
DESCRIPTION
The ahci driver provides support for Serial ATA controllers conforming to
the Advanced Host Controller Interface specification.
Several AHCI capable controllers also provide a compatibility mode that
causes them to appear as a traditional ATA controller supported by
nata(4).
Although ahci controllers are actual ATA controllers, the driver emulates
SCSI via a translation layer.
Special Features
This driver detects chipsets with the FBS capability, indicating FIS-
Based Switching support. This capability allows I/O to be queued to
multiple targets behind a port-multiplier and will substantially increase
performance when operating on multiple targets at once. Unfortunately,
most AHCI controllers do not implement FBS. Without it, concurrent
access to multiple targets behind a port-multiplier will serialize and
wind up being quite slow.
This driver detects and supports chipsets with the SPM capability,
indicating Port-Multiplier support. This capability allows you to
connect a port-multiplier to the SATA port. The driver will then probe
and attach all targets loaded into the port-multiplier. A few
provisios... most port-multipliers implode if no drives are loaded into
them, and most port-multipliers also fail to properly follow the AHCI
port-multiplier standards, so YMMV. The driver will do everything it can
to attach to a port-multiplier if it sees one.
WARNINGS
eSATA PCIe cards - There are many consumer PCIe cards which provide on-
board AHCI controllers and internal or external ports. This driver
should work with most of them. However, we strongly recommend that you
avoid purchasing any AHCI PCIe cards which provide both external eSATA
and internal SATA ports and have jumpers to select between the two. The
jumper header seriously interferes with delicate SATA communications and
can cause instability and I/O errors even at slower 3Gbps speeds.
Port-Multipliers - There are many consumer port multipliers. Nearly all
of them fail to properly follow the spec. This driver works hard to
attach to whatever port-mutilplier it sees. A good rule of thumb to
follow is to always plug something into the first target slot on the PM.
Dual eSATA/USB port-multipliers are very common but tend to have poorly
implemented firmwares. Still, you might not have a choice, so YMMV.
Issues that can arise: The PM fails to probe, or the driver only sees one
drive, or hot-swap detection fails to operate properly.
Port-Multipliers require PM-capable AHCI chipsets. Most AHCI chipsets
are not PM-capable... Intel is particularly bad (for reasons unknown).
Marvell chipsets tend to either be PM-capable or implement virtual PM
handling on a (single) normal SATA port. ASMedia chipsets are usually
PM-capable, but the PCIe card might be poorly designed and generate lots
of I/O errors due to electrical noise.
The asynchronous attach described below may cause problems detecting your
boot drive quickly enough for the kernel to be able to mount it. If you
use the feature, the boot drive should normally be on the first AHCI
controller and not be behind a port-multiplier. Only use the feature if
you have a lot of controllers (like three or more).
LOADER TUNABLES
The following hints may be set in loader.conf(5) to control the ahci
driver's behavior. Note that the hint need only exist, so removing it
requires commenting it out.
Usually both the nata(4) and the ahci drivers are loaded. The nata(4)
driver will pick up any ata-like devices which the ahci driver misses.
If the ahci driver is disabled the nata(4) driver will typically pick up
the ahci devices, albeit under the ad disk name rather than the da disk
name.
hint.ahci.disabled=1
The ahci driver can be told to force a lower-speed 1.5Gb or 3.0Gb link
speed if necessary, and can also be told to refrain from attempting to
send certain higher-level ATA commands to initialize ATA features which
some devices might not properly implement. Dropping the link speed is
sometimes necessary to avoid chipset comm errors when a machine's cabling
is sub-standard.
hint.ahci.force150=1
hint.ahci.force300=1
hint.ahci.force600=1
hint.ahci.nofeatures=1
By default, the driver will use MSI if it is supported. This behavior
can be turned off by setting the following tunable:
hw.ahci.msi.enable=0
By default, on startup the driver will synchronously wait for all ports
to probe and attach them in order before allowing the kernel boot to
proceed to the next controller. Even though ports are probed in
parallel, this can slow booting down if your system has multiple AHCI
controllers. You can force a full asynchronous probe by setting the
following tunable. The kernel will still wait for all controllers to
finish before proceeding to the mountroot, but all ports will probe in
parallel so booting will be a lot faster. WARNING! When probing
asynchronously /dev/da* assignments for drives can change from boot to
boot, so be sure to only access drives by their /dev/serno/* path and not
by their /dev/da* drive.
# Attach everything asynchronously
hw.ahci.synchronous_boot=0
SYSCTL VARIABLES
Link power management can be set with the sysctl
dev.ahci.%d.%d.link_pwr_mgmt to 0 for `disabled', 1 for `medium', and 2
for `aggressive'. Link power state can be read with the sysctl
dev.ahci.%d.%d.link_pwr_state.
SEE ALSO
intro(4), nata(4), nvme(4), pci(4), scsi(4), sili(4), loader.conf(5)
HISTORY
The ahci driver first appeared in DragonFly 2.3.
AUTHORS
The ahci driver was originally written by David Gwynne <dlg@openbsd.org>
and Christopher Pascoe <pascoe@openbsd.org> for OpenBSD.
It was ported to DragonFly by Matt Dillon <dillon@apollo.backplane.com>,
who substantially rewrote the driver (honestly, just about from scratch
but having the openbsd code as a reference helped a lot), and added new
features such as hot-plug, FIS-based switching, and port multiplier
support.
DragonFly 5.9-DEVELOPMENT November 28, 2014 DragonFly 5.9-DEVELOPMENT