1 /*- 2 * This file is provided under a dual BSD/GPLv2 license. When using or 3 * redistributing this file, you may do so under either license. 4 * 5 * GPL LICENSE SUMMARY 6 * 7 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8 * 9 * This program is free software; you can redistribute it and/or modify 10 * it under the terms of version 2 of the GNU General Public License as 11 * published by the Free Software Foundation. 12 * 13 * This program is distributed in the hope that it will be useful, but 14 * WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * General Public License for more details. 17 * 18 * You should have received a copy of the GNU General Public License 19 * along with this program; if not, write to the Free Software 20 * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21 * The full GNU General Public License is included in this distribution 22 * in the file called LICENSE.GPL. 23 * 24 * BSD LICENSE 25 * 26 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27 * All rights reserved. 28 * 29 * Redistribution and use in source and binary forms, with or without 30 * modification, are permitted provided that the following conditions 31 * are met: 32 * 33 * * Redistributions of source code must retain the above copyright 34 * notice, this list of conditions and the following disclaimer. 35 * * Redistributions in binary form must reproduce the above copyright 36 * notice, this list of conditions and the following disclaimer in 37 * the documentation and/or other materials provided with the 38 * distribution. 39 * 40 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51 * 52 * $FreeBSD$ 53 */ 54 #ifndef _SCIC_CONTROLLER_H_ 55 #define _SCIC_CONTROLLER_H_ 56 57 /** 58 * @file 59 * 60 * @brief This file contains all of the interface methods that can be called 61 * by an SCIC user on a controller object. 62 */ 63 64 #ifdef __cplusplus 65 extern "C" { 66 #endif // __cplusplus 67 68 #include <dev/isci/scil/sci_types.h> 69 #include <dev/isci/scil/sci_status.h> 70 #include <dev/isci/scil/sci_controller.h> 71 #include <dev/isci/scil/scic_config_parameters.h> 72 73 /** 74 * @enum 75 * 76 * Allowed PORT configuration modes 77 * 78 * APC Automatic PORT configuration mode is defined by the OEM configuration 79 * parameters providing no PHY_MASK parameters for any PORT. i.e. There are 80 * no phys assigned to any of the ports at start. 81 * 82 * MPC Manual PORT configuration mode is defined by the OEM configuration 83 * parameters providing a PHY_MASK value for any PORT. It is assumed that 84 * any PORT with no PHY_MASK is an invalid port and not all PHYs must be 85 * assigned. A PORT_PHY mask that assigns just a single PHY to a port and no 86 * other PHYs being assigned is sufficient to declare manual PORT configuration. 87 */ 88 enum SCIC_PORT_CONFIGURATION_MODE 89 { 90 SCIC_PORT_MANUAL_CONFIGURATION_MODE, 91 SCIC_PORT_AUTOMATIC_CONFIGURATION_MODE 92 }; 93 94 /** 95 * @enum _SCIC_INTERRUPT_TYPE 96 * 97 * @brief This enumeration depicts the various types of interrupts that 98 * are potentially supported by a SCI Core implementation. 99 */ 100 typedef enum _SCIC_INTERRUPT_TYPE 101 { 102 SCIC_LEGACY_LINE_INTERRUPT_TYPE, 103 SCIC_MSIX_INTERRUPT_TYPE, 104 105 /** 106 * This enumeration value indicates the use of polling. 107 */ 108 SCIC_NO_INTERRUPTS 109 110 } SCIC_INTERRUPT_TYPE; 111 112 /** 113 * @typedef SCIC_CONTROLLER_INTERRUPT_HANDLER 114 * 115 * @brief This method is called by the SCI user in order to have the SCI 116 * implementation handle the interrupt. This method performs 117 * minimal processing to allow for streamlined interrupt time usage. 118 * @note 119 * TRUE: returned if there is an interrupt to process and it was 120 * processed. 121 * FALSE: returned if no interrupt was processed. 122 * 123 */ 124 typedef BOOL (*SCIC_CONTROLLER_INTERRUPT_HANDLER)( 125 SCI_CONTROLLER_HANDLE_T controller 126 ); 127 128 /** 129 * @brief This method is called by the SCI user to process completions 130 * generated as a result of a previously handled interrupt. This 131 * method will result in the completion of IO requests and handling 132 * of other controller generated events. This method should be 133 * called some time after the interrupt handler. 134 * 135 * @note Most, if not all, of the user callback APIs are invoked from within 136 * this API. As a result, the user should be cognizent of the operating 137 * level at which they invoke this API. 138 * 139 */ 140 typedef void (*SCIC_CONTROLLER_COMPLETION_HANDLER)( 141 SCI_CONTROLLER_HANDLE_T controller 142 ); 143 144 /** 145 * @struct SCIC_CONTROLLER_HANDLER_METHODS 146 * 147 * @brief This structure contains an interrupt handler and completion 148 * handler function pointers. 149 */ 150 typedef struct SCIC_CONTROLLER_HANDLER_METHODS 151 { 152 SCIC_CONTROLLER_INTERRUPT_HANDLER interrupt_handler; 153 SCIC_CONTROLLER_COMPLETION_HANDLER completion_handler; 154 155 } SCIC_CONTROLLER_HANDLER_METHODS_T; 156 157 /** 158 * @brief This method will attempt to construct a controller object 159 * utilizing the supplied parameter information. 160 * 161 * @param[in] library This parameter specifies the handle to the library 162 * object associated with the controller being constructed. 163 * @param[in] controller This parameter specifies the controller to be 164 * constructed. 165 * @param[in] user_object This parameter is a reference to the SCIL users 166 * controller object and will be used to associate with the core 167 * controller. 168 * 169 * @return Indicate if the controller was successfully constructed or if 170 * it failed in some way. 171 * @retval SCI_SUCCESS This value is returned if the controller was 172 * successfully constructed. 173 * @retval SCI_WARNING_TIMER_CONFLICT This value is returned if the 174 * interrupt coalescence timer may cause SAS compliance issues 175 * for SMP Target mode response processing. 176 * @retval SCI_FAILURE_UNSUPPORTED_CONTROLLER_TYPE This value is returned if 177 * the controller does not support the supplied type. 178 * @retval SCI_FAILURE_UNSUPPORTED_INIT_DATA_VERSION This value is returned 179 * if the controller does not support the supplied initialization 180 * data version. 181 */ 182 SCI_STATUS scic_controller_construct( 183 SCI_LIBRARY_HANDLE_T library, 184 SCI_CONTROLLER_HANDLE_T controller, 185 void * user_object 186 ); 187 188 /** 189 * @brief This method will enable all controller interrupts. 190 * 191 * @param[in] controller This parameter specifies the controller for which 192 * to enable interrupts. 193 * 194 * @return none 195 */ 196 void scic_controller_enable_interrupts( 197 SCI_CONTROLLER_HANDLE_T controller 198 ); 199 200 /** 201 * @brief This method will disable all controller interrupts. 202 * 203 * @param[in] controller This parameter specifies the controller for which 204 * to disable interrupts. 205 * 206 * @return none 207 */ 208 void scic_controller_disable_interrupts( 209 SCI_CONTROLLER_HANDLE_T controller 210 ); 211 212 /** 213 * @brief This method will return provide function pointers for the 214 * interrupt handler and completion handler. The interrupt handler 215 * is expected to be invoked at interrupt time. The completion 216 * handler is scheduled to run as a result of the interrupt handler. 217 * The completion handler performs the bulk work for processing 218 * silicon events. 219 * 220 * @param[in] interrupt_type This parameter informs the core which type 221 * of interrupt/completion methods are being requested. These 222 * are the types: SCIC_LEGACY_LINE_INTERRUPT_TYPE, 223 * SCIC_MSIX_INTERRUPT_TYPE, SCIC_NO_INTERRUPTS (POLLING) 224 * @param[in] message_count This parameter informs the core the 225 * number of MSI-X messages to be utilized. This parameter must 226 * be 0 when requesting legacy line based handlers. 227 * @param[in] handler_methods The caller provides a pointer to a buffer of 228 * type SCIC_CONTROLLER_HANDLER_METHODS_T. The size depends on 229 * the combination of the interrupt_type and message_count input 230 * parameters: 231 * SCIC_LEGACY_LINE_INTERRUPT_TYPE: 232 * - size = sizeof(SCIC_CONTROLLER_HANDLER_METHODS_T) 233 * SCIC_MSIX_INTERRUPT_TYPE: 234 * - size = message_count*sizeof(SCIC_CONTROLLER_HANDLER_METHODS_T) 235 * @param[out] handler_methods SCIC fills out the caller's buffer with the 236 * appropriate interrupt and completion handlers based on the info 237 * provided in the interrupt_type and message_count input 238 * parameters. For SCIC_LEGACY_LINE_INTERRUPT_TYPE, the buffer 239 * receives a single SCIC_CONTROLLER_HANDLER_METHODS_T element 240 * regardless that the message_count parameter is zero. 241 * For SCIC_MSIX_INTERRUPT_TYPE, the buffer receives an array of 242 * elements of type SCIC_CONTROLLER_HANDLER_METHODS_T where the 243 * array size is equivalent to the message_count parameter. The 244 * array is zero-relative where entry zero corresponds to 245 * message-vector zero, entry one corresponds to message-vector one, 246 * and so forth. 247 * 248 * @return Indicate if the handler retrieval operation was successful. 249 * @retval SCI_SUCCESS This value is returned if retrieval succeeded. 250 * @retval SCI_FAILURE_UNSUPPORTED_MESSAGE_COUNT This value is returned 251 * if the user supplied an unsupported number of MSI-X messages. 252 * For legacy line interrupts the only valid value is 0. 253 */ 254 SCI_STATUS scic_controller_get_handler_methods( 255 SCIC_INTERRUPT_TYPE interrupt_type, 256 U16 message_count, 257 SCIC_CONTROLLER_HANDLER_METHODS_T * handler_methods 258 ); 259 260 /** 261 * @brief This method will initialize the controller hardware managed by 262 * the supplied core controller object. This method will bring the 263 * physical controller hardware out of reset and enable the core to 264 * determine the capabilities of the hardware being managed. Thus, 265 * the core controller can determine it's exact physical (DMA capable) 266 * memory requirements. 267 * 268 * @pre The SCI Core user must have called scic_controller_construct() 269 * on the supplied controller object previously. 270 * 271 * @param[in] controller This parameter specifies the controller to be 272 * initialized. 273 * 274 * @return Indicate if the controller was successfully initialized or if 275 * it failed in some way. 276 * @retval SCI_SUCCESS This value is returned if the controller hardware 277 * was successfully initialized. 278 */ 279 SCI_STATUS scic_controller_initialize( 280 SCI_CONTROLLER_HANDLE_T controller 281 ); 282 283 /** 284 * @brief This method returns the suggested scic_controller_start() 285 * timeout amount. The user is free to use any timeout value, 286 * but this method provides the suggested minimum start timeout 287 * value. The returned value is based upon empirical information 288 * determined as a result of interoperability testing. 289 * 290 * @param[in] controller the handle to the controller object for which 291 * to return the suggested start timeout. 292 * 293 * @return This method returns the number of milliseconds for the 294 * suggested start operation timeout. 295 */ 296 U32 scic_controller_get_suggested_start_timeout( 297 SCI_CONTROLLER_HANDLE_T controller 298 ); 299 300 /** 301 * @brief This method will start the supplied core controller. This method 302 * will start the staggered spin up operation. The SCI User completion 303 * callback is called when the following conditions are met: 304 * -# the return status of this method is SCI_SUCCESS. 305 * -# after all of the phys have successfully started or been given 306 * the opportunity to start. 307 * 308 * @pre The SCI Core user must have filled in the physical memory 309 * descriptor structure via the 310 * sci_controller_get_memory_descriptor_list() method. 311 * @pre The SCI Core user must have invoked the scic_controller_initialize() 312 * method prior to invoking this method. 313 * 314 * @pre The controller must be in the INITIALIZED or STARTED state. 315 * 316 * @param[in] controller the handle to the controller object to start. 317 * @param[in] timeout This parameter specifies the number of milliseconds 318 * in which the start operation should complete. 319 * 320 * @return Indicate if the controller start method succeeded or failed in 321 * some way. 322 * @retval SCI_SUCCESS if the start operation succeeded. 323 * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in 324 * the STARTED state. 325 * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in 326 * the INITIALIZED or STARTED states. 327 * @retval SCI_FAILURE_INVALID_MEMORY_DESCRIPTOR if there are 328 * inconsistent or invalid values in the supplied 329 * SCI_PHYSICAL_MEMORY_DESCRIPTOR array. 330 */ 331 SCI_STATUS scic_controller_start( 332 SCI_CONTROLLER_HANDLE_T controller, 333 U32 timeout 334 ); 335 336 /** 337 * @brief This method will stop an individual controller object.This method 338 * will invoke the associated user callback upon completion. The 339 * completion callback is called when the following conditions are met: 340 * -# the method return status is SCI_SUCCESS. 341 * -# the controller has been quiesced. 342 * This method will ensure that all IO requests are quiesced, phys 343 * are stopped, and all additional operation by the hardware is halted. 344 * 345 * @pre The controller must be in the STARTED or STOPPED state. 346 * 347 * @param[in] controller the handle to the controller object to stop. 348 * @param[in] timeout This parameter specifies the number of milliseconds 349 * in which the stop operation should complete. 350 * 351 * @return Indicate if the controller stop method succeeded or failed in 352 * some way. 353 * @retval SCI_SUCCESS if the stop operation successfully began. 354 * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in 355 * the STOPPED state. 356 * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in 357 * the STARTED or STOPPED states. 358 */ 359 SCI_STATUS scic_controller_stop( 360 SCI_CONTROLLER_HANDLE_T controller, 361 U32 timeout 362 ); 363 364 /** 365 * @brief This method will reset the supplied core controller regardless of 366 * the state of said controller. This operation is considered 367 * destructive. In other words, all current operations are wiped 368 * out. No IO completions for outstanding devices occur. Outstanding 369 * IO requests are not aborted or completed at the actual remote 370 * device. 371 * 372 * @param[in] controller the handle to the controller object to reset. 373 * 374 * @return Indicate if the controller reset method succeeded or failed in 375 * some way. 376 * @retval SCI_SUCCESS if the reset operation successfully started. 377 * @retval SCI_FATAL_ERROR if the controller reset operation is unable to 378 * complete. 379 */ 380 SCI_STATUS scic_controller_reset( 381 SCI_CONTROLLER_HANDLE_T controller 382 ); 383 384 /** 385 * @brief This method is called by the SCI user to send/start an IO request. 386 * If the method invocation is successful, then the IO request has 387 * been queued to the hardware for processing. 388 * 389 * @warning 390 * - IO tags are a protected resource. It is incumbent upon the 391 * SCI Core user to ensure that each of the methods that may 392 * allocate or free available IO tags are handled in a mutually 393 * exclusive manner. This method is one of said methods requiring 394 * proper critical code section protection (e.g. semaphore, 395 * spin-lock, etc.). 396 * - For SATA, the user is required to manage NCQ tags. As a 397 * result, it is expected the user will have set the NCQ tag 398 * field in the host to device register FIS prior to calling 399 * this method. There is also a requirement for the user 400 * to call scic_stp_io_set_ncq_tag() prior to invoking the 401 * scic_controller_start_io() method. 402 * 403 * @param[in] controller the handle to the controller object for which 404 * to start an IO request. 405 * @param[in] remote_device the handle to the remote device object for which 406 * to start an IO request. 407 * @param[in] io_request the handle to the io request object to start. 408 * @param[in] io_tag This parameter specifies a previously allocated IO tag 409 * that the user desires to be utilized for this request. 410 * This parameter is optional. The user is allowed to supply 411 * SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter. 412 * @see scic_controller_allocate_tag() for more information 413 * on allocating a tag. 414 * 415 * @return Indicate if the controller successfully started the IO request. 416 * @retval SCI_IO_SUCCESS if the IO request was successfully started. 417 * 418 * @todo Determine the failure situations and return values. 419 */ 420 SCI_IO_STATUS scic_controller_start_io( 421 SCI_CONTROLLER_HANDLE_T controller, 422 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 423 SCI_IO_REQUEST_HANDLE_T io_request, 424 U16 io_tag 425 ); 426 427 #if !defined(DISABLE_TASK_MANAGEMENT) 428 429 /** 430 * @brief This method is called by the SCIC user to send/start a framework 431 * task management request. 432 * 433 * @warning 434 * - IO tags are a protected resource. It is incumbent upon the 435 * SCI Core user to ensure that each of the methods that may 436 * allocate or free available IO tags are handled in a mutually 437 * exclusive manner. This method is one of said methods requiring 438 * proper critical code section protection (e.g. semaphore, 439 * spin-lock, etc.). 440 * - The user must synchronize this task with completion queue 441 * processing. If they are not synchronized then it is possible 442 * for the io requests that are being managed by the task request 443 * can complete before starting the task request. 444 * 445 * @param[in] controller the handle to the controller object for which 446 * to start the task management request. 447 * @param[in] remote_device the handle to the remote device object for which 448 * to start the task management request. 449 * @param[in] task_request the handle to the task request object to start. 450 * @param[in] io_tag This parameter specifies a previously allocated IO tag 451 * that the user desires to be utilized for this request. Note 452 * this not the io_tag of the request being managed. It is to 453 * be utilized for the task request itself. 454 * This parameter is optional. The user is allowed to supply 455 * SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter. 456 * @see scic_controller_allocate_tag() for more information 457 * on allocating a tag. 458 * 459 * @return Indicate if the controller successfully started the IO request. 460 * @retval SCI_TASK_SUCCESS if the task request was successfully started. 461 * @retval SCI_TASK_FAILURE_REQUIRES_SCSI_ABORT This value is returned if 462 * there is/are task(s) outstanding that require termination or 463 * completion before this request can succeed. 464 */ 465 SCI_TASK_STATUS scic_controller_start_task( 466 SCI_CONTROLLER_HANDLE_T controller, 467 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 468 SCI_TASK_REQUEST_HANDLE_T task_request, 469 U16 io_tag 470 ); 471 472 /** 473 * @brief This method will perform core specific completion operations for 474 * task management request. After this method is invoked, the user should 475 * consider the task request as invalid until it is properly reused 476 * (i.e. re-constructed). 477 * 478 * @param[in] controller The handle to the controller object for which 479 * to complete the task management request. 480 * @param[in] remote_device The handle to the remote device object for which 481 * to complete the task management request. 482 * @param[in] task_request the handle to the task management request object 483 * to complete. 484 * 485 * @return Indicate if the controller successfully completed the task 486 * management request. 487 * @retval SCI_SUCCESS if the completion process was successful. 488 */ 489 SCI_STATUS scic_controller_complete_task( 490 SCI_CONTROLLER_HANDLE_T controller, 491 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 492 SCI_TASK_REQUEST_HANDLE_T task_request 493 ); 494 495 #else // !defined(DISABLE_TASK_MANAGEMENT) 496 497 #define scic_controller_start_task(controller, dev, task, tag) SCI_TASK_FAILURE 498 #define scic_controller_complete_task(controller, dev, task) SCI_FAILURE 499 500 #endif // !defined(DISABLE_TASK_MANAGEMENT) 501 502 /** 503 * @brief This method is called by the SCI Core user to terminate an ongoing 504 * (i.e. started) core IO request. This does not abort the IO request 505 * at the target, but rather removes the IO request from the host 506 * controller. 507 * 508 * @param[in] controller the handle to the controller object for which 509 * to terminate a request. 510 * @param[in] remote_device the handle to the remote device object for which 511 * to terminate a request. 512 * @param[in] request the handle to the io or task management request 513 * object to terminate. 514 * 515 * @return Indicate if the controller successfully began the terminate process 516 * for the IO request. 517 * @retval SCI_SUCCESS if the terminate process was successfully started for 518 * the request. 519 * 520 * @todo Determine the failure situations and return values. 521 */ 522 SCI_STATUS scic_controller_terminate_request( 523 SCI_CONTROLLER_HANDLE_T controller, 524 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 525 SCI_IO_REQUEST_HANDLE_T request 526 ); 527 528 /** 529 * @brief This method will perform core specific completion operations for 530 * an IO request. After this method is invoked, the user should 531 * consider the IO request as invalid until it is properly reused 532 * (i.e. re-constructed). 533 * 534 * @warning 535 * - IO tags are a protected resource. It is incumbent upon the 536 * SCI Core user to ensure that each of the methods that may 537 * allocate or free available IO tags are handled in a mutually 538 * exclusive manner. This method is one of said methods requiring 539 * proper critical code section protection (e.g. semaphore, 540 * spin-lock, etc.). 541 * - If the IO tag for a request was allocated, by the SCI Core user, 542 * using the scic_controller_allocate_io_tag() method, then it is 543 * the responsibility of the caller to invoke the 544 * scic_controller_free_io_tag() method to free the tag (i.e. this 545 * method will not free the IO tag). 546 * 547 * @param[in] controller The handle to the controller object for which 548 * to complete the IO request. 549 * @param[in] remote_device The handle to the remote device object for which 550 * to complete the IO request. 551 * @param[in] io_request the handle to the io request object to complete. 552 * 553 * @return Indicate if the controller successfully completed the IO request. 554 * @retval SCI_SUCCESS if the completion process was successful. 555 */ 556 SCI_STATUS scic_controller_complete_io( 557 SCI_CONTROLLER_HANDLE_T controller, 558 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 559 SCI_IO_REQUEST_HANDLE_T io_request 560 ); 561 562 563 /** 564 * @brief This method simply provides the user with a unique handle for a 565 * given SAS/SATA core port index. 566 * 567 * @param[in] controller This parameter represents the handle to the 568 * controller object from which to retrieve a port (SAS or 569 * SATA) handle. 570 * @param[in] port_index This parameter specifies the port index in 571 * the controller for which to retrieve the port handle. 572 * 0 <= port_index < maximum number of phys. 573 * @param[out] port_handle This parameter specifies the retrieved port handle 574 * to be provided to the caller. 575 * 576 * @return Indicate if the retrieval of the port handle was successful. 577 * @retval SCI_SUCCESS This value is returned if the retrieval was successful. 578 * @retval SCI_FAILURE_INVALID_PORT This value is returned if the supplied 579 * port id is not in the supported range. 580 */ 581 SCI_STATUS scic_controller_get_port_handle( 582 SCI_CONTROLLER_HANDLE_T controller, 583 U8 port_index, 584 SCI_PORT_HANDLE_T * port_handle 585 ); 586 587 /** 588 * @brief This method simply provides the user with a unique handle for a 589 * given SAS/SATA phy index/identifier. 590 * 591 * @param[in] controller This parameter represents the handle to the 592 * controller object from which to retrieve a phy (SAS or 593 * SATA) handle. 594 * @param[in] phy_index This parameter specifies the phy index in 595 * the controller for which to retrieve the phy handle. 596 * 0 <= phy_index < maximum number of phys. 597 * @param[out] phy_handle This parameter specifies the retrieved phy handle 598 * to be provided to the caller. 599 * 600 * @return Indicate if the retrieval of the phy handle was successful. 601 * @retval SCI_SUCCESS This value is returned if the retrieval was successful. 602 * @retval SCI_FAILURE_INVALID_PHY This value is returned if the supplied phy 603 * id is not in the supported range. 604 */ 605 SCI_STATUS scic_controller_get_phy_handle( 606 SCI_CONTROLLER_HANDLE_T controller, 607 U8 phy_index, 608 SCI_PHY_HANDLE_T * phy_handle 609 ); 610 611 /** 612 * @brief This method will allocate a tag from the pool of free IO tags. 613 * Direct allocation of IO tags by the SCI Core user is optional. 614 * The scic_controller_start_io() method will allocate an IO 615 * tag if this method is not utilized and the tag is not 616 * supplied to the IO construct routine. Direct allocation of IO tags 617 * may provide additional performance improvements in environments 618 * capable of supporting this usage model. Additionally, direct 619 * allocation of IO tags also provides additional flexibility to the 620 * SCI Core user. Specifically, the user may retain IO tags across 621 * the lives of multiple IO requests. 622 * 623 * @warning IO tags are a protected resource. It is incumbent upon the 624 * SCI Core user to ensure that each of the methods that may 625 * allocate or free available IO tags are handled in a mutually 626 * exclusive manner. This method is one of said methods requiring 627 * proper critical code section protection (e.g. semaphore, 628 * spin-lock, etc.). 629 * 630 * @param[in] controller the handle to the controller object for which to 631 * allocate the tag. 632 * 633 * @return An unsigned integer representing an available IO tag. 634 * @retval SCI_CONTROLLER_INVALID_IO_TAG This value is returned if there 635 * are no currently available tags to be allocated. 636 * @retval All return other values indicate a legitimate tag. 637 */ 638 U16 scic_controller_allocate_io_tag( 639 SCI_CONTROLLER_HANDLE_T controller 640 ); 641 642 /** 643 * @brief This method will free an IO tag to the pool of free IO tags. 644 * This method provides the SCI Core user more flexibility with 645 * regards to IO tags. The user may desire to keep an IO tag after 646 * an IO request has completed, because they plan on re-using the 647 * tag for a subsequent IO request. This method is only legal if 648 * the tag was allocated via scic_controller_allocate_io_tag(). 649 * 650 * @warning 651 * - IO tags are a protected resource. It is incumbent upon the 652 * SCI Core user to ensure that each of the methods that may 653 * allocate or free available IO tags are handled in a mutually 654 * exclusive manner. This method is one of said methods requiring 655 * proper critical code section protection (e.g. semaphore, 656 * spin-lock, etc.). 657 * - If the IO tag for a request was allocated, by the SCI Core user, 658 * using the scic_controller_allocate_io_tag() method, then it is 659 * the responsibility of the caller to invoke this method to free 660 * the tag. 661 * 662 * @param[in] controller This parameter specifies the handle to the 663 * controller object for which to free/return the tag. 664 * @param[in] io_tag This parameter represents the tag to be freed to the 665 * pool of available tags. 666 * 667 * @return This method returns an indication of whether the tag was 668 * successfully put back (freed) to the pool of available tags. 669 * @retval SCI_SUCCESS This return value indicates the tag was successfully 670 * placed into the pool of available IO tags. 671 * @retval SCI_FAILURE_INVALID_IO_TAG This value is returned if the supplied 672 * tag is not a valid IO tag value. 673 */ 674 SCI_STATUS scic_controller_free_io_tag( 675 SCI_CONTROLLER_HANDLE_T controller, 676 U16 io_tag 677 ); 678 679 /** 680 * @brief This method returns the size of the core's scratch RAM. 681 * 682 * @return Size of the scratch RAM in dwords. 683 */ 684 U32 scic_controller_get_scratch_ram_size( 685 SCI_CONTROLLER_HANDLE_T controller 686 ); 687 688 /** 689 * @brief This method allows the user to read a U32 from the core's 690 * scratch RAM. 691 * 692 * @param[in] controller This parameter represents the handle to the 693 * controller object for which to read scratch RAM. 694 * @param[in] offset The offset (in dwords) into the scratch RAM. 695 * @param[out] value The location where the read value should be stored. 696 * 697 * @return Indicate if the user specified a valid offset into the 698 * scratch RAM. 699 * @retval SCI_SUCCESS The scratch RAM was successfully read. 700 * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user specified an 701 * invalid offset. 702 */ 703 SCI_STATUS scic_controller_read_scratch_ram_dword( 704 SCI_CONTROLLER_HANDLE_T controller, 705 U32 offset, 706 U32 * value 707 ); 708 709 /** 710 * @brief This method allows the user to write a U32 to the core's 711 * scratch RAM. 712 * 713 * @param[in] controller This parameter represents the handle to the 714 * controller object for which to write scratch RAM. 715 * @param[in] offset The offset (in dwords) into the scratch RAM. 716 * @param[out] value The value to be written to scratch RAM. 717 * 718 * @return Indicate if the user specified a valid offset into the 719 * scratch RAM. 720 * @retval SCI_SUCCESS The scratch RAM was successfully written. 721 * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user specified an 722 * invalid offset. 723 */ 724 SCI_STATUS scic_controller_write_scratch_ram_dword( 725 SCI_CONTROLLER_HANDLE_T controller, 726 U32 offset, 727 U32 value 728 ); 729 730 /** 731 * @brief This method allows the user to configure the SCI core into 732 * either a performance mode or a memory savings mode. 733 * 734 * @param[in] controller This parameter represents the handle to the 735 * controller object for which to update the operating 736 * mode. 737 * @param[in] mode This parameter specifies the new mode for the 738 * controller. 739 * 740 * @return Indicate if the user successfully change the operating mode 741 * of the controller. 742 * @retval SCI_SUCCESS The user successfully updated the mode. 743 */ 744 SCI_STATUS scic_controller_set_mode( 745 SCI_CONTROLLER_HANDLE_T controller, 746 SCI_CONTROLLER_MODE mode 747 ); 748 749 750 #if !defined(DISABLE_INTERRUPTS) 751 /** 752 * @brief This method allows the user to configure the interrupt coalescence. 753 * 754 * @param[in] controller This parameter represents the handle to the 755 * controller object for which its interrupt coalesce register 756 * is overridden. 757 * 758 * @param[in] coalesce_number Used to control the number of entries in the 759 * Completion Queue before an interrupt is generated. If the 760 * number of entries exceed this number, an interrupt will be 761 * generated. The valid range of the input is [0, 256]. 762 * A setting of 0 results in coalescing being disabled. 763 * @param[in] coalesce_timeout Timeout value in microseconds. The valid range 764 * of the input is [0, 2700000] . A setting of 0 is allowed and 765 * results in no interrupt coalescing timeout. 766 * 767 * @return Indicate if the user successfully set the interrupt coalesce parameters. 768 * @retval SCI_SUCCESS The user successfully updated the interrutp coalescence. 769 * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user input value is out of range. 770 */ 771 SCI_STATUS scic_controller_set_interrupt_coalescence( 772 SCI_CONTROLLER_HANDLE_T controller, 773 U32 coalesce_number, 774 U32 coalesce_timeout 775 ); 776 777 /** 778 * @brief This method retrieves the interrupt coalescing values 779 * 780 * @param[in] controller This parameter specifies the controller for 781 * which its interrupt coalescing number is read. 782 * 783 * @param[out] coalesce_number, interrupt coalescing number read from controller. 784 * 785 * @param[out] coalesce_timeout, timeout value in microseconds. 786 * 787 * @return None 788 */ 789 void scic_controller_get_interrupt_coalescence( 790 SCI_CONTROLLER_HANDLE_T controller, 791 U32 * coalesce_number, 792 U32 * coalesce_timeout 793 ); 794 #else // !defined(DISABLE_INTERRUPTS) 795 #define scic_controller_set_interrupt_coalescence(controller, num, timeout) \ 796 SCI_FAILURE 797 #define scic_controller_get_interrupt_coalescence(controller, num, timeout) 798 #endif // !defined(DISABLE_INTERRUPTS) 799 800 801 /** 802 * @brief This method suspend the controller, reinitialize RAMs, then resume 803 * the controller. 804 * 805 * @param[in] controller This parameter specifies the controller which is transitioning. 806 * 807 * @param[in] restrict_completions This parameter specifies whether the controller should 808 * ignore completion processing for non-fastpath events. This will cause 809 * the completions to be thrown away. 810 * 811 * @return SCI_STATUS The status of controller transition. 812 */ 813 SCI_STATUS scic_controller_transition( 814 SCI_CONTROLLER_HANDLE_T controller, 815 BOOL restrict_completions 816 ); 817 818 819 /** 820 * @brief This method suspends the controller. 821 * 822 * @param[in] controller This parameter specifies the controller which is to be suspended. 823 * 824 * @return SCI_STATUS The status of controller suspend. 825 */ 826 SCI_STATUS scic_controller_suspend( 827 SCI_CONTROLLER_HANDLE_T controller 828 ); 829 830 /** 831 * @brief This method resumes the controller. 832 * 833 * @param[in] controller This parameter specifies the controller which is to be resumed. 834 * 835 * @return SCI_STATUS The status of controller resume. 836 */ 837 SCI_STATUS scic_controller_resume( 838 SCI_CONTROLLER_HANDLE_T controller 839 ); 840 841 SCI_STATUS scic_controller_get_max_ports( 842 SCI_CONTROLLER_HANDLE_T controller, 843 U8 * count 844 ); 845 846 SCI_STATUS scic_controller_get_max_phys( 847 SCI_CONTROLLER_HANDLE_T controller, 848 U8 * count 849 ); 850 851 #ifdef __cplusplus 852 } 853 #endif // __cplusplus 854 855 #endif // _SCIC_CONTROLLER_H_ 856 857