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 _SCIC_USER_CALLBACK_H_ 55 #define _SCIC_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 Core user. 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 72 /** 73 * @brief This callback method asks the user to create a timer and provide 74 * a handle for this timer for use in further timer interactions. 75 * 76 * @warning The "timer_callback" method should be executed in a mutually 77 * exclusive manner from the controller completion handler 78 * handler (refer to scic_controller_get_handler_methods()). 79 * 80 * @param[in] controller This parameter specifies the controller with 81 * which this timer is to be associated. 82 * @param[in] timer_callback This parameter specifies the callback method 83 * to be invoked whenever the timer expires. 84 * @param[in] cookie This parameter specifies a piece of information that 85 * the user must retain. This cookie is to be supplied by the 86 * user anytime a timeout occurs for the created timer. 87 * 88 * @return This method returns a handle to a timer object created by the 89 * user. The handle will be utilized for all further interactions 90 * relating to this timer. 91 */ 92 void * scic_cb_timer_create( 93 SCI_CONTROLLER_HANDLE_T controller, 94 SCI_TIMER_CALLBACK_T timer_callback, 95 void * cookie 96 ); 97 98 /** 99 * @brief This callback method asks the user to destroy the supplied timer. 100 * 101 * @param[in] controller This parameter specifies the controller with 102 * which this timer is to associated. 103 * @param[in] timer This parameter specifies the timer to be destroyed. 104 * 105 * @return none 106 */ 107 void scic_cb_timer_destroy( 108 SCI_CONTROLLER_HANDLE_T controller, 109 void * timer 110 ); 111 112 /** 113 * @brief This callback method asks the user to start the supplied timer. 114 * 115 * @warning All timers in the system started by the SCI Core are one shot 116 * timers. Therefore, the SCI user should make sure that it 117 * removes the timer from it's list when a timer actually fires. 118 * Additionally, SCI Core user's should be able to handle 119 * calls from the SCI Core to stop a timer that may already 120 * be stopped. 121 * 122 * @param[in] controller This parameter specifies the controller with 123 * which this timer is to associated. 124 * @param[in] timer This parameter specifies the timer to be started. 125 * @param[in] milliseconds This parameter specifies the number of 126 * milliseconds for which to stall. The operating system driver 127 * is allowed to round this value up where necessary. 128 * 129 * @return none 130 */ 131 void scic_cb_timer_start( 132 SCI_CONTROLLER_HANDLE_T controller, 133 void * timer, 134 U32 milliseconds 135 ); 136 137 /** 138 * @brief This callback method asks the user to stop the supplied timer. 139 * 140 * @param[in] controller This parameter specifies the controller with 141 * which this timer is to associated. 142 * @param[in] timer This parameter specifies the timer to be stopped. 143 * 144 * @return none 145 */ 146 void scic_cb_timer_stop( 147 SCI_CONTROLLER_HANDLE_T controller, 148 void * timer 149 ); 150 151 /** 152 * @brief This method is called when the core requires the OS driver 153 * to stall execution. This method is utilized during initialization 154 * or non-performance paths only. 155 * 156 * @param[in] microseconds This parameter specifies the number of 157 * microseconds for which to stall. The operating system driver 158 * is allowed to round this value up where necessary. 159 * 160 * @return none. 161 */ 162 void scic_cb_stall_execution( 163 U32 microseconds 164 ); 165 166 /** 167 * @brief This user callback will inform the user that the controller has 168 * finished the start process. 169 * 170 * @param[in] controller This parameter specifies the controller that was 171 * started. 172 * @param[in] completion_status This parameter specifies the results of 173 * the start operation. SCI_SUCCESS indicates successful 174 * completion. 175 * 176 * @return none 177 */ 178 void scic_cb_controller_start_complete( 179 SCI_CONTROLLER_HANDLE_T controller, 180 SCI_STATUS completion_status 181 ); 182 183 /** 184 * @brief This user callback will inform the user that the controller has 185 * finished the stop process. 186 * 187 * @param[in] controller This parameter specifies the controller that was 188 * stopped. 189 * @param[in] completion_status This parameter specifies the results of 190 * the stop operation. SCI_SUCCESS indicates successful 191 * completion. 192 * 193 * @return none 194 */ 195 void scic_cb_controller_stop_complete( 196 SCI_CONTROLLER_HANDLE_T controller, 197 SCI_STATUS completion_status 198 ); 199 200 /** 201 * @brief This user callback will inform the user that an IO request has 202 * completed. 203 * 204 * @param[in] controller This parameter specifies the controller on 205 * which the IO is completing. 206 * @param[in] remote_device This parameter specifies the remote device on 207 * which this IO request is completing. 208 * @param[in] io_request This parameter specifies the IO request that has 209 * completed. 210 * @param[in] completion_status This parameter specifies the results of 211 * the IO request operation. SCI_SUCCESS indicates successful 212 * completion. 213 * 214 * @return none 215 */ 216 void scic_cb_io_request_complete( 217 SCI_CONTROLLER_HANDLE_T controller, 218 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 219 SCI_IO_REQUEST_HANDLE_T io_request, 220 SCI_IO_STATUS completion_status 221 ); 222 223 /** 224 * @brief This method simply returns the virtual address associated 225 * with the scsi_io and byte_offset supplied parameters. 226 * 227 * @note This callback is not utilized in the fast path. The expectation 228 * is that this method is utilized for items such as SCSI to ATA 229 * translation for commands like INQUIRY, READ CAPACITY, etc. 230 * 231 * @param[in] scic_user_io_request This parameter points to the user's 232 * IO request object. It is a cookie that allows the user to 233 * provide the necessary information for this callback. 234 * @param[in] byte_offset This parameter specifies the offset into the data 235 * buffers pointed to by the SGL. The byte offset starts at 0 236 * and continues until the last byte pointed to be the last SGL 237 * element. 238 * 239 * @return A virtual address pointer to the location specified by the 240 * parameters. 241 */ 242 U8 *scic_cb_io_request_get_virtual_address_from_sgl( 243 void * scic_user_io_request, 244 U32 byte_offset 245 ); 246 247 /** 248 * @brief This user callback will inform the user that a task management 249 * request completed. 250 * 251 * @param[in] controller This parameter specifies the controller on 252 * which the task management request is completing. 253 * @param[in] remote_device This parameter specifies the remote device on 254 * which this task management request is completing. 255 * @param[in] task_request This parameter specifies the task management 256 * request that has completed. 257 * @param[in] completion_status This parameter specifies the results of 258 * the IO request operation. SCI_SUCCESS indicates successful 259 * completion. 260 * 261 * @return none 262 */ 263 void scic_cb_task_request_complete( 264 SCI_CONTROLLER_HANDLE_T controller, 265 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 266 SCI_TASK_REQUEST_HANDLE_T task_request, 267 SCI_TASK_STATUS completion_status 268 ); 269 270 #ifndef SCI_GET_PHYSICAL_ADDRESS_OPTIMIZATION_ENABLED 271 /** 272 * @brief This callback method asks the user to provide the physical 273 * address for the supplied virtual address when building an 274 * io request object. 275 * 276 * @param[in] controller This parameter is the core controller object 277 * handle. 278 * @param[in] io_request This parameter is the io request object handle 279 * for which the physical address is being requested. 280 * @param[in] virtual_address This parameter is the virtual address which 281 * is to be returned as a physical address. 282 * @param[out] physical_address The physical address for the supplied virtual 283 * address. 284 * 285 * @return None. 286 */ 287 void scic_cb_io_request_get_physical_address( 288 SCI_CONTROLLER_HANDLE_T controller, 289 SCI_IO_REQUEST_HANDLE_T io_request, 290 void * virtual_address, 291 SCI_PHYSICAL_ADDRESS * physical_address 292 ); 293 #endif // SCI_GET_PHYSICAL_ADDRESS_OPTIMIZATION_ENABLED 294 295 /** 296 * @brief This callback method asks the user to provide the number of 297 * bytes to be transferred as part of this request. 298 * 299 * @param[in] scic_user_io_request This parameter points to the user's 300 * IO request object. It is a cookie that allows the user to 301 * provide the necessary information for this callback. 302 * 303 * @return This method returns the number of payload data bytes to be 304 * transferred for this IO request. 305 */ 306 U32 scic_cb_io_request_get_transfer_length( 307 void * scic_user_io_request 308 ); 309 310 /** 311 * @brief This callback method asks the user to provide the data direction 312 * for this request. 313 * 314 * @param[in] scic_user_io_request This parameter points to the user's 315 * IO request object. It is a cookie that allows the user to 316 * provide the necessary information for this callback. 317 * 318 * @return This method returns the value of SCI_IO_REQUEST_DATA_OUT or 319 * SCI_IO_REQUEST_DATA_IN, or SCI_IO_REQUEST_NO_DATA. 320 */ 321 SCI_IO_REQUEST_DATA_DIRECTION scic_cb_io_request_get_data_direction( 322 void * scic_user_io_request 323 ); 324 325 #ifdef ENABLE_OSSL_COPY_BUFFER 326 /** 327 * @brief This method is presently utilized in the PIO path, 328 * copies from UF buffer to the SGL buffer. This method 329 * can be served for other OS related copies. 330 * 331 * @param[in] scic_user_io_request. This parameter points to the user's 332 * IO request object. It is a cookie that allows the user to 333 * provide the necessary information for this callback. 334 * @param[in] source addr. Address of UF buffer. 335 * @param[in] offset. This parameter specifies the offset into the data 336 * buffers pointed to by the SGL. The byte offset starts at 0 337 * and continues until the last byte pointed to be the last SGL 338 * element. 339 * @param[in] length. data length 340 * 341 * @return None 342 */ 343 void scic_cb_io_request_copy_buffer( 344 void * scic_user_io_request, 345 U8 *source_addr, 346 U32 offset, 347 U32 length 348 ); 349 #endif 350 351 #ifndef SCI_SGL_OPTIMIZATION_ENABLED 352 /** 353 * @brief This callback method asks the user to provide the address 354 * to where the next Scatter-Gather Element is located. 355 * 356 * Details regarding usage: 357 * - Regarding the first SGE: the user should initialize an index, 358 * or a pointer, prior to construction of the request that will 359 * reference the very first scatter-gather element. This is 360 * important since this method is called for every scatter-gather 361 * element, including the first element. 362 * - Regarding the last SGE: the user should return NULL from this 363 * method when this method is called and the SGL has exhausted 364 * all elements. 365 * 366 * @param[in] scic_user_io_request This parameter points to the user's 367 * IO request object. It is a cookie that allows the user to 368 * provide the necessary information for this callback. 369 * @param[in] current_sge_address This parameter specifies the address for 370 * the current SGE (i.e. the one that has just processed). 371 * @param[out] next_sge An address specifying the location for the next 372 * scatter gather element to be processed. 373 * 374 * @return None 375 */ 376 void scic_cb_io_request_get_next_sge( 377 void * scic_user_io_request, 378 void * current_sge_address, 379 void ** next_sge 380 ); 381 #endif // SCI_SGL_OPTIMIZATION_ENABLED 382 383 /** 384 * @brief This callback method asks the user to provide the contents of the 385 * "address" field in the Scatter-Gather Element. 386 * 387 * @param[in] scic_user_io_request This parameter points to the user's 388 * IO request object. It is a cookie that allows the user to 389 * provide the necessary information for this callback. 390 * @param[in] sge_address This parameter specifies the address for the 391 * SGE from which to retrieve the address field. 392 * 393 * @return A physical address specifying the contents of the SGE's address 394 * field. 395 */ 396 SCI_PHYSICAL_ADDRESS scic_cb_sge_get_address_field( 397 void * scic_user_io_request, 398 void * sge_address 399 ); 400 401 /** 402 * @brief This callback method asks the user to provide the contents of the 403 * "length" field in the Scatter-Gather Element. 404 * 405 * @param[in] scic_user_io_request This parameter points to the user's 406 * IO request object. It is a cookie that allows the user to 407 * provide the necessary information for this callback. 408 * @param[in] sge_address This parameter specifies the address for the 409 * SGE from which to retrieve the address field. 410 * 411 * @return This method returns the length field specified inside the SGE 412 * referenced by the sge_address parameter. 413 */ 414 U32 scic_cb_sge_get_length_field( 415 void * scic_user_io_request, 416 void * sge_address 417 ); 418 419 /** 420 * @brief This callback method asks the user to provide the address for 421 * the command descriptor block (CDB) associated with this IO request. 422 * 423 * @param[in] scic_user_io_request This parameter points to the user's 424 * IO request object. It is a cookie that allows the user to 425 * provide the necessary information for this callback. 426 * 427 * @return This method returns the virtual address of the CDB. 428 */ 429 void * scic_cb_ssp_io_request_get_cdb_address( 430 void * scic_user_io_request 431 ); 432 433 /** 434 * @brief This callback method asks the user to provide the length of 435 * the command descriptor block (CDB) associated with this IO request. 436 * 437 * @param[in] scic_user_io_request This parameter points to the user's 438 * IO request object. It is a cookie that allows the user to 439 * provide the necessary information for this callback. 440 * 441 * @return This method returns the length of the CDB. 442 */ 443 U32 scic_cb_ssp_io_request_get_cdb_length( 444 void * scic_user_io_request 445 ); 446 447 /** 448 * @brief This callback method asks the user to provide the Logical Unit (LUN) 449 * associated with this IO request. 450 * 451 * @note The contents of the value returned from this callback are defined 452 * by the protocol standard (e.g. T10 SAS specification). Please 453 * refer to the transport command information unit description 454 * in the associated standard. 455 * 456 * @param[in] scic_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 * 460 * @return This method returns the LUN associated with this request. 461 * @todo This should be U64? 462 */ 463 U32 scic_cb_ssp_io_request_get_lun( 464 void * scic_user_io_request 465 ); 466 467 /** 468 * @brief This callback method asks the user to provide the task attribute 469 * associated with this IO request. 470 * 471 * @note The contents of the value returned from this callback are defined 472 * by the protocol standard (e.g. T10 SAS specification). Please 473 * refer to the transport command information unit description 474 * in the associated standard. 475 * 476 * @param[in] scic_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 task attribute associated with this 481 * IO request. 482 */ 483 U32 scic_cb_ssp_io_request_get_task_attribute( 484 void * scic_user_io_request 485 ); 486 487 /** 488 * @brief This callback method asks the user to provide the command priority 489 * associated with this IO request. 490 * 491 * @note The contents of the value returned from this callback are defined 492 * by the protocol standard (e.g. T10 SAS specification). Please 493 * refer to the transport command information unit description 494 * in the associated standard. 495 * 496 * @param[in] scic_user_io_request This parameter points to the user's 497 * IO request object. It is a cookie that allows the user to 498 * provide the necessary information for this callback. 499 * 500 * @return This method returns the command priority associated with this 501 * IO request. 502 */ 503 U32 scic_cb_ssp_io_request_get_command_priority( 504 void * scic_user_io_request 505 ); 506 507 /** 508 * @brief This callback method asks the user if the received RX frame data is 509 * to be copied to the SGL or should be stored by the SCI core to be 510 * retrieved later with the scic_io_request_get_rx_frame(). 511 * 512 * @param[in] scic_user_io_request This parameter points to the user's IO 513 * request object. It is a cookie that allows the user to provide the 514 * necessary information for this callback. 515 * 516 * @return This method returns TRUE if the SCI core should copy the received 517 * frame data to the SGL location or FALSE if the SCI user wants to 518 * retrieve the frame data at a later time. 519 */ 520 BOOL scic_cb_io_request_do_copy_rx_frames( 521 void * scic_user_io_request 522 ); 523 524 /** 525 * @brief This callback method asks the user to return the SAT protocol 526 * definition for this IO request. This method is only called by the 527 * SCI core if the request type constructed is SATA. 528 * 529 * @param[in] scic_user_io_request This parameter points to the user's IO 530 * request object. It is a cookie that allows the user to provide the 531 * necessary information for this callback. 532 * 533 * @return This method returns one of the sat.h defined protocols for the 534 * given io request. 535 */ 536 U8 scic_cb_request_get_sat_protocol( 537 void * scic_user_io_request 538 ); 539 540 /** 541 * @brief This callback method asks the user to indicate if the IO is initially 542 * constructed or is reconstructed using the recycled memory. 543 * 544 * @param[in] scic_user_io_request This parameter points to the user's IO 545 * request object. It is a cookie that allows the user to provide the 546 * necessary information for this callback. 547 * 548 * @return This method returns TRUE if the request is initial constructed. 549 * This method returns FALSE if the request is constructed using recycled 550 * memory. For many scic user, this method mostly always returns TRUE. 551 */ 552 BOOL scic_cb_request_is_initial_construction( 553 void * scic_user_io_request 554 ); 555 556 /** 557 * @brief This method returns the Logical Unit to be utilized for this 558 * task management request. 559 * 560 * @note The contents of the value returned from this callback are defined 561 * by the protocol standard (e.g. T10 SAS specification). Please 562 * refer to the transport task information unit description 563 * in the associated standard. 564 * 565 * @param[in] scic_user_task_request This parameter points to the user's 566 * task request object. It is a cookie that allows the user to 567 * provide the necessary information for this callback. 568 * 569 * @return This method returns the LUN associated with this request. 570 * @todo This should be U64? 571 */ 572 U32 scic_cb_ssp_task_request_get_lun( 573 void * scic_user_task_request 574 ); 575 576 /** 577 * @brief This method returns the task management function to be utilized 578 * for this task request. 579 * 580 * @note The contents of the value returned from this callback are defined 581 * by the protocol standard (e.g. T10 SAS specification). Please 582 * refer to the transport task information unit description 583 * in the associated standard. 584 * 585 * @param[in] scic_user_task_request This parameter points to the user's 586 * task request object. It is a cookie that allows the user to 587 * provide the necessary information for this callback. 588 * 589 * @return This method returns an unsigned byte representing the task 590 * management function to be performed. 591 */ 592 U8 scic_cb_ssp_task_request_get_function( 593 void * scic_user_task_request 594 ); 595 596 /** 597 * @brief This method returns the task management IO tag to be managed. 598 * Depending upon the task management function the value returned 599 * from this method may be ignored. 600 * 601 * @param[in] scic_user_task_request This parameter points to the user's 602 * task request object. It is a cookie that allows the user to 603 * provide the necessary information for this callback. 604 * 605 * @return This method returns an unsigned 16-bit word depicting the IO 606 * tag to be managed. 607 */ 608 U16 scic_cb_ssp_task_request_get_io_tag_to_manage( 609 void * scic_user_task_request 610 ); 611 612 /** 613 * @brief This callback method asks the user to provide the virtual 614 * address of the response data buffer for the supplied IO request. 615 * 616 * @param[in] scic_user_task_request This parameter points to the user's 617 * task request object. It is a cookie that allows the user to 618 * provide the necessary information for this callback. 619 * 620 * @return This method returns the virtual address for the response data buffer 621 * associated with this IO request. 622 */ 623 void * scic_cb_ssp_task_request_get_response_data_address( 624 void * scic_user_task_request 625 ); 626 627 /** 628 * @brief This callback method asks the user to provide the length of the 629 * response data buffer for the supplied IO request. 630 * 631 * @param[in] scic_user_task_request This parameter points to the user's 632 * task request object. It is a cookie that allows the user to 633 * provide the necessary information for this callback. 634 * 635 * @return This method returns the length of the response buffer data 636 * associated with this IO request. 637 */ 638 U32 scic_cb_ssp_task_request_get_response_data_length( 639 void * scic_user_task_request 640 ); 641 642 /** 643 * @brief In this method the user is expected to log the supplied 644 * error information. The user must be capable of handling variable 645 * length argument lists and should consider prepending the fact 646 * that this is an error from the core. 647 * 648 * @param[in] logger_object This parameter specifies the logger object 649 * associated with this message. 650 * @param[in] log_object_mask This parameter specifies the log objects 651 * for which this message is being generated. 652 * @param[in] log_message This parameter specifies the message to be logged. 653 * 654 * @return none 655 */ 656 void scic_cb_logger_log_error( 657 SCI_LOGGER_HANDLE_T logger_object, 658 U32 log_object_mask, 659 char * log_message, 660 ... 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 core. 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 scic_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 /** 687 * @brief In this method the user is expected to log the supplied debug 688 * information. The user must be capable of handling variable 689 * length argument lists and should consider prepending the fact 690 * that this is a debug message from the core. 691 * 692 * @param[in] logger_object This parameter specifies the logger object 693 * associated with this message. 694 * @param[in] log_object_mask This parameter specifies the log objects 695 * for which this message is being generated. 696 * @param[in] log_message This parameter specifies the message to be logged. 697 * 698 * @return none 699 */ 700 void scic_cb_logger_log_info( 701 SCI_LOGGER_HANDLE_T logger_object, 702 U32 log_object_mask, 703 char * log_message, 704 ... 705 ); 706 707 708 /** 709 * @brief In this method the user is expected to log the supplied function 710 * trace information. The user must be capable of handling variable 711 * length argument lists and should consider prepending the fact 712 * that this is a function trace (i.e. entry/exit) message from the 713 * core. 714 * 715 * @param[in] logger_object This parameter specifies the logger object 716 * associated with this message. 717 * @param[in] log_object_mask This parameter specifies the log objects 718 * for which this message is being generated. 719 * @param[in] log_message This parameter specifies the message to be logged. 720 * 721 * @return none 722 */ 723 void scic_cb_logger_log_trace( 724 SCI_LOGGER_HANDLE_T logger_object, 725 U32 log_object_mask, 726 char * log_message, 727 ... 728 ); 729 730 731 /** 732 * @brief In this method the user is expected to log the supplied state 733 * transition information. The user must be capable of handling 734 * variable length argument lists and should consider prepending the 735 * fact that this is a warning from the core. 736 * 737 * @param[in] logger_object This parameter specifies the logger object 738 * associated with this message. 739 * @param[in] log_object_mask This parameter specifies the log objects 740 * for which this message is being generated. 741 * @param[in] log_message This parameter specifies the message to be logged. 742 * 743 * @return none 744 */ 745 void scic_cb_logger_log_states( 746 SCI_LOGGER_HANDLE_T logger_object, 747 U32 log_object_mask, 748 char * log_message, 749 ... 750 ); 751 752 753 /** 754 * @brief In this method the user must return the base address register (BAR) 755 * value for the supplied base address register number. 756 * 757 * @param[in] controller The controller for which to retrieve the bar number. 758 * @param[in] bar_number This parameter depicts the BAR index/number to be read. 759 * 760 * @return Return a pointer value indicating the contents of the BAR. 761 * @retval NULL indicates an invalid BAR index/number was specified. 762 * @retval All other values indicate a valid VIRTUAL address from the BAR. 763 */ 764 void * scic_cb_pci_get_bar( 765 SCI_CONTROLLER_HANDLE_T controller, 766 U16 bar_number 767 ); 768 769 /** 770 * @brief In this method the user must read from PCI memory via access. 771 * This method is used for access to memory space and IO space. 772 * 773 * @param[in] controller The controller for which to read a DWORD. 774 * @param[in] address This parameter depicts the address from 775 * which to read. 776 * 777 * @return The value being returned from the PCI memory location. 778 * 779 * @todo This PCI memory access calls likely need to be optimized into macro? 780 */ 781 U32 scic_cb_pci_read_dword( 782 SCI_CONTROLLER_HANDLE_T controller, 783 void * address 784 ); 785 786 /** 787 * @brief In this method the user must write to PCI memory via access. 788 * This method is used for access to memory space and IO space. 789 * 790 * @param[in] controller The controller for which to read a DWORD. 791 * @param[in] address This parameter depicts the address into 792 * which to write. 793 * @param[out] write_value This parameter depicts the value being written 794 * into the PCI memory location. 795 * 796 * @todo This PCI memory access calls likely need to be optimized into macro? 797 */ 798 void scic_cb_pci_write_dword( 799 SCI_CONTROLLER_HANDLE_T controller, 800 void * address, 801 U32 write_value 802 ); 803 804 /** 805 * @brief This method informs the user when a stop operation on the port 806 * has completed. 807 * 808 * @param[in] controller This parameter represents the controller which 809 * contains the port. 810 * @param[in] port This parameter specifies the SCI port object for which 811 * the callback is being invoked. 812 * @param[in] completion_status This parameter specifies the status for 813 * the operation being completed. 814 * 815 * @return none 816 */ 817 void scic_cb_port_stop_complete( 818 SCI_CONTROLLER_HANDLE_T controller, 819 SCI_PORT_HANDLE_T port, 820 SCI_STATUS completion_status 821 ); 822 823 /** 824 * @brief This method informs the user when a hard reset on the port 825 * has completed. This hard reset could have been initiated by the 826 * user or by the remote port. 827 * 828 * @param[in] controller This parameter represents the controller which 829 * contains the port. 830 * @param[in] port This parameter specifies the SCI port object for which 831 * the callback is being invoked. 832 * @param[in] completion_status This parameter specifies the status for 833 * the operation being completed. 834 * 835 * @return none 836 */ 837 void scic_cb_port_hard_reset_complete( 838 SCI_CONTROLLER_HANDLE_T controller, 839 SCI_PORT_HANDLE_T port, 840 SCI_STATUS completion_status 841 ); 842 843 /** 844 * @brief This method informs the user that the port is now in a ready 845 * state and can be utilized to issue IOs. 846 * 847 * @param[in] controller This parameter represents the controller which 848 * contains the port. 849 * @param[in] port This parameter specifies the SCI port object for which 850 * the callback is being invoked. 851 * 852 * @return none 853 */ 854 void scic_cb_port_ready( 855 SCI_CONTROLLER_HANDLE_T controller, 856 SCI_PORT_HANDLE_T port 857 ); 858 859 /** 860 * @brief This method informs the user that the port is now not in a ready 861 * (i.e. busy) state and can't be utilized to issue IOs. 862 * 863 * @param[in] controller This parameter represents the controller which 864 * contains the port. 865 * @param[in] port This parameter specifies the SCI port object for which 866 * the callback is being invoked. 867 * @param[in] reason_code This parameter specifies the reason for the port 868 * not ready callback. 869 * 870 * @return none 871 */ 872 void scic_cb_port_not_ready( 873 SCI_CONTROLLER_HANDLE_T controller, 874 SCI_PORT_HANDLE_T port, 875 U32 reason_code 876 ); 877 878 /** 879 * @brief This method informs the SCI Core user that a phy/link became 880 * ready, but the phy is not allowed in the port. In some 881 * situations the underlying hardware only allows for certain phy 882 * to port mappings. If these mappings are violated, then this 883 * API is invoked. 884 * 885 * @param[in] controller This parameter represents the controller which 886 * contains the port. 887 * @param[in] port This parameter specifies the SCI port object for which 888 * the callback is being invoked. 889 * @param[in] phy This parameter specifies the phy that came ready, but the 890 * phy can't be a valid member of the port. 891 * 892 * @return none 893 */ 894 void scic_cb_port_invalid_link_up( 895 SCI_CONTROLLER_HANDLE_T controller, 896 SCI_PORT_HANDLE_T port, 897 SCI_PHY_HANDLE_T phy 898 ); 899 900 /** 901 * @brief This callback method informs the user that a broadcast change 902 * primitive was received. 903 * 904 * @param[in] controller This parameter represents the controller which 905 * contains the port. 906 * @param[in] port This parameter specifies the SCI port object for which 907 * the callback is being invoked. For instances where the phy 908 * on which the primitive was received is not part of a port, this 909 * parameter will be SCI_INVALID_HANDLE_T. 910 * @param[in] phy This parameter specifies the phy on which the primitive 911 * was received. 912 * 913 * @return none 914 */ 915 void scic_cb_port_bc_change_primitive_recieved( 916 SCI_CONTROLLER_HANDLE_T controller, 917 SCI_PORT_HANDLE_T port, 918 SCI_PHY_HANDLE_T phy 919 ); 920 921 /** 922 * @brief This callback method informs the user that a broadcast SES 923 * primitive was received. 924 * 925 * @param[in] controller This parameter represents the controller which 926 * contains the port. 927 * @param[in] port This parameter specifies the SCI port object for which 928 * the callback is being invoked. For instances where the phy 929 * on which the primitive was received is not part of a port, this 930 * parameter will be SCI_INVALID_HANDLE_T. 931 * @param[in] phy This parameter specifies the phy on which the primitive 932 * was received. 933 * 934 * @return none 935 */ 936 void scic_cb_port_bc_ses_primitive_recieved( 937 SCI_CONTROLLER_HANDLE_T controller, 938 SCI_PORT_HANDLE_T port, 939 SCI_PHY_HANDLE_T phy 940 ); 941 942 /** 943 * @brief This callback method informs the user that a broadcast EXPANDER 944 * primitive was received. 945 * 946 * @param[in] controller This parameter represents the controller which 947 * contains the port. 948 * @param[in] port This parameter specifies the SCI port object for which 949 * the callback is being invoked. For instances where the phy 950 * on which the primitive was received is not part of a port, this 951 * parameter will be SCI_INVALID_HANDLE_T. 952 * @param[in] phy This parameter specifies the phy on which the primitive 953 * was received. 954 * 955 * @return none 956 */ 957 void scic_cb_port_bc_expander_primitive_recieved( 958 SCI_CONTROLLER_HANDLE_T controller, 959 SCI_PORT_HANDLE_T port, 960 SCI_PHY_HANDLE_T phy 961 ); 962 963 /** 964 * @brief This callback method informs the user that a broadcast ASYNCHRONOUS 965 * EVENT (AEN) primitive was received. 966 * 967 * @param[in] controller This parameter represents the controller which 968 * contains the port. 969 * @param[in] port This parameter specifies the SCI port object for which 970 * the callback is being invoked. For instances where the phy 971 * on which the primitive was received is not part of a port, this 972 * parameter will be SCI_INVALID_HANDLE_T. 973 * @param[in] phy This parameter specifies the phy on which the primitive 974 * was received. 975 * 976 * @return none 977 */ 978 void scic_cb_port_bc_aen_primitive_recieved( 979 SCI_CONTROLLER_HANDLE_T controller, 980 SCI_PORT_HANDLE_T port, 981 SCI_PHY_HANDLE_T phy 982 ); 983 984 /** 985 * @brief This callback method informs the user that a phy has become 986 * operational and is capable of communicating with the remote end 987 * point. 988 * 989 * @param[in] controller This parameter represents the controller 990 * associated with the phy. 991 * @param[in] port This parameter specifies the port object for which the 992 * user callback is being invoked. There may be conditions where 993 * this parameter can be SCI_INVALID_HANDLE 994 * @param[in] phy This parameter specifies the phy object for which the 995 * user callback is being invoked. 996 * 997 * @return none 998 */ 999 void scic_cb_port_link_up( 1000 SCI_CONTROLLER_HANDLE_T controller, 1001 SCI_PORT_HANDLE_T port, 1002 SCI_PHY_HANDLE_T phy 1003 ); 1004 1005 /** 1006 * @brief This callback method informs the user that a phy is no longer 1007 * operational and is not capable of communicating with the remote end 1008 * point. 1009 * 1010 * @param[in] controller This parameter represents the controller 1011 * associated with the phy. 1012 * @param[in] port This parameter specifies the port object for which the 1013 * user callback is being invoked. There may be conditions where 1014 * this parameter can be SCI_INVALID_HANDLE 1015 * @param[in] phy This parameter specifies the phy object for which the 1016 * user callback is being invoked. 1017 * 1018 * @return none 1019 */ 1020 void scic_cb_port_link_down( 1021 SCI_CONTROLLER_HANDLE_T controller, 1022 SCI_PORT_HANDLE_T port, 1023 SCI_PHY_HANDLE_T phy 1024 ); 1025 1026 /** 1027 * @brief This user callback method will inform the user that a start 1028 * operation has completed. 1029 * 1030 * @param[in] controller This parameter specifies the core controller 1031 * associated with the completion callback. 1032 * @param[in] remote_device This parameter specifies the remote device 1033 * associated with the completion callback. 1034 * @param[in] completion_status This parameter specifies the completion 1035 * status for the operation. 1036 * 1037 * @return none 1038 */ 1039 void scic_cb_remote_device_start_complete( 1040 SCI_CONTROLLER_HANDLE_T controller, 1041 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 1042 SCI_STATUS completion_status 1043 ); 1044 1045 /** 1046 * @brief This user callback method will inform the user that a stop 1047 * operation has completed. 1048 * 1049 * @param[in] controller This parameter specifies the core controller 1050 * associated with the completion callback. 1051 * @param[in] remote_device This parameter specifies the remote device 1052 * associated with the completion callback. 1053 * @param[in] completion_status This parameter specifies the completion 1054 * status for the operation. 1055 * 1056 * @return none 1057 */ 1058 void scic_cb_remote_device_stop_complete( 1059 SCI_CONTROLLER_HANDLE_T controller, 1060 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 1061 SCI_STATUS completion_status 1062 ); 1063 1064 /** 1065 * @brief This user callback method will inform the user that a remote 1066 * device is now capable of handling IO requests. 1067 * 1068 * @param[in] controller This parameter specifies the core controller 1069 * associated with the completion callback. 1070 * @param[in] remote_device This parameter specifies the remote device 1071 * associated with the callback. 1072 * 1073 * @return none 1074 */ 1075 void scic_cb_remote_device_ready( 1076 SCI_CONTROLLER_HANDLE_T controller, 1077 SCI_REMOTE_DEVICE_HANDLE_T remote_device 1078 ); 1079 1080 /** 1081 * @brief This user callback method will inform the user that a remote 1082 * device is no longer capable of handling IO requests (until a 1083 * ready callback is invoked). 1084 * 1085 * @param[in] controller This parameter specifies the core controller 1086 * associated with the completion callback. 1087 * @param[in] remote_device This parameter specifies the remote device 1088 * associated with the callback. 1089 * @param[in] reason_code This paramete specifies the reason the remote 1090 * device is not ready. 1091 * 1092 * @return none 1093 */ 1094 void scic_cb_remote_device_not_ready( 1095 SCI_CONTROLLER_HANDLE_T controller, 1096 SCI_REMOTE_DEVICE_HANDLE_T remote_device, 1097 U32 reason_code 1098 ); 1099 1100 1101 /** 1102 * @brief This user callback method will inform the user that this controller 1103 * is having unexpected error. The user can choose to reset the controller. 1104 * @param[in] controller The controller that is failed at the moment. 1105 * 1106 * @return none 1107 */ 1108 void scic_cb_controller_error( 1109 SCI_CONTROLLER_HANDLE_T controller, 1110 SCI_CONTROLLER_ERROR error 1111 ); 1112 1113 1114 #if !defined(DISABLE_ATAPI) 1115 /** 1116 * @brief This user callback gets from stp packet io's user request 1117 * the CDB address. 1118 * @param[in] scic_user_io_request 1119 * 1120 * @return The cdb address. 1121 */ 1122 void * scic_cb_stp_packet_io_request_get_cdb_address( 1123 void * scic_user_io_request 1124 ); 1125 1126 /** 1127 * @brief This user callback gets from stp packet io's user request 1128 * the CDB length. 1129 * @param[in] scic_user_io_request 1130 * 1131 * @return The cdb length. 1132 */ 1133 U32 scic_cb_stp_packet_io_request_get_cdb_length( 1134 void * scic_user_io_request 1135 ); 1136 #else //!defined(DISABLE_ATAPI) 1137 #define scic_cb_stp_packet_io_request_get_cdb_address(scic_user_io_request) NULL 1138 #define scic_cb_stp_packet_io_request_get_cdb_length(scic_user_io_request) 0 1139 #endif //!defined(DISABLE_ATAPI) 1140 1141 #ifdef __cplusplus 1142 } 1143 #endif // __cplusplus 1144 1145 #endif // _SCIC_USER_CALLBACK_H_ 1146 1147