Driver Disk Installation Guide for ARC-11XX/ARC12XX/ARC16XX/18XX RAID Controller 
on Ubuntu 18.04.2 x86_64(kernel 4.15.0-45, 4.18.0-15)
=================================================================================
=================================================================================
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 Areca Raid driver for Ubuntu
arcmsr-ubuntu-18.04.2.zip	- Areca RAID driver disk for system installation
arcmsr-modules-4.15.0-45-generic.x86_64.deb  - driver for kernel 4.15.0-45
arcmsr-modules-4.15.0-142-generic.x86_64.deb - driver for kernel 4.15.0-142
arcmsr-modules-4.15.0-144-generic.x86_64.deb - driver for kernel 4.15.0-144
arcmsr-modules-4.18.0-15-generic.x86_64.deb  - driver for kernel 4.18.0-15
arcmsr-modules-5.4.0-74-generic.x86_64.deb  - driver for kernel 5.4.0-74
arcmsr-1.50.00.09-source-only.dkms.tar.gz - DKMS enabled driver source code
arcmsr-1.50.0X.09-20220309.zip	- driver source code

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

A. Before Installation

   Extract arcmsr-ubuntu-18.04.2.zip to an USB flash drive.

    If you would like system boots with UEFI Secure Boot, following condition must be satisfied in BIOS setup.
    Or system may not boot properly.
	1. Set "Secure Boot" to "Enabled".
	2. Set "Secure Boot Mode" to "Custom".
	3. Set "Csm support" to "Disabled".
	4. Install all manufacture defaults to Platform Key(PK), Key Exchange Key(KEK), Authorized Signatures(DB), 
	   Forbidden Signatures(DBX).
	5. Set "CPU slot PCI-E Device OPROM (Option ROM)" to "EFI" or "UEFI", if any.
	6. Areca Raid controller System controls->Advanced configuration->BISO selection set to UEFI or AUTO. 
	  (This can be done by web browser through Raid controller Ethernet port. Please refer to areca Raid controller user manual.)
	7. Add Areca Linux driver's public key to Authorized signature database(DB) or Machine Owner Key(MOK) database.
	8. OS is 64 bits version, CPU is 64 bits, and both support UEFI specification.

	 
    You must add Areca Linux driver's public key to the MOK before installing operation system. 
    If Areca Linux driver's public key has been in the MOK of system NVRAM, it is not necessary to do it again.

    To add Areca Linux driver's public key to the MOK database, select one of two method to do.

    =============================================================
    1. Enroll public_key.der to MOK database by mmx64.efi
    =============================================================
	Copy Areca public_key.der and mmx64.efi to an USB flash drive with label name ARECA.
	a. Insert the USB flash drive to the target system.
	b. Insert Installation DVD disc to DVD drive.
	c. Booting from UEFI: CD/DVD drive.
	d. When grub2 boot menu show up, type c to get into grub CLI.
	   At grub console, input following command.

		grub> chainloader (hdx,1)/mmx64.efi
		      where hdx may be hd1, hd2, or, .... It represents USB flash device.
		grub> boot

	e. When "shim EFI key management" page show up, press Enter.
	f. When "Perform MOK management" menu show up, move cursor to "Enroll key from disk", then press Enter.
	g. When "Seclect Key" menu show up, move cursor to "ARECA", then press Enter.
	   Move cursor to "publick_key.der", then press Enter.
	h. When "[Enroll MOK]" menu show up, move cursour to "continue", then press Enter.
	i. When "Enroll the key(s)?" menu show up, move cursor to "Yes", then press Enter.
	j. When "Perform MOK management" menu show up again, move cursor to "continue to boot", then press Enter.
	k. When back to grub CLI, press Esc.

	The public key is added to the MOK list now, which is persistent.
	Once a key is on the MOK list, it is propagated automatically to the system key ring for this and subsequent 
	reboots, when uEFI Secure Boot is enabled.

    ======================================================
    2. Enroll public_key.der to MOK database by "mokutil"
    ======================================================
	Copy Areca public_key.der to home directory.
	a. In installed OS, open a terminal console.
	   # sudo mokutil --import public_key.der
	   
	   When prompted, enter a password of your choice. 
	   This password will be used when enrolling the key into the MOK list(at step g.).

	b. Reboot your system.

	c. Upon rebooting, the "Shim UEFI key management" screen appears. 
	   Press Enter to proceed.

	d. Perform MOK management
	   Select: Enroll MOK

	e. [Enroll MOK]
	   Select: View key 0
	   Select: Continue

	f. Enroll the key(s)?
	   Select: Yes

	g. Enroll the key(s)?
	   Password:      <------ give the password that previously requested by mokutil(at step a.)

	h. Reboot the system?
	   Select: OK

	The key is now enrolled.


B. Install ubuntu server

	1) Start Ubuntu installation by booting from Ubuntu installation DVD disc.
	2) On the Welcom screen, if you select "Install Ubuntu Server", then press Enter and go to next step.
	   If you select "Install Ubuntu Server with the HWE kernel", HWE kernel had supported all areca RAID adapters,
	   you just follow normal Ubuntu installation procedure and ignore following steps except you want to update
	   driver by this one.
	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 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
	   Press "Alt+F1" back to installation screen.
	7) Continue the installation process. 
	8) In case of been stuck at 66% of 'Running Update grub' very long time, press "CTRL+ALT+F2" to console.
	   # ps | grep 'dmsetup create'
	   Kill this process by its process number.
	   # kill xxxxx
	   Press "Alt+F1" back to installation screen.
	9) 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
	10) Press "Alt+F1" to continue. 

C. Install ubuntu Desktop

	Ubuntu Desktop kernel had supported all areca RAID adapters, you just follow normal Ubuntu installation procedure
	and ignore following steps except you want to update driver by this one.
	   
	1) Insert the Areca driver USB flash disk to target system.
	2) Start Ubuntu installation by booting from Ubuntu installation DVD disc.
	3) On the Ubuntu menu, stay cursor at "Try Ubuntu without installing", then press Enter.
	4) At Ubuntu desktop, open a terminal console.
	5) Type the following commands:
	   # mount
	   Find the driver USB device /dev/sda1 mount point, and unmount it.
	   # 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) Click th "Install Ubuntu 18.04.2" icon, to start Ubuntu system installation.
	8) Do not reboot after the installation is complete.
	   Switch to terminal console and type the following commands:
	   # mkdir /target/tmp/arcmsr
	   # cp /tmp/arcmsr/* /target/tmp/arcmsr
	   # sudo chroot /target
	   # cd /tmp/arcmsr
	   # sudo ./post-install.sh
	   # exit
	9) Now you can restart 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 especially on Ubuntu desktop.
           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.

	# sudo dpkg -i arcmsr-modules-x.x.x-x-generic.x86_64.deb
	  where x.x.x-x is kernel version
	# 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.50.00.09
	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., 4.15.0-45-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

	Unzip arcmsr-1.50.0X.09-20220309.zip to a directory and change to.
	# 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)
	# sudo insmod arcmsr.ko

**********************************************************************************
6. To support Areca thunderbolt device and cable hotplug
**********************************************************************************

Ubuntu Desktop:
===============
	Ubuntu 18.04.2 desktop has native support Areca thunderbolt 2 & 3 devices, ARC-8050T2/T3 series.
	With connecting the thunderbolt cable, it will detect devices automatically.
	Hot-plug cable, will request password for authorising.

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

Ubuntu Server:
==============
	Ubuntu 18.04.2 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/vmlinux-4.15.0-45..... ... ... $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.15.0-45..... ... ... $vt_handoff 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, ...
