OneCore Storage Linux FC RAMD (ocs_fc_ramd) driver

Updated: 8-Oct-2014

Note: This README provides an abbreviated version of the description,
building instructions, and supported module parameters for the Linux
ocs_fc_ramd driver. For complete details, see the latest versions of
the OneCore Storage Quick Start Guide and the OneCore Storage Reference
Driver Manual.

Description

    The OneCore Storage Linux RAMD (ocs_fc_ramd) driver is a target driver
    that implements a non-persistant RAM disk backing store. Support is
    included for a number of SCSI commands, sufficient to allow most FC
    initiators/hosts to log into and access data.

    When loaded with initiator capability enabled, the Linux SCSI Midlayer
    initiator client is used, providing full initiator driver capability.

Unpack and Build

    Perform the following steps:

        # create a build directory
        mkdir build_dir
        cd build_dir
        # extract tar file
        tar xfv <tarfile>

    Compilation

        # move to directory containing the Makefile
        cd driver/linux/ocs_fc_ramd
        # build it
        make

    ARM-specific Instructions for Ubuntu 14.04

       There are two additional modifications needed prior to building
       the driver for ARM64 on Ubuntu 14.04:

         - Modify the MODULE_LICENSE() declaration in
           driver/linux/common/ocs_lnx.c from Proprietary to GPL.
           This modification is a workaround a temporary problem.

         - Modify the Linux header file to include/linux/skbuff.h on line
           2255 to cast the expression compared to "off" to an int. That is:
           (int)(frag->page_offset + skb_frag_size(frag))

       # native build for ARM64
       make

       # cross-compile for ARM64
       # see the following Cross-compile Environment Setup section
       # for steps to set up the cross-compile build environment
       make CROSS=arm64 KERN_SRC=<path to ARM64 kernel source>

       For example:
         KERN_SRC=/opt/ubuntu/linux-3.13.0/debian/build/build-generic/

       Cross-compile Environment Setup

          Instructions to set up a cross-compile build environment for
          ARM64 on a x86_64 host running Ubuntu 14.04.

          Note that the kernel version is modified as part of the kernel build.
          For example, the Makefile may show kernel version 3.13.11.4,
          but the resulting kernel will have a vermagic of 3.13.0-32-generic.

          1. Install the build tools if necessary:
             fetch a version matching the current kernel
             $ sudo apt-get build-dep linux-image-$(uname -r)
             or
             fetch a specific version
             $ sudo apt-get build-dep linux-image-3.13.0-36-generic
             $ sudo apt-get install kernel-wedge

          2. Install the ARM compiler:
             $ sudo apt-get install gcc-aarch64-linux-gnu

          3. Get the Linux source:
             $ cd /opt/ubuntu
             $ apt-get source linux-image-$(uname -r)
             or
             $ apt-get source linux-image-3.13.0-36-generic

          4. Install fakeroot package if not already installed:
             $ sudo apt-get install fakeroot

          5. Build the kernel source:
             $ cd linux-3.13.0
             $ export $(env CC=aarch64-linux-gnu-gcc dpkg-architecture -aarm64)
             $ env CROSS_COMPILE=aarch64-linux-gnu- fakeroot debian/rules clean
             $ env CROSS_COMPILE=aarch64-linux-gnu- fakeroot debian/rules
                      binary-headers binary-generic

          6. Patch skbuff.h:
             Modify the Linux header file include/linux/skbuff.h on line
             2255 to cast the expression compared to off to an int. I.e.:
             (int)(frag->page_offset + skb_frag_size(frag))
             - skbuff.h in the following directories need to be modified
                  i. /opt/ubuntu/linux-3.13.0/include/linux/skbuff.h
                 ii. /opt/ubuntu/linux-3.13.0/debian/linux-headers-3.13.0-36/
                        usr/src/linux-headers-3.13.0-36/include/linux/skbuff.h

          7. Install libxml2-dev to get xml2-config command:
             $ sudo apt-get install libxml2-dev

          8. Copy ARM64 versions of libxml2, libz, libm and liblzma libraries
             from an ARM64 system (located under /usr/lib/aarch64-linux-gnu/
             and /lib/aarch64-linux-gnu) to the cross-compile system and put
             under /opt/usr/lib/aarch64/.

Install driver

    Load driver

        # as root use insmod to install the driver
        modprobe scsi_transport_fc   # midlayer uses scsi_transport_fc
        insmod ocs_fc_ramd.ko        # parameters here

    Load driver as target and initiator

        modprobe scsi_transport_fc   # midlayer uses scsi_transport_fc
        insmod ocs_fc_ramd.ko initiator=1

    Summary of module parameters

        auto_xfer_rdy_size  The maximum sized write command to use a auto
                            generated transfer ready. Must have sequence
                            coalescing enabled and RXRI mode disabled.
                            (default 0)

        ctrlmask            bit[0] disable auto response on target reads
                                   (default is 0)
                            bit[1] disable auto response on target writes
                                   (default is 1)
                            bit[3] enable target RSCN procesing
                            bit[4] Tgt Always verify DIF (clear AT/ATRT)
                            bit[5] Tgt set ref tag and CRC on format
                            bit[6] EVT: Limit MAX_SGL to 4, report as 8
                            bit[8] enable Fabric Emulation mode
                            bit[9] force sport into non-initiator mode
                            bit[10] stop driver load after firmware is reset

        ddump_saved_size    size of saved ddump (default 0)

        dif_separate        1 - DIF block is separate, 0 DIF block is interleaved
                            (default is 0)

        enable_hlm          0 - High Login Mode disabled,
                            1 - High Login Mode enabled (default is 0)

        ethernet_license    Ethernet license key

        explicit_buffer_list  Controls whether SGLs are pre-registered.
                              0 - Preregister SGLs, 1 - Host SGL (default 0)
                              Note: if device does not suppport Host SGL, then
                              Preregistered SGLs are used.

        external_loopback   If set to 1, enables external loopback mode. This
                            allows a port to discover and login to itself when
                            the Tx and Rx are connected via loopback hood
                            (default 0).
        global_ramdisc      use global ramdiscs (default is 1).  A value of 0
                            will create separate ramdiscs per port

        hal_war_version     Use this as f/w version for HAL workaround matching

        hlm_group_size      High Login Mode group size (default is 8)

        holdoff_link_online hold off link online until 0 - immediately,
                            1 - until all PCI devices have been enumerated,
                            2 - until brought up by mgmt request (default 0)

        hw_cmpl_context     Indicates where the driver processes hardware
                            completions:
                            0 - tasklet, 1 - kernel thread (default 1)

        initiator           enable initiator functionality (default is 0) (int)

        logdest             logging destination bit[0] = system log default 1),
                            bit[1] = ram log (default 0)

        logmask             mask bits to enable logging (default is 0)
                            bit[0] enable state machine traces
                            bit[1] enable ELS trace
                            bit[2] enable SCSI command trace
                            bit[3] enable SCSI backend target trace
                            bit[4] enable domain/sport state machine trace

        num_luns            number of LUNs (ramdisc count) (default is 1)

        num_scsi_ios        number of IO context's to allocated (default 8192)

        num_vports          Number of NPIV ports to create (default 0)



        p_type              protection type for T10 DIF.  Default is 0.

        ramdisc_blocksize   disk block size(default is 512)

        ramdisc_size        value as <number>[k|K|m|M|g|G] (default is 50M)

        ramlog_size         size of ram logging buffer (default 1M)

        speed               link speed in Mbps (0 - auto, e.g. 8000 for 8G)

        stub_res6_rel6      Enables the acceptance of legacy Reserve 6 (0x16)
                            and Release 6 (0x17) SCSI commands. No actual
                            Reserve/Release functionality is implemented.
                            Commands received will be accepted and
                            a GOOD STATUS will be returned.
                            0 - Reserve/Release 6 commands will receive
                                a Check Condition with 05/20/00.
                            1 - Reserve/Release 6 commands will receive
                                a Good Status.

        target              target functionality(default is 1) (int)

        target_io_timer     Timeout value, in seconds, for target commands
                            (default 0 - target timer disabled)

        topology            0 - auto, 1 - N_PORT, 2 - LOOP (default is 0)

        wwn_bump            the local port's WWN's are XOR'd with this value
                            prior to registering service parameters with the HBA.
                            This is used to alter the WWN values for the purpose
                            of testing point to point negotiations.

        hal_bounce          HAL bounce, 0 - no bounce, 1 - bounce (default 0)

        rq_threads          The number of RQ processing threads to create (default 0)

        rq_select_policy    MultiRQ select policy, 0 - S_ID/D_ID/OX_ID hash, 1 - S_ID/D_ID hash (default 0)

        queue_topology      Queue topology string (default "eq cq rq cq mq $nulp($nwq(cq wq:ulp=$rpt1))")

        ramd_threading      1 - start ramd threads, 0 - don't start ramd threads (default is 0)

        thread_cmds         1 - thread ramd commands, 0 don't thread ramd commands (default is 0)

    Module Parameter Example:
        Create two 100mb LUNs
            insmod ocs_fc_ramd.ko ramdisc_size=100m num_luns=2


Supported SCSI commands
    FORMAT UNIT
    INQUIRY (Standard Inquiry, VPD pages 0x00, x80, x83, x86)
    MODE SELECT6, MODE SELECT10 (for setting block size)
    MODE SENSE6 (limited pages)
    MODE SENSE10 (limited pages)
    READ6, READ10, READ12, READ16, READ32
    READ_LONG10, READ_LONG16
    READ CAPACITY10 and READ CAPACITY16
    REPORT LUNS
    REQUEST SENSE
    TEST UNIT READY
    WRITE6, WRITE10, WRITE12, WRITE16 and WRITE32
    WRITE_LONG10, WRITE_LONG16
    WRITE_SAME10, WRITE_SAME16, WRITE_SAME32
    WRITE_AND_VERIFY10, WRITE_AND_VERIFY_12, WRITE_AND_VERIFY16

