1/*- 2 * This file is provided under a dual BSD/GPLv2 license. When using or 3 * redistributing this file, you may do so under either license. 4 * 5 * GPL LICENSE SUMMARY 6 * 7 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8 * 9 * This program is free software; you can redistribute it and/or modify 10 * it under the terms of version 2 of the GNU General Public License as 11 * published by the Free Software Foundation. 12 * 13 * This program is distributed in the hope that it will be useful, but 14 * WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * General Public License for more details. 17 * 18 * You should have received a copy of the GNU General Public License 19 * along with this program; if not, write to the Free Software 20 * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21 * The full GNU General Public License is included in this distribution 22 * in the file called LICENSE.GPL. 23 * 24 * BSD LICENSE 25 * 26 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27 * All rights reserved. 28 * 29 * Redistribution and use in source and binary forms, with or without 30 * modification, are permitted provided that the following conditions 31 * are met: 32 * 33 * * Redistributions of source code must retain the above copyright 34 * notice, this list of conditions and the following disclaimer. 35 * * Redistributions in binary form must reproduce the above copyright 36 * notice, this list of conditions and the following disclaimer in 37 * the documentation and/or other materials provided with the 38 * distribution. 39 * 40 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51 * 52 * $FreeBSD$ 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 */ 78void * 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 */ 92U32 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 */ 106void 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 */ 127void 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 */ 149void 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 */ 166U8 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 retreive the location of the response buffer to 177 * be written. 178 * 179 * @return This method returns the address of the response data buffer. 180 */ 181void * 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 retreive the location of the sense buffer to 193 * be written. 194 * 195 * @return This method returns the address of the sense data buffer. 196 */ 197U8* 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 retreive the location of the sense buffer to 207 * be written. 208 * 209 * @return This method returns the length of the sense data buffer. 210 */ 211U32 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 */ 226void 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 */ 243U8 * 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 reponse 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 */ 257U8 * 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 */ 271void * 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 */ 290void 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 */ 308void 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 */ 329void 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 */ 351void 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 */ 367BOOL 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 retreive 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 */ 383void 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 */ 402void 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 */ 423void 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 */ 444void 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 */ 466void 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