ocs_ramd.h

Go to the documentation of this file.

/*
 * Copyright (c) 2011-2015, Emulex
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice,
 *    this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * 3. Neither the name of the copyright holder nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 */

/**
 * @file
 * SCSI RAMD target-service declarations.
 */

#if !defined(__OCS_RAMD_H__)
#define __OCS_RAMD_H__

#include "ocs_ramdisc.h"
#include "ocs_dif.h"
#include "scsi_asc_ascq.h"
#include "ocs_ramd_thread.h"

/* Command error codes */

/* Sense Keys */
#define SNS_ILLEGAL_REQ   0x05   /* sense key is byte 3 ([2]) */
#define SNS_UNIT_ATTENTION  0x06
#define SNS_ABORTED_CMD   0x0B   /* sense key - aborted command */

/* Additional Sense Codes */
#define SNSCODE_INV_CMDIU 0x0E    /* INVALID FIELD IN COMMAND IU */
#define SNSCODE_DIF_ERR   0x10   /* ID CRC OR ECC ERROR */
#define SNSCODE_BAD_CMD   0x20   /* INVALID COMMAND OPERATION CODE */
#define SNSCODE_LBA_OOR   0x21   /* LOGICAL BLOCK ADDRESS OUT OF RANGE */
#define SNSCODE_INV_CDB   0x24   /* INVALID FIELD IN CDB */
#define SNSCODE_INV_PRM   0x26   /* INVALID FIELD IN PARAMETER LIST */
#define SNSCODE_ABORTED_CMD 0x47   /* Aborted command */
#define SNSCODE_OFF_ERR   0x4B   /* DATA PHASE ERROR */
#define SNSCODE_SAVE_NOT_SUPPORTED 0x39 /* SAVING PARAMETERS NOT SUPPORTED */

/* Additional Sense Code Qualifiers */
#define SNSCODEQUAL_INV_CMDIU 0x03  /* INVALID FIELD IN COMMAND IU */


#define scsi_pack_result(key, code, qualifier) (((key & 0xff) << 16) | ((code && 0xff) << 8) | (qualifier & 0xff))

/* Handler return codes */
typedef enum {
    SCSI_HANDLER_DATAPHASE_STARTED = 1,
    SCSI_HANDLER_RESP_STARTED,
    SCSI_HANDLER_VALIDATED_DATAPHASE_STARTED,
    SCSI_HANDLER_WRITE_SAME_DATAPHASE_STARTED,
    SCSI_HANDLER_NOT_STARTED,
    SCSI_CMD_NOT_SUPPORTED,
} ocs_ramd_hndlr_rtn_e;

extern int32_t _ocs_scsi_recv_cmd(ocs_io_t *io, uint32_t lun, uint8_t *cdb, uint32_t cdb_len, uint32_t flags);
extern int32_t ocs_scsi_recv_cmd_common(ocs_io_t *io, uint32_t lun, uint8_t *cdb, uint32_t cdb_len, uint32_t flags,
                    uint8_t has_first_burst,
                    ocs_dma_t first_burst_buffers[], uint32_t first_burst_bytes);
extern ocs_ramd_hndlr_rtn_e ocs_ramd_check_cond(ocs_io_t *io, uint8_t sense_key, uint8_t asc, uint8_t ascq);
ocs_ramd_hndlr_rtn_e ocs_ramd_task_set_full_or_busy(ocs_io_t *io);
extern ocs_ramd_hndlr_rtn_e ocs_ramd_good_status(ocs_io_t *io);
int32_t scsi_io_cb(ocs_io_t *io, ocs_scsi_io_status_e scsi_status, uint32_t flags, void *arg);
int32_t _scsi_io_cb(ocs_io_t *io, ocs_scsi_io_status_e scsi_status, uint32_t flags, void *arg);
extern int32_t scsi_dataphase_cb(ocs_io_t *io, ocs_scsi_io_status_e scsi_status, uint32_t flags, void *arg);
extern int32_t _scsi_dataphase_cb(ocs_io_t *io, ocs_scsi_io_status_e scsi_status, uint32_t flags, void *arg);
extern ocs_ramdisc_t *ocs_ramd_lookup(ocs_io_t *io, uint32_t lun);
extern ocs_ramdisc_t *ocs_ramd_lookup_by_tgt(ocs_t *ocs, uint32_t tgt, uint32_t lun);
extern void ocs_ramd_post_ua(ocs_t *ocs, ocs_ramdisc_t *ramdisc, uint8_t asc, uint8_t ascq, ocs_node_t *except_node);
extern int32_t ocs_ramd_get_ua(ocs_t *ocs, ocs_node_t *node, uint32_t lun, uint8_t *asc, uint8_t *ascq);
extern void ocs_ramd_clear_ua(ocs_t *ocs, ocs_node_t *node, uint32_t lun, uint8_t asc, uint8_t ascq);

/* exported from mode_sense6.c */
extern ocs_ramd_hndlr_rtn_e ocs_ramd_mode_sense6(ocs_io_t *io, uint8_t cdb[]);
extern ocs_ramd_hndlr_rtn_e ocs_ramd_mode_sense10(ocs_io_t *io, uint8_t cdb[]);

extern int32_t ocs_port_rdisc_init(ocs_t *ocs);
extern void ocs_port_rdisc_free(ocs_t *ocs);
extern int32_t ocs_port_rdisc_find(ocs_t *ocs, uint32_t tgt_id, ocs_ramdisc_t ***rdisc, uint32_t *rdisc_count);
extern int32_t ocs_port_rdisc_save(ocs_t *ocs, uint32_t tgt_id, ocs_ramdisc_t **rdisc, uint32_t rdisc_count);

#endif // __OCS_RAMD_H__


/**
 * @page ramd_api_overview Back-end Target (RAMD) APIs and State Machine Functions
 * - @ref scsi_api_target
 * - @ref scsi_cmd
 * - @ref io_sm
 * - @ref ramdisc
 *
 * <div class="overview">
 * <img src="elx_ramd_tgt.jpg" alt="RAMD" title="RAMD" align="right"/>
 *
 * <h2>Target (RAMD)</h2>
 * The RAMD target of the OneCore Storage driver
 * implements a non-persistent RAM drive. The driver implements a number of SCSI commands,
 * and appears to initiators as a valid SCSI block device.<br><br>
 *
 * The RAMD consists of four main components: the SCSI Target, SCSI
 * Command Processing, RAMD Target IO State Machine, and the
 * RAMdisc.<br><br>
 *
 * When the driver is initially loaded, there is a driver-wide
 * initialization for the RAMD (ocs_scsi_tgt_driver_init()).
 * After the driver is loaded, the devices are enumerated. The
 * ocs_pci_probe() function calls ocs_scsi_tgt_new_device()
 * to create a new SCSI target.<br><br>
 *
 * Memory is allocated to hold the data for a ramdisc instance(s),
 * also called a LUN(s). Each default ramdisc instance (LUN) is 50 MB, consisting of 512-byte
 * blocks. This 50 MB area is further divided into segments of 64K,
 * resulting in a default ramdisc instance size up to 800 segments,
 * each with 128 blocks.
 * The ramdisc size and ramdisc block size can be changed using the
 * ramdisc_size and ramdisc_blocksize module parameters.
 * The ramdisc block size can be also changed using the FORMAT UNIT SCSI command,
 * but reverts to 512-byte blocks if the driver is reloaded.<br><br>
 *
 * Once initialized, the target performs the following functions:
 * <ul><li>Command parsing – commands are received as unsolicited FCP frames and the
 * CDB opcode is parsed.</li>
 * <li>Command dispatch – a table of SCSI command handler functions determines
 * the specific functions that are called to handle the specific commands.</li>
 * <li>Data transport – for SCSI READ and SCSI WRITE commands, data is DMA’d
 * directly to and from the memory buffers of the RAM drive.</li>
 * <li>Acts as a SCSI block device – SCSI configuration and informational
 * commands such as TEST UNIT READY, INQUIRY, MODE SELECT, and
 * MODE SENSE are implemented to allow the driver to respond, as if it were an
 * actual SCSI block device.</li></ul>
 *
 * To exit, the ocs_scsi_tgt_driver_exit() is called when the driver is unloaded (which
 * occurs after ocs_scsi_tgt_del_device()).
 *
 * <h3>Supported SCSI Commands</h3>
 * <ul><li>FORMAT UNIT</li>
 * <li>INQUIRY (Standard Inquiry, VPD pages 0x00, 0x80, 0x83, 0x86)</li>
 * <li>MODE SELECT (6), MODE SELECT 10 (for setting block size)</li>
 * <li>MODE SENSE (6) (limited pages), MODE SENSE (10) (limited pages)</li>
 * <li>READ (6), READ (10), READ (12), READ (16), READ (32)</li>
 * <li>READ CAPACITY (10), READ CAPACITY (16)</li>
 * <li>READ LONG (10), READ LONG (16)</li>
 * <li>REPORT LUNS</li>
 * <li>REQUEST SENSE</li>
 * <li>TEST UNIT READY</li>
 * <li>WRITE (6), WRITE (10), WRITE (12), WRITE (16), WRITE (32)</li>
 * <li>WRITE AND VERIFY (10), WRITE AND VERIFY (12), WRITE AND VERIFY (16)</li>
 * <li>WRITE LONG (10), WRITE LONG (16)</li>
 * <li>WRITE SAME (10), WRITE SAME (16), WRITE SAME (32)</li></ul>
 * </div><!-- overview -->
 */