Driver Disk Installation Guide for ARC-11XX/ARC12XX/ARC16XX/18XX RAID Controller 
on TrueNAS-SCALE 23.10.1 amd64(kernel 6.1.63-production+truenas)
=================================================================================
=================================================================================
Linux SCSI driver technical support 
Mail address: support@areca.com.tw
Web site: www.areca.com.tw
==================================================================================
==================================================================================

**********************************************************************************   
1. Contents
**********************************************************************************
readme.txt	- the installation guide of ARC-11XX/12XX/16XX/18XX driver for TrueNAS-SCALE
arcmsr-TrueNAS-SCALE-23.10.1.zip	  - Areca RAID driver disk for system installation
arcmsr_1.51.0X.16-TNS23.10.1_amd64.deb    - driver for x86_64
arcmsr-1.51.0X.16-20231226.zip		  - driver source code
arcmsr-1.51.00.16-source-only.dkms.tar.gz - DKMS enabled driver source code

**********************************************************************
2. System Installation                                 	    **
**********************************************************************

    TrueNAS-SCALE 23.10.1 kernel default driver has support Areca all Raid controllers except ARC-1688.
    So just following the installation guide to install system to on-board hard drive or Areca Raid volume.
    In case of installation to Areca Raid volume, 
    you should first create a Raid volume by reference to Areca Raid controllers user's manual.

    For install TrueNAS-SCALE 23.10.1 onto Areca ARC-1688 Raid volume or update driver, following below steps.

	0) Extract arcmsr-TrueNAS-SCALE-23.10.1.zip to an USB flash drive.
	1) Insert the Areca driver USB flash disk to target system.
	2) Start TrueNAS-SCALE installation by booting from TrueNAS-SCALE installation media.
	3) On the TrueNAS 23.10.1 Console Setup, select "2 Shell" then press Enter.
	4) Type the following commands: (here we assume USB drivr disk is sde device)
	   # rmmod arcmsr
	   # mkdir /arcmsr /tmp/arcmsr
	   # mount /dev/sde1 /arcmsr
	   # cp -f /arcmsr/* /tmp/arcmsr
	   # umount /arcmsr
	5) Remove the USB flash drive from USB port.
	   # cd /tmp/arcmsr
	   # sh ./pre-install.sh
	   # exit
	6) On "TrueNAS 23.10.1 Console Setup", continue the installation process. 
	7) When TrueNAS installation succeeded, and GUI come to "TrueNAS 23.10.1 Console Setup" again,
	   move cursor to '2 Shell', then press Enter.
	   # zpool import boot-pool
	   Find the ROOT directory
	   # zfs list
	   # zfs set mountpoint=/arcmsr boot-pool/ROOT/23.10.1
	   # mkdir /arcmsr/tmp/arcmsr
	   # cp /tmp/arcmsr/* /arcmsr/tmp/arcmsr
	   # chroot /arcmsr
	   # cd /tmp/arcmsr
	   # sh ./post-install.sh
	   # exit
	   # zfs set mountpoint=legacy boot-pool/ROOT/23.10.1
	press "Ctrl+Alt+F1" to back to reboot page and 'OK' to reboot.

**********************************************************************
3. Installing raid driver on your System	
**********************************************************************
   If your Linux system can use Areca Raid volume normally, you need not to install driver package.

        if your target kernel version is not 'uname -r', then replace following
        $(uname -r) by real target kernel version

	# chmod +x /usr/bin/*
	# sudo dpkg -i arcmsr_1.51.0X.16-TNS23.10.1_amd64.deb
	# sudo depmod -a $(uname -r)
	# sudo update-initramfs -u -k $(uname -r)

	Reboot your system to make arcmsr driver take effect.

**********************************************************************************
4. To compile arcmsr driver on your System.
**********************************************************************************
   If your Linux system can use Areca Raid volume normally, you need not to compile driver for it.
   If areca pre-build driver(arcmsr...deb) can not fit for your kernel, then you need compile
   driver for it by yourself.

        if your target kernel version is not (uname -r), then replace following
        $(uname -r) by real target kernel version

	# sudo chmod +x /usr/bin/*
	# sudo apt-get update
	# sudo apt-get install gcc make
	Unzip arcmsr-1.51.0X.16-20231226.zip to a directory and change to.
	# make KVER=$(uname -r)

	# sudo cp -f arcmsr.ko /lib/modules/$(uname -r)/kernel/drivers/scsi/arcmsr/
	# sudo depmod -a $(uname -r)
	# sudo update-initramfs -u -k $(uname -r)

	Reboot your system to make arcmsr driver take effect.

**********************************************************************************
5. To install DKMS enabled tarball of arcmsr driver on an existed System.
**********************************************************************************
	In case of updating software packages, the kernel's version could be change.
	If the new kernel built-in driver can not support your Raid controller, then install dkms package
	and install areca dkms-able driver source tarball is a good solution.
	Once kernel was updated, it compiles and installs driver for new kernel automatically.

	Before using DKMS, you must install DKMS package. You can install dkms as following.
	# sudo apt-get install dkms

	Copy arcmsr DKMS enabled tarball to home directory.
	In order to load tarball into the DKMS tree, you must use the following command:

	# sudo dkms ldtarball --archive=./arcmsr-<module version>-source-only.dkms.tar.gz
	where <module version> could be, e.g., 1.51.00.16
	arcmsr source code will be added to DKMS tree.
	
	To build arcmsr driver module
	# sudo dkms build -m arcmsr -v <module version>
	
	To install arcmsr driver module
	# sudo dkms install -m arcmsr -v <module version>

	If you are upgrading linux kernel, then you have to install the corresponding linux-headers-<kernelver> before
	reboot your system. New kernel image can be find in /boot, corresponding new linux header can be find in /usr/src.
	If you can not find new linux header in /usr/src, you can install it as following.
	# sudo apt-get install linux-headers-<kernelver>
	where <kernelver> could be, e.g., 6.1.63-production+truenas.
	
	After installed linux header files, DKMS service will build and install arcmsr driver for new kernel automatically.

**********************************************************************************
6. To support thunderbolt cable hotplug
**********************************************************************************

	TrueNAS-SCALE 23.10.1 has native support Areca thunderbolt 2 & 3 devices, ARC-8050T2/T3 series.
	The first time of connection thunderbolt device to system, it may need to authorize the device to system.

	1. Find the thunderbolt deivce's UUID.
	   # chmod +x /usr/bin/apt*
	   # chmod +x /usr/bin/dpkg*
	   # sudo apt-get update
	   # sudo apt-get install bolt
	   # boltctl list

	2. Give an authorised permission to thunderbolt devices
	   # boltctl authorize UUID
	   	where UUID is thunderbolt device's UUID, like 00000000-0000-0008-0015-5f0b2012a051
	   Now detecting devices start, just a moment you will can access thunderbolt devices.


**********************************************************************************
7. To set driver parameters value
**********************************************************************************
    arcmsr provided driver parameters setting since v1.30.0X.25.
    Multiple Driver parameters can be set at a time.
    e.g. # insmod arcmsr.ko host_can_queue=72 cmd_per_lun=16

    Setting parameter value out of range will be ignored, parameter remain default value.

    a. To list what driver parameter can be set, parameter default value and value range.
       # modinfo arcmsr

    b. To set driver parameter when you manually install driver.
       (This method will be infeasible if your system was boot from areca Raid volume.)
       e.g. to set parameter host_can_queue value to 64
       # sudo rmmod arcmsr
       # sudo insmod /lib/modules/$(uname -r)/kernel/drivers/scsi/arcmsr/arcmsr.ko host_can_queue=64

    c. To set driver parameter during booting from grub menu.
       When grub menu display, use UP and DOWN arrow key to move cursor to booting target.
       Type e to edit, move cursor to end of line that include "linux   /boot/vmlinuz-x.xx.xx ....."
       Append driver parameter to there.(e.g. to set parameter host_can_queue value to 64)

       linux  .../boot/vmlinuz-6.1.63-production+truenas..... ... ... zfsforce=1 arcmsr.host_can_queue=64

    d. To set driver parameter for every boot up.
       e.g. to set parameter host_can_queue value to 64
       # sudo gedit /boot/grub/grub.cfg
       Append driver parameter setting to end of line that include "linux   /boot/vmlinuz-x.xx.xx ....."

       linux  .../boot/vmlinuz-6.1.63-production+truenas..... ... ... zfsforce=1 arcmsr.host_can_queue=64

    e. To verify parameter setting is correct.
       1. To locate adapter parameter directory
          Find Areca host number:
          # dmesg | grep 'scsi host'
          # cat /sys/class/scsi_host/hostX/proc_name
                where hostX could be host0, host1, ...
          The correct output should be 'arcmsr'. If output is (null), check host_fw_model and host_driver_version.
          # cat /sys/class/scsi_host/hostX/host_fw_model
          # cat /sys/class/scsi_host/hostX/host_driver_version

       2. List host_can_queue value
          #  cat /sys/class/scsi_host/hostX/can_queue

       3. List cmd_per_lun value
          #  cat /sys/class/scsi_host/hostX/cmd_per_lun

       4. List cmd_timeout value
          #  cat /sys/block/sdX/device/cmd_timeout
             where sdX could be sda, sdb, ...
