
Driver Disk Installation Guide for ARC-11XX/ARC12XX/ARC16XX/18XX RAID Controller 
         on Fedora 28 (kernel 4.16.3-301.fc28)
=================================================================================
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 Fedora 28
arcmsr_fc28.zip - Areca RAID driver for system installation
kmod-arcmsr-1.50.0X.05-1.fc28.x86_64.rpm    - arcmsr driver for x86_64
arcmsr-1.50.0X.05-20210429.zip  - arcmsr 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. First installation
**********************************************************************************
A. Before Installation 

   Fedora 28 kernel default driver has support Areca all Raid controllers except ARC-1886.
   So just following the Fedora 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 reference to
   Areca Raid controllers user's manual.

    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 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/mmx64.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 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.


   For installation Fedora 28 onto ARC-1886 Raid volume, following below steps.
   Extract arcmsr_fc28.zip and copy public_key.der to top(/) directory of an USB flash drive .
   Give a label to this USB flash drive, said ARECA.

B. For Server Installation
	1. Booting from Fedora Installation DVD disc.
	2. When the Installation screen appears, move cursor UP to "Install Fedora 28".
	   Press Enter to start system installation.
	3. When 'Welcom to Fedora 28' was displayed, press CTRL+ALT+F2 to open a command console.
	   Login as root.
	4. Insert USB flash drive to target system.
	   # mkdir /arcmsr /tmp/arcmsr
	   # mount /dev/sda1 /arcmsr
	   # cp /arcmsr/* /tmp/arcmsr
	   # umount /arcmsr
	5. Remove the USB flash drive from the USB port and then type:
	   Press Alt+F6 to back to 'Welcom to Fedora 28' GUI, go on the system installtion.
	6. In INSTALLATION DESTINATION page, if you can not find hard drive(s) to install OS, click the Refresh at Bottom right corner
	   to rescan hard drive(s).
	7. When Fedora was successfully installed and prompts you to Quit, press CTRL+ALT+F2 to command console
	   # mkdir /mnt/sysimage/tmp/arcmsr
	   # cp /tmp/arcmsr/* /mnt/sysimage/tmp/arcmsr
	   # chroot /mnt/sysimage
	   # cd /tmp/arcmsr
	   # chmod +x post-install.sh
	   # ./post-install.sh
	   # exit
	8. Press ALT+F6 to back to system installation GUI and Reboot. 


C. For Workstation Installation
	1. Booting from Fedora Installation DVD disc.
	2. When the Installation screen appears, move cursor UP to "Start Fedora-Workstation-Live 28".
	   Press Enter to start system.
	3. When 'Welcom to Fedora' was displayed, press Ctrl+Alt+F2 to open a terminal console.
	   Login as root.
	4. Insert USB flash drive to target system.
	   # mkdir /arcmsr /tmp/arcmsr
	   # mount /dev/sda1 /arcmsr
	   # cp /arcmsr/* /tmp/arcmsr
	   # umount /arcmsr
	5. Remove the USB flash drive from the USB port and then type:
	   Press Alt+F1 to back to 'Welcom to Fedora' GUI, click "Install to Hard Drive" to install system.
	6. When Fedora was successfully installed and prompts you to Quit, press CTRL+ALT+F2 to command console
	   # mkdir /mnt/sysimage/tmp/arcmsr
	   # cp /tmp/arcmsr/* /mnt/sysimage/tmp/arcmsr
	   # chroot /mnt/sysimage
	   # cd /tmp/arcmsr
	   # chmod +x post-install.sh
	   # ./post-install.sh
	   # exit
	7. Press ALT+F1 to back to system installation GUI and Quit. 

**********************************************************************************
3. Installing raid driver on an Existing System.
**********************************************************************************
	login as root
	============= 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
	=======================================================

	# rpm -ivh kmod-arcmsr-1.50.0X.05-1.fc28.$(uname -m).rpm
	# xz -f /lib/modules/$(uname -r)/updates/arcmsr.ko
	# 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 driver, you have to install kernel-devel.
	# yum install kernel-devel-$(uname -r)

	If you do not have installed gcc compiler.
	# yum install gcc

	To compile arcmsr driver, extract driver source code 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 and public key for each time you build new driver.
	# /usr/src/kernels/$(uname -r)/scripts/sign-file sha256 ./private_key.priv ./public_key.der ./arcmsr.ko
	
	Enroll public_key.der to MOK database as state in above 2.- A.
	========================================================================================================

	# xz arcmsr.ko
	# cp -f arcmsr.ko.xz  /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 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 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.

    To build and install tbtadm utility:

    0. # sudo dnf install cmake boost-devel txt2tags gcc-c++
    1. 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')
    2. Extract thunderbolt-software-user-space-master.zip.
    3. # cd thunderbolt-software-user-space-master
    4. # mkdir build
    5. # cd build
    6. # sudo cmake -DCMAKE_CXX_COMPILER=/usr/bin/g++ -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr ..
    7. # sudo cmake --build . --target install

    Following the instruction of readme file on package source to make thunderbolt adapter in ACL.
    i.e. # tbtadm devices
	 # tbtadm approve 0-1

    NOTE!!! If you upgrade to Fedora higher version or kernel, you may need to remove both thunderbolt-software-user-space-master and build directories.
            And redo above steps 2 to 7 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.16.3-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/fedora/grub.cfg
       Append driver parameter setting to end of line that include "linux   /boot/vmlinuz-x.xx.xx ....."

       linux   /boot/vmlinux-4.16.3-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
          # 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, ...
