sci_base_remote_device.h revision 230557
1193323Sed/*- 2193323Sed * This file is provided under a dual BSD/GPLv2 license. When using or 3193323Sed * redistributing this file, you may do so under either license. 4193323Sed * 5193323Sed * GPL LICENSE SUMMARY 6193323Sed * 7193323Sed * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8193323Sed * 9193323Sed * This program is free software; you can redistribute it and/or modify 10193323Sed * it under the terms of version 2 of the GNU General Public License as 11206083Srdivacky * published by the Free Software Foundation. 12193323Sed * 13193323Sed * This program is distributed in the hope that it will be useful, but 14193323Sed * WITHOUT ANY WARRANTY; without even the implied warranty of 15193323Sed * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16193323Sed * General Public License for more details. 17193323Sed * 18193323Sed * You should have received a copy of the GNU General Public License 19193323Sed * along with this program; if not, write to the Free Software 20193323Sed * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21206083Srdivacky * The full GNU General Public License is included in this distribution 22206083Srdivacky * in the file called LICENSE.GPL. 23206083Srdivacky * 24202878Srdivacky * BSD LICENSE 25193323Sed * 26193323Sed * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27193323Sed * All rights reserved. 28193323Sed * 29193323Sed * Redistribution and use in source and binary forms, with or without 30193323Sed * modification, are permitted provided that the following conditions 31193323Sed * are met: 32193323Sed * 33193323Sed * * Redistributions of source code must retain the above copyright 34193323Sed * notice, this list of conditions and the following disclaimer. 35193323Sed * * Redistributions in binary form must reproduce the above copyright 36198892Srdivacky * notice, this list of conditions and the following disclaimer in 37193323Sed * the documentation and/or other materials provided with the 38193323Sed * distribution. 39193323Sed * 40193323Sed * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41193323Sed * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42193323Sed * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43206083Srdivacky * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44206083Srdivacky * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45206083Srdivacky * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46206083Srdivacky * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47206083Srdivacky * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48206083Srdivacky * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49206083Srdivacky * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50206083Srdivacky * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51206083Srdivacky * 52193323Sed * $FreeBSD$ 53193323Sed */ 54193323Sed#ifndef _SCI_BASE_REMOTE_DEVICE_H_ 55193323Sed#define _SCI_BASE_REMOTE_DEVICE_H_ 56193323Sed 57193323Sed/** 58193323Sed * @file 59193323Sed * 60193323Sed * @brief This file contains all of the structures, constants, and methods 61193323Sed * common to all remote device object definitions. 62193323Sed */ 63193323Sed 64193323Sed#ifdef __cplusplus 65193323Sedextern "C" { 66193323Sed#endif // __cplusplus 67193323Sed 68193323Sed#include <dev/isci/scil/sci_base_state_machine.h> 69193323Sed#include <dev/isci/scil/sci_base_logger.h> 70193323Sed#include <dev/isci/scil/sci_base_state_machine_logger.h> 71193323Sed 72193323Sedstruct SCI_BASE_REQUEST; 73193323Sed 74193323Sed/** 75193323Sed * @enum SCI_BASE_REMOTE_DEVICE_STATES 76193323Sed * 77193323Sed * @brief This enumeration depicts all the states for the common remote device 78193323Sed * state machine. 79206083Srdivacky */ 80206083Srdivackytypedef enum _SCI_BASE_REMOTE_DEVICE_STATES 81193323Sed{ 82193323Sed /** 83193323Sed * Simply the initial state for the base remote device state machine. 84193323Sed */ 85193323Sed SCI_BASE_REMOTE_DEVICE_STATE_INITIAL, 86206083Srdivacky 87206083Srdivacky /** 88206083Srdivacky * This state indicates that the remote device has successfully been 89206083Srdivacky * stopped. In this state no new IO operations are permitted. 90206083Srdivacky * This state is entered from the INITIAL state. 91206083Srdivacky * This state is entered from the STOPPING state. 92206083Srdivacky */ 93206083Srdivacky SCI_BASE_REMOTE_DEVICE_STATE_STOPPED, 94206083Srdivacky 95206083Srdivacky /** 96206083Srdivacky * This state indicates the the remote device is in the process of 97206083Srdivacky * becoming ready (i.e. starting). In this state no new IO operations 98206083Srdivacky * are permitted. 99206083Srdivacky * This state is entered from the STOPPED state. 100206083Srdivacky */ 101206083Srdivacky SCI_BASE_REMOTE_DEVICE_STATE_STARTING, 102206083Srdivacky 103206083Srdivacky /** 104206083Srdivacky * This state indicates the remote device is now ready. Thus, the user 105206083Srdivacky * is able to perform IO operations on the remote device. 106206083Srdivacky * This state is entered from the STARTING state. 107206083Srdivacky */ 108206083Srdivacky SCI_BASE_REMOTE_DEVICE_STATE_READY, 109206083Srdivacky 110206083Srdivacky /** 111206083Srdivacky * This state indicates that the remote device is in the process of 112206083Srdivacky * stopping. In this state no new IO operations are permitted, but 113206083Srdivacky * existing IO operations are allowed to complete. 114206083Srdivacky * This state is entered from the READY state. 115206083Srdivacky * This state is entered from the FAILED state. 116206083Srdivacky */ 117206083Srdivacky SCI_BASE_REMOTE_DEVICE_STATE_STOPPING, 118206083Srdivacky 119206083Srdivacky /** 120206083Srdivacky * This state indicates that the remote device has failed. 121206083Srdivacky * In this state no new IO operations are permitted. 122206083Srdivacky * This state is entered from the INITIALIZING state. 123206083Srdivacky * This state is entered from the READY state. 124206083Srdivacky */ 125206083Srdivacky SCI_BASE_REMOTE_DEVICE_STATE_FAILED, 126206083Srdivacky 127206083Srdivacky /** 128206083Srdivacky * This state indicates the device is being reset. 129206083Srdivacky * In this state no new IO operations are permitted. 130206083Srdivacky * This state is entered from the READY state. 131206083Srdivacky */ 132206083Srdivacky SCI_BASE_REMOTE_DEVICE_STATE_RESETTING, 133206083Srdivacky 134206083Srdivacky#if !defined(DISABLE_WIDE_PORTED_TARGETS) 135206083Srdivacky /** 136206083Srdivacky * This state indicates the device is in the middle of updating 137206083Srdivacky * its port width. All the IOs sent to this device will be Quiesced. 138206083Srdivacky */ 139206083Srdivacky SCI_BASE_REMOTE_DEVICE_STATE_UPDATING_PORT_WIDTH, 140206083Srdivacky#endif 141206083Srdivacky 142206083Srdivacky /** 143206083Srdivacky * Simply the final state for the base remote device state machine. 144206083Srdivacky */ 145206083Srdivacky SCI_BASE_REMOTE_DEVICE_STATE_FINAL, 146206083Srdivacky 147206083Srdivacky SCI_BASE_REMOTE_DEVICE_MAX_STATES 148206083Srdivacky 149206083Srdivacky} SCI_BASE_REMOTE_DEVICE_STATES; 150206083Srdivacky 151206083Srdivacky/** 152206083Srdivacky * @struct SCI_BASE_REMOTE_DEVICE 153206083Srdivacky * 154206083Srdivacky * @brief The base remote device object abstracts the fields common to all 155193323Sed * SCI remote device objects. 156193323Sed */ 157193323Sedtypedef struct SCI_BASE_REMOTE_DEVICE 158193323Sed{ 159206083Srdivacky /** 160206083Srdivacky * The field specifies that the parent object for the base remote 161193323Sed * device is the base object itself. 162193323Sed */ 163193323Sed SCI_BASE_OBJECT_T parent; 164193323Sed 165193323Sed /** 166193323Sed * This field contains the information for the base remote device state 167193323Sed * machine. 168193323Sed */ 169193323Sed SCI_BASE_STATE_MACHINE_T state_machine; 170193323Sed 171193323Sed #ifdef SCI_LOGGING 172193323Sed /** 173193323Sed * This field contains the state machine observer for the state machine. 174193323Sed */ 175193323Sed SCI_BASE_STATE_MACHINE_LOGGER_T state_machine_logger; 176193323Sed #endif // SCI_LOGGING 177193323Sed 178193323Sed} SCI_BASE_REMOTE_DEVICE_T; 179193323Sed 180193323Sed 181193323Sedtypedef SCI_STATUS (*SCI_BASE_REMOTE_DEVICE_HANDLER_T)( 182193323Sed SCI_BASE_REMOTE_DEVICE_T * 183193323Sed); 184193323Sed 185193323Sedtypedef SCI_STATUS (*SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T)( 186193323Sed SCI_BASE_REMOTE_DEVICE_T *, 187206083Srdivacky struct SCI_BASE_REQUEST * 188206083Srdivacky); 189206083Srdivacky 190206083Srdivackytypedef SCI_STATUS (*SCI_BASE_REMOTE_DEVICE_HIGH_PRIORITY_REQUEST_COMPLETE_HANDLER_T)( 191206083Srdivacky SCI_BASE_REMOTE_DEVICE_T *, 192206083Srdivacky struct SCI_BASE_REQUEST *, 193206083Srdivacky void *, 194206083Srdivacky SCI_IO_STATUS 195206083Srdivacky); 196206083Srdivacky 197206083Srdivacky/** 198206083Srdivacky * @struct SCI_BASE_CONTROLLER_STATE_HANDLER 199206083Srdivacky * 200206083Srdivacky * @brief This structure contains all of the state handler methods common to 201206083Srdivacky * base remote device state machines. Handler methods provide the ability 202206083Srdivacky * to change the behavior for user requests or transitions depending 203206083Srdivacky * on the state the machine is in. 204206083Srdivacky */ 205206083Srdivackytypedef struct SCI_BASE_REMOTE_DEVICE_STATE_HANDLER 206206083Srdivacky{ 207206083Srdivacky /** 208206083Srdivacky * The start_handler specifies the method invoked when a user attempts to 209206083Srdivacky * start a remote device. 210206083Srdivacky */ 211206083Srdivacky SCI_BASE_REMOTE_DEVICE_HANDLER_T start_handler; 212206083Srdivacky 213206083Srdivacky /** 214206083Srdivacky * The stop_handler specifies the method invoked when a user attempts to 215206083Srdivacky * stop a remote device. 216206083Srdivacky */ 217206083Srdivacky SCI_BASE_REMOTE_DEVICE_HANDLER_T stop_handler; 218206083Srdivacky 219206083Srdivacky /** 220206083Srdivacky * The fail_handler specifies the method invoked when a remote device 221206083Srdivacky * failure has occurred. A failure may be due to an inability to 222206083Srdivacky * initialize/configure the device. 223206083Srdivacky */ 224206083Srdivacky SCI_BASE_REMOTE_DEVICE_HANDLER_T fail_handler; 225206083Srdivacky 226206083Srdivacky /** 227206083Srdivacky * The destruct_handler specifies the method invoked when attempting to 228206083Srdivacky * destruct a remote device. 229206083Srdivacky */ 230206083Srdivacky SCI_BASE_REMOTE_DEVICE_HANDLER_T destruct_handler; 231206083Srdivacky 232206083Srdivacky /** 233206083Srdivacky * The reset handler specifies the method invloked when requesting to reset a 234206083Srdivacky * remote device. 235206083Srdivacky */ 236206083Srdivacky SCI_BASE_REMOTE_DEVICE_HANDLER_T reset_handler; 237206083Srdivacky 238206083Srdivacky /** 239206083Srdivacky * The reset complete handler specifies the method invloked when reporting 240206083Srdivacky * that a reset has completed to the remote device. 241206083Srdivacky */ 242206083Srdivacky SCI_BASE_REMOTE_DEVICE_HANDLER_T reset_complete_handler; 243206083Srdivacky 244206083Srdivacky /** 245206083Srdivacky * The start_io_handler specifies the method invoked when a user 246206083Srdivacky * attempts to start an IO request for a remote device. 247206083Srdivacky */ 248206083Srdivacky SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T start_io_handler; 249206083Srdivacky 250206083Srdivacky /** 251206083Srdivacky * The complete_io_handler specifies the method invoked when a user 252206083Srdivacky * attempts to complete an IO request for a remote device. 253206083Srdivacky */ 254206083Srdivacky SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T complete_io_handler; 255206083Srdivacky 256206083Srdivacky /** 257206083Srdivacky * The continue_io_handler specifies the method invoked when a user 258206083Srdivacky * attempts to continue an IO request for a remote device. 259206083Srdivacky */ 260206083Srdivacky SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T continue_io_handler; 261206083Srdivacky 262206083Srdivacky /** 263206083Srdivacky * The start_task_handler specifies the method invoked when a user 264206083Srdivacky * attempts to start a task management request for a remote device. 265206083Srdivacky */ 266206083Srdivacky SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T start_task_handler; 267206083Srdivacky 268206083Srdivacky /** 269206083Srdivacky * The complete_task_handler specifies the method invoked when a user 270206083Srdivacky * attempts to complete a task management request for a remote device. 271206083Srdivacky */ 272206083Srdivacky SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T complete_task_handler; 273206083Srdivacky 274206083Srdivacky} SCI_BASE_REMOTE_DEVICE_STATE_HANDLER_T; 275206083Srdivacky 276206083Srdivacky/** 277206083Srdivacky * @brief Construct the base remote device 278206083Srdivacky * 279206083Srdivacky * @param[in] this_remote_device This parameter specifies the base remote 280206083Srdivacky * device to be constructed. 281206083Srdivacky * @param[in] logger This parameter specifies the logger associated with 282206083Srdivacky * this base remote device object. 283206083Srdivacky * @param[in] state_table This parameter specifies the table of state 284206083Srdivacky * definitions to be utilized for the remote device state machine. 285206083Srdivacky * 286206083Srdivacky * @return none 287206083Srdivacky */ 288206083Srdivackyvoid sci_base_remote_device_construct( 289206083Srdivacky SCI_BASE_REMOTE_DEVICE_T * this_device, 290206083Srdivacky SCI_BASE_LOGGER_T * logger, 291206083Srdivacky SCI_BASE_STATE_T * state_table 292206083Srdivacky); 293206083Srdivacky 294206083Srdivacky#ifdef __cplusplus 295206083Srdivacky} 296206083Srdivacky#endif // __cplusplus 297206083Srdivacky 298206083Srdivacky#endif // _SCI_BASE_REMOTE_DEVICE_H_ 299206083Srdivacky