share/man/man4/ahci.4

   1 .\"     $OpenBSD: ahci.4,v 1.7 2008/04/19 01:18:39 djm Exp $
   2 .\"
   3 .\" Copyright (c) 2006 David Gwynne <dlg@openbsd.org>
   4 .\" Copyright (c) 2009-2016 Matthew Dillon <dillon@backplane.com>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" TORTIOUS ACTION, ARISING OUT OF
  16 .\" PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .\" Copyright (c) 2016 The DragonFly Project.  All rights reserved.
  19 .\"
  20 .\" This code is derived from software contributed to The DragonFly Project
  21 .\" by Matthew Dillon <dillon@backplane.com>
  22 .\"
  23 .\" Redistribution and use in source and binary forms, with or without
  24 .\" modification, are permitted provided that the following conditions
  25 .\" are met:
  26 .\"
  27 .\" 1. Redistributions of source code must retain the above copyright
  28 .\"    notice, this list of conditions and the following disclaimer.
  29 .\" 2. Redistributions in binary form must reproduce the above copyright
  30 .\"    notice, this list of conditions and the following disclaimer in
  31 .\"    the documentation and/or other materials provided with the
  32 .\"    distribution.
  33 .\" 3. Neither the name of The DragonFly Project nor the names of its
  34 .\"    contributors may be used to endorse or promote products derived
  35 .\"    from this software without specific, prior written permission.
  36 .\"
  37 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  38 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  39 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  40 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  41 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  42 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  43 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  44 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  45 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  46 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  47 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  48 .\" SUCH DAMAGE.
  49 .\"
  50 .Dd November 28, 2014
  51 .Dt AHCI 4
  52 .Os
  53 .Sh NAME
  54 .Nm ahci
  55 .Nd Advanced Host Controller Interface for Serial ATA
  56 .Sh SYNOPSIS
  57 To compile this driver into the kernel,
  58 place the following line in your
  59 kernel configuration file:
  60 .Bd -ragged -offset indent
  61 .Cd "device ahci"
  62 .Ed
  63 .Pp
  64 Alternatively, to load the driver as a
  65 module at boot time, place the following line in
  66 .Xr loader.conf 5 :
  67 .Bd -literal -offset indent
  68 ahci_load="YES"
  69 .Ed
  70 .Pp
  71 Note that
  72 .Dx
  73 compiles this driver into the kernel by default, so you normally do not
  74 have to do anything..
  75 .Sh DESCRIPTION
  76 The
  77 .Nm
  78 driver provides support for Serial ATA controllers conforming to the
  79 Advanced Host Controller Interface specification.
  80 .Pp
  81 Several AHCI capable controllers also provide a compatibility mode that
  82 causes them to appear as a traditional ATA controller supported by
  83 .Xr nata 4 .
  84 .Pp
  85 Although
  86 .Nm
  87 controllers are actual ATA controllers, the driver emulates SCSI via a
  88 translation layer.
  89 .Sh Special Features
  90 This driver detects chipsets with the FBS capability, indicating FIS-Based
  91 Switching support.
  92 This capability allows I/O to be queued to multiple targets behind a
  93 port-multiplier and will substantially increase performance when
  94 operating on multiple targets at once.
  95 Unfortunately, most AHCI controllers do not implement FBS.  Without it,
  96 concurrent access to multiple targets behind a port-multiplier will
  97 serialize and wind up being quite slow.
  98 .Pp
  99 This driver detects and supports chipsets with the SPM capability,
 100 indicating Port-Multiplier support.
 101 This capability allows you to connect a port-multiplier to the SATA port.
 102 The driver will then probe and attach all targets loaded into the
 103 port-multiplier.
 104 A few provisios... most port-multipliers implode if no drives are loaded
 105 into them, and most port-multipliers also fail to properly follow the
 106 AHCI port-multiplier standards, so YMMV.  The driver will do everything it
 107 can to attach to a port-multiplier if it sees one.
 108 .Sh WARNINGS
 109 eSATA PCIe cards -
 110 There are many consumer PCIe cards which provide on-board AHCI controllers
 111 and internal or external ports.
 112 This driver should work with most of them.
 113 However, we strongly recommend that you avoid purchasing any AHCI PCIe
 114 cards which provide both external eSATA and internal SATA ports and
 115 have jumpers to select between the two.
 116 The jumper header seriously interferes with delicate SATA
 117 communications and can cause instability and I/O errors even at slower
 118 3Gbps speeds.
 119 .Pp
 120 Port-Multipliers -
 121 There are many consumer port multipliers.  Nearly all of them fail to
 122 properly follow the spec.  This driver works hard to attach to whatever
 123 port-mutilplier it sees.  A good rule of thumb to follow is to
 124 always plug something into the first target slot on the PM.
 125 Dual eSATA/USB port-multipliers are very common but tend to have poorly
 126 implemented firmwares.  Still, you might not have a choice, so YMMV.
 127 Issues that can arise: The PM fails to probe, or the driver only sees
 128 one drive, or hot-swap detection fails to operate properly.
 129 .Pp
 130 Port-Multipliers require PM-capable AHCI chipsets.
 131 Most AHCI chipsets are not PM-capable... Intel is particularly bad (for
 132 reasons unknown).  Marvell chipsets tend to either be PM-capable or
 133 implement virtual PM handling on a (single) normal SATA port.  ASMedia
 134 chipsets are usually PM-capable, but the PCIe card might be poorly designed
 135 and generate lots of I/O errors due to electrical noise.
 136 .Pp
 137 The asynchronous attach described below may cause problems detecting your
 138 boot drive quickly enough for the kernel to be able to mount it.
 139 If you use the feature, the boot drive should normally be on the first
 140 AHCI controller and not be behind a port-multiplier.
 141 Only use the feature if you have a lot of controllers (like three or more).
 142 .Sh LOADER TUNABLES
 143 The following hints may be set in
 144 .Xr loader.conf 5
 145 to control the
 146 .Nm
 147 driver's behavior.
 148 Note that the hint need only exist, so removing it requires commenting it out.
 149 .Pp
 150 Usually both the
 151 .Xr nata 4
 152 and the
 153 .Nm
 154 drivers are loaded.
 155 The
 156 .Xr nata 4
 157 driver will pick up any ata-like devices which the
 158 .Nm
 159 driver misses.
 160 If the
 161 .Nm
 162 driver is disabled the
 163 .Xr nata 4
 164 driver will typically pick up the
 165 .Nm
 166 devices, albeit under the
 167 .Pa ad
 168 disk name rather than the
 169 .Pa da
 170 disk name.
 171 .Bd -literal -offset indent
 172 hint.ahci.disabled=1
 173 .Ed
 174 .Pp
 175 The
 176 .Nm
 177 driver can be told to force a lower-speed 1.5Gb link speed
 178 if necessary, and can also be told to refrain from attempting to send
 179 certain higher-level ATA commands to initialize ATA features which
 180 some devices might not properly implement.
 181 .Bd -literal -offset indent
 182 hint.ahci.force150=1
 183 hint.ahci.nofeatures=1
 184 .Ed
 185 .Pp
 186 By default, the driver will use MSI if it is supported.
 187 This behavior can be turned off by setting the following tunable:
 188 .Bd -literal -offset indent
 189 hw.ahci.msi.enable=0
 190 .Ed
 191 .Pp
 192 By default, on startup the driver will synchronously wait for all ports
 193 to probe and attach them in order before allowing the kernel boot to
 194 proceed to the next controller.
 195 Even though ports are probed in parallel, this can slow booting down
 196 if your system has multiple AHCI controllers.
 197 You can force a full asynchronous probe by setting the following
 198 tunable.
 199 The kernel will still wait for all controllers to finish before
 200 proceeding to the mountroot, but all ports will probe in parallel
 201 so booting will be a lot faster.
 202 WARNING!  When probing asynchronously /dev/da* assignments for drives can
 203 change from boot to boot, so be sure to only access drives by their
 204 /dev/serno/* path and not by their /dev/da* drive.
 205 .Bd -literal -offset indent
 206 # Attach everything asynchronously
 207 hw.ahci.synchronous_boot=0
 208 .Ed
 209 .Sh SYSCTL VARIABLES
 210 Link power management can be set with the sysctl
 211 .Va dev.ahci.%d.%d.link_pwr_mgmt
 212 to 0 for `disabled', 1 for `medium', and 2 for `aggressive'.
 213 Link power state can be read with the sysctl
 214 .Va dev.ahci.%d.%d.link_pwr_state .
 215 .Sh SEE ALSO
 216 .Xr intro 4 ,
 217 .Xr nata 4 ,
 218 .Xr nvme 4 ,
 219 .Xr pci 4 ,
 220 .Xr scsi 4 ,
 221 .Xr sili 4 ,
 222 .Xr loader.conf 5
 223 .Sh HISTORY
 224 The
 225 .Nm
 226 driver first appeared in
 227 .Dx 2.3 .
 228 .Sh AUTHORS
 229 .An -nosplit
 230 The
 231 .Nm
 232 driver was originally written by
 233 .An David Gwynne Aq Mt dlg@openbsd.org
 234 and
 235 .An Christopher Pascoe Aq Mt pascoe@openbsd.org
 236 for
 237 .Ox .
 238 .Pp
 239 It was ported to
 240 .Dx
 241 by
 242 .An Matt Dillon Aq Mt dillon@apollo.backplane.com ,
 243 who substantially rewrote the driver (honestly, just about from scratch
 244 but having the openbsd code as a reference helped a lot), and
 245 added new features such as hot-plug, FIS-based switching, and port
 246 multiplier support.