1.\" Copyright (c) 2009-2013 Alexander Motin <mav@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd December 17, 2021 28.Dt AHCI 4 29.Os 30.Sh NAME 31.Nm ahci 32.Nd Serial ATA Advanced Host Controller Interface driver 33.Sh SYNOPSIS 34To compile this driver into the kernel, 35place the following lines in your 36kernel configuration file: 37.Bd -ragged -offset indent 38.Cd "device pci" 39.Cd "device scbus" 40.Cd "device ahci" 41.Ed 42.Pp 43Alternatively, to load the driver as a 44module at boot time, place the following line in 45.Xr loader.conf 5 : 46.Bd -literal -offset indent 47ahci_load="YES" 48.Ed 49.Pp 50The following tunables are settable from the 51.Xr loader 8 : 52.Bl -ohang 53.It Va hint.ahci. Ns Ar X Ns Va .msi 54controls Message Signaled Interrupts (MSI) usage by the specified controller. 55.Pp 56.Bl -tag -width 4n -offset indent -compact 57.It 0 58MSI disabled; 59.It 1 60single MSI vector used, if supported; 61.It 2 62multiple MSI vectors used, if supported (default); 63.El 64.It Va hint.ahci. Ns Ar X Ns Va .ccc 65controls Command Completion Coalescing (CCC) usage by the specified controller. 66Non-zero value enables CCC and defines maximum time (in ms), request can wait 67for interrupt, if there are some more requests present on controller queue. 68CCC reduces number of context switches on systems with many parallel requests, 69but it can decrease disk performance on some workloads due to additional 70command latency. 71.It Va hint.ahci. Ns Ar X Ns Va .direct 72controls whether the driver should use direct command completion from 73interrupt thread(s), or queue them to CAM completion threads. 74Default value depends on number of MSI interrupts supported and number of 75implemented SATA ports. 76.It Va hint.ahci. Ns Ar X Ns Va .em 77controls whether the driver should implement virtual enclosure management 78device on top of SGPIO or other interface. 79Default value depends on controller capabilities. 80.It Va hint.ahcich. Ns Ar X Ns Va .pm_level 81controls SATA interface Power Management for the specified channel, 82allowing some power to be saved at the cost of additional command 83latency. 84Possible values: 85.Pp 86.Bl -tag -width 4n -offset indent -compact 87.It 0 88interface Power Management is disabled (default); 89.It 1 90device is allowed to initiate PM state change, host is passive; 91.It 2 92host initiates PARTIAL PM state transition every time port becomes idle; 93.It 3 94host initiates SLUMBER PM state transition every time port becomes idle. 95.It 4 96driver initiates PARTIAL PM state transition 1ms after port becomes idle; 97.It 5 98driver initiates SLUMBER PM state transition 125ms after port becomes idle. 99.El 100.Pp 101Some controllers, such as ICH8, do not implement modes 2 and 3 with NCQ used. 102Because of artificial entering latency, performance degradation in modes 1034 and 5 is much smaller then in modes 2 and 3. 104.Pp 105Note that interface Power Management complicates device presence detection. 106A manual bus reset/rescan may be needed after device hot-plug, unless hardware 107implements Cold Presence Detection. 108.It Va hint.ahcich. Ns Ar X Ns Va .sata_rev 109setting to nonzero value limits maximum SATA revision (speed). 110Values 1, 2 and 3 are respectively 1.5, 3 and 6Gbps. 111.It Va hw.ahci.force 112setting to nonzero value forces driver attach to some known AHCI-capable 113chips even if they are configured for legacy IDE emulation. 114Default is 1. 115.El 116.Sh DESCRIPTION 117This driver provides the 118.Xr CAM 4 119subsystem with native access to the 120.Tn SATA 121ports of AHCI-compatible controllers. 122Each SATA port found is represented to CAM as a separate bus with one 123target, or, if HBA supports Port Multipliers, 16 targets. 124Most of the bus-management details are handled by the SATA-specific 125transport of CAM. 126Connected ATA disks are handled by the ATA protocol disk peripheral driver 127.Xr ada 4 . 128ATAPI devices are handled by the SCSI protocol peripheral drivers 129.Xr cd 4 , 130.Xr da 4 , 131.Xr sa 4 , 132etc. 133.Pp 134Driver features include support for Serial ATA and ATAPI devices, 135Port Multipliers (including FIS-based switching, when supported), 136hardware command queues (up to 32 commands per port), 137Native Command Queuing, SATA interface Power Management, device hot-plug 138and Message Signaled Interrupts. 139.Pp 140Driver supports "LED" enclosure management messages, defined by the AHCI. 141When supported by hardware, it allows to control per-port activity, locate 142and fault LEDs via the 143.Xr led 4 144API or emulated 145.Xr ses 4 146device for localization and status reporting purposes. 147Supporting AHCI controllers may transmit that information to the backplane 148controllers via SGPIO interface. 149Backplane controllers interpret received 150statuses in some way (IBPI standard) to report them using present indicators. 151.Sh HARDWARE 152The 153.Nm 154driver supports AHCI compatible controllers having PCI class 1 (mass storage), 155subclass 6 (SATA) and programming interface 1 (AHCI). 156.Pp 157Also, in cooperation with atamarvell and atajmicron drivers of ata(4), 158it supports AHCI part of legacy-PATA + AHCI-SATA combined controllers, 159such as JMicron JMB36x and Marvell 88SE61xx. 160.Pp 161The 162.Nm 163driver also supports AHCI devices that act as PCI bridges for 164.Xr nvme 4 165using Intel Rapid Storage Technology (RST). 166To use the 167.Xr nvme 4 168device, either one must set the SATA mode in the BIOS to AHCI (from RST), 169or one must accept the performance with RST enabled due to interrupt sharing. 170.Fx 171will automatically detect AHCI devices with this extension that are in RST 172mode. 173When that happens, 174.Nm 175will attach 176.Xr nvme 4 177children to the 178.Nm 179device. 180.Sh FILES 181.Bl -tag -width /dev/led/ahcich*.locate 182.It Pa /dev/led/ahci*.*.act 183activity LED device nodes 184.It Pa /dev/led/ahci*.*.fault 185fault LED device nodes 186.It Pa /dev/led/ahci*.*.locate 187locate LED device nodes 188.El 189.Sh SYSCTL 190.Bl -tag 191.It Pa dev.ahcich.X.disable_phy 192Set to 1 to disable the phy for the drive on channel X. 193Set to 0 to enable the phy. 194Useful for turning off troublemakers. 195Also useful for debugging when you need the ada drive to come and go. 196.El 197.Sh SEE ALSO 198.Xr ada 4 , 199.Xr ata 4 , 200.Xr cam 4 , 201.Xr cd 4 , 202.Xr da 4 , 203.Xr sa 4 , 204.Xr ses 4 205.Sh HISTORY 206The 207.Nm 208driver first appeared in 209.Fx 8.0 . 210.Sh AUTHORS 211.An Alexander Motin Aq Mt mav@FreeBSD.org 212