OneCore Storage Linux User Space FC RAMD (ocs_fc_ramd) driver

Updated: 1-Jul-2014

Note: This README provides an abbreviated version of the description,
building instructions, and supported module parameters for the Linux
User Space 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 User Space FC RAMD (ocs_fc_ramd) driver is a
    user space target driver that implements a non-persistent Ram Disk backing
    store. Support is included for a number of SCSI command, sufficient to
    allow most FC initiators/hosts to log into and access data.

    The driver consists of a small kernel module (ocs_uspace.ko), and a user space application
    (driver/uspace/ocs_fc_ramd).  The kernel module provides access to PCI resources, as well
    as managing DMA memory buffers.

    This driver is functionally identical to the kernel mode ocs_fc_ramd driver.

    There is no initiator functionality provided with this driver

Unpack and build

    Perform the following steps:

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

    Compile the kernel module

        # move to directory containing makefile
        cd driver/linux/ocs_uspace
        # build it
        make

    Compile the user space application

        # move to directory containing makefile
        cd driver/uspace/ocs_fc_ramd
        # build it
        make

Install kernel module

        cd driver/linux/ocs_uspace
        insmod ocs_uspace.ko

Running the user space application

        # as root (or set protections on /dev/ocs_*)
        cd driver/uspace/ocs_fc_ramd
        ./ocs_fc_ramd [parameters]

A number of driver parameters may be specified when running user space application (ocs_fc_ramd).
These are set using the following as command line options:

        --<parameter>=<value>

    Summary of module parameters

        ramdisc_blocksize   disk block size(default is 512)
        ramdisc_size        value as <number>[k|K|m|M|g|G] (default is 50M)
        num_luns            number of LUNs (ramdisc count) (default is 1)
        initiator           enable initiator functionality (default is 0) (int)
        target              target functionality(default is 1) (int)
        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
        ctrlmask            bit[0] disable auto response on target reads (default is 0)
                            bit[1] disable auto response on target writes (default is 0)
                            bit[3] enable target RSCN processing
                            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
        uspacemask          bit[0] 0:thread per port(default), 1:poll from single thread
                            bit[1] 0:threads block on events(default), 1:threads poll
        hal_war_version     Use this as f/w version for HAL workaround matching
        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.
        topology            0 - auto, 1 - N_PORT, 2 - LOOP (default is 0)
        speed               link speed in Mbps (0 - auto, e.g. 8000 for 8G)
        num_vports          Number of NPIV ports to create (default 0)
        p_type              protection type for T10 DIF.  Default is 0.
        dif_separate        1 - DIF block is separate, 0 DIF block is interleaved (default is 0)
        holdoff_link_online hold off link online until all PCI devices have been enumerated (default 0)
        enable_hlm          0 - High Login Mode disabled, 1 - High Login Mode enabled (default is 0)
	enable_fw_ag_rsp    Enable firmware path for auto-good response (reset parameter field to 0) (default is 0)
        hlm_group_size      High Login Mode group size (default is 8)
        logdest             logging destination bit[0] = system log default 1), bit[1] = ram log (default 0)
        ramlog_size         size of ram logging buffer (default 1M)
        ethernet_license    ethernet license key
        num_scsi_ios        number of IO context's to allocated (default 8192)
        ddump_saved_size    size of saved ddump (default 0)
        auto_xfer_rdy_size  The maximum sized write command to use a auto
                            generated transfer ready. Must have sequence coalesing
                            enabled and RXRI mode disabled. (default 0)
        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.
        hw_cmpl_context     Indicates where the driver processes hardware completions:
                            0 - tasklet, 1 - kernel thread (default 1)
        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.
        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)
        target_io_timer     Timeout value, in seconds, for target commands (default 0 - timer disabled)
        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

