Driver Disk Installation Guide for ARC-11XX/ARC12XX/ARC16XX/18XX RAID Controller 
on debian 9.7.x amd64 and i386(kernel 4.9.0-8)
=================================================================================
=================================================================================
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 debian
arcmsr-debian-9.7.0.zip	- Areca RAID driver disk for system installation
arcmsr_1.50.0X.05-2-debian9.7.0_amd64.deb    - driver for x86_64
arcmsr_1.50.0X.05-2-debian9.7.0_i386.deb     - driver for i686
arcmsr-1.50.0X.05-20210429.zip	- driver source code

**********************************************************************
2. First time Installation                                 	    **
**********************************************************************

A. Before Installation 

   Extract arcmsr-debian-9.7.0.zip to an USB flash drive.

B. Installation

	1) Insert the Areca driver USB flash disk to target system.
	2) Start debian installation by booting from debian installation disc.
	3) On the Welcom screen, select "Install" or "Graphical install", then press Enter.
	4) When at "Partition disks" step, Press "CTRL+ALT+F2" to switch to terminal console.
	5) Type the following commands:
	   # mkdir /arcmsr /tmp/arcmsr
	   # mount /dev/sda1 /arcmsr
	   # cp -rf /arcmsr/* /tmp/arcmsr
	   # umount /arcmsr
	6) Remove the USB flash drive from the USB port and then type:
	   # cd /tmp/arcmsr
	   # sh pre-install.sh
	7) Press "Alt+F1" (or "Alt+F5" for Graphical) back to installation screen.
	   On "Partition disks" page, move cursor to <Go Back> and Enter.
	8) On "Debian installer main menu" page, move cursor to "Detect disks" and continue the installation process. 
	9) When on "Finish the installation" page, and it said installation complete. press "Ctrl+Alt+F2" to
	   switch to terminal console and type the following commands:
	   # mkdir /target/tmp/arcmsr
	   # cp /tmp/arcmsr/* /target/tmp/arcmsr
	   # chroot /target
	   # cd /tmp/arcmsr
	   # sh post-install.sh
	10) Press "Alt+F1" (or "Alt+F5" for Graphical) to continue. 

**********************************************************************
3. Installing raid driver on an Existing System	
**********************************************************************
	Install right package for your target kernel version and enter the real kernel version for
	following $(TARGET_KERNEL_VERSION).
	# su

	For x86_64 system:
	# dpkg -i --force-overwrite arcmsr_1.50.0X.05-2-debian9.7.0_amd64.deb

	For i386, i686 system:
	# dpkg -i --force-overwrite arcmsr_1.50.0X.05-2-debian9.7.0_i386.deb

	# depmod -a $(TARGET_KERNEL_VERSION)
	# update-initramfs -u -k $(TARGET_KERNEL_VERSION)
	Reboot you system to make arcmsr driver take effect.

**********************************************************************************
4. To compile arcmsr driver on an Existing System.
**********************************************************************************
        if your target kernel version is not (uname -r), then replace following
        $(uname -r) by real target kernel version

	Before you make driver module, you must have installed linux-headers.
	# su
	# apt-get install linux-headers-$(uname -r) gcc
	
	Unzip arcmsr.1.50.0X.05-20210429.zip to a directory and change to.
	# su
	# make KVER=/lib/modules/$(uname -r)/build
	# cp -f arcmsr.ko /lib/modules/$(uname -r)/kernel/drivers/scsi/arcmsr/
	# depmod -a $(uname -r)
	# update-initramfs -u -k $(uname -r)
	Reboot you system to make arcmsr driver take effect.

**********************************************************************************
5. To support thunderbolt cable hotplug
**********************************************************************************

    You have to install intel tbtadm CLI utility, in order to support thunderbolt cable hotplug.
    Before you install tbtadm you have to download the tbtadm package source and build it.

    NOTE!!! a. To support Areca thunderbolt devices, ARC-8050Tx, Linux kernel must be >= v4.13.
            b. The tbtadm utility need Linux system kernel >= 4.13.
            c. To support thunderbolt cable hotplug, arcmsr driver must be >= v1.40.0X.05-20180309.
               This version's driver was built-in in Linux kernel since v4.17.

  A. To install a new kernel >= v4.13.13:
  ========================================================
    # su
    # gedit /etc/apt/sources.list
      Append following two lines to end of file.

      deb http://ftp.us.debian.org/debian/ unstable main contrib non-free
      deb-src http://ftp.us.debian.org/debian/ unstable main contrib non-free

    # apt-get update
    # apt-get install linux-image-4.16.0-2-amd64
    # reboot

  B. Build arcmsr driver for new kernel
  ========================================================
   1. install g++-7 compiler

    # su
    # apt-get install g++-7
    # mv /usr/bin/g++-7 /usr/bin/g++
    # apt-get install make

  2. install linux-headers
    # apt-get install linux-headers-$(uname -r)

  3. Extract arcmsr.1.50.0X.05-20210429.zip to ./arcmsr
    # cd arcmsr
    # make
    # cp -f arcmsr.ko /lib/modules/$(uname -r)/kernel/drivers/scsi/arcmsr
    # depmod -a
    # update-initramfs -u
    # reboot

  C. To build and install tbtadm utility:
  ========================================================
    # su
    # apt-get install cmake libboost-filesystem-dev txt2tags pkg-config

    Download thunderbolt-software-user-space-master.zip from https://github.com/intel/thunderbolt-software-user-space
    (click the pull down menu of "Clone or download", then select 'Download ZIP')
    Extract thunderbolt-software-user-space-master.zip to thunderbolt-software-user-space-master.
    # cd thunderbolt-software-user-space-master
    # mkdir build
    # cd build
    # cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr ..
    # cmake --build . --target install

    Now tbtadm utility was installed.
    Following the instruction of readme file on tbtadm package source to make thunderbolt adapter in ACL.
    # tbtadm devices
    # tbtadm approve 0-1

    NOTE!!! If you upgrade Debian to higher version or kernel, you may need to remove both thunderbolt-software-user-space-master
            and build directories.
            And redo above steps to rebuild and install tbtadm utility, or tbtadm may not work.

**********************************************************************************
6. 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/vmlinux-4.9.0-8..... ... ... $vt_handoff 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/vmlinux-4.9.0-8..... ... ... $vt_handoff arcmsr.host_can_queue=64

    e. To verify parameter setting is correct.
       1. To locate adapter parameter directory
          # 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, ...
