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