Driver Disk Installation Guide for ARC-11XX/ARC12XX/ARC16XX/18XX RAID Controller 
on openSUSE 15.2(kernel 5.3.18-lp152.19)
=================================================================================
=================================================================================
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 arcsas driver for openSUSE 15.2
arcmsr-opensuse15.2.zip  - Areca Raid driver for system installation
arcmsr-1.50.0X.09-20220309.zip  - arcms driver source code
arcmsr-1.50.00.09-source-only.dkms.tar.gz - DKMS enabled 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 .ko first time installation

**********************************************************************************
2. SLES system Installation
**********************************************************************************

A. Before Installation
=========================

    Extract arcmsr-opensuse15.2.zip to the top(/) directory of an USB flash drive.
    Copy public_key.der to top(/) directory of the same 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.

	 
    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 ways to do.

    =============================================================
    1. Enroll public_key.der to MOK database by "MokManager.efi"
    =============================================================
	Copy Areca public_key.der 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 /EFI/BOOT/MokManager.efi
		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 OS, open a terminal console.
	   # 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 any key within 10 seconds 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. Start installation
========================
  [NOTE!]: For ARC-1200/1201/1203 install on newer M/B, kernel build-in arcmsr driver may not be use to install system.
           It is need to update arcmsr driver by below steps.

    openSUSE 15.2 kernel default has supported driver for all Areca Raid controllers except ARC-1886. So just following the
    installation guide to install system to on-board hard drive or Areca Raid volume. You can ignore following
    procedure, except you want to use this udpated driver.

        a. Insert the USB flash drive to the target system.
	
        b. Boot from openSUSE 15.2 DVD installation disc.
	
    For choice legacy DVD drive to install:
    =======================================
        c. Press "F6" select "Yes".

           Move cursor to hightlight "Installation", then press ENTER to install openSUSE

	 ==== For ARC-1200/1201/1203 adapters only ====
           At Boot Options line type: brokenmodules=arcmsr, then press ENTER to install openSUSE

    For choice UEFI DVD drive to install:
    =======================================
	c. When grub boot menu show up, move cursor to "Installation"
	   type e to edit kernel boot option.

	   At the end of line that include "linuxefi /boot/x86_64/loader/linux" append " dud=1"
	   (double quotation mark are not include).

	 ==== For ARC-1200/1201/1203 adapters only ====
	   At the end of line that include "linuxefi /boot/x86_64/loader/linux" append " dud=1  brokenmodules=arcmsr"

	   Press F10 to start system installation.


        d. When the message: "Driver Updates Added" show-up, and you can see "arcmsr Driver Update Disk 1",
           press Enter to continue.
	   
        e. When the message: "Please choose the driver update medium" show-up, if 
           you can see all your raid volumes appear on the medium list,
           move cursor to "Back" and press Enter to continue system installation.

           If you can't see the Areca RAID controller or raid volumes, move cursor to
           driver update media and press OK to update driver.

    For ARC-1200/1201/1203 adapters only
    ====================================
	f. When License Agreement page show, press Ctrl+Alt+F2 to tty2 console.
	   Find the update arcmsr driver file location
	   # modinfo arcmsr | grep file
	g. Load arcmsr driver
	   # insmod /lib/modules/5.3.18-57-default/initrd/arcmsr.ko
	h. Press Alt+F7 to back to License Agreement page, contine the OS installation.
	i. After system installation complete, keep installation DVD disc in DVD drive, reboot the system.
	j. Do above step a ~ g, and mount the previous installed OS partition (assume it is /dev/sdb1).
	   # mount /dev/sdb1 /mnt
	   # cp /lib/modules/5.3.18-57-default/initrd/arcmsr.ko .
	   # xz arcmsr.ko
	   # cp -f arcmsr.ko.xz /mnt/lib/modules/5.3.18-57-default/kernel/drivers/scsi/arcmsr
	   # chroot /mnt
	   Find the installed kernel version 
	   # ls /lib/modules
	   # depmod -a $KERNEL_VERSION
	     where $KERNEL_VERSION is the output of ls /lib/modules
	   # mkinitrd initrd-$KERNEL_VERSION $KERNEL_VERSION
	   # vi /etc/modprobe.d/50-blacklist.conf
	     remove the line of `blacklist arcmsr', save the change.
	   # exit
	   # Press Alt+F7 to back to License Agreement page, 'Abort' the installation and reboot.
	
**********************************************************************************
3. Installing arcmsr 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.

	============= For UEFI Secure Boot Only ==========================================
	If you had ever added areca public key to MOK list on this PC, do not do it again.
	# mokutil --import public_key.der
	# reboot
	==================================================================================

        Extract arcmsr-opensuse15.2.zip to current directory.
        # cd linux/suse/x86_64-leap15.2/install

        Install driver package.
        # rpm -ivh arcmsr-kmp-default-1.50.0X.09_opensuse15.2_k5.3.18_lp152.19-1.x86_64.rpm
        # insmod /lib/modules/$(uname -r)/updates/arcmsr.ko
	# depmod -a

	To build new init ramdisk with updated arcmsr driver for next boot-up, or system boot from Raid volume.
	# cd /boot
	# mv initrd-$(uname -r) initrd-$(uname -r).old				
	# mkinitrd initrd-$(uname -r) $(uname -r)

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

	You must have your Linux system with developmental environment and kernel source,
	in order to build kernel modules.
	When you install kernel-macros, kernel-devel, kernel default-devel, kernel-syms, checking current kernel 
	version by $(uname -r) first. Be sure to install the kernel package corresponding to current kernel version.

	# zypper install kernel-source
	# zypper install kernel-syms
	# zypper install rpm-build

	Unzip arcmsr-1.50.0X.09-20220309.zip to a new directory
	# make KDIR=/lib/modules/$(uname -r)/build

	============================ For UEFI Secure Boot Only ===========================================================
	For "UEFI Secure Boot" was Enabled in M/B BIOS, you have to generate a pair of public and private key by yourself.
	If you had ever generated key pair and added public key to MOK list once, do not do it again.

	Copy genkey.cfg to current directory, run following to generate key pair and add public key to MOK list.
	# openssl req -x509 -new -nodes -utf8 -sha256 -days 36500 -batch -config genkey.cfg -outform DER -out public_key.der -keyout private_key.priv
	# mokutil --import public_key.der

	Signing driver module with the Private Key by sign-file for each time you build new driver.
	# /usr/src/linux/scripts/sign-file sha256 ./private_key.priv ./public_key.der ./arcmsr.ko
	==================================================================================================================

	# cp -f arcmsr.ko /lib/modules/$(uname -r)/kernel/drivers/scsi/arcmsr 
	# depmod -a $(uname -r)
	# insmod arcmsr.ko

	To build new init ramdisk with updated arcmsr driver for next boot-up, or system boot from Raid volume.
	# cd /boot
	# mv initrd-$(uname -r) initrd-$(uname -r).old				
	# mkinitrd initrd-$(uname -r) $(uname -r)

**********************************************************************************
5. To install DKMS enabled tarball of arcmsr driver on an existed System.
**********************************************************************************
	You must have your Linux system with developmental environment and kernel source,
	in other words you should select the adequate packages on the menu list during installation.
	If you do not have installed these packages during system installation, you can install 
	kernel-default-devel rpm package from internet.

	Login as root.
	# zypper install kernel-default-devel-5.3.18-lp152.19.2

	Download DKMS package dkms-<dkmsversion>.noarch.rpm from http://software.opensuse.org/package/dkms or 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_git20141020-2.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.0X.09
	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 kernel-devel-<kernelver>.noarch.rpm before
	reboot your system. 
	# rpm -ivh kernel-devel-<kernelver>.noarch.rpm
	where <kernelver> is kernel version could be, e.g., 5.3.18-lp152.19.2
	
	After installed kernel devel files, DKMS service will build and install arcmsr driver for new kernel automatically.

**********************************************************************************
6. To support Areca thunderbolt device and cable hotplug
**********************************************************************************
	Opensuse 15.2 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->Devices->Thunderbolt, click the 'connected' but not yet authorized device,
	confirm the 'authorize and connect' to make it 'authorized'.

**********************************************************************************
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.3.18-xx..... ... ... quiet 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
       Append driver parameter setting to end of line that include "linux   /boot/vmlinuz-x.xx.xx ....."

       linux   /boot/vmlinuz-5.3.18-xx..... ... ... quiet 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, ...
