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 #ifndef _SCIF_USER_CALLBACK_H_ 55 #define _SCIF_USER_CALLBACK_H_ 56 57 /** 58 * @file 59 * 60 * @brief This file contains all of the interface methods/macros that must 61 * be implemented by an SCI Framework user. 62 */ 63 64 65 #ifdef __cplusplus 66 extern "C" { 67 #endif // __cplusplus 68 69 #include <dev/isci/scil/sci_types.h> 70 #include <dev/isci/scil/sci_status.h> 71 #include <dev/isci/scil/sci_controller.h> 72 #include <dev/isci/scil/intel_sas.h> 73 #include <dev/isci/scil/sci_memory_descriptor_list.h> 74 75 76 /** 77 * @brief This callback method asks the user to create a timer and provide 78 * a handle for this timer for use in further timer interactions. 79 * 80 * @warning The "timer_callback" method should be executed in a mutually 81 * exclusive manner from the controller completion handler 82 * handler (refer to scic_controller_get_handler_methods()). 83 * 84 * @param[in] timer_callback This parameter specifies the callback method 85 * to be invoked whenever the timer expires. 86 * @param[in] controller This parameter specifies the controller with 87 * which this timer is to be associated. 88 * @param[in] cookie This parameter specifies a piece of information that 89 * the user must retain. This cookie is to be supplied by the 90 * user anytime a timeout occurs for the created timer. 91 * 92 * @return This method returns a handle to a timer object created by the 93 * user. The handle will be utilized for all further interactions 94 * relating to this timer. 95 */ 96 void * scif_cb_timer_create( 97 SCI_CONTROLLER_HANDLE_T controller, 98 SCI_TIMER_CALLBACK_T timer_callback, 99 void * cookie 100 ); 101 102 /** 103 * @brief This callback method asks the user to destroy the supplied timer. 104 * 105 * @param[in] controller This parameter specifies the controller with 106 * which this timer is to associated. 107 * @param[in] timer This parameter specifies the timer to be destroyed. 108 * 109 * @return none 110 */ 111 void scif_cb_timer_destroy( 112 SCI_CONTROLLER_HANDLE_T controller, 113 void * timer 114 ); 115 116 /** 117 * @brief This callback method asks the user to start the supplied timer. 118 * 119 * @warning All timers in the system started by the SCI Framework are one 120 * shot timers. Therefore, the SCI user should make sure that it 121 * removes the timer from it's list when a timer actually fires. 122 * Additionally, SCI Framework user's should be able to handle 123 * calls from the SCI Framework to stop a timer that may already 124 * be stopped. 125 * 126 * @param[in] controller This parameter specifies the controller with 127 * which this timer is to associated. 128 * @param[in] timer This parameter specifies the timer to be started. 129 * @param[in] milliseconds This parameter specifies the number of 130 * milliseconds for which to stall. The operating system driver 131 * is allowed to round this value up where necessary. 132 * 133 * @return none 134 */ 135 void scif_cb_timer_start( 136 SCI_CONTROLLER_HANDLE_T controller, 137 void * timer, 138 U32 milliseconds 139 ); 140 141 /** 142 * @brief This callback method asks the user to stop the supplied timer. 143 * 144 * @param[in] controller This parameter specifies the controller with 145 * which this timer is to associated. 146 * @param[in] timer This parameter specifies the timer to be stopped. 147 * 148 * @return none 149 */ 150 void scif_cb_timer_stop( 151 SCI_CONTROLLER_HANDLE_T controller, 152 void * timer 153 ); 154 155 /** 156 * @brief This callback method asks the user to associate the supplied 157 * lock with an operating environment specific locking construct. 158 * 159 * @param[in] controller This parameter specifies the controller with 160 * which this lock is to be associated. 161 * @param[in] lock This parameter specifies the lock for which the 162 * user should associate an operating environment specific 163 * locking object. 164 * 165 * @see The SCI_LOCK_LEVEL enumeration for more information. 166 * 167 * @return none. 168 */ 169 void scif_cb_lock_associate( 170 SCI_CONTROLLER_HANDLE_T controller, 171 SCI_LOCK_HANDLE_T lock 172 ); 173 174 /** 175 * @brief This callback method asks the user to de-associate the supplied 176 * lock with an operating environment specific locking construct. 177 * 178 * @param[in] controller This parameter specifies the controller with 179 * which this lock is to be de-associated. 180 * @param[in] lock This parameter specifies the lock for which the 181 * user should de-associate an operating environment specific 182 * locking object. 183 * 184 * @see The SCI_LOCK_LEVEL enumeration for more information. 185 * 186 * @return none. 187 */ 188 void scif_cb_lock_disassociate( 189 SCI_CONTROLLER_HANDLE_T controller, 190 SCI_LOCK_HANDLE_T lock 191 ); 192 193 194 /** 195 * @brief This callback method asks the user to acquire/get the lock. 196 * This method should pend until the lock has been acquired. 197 * 198 * @param[in] controller This parameter specifies the controller with 199 * which this lock is associated. 200 * @param[in] lock This parameter specifies the lock to be acquired. 201 * 202 * @return none 203 */ 204 void scif_cb_lock_acquire( 205 SCI_CONTROLLER_HANDLE_T controller, 206 SCI_LOCK_HANDLE_T lock 207 ); 208 209 /** 210 * @brief This callback method asks the user to release a lock. 211 * 212 * @param[in] controller This parameter specifies the controller with 213 * which this lock is associated. 214 * @param[in] lock This parameter specifies the lock to be released. 215 * 216 * @return none 217 */ 218 void scif_cb_lock_release( 219 SCI_CONTROLLER_HANDLE_T controller, 220 SCI_LOCK_HANDLE_T lock 221 ); 222 223 /** 224 * @brief This user callback will inform the user that the controller has 225 * had a serious unexpected error. The user should not the error, 226 * disable interrupts, and wait for current ongoing processing to 227 * complete. Subsequently, the user should reset the controller. 228 * 229 * @param[in] controller This parameter specifies the controller that had 230 * an error. 231 * 232 * @return none 233 */ 234 void scif_cb_controller_error( 235 SCI_CONTROLLER_HANDLE_T controller, 236 SCI_CONTROLLER_ERROR error 237 ); 238 239 /** 240 * @brief This user callback will inform the user that the controller has 241 * finished the start process. 242 * 243 * @param[in] controller This parameter specifies the controller that was 244 * started. 245 * @param[in] completion_status This parameter specifies the results of 246 * the start operation. SCI_SUCCESS indicates successful 247 * completion. 248 * 249 * @return none 250 */ 251 void scif_cb_controller_start_complete( 252 SCI_CONTROLLER_HANDLE_T controller, 253 SCI_STATUS completion_status 254 ); 255 256 /** 257 * @brief This user callback will inform the user that the controller has 258 * finished the stop process. Note, after user calls 259 * scif_controller_stop(), before user receives this controller stop 260 * complete callback, user should not expect any callback from 261 * framework, such like scif_cb_domain_change_notification(). 262 * 263 * @param[in] controller This parameter specifies the controller that was 264 * stopped. 265 * @param[in] completion_status This parameter specifies the results of 266 * the stop operation. SCI_SUCCESS indicates successful 267 * completion. 268 * 269 * @return none 270 */ 271 void scif_cb_controller_stop_complete( 272 SCI_CONTROLLER_HANDLE_T controller, 273 SCI_STATUS completion_status 274 ); 275 276 /** 277 * @brief This method simply returns the virtual address associated 278 * with the scsi_io and byte_offset supplied parameters. 279 * 280 * @note This callback is not utilized in the fast path. The expectation 281 * is that this method is utilized for items such as SCSI to ATA 282 * translation for commands like INQUIRY, READ CAPACITY, etc. 283 * 284 * @param[in] scif_user_io_request This parameter points to the user's 285 * IO request object. It is a cookie that allows the user to 286 * provide the necessary information for this callback. 287 * @param[in] byte_offset This parameter specifies the offset into the data 288 * buffers pointed to by the SGL. The byte offset starts at 0 289 * and continues until the last byte pointed to be the last SGL 290 * element. 291 * 292 * @return A virtual address pointer to the location specified by the 293 * parameters. 294 */ 295 U8 * scif_cb_io_request_get_virtual_address_from_sgl( 296 void * scif_user_io_request, 297 U32 byte_offset 298 ); 299 300 #ifdef ENABLE_OSSL_COPY_BUFFER 301 /** 302 * @brief This method is presently utilized in the PIO path, 303 * copies from UF buffer to the SGL buffer. This method 304 * can be served for other OS related copies. 305 * 306 * @param[in] user_io_request. This parameter points to the user's 307 * IO request object. It is a cookie that allows the user to 308 * provide the necessary information for this callback. 309 * @param[in] source addr. Address of UF buffer. 310 * @param[in] offset. This parameter specifies the offset into the data 311 * buffers pointed to by the SGL. The byte offset starts at 0 312 * and continues until the last byte pointed to be the last SGL 313 * element. 314 * @param[in] length. 315 * 316 * @return None 317 */ 318 void scif_cb_io_request_copy_buffer( 319 void * scic_user_io_request, 320 U8 *source_addr, 321 U32 offset, 322 U32 length 323 ); 324 #endif 325 326 /** 327 * @brief This user callback will inform the user that an IO request has 328 * completed. 329 * 330 * @param[in] controller This parameter specifies the controller on 331 * which the IO request is completing. 332 * @param[in] remote_device This parameter specifies the remote device on 333 * which this request is completing. 334 * @param[in] io_request This parameter specifies the IO request that has 335 * completed. 336 * @param[in] completion_status This parameter specifies the results of 337 * the IO request operation. SCI_IO_SUCCESS indicates 338 * successful completion. 339 * 340 * @return none 341 */ 342 void scif_cb_io_request_complete( 343 SCI_CONTROLLER_HANDLE_T controller, 344 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 345 SCI_IO_REQUEST_HANDLE_T io_request, 346 SCI_IO_STATUS completion_status 347 ); 348 349 /** 350 * @brief This user callback will inform the user that a task management 351 * request completed. 352 * 353 * @param[in] controller This parameter specifies the controller on 354 * which the task management request is completing. 355 * @param[in] remote_device This parameter specifies the remote device on 356 * which this task management request is completing. 357 * @param[in] task_request This parameter specifies the task management 358 * request that has completed. 359 * @param[in] completion_status This parameter specifies the results of 360 * the IO request operation. SCI_TASK_SUCCESS indicates 361 * successful completion. 362 * 363 * @return none 364 */ 365 void scif_cb_task_request_complete( 366 SCI_CONTROLLER_HANDLE_T controller, 367 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 368 SCI_TASK_REQUEST_HANDLE_T task_request, 369 SCI_TASK_STATUS completion_status 370 ); 371 372 /** 373 * @brief This callback method asks the user to provide the number of 374 * bytes to be transferred as part of this request. 375 * 376 * @param[in] scif_user_io_request This parameter points to the user's 377 * IO request object. It is a cookie that allows the user to 378 * provide the necessary information for this callback. 379 * 380 * @return This method returns the number of payload data bytes to be 381 * transferred for this IO request. 382 */ 383 U32 scif_cb_io_request_get_transfer_length( 384 void * scif_user_io_request 385 ); 386 387 /** 388 * @brief This callback method asks the user to provide the data direction 389 * for this request. 390 * 391 * @param[in] scif_user_io_request This parameter points to the user's 392 * IO request object. It is a cookie that allows the user to 393 * provide the necessary information for this callback. 394 * 395 * @return This method returns the value of SCI_IO_REQUEST_DATA_OUT, 396 * SCI_IO_REQUEST_DATA_IN, or SCI_IO_REQUEST_NO_DATA. 397 */ 398 SCI_IO_REQUEST_DATA_DIRECTION scif_cb_io_request_get_data_direction( 399 void * scif_user_io_request 400 ); 401 402 #ifndef SCI_SGL_OPTIMIZATION_ENABLED 403 /** 404 * @brief This callback method asks the user to provide the address 405 * to where the next Scatter-Gather Element is located. 406 * 407 * Details regarding usage: 408 * - Regarding the first SGE: the user should initialize an index, 409 * or a pointer, prior to construction of the request that will 410 * reference the very first scatter-gather element. This is 411 * important since this method is called for every scatter-gather 412 * element, including the first element. 413 * - Regarding the last SGE: the user should return NULL from this 414 * method when this method is called and the SGL has exhausted 415 * all elements. 416 * 417 * @param[in] scif_user_io_request This parameter points to the user's 418 * IO request object. It is a cookie that allows the user to 419 * provide the necessary information for this callback. 420 * @param[in] current_sge_address This parameter specifies the address for 421 * the current SGE (i.e. the one that has just processed). 422 * @param[out] next_sge An address specifying the location for the next scatter 423 * gather element to be processed. 424 * 425 * @return None. 426 */ 427 void scif_cb_io_request_get_next_sge( 428 void * scif_user_io_request, 429 void * current_sge_address, 430 void ** next_sge 431 ); 432 #endif 433 434 /** 435 * @brief This callback method asks the user to provide the contents of the 436 * "address" field in the Scatter-Gather Element. 437 * 438 * @param[in] scif_user_io_request This parameter points to the user's 439 * IO request object. It is a cookie that allows the user to 440 * provide the necessary information for this callback. 441 * @param[in] sge_address This parameter specifies the address for the 442 * SGE from which to retrieve the address field. 443 * 444 * @return A physical address specifying the contents of the SGE's address 445 * field. 446 */ 447 SCI_PHYSICAL_ADDRESS scif_cb_sge_get_address_field( 448 void * scif_user_io_request, 449 void * sge_address 450 ); 451 452 /** 453 * @brief This callback method asks the user to provide the contents of the 454 * "length" field in the Scatter-Gather Element. 455 * 456 * @param[in] scif_user_io_request This parameter points to the user's 457 * IO request object. It is a cookie that allows the user to 458 * provide the necessary information for this callback. 459 * @param[in] sge_address This parameter specifies the address for the 460 * SGE from which to retrieve the address field. 461 * 462 * @return This method returns the length field specified inside the SGE 463 * referenced by the sge_address parameter. 464 */ 465 U32 scif_cb_sge_get_length_field( 466 void * scif_user_io_request, 467 void * sge_address 468 ); 469 470 /** 471 * @brief This callback method asks the user to provide the address for 472 * the command descriptor block (CDB) associated with this IO request. 473 * 474 * @param[in] scif_user_io_request This parameter points to the user's 475 * IO request object. It is a cookie that allows the user to 476 * provide the necessary information for this callback. 477 * 478 * @return This method returns the virtual address of the CDB. 479 */ 480 void * scif_cb_io_request_get_cdb_address( 481 void * scif_user_io_request 482 ); 483 484 /** 485 * @brief This callback method asks the user to provide the length of 486 * the command descriptor block (CDB) associated with this IO request. 487 * 488 * @param[in] scif_user_io_request This parameter points to the user's 489 * IO request object. It is a cookie that allows the user to 490 * provide the necessary information for this callback. 491 * 492 * @return This method returns the length of the CDB. 493 */ 494 U32 scif_cb_io_request_get_cdb_length( 495 void * scif_user_io_request 496 ); 497 498 /** 499 * @brief This callback method asks the user to provide the Logical Unit (LUN) 500 * associated with this IO request. 501 * 502 * @note The contents of the value returned from this callback are defined 503 * by the protocol standard (e.g. T10 SAS specification). Please 504 * refer to the transport command information unit description 505 * in the associated standard. 506 * 507 * @param[in] scif_user_io_request This parameter points to the user's 508 * IO request object. It is a cookie that allows the user to 509 * provide the necessary information for this callback. 510 * 511 * @return This method returns the LUN associated with this request. 512 */ 513 U32 scif_cb_io_request_get_lun( 514 void * scif_user_io_request 515 ); 516 517 /** 518 * @brief This callback method asks the user to provide the task attribute 519 * associated with this IO request. 520 * 521 * @note The contents of the value returned from this callback are defined 522 * by the protocol standard (e.g. T10 SAS specification). Please 523 * refer to the transport command information unit description 524 * in the associated standard. 525 * 526 * @param[in] scif_user_io_request This parameter points to the user's 527 * IO request object. It is a cookie that allows the user to 528 * provide the necessary information for this callback. 529 * 530 * @return This method returns the task attribute associated with this 531 * IO request. 532 */ 533 U32 scif_cb_io_request_get_task_attribute( 534 void * scif_user_io_request 535 ); 536 537 /** 538 * @brief This callback method asks the user to provide the command priority 539 * associated with this IO request. 540 * 541 * @note The contents of the value returned from this callback are defined 542 * by the protocol standard (e.g. T10 SAS specification). Please 543 * refer to the transport command information unit description 544 * in the associated standard. 545 * 546 * @param[in] scif_user_io_request This parameter points to the user's 547 * IO request object. It is a cookie that allows the user to 548 * provide the necessary information for this callback. 549 * 550 * @return This method returns the command priority associated with this 551 * IO request. 552 */ 553 U32 scif_cb_io_request_get_command_priority( 554 void * scif_user_io_request 555 ); 556 557 /** 558 * @brief This method returns the Logical Unit to be utilized for this 559 * task management request. 560 * 561 * @note The contents of the value returned from this callback are defined 562 * by the protocol standard (e.g. T10 SAS specification). Please 563 * refer to the transport task information unit description 564 * in the associated standard. 565 * 566 * @param[in] scif_user_task_request This parameter points to the user's 567 * task request object. It is a cookie that allows the user to 568 * provide the necessary information for this callback. 569 * 570 * @return This method returns the LUN associated with this request. 571 * @todo This should be U64? 572 */ 573 U32 scif_cb_task_request_get_lun( 574 void * scif_user_task_request 575 ); 576 577 /** 578 * @brief This method returns the task management function to be utilized 579 * for this task request. 580 * 581 * @note The contents of the value returned from this callback are defined 582 * by the protocol standard (e.g. T10 SAS specification). Please 583 * refer to the transport task information unit description 584 * in the associated standard. 585 * 586 * @param[in] scif_user_task_request This parameter points to the user's 587 * task request object. It is a cookie that allows the user to 588 * provide the necessary information for this callback. 589 * 590 * @return This method returns an unsigned byte representing the task 591 * management function to be performed. 592 */ 593 U8 scif_cb_task_request_get_function( 594 void * scif_user_task_request 595 ); 596 597 /** 598 * @brief This method returns the task management IO tag to be managed. 599 * Depending upon the task management function the value returned 600 * from this method may be ignored. 601 * 602 * @param[in] scif_user_task_request This parameter points to the user's 603 * task request object. It is a cookie that allows the user to 604 * provide the necessary information for this callback. 605 * 606 * @return This method returns an unsigned 16-bit word depicting the IO 607 * tag to be managed. 608 */ 609 U16 scif_cb_task_request_get_io_tag_to_manage( 610 void * scif_user_task_request 611 ); 612 613 /** 614 * @brief This callback method asks the user to provide the virtual 615 * address of the response data buffer for the supplied IO request. 616 * 617 * @param[in] scif_user_task_request This parameter points to the user's 618 * task request object. It is a cookie that allows the user to 619 * provide the necessary information for this callback. 620 * 621 * @return This method returns the virtual address for the response data buffer 622 * associated with this IO request. 623 */ 624 void * scif_cb_task_request_get_response_data_address( 625 void * scif_user_task_request 626 ); 627 628 /** 629 * @brief This callback method asks the user to provide the length of the 630 * response data buffer for the supplied IO request. 631 * 632 * @param[in] scif_user_task_request This parameter points to the user's 633 * task request object. It is a cookie that allows the user to 634 * provide the necessary information for this callback. 635 * 636 * @return This method returns the length of the response buffer data 637 * associated with this IO request. 638 */ 639 U32 scif_cb_task_request_get_response_data_length( 640 void * scif_user_task_request 641 ); 642 643 /** 644 * @brief In this method the user is expected to log the supplied 645 * error information. The user must be capable of handling variable 646 * length argument lists and should consider prepending the fact 647 * that this is an error from the framework. 648 * 649 * @param[in] logger_object This parameter specifies the logger object 650 * associated with this message. 651 * @param[in] log_object_mask This parameter specifies the log objects 652 * for which this message is being generated. 653 * @param[in] log_message This parameter specifies the message to be logged. 654 * 655 * @return none 656 */ 657 void scif_cb_logger_log_error( 658 SCI_LOGGER_HANDLE_T logger_object, 659 U32 log_object_mask, 660 char * log_message, 661 ... 662 ); 663 664 /** 665 * @brief In this method the user is expected to log the supplied warning 666 * information. The user must be capable of handling variable 667 * length argument lists and should consider prepending the fact 668 * that this is a warning from the framework. 669 * 670 * @param[in] logger_object This parameter specifies the logger object 671 * associated with this message. 672 * @param[in] log_object_mask This parameter specifies the log objects 673 * for which this message is being generated. 674 * @param[in] log_message This parameter specifies the message to be logged. 675 * 676 * @return none 677 */ 678 void scif_cb_logger_log_warning( 679 SCI_LOGGER_HANDLE_T logger_object, 680 U32 log_object_mask, 681 char * log_message, 682 ... 683 ); 684 685 /** 686 * @brief In this method the user is expected to log the supplied debug 687 * information. The user must be capable of handling variable 688 * length argument lists and should consider prepending the fact 689 * that this is a debug message from the framework. 690 * 691 * @param[in] logger_object This parameter specifies the logger object 692 * associated with this message. 693 * @param[in] log_object_mask This parameter specifies the log objects 694 * for which this message is being generated. 695 * @param[in] log_message This parameter specifies the message to be logged. 696 * 697 * @return none 698 */ 699 void scif_cb_logger_log_info( 700 SCI_LOGGER_HANDLE_T logger_object, 701 U32 log_object_mask, 702 char * log_message, 703 ... 704 ); 705 706 707 /** 708 * @brief In this method the user is expected to log the supplied function 709 * trace information. The user must be capable of handling variable 710 * length argument lists and should consider prepending the fact 711 * that this is a function trace (i.e. entry/exit) message from the 712 * framework. 713 * 714 * @param[in] logger_object This parameter specifies the logger object 715 * associated with this message. 716 * @param[in] log_object_mask This parameter specifies the log objects 717 * for which this message is being generated. 718 * @param[in] log_message This parameter specifies the message to be logged. 719 * 720 * @return none 721 */ 722 void scif_cb_logger_log_trace( 723 SCI_LOGGER_HANDLE_T logger_object, 724 U32 log_object_mask, 725 char * log_message, 726 ... 727 ); 728 729 730 /** 731 * @brief In this method the user is expected to log the supplied state 732 * transition information. The user must be capable of handling 733 * variable length argument lists and should consider prepending the 734 * fact that this is an error from the framework. 735 * 736 * @param[in] logger_object This parameter specifies the logger object 737 * associated with this message. 738 * @param[in] log_object_mask This parameter specifies the log objects 739 * for which this message is being generated. 740 * @param[in] log_message This parameter specifies the message to be logged. 741 * 742 * @return none 743 */ 744 void scif_cb_logger_log_states( 745 SCI_LOGGER_HANDLE_T logger_object, 746 U32 log_object_mask, 747 char * log_message, 748 ... 749 ); 750 751 752 /** 753 * @brief This callback method informs the framework user that something 754 * in the supplied domain has changed (e.g. a device was added or 755 * removed). 756 * 757 * This callback is called by the framework outside of discovery or 758 * target reset processes. Specifically, domain changes occurring 759 * during these processes are handled by the framework. For example, 760 * in the case of Serial Attached SCSI, reception of a BROADCAST (CHANGE) 761 * during discovery will cause discovery to restart. Thus, discovery 762 * does not complete until all BCNs are processed. Note, during controller 763 * stopping/reset process, the framework user should not expect this call 764 * back. 765 * 766 * @param[in] controller This parameter specifies the controller object 767 * with which this callback is associated. 768 * @param[in] domain This parameter specifies the domain object with 769 * which this callback is associated. 770 * 771 * @return none 772 */ 773 void scif_cb_domain_change_notification( 774 SCI_CONTROLLER_HANDLE_T controller, 775 SCI_DOMAIN_HANDLE_T domain 776 ); 777 778 779 /** 780 * @brief This callback method informs the framework user that a previously 781 * requested discovery operation on the domain has completed. 782 * 783 * @param[in] controller This parameter specifies the controller object 784 * with which this callback is associated. 785 * @param[in] domain This parameter specifies the domain object with 786 * which this callback is associated. 787 * @param[in] completion_status This parameter indicates the results of the 788 * discovery operation. 789 * 790 * @return none 791 */ 792 void scif_cb_domain_discovery_complete( 793 SCI_CONTROLLER_HANDLE_T controller, 794 SCI_DOMAIN_HANDLE_T domain, 795 SCI_STATUS completion_status 796 ); 797 798 /** 799 * @brief This callback method informs the framework user that a previously 800 * requested reset operation on the domain has completed. 801 * 802 * @param[in] controller This parameter specifies the controller object 803 * with which this callback is associated. 804 * @param[in] domain This parameter specifies the domain object with 805 * which this callback is associated. 806 * @param[in] completion_status This parameter indicates the results of the 807 * reset operation. 808 * 809 * @return none 810 */ 811 void scif_cb_domain_reset_complete( 812 SCI_CONTROLLER_HANDLE_T controller, 813 SCI_DOMAIN_HANDLE_T domain, 814 SCI_STATUS completion_status 815 ); 816 817 /** 818 * @brief This callback method informs the framework user that the domain 819 * is ready and capable of processing IO requests for devices found 820 * inside it. 821 * 822 * @param[in] controller This parameter specifies the controller object 823 * with which this callback is associated. 824 * @param[in] domain This parameter specifies the domain object with 825 * which this callback is associated. 826 * 827 * @return none 828 */ 829 void scif_cb_domain_ready( 830 SCI_CONTROLLER_HANDLE_T controller, 831 SCI_DOMAIN_HANDLE_T domain 832 ); 833 834 /** 835 * @brief This callback method informs the framework user that the domain 836 * is no longer ready. Thus, it is incapable of processing IO 837 * requests for devices found inside it. 838 * 839 * @param[in] controller This parameter specifies the controller object 840 * with which this callback is associated. 841 * @param[in] domain This parameter specifies the domain object with 842 * which this callback is associated. 843 * 844 * @return none 845 */ 846 void scif_cb_domain_not_ready( 847 SCI_CONTROLLER_HANDLE_T controller, 848 SCI_DOMAIN_HANDLE_T domain 849 ); 850 851 /** 852 * @brief This callback method informs the framework user that a new 853 * direct attached device was found in the domain. 854 * 855 * @param[in] controller This parameter specifies the controller object 856 * with which this callback is associated. 857 * @param[in] domain This parameter specifies the domain object with 858 * which this callback is associated. 859 * @param[in] sas_address This parameter specifies the SAS address of 860 * the new device. 861 * @param[in] protocols This parameter specifies the protocols 862 * supported by the newly discovered device. 863 * 864 * @return none 865 */ 866 void scif_cb_domain_da_device_added( 867 SCI_CONTROLLER_HANDLE_T controller, 868 SCI_DOMAIN_HANDLE_T domain, 869 SCI_SAS_ADDRESS_T * sas_address, 870 SCI_SAS_IDENTIFY_ADDRESS_FRAME_PROTOCOLS_T * protocols 871 ); 872 873 /** 874 * @brief This callback method informs the framework user that a new 875 * expander attached device was found in the domain. 876 * 877 * @param[in] controller This parameter specifies the controller object 878 * with which this callback is associated. 879 * @param[in] domain This parameter specifies the domain object with 880 * which this callback is associated. 881 * @param[in] containing_device This parameter specifies the remote 882 * device that contains the device that was added. 883 * @param[in] smp_response This parameter specifies the SMP response 884 * data associated with the newly discovered device. 885 * 886 * @return none 887 */ 888 void scif_cb_domain_ea_device_added( 889 SCI_CONTROLLER_HANDLE_T controller, 890 SCI_DOMAIN_HANDLE_T domain, 891 SCI_REMOTE_DEVICE_HANDLE_T containing_device, 892 SMP_RESPONSE_DISCOVER_T * smp_response 893 ); 894 895 /** 896 * @brief This callback method informs the framework user that a device 897 * has been removed from the domain. 898 * 899 * @param[in] controller This parameter specifies the controller object 900 * with which this callback is associated. 901 * @param[in] domain This parameter specifies the domain object with 902 * which this callback is associated. 903 * @param[in] remote_device This parameter specifies the device object with 904 * which this callback is associated. 905 * 906 * @return none 907 */ 908 void scif_cb_domain_device_removed( 909 SCI_CONTROLLER_HANDLE_T controller, 910 SCI_DOMAIN_HANDLE_T domain, 911 SCI_REMOTE_DEVICE_HANDLE_T remote_device 912 ); 913 914 /** 915 * @brief This callback method informs the framework user that the remote 916 * device is ready and capable of processing IO requests. 917 * 918 * @param[in] controller This parameter specifies the controller object 919 * with which this callback is associated. 920 * @param[in] domain This parameter specifies the domain object with 921 * which this callback is associated. 922 * @param[in] remote_device This parameter specifies the device object with 923 * which this callback is associated. 924 * 925 * @return none 926 */ 927 void scif_cb_remote_device_ready( 928 SCI_CONTROLLER_HANDLE_T controller, 929 SCI_DOMAIN_HANDLE_T domain, 930 SCI_REMOTE_DEVICE_HANDLE_T remote_device 931 ); 932 933 /** 934 * @brief This callback method informs the framework user that the remote 935 * device is not ready. Thus, it is incapable of processing IO 936 * requests. 937 * 938 * @param[in] controller This parameter specifies the controller object 939 * with which this callback is associated. 940 * @param[in] domain This parameter specifies the domain object with 941 * which this callback is associated. 942 * @param[in] remote_device This parameter specifies the device object with 943 * which this callback is associated. 944 * 945 * @return none 946 */ 947 void scif_cb_remote_device_not_ready( 948 SCI_CONTROLLER_HANDLE_T controller, 949 SCI_DOMAIN_HANDLE_T domain, 950 SCI_REMOTE_DEVICE_HANDLE_T remote_device 951 ); 952 953 /** 954 * @brief This callback method informs the framework user that the remote 955 * device failed. This typically occurs shortly after the device 956 * has been discovered, during the configuration phase for the device. 957 * 958 * @param[in] controller This parameter specifies the controller object 959 * with which this callback is associated. 960 * @param[in] domain This parameter specifies the domain object with 961 * which this callback is associated. 962 * @param[in] remote_device This parameter specifies the device object with 963 * which this callback is associated. 964 * @param[in] status This parameter specifies the specific failure condition 965 * associated with this device failure. 966 * 967 * @return none 968 */ 969 void scif_cb_remote_device_failed( 970 SCI_CONTROLLER_HANDLE_T controller, 971 SCI_DOMAIN_HANDLE_T domain, 972 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 973 SCI_STATUS status 974 ); 975 976 977 978 /** 979 * @brief This callback method creates an OS specific deferred task 980 * for internal usage. The handler to deferred task is stored by OS 981 * driver. 982 * 983 * @param[in] controller This parameter specifies the controller object 984 * with which this callback is associated. 985 * 986 * @return none 987 */ 988 void scif_cb_start_internal_io_task_create( 989 SCI_CONTROLLER_HANDLE_T controller 990 ); 991 992 993 /** 994 * @brief This callback method schedules a OS specific deferred task. 995 * 996 * @param[in] controller This parameter specifies the controller 997 * object with which this callback is associated. 998 * @param[in] start_internal_io_task_routine This parameter specifies the 999 * sci start_internal_io routine. 1000 * @param[in] context This parameter specifies a handle to a parameter 1001 * that will be passed into the "start_internal_io_task_routine" 1002 * when it is invoked. 1003 * 1004 * @return none 1005 */ 1006 void scif_cb_start_internal_io_task_schedule( 1007 SCI_CONTROLLER_HANDLE_T controller, 1008 FUNCPTR start_internal_io_task_routine, 1009 void * context 1010 ); 1011 1012 /** 1013 * @brief This method will be invoked to allocate memory dynamically. 1014 * 1015 * @param[in] controller This parameter represents the controller 1016 * object for which to allocate memory. 1017 * @param[out] mde This parameter represents the memory descriptor to 1018 * be filled in by the user that will reference the newly 1019 * allocated memory. 1020 * 1021 * @return none 1022 */ 1023 void scif_cb_controller_allocate_memory( 1024 SCI_CONTROLLER_HANDLE_T controller, 1025 SCI_PHYSICAL_MEMORY_DESCRIPTOR_T * mde 1026 ); 1027 1028 /** 1029 * @brief This method will be invoked to allocate memory dynamically. 1030 * 1031 * @param[in] controller This parameter represents the controller 1032 * object for which to allocate memory. 1033 * @param[out] mde This parameter represents the memory descriptor to 1034 * be filled in by the user that will reference the newly 1035 * allocated memory. 1036 * 1037 * @return none 1038 */ 1039 void scif_cb_controller_free_memory( 1040 SCI_CONTROLLER_HANDLE_T controller, 1041 SCI_PHYSICAL_MEMORY_DESCRIPTOR_T * mde 1042 ); 1043 1044 #ifdef __cplusplus 1045 } 1046 #endif // __cplusplus 1047 1048 #endif // _SCIF_USER_CALLBACK_H_ 1049 1050