sci_base_remote_device.h revision 240518
189857Sobrien/*- 2218822Sdim * This file is provided under a dual BSD/GPLv2 license. When using or 389857Sobrien * redistributing this file, you may do so under either license. 489857Sobrien * 589857Sobrien * GPL LICENSE SUMMARY 689857Sobrien * 789857Sobrien * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 889857Sobrien * 989857Sobrien * This program is free software; you can redistribute it and/or modify 1089857Sobrien * it under the terms of version 2 of the GNU General Public License as 1189857Sobrien * published by the Free Software Foundation. 1289857Sobrien * 1389857Sobrien * This program is distributed in the hope that it will be useful, but 1489857Sobrien * WITHOUT ANY WARRANTY; without even the implied warranty of 1589857Sobrien * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 1689857Sobrien * General Public License for more details. 1789857Sobrien * 1889857Sobrien * You should have received a copy of the GNU General Public License 19218822Sdim * along with this program; if not, write to the Free Software 20218822Sdim * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 2189857Sobrien * The full GNU General Public License is included in this distribution 2289857Sobrien * in the file called LICENSE.GPL. 2389857Sobrien * 2489857Sobrien * BSD LICENSE 2589857Sobrien * 2689857Sobrien * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 2789857Sobrien * All rights reserved. 2889857Sobrien * 2989857Sobrien * Redistribution and use in source and binary forms, with or without 3089857Sobrien * modification, are permitted provided that the following conditions 3189857Sobrien * are met: 3289857Sobrien * 3389857Sobrien * * Redistributions of source code must retain the above copyright 3489857Sobrien * notice, this list of conditions and the following disclaimer. 3589857Sobrien * * Redistributions in binary form must reproduce the above copyright 3689857Sobrien * notice, this list of conditions and the following disclaimer in 3789857Sobrien * the documentation and/or other materials provided with the 3889857Sobrien * distribution. 3989857Sobrien * 4089857Sobrien * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 4189857Sobrien * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 4289857Sobrien * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 4389857Sobrien * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 4489857Sobrien * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 4589857Sobrien * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 4689857Sobrien * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 4789857Sobrien * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 4889857Sobrien * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 4989857Sobrien * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 5089857Sobrien * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 5189857Sobrien * 52130561Sobrien * $FreeBSD: head/sys/dev/isci/scil/sci_base_remote_device.h 240518 2012-09-14 21:28:56Z eadler $ 5389857Sobrien */ 5489857Sobrien#ifndef _SCI_BASE_REMOTE_DEVICE_H_ 5589857Sobrien#define _SCI_BASE_REMOTE_DEVICE_H_ 5689857Sobrien 5789857Sobrien/** 5889857Sobrien * @file 5989857Sobrien * 6089857Sobrien * @brief This file contains all of the structures, constants, and methods 6189857Sobrien * common to all remote device object definitions. 6289857Sobrien */ 6389857Sobrien 6489857Sobrien#ifdef __cplusplus 6589857Sobrienextern "C" { 66130561Sobrien#endif // __cplusplus 67130561Sobrien 68130561Sobrien#include <dev/isci/scil/sci_base_state_machine.h> 69130561Sobrien#include <dev/isci/scil/sci_base_logger.h> 70130561Sobrien#include <dev/isci/scil/sci_base_state_machine_logger.h> 71130561Sobrien 72130561Sobrienstruct SCI_BASE_REQUEST; 73130561Sobrien 74130561Sobrien/** 75130561Sobrien * @enum SCI_BASE_REMOTE_DEVICE_STATES 76130561Sobrien * 77130561Sobrien * @brief This enumeration depicts all the states for the common remote device 78130561Sobrien * state machine. 79130561Sobrien */ 80130561Sobrientypedef enum _SCI_BASE_REMOTE_DEVICE_STATES 81130561Sobrien{ 82130561Sobrien /** 83130561Sobrien * Simply the initial state for the base remote device state machine. 84130561Sobrien */ 85130561Sobrien SCI_BASE_REMOTE_DEVICE_STATE_INITIAL, 86130561Sobrien 87130561Sobrien /** 88130561Sobrien * This state indicates that the remote device has successfully been 89130561Sobrien * stopped. In this state no new IO operations are permitted. 90130561Sobrien * This state is entered from the INITIAL state. 91130561Sobrien * This state is entered from the STOPPING state. 92130561Sobrien */ 93130561Sobrien SCI_BASE_REMOTE_DEVICE_STATE_STOPPED, 94130561Sobrien 95130561Sobrien /** 96130561Sobrien * This state indicates the remote device is in the process of 97130561Sobrien * becoming ready (i.e. starting). In this state no new IO operations 98130561Sobrien * are permitted. 99130561Sobrien * This state is entered from the STOPPED state. 100130561Sobrien */ 101130561Sobrien SCI_BASE_REMOTE_DEVICE_STATE_STARTING, 102130561Sobrien 103130561Sobrien /** 104130561Sobrien * This state indicates the remote device is now ready. Thus, the user 105130561Sobrien * is able to perform IO operations on the remote device. 106130561Sobrien * This state is entered from the STARTING state. 107130561Sobrien */ 108130561Sobrien SCI_BASE_REMOTE_DEVICE_STATE_READY, 109130561Sobrien 110130561Sobrien /** 111130561Sobrien * This state indicates that the remote device is in the process of 112130561Sobrien * stopping. In this state no new IO operations are permitted, but 113130561Sobrien * existing IO operations are allowed to complete. 114130561Sobrien * This state is entered from the READY state. 115130561Sobrien * This state is entered from the FAILED state. 116130561Sobrien */ 117130561Sobrien SCI_BASE_REMOTE_DEVICE_STATE_STOPPING, 11889857Sobrien 11989857Sobrien /** 12089857Sobrien * This state indicates that the remote device has failed. 12189857Sobrien * In this state no new IO operations are permitted. 12289857Sobrien * This state is entered from the INITIALIZING state. 12389857Sobrien * This state is entered from the READY state. 12489857Sobrien */ 12589857Sobrien SCI_BASE_REMOTE_DEVICE_STATE_FAILED, 126 127 /** 128 * This state indicates the device is being reset. 129 * In this state no new IO operations are permitted. 130 * This state is entered from the READY state. 131 */ 132 SCI_BASE_REMOTE_DEVICE_STATE_RESETTING, 133 134#if !defined(DISABLE_WIDE_PORTED_TARGETS) 135 /** 136 * This state indicates the device is in the middle of updating 137 * its port width. All the IOs sent to this device will be Quiesced. 138 */ 139 SCI_BASE_REMOTE_DEVICE_STATE_UPDATING_PORT_WIDTH, 140#endif 141 142 /** 143 * Simply the final state for the base remote device state machine. 144 */ 145 SCI_BASE_REMOTE_DEVICE_STATE_FINAL, 146 147 SCI_BASE_REMOTE_DEVICE_MAX_STATES 148 149} SCI_BASE_REMOTE_DEVICE_STATES; 150 151/** 152 * @struct SCI_BASE_REMOTE_DEVICE 153 * 154 * @brief The base remote device object abstracts the fields common to all 155 * SCI remote device objects. 156 */ 157typedef struct SCI_BASE_REMOTE_DEVICE 158{ 159 /** 160 * The field specifies that the parent object for the base remote 161 * device is the base object itself. 162 */ 163 SCI_BASE_OBJECT_T parent; 164 165 /** 166 * This field contains the information for the base remote device state 167 * machine. 168 */ 169 SCI_BASE_STATE_MACHINE_T state_machine; 170 171 #ifdef SCI_LOGGING 172 /** 173 * This field contains the state machine observer for the state machine. 174 */ 175 SCI_BASE_STATE_MACHINE_LOGGER_T state_machine_logger; 176 #endif // SCI_LOGGING 177 178} SCI_BASE_REMOTE_DEVICE_T; 179 180 181typedef SCI_STATUS (*SCI_BASE_REMOTE_DEVICE_HANDLER_T)( 182 SCI_BASE_REMOTE_DEVICE_T * 183); 184 185typedef SCI_STATUS (*SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T)( 186 SCI_BASE_REMOTE_DEVICE_T *, 187 struct SCI_BASE_REQUEST * 188); 189 190typedef SCI_STATUS (*SCI_BASE_REMOTE_DEVICE_HIGH_PRIORITY_REQUEST_COMPLETE_HANDLER_T)( 191 SCI_BASE_REMOTE_DEVICE_T *, 192 struct SCI_BASE_REQUEST *, 193 void *, 194 SCI_IO_STATUS 195); 196 197/** 198 * @struct SCI_BASE_CONTROLLER_STATE_HANDLER 199 * 200 * @brief This structure contains all of the state handler methods common to 201 * base remote device state machines. Handler methods provide the ability 202 * to change the behavior for user requests or transitions depending 203 * on the state the machine is in. 204 */ 205typedef struct SCI_BASE_REMOTE_DEVICE_STATE_HANDLER 206{ 207 /** 208 * The start_handler specifies the method invoked when a user attempts to 209 * start a remote device. 210 */ 211 SCI_BASE_REMOTE_DEVICE_HANDLER_T start_handler; 212 213 /** 214 * The stop_handler specifies the method invoked when a user attempts to 215 * stop a remote device. 216 */ 217 SCI_BASE_REMOTE_DEVICE_HANDLER_T stop_handler; 218 219 /** 220 * The fail_handler specifies the method invoked when a remote device 221 * failure has occurred. A failure may be due to an inability to 222 * initialize/configure the device. 223 */ 224 SCI_BASE_REMOTE_DEVICE_HANDLER_T fail_handler; 225 226 /** 227 * The destruct_handler specifies the method invoked when attempting to 228 * destruct a remote device. 229 */ 230 SCI_BASE_REMOTE_DEVICE_HANDLER_T destruct_handler; 231 232 /** 233 * The reset handler specifies the method invloked when requesting to reset a 234 * remote device. 235 */ 236 SCI_BASE_REMOTE_DEVICE_HANDLER_T reset_handler; 237 238 /** 239 * The reset complete handler specifies the method invloked when reporting 240 * that a reset has completed to the remote device. 241 */ 242 SCI_BASE_REMOTE_DEVICE_HANDLER_T reset_complete_handler; 243 244 /** 245 * The start_io_handler specifies the method invoked when a user 246 * attempts to start an IO request for a remote device. 247 */ 248 SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T start_io_handler; 249 250 /** 251 * The complete_io_handler specifies the method invoked when a user 252 * attempts to complete an IO request for a remote device. 253 */ 254 SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T complete_io_handler; 255 256 /** 257 * The continue_io_handler specifies the method invoked when a user 258 * attempts to continue an IO request for a remote device. 259 */ 260 SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T continue_io_handler; 261 262 /** 263 * The start_task_handler specifies the method invoked when a user 264 * attempts to start a task management request for a remote device. 265 */ 266 SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T start_task_handler; 267 268 /** 269 * The complete_task_handler specifies the method invoked when a user 270 * attempts to complete a task management request for a remote device. 271 */ 272 SCI_BASE_REMOTE_DEVICE_REQUEST_HANDLER_T complete_task_handler; 273 274} SCI_BASE_REMOTE_DEVICE_STATE_HANDLER_T; 275 276/** 277 * @brief Construct the base remote device 278 * 279 * @param[in] this_remote_device This parameter specifies the base remote 280 * device to be constructed. 281 * @param[in] logger This parameter specifies the logger associated with 282 * this base remote device object. 283 * @param[in] state_table This parameter specifies the table of state 284 * definitions to be utilized for the remote device state machine. 285 * 286 * @return none 287 */ 288void sci_base_remote_device_construct( 289 SCI_BASE_REMOTE_DEVICE_T * this_device, 290 SCI_BASE_LOGGER_T * logger, 291 SCI_BASE_STATE_T * state_table 292); 293 294#ifdef __cplusplus 295} 296#endif // __cplusplus 297 298#endif // _SCI_BASE_REMOTE_DEVICE_H_ 299