1 /*- 2 * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0 3 * 4 * This file is provided under a dual BSD/GPLv2 license. When using or 5 * redistributing this file, you may do so under either license. 6 * 7 * GPL LICENSE SUMMARY 8 * 9 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 10 * 11 * This program is free software; you can redistribute it and/or modify 12 * it under the terms of version 2 of the GNU General Public License as 13 * published by the Free Software Foundation. 14 * 15 * This program is distributed in the hope that it will be useful, but 16 * WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 18 * General Public License for more details. 19 * 20 * You should have received a copy of the GNU General Public License 21 * along with this program; if not, write to the Free Software 22 * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 23 * The full GNU General Public License is included in this distribution 24 * in the file called LICENSE.GPL. 25 * 26 * BSD LICENSE 27 * 28 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 29 * All rights reserved. 30 * 31 * Redistribution and use in source and binary forms, with or without 32 * modification, are permitted provided that the following conditions 33 * are met: 34 * 35 * * Redistributions of source code must retain the above copyright 36 * notice, this list of conditions and the following disclaimer. 37 * * Redistributions in binary form must reproduce the above copyright 38 * notice, this list of conditions and the following disclaimer in 39 * the documentation and/or other materials provided with the 40 * distribution. 41 * 42 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 43 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 44 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 45 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 46 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 47 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 48 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 49 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 50 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 51 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 52 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 53 * 54 * $FreeBSD$ 55 */ 56 #ifndef _SCIF_CONTROLLER_H_ 57 #define _SCIF_CONTROLLER_H_ 58 59 /** 60 * @file 61 * 62 * @brief This file contains all of the interface methods that can be called 63 * by an SCIF user on a SCIF controller object. 64 */ 65 66 #ifdef __cplusplus 67 extern "C" { 68 #endif // __cplusplus 69 70 #include <dev/isci/scil/sci_types.h> 71 #include <dev/isci/scil/sci_status.h> 72 73 74 /** 75 * @brief This method will attempt to construct a framework controller object 76 * utilizing the supplied parameter information. 77 * 78 * @param[in] library This parameter specifies the handle to the framework 79 * library object associated with the controller being constructed. 80 * @param[in] controller This parameter specifies the framework controller to 81 * be constructed. 82 * @param[in] user_object This parameter is a reference to the SCIL users 83 * controller object and will be used to associate with the 84 * framework controller. 85 * 86 * @return Indicate if the controller was successfully constructed or if 87 * it failed in some way. 88 * @retval SCI_SUCCESS This value is returned if the controller was 89 * successfully constructed. 90 * @retval SCI_FAILURE_UNSUPPORTED_INIT_DATA_VERSION This value is returned 91 * if the controller does not support the supplied oem parameter 92 * data version. 93 * @retval SCI_FAILURE_UNSUPPORTED_PORT_CONFIGURATION This value is returned 94 * if the controller doesn't support the port configuration scheme 95 * (APC or MPC). 96 */ 97 SCI_STATUS scif_controller_construct( 98 SCI_LIBRARY_HANDLE_T library, 99 SCI_CONTROLLER_HANDLE_T controller, 100 void * user_object 101 ); 102 103 /** 104 * @brief This method will initialize the SCI Framework controller object. 105 * This includes initialization of the associated core controller. 106 * 107 * @param[in] controller This parameter specifies the controller to be 108 * initialized. 109 * 110 * @return Indicate if the controller was successfully initialized or if 111 * it failed in some way. 112 * @retval SCI_SUCCESS This value is returned if the controller hardware 113 * was successfully initialized. 114 */ 115 SCI_STATUS scif_controller_initialize( 116 SCI_CONTROLLER_HANDLE_T controller 117 ); 118 119 /** 120 * @brief This method returns the suggested scif_controller_start() 121 * timeout amount. The user is free to use any timeout value, 122 * but this method provides the suggested minimum start timeout 123 * value. The returned value is based upon empirical information 124 * determined as a result of interoperability testing. 125 * 126 * @param[in] controller the handle to the controller object for which 127 * to return the suggested start timeout. 128 * 129 * @return This method returns the number of milliseconds for the 130 * suggested start operation timeout. 131 */ 132 U32 scif_controller_get_suggested_start_timeout( 133 SCI_CONTROLLER_HANDLE_T controller 134 ); 135 136 /** 137 * @brief This method will start the SCIF controller. The SCI User completion 138 * callback is called when the following conditions are met: 139 * -# the return status of this method is SCI_SUCCESS. 140 * -# after all of the phys have successfully started or been given 141 * the opportunity to start. 142 * 143 * @pre The controller must be in the INITIALIZED or STARTED state. 144 * 145 * @param[in] controller the handle to the controller object to start. 146 * @param[in] timeout This parameter specifies the number of milliseconds 147 * in which the start operation should complete. 148 * 149 * @return Indicate if the controller start method succeeded or failed in 150 * some way. 151 * @retval SCI_SUCCESS if the start operation succeeded. 152 * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in 153 * the STARTED state. 154 * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in 155 * the INITIALIZED or STARTED states. 156 * @retval SCI_FAILURE_INVALID_MEMORY_DESCRIPTOR if there are 157 * inconsistent or invalid values in the supplied 158 * SCI_PHYSICAL_MEMORY_DESCRIPTOR array. 159 * @retval SCI_FAILURE_UNSUPPORTED_PORT_CONFIGURATION This value is 160 * returned if the phy to port allocation cannot be supported. 161 * 162 * @see For additional information please refer to: scic_controller_start() 163 */ 164 SCI_STATUS scif_controller_start( 165 SCI_CONTROLLER_HANDLE_T controller, 166 U32 timeout 167 ); 168 169 /** 170 * @brief This method will stop an individual framework controller object. This 171 * includes quiescing IOs, releasing affiliations, and other shutdown 172 * related operations. This method will invoke the associated user 173 * callback upon completion. The completion callback is called when 174 * the following conditions are met: 175 * -# the method return status is SCI_SUCCESS. 176 * -# the controller has been quiesced. 177 * This method will ensure that all framework IO requests are quiesced 178 * and any additional framework operations are halted. 179 * 180 * @pre The controller must be in the STARTED or STOPPED state. 181 * 182 * @param[in] controller the handle to the controller object to stop. 183 * @param[in] timeout This parameter specifies the number of milliseconds 184 * in which the stop operation should complete. 185 * 186 * @return Indicate if the controller stop method succeeded or failed in 187 * some way. 188 * @retval SCI_SUCCESS if the stop operation successfully began. 189 * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in 190 * the STOPPED state. 191 * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in 192 * the STARTED or STOPPED states. 193 * 194 * @see For additional information please refer to: scic_controller_stop() 195 */ 196 SCI_STATUS scif_controller_stop( 197 SCI_CONTROLLER_HANDLE_T controller, 198 U32 timeout 199 ); 200 201 /** 202 * @brief This method will reset the supplied framework controller regardless 203 * of the state of said controller. This operation is considered 204 * destructive. Outstanding IO requests are not aborted or completed 205 * at the actual remote device. However, the framework will 206 * manufacture completion callbacks to the OS driver for the IO 207 * requests. 208 * 209 * @param[in] controller the handle to the controller object to reset. 210 * 211 * @return Indicate if the controller reset method succeeded or failed in 212 * some way. 213 * @retval SCI_SUCCESS if the reset operation successfully started. 214 * @retval SCI_FATAL_ERROR if the controller reset operation is unable to 215 * complete. 216 * 217 * @see For additional information please refer to: scic_controller_reset() 218 */ 219 SCI_STATUS scif_controller_reset( 220 SCI_CONTROLLER_HANDLE_T controller 221 ); 222 223 /** 224 * @brief This method returns the SCI Core controller handle associated 225 * with this controller. 226 * 227 * @param[in] scif_controller the handle to the controller object for which 228 * to retrieve the core specific controller handle 229 * 230 * @return Return the SCI core controller handle associated with the supplied 231 * framework controller. 232 */ 233 SCI_CONTROLLER_HANDLE_T scif_controller_get_scic_handle( 234 SCI_CONTROLLER_HANDLE_T scif_controller 235 ); 236 237 /** 238 * @brief This method is called by the SCIF user to send/start a framework 239 * IO request. 240 * 241 * @param[in] controller the handle to the controller object for which 242 * to start an IO request. 243 * @param[in] remote_device the handle to the remote device object for which 244 * to start an IO request. 245 * @param[in] io_request the handle to the io request object to start. 246 * @param[in] io_tag This parameter specifies a previously allocated IO tag 247 * that the user desires to be utilized for this request. 248 * This parameter is optional. The user is allowed to supply 249 * SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter. 250 * @see scic_controller_allocate_tag() for more information 251 * on allocating a tag. 252 * 253 * @return Indicate if the controller successfully started the IO request. 254 * @retval SCI_IO_SUCCESS if the IO request was successfully started. 255 * 256 * @see For additional information please refer to: scic_controller_start_io() 257 * 258 * @todo Determine the failure situations and return values. 259 */ 260 SCI_IO_STATUS scif_controller_start_io( 261 SCI_CONTROLLER_HANDLE_T controller, 262 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 263 SCI_IO_REQUEST_HANDLE_T io_request, 264 U16 io_tag 265 ); 266 267 /** 268 * @brief This method is called by the SCIF user to send/start a framework 269 * task management request. 270 * 271 * @param[in] controller the handle to the controller object for which 272 * to start the task management request. 273 * @param[in] remote_device the handle to the remote device object for which 274 * to start the task management request. 275 * @param[in] task_request the handle to the task request object to start. 276 * @param[in] io_tag This parameter specifies a previously allocated IO tag 277 * that the user desires to be utilized for this request. Note 278 * this not the io_tag of the request being managed. It is to 279 * be utilized for the task request itself. 280 * This parameter is optional. The user is allowed to supply 281 * SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter. 282 * @see scic_controller_allocate_tag() for more information 283 * on allocating a tag. 284 * 285 * @return Indicate if the controller successfully started the IO request. 286 * @retval SCI_TASK_SUCCESS if the task request was successfully started. 287 * 288 * @see For additional information please refer to: scic_controller_start_task() 289 * 290 * @todo Determine the failure situations and return values. 291 */ 292 SCI_TASK_STATUS scif_controller_start_task( 293 SCI_CONTROLLER_HANDLE_T controller, 294 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 295 SCI_TASK_REQUEST_HANDLE_T task_request, 296 U16 io_tag 297 ); 298 299 /** 300 * @brief This method is called by the SCI user to complete a previously 301 * started IO request. After this method is invoked, the user should 302 * consider the IO request as invalid until it is properly reused 303 * (i.e. re-constructed). 304 * 305 * @param[in] controller The handle to the controller object for which 306 * to complete the IO request. 307 * @param[in] remote_device The handle to the remote device object for which 308 * to complete the IO request. 309 * @param[in] io_request the handle to the io request object to complete. 310 * 311 * @return Indicate if the controller successfully completed the IO request. 312 * @retval SCI_SUCCESS if the completion process was successful. 313 * 314 * @see For additional information please refer to: 315 * scic_controller_complete_io() 316 */ 317 SCI_STATUS scif_controller_complete_io( 318 SCI_CONTROLLER_HANDLE_T controller, 319 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 320 SCI_IO_REQUEST_HANDLE_T io_request 321 ); 322 323 /** 324 * @brief This method will perform framework specific completion operations for 325 * a task management request. After this method is invoked, the user 326 * should consider the task request as invalid until it is properly 327 * reused (i.e. re-constructed). 328 * 329 * @param[in] controller The handle to the controller object for which 330 * to complete the task management request. 331 * @param[in] remote_device The handle to the remote device object for which 332 * to complete the task management request. 333 * @param[in] task_request the handle to the task management request object 334 * to complete. 335 * 336 * @return Indicate if the controller successfully completed the task 337 * management request. 338 * @retval SCI_SUCCESS if the completion process was successful. 339 */ 340 SCI_STATUS scif_controller_complete_task( 341 SCI_CONTROLLER_HANDLE_T controller, 342 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 343 SCI_TASK_REQUEST_HANDLE_T task_request 344 ); 345 346 /** 347 * @brief This method simply provides the user with a unique handle for a 348 * given SAS/SATA domain index. 349 * 350 * @param[in] controller This parameter represents the handle to the 351 * controller object from which to retrieve a domain (SAS or 352 * SATA) handle. 353 * @param[in] port_index This parameter specifies the domain index in 354 * the controller for which to retrieve the domain handle. 355 * @note 0 <= port_index < maximum number of phys. 356 * @param[out] domain_handle This parameter specifies the retrieved domain 357 * handle to be provided to the caller. 358 * 359 * @return Indicate if the retrieval of the domain handle was successful. 360 * @retval SCI_SUCCESS This value is returned if the retrieval was successful. 361 * @retval SCI_FAILURE_INVALID_PORT This value is returned if the supplied 362 * port index is not invalid. 363 */ 364 SCI_STATUS scif_controller_get_domain_handle( 365 SCI_CONTROLLER_HANDLE_T controller, 366 U8 port_index, 367 SCI_DOMAIN_HANDLE_T * domain_handle 368 ); 369 370 /** 371 * @brief This method allows the user to configure the SCI Framework 372 * into either a performance mode or a memory savings mode. 373 * 374 * @param[in] controller This parameter represents the handle to the 375 * controller object for which to update the operating 376 * mode. 377 * @param[in] mode This parameter specifies the new mode for the 378 * controller. 379 * 380 * @return Indicate if the user successfully change the operating mode 381 * of the controller. 382 * @retval SCI_SUCCESS The user successfully updated the mode. 383 */ 384 SCI_STATUS scif_controller_set_mode( 385 SCI_CONTROLLER_HANDLE_T controller, 386 SCI_CONTROLLER_MODE mode 387 ); 388 389 /** 390 * @brief This method simply returns the T10 SCSI to ATA Translation (SAT) 391 * specification version to which this translator is compliant for 392 * supported commands. 393 * 394 * @return An integer value indicating the SAT version to which this 395 * translator complies. 396 */ 397 U32 scif_controller_get_sat_compliance_version( 398 void 399 ); 400 401 /** 402 * @brief This method simply returns the revision of the T10 SCSI to ATA 403 * Translation (SAT) specification version to which this translator 404 * is compliant for supported commands. 405 * 406 * @return An integer value indicating the revision of the SAT version 407 * to which this translator complies. 408 */ 409 U32 scif_controller_get_sat_compliance_version_revision( 410 void 411 ); 412 413 /** 414 * @brief This method is called by the SCI user to start internal io. 415 */ 416 typedef void (*SCI_START_INTERNAL_IO_ROUTINE)( 417 SCI_CONTROLLER_HANDLE_T controller 418 ); 419 420 #if !defined(DISABLE_INTERRUPTS) 421 /** 422 * @brief This method allows the user to configure the interrupt coalescence. 423 * Please refer to the comment header for 424 * scic_controller_set_interrupt_coalescence() to find details. 425 */ 426 SCI_STATUS scif_controller_set_interrupt_coalescence( 427 SCI_CONTROLLER_HANDLE_T controller, 428 U32 coalesce_number, 429 U32 coalesce_timeout 430 ); 431 432 /** 433 * @brief This method retrieves the interrupt coalescence information. 434 * Please refer to the comment header for 435 * scic_controller_get_interrupt_coalescence() to find details. 436 */ 437 void scif_controller_get_interrupt_coalescence( 438 SCI_CONTROLLER_HANDLE_T controller, 439 U32 * coalesce_number, 440 U32 * coalesce_timeout 441 ); 442 443 #else // !defined(DISABLE_INTERRUPTS) 444 445 #define scif_controller_set_interrupt_coalescence(controller, num, timeout) \ 446 SCI_FAILURE 447 #define scif_controller_get_interrupt_coalescence(controller, num, timeout) 448 449 #endif // !defined(DISABLE_INTERRUPTS) 450 451 #ifdef __cplusplus 452 } 453 #endif // __cplusplus 454 455 #endif // _SCIF_CONTROLLER_H_ 456 457