2 * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0
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.
9 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
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.
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.
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.
28 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
29 * All rights reserved.
31 * Redistribution and use in source and binary forms, with or without
32 * modification, are permitted provided that the following conditions
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
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.
56 #ifndef _SATI_CALLBACKS_H_
57 #define _SATI_CALLBACKS_H_
61 * @brief This file contains the default callback bindings for SATI. These
62 * must be overridden by the SATI user to ensure successful operation.
65 #include <dev/isci/scil/sati_types.h>
66 #include <dev/isci/scil/intel_sas.h>
68 #ifdef SATI_DEFAULT_DECLARATION
71 * @brief This callback method asks the user to provide the address for
72 * the command descriptor block (CDB) associated with this IO request.
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.
78 * @return This method returns the virtual address of the CDB.
80 void * sati_cb_get_cdb_address(
85 * @brief This callback method asks the user to provide the length of
86 * the command descriptor block (CDB) associated with this IO request.
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.
92 * @return This method returns the length of the CDB.
94 U32 sati_cb_get_cdb_length(
99 * @brief This callback method asks the user to provide the data transfer
100 * direction of this IO request.
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.
108 void sati_cb_get_data_direction(
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.
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.
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
129 void sati_cb_set_data_byte(
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.
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.
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
151 void sati_cb_get_data_byte(
158 * @brief This callback method gets the task type for the SCSI task
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.
165 * @return This method returns one of the enumeration values for
166 * SCSI_TASK_MGMT_REQUEST_CODES
168 U8 sati_cb_get_task_function(
172 #ifdef SATI_TRANSPORT_SUPPORTS_SAS
174 * @brief This callback method retrieves the address of the user's SSP
175 * response IU buffer.
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
181 * @return This method returns the address of the response data buffer.
183 void * sati_cb_get_response_iu_address(
187 #else // SATI_TRANSPORT_SUPPORTS_SAS
190 * @brief This callback method retrieves the address of the user's sense data
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
197 * @return This method returns the address of the sense data buffer.
199 U8* sati_cb_get_sense_data_address(
204 * @brief This callback method retrieves the length of the user's sense data
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
211 * @return This method returns the length of the sense data buffer.
213 U32 sati_cb_get_sense_data_length(
218 * @brief This callback method sets the SCSI status to be associated with
219 * the supplied user's SCSI IO request.
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.
228 void sati_cb_set_scsi_status(
233 #endif // SATI_TRANSPORT_SUPPORTS_SAS
236 * @brief This method retrieves the ATA task file (register FIS) relating to
237 * the host to device command values.
239 * @param[in] ata_io This parameter specifies the user's ATA IO request
240 * from which to retrieve the h2d register FIS address.
242 * @return This method returns the address for the host to device register
245 U8 * sati_cb_get_h2d_register_fis_address(
250 * @brief This method retrieves the ATA task file (register FIS) relating to
251 * the device to host response values.
253 * @param[in] ata_io This parameter specifies the user's ATA IO request
254 * from which to retrieve the d2h register FIS address.
256 * @return This method returns the address for the device to host register
259 U8 * sati_cb_get_d2h_register_fis_address(
264 * @brief This method retrieves the address where the ATA data received
265 * from the device is stored.
267 * @param[in] ata_io This parameter specifies the user's ATA IO request
268 * from which to retrieve the received data address.
270 * @return This method returns the address for the data received from
273 void * sati_cb_get_ata_data_address(
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.
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.
289 * @return This method returns the virtual and physical address
290 * of the allocated DMA buffer.
292 void sati_cb_allocate_dma_buffer(
295 void ** virt_address,
296 U32 * phys_address_low,
297 U32 * phys_address_high
301 * @brief This method frees a previously allocated DMA buffer
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
307 * @return This method returns the address for the data received from
310 void sati_cb_free_dma_buffer(
316 * @brief This method retrieves a pointer to the next scatter gather
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.
329 * @return This method returns a pointer to the scatter gather element.
331 void sati_cb_sgl_next_sge(
339 * @brief This method will set the next scatter-gather elements address
342 * @param[in] current_sge This parameter specifies the current SG element
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.
353 void sati_cb_sge_write(
355 U32 phys_address_low,
356 U32 phys_address_high,
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.
365 * @param[in] the current SCIC request under going translation.
367 * @return TRUE A response callback will be required to complete this translation sequence.
369 BOOL sati_cb_do_translate_response(
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.
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.
385 void sati_cb_device_get_sas_address(
387 SCI_SAS_ADDRESS_T * sas_address
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.
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.
404 void sati_cb_logger_log_error(
405 void * logger_object,
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.
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.
425 void sati_cb_logger_log_warning(
426 void * logger_object,
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.
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.
446 void sati_cb_logger_log_info(
447 void * logger_object,
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
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.
468 void sati_cb_logger_log_trace(
469 void * logger_object,
475 #include <dev/isci/scil/sati_callbacks_implementation.h>
477 #else // SATI_DEFAULT_DECLARATION
479 #include <dev/isci/scil/scif_sas_sati_binding.h>
480 #endif // SATI_DEFAULT_DECLARATION
482 #endif // _SATI_CALLBACKS_H_