
Driver Installation Guide of ARC-11XX/ARC12XX/ARC16XX/18XX RAID Controller 
  for ORACLE Linux 7.5(kernel 3.10.0-862.el7.x86_64, 4.1.12-112.16.4.el7uek.x86_64)
=================================================================================
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 ORACLE Linux 7.5
arcmsr-1.50.0X.11-oracle7.5.iso	- Areca RAID driver for Linux system installation
kmod-arcmsr-1.50.0X.11_oracle7.5-3.10.0-862-1.x86_64.rpm  - driver for kernel 3.10.0-862.el7.x86_64
kmod-arcmsr-1.50.0X.11_oracle7.5-4.1.12-112-1.x86_64.rpm  - driver for kernel 4.1.12-112.16.4.el7uek.x86_64
arcmsr-1.50.0X.11-20220601.zip                 - arcmsr driver source code
arcmsr-1.50.00.11-source-only.dkms.tar.gz      - arcmsr DKMS enabled driver source code
genkey.cfg	- configuration file for generating public and private key pair
public_key.der	- public key of pre-compiled driver arcmsr.ko in .rpm and .iso for first time installation

**********************************************************************************
2. First installation
**********************************************************************************
A. Before Installation 
======================
    Copy arcmsr-1.50.0X.11-oracle7.5.iso. *.rpm and public_key.der to top(/) directory of an USB flash drive .
    Give a label to this USB flash drive, said ARECA.

    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.


B. Installation
===============
	a. Insert the USB flash drive to the target system.
	b. Booting from Installation DVD disc.

    For choice legacy DVD drive to install:
    =======================================
	c. When the Installation screen appears, move cursor UP to "Install Oracle Linux 7.5".

	   Press Tab to edit boot command line option.

	   At the end of command line, append " inst.dd"
	   (double quotation mark are not include).

	   Press Enter to start system installation.

    For choice UEFI DVD drive to install:
    =====================================
	c. When the Installation screen appears, move cursor UP to "Install Oracle Linux 7.5".

	   type e to edit kernel boot option.

	   At the end of command line that include "linuxefi /images/pxeboot/vmlinuz" append " inst.dd"
	   (double quotation mark are not include).

	   Press Ctrl-x to start system installation.


	d. When following messages show up, type the line number that line with the LABEL of USB flash drive.

	   (Page 1 of 1) Driver disk device selection
	       /DEVICE  TYPE     LABEL                UUID
	    1) sr0      iso9660  OL-7.5\x20Server.x86 2018-04-12-16-49-52-00
	    2) sda1     vfat     ARECA                60A4-83FC

	   In this example, type 2 and press Enter
	   
	   (Page 1 of 1) Choose driver disk ISO file
	    1) /media/DD-1/arcmsr-1.50.0X.11-Oracle7.5.iso
	     
	   In this example, type 1 and press Enter
	   
	------------------------------------------------
	For boot from x86_64-boot or x86_64-dvd image:
	   (Page 1 of 1) Select drivers to install
	    1) [ ] /media/DD-2/rpms/x86_64/kmod-arcmsr-1.50.0X.11_oracle7.5-3.10.0-862-1.x86_64.rpm
	     
	   In this example, type 1 and press Enter
		   
	   (Page 1 of 1) Select drivers to install
	    1) [x] /media/DD-2/rpms/x86_64/kmod-arcmsr-1.50.0X.11_oracle7.5-3.10.0-862-1.x86_64.rpm
	------------------------------------------------

	================================================
	For boot from x86_64-boot-uek image:
	   (Page 1 of 1) Select drivers to install
	    1) [ ] /media/DD-2/rpms/x86_64/kmod-arcmsr-1.50.0X.11_oracle7.5-4.1.12-112-1.x86_64.rpm
	    2) [ ] /media/DD-2/rpms/x86_64/kmod-arcmsr-1.50.0X.11_oracle7.5-3.10.0-862-1.x86_64.rpm
	     
	   In this example, type 1 and press Enter
		   
	   (Page 1 of 1) Select drivers to install
	    1) [x] /media/DD-2/rpms/x86_64/kmod-arcmsr-1.50.0X.11_oracle7.5-4.1.12-112-1.x86_64.rpm
	    2) [ ] /media/DD-2/rpms/x86_64/kmod-arcmsr-1.50.0X.11_oracle7.5-3.10.0-862-1.x86_64.rpm
	===============================================		   
		     
	   In this example, type c and press Enter
		   
	e. After driver installation, type c and press Enter to continue the system installation. 

	f. After system installation complete and ready for reboot, press Ctrl+Alt+F2 to terminal console.
	   # chroot /mnt/sysimage
	   # mkdir /mnt0
	   # mount /dev/sda1 /mnt0
	   # rpm -ivh --force /mnt0/kmod-arcmsr-1.50.0X.11_oracle7.5-4.1.12-112-1.x86_64.rpm
	   # umount /mnt0
	   # exit

	g. Press Alt+F6 backing to GUI, click "Reboot".
**********************************************************************************
3. Installing raid driver on an Existing System.
**********************************************************************************
	login as root

	# rpm -ivh --force kmod-arcmsr-1.50.0X.11_oracle7.5-3.10.0-862-1.x86_64.rpm
	# rpm -ivh --force kmod-arcmsr-1.50.0X.11_oracle7.5-4.1.12-112-1.x86_64.rpm
	# depmod -a
	# reboot

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

	Before you can compile a new driver, you have to install kernel-headers and kernel-devel.
	These two rpm packages are in ORACLE LINUX 7.5 DVD installation disc /Packages.
	# rpm -ivh kernel-headers-$(uname -r).rpm
	# rpm -ivh kernel-devel-$(uname -r).rpm
	# rpm -ivh kernel-uek-devel-$(uname -r).rpm

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

	# ls /lib/modules/$(uname -r)/kernel/drivers/scsi/arcmsr
	If it is arcmsr.ko.xz, then {
	    # xz arcmsr.ko
	    # cp -f arcmsr.ko.xz /lib/modules/$(uname -r)/kernel/drivers/scsi/arcmsr
	}
	else {
	    # cp -f arcmsr.ko /lib/modules/$(uname -r)/kernel/drivers/scsi/arcmsr
	}

	# depmod -a $(uname -r)

	If your system was booted from Areca volume, you have to rebuild initial ramdisk.
	# dracut --kver $(uname -r)
	# reboot

**********************************************************************************
5. To install DKMS enabled tarball of arcmsr driver on an Existing System.
**********************************************************************************
	Login as root or as superuser.

	Before you can compile a new driver, you have to install kernel-headers and kernel-devel.
	These two rpm packages are in ORACLE LINUX 7.5 DVD installation disc /Packages.
	# rpm -ivh kernel-headers-$(uname -r).rpm
	# rpm -ivh kernel-devel-$(uname -r).rpm

	Download DKMS package dkms-<dkmsversion>.noarch.rpm from http://linux.dell.com/dkms/
	Before using DKMS, you must install DKMS package. You can install dkms as following.
	# rpm -ivh dkms-<dkmsversion>.noarch.rpm
	where <moduleversion> is dkms version could be, e.g., 2.2.0.3-1

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

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


	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.
	# rpm -ivh kernel-headers-<kernelver>.rpm
	where <kernelver> is kernel version could be, e.g., 3.10.0-862.el7.$(uname -m)
	
	After installed linux header files, DKMS service will build and install arcmsr driver for new kernel automatically.

**********************************************************************************
6. To support Areca thunderbolt device and cable hotplug
**********************************************************************************
    You have to install intel tbtadm CLI utility, in order to support Areca thunderbolt devices hotplug.
    Before you can install tbtadm, you have to download the tbtadm package source and build it by yourself.

    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.

    The following operation should be run as root user.

  A. To install a new kernel >= v4.13.13:
  ========================================================
    There is most up-to-date kernel rpm package on http://elrepo.org/linux/kernel/el7/x86_64/RPMS
    You can get kernel-ml rpm that was build from mainline Linux kernel.
    They always have the most latest two version of kernel-ml rpm package equivalent to released mainline stable kernel at that time.
    Of course, you can get earlier version from 'https://elrepo.org/tiki/Download' mirror site,
    web site URL that with 'archive' at the end.
    Open a web site with archive, in path ~/archive/kernel/el7/x86_64/RPMS/, there have some earlier build kernel.
    At this moment, I get following two rpms, then install them.
    kernel-ml-devel is need to install for making arcmsr device driver.

    kernel-ml-4.15.10-1.el7.elrepo.x86_64.rpm
    kernel-ml-devel-4.15.10-1.el7.elrepo.x86_64.rpm

    # rpm -ivh kernel-ml-4.15.10-1.el7.elrepo.x86_64.rpm
    # rpm -ivh kernel-ml-devel-4.15.10-1.el7.elrepo.x86_64.rpm

  B. Build arcmsr driver for new kernel
  ========================================================
    Before making arcmsr driver, you have to install c compiler gcc-c++ at this moment.
    # yum install centos-release-scl-rh
    # yum install devtoolset-7-gcc-c++
    # scl enable devtoolset-7 bash

    Extract arcmsr-1.50.0X.11-20220601.zip to /root/arcmsr
    # cd /root/arcmsr

    The following $KERNEL_RELEASE is 4.15.10-1.el7.elrepo.x86_64, or 'ls /lib/modules' to get installed new kernel,
    it depends on which version of new kernel you have installed on above step A.
    # make KVER=$KERNEL_RELEASE M=/root/arcmsr
    # ls /lib/modules/$KERNEL_RELEASE/kernel/drivers/scsi/arcmsr

    If it is arcmsr.ko.xz, then
        # xz arcmsr.ko
        # cp -f arcmsr.ko.xz /lib/modules/$KERNEL_RELEASE/kernel/drivers/scsi/arcmsr
    else
        # cp -f arcmsr.ko /lib/modules/$KERNEL_RELEASE/kernel/drivers/scsi/arcmsr
 
    # depmod -a
    # cd /boot
    # mv initramfs-$KERNEL_RELEASE.img initramfs-$KERNEL_RELEASE.img.old
    # dracut -k /lib/modules/$KERNEL_RELEASE --kver $KERNEL_RELEASE initramfs-$KERNEL_RELEASE.img
    # reboot

  C. Build and install tbtadm utility:
  =======================================
    Before to compile tbtadm, you need to prepare txt2tags >= 2.5-16, cmake >= 3.10.2,
    libboost >= 1.63.0. (gcc-c++ >= 7.3.0, libstdc++ >= 7.3.0 --- g++ and libstdc++ have been installed
    at step B before building arcmsr driver)

   1. Prepare developing environment - txt2tags, cmake tools, libboost, ....
   ---------------------------------------------------------------------------------
    Download txt2tags-2.5-16.el7.noarch.rpm from https://centos.pkgs.org/7/epel-x86_64/txt2tags-2.5-16.el7.noarch.rpm.html
    # rpm -ivh txt2tags-2.5-16.el7.noarch.rpm

    Download cmake-3.10.2-Linux-x86_64.tar.gz from https://cmake.org/files/v3.10/
    extract cmake-3.10.2-Linux-x86_64.tar.gz
    # cd cmake-3.10.2-Linux-x86_64
    # cp -r * /usr/local

    # scl enable devtoolset-7 bash

    To build libboost, download boost_1_63_0.tar.gz from https://sourceforge.net/projects/boost/files/boost/1.63.0/
    extract boost_1_63_0.tar.gz
    # cd boost_1_63_0
    # ./bootstrap.sh --with-libraries=filesystem,system --libdir=/usr/lib64 --includedir=/usr/include
    # ./b2 install

   2. Build tbtadm utility by cmake tool
   ---------------------------------------------------------------------------------
    To build tbtadm, 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
    # 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


**********************************************************************************
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-3.10.0-xx..... ... ... quiet LANG=en_US.UTF-8 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/grub2/grub.cfg
           or
       # sudo gedit /boot/efi/EFI/centos/grub.cfg
       Append driver parameter setting to end of line that include "linux   /boot/vmlinuz-x.xx.xx ....."

       linux   /boot/vmlinuz-3.10.0-xx..... ... ... quiet LANG=en_US.UTF-8 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, ...
