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 _SATI_CALLBACKS_H_ 55 #define _SATI_CALLBACKS_H_ 56 57 /** 58 * @file 59 * @brief This file contains the default callback bindings for SATI. These 60 * must be overridden by the SATI user to ensure successful operation. 61 */ 62 63 #include <dev/isci/scil/sati_types.h> 64 #include <dev/isci/scil/intel_sas.h> 65 66 #ifdef SATI_DEFAULT_DECLARATION 67 68 /** 69 * @brief This callback method asks the user to provide the address for 70 * the command descriptor block (CDB) associated with this IO request. 71 * 72 * @param[in] scsi_io This parameter points to the user's IO request object 73 * It is a cookie that allows the user to provide the necessary 74 * information for this callback. 75 * 76 * @return This method returns the virtual address of the CDB. 77 */ 78 void * sati_cb_get_cdb_address( 79 void * scsi_io 80 ); 81 82 /** 83 * @brief This callback method asks the user to provide the length of 84 * the command descriptor block (CDB) associated with this IO request. 85 * 86 * @param[in] scsi_io This parameter points to the user's IO request object. 87 * It is a cookie that allows the user to provide the necessary 88 * information for this callback. 89 * 90 * @return This method returns the length of the CDB. 91 */ 92 U32 sati_cb_get_cdb_length( 93 void * scsi_io 94 ); 95 96 /** 97 * @brief This callback method asks the user to provide the data transfer 98 * direction of this IO request. 99 * 100 * @param[in] scsi_io This parameter points to the user's IO request object. 101 * It is a cookie that allows the user to provide the necessary 102 * information for this callback. 103 * @param[in] io_direction to return 104 * @return This method returns the length of the CDB. 105 */ 106 void sati_cb_get_data_direction( 107 void * scsi_io, 108 U8 * io_direction 109 ); 110 111 /** 112 * @brief This callback method sets a value into the data buffer associated 113 * with the supplied user SCSI IO request at the supplied byte offset. 114 * 115 * @note SATI does not manage the user scatter-gather-list. As a result, 116 * the user must ensure that data is written according to the SGL. 117 * 118 * @param[in] scsi_io This parameter specifies the user's SCSI IO request 119 * for which to set the data buffer byte. 120 * @param[in] byte_offset This parameter specifies the offset into the 121 * data buffer at which to set the value. 122 * @param[in] value This parameter specifies the new value to be set into 123 * the data buffer. 124 * 125 * @return none 126 */ 127 void sati_cb_set_data_byte( 128 void * scsi_io, 129 U32 byte_offset, 130 U8 value 131 ); 132 133 /** 134 * @brief This callback method gets a value from the data buffer associated 135 * with the supplied user SCSI IO request at the supplied byte offset. 136 * 137 * @note SATI does not manage the user scatter-gather-list. As a result, 138 * the user must ensure that data is written according to the SGL. 139 * 140 * @param[in] scsi_io This parameter specifies the user's SCSI IO request 141 * for which to get the data buffer byte. 142 * @param[in] byte_offset This parameter specifies the offset into the 143 * data buffer at which to get the value. 144 * @param[in] value This parameter specifies the new value to be get into 145 * the data buffer. 146 * 147 * @return none 148 */ 149 void sati_cb_get_data_byte( 150 void * scsi_io, 151 U32 byte_offset, 152 U8 * value 153 ); 154 155 /** 156 * @brief This callback method gets the task type for the SCSI task 157 * request. 158 * 159 * @param[in] scsi_task This parameter specifies the user's SCSI Task request. 160 * It is a cookie that allows the user to provide the necessary 161 * information for this callback. 162 * 163 * @return This method returns one of the enumeration values for 164 * SCSI_TASK_MGMT_REQUEST_CODES 165 */ 166 U8 sati_cb_get_task_function( 167 void * scsi_task 168 ); 169 170 #ifdef SATI_TRANSPORT_SUPPORTS_SAS 171 /** 172 * @brief This callback method retrieves the address of the user's SSP 173 * response IU buffer. 174 * 175 * @param[in] scsi_io This parameter specifies the user's SCSI IO request 176 * for which to retrieve the location of the response buffer to 177 * be written. 178 * 179 * @return This method returns the address of the response data buffer. 180 */ 181 void * sati_cb_get_response_iu_address( 182 void * scsi_io 183 ); 184 185 #else // SATI_TRANSPORT_SUPPORTS_SAS 186 187 /** 188 * @brief This callback method retrieves the address of the user's sense data 189 * buffer. 190 * 191 * @param[in] scsi_io This parameter specifies the user's SCSI IO request 192 * for which to retrieve the location of the sense buffer to 193 * be written. 194 * 195 * @return This method returns the address of the sense data buffer. 196 */ 197 U8* sati_cb_get_sense_data_address( 198 void * scsi_io 199 ); 200 201 /** 202 * @brief This callback method retrieves the length of the user's sense data 203 * buffer. 204 * 205 * @param[in] scsi_io This parameter specifies the user's SCSI IO request 206 * for which to retrieve the location of the sense buffer to 207 * be written. 208 * 209 * @return This method returns the length of the sense data buffer. 210 */ 211 U32 sati_cb_get_sense_data_length( 212 void * scsi_io 213 ); 214 215 /** 216 * @brief This callback method sets the SCSI status to be associated with 217 * the supplied user's SCSI IO request. 218 * 219 * @param[in] scsi_io This parameter specifies the user's SCSI IO request 220 * for which to set the SCSI status. 221 * @param[in] status This parameter specifies the SCSI status to be 222 * associated with the supplied user's SCSI IO request. 223 * 224 * @return none 225 */ 226 void sati_cb_set_scsi_status( 227 void * scsi_io, 228 U8 status 229 ); 230 231 #endif // SATI_TRANSPORT_SUPPORTS_SAS 232 233 /** 234 * @brief This method retrieves the ATA task file (register FIS) relating to 235 * the host to device command values. 236 * 237 * @param[in] ata_io This parameter specifies the user's ATA IO request 238 * from which to retrieve the h2d register FIS address. 239 * 240 * @return This method returns the address for the host to device register 241 * FIS. 242 */ 243 U8 * sati_cb_get_h2d_register_fis_address( 244 void * ata_io 245 ); 246 247 /** 248 * @brief This method retrieves the ATA task file (register FIS) relating to 249 * the device to host response values. 250 * 251 * @param[in] ata_io This parameter specifies the user's ATA IO request 252 * from which to retrieve the d2h register FIS address. 253 * 254 * @return This method returns the address for the device to host register 255 * FIS. 256 */ 257 U8 * sati_cb_get_d2h_register_fis_address( 258 void * ata_io 259 ); 260 261 /** 262 * @brief This method retrieves the address where the ATA data received 263 * from the device is stored. 264 * 265 * @param[in] ata_io This parameter specifies the user's ATA IO request 266 * from which to retrieve the received data address. 267 * 268 * @return This method returns the address for the data received from 269 * the remote device. 270 */ 271 void * sati_cb_get_ata_data_address( 272 void * ata_io 273 ); 274 275 /** 276 * @brief This method allocates a DMA buffer 277 * that can be utilized for small (<=4K) DMA sequences. 278 * This is utilized to translate SCSI UNMAP requests. 279 * 280 * @param[in] scsi_io This parameter specifies the user's SCSI IO request 281 * for which to set the SCSI status. 282 * @param[in] length in bytes of the buffer to be allocated 283 * @param[in] virtual address of the allocated DMA buffer. 284 * @param[in] low 32 bits of the physical DMA address. 285 * @param[in] high 32 bits of the physical DMA address. 286 * 287 * @return This method returns the virtual and physical address 288 * of the allocated DMA buffer. 289 */ 290 void sati_cb_allocate_dma_buffer( 291 void * scsi_io, 292 U32 length, 293 void ** virt_address, 294 U32 * phys_address_low, 295 U32 * phys_address_high 296 ); 297 298 /** 299 * @brief This method frees a previously allocated DMA buffer 300 * 301 * @param[in] scsi_io This parameter specifies the user's SCSI IO request 302 * for which to set the SCSI status. 303 * @param[in] address - write buffer address being freed 304 * 305 * @return This method returns the address for the data received from 306 * the remote device. 307 */ 308 void sati_cb_free_dma_buffer( 309 void * scsi_io, 310 void * virt_address 311 ); 312 313 /** 314 * @brief This method retrieves a pointer to the next scatter gather 315 * list element. 316 * 317 * @param[in] scsi_io This parameter specifies the user's SCSI IO request 318 * from which to retrieve the scatter gather list. 319 * @param[in] ata_io This parameter specifies the user's ATA IO request 320 * from which to retrieve the scatter gather list. 321 * @param[in] current_sge This parameter specifies the current SG element 322 * being pointed to. If retrieving the first element, 323 * then this value should be NULL. 324 * @param[in] next_sge This parameter is the returned SGL element 325 * based on current_sge. 326 * 327 * @return This method returns a pointer to the scatter gather element. 328 */ 329 void sati_cb_sgl_next_sge( 330 void * scsi_io, 331 void * ata_io, 332 void * current_sge, 333 void ** next_sge 334 ); 335 336 /** 337 * @brief This method will set the next scatter-gather elements address 338 * low field. 339 * 340 * @param[in] current_sge This parameter specifies the current SG element 341 * being pointed to. 342 * @param[in] address_low This parameter specifies the lower 32-bits 343 * of address to be programmed into the SG element. 344 * @param[in] address_high This parameter specifies the upper 32-bits 345 * of address to be programmed into the SG element. 346 * @param[in] length This parameter specifies the number of bytes 347 * to be programmed into the SG element. 348 * 349 * @return none 350 */ 351 void sati_cb_sge_write( 352 void * current_sge, 353 U32 phys_address_low, 354 U32 phys_address_high, 355 U32 byte_length 356 ); 357 358 /** 359 * @brief This method will check to see if the translation requires 360 * a translation response callback. Some translations need to be alerted on all 361 * failures so sequence cleanup can be completed for halting the translation. 362 * 363 * @param[in] the current SCIC request under going translation. 364 * 365 * @return TRUE A response callback will be required to complete this translation sequence. 366 */ 367 BOOL sati_cb_do_translate_response( 368 void * request 369 ); 370 371 /** 372 * @brief This method retrieves the SAS address for the device associated 373 * with the supplied SCSI IO request. This method assumes that the 374 * associated device is contained in a SAS Domain. 375 * 376 * @param[in] scsi_io This parameter specifies the user's SCSI IO request 377 * for which to retrieve the SAS address of the device. 378 * @param[out] sas_address This parameter specifies the SAS address memory 379 * to be contain the retrieved value. 380 * 381 * @return none 382 */ 383 void sati_cb_device_get_sas_address( 384 void * scsi_io, 385 SCI_SAS_ADDRESS_T * sas_address 386 ); 387 388 /** 389 * @brief In this method the user is expected to log the supplied 390 * error information. The user must be capable of handling variable 391 * length argument lists and should consider prepending the fact 392 * that this is an error from the core. 393 * 394 * @param[in] logger_object This parameter specifies the logger object 395 * associated with this message. 396 * @param[in] log_object_mask This parameter specifies the log objects 397 * for which this message is being generated. 398 * @param[in] log_message This parameter specifies the message to be logged. 399 * 400 * @return none 401 */ 402 void sati_cb_logger_log_error( 403 void * logger_object, 404 U32 log_object_mask, 405 char * log_message, 406 ... 407 ); 408 409 /** 410 * @brief In this method the user is expected to log the supplied warning 411 * information. The user must be capable of handling variable 412 * length argument lists and should consider prepending the fact 413 * that this is a warning from the core. 414 * 415 * @param[in] logger_object This parameter specifies the logger object 416 * associated with this message. 417 * @param[in] log_object_mask This parameter specifies the log objects 418 * for which this message is being generated. 419 * @param[in] log_message This parameter specifies the message to be logged. 420 * 421 * @return none 422 */ 423 void sati_cb_logger_log_warning( 424 void * logger_object, 425 U32 log_object_mask, 426 char * log_message, 427 ... 428 ); 429 430 /** 431 * @brief In this method the user is expected to log the supplied debug 432 * information. The user must be capable of handling variable 433 * length argument lists and should consider prepending the fact 434 * that this is a debug message from the core. 435 * 436 * @param[in] logger_object This parameter specifies the logger object 437 * associated with this message. 438 * @param[in] log_object_mask This parameter specifies the log objects 439 * for which this message is being generated. 440 * @param[in] log_message This parameter specifies the message to be logged. 441 * 442 * @return none 443 */ 444 void sati_cb_logger_log_info( 445 void * logger_object, 446 U32 log_object_mask, 447 char * log_message, 448 ... 449 ); 450 451 /** 452 * @brief In this method the user is expected to log the supplied function 453 * trace information. The user must be capable of handling variable 454 * length argument lists and should consider prepending the fact 455 * that this is a function trace (i.e. entry/exit) message from the 456 * core. 457 * 458 * @param[in] logger_object This parameter specifies the logger object 459 * associated with this message. 460 * @param[in] log_object_mask This parameter specifies the log objects 461 * for which this message is being generated. 462 * @param[in] log_message This parameter specifies the message to be logged. 463 * 464 * @return none 465 */ 466 void sati_cb_logger_log_trace( 467 void * logger_object, 468 U32 log_object_mask, 469 char * log_message, 470 ... 471 ); 472 473 #include <dev/isci/scil/sati_callbacks_implementation.h> 474 475 #else // SATI_DEFAULT_DECLARATION 476 477 #include <dev/isci/scil/scif_sas_sati_binding.h> 478 #endif // SATI_DEFAULT_DECLARATION 479 480 #endif // _SATI_CALLBACKS_H_ 481 482