ThinkWiki - User contributions [en]

How to hotswap Ultrabay devices

2009-06-09T17:33:53Z

Xkahn: /* HAL support */ suffix_outof doesn't exist in the FDI grammar, switching to contains_outof

The following discusses hotswap (AKA "hotplug") of devices in the [[Ultrabay]].

This page has a lot of old information. Some cleanup might be useful.

==Which driver?==
This may be confusing, so first a quick history lesson.

Older ThinkPads (up to the R51, T42p and X40) where fully IDE (PATA) for both the internal HDD and Ultrabay. For this there are two drivers, the modern libata based {{path|ata_piix}} and the old legacy {{path|piix}}/{{path|ide-disk}} combo. Most modern distributions will default to the {{path|ata_piix}} driver, which is really what you want anyway.

ThinkPads like the R52, T43, T43p, X41 and X41 Tablet are strange hybrids, they have a Serial-ATA (SATA) chipset for the internal disk controller, but through a separate SATA-PATA bridge chip the actual disk is still legacy IDE. The Ultrabay though is still connected to the legacy IDE host controller. This results in a setup where the internal disk is handled by a SATA driver and the Ultrabay is handled by either {{path|ata_piix}} or {{path|ide-disk}}.

ThinkPads like the R60, T60 and Z60 series are also hybrids, but they use a native SATA HDD internal. Just like with the previous models though you end up with two separate drivers for the internal HDD and the Ultrabay.

The latest generation ThinkPads like the R400, R500, T400, T500, W500, W700, X200, and X300 are all fully SATA for both the internal HDD and the Ultrabay device, so both are handled by the same SATA driver.
{{Todo|Figure out in which category the X60 series ThinkPads truly belong. Some of these machines might have been shipped with a 1.8" HDD which is likely to be PATA, in fact the HMM even states so. But tabook and ltwbook only lists SATA models, so the 1.8" model might never have shipped. But even if it did there will be a SATA-PATA bridge chip, so from the OS it will look like SATA.}}

{| border="1" cellspacing="0" cellpadding="2"
|+Overview of disk interface types
! width=140px|Thinkpad !! internal HDD !! Ultrabay !! Modern Driver !! Old Driver
|-
| {{R30}}, {{R31}}, {{R32}}, {{R40}}, {{R50}}, {{R50e}}, {{R50p}}, {{R51}} || Legacy 2.5" IDE (PATA) || Legacy IDE (PATA) || ata_piix || piix + ide-disk
|-
| {{R52}} || Legacy 2.5" PATA HDD with conversion to SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{R60}}, {{R61}} || 2.5" SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{R400}}, {{R500}} ||2.5" SATA || SATA || ahci || -
|-
| {{T20}}, {{T21}}, {{T22}}, {{T23}}, {{T30}}, {{T40}}, {{T40p}}, {{T41}}, {{T41p}}, {{T42}}, {{T42p}} || Legacy 2.5" IDE (PATA) || Legacy IDE (PATA) || ata_piix || piix + ide-disk
|-
| {{T43}}, {{T43p}} || Legacy 2.5" PATA HDD with conversion to SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{T60}}, {{T60p}}, {{T61}}, {{T61p}} || 2.5" SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{T400}}, {{T500}} ||2.5" SATA || SATA || ahci || -
|-
| {{X20}}, {{X21}}, {{X22}}, {{X23}}, {{X24}}, {{X30}}, {{X31}}, {{X32}} || Legacy 2.5" IDE (PATA) || Legacy IDE (PATA) || ata_piix || piix + ide-disk
|-
| {{X40}} || Legacy 1.8" IDE (PATA) || Legacy IDE (PATA) || ata_piix || piix + ide-disk
|-
| {{X41}}, {{X41t}} || Legacy 1.8" PATA HDD with conversion to SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{X60}}, {{X60s}}, {{x60t}}, {{x61}}, {{x61s}}, {{x61t}} || 2.5" HDD is SATA, 1.8" HDD is PATA with SATA conversion || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{X200}}, {{X200 Tablet}}, {{X300}}, {{X301}} ||2.5" SATA || SATA || ahci || -
|-
| {{W500}}, {{W700}} ||2.5" SATA || SATA || ahci || -
|-
| {{Z60m}}, {{Z60t}}, {{Z61e}}, {{Z61m}}, {{Z61p}}, {{Z61t}} || 2.5" SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
|}

{{NOTE|Debian users: at least up the the kernel released with Lenny, Debian applies a patch in the Debian kernel sources which prevents the use of <tt>ata_piix</tt> with PATA devices (like the IDE bus for the Ultrabay). You will have to either use an upstream kernel or (re)patch the Debian kernel sources.
You may want to have a look at the following Debian bug reports as well: [http://bugs.debian.org/444182 #444182], [http://bugs.debian.org/463833 #463833].}}

==When using the <tt>ata_piix</tt> driver==
The following applies when using the <tt>ata_piix</tt> driver, which is really the driver you should be using if your Ultrabay is legacy IDE (PATA).

You should at least be using a distribution with kernel 2.6.23. If you have a distribution with an older kernel, please update your distribution, as in addition to a newer kernel, you will need some of the newer userland tools.

===Using libata-acpi and udev===

Starting from kernel 2.6.26-rc5, it's possible to use <tt>libata-acpi</tt> in combination with udev to hotswap. Please check if CONFIG_ATA_ACPI is enabled in your kernel configuration.

For 2.6.25, you need two patches which can be easily backported ([http://article.gmane.org/gmane.linux.acpi.devel/31159],[http://article.gmane.org/gmane.linux.acpi.devel/31369]).

Create a file {{path|/etc/udev/rules.d/50-thinkpad-ultrabay.rules}} with the following contents:
<pre>
ENV{BAY_EVENT}=="3", ACTION=="change", SUBSYSTEM=="scsi", RUN+="/usr/local/sbin/ultrabay_eject"
</pre>
Then ensure it has the right permissions
chown root:root /etc/udev/rules.d/50-thinkpad-ultrabay.rules
chmod 644 /etc/udev/rules.d/50-thinkpad-ultrabay.rules
For Red Hat/Fedora and other systems with selinux, you also need to set the security context:
chcon system_u:object_r:etc_runtime_t:s0 /etc/udev/rules.d/50-thinkpad-ultrabay.rules

Now create the below ultrabay-eject script

===Script for Ultrabay eject===

The following script does the following:
* Automatically unmounts the relevant filesystems and power off the Ultrabay when the Ultrabay eject lever is released. Screams if some filesystem can't be unmounted.

create a executable file {{path|/usr/local/sbin/ultrabay_eject}} with the following content
<pre>
#!/bin/bash

ULTRABAY_SYSDIR=/sys$DEVPATH
shopt -s nullglob
logger ultrabay_eject storage device $DEVPATH
export DISPLAY=:0.0 # required for notify-send

# Umount the filesystem(s) backed by the given major:minor device(s)
unmount_rdev() { perl - "$@" <<'EOPERL' # let's do it in Perl
for $major_minor (@ARGV) {
$major_minor =~ m/^(\d+):(\d+)$/ or die;
push(@tgt_rdevs, ($1<<8)|$2);
}
# Sort by reverse length of mount point, to unmount sub-directories first
open MOUNTS,"</proc/mounts" or die "$!";
@mounts=sort { length($b->[1]) <=> length($a->[1]) } map { [ split ] } <MOUNTS>;
close MOUNTS;
foreach $m (@mounts) {
($dev,$dir)=@$m;
next unless -b $dev; $rdev=(stat($dev))[6];
next unless grep($_==$rdev, @tgt_rdevs);
system("umount","-v","$dir")==0 or $bad=1;
if ($bad == 1) {
system("logger","ultrabay_eject","ERROR unmounting",$dev,$dir);
system("notify-send -u critical -t 300000 \"Error unmounting $dir\" \"Unmounting of $dir on $dev failed!\"");
} else {
system("logger","ultrabay_eject","unmounted",$dev,$dir);
system("notify-send -u normal -t 300000 \"Unmounted $dir\"");
};
}
exit 1 if $bad;
EOPERL
}

# Get the UltraBay's /dev/foo block device node
ultrabay_dev_node() {
UDEV_PATH="`readlink -e "$ULTRABAY_SYSDIR/block/"*`" || return 1
UDEV_NAME="`udevadm info --query=name --path=$UDEV_PATH`" || return 1
echo /dev/$UDEV_NAME
}

if [ -d $ULTRABAY_SYSDIR ]; then
sync
# Unmount filesystems backed by this device
## This seems to be very inelegant and prone to failure
unmount_rdev `cat $ULTRABAY_SYSDIR/block/*/dev \
$ULTRABAY_SYSDIR/block/*/*/dev` \
|| {
logger ultrabay_eject umounting failed
echo 2 > /proc/acpi/ibm/beep # triple error tone
notify-send -u critical -t 300000 "ThinkPad Ultrabay eject failed" "Please do not pull the device, doing so could cause file corruption and possibly hang the system. Unmounting of the filesystem on the ThinkPad Ultrabay device failed. Please put the eject leaver back in place, and try to unmount the filesystem manually. If this succeeds you can try the eject again"
exit 1;
}
sync
# Nicely power off the device
DEVNODE=`ultrabay_dev_node` && hdparm -Y $DEVNODE
# Let HAL+KDE notice the unmount and let the disk spin down
sleep 0.5
# Unregister this SCSI device:
sync
echo 1 > $ULTRABAY_SYSDIR/delete
else
logger ultrabay_eject no ultrabay device directory
echo 2 > /proc/acpi/ibm/beep # triple error tone
exit 1
fi

# We need sleep here so someone can disconnect the bay and the drive
sleep 1

# Turn off power to the UltraBay
dock=$( /bin/grep ata_bay /sys/devices/platform/dock.?/type )
dock=${dock%%/type:ata_bay} # needed for 2.6.27 and later
if [ -n "$dock" -a -d "$dock" ]; then
logger ultrabay_eject undocking $dock
echo 1 > $dock/undock
fi
# Tell the user we're OK
logger ultrabay_eject done
echo 12 > /proc/acpi/ibm/beep
notify-send -u normal -t 300000 "Safe to remove" "The ThinkPad Ultrabay device can now safely be removed"
</pre>
Then make sure ownership and permissions are set correct
chown root:root /usr/local/sbin/ultrabay_eject
chmod 555 /usr/local/sbin/ultrabay_eject

If the <tt>ata_piix</tt> driver is built in the kernel, it will catch bay events and you will see the
following message in your system log:
<pre>
thinkpad_acpi: another device driver is already handling bay events
thinkpad_acpi: disabling subdriver bay
</pre>
You should load <tt>thinkpad_acpi</tt> before <tt>ata_piix</tt> if you want it to handle bay events.

===Script for Ultrabay insert===
{{WARN|Only needed for kernels prior to 2.6.26}}
Create {{path|/usr/local/sbin/ultrabay_insert}} with the following content:
#!/bin/bash
echo 12 > /proc/acpi/ibm/beep
sync
echo 0 0 0 > /sys/class/scsi_host/host1/scan

and set the right permissions
chown root:root /usr/local/sbin/ultrabay_insert
chmod 555 /usr/local/sbin/ultrabay_insert

===Using the generic bay driver and udev===
{{WARN|If you have kernel 2.6.26 or newer, please use the above [[#Using libata-acpi and udev]] method instead}}
Starting from kernel 2.6.23-rc3, it's possible to use the generic <tt>bay</tt> driver in combination with udev to hotswap. Please check if CONFIG_ACPI_BAY is enabled (module or built-in) in your kernel configuration.

Create {{path|/etc/udev/rules.d/ibm-ultrabay.rules}}:
ENV{BAY_EVENT}=="3", KERNEL=="bay.0", ACTION=="change", SUBSYSTEM=="platform", RUN+="/usr/local/sbin/ultrabay_eject"
ENV{BAY_EVENT}=="1", KERNEL=="bay.0", ACTION=="change", SUBSYSTEM=="platform", RUN+="/usr/local/sbin/ultrabay_insert"

Starting with kernel 2.6.28, the <tt>bay</tt> driver was removed from the mainline kernel. The <tt>dock</tt> driver replaced it completely. Make sure CONFIG_ACPI_DOCK is enabled in the kernel, and use the following udev rules:

ENV{EVENT}=="undock", KERNEL=="dock.2", ACTION=="change", SUBSYSTEM=="platform", RUN+="/usr/local/sbin/ultrabay_eject"
ENV{EVENT}=="dock", KERNEL=="dock.2", ACTION=="change", SUBSYSTEM=="platform", RUN+="/usr/local/sbin/ultrabay_insert"

However, the ultra_eject script needs to be changed, otherwise udev goes into an infinite event loop. It will send undock events every few seconds forever. That means as soon as the ultrabay is plugged in again, it will be immediately ejected. For kernels 2.6.28 and higher, the bay cannot be powered off using this method, so change the end of the script to read:
# Turn off power to the UltraBay:
if [ -d /sys/devices/platform/bay.0 ]; then
echo 1 > /sys/devices/platform/bay.0/eject
elif [ -e /proc/acpi/ibm/bay ]; then
echo eject > /proc/acpi/ibm/bay
fi
# Tell the user we're OK
echo 12 > /proc/acpi/ibm/beep

Alternatively, instead of modifying the script, use the libata-acpi method below.
This was tested on a T61p running Gentoo with tuxonice 2.6.28-r8 without any issues.

===Model-specific notes===
See the table above for a list of ata_piix supported laptops and the bus ID to use.

===HAL support===
{{HELP| If the script below does not work, or you have a A or W-series ThinkPad, please provide your lshal output on the [[Talk:How_to_hotswap_Ultrabay_devices]] page}}
{{NOTE| If your HAL version is older then 0.5.11, you need to replace "info.parent" with "storage.physical_device".}}

HAL support is only needed for proper notification to your desktop applications, such as Gnome and KDE. You will still require the udev script to handle the proper removal.

To tell HAL that devices connected to the UltraBay port are hotpluggable, you need to create a file {{path|/etc/hal/fdi/information/10-thinkpad-ultrabay.fdi}} with the following content:
<pre>
<?xml version="1.0" encoding="ISO-8859-1"?> 



<deviceinfo version="0.2">
<device>
<match key="/org/freedesktop/Hal/devices/computer:system.hardware.version" prefix="ThinkPad">
<match key="/org/freedesktop/Hal/devices/computer:system.hardware.vendor" string="IBM">


<match key="/org/freedesktop/Hal/devices/computer:system.hardware.version" contains_outof="T20;T21;T22;X20;X21">
<match key="storage.bus" string_outof="pci;scsi">
<match key="info.parent" string="/org/freedesktop/Hal/devices/pci_8086_7111_scsi_host_0_scsi_device_lun0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>
</match>


<match key="/org/freedesktop/Hal/devices/computer:system.hardware.version" contains_outof="T23;T30;X22;X23;X24;X30">
<match key="storage.bus" string_outof="pci;scsi">
<match key="info.parent" string="/org/freedesktop/Hal/devices/pci_8086_248a_scsi_host_0_scsi_device_lun0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>
</match>


<match key="/org/freedesktop/Hal/devices/computer:system.hardware.version" contains_outof="R50;R51;T40;T41;T42;X31;X32;X40">
<match key="storage.bus" string_outof="pci;scsi">
<match key="info.parent" string="/org/freedesktop/Hal/devices/pci_8086_24ca_scsi_host_0_scsi_device_lun0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>
</match>


<match key="/org/freedesktop/Hal/devices/computer:system.hardware.version" contains_outof="R52;T43;X41;Z60">
<match key="storage.bus" string_outof="pci;scsi">
<match key="info.parent" string="/org/freedesktop/Hal/devices/pci_8086_2653_scsi_host_scsi_device_lun0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>
</match>

</match>
<match key="/org/freedesktop/Hal/devices/computer:system.hardware.vendor" string="LENOVO">


<match key="/org/freedesktop/Hal/devices/computer:system.hardware.version" contains_outof="T60;Z61">
<match key="storage.bus" string_outof="pci;scsi">
<match key="info.parent" string="/org/freedesktop/Hal/devices/pci_8086_27df_scsi_host_scsi_device_lun0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>
</match>


<match key="/org/freedesktop/Hal/devices/computer:system.hardware.version" contains_outof="R60;X60">
<match key="storage.bus" string_outof="pci;scsi">
<match key="info.parent" string="/org/freedesktop/Hal/devices/pci_8086_27c4_scsi_host_scsi_device_lun0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>
</match>


<match key="/org/freedesktop/Hal/devices/computer:system.hardware.version" contains_outof="R61;T61;X300">
<match key="storage.bus" string_outof="pci;scsi">
<match key="info.parent" string="/org/freedesktop/Hal/devices/pci_8086_2850_scsi_host_scsi_device_lun0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>
</match>


<match key="/org/freedesktop/Hal/devices/computer:system.hardware.version" contains_outof="R400;R500;T400;T500;W500;W700;X200;X301">
<match key="storage.bus" string_outof="pci;scsi">
<match key="info.parent" string="/org/freedesktop/Hal/devices/pci_8086_2929_scsi_host_0_scsi_device_lun0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>
</match>

</match>
</match>
</device>
</deviceinfo>
</pre>

Then ensure it has the right permissions

chown root:root /etc/hal/fdi/information/10-thinkpad-ultrabay.fdi
chmod 644 /etc/hal/fdi/information/10-thinkpad-ultrabay.fdi

To check the effect, look at your lshal output, the section for your optical disk (/dev/sr0 typically) or your 2nd hdd (/dev/sdb typically) should have storage.hotpluggable = true after restarting your hal deamon or rebooting.

==When using the <tt>ide-disk</tt> driver==
The following applies if you use the <tt>ide-disk</tt> driver for the UltraBay device. 
Note that essentially, you shouldn't be using this driver, and use ata_piix instead unless you're running an older kernel where ata_piix won't work for you

Hotswapping is supposed to be supported as well, using either hdparm/[http://packages.debian.org/unstable/admin/hotswap Debian hotswap] or [[lt_hotswap]] to (un)register IDE devices. The latter is the recommended method with kernels from 2.6, since it will leave DMA working. However, for recent models (R52, T43, X41, Z60 and later) no method is known to work while maintaining DMA support; see [[Problems with SATA and Linux]].

Only IDE devices (HDD's, optical drives, zip drives) require special treatment - batteries, floppies and other devices can just be pulled from the bay, provided they are not mounted or in use at the time. However, you should still power them down first using the [[ibm-acpi]] eject function.

The [[ibm-acpi]] kernel module has an eject function ({{cmdroot|echo eject > /proc/acpi/ibm/bay}}). This only manages the ACPI calls to power down the device and the bay. It does not actually unregister the device from the IDE driver. {{cmdroot|cat /proc/acpi/ibm/bay}} shows "unoccupied" unless an IDE device is present, but the eject function still works and should still be used.

To unregister the device, you can either use the [http://packages.debian.org/unstable/admin/hotswap Debian hotswap] package, or [[lt_hotswap]]. Note that lt_hotswap doesn't seem to even build on recent (at 2.6.22 or newer, although it probably broke before 2.6.22) and on newer kernels, you should not build/load the old IDE PIIX (CONFIG_BLK_DEV_PIIX) and use the natively hotswapping ata_piix (CONFIG_ATA_PIIX) as explained on the top of this page.

[http://packages.debian.org/unstable/admin/hotswap Debian hotswap] also allows the drive to be swapped as a normal user by default, which is useful. You should use <tt>hotswap</tt> to unregister the device and then {{cmdroot|echo eject > /proc/acpi/ibm/bay}}. However, if you use this method on a 2.6 kernel, you will lose DMA support for the reinserted drive. This is due to kernel issues. This method was reported to work on a ThinkPad {{T23}} (kernels 2.6.8.1, 2.6.14.2 and 2.6.15-arch) and {{T42}} (kernel 2.6.13), but fails on a ThinkPad {{T43}} (kernel 2.6.14.3).

[[lt_hotswap]] is now the recommended method to un- and reregister the IDE device. It installs as a kernel module and has support for automatically unregistering (if loaded with the auto_eject=1 option) the device when the eject event is generated by [[ibm-acpi]]. It will leave DMA support intact. It has supported to work on a ThinkPad {{T22}} and {{T40}} and should work with many other models (but not recent models which require the <tt>ata_piix</tt> driver for disk DMA support). With the [[lt_hotswap]] kernel module loaded, run: {{cmdroot|modprobe -r ide_cd && modprobe -r cdrom && echo "MSTR eject" > /proc/acpi/lths}}

===HAL support===

HAL support also can also be configured To do so, create the file {{path|/etc/hal/fdi/information/10-ultrabay.fdi}} as follows:
<pre>
<?xml version="1.0" encoding="UTF-8"?> 

<deviceinfo version="0.2">
<device>


<match key="storage.bus" string="ide">
<match key="storage.physical_device" string="/org/freedesktop/Hal/devices/pci_8086_24ca_ide_1_0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>

</device>
</deviceinfo>
</pre>
For more details see HAL section for ata driver.

==Password protected HDD==

If you are hot-swapping a hard disk on a Ultrabay HDD tray, and the HDD has a password set, you will have to enter the password before it can be used. Example:
hdparm /dev/sdb --security-unlock

[[Category:Scripts]]
[[Category:HOWTOs]]

How to hotswap Ultrabay devices

2009-06-05T15:33:44Z

Xkahn: /* Details */ Add in details for the T400 (at least)

The following discusses hotswap (AKA "hotplug") of devices in the [[Ultrabay]].

This page has a lot of old information. Some cleanup might be useful.

==Which driver?==
This may be confusing, so first a quick history lesson.

Older ThinkPads (up to the R51, T42p and X40) where fully IDE (PATA) for both the internal HDD and Ultrabay. For this there are two drivers, the modern libata based {{path|ata_piix}} and the old legacy {{path|piix}}/{{path|ide-disk}} combo. Most modern distributions will default to the {{path|ata_piix}} driver, which is really what you want anyway.

ThinkPads like the R52, T43, T43p, X41 and X41 Tablet are strange hybrids, they have a Serial-ATA (SATA) chipset for the internal disk controller, but through a separate SATA-PATA bridge chip the actual disk is still legacy IDE. The Ultrabay though is still connected to the legacy IDE host controller. This results in a setup where the internal disk is handled by a SATA driver and the Ultrabay is handled by either {{path|ata_piix}} or {{path|ide-disk}}.

ThinkPads like the R60, T60 and Z60 series are also hybrids, but they use a native SATA HDD internal. Just like with the previous models though you end up with two separate drivers for the internal HDD and the Ultrabay.

The latest generation ThinkPads like the R400, R500, T400, T500, W500, W700, X200, and X300 are all fully SATA for both the internal HDD and the Ultrabay device, so both are handled by the same SATA driver.
{{Todo|Figure out in which category the X60 series ThinkPads truly belong. Some of these machines might have been shipped with a 1.8" HDD which is likely to be PATA, in fact the HMM even states so. But tabook and ltwbook only lists SATA models, so the 1.8" model might never have shipped. But even if it did there will be a SATA-PATA bridge chip, so from the OS it will look like SATA.}}

{| border="1" cellspacing="0" cellpadding="2"
|+Overview of disk interface types
! width=140px|Thinkpad !! internal HDD !! Ultrabay !! Modern Driver !! Old Driver
|-
| {{R30}}, {{R31}}, {{R32}}, {{R40}}, {{R50}}, {{R50e}}, {{R50p}}, {{R51}} || Legacy 2.5" IDE (PATA) || Legacy IDE (PATA) || ata_piix || piix + ide-disk
|-
| {{R52}} || Legacy 2.5" PATA HDD with conversion to SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{R60}}, {{R61}} || 2.5" SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{R400}}, {{R500}} ||2.5" SATA || SATA || ahci || -
|-
| {{T20}}, {{T21}}, {{T22}}, {{T23}}, {{T30}}, {{T40}}, {{T40p}}, {{T41}}, {{T41p}}, {{T42}}, {{T42p}} || Legacy 2.5" IDE (PATA) || Legacy IDE (PATA) || ata_piix || piix + ide-disk
|-
| {{T43}}, {{T43p}} || Legacy 2.5" PATA HDD with conversion to SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{T60}}, {{T60p}}, {{T61}}, {{T61p}} || 2.5" SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{T400}}, {{T500}} ||2.5" SATA || SATA || ahci || -
|-
| {{X20}}, {{X21}}, {{X22}}, {{X23}}, {{X24}}, {{X30}}, {{X31}}, {{X32}} || Legacy 2.5" IDE (PATA) || Legacy IDE (PATA) || ata_piix || piix + ide-disk
|-
| {{X40}} || Legacy 1.8" IDE (PATA) || Legacy IDE (PATA) || ata_piix || piix + ide-disk
|-
| {{X41}}, {{X41t}} || Legacy 1.8" PATA HDD with conversion to SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{X60}}, {{X60s}}, {{x60t}}, {{x61}}, {{x61s}}, {{x61t}} || 2.5" HDD is SATA, 1.8" HDD is PATA with SATA conversion || Legacy IDE (PATA) || ahci + ata_piix || -
|-
| {{X200}}, {{X200 Tablet}}, {{X300}}, {{X301}} ||2.5" SATA || SATA || ahci || -
|-
| {{W500}}, {{W700}} ||2.5" SATA || SATA || ahci || -
|-
| {{Z60m}}, {{Z60t}}, {{Z61e}}, {{Z61m}}, {{Z61p}}, {{Z61t}} || 2.5" SATA || Legacy IDE (PATA) || ahci + ata_piix || -
|-
|}

{{NOTE|Debian users: at least up the the kernel released with Lenny, Debian applies a patch in the Debian kernel sources which prevents the use of <tt>ata_piix</tt> with PATA devices (like the IDE bus for the Ultrabay). You will have to either use an upstream kernel or (re)patch the Debian kernel sources.
You may want to have a look at the following Debian bug reports as well: [http://bugs.debian.org/444182 #444182], [http://bugs.debian.org/463833 #463833].}}

==When using the <tt>ata_piix</tt> driver==
The following applies when using the <tt>ata_piix</tt> driver, which is really the driver you should be using if your Ultrabay is legacy IDE (PATA).

You should at least be using a distribution with kernel 2.6.23. If you have a distribution with an older kernel, please update your distribution, as in addition to a newer kernel, you will need some of the newer userland tools.

===Script for Ultrabay eject===

The following script does the following:
* Automatically unmounts the relevant filesystems and power off the Ultrabay when the Ultrabay eject lever is released. Screams if some filesystem can't be unmounted.

create a executable file {{path|/usr/local/sbin/ultrabay_eject}} with the following content
<pre>
#!/bin/bash

ULTRABAY_SYSDIR=/sys$DEVPATH
shopt -s nullglob
logger ultrabay_eject storage device $DEVPATH
export DISPLAY=:0.0 # required for notify-send

# Umount the filesystem(s) backed by the given major:minor device(s)
unmount_rdev() { perl - "$@" <<'EOPERL' # let's do it in Perl
for $major_minor (@ARGV) {
$major_minor =~ m/^(\d+):(\d+)$/ or die;
push(@tgt_rdevs, ($1<<8)|$2);
}
# Sort by reverse length of mount point, to unmount sub-directories first
open MOUNTS,"</proc/mounts" or die "$!";
@mounts=sort { length($b->[1]) <=> length($a->[1]) } map { [ split ] } <MOUNTS>;
close MOUNTS;
foreach $m (@mounts) {
($dev,$dir)=@$m;
next unless -b $dev; $rdev=(stat($dev))[6];
next unless grep($_==$rdev, @tgt_rdevs);
system("umount","-v","$dir")==0 or $bad=1;
if ($bad == 1) {
system("logger","ultrabay_eject","ERROR unmounting",$dev,$dir);
system("notify-send -u critical -t 300000 \"Error unmounting $dir\" \"Unmounting of $dir on $dev failed!\"");
} else {
system("logger","ultrabay_eject","unmounted",$dev,$dir);
system("notify-send -u normal -t 300000 \"Unmounted $dir\"");
};
}
exit 1 if $bad;
EOPERL
}

# Get the UltraBay's /dev/foo block device node
ultrabay_dev_node() {
UDEV_PATH="`readlink -e "$ULTRABAY_SYSDIR/block/"*`" || return 1
UDEV_NAME="`udevadm info --query=name --path=$UDEV_PATH`" || return 1
echo /dev/$UDEV_NAME
}

if [ -d $ULTRABAY_SYSDIR ]; then
sync
# Unmount filesystems backed by this device
## This seems to be very inelegant and prone to failure
unmount_rdev `cat $ULTRABAY_SYSDIR/block/*/dev \
$ULTRABAY_SYSDIR/block/*/*/dev` \
|| {
logger ultrabay_eject umounting failed
echo 2 > /proc/acpi/ibm/beep # triple error tone
notify-send -u critical -t 300000 "ThinkPad Ultrabay eject failed" "Please do not pull the device, doing so could cause file corruption and possibly hang the system. Unmounting of the filesystem on the ThinkPad Ultrabay device failed. Please put the eject leaver back in place, and try to unmount the filesystem manually. If this succeeds you can try the eject again"
exit 1;
}
sync
# Nicely power off the device
DEVNODE=`ultrabay_dev_node` && hdparm -Y $DEVNODE
# Let HAL+KDE notice the unmount and let the disk spin down
sleep 0.5
# Unregister this SCSI device:
sync
echo 1 > $ULTRABAY_SYSDIR/delete
else
logger ultrabay_eject no ultrabay device directory
echo 2 > /proc/acpi/ibm/beep # triple error tone
exit 1
fi

# We need sleep here so someone can disconnect the bay and the drive
sleep 1

# Turn off power to the UltraBay
dock=$( /bin/grep ata_bay /sys/devices/platform/dock.?/type )
dock=${dock%%/type:ata_bay} # needed for 2.6.27 and later
if [ -n "$dock" -a -d "$dock" ]; then
logger ultrabay_eject undocking $dock
echo 1 > $dock/undock
fi
# Tell the user we're OK
logger ultrabay_eject done
echo 12 > /proc/acpi/ibm/beep
notify-send -u normal -t 300000 "Safe to remove" "The ThinkPad Ultrabay device can now safely be removed"
</pre>
Then make sure ownership and permissions are set correct
chown root:root /usr/local/sbin/ultrabay_eject
chmod 555 /usr/local/sbin/ultrabay_eject

If the <tt>ata_piix</tt> driver is built in the kernel, it will catch bay events and you will see the
following message in your system log:
<pre>
thinkpad_acpi: another device driver is already handling bay events
thinkpad_acpi: disabling subdriver bay
</pre>
You should load <tt>thinkpad_acpi</tt> before <tt>ata_piix</tt> if you want it to handle bay events.

===Script for Ultrabay insert===
{{WARN|Only needed for kernels prior to 2.6.26}}
Create {{path|/usr/local/sbin/ultrabay_insert}} with the following content:
#!/bin/bash
echo 12 > /proc/acpi/ibm/beep
sync
echo 0 0 0 > /sys/class/scsi_host/host1/scan

and set the right permissions
chown root:root /usr/local/sbin/ultrabay_insert
chmod 555 /usr/local/sbin/ultrabay_insert

===Using libata-acpi and udev===

Starting from kernel 2.6.26-rc5, it's possible to use <tt>libata-acpi</tt> in combination with udev to hotswap. Please check if CONFIG_ATA_ACPI is enabled in your kernel configuration.

You will also need the above ultrabay-eject script

For 2.6.25, you need two patches which can be easily backported ([http://article.gmane.org/gmane.linux.acpi.devel/31159],[http://article.gmane.org/gmane.linux.acpi.devel/31369]).

Create a file {{path|/etc/udev/rules.d/50-thinkpad-ultrabay.rules}} with the following contents:
<pre>
ENV{BAY_EVENT}=="3", ACTION=="change", SUBSYSTEM=="scsi", RUN+="/usr/local/sbin/ultrabay_eject"
</pre>
Then ensure it has the right permissions
chown root:root /etc/udev/rules.d/50-thinkpad-ultrabay.rules
chmod 644 /etc/udev/rules.d/50-thinkpad-ultrabay.rules
For Red Hat/Fedora and other systems with selinux, you also need to set the security context:
chcon system_u:object_r:etc_runtime_t:s0 /etc/udev/rules.d/50-thinkpad-ultrabay.rules

===Using the generic bay driver and udev===
{{WARN|If you have kernel 2.6.26 or newer, please use the above [[#Using libata-acpi and udev]] method instead}}
Starting from kernel 2.6.23-rc3, it's possible to use the generic <tt>bay</tt> driver in combination with udev to hotswap. Please check if CONFIG_ACPI_BAY is enabled (module or built-in) in your kernel configuration.

Create {{path|/etc/udev/rules.d/ibm-ultrabay.rules}}:
ENV{BAY_EVENT}=="3", KERNEL=="bay.0", ACTION=="change", SUBSYSTEM=="platform", RUN+="/usr/local/sbin/ultrabay_eject"
ENV{BAY_EVENT}=="1", KERNEL=="bay.0", ACTION=="change", SUBSYSTEM=="platform", RUN+="/usr/local/sbin/ultrabay_insert"

Starting with kernel 2.6.28, the <tt>bay</tt> driver was removed from the mainline kernel. The <tt>dock</tt> driver replaced it completely. Make sure CONFIG_ACPI_DOCK is enabled in the kernel, and use the following udev rules:

ENV{EVENT}=="undock", KERNEL=="dock.2", ACTION=="change", SUBSYSTEM=="platform", RUN+="/usr/local/sbin/ultrabay_eject"
ENV{EVENT}=="dock", KERNEL=="dock.2", ACTION=="change", SUBSYSTEM=="platform", RUN+="/usr/local/sbin/ultrabay_insert"

However, the ultra_eject script needs to be changed, otherwise udev goes into an infinite event loop. It will send undock events every few seconds forever. That means as soon as the ultrabay is plugged in again, it will be immediately ejected. For kernels 2.6.28 and higher, the bay cannot be powered off using this method, so change the end of the script to read:
# Turn off power to the UltraBay:
if [ -d /sys/devices/platform/bay.0 ]; then
echo 1 > /sys/devices/platform/bay.0/eject
elif [ -e /proc/acpi/ibm/bay ]; then
echo eject > /proc/acpi/ibm/bay
fi
# Tell the user we're OK
echo 12 > /proc/acpi/ibm/beep

Alternatively, instead of modifying the script, use the libata-acpi method below.
This was tested on a T61p running Gentoo with tuxonice 2.6.28-r8 without any issues.

===Model-specific notes===
See the table above for a list of ata_piix supported laptops and the bus ID to use.

===HAL support===
{{HELP| Please try the new HAL script on the [[Talk:How_to_hotswap_Ultrabay_devices]] page and report if it worked}}
{{NOTE| Starting from HAL 0.5.11, you need to replace "storage.physical_device" with "info.parent".}}

Many programs, KDE included, rely on [[HAL]] to get notifications and information about device hotplugging. You need to tell HAL that devices connected the UltraBay port are hotpluggable. To do so, create the file {{path|/etc/hal/fdi/information/10-ultrabay.fdi}} as follows:
<pre>
<?xml version="1.0" encoding="UTF-8"?> 

<deviceinfo version="0.2">
<device>


<match key="storage.bus" string="scsi">
<match key="storage.physical_device" string="/org/freedesktop/Hal/devices/pci_8086_2653_scsi_host_0_scsi_device_lun0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>

</device>
</deviceinfo>
</pre>

The string "8086_2653" may need to be changed to match your ThinkPad model; see below.

====Details====

By default, HAL doesn't know that UltraBay devices are hotpluggable:

# PHYSDEV=/org/freedesktop/Hal/devices/pci_8086_2653_scsi_host_0_scsi_device_lun0
# UDI=`hal-find-by-property --key storage.physical_device --string $PHYSDEV` || echo Failed
# hal-get-property --udi $UDI --key block.device
/dev/sdb
# hal-get-property --udi $UDI --key storage.hotpluggable
false

After creating {{path|/etc/hal/fdi/information/10-ultrabay.fdi}} as above and re-plugging the device, it will get marked correctly:

# PHYSDEV=/org/freedesktop/Hal/devices/pci_8086_2653_scsi_host_0_scsi_device_lun0
# UDI=`hal-find-by-property --key storage.physical_device --string $PHYSDEV` || echo Failed
# hal-get-property --udi $UDI --key block.device
/dev/sdb
# hal-get-property --udi $UDI --key storage.hotpluggable
true

The string "8086_2653" gives the PCI ID of the [[Intel 82801FBM]] southbridge. If your model has a different southbridge, or the UltraBay is attached to a different port, then you can find the appropriate <tt>storage.physical_device</tt> value by finding out the block device of the currently running UltraBay device (<tt>/dev/sdb</tt> in the following example) and then running:

# DEVICE=/dev/sdb
# UDI=`hal-find-by-property --key block.device --string $DEVICE` || echo Failed
# hal-get-property --udi $UDI --key storage.physical_device
/org/freedesktop/Hal/devices/pci_8086_2653_scsi_host_0_scsi_device_lun0

If you have a different <tt>storage.physical_device</tt> value, please report your findings.

{| border=1
|+ Known South Bridge PCI IDs
! ID !! ThinkPad model !! South Bridge chip (for Ultrabay) !! parent device (host_0, lun0 = 2nd IDE controller, master device)
|-
| 8086_7111 || T20, T21, T22, X20, X21 || Intel 82371AB/EB/MB PIIX4 IDE || /org/freedesktop/Hal/devices/pci_8086_7111_scsi_host_0_scsi_device_lun0
|-
| 8086_248a || T23, T30, X22, X23, X24, X30|| Intel 82801CAM IDE U100 (rev 2) || /org/freedesktop/Hal/devices/pci_8086_248a_scsi_host_0_scsi_device_lun0
|-
| 8086_24ca || R50, R51, T40, T40p, T41, T41p, T42, T42p, X31, X32, X40 || Intel 82801DBM (ICH4-M) || /org/freedesktop/Hal/devices/pci_8086_24ca_scsi_host_0_scsi_device_lun0
|-
| 8086_2653 || R52, T43, T43p, X41 || Intel 82801FBM (ICH6-M) || /org/freedesktop/Hal/devices/pci_8086_2653_scsi_host_scsi_device_lun0
|-
| 8086_27c4 || R60, X60 || Intel 82801GBM (ICH7 Family) || /org/freedesktop/Hal/devices/pci_8086_27c4_scsi_host_scsi_device_lun0
|-
| 8086_27df || T60, T60p, Z61p || Intel 82801GBM/GHM (ICH7 Family) || /org/freedesktop/Hal/devices/pci_8086_27df_scsi_host_scsi_device_lun0
|-
| 8086_2850 || R61, T61, T61p, X300 || Intel 82801H (ICH8 Family) || /org/freedesktop/Hal/devices/pci_8086_2850_scsi_host_scsi_device_lun0
|-
| 8086_2929 || R400, R500, T400, T500, W500, X200, X301 || Intel 82801I ICH9 Family || /org/freedesktop/Hal/devices/pci_8086_2929_scsi_host_0_scsi_device_lun0
|}

==When using the <tt>ide-disk</tt> driver==
The following applies if you use the <tt>ide-disk</tt> driver for the UltraBay device. 
Note that essentially, you shouldn't be using this driver, and use ata_piix instead unless you're running an older kernel where ata_piix won't work for you

Hotswapping is supposed to be supported as well, using either hdparm/[http://packages.debian.org/unstable/admin/hotswap Debian hotswap] or [[lt_hotswap]] to (un)register IDE devices. The latter is the recommended method with kernels from 2.6, since it will leave DMA working. However, for recent models (R52, T43, X41, Z60 and later) no method is known to work while maintaining DMA support; see [[Problems with SATA and Linux]].

Only IDE devices (HDD's, optical drives, zip drives) require special treatment - batteries, floppies and other devices can just be pulled from the bay, provided they are not mounted or in use at the time. However, you should still power them down first using the [[ibm-acpi]] eject function.

The [[ibm-acpi]] kernel module has an eject function ({{cmdroot|echo eject > /proc/acpi/ibm/bay}}). This only manages the ACPI calls to power down the device and the bay. It does not actually unregister the device from the IDE driver. {{cmdroot|cat /proc/acpi/ibm/bay}} shows "unoccupied" unless an IDE device is present, but the eject function still works and should still be used.

To unregister the device, you can either use the [http://packages.debian.org/unstable/admin/hotswap Debian hotswap] package, or [[lt_hotswap]]. Note that lt_hotswap doesn't seem to even build on recent (at 2.6.22 or newer, although it probably broke before 2.6.22) and on newer kernels, you should not build/load the old IDE PIIX (CONFIG_BLK_DEV_PIIX) and use the natively hotswapping ata_piix (CONFIG_ATA_PIIX) as explained on the top of this page.

[http://packages.debian.org/unstable/admin/hotswap Debian hotswap] also allows the drive to be swapped as a normal user by default, which is useful. You should use <tt>hotswap</tt> to unregister the device and then {{cmdroot|echo eject > /proc/acpi/ibm/bay}}. However, if you use this method on a 2.6 kernel, you will lose DMA support for the reinserted drive. This is due to kernel issues. This method was reported to work on a ThinkPad {{T23}} (kernels 2.6.8.1, 2.6.14.2 and 2.6.15-arch) and {{T42}} (kernel 2.6.13), but fails on a ThinkPad {{T43}} (kernel 2.6.14.3).

[[lt_hotswap]] is now the recommended method to un- and reregister the IDE device. It installs as a kernel module and has support for automatically unregistering (if loaded with the auto_eject=1 option) the device when the eject event is generated by [[ibm-acpi]]. It will leave DMA support intact. It has supported to work on a ThinkPad {{T22}} and {{T40}} and should work with many other models (but not recent models which require the <tt>ata_piix</tt> driver for disk DMA support). With the [[lt_hotswap]] kernel module loaded, run: {{cmdroot|modprobe -r ide_cd && modprobe -r cdrom && echo "MSTR eject" > /proc/acpi/lths}}

===HAL support===

HAL support also can also be configured To do so, create the file {{path|/etc/hal/fdi/information/10-ultrabay.fdi}} as follows:
<pre>
<?xml version="1.0" encoding="UTF-8"?> 

<deviceinfo version="0.2">
<device>


<match key="storage.bus" string="ide">
<match key="storage.physical_device" string="/org/freedesktop/Hal/devices/pci_8086_24ca_ide_1_0">
<merge key="storage.hotpluggable" type="bool">true</merge>
</match>
</match>

</device>
</deviceinfo>
</pre>
For more details see HAL section for ata driver.

==Password protected HDD==

If you are hot-swapping a hard disk on a Ultrabay HDD tray, and the HDD has a password set, you will have to enter the password before it can be used. Example:
hdparm /dev/sdb --security-unlock

[[Category:Scripts]]
[[Category:HOWTOs]]