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