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.
7 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
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.
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.
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.
26 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
27 * All rights reserved.
29 * Redistribution and use in source and binary forms, with or without
30 * modification, are permitted provided that the following conditions
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
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.
54 #ifndef _SATI_CALLBACKS_H_
55 #define _SATI_CALLBACKS_H_
59 * @brief This file contains the default callback bindings for SATI. These
60 * must be overridden by the SATI user to ensure successful operation.
63 #include <dev/isci/scil/sati_types.h>
64 #include <dev/isci/scil/intel_sas.h>
66 #ifdef SATI_DEFAULT_DECLARATION
69 * @brief This callback method asks the user to provide the address for
70 * the command descriptor block (CDB) associated with this IO request.
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.
76 * @return This method returns the virtual address of the CDB.
78 void * sati_cb_get_cdb_address(
83 * @brief This callback method asks the user to provide the length of
84 * the command descriptor block (CDB) associated with this IO request.
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.
90 * @return This method returns the length of the CDB.
92 U32 sati_cb_get_cdb_length(
97 * @brief This callback method asks the user to provide the data transfer
98 * direction of this IO request.
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.
106 void sati_cb_get_data_direction(
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.
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.
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
127 void sati_cb_set_data_byte(
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.
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.
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
149 void sati_cb_get_data_byte(
156 * @brief This callback method gets the task type for the SCSI task
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.
163 * @return This method returns one of the enumeration values for
164 * SCSI_TASK_MGMT_REQUEST_CODES
166 U8 sati_cb_get_task_function(
170 #ifdef SATI_TRANSPORT_SUPPORTS_SAS
172 * @brief This callback method retrieves the address of the user's SSP
173 * response IU buffer.
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
179 * @return This method returns the address of the response data buffer.
181 void * sati_cb_get_response_iu_address(
185 #else // SATI_TRANSPORT_SUPPORTS_SAS
188 * @brief This callback method retrieves the address of the user's sense data
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
195 * @return This method returns the address of the sense data buffer.
197 U8* sati_cb_get_sense_data_address(
202 * @brief This callback method retrieves the length of the user's sense data
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
209 * @return This method returns the length of the sense data buffer.
211 U32 sati_cb_get_sense_data_length(
216 * @brief This callback method sets the SCSI status to be associated with
217 * the supplied user's SCSI IO request.
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.
226 void sati_cb_set_scsi_status(
231 #endif // SATI_TRANSPORT_SUPPORTS_SAS
234 * @brief This method retrieves the ATA task file (register FIS) relating to
235 * the host to device command values.
237 * @param[in] ata_io This parameter specifies the user's ATA IO request
238 * from which to retrieve the h2d register FIS address.
240 * @return This method returns the address for the host to device register
243 U8 * sati_cb_get_h2d_register_fis_address(
248 * @brief This method retrieves the ATA task file (register FIS) relating to
249 * the device to host reponse values.
251 * @param[in] ata_io This parameter specifies the user's ATA IO request
252 * from which to retrieve the d2h register FIS address.
254 * @return This method returns the address for the device to host register
257 U8 * sati_cb_get_d2h_register_fis_address(
262 * @brief This method retrieves the address where the ATA data received
263 * from the device is stored.
265 * @param[in] ata_io This parameter specifies the user's ATA IO request
266 * from which to retrieve the received data address.
268 * @return This method returns the address for the data received from
271 void * sati_cb_get_ata_data_address(
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.
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.
287 * @return This method returns the virtual and physical address
288 * of the allocated DMA buffer.
290 void sati_cb_allocate_dma_buffer(
293 void ** virt_address,
294 U32 * phys_address_low,
295 U32 * phys_address_high
299 * @brief This method frees a previously allocated DMA buffer
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
305 * @return This method returns the address for the data received from
308 void sati_cb_free_dma_buffer(
314 * @brief This method retrieves a pointer to the next scatter gather
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.
327 * @return This method returns a pointer to the scatter gather element.
329 void sati_cb_sgl_next_sge(
337 * @brief This method will set the next scatter-gather elements address
340 * @param[in] current_sge This parameter specifies the current SG element
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.
351 void sati_cb_sge_write(
353 U32 phys_address_low,
354 U32 phys_address_high,
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.
363 * @param[in] the current SCIC request under going translation.
365 * @return TRUE A response callback will be required to complete this translation sequence.
367 BOOL sati_cb_do_translate_response(
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.
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.
383 void sati_cb_device_get_sas_address(
385 SCI_SAS_ADDRESS_T * sas_address
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.
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.
402 void sati_cb_logger_log_error(
403 void * logger_object,
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.
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.
423 void sati_cb_logger_log_warning(
424 void * logger_object,
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.
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.
444 void sati_cb_logger_log_info(
445 void * logger_object,
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
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.
466 void sati_cb_logger_log_trace(
467 void * logger_object,
473 #include <dev/isci/scil/sati_callbacks_implementation.h>
475 #else // SATI_DEFAULT_DECLARATION
477 #include <dev/isci/scil/scif_sas_sati_binding.h>
478 #endif // SATI_DEFAULT_DECLARATION
480 #endif // _SATI_CALLBACKS_H_