Driver Disk Installation Guide for ARC-11XX/ARC12XX/ARC16XX/18XX RAID Controller 
on Ubuntu 20.04.5 x86_64(kernel 5.4.0-125, 5.15.0-46)
=================================================================================
=================================================================================
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 Ubuntu
arcmsr-ubuntu-20.04.5.zip	- Areca RAID driver disk for system installation
arcmsr-modules-k5.4.0-125-generic.x86_64.deb  - driver for Ubuntu kernel 5.4.0-125
arcmsr-modules-k5.15.0-46-generic.x86_64.deb  - driver for Ubuntu kernel 5.15.0-46
arcmsr-1.51.00.15-source-only.dkms.tar.gz - DKMS enabled driver source code
arcmsr-1.51.0X.15-20230915.zip	- driver source code
genkey.cfg	- configuration file for generating public and private key pair
public_key.der	- public key for pre-compiled driver arcmsr in .rpm and .iso first time installation

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

   Ubuntu 20.04.5 kernel built-in arcmsr driver has supported Areca all Raid controllers except ARC-1886, ARC-1688.
   So just following the Ubuntu 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 refer to
   Areca Raid controllers user's manual.

  For installation Ubuntu 20.04.5 onto ARC-1886, ARC-1688 Raid volume, following below steps.
  
	0) Extract arcmsr-ubuntu-20.04.5.zip to an USB flash drive.

    A. Installing ubuntu server
    ===========================
  [NOTE!]: For ARC-1200/1201/1203 install on newer M/B, kernel build-in arcmsr driver may can not use to install system.
           It is need to update arcmsr driver by below steps.

	1) Start Ubuntu installation by booting from Ubuntu installation DVD disc.

	For ARC-1886 =====
	2) On the GNU GRUB menu, select "Install Ubuntu Server", then press Enter.

	For ARC-1200/1201/1203 =====
	2) On the GNU GRUB menu, select "Install Ubuntu Server", type e to edit kernel command option.
	   Append ` modprobe.blacklist=arcmsr' to the end of line that contain `vmlinuz'.
	   Then press Ctrl-x to boot.

	3) At "Select a language" screen, Press "CTRL+ALT+F2" to switch to console.
	4) Insert the Areca driver USB flash disk to target system.
	5) Type the following commands:
	   # sudo rmmod arcmsr
	   # sudo mkdir /arcmsr /tmp/arcmsr
	   # sudo mount /dev/sda1 /arcmsr
	   # sudo cp -f /arcmsr/* /tmp/arcmsr
	   # sudo umount /arcmsr
	6) Remove the USB flash drive from the USB port and then type:
	   # cd /tmp/arcmsr
	   # sudo ./pre-install.sh
	7) Press "Alt+F1" back to installation process. 
	8) After the installation is complete and before rebooting. press "Ctrl+Alt+F2" to
	   switch to console 2 and type the following commands:
	   # sudo mkdir /target/tmp/arcmsr
	   # sudo cp /tmp/arcmsr/* /target/tmp/arcmsr
	   # sudo chroot /target
	   # cd /tmp/arcmsr
	   # sudo ./post-install.sh
	   # exit
	9) Press "Alt+F1" to continue or reboot. 

    B. Installing ubuntu Desktop
    ============================
    	20.04.5 desktop kernel 5.15.0-46 build-in driver has supported all Areca Raid controllers except ARC-1688.
    	You can ignore following step except you want to update to this new one.
	1) Insert the Areca driver USB flash disk to target system.
	2) Start Ubuntu installation by booting from Ubuntu installation DVD disc.
	   When Ubuntu disc is being access, press e periodically until select installation language show-up.
	3) On the Ubuntu menu, move cursor to "Install Ubuntu", then press F6 function key, follow by press ESC key.
   	   Append "modprobe.blacklist=arcmsr" to end of kernel boot options, then press Enter.
	4) At 'Welcome' to select installing language, press Ctrl+Alt+F2 to open a terminal console.
	   Login with 'ubuntu' without password.
	5) Type the following commands:
	   # sudo mkdir /arcmsr /tmp/arcmsr
	   # sudo mount /dev/sda1 /arcmsr
	   # sudo cp -f /arcmsr/* /tmp/arcmsr
	   # sudo umount /arcmsr
	6) Remove the USB flash drive from the USB port and then type:
	   # cd /tmp/arcmsr
	   # sudo chmod +x *.sh
	   # sudo ./pre-install.sh
	7) Press Alt+F1 to back to Ubuntu installation.
	8) Do not reboot after the installation is complete.
	   Switch to terminal console and type the following commands:
	   # sudo mkdir /target/tmp/arcmsr
	   # sudo cp /tmp/arcmsr/* /target/tmp/arcmsr
	   # sudo chroot /target
	   # cd /tmp/arcmsr
	   # sudo ./post-install.sh
	   # exit
	   # sudo chmod +w /target/boot/grub/grub.cfg
	   # sudo vi /target/boot/grub/grub.cfg
	   Remove all the string 'modprobe.blacklist=arcmsr'.
	9) Press Alt+F1, now you can reboot the system. 

**********************************************************************
3. Installing raid driver on an existed System	
**********************************************************************
  [NOTE!]: For ARC-1200/1201/1203 install on newer M/B, kernel build-in arcmsr driver may cause system boot error or hang.
           To let system boot success, disable arcmsr driver loading is necessary.
	   At GRUB menu during system boot, type e to edit kernel command line option.
	   Append ` modprobe.blacklist=arcmsr' to the end of line that contain `vmlinuz'.
	   Then press Ctrl-x to boot.

	login as root or su
	Depends on your current kernel version.
	# sudo dpkg -i arcmsr-modules-k5.4.0-xx-generic.x86_64.deb
		or
	# sudo dpkg -i arcmsr-modules-k5.15.0-xx-generic.x86_64.deb

	# sudo depmod -a
	# sudo update-initramfs -u

	Reboot your system to make arcmsr driver take effect.

**********************************************************************************
4. To install DKMS enabled tarball of arcmsr driver on an existed System.
**********************************************************************************
	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.15
	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., 5.4.0-125-generic.
	
	After installed linux header files, DKMS service will build and install arcmsr driver for new kernel automatically.

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

	To compile arcmsr driver, extract driver source code to a new directory.
	# sudo make KDIR=/lib/modules/$(uname -r)/build

	# 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.


**********************************************************************************
6. To support Areca thunderbolt device and cable hotplug
**********************************************************************************
Ubuntu Desktop:
===============
	Ubuntu 20.04.5 has native support Areca thunderbolt 2 & 3 devices, ARC-8050T2/T3 series.
	But it needs root user to authorised permission after connect the thunderbolt cable.

	The first time of connection thunderbolt device to system, it may need to authorize the device to system.
	From GNOME Settings->Privacy->Thunderbolt, click the 'connected' but not yet authorized device,
	confirm the 'authorize and connect' to make it 'authorized'.

Ubuntu Server:
==============
	Ubuntu 20.04.5 Server also has native support Areca thunderbolt 2 & 3 devices, ARC-8050T2/T3 series.
	But it needs root user to authorise permission after connect the thunderbolt devices.

	1. Find the thunderbolt deivce's UUID.
	   # 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-5.4.0-125..... ... ...  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-5.4.0-125..... ... ...  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, ...
