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