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 _SCIF_CONTROLLER_H_
57 #define _SCIF_CONTROLLER_H_
62 * @brief This file contains all of the interface methods that can be called
63 * by an SCIF user on a SCIF controller object.
70 #include <dev/isci/scil/sci_types.h>
71 #include <dev/isci/scil/sci_status.h>
75 * @brief This method will attempt to construct a framework controller object
76 * utilizing the supplied parameter information.
78 * @param[in] library This parameter specifies the handle to the framework
79 * library object associated with the controller being constructed.
80 * @param[in] controller This parameter specifies the framework controller to
82 * @param[in] user_object This parameter is a reference to the SCIL users
83 * controller object and will be used to associate with the
84 * framework controller.
86 * @return Indicate if the controller was successfully constructed or if
87 * it failed in some way.
88 * @retval SCI_SUCCESS This value is returned if the controller was
89 * successfully constructed.
90 * @retval SCI_FAILURE_UNSUPPORTED_INIT_DATA_VERSION This value is returned
91 * if the controller does not support the supplied oem parameter
93 * @retval SCI_FAILURE_UNSUPPORTED_PORT_CONFIGURATION This value is returned
94 * if the controller doesn't support the port configuration scheme
97 SCI_STATUS scif_controller_construct(
98 SCI_LIBRARY_HANDLE_T library,
99 SCI_CONTROLLER_HANDLE_T controller,
104 * @brief This method will initialize the SCI Framework controller object.
105 * This includes initialization of the associated core controller.
107 * @param[in] controller This parameter specifies the controller to be
110 * @return Indicate if the controller was successfully initialized or if
111 * it failed in some way.
112 * @retval SCI_SUCCESS This value is returned if the controller hardware
113 * was successfully initialized.
115 SCI_STATUS scif_controller_initialize(
116 SCI_CONTROLLER_HANDLE_T controller
120 * @brief This method returns the suggested scif_controller_start()
121 * timeout amount. The user is free to use any timeout value,
122 * but this method provides the suggested minimum start timeout
123 * value. The returned value is based upon empirical information
124 * determined as a result of interoperability testing.
126 * @param[in] controller the handle to the controller object for which
127 * to return the suggested start timeout.
129 * @return This method returns the number of milliseconds for the
130 * suggested start operation timeout.
132 U32 scif_controller_get_suggested_start_timeout(
133 SCI_CONTROLLER_HANDLE_T controller
137 * @brief This method will start the SCIF controller. The SCI User completion
138 * callback is called when the following conditions are met:
139 * -# the return status of this method is SCI_SUCCESS.
140 * -# after all of the phys have successfully started or been given
141 * the opportunity to start.
143 * @pre The controller must be in the INITIALIZED or STARTED state.
145 * @param[in] controller the handle to the controller object to start.
146 * @param[in] timeout This parameter specifies the number of milliseconds
147 * in which the start operation should complete.
149 * @return Indicate if the controller start method succeeded or failed in
151 * @retval SCI_SUCCESS if the start operation succeeded.
152 * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in
154 * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in
155 * the INITIALIZED or STARTED states.
156 * @retval SCI_FAILURE_INVALID_MEMORY_DESCRIPTOR if there are
157 * inconsistent or invalid values in the supplied
158 * SCI_PHYSICAL_MEMORY_DESCRIPTOR array.
159 * @retval SCI_FAILURE_UNSUPPORTED_PORT_CONFIGURATION This value is
160 * returned if the phy to port allocation cannot be supported.
162 * @see For additional information please refer to: scic_controller_start()
164 SCI_STATUS scif_controller_start(
165 SCI_CONTROLLER_HANDLE_T controller,
170 * @brief This method will stop an individual framework controller object. This
171 * includes quiescing IOs, releasing affiliations, and other shutdown
172 * related operations. This method will invoke the associated user
173 * callback upon completion. The completion callback is called when
174 * the following conditions are met:
175 * -# the method return status is SCI_SUCCESS.
176 * -# the controller has been quiesced.
177 * This method will ensure that all framework IO requests are quiesced
178 * and any additional framework operations are halted.
180 * @pre The controller must be in the STARTED or STOPPED state.
182 * @param[in] controller the handle to the controller object to stop.
183 * @param[in] timeout This parameter specifies the number of milliseconds
184 * in which the stop operation should complete.
186 * @return Indicate if the controller stop method succeeded or failed in
188 * @retval SCI_SUCCESS if the stop operation successfully began.
189 * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in
191 * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in
192 * the STARTED or STOPPED states.
194 * @see For additional information please refer to: scic_controller_stop()
196 SCI_STATUS scif_controller_stop(
197 SCI_CONTROLLER_HANDLE_T controller,
202 * @brief This method will reset the supplied framework controller regardless
203 * of the state of said controller. This operation is considered
204 * destructive. Outstanding IO requests are not aborted or completed
205 * at the actual remote device. However, the framework will
206 * manufacture completion callbacks to the OS driver for the IO
209 * @param[in] controller the handle to the controller object to reset.
211 * @return Indicate if the controller reset method succeeded or failed in
213 * @retval SCI_SUCCESS if the reset operation successfully started.
214 * @retval SCI_FATAL_ERROR if the controller reset operation is unable to
217 * @see For additional information please refer to: scic_controller_reset()
219 SCI_STATUS scif_controller_reset(
220 SCI_CONTROLLER_HANDLE_T controller
224 * @brief This method returns the SCI Core controller handle associated
225 * with this controller.
227 * @param[in] scif_controller the handle to the controller object for which
228 * to retrieve the core specific controller handle
230 * @return Return the SCI core controller handle associated with the supplied
231 * framework controller.
233 SCI_CONTROLLER_HANDLE_T scif_controller_get_scic_handle(
234 SCI_CONTROLLER_HANDLE_T scif_controller
238 * @brief This method is called by the SCIF user to send/start a framework
241 * @param[in] controller the handle to the controller object for which
242 * to start an IO request.
243 * @param[in] remote_device the handle to the remote device object for which
244 * to start an IO request.
245 * @param[in] io_request the handle to the io request object to start.
246 * @param[in] io_tag This parameter specifies a previously allocated IO tag
247 * that the user desires to be utilized for this request.
248 * This parameter is optional. The user is allowed to supply
249 * SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter.
250 * @see scic_controller_allocate_tag() for more information
251 * on allocating a tag.
253 * @return Indicate if the controller successfully started the IO request.
254 * @retval SCI_IO_SUCCESS if the IO request was successfully started.
256 * @see For additional information please refer to: scic_controller_start_io()
258 * @todo Determine the failure situations and return values.
260 SCI_IO_STATUS scif_controller_start_io(
261 SCI_CONTROLLER_HANDLE_T controller,
262 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
263 SCI_IO_REQUEST_HANDLE_T io_request,
268 * @brief This method is called by the SCIF user to send/start a framework
269 * task management request.
271 * @param[in] controller the handle to the controller object for which
272 * to start the task management request.
273 * @param[in] remote_device the handle to the remote device object for which
274 * to start the task management request.
275 * @param[in] task_request the handle to the task request object to start.
276 * @param[in] io_tag This parameter specifies a previously allocated IO tag
277 * that the user desires to be utilized for this request. Note
278 * this not the io_tag of the request being managed. It is to
279 * be utilized for the task request itself.
280 * This parameter is optional. The user is allowed to supply
281 * SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter.
282 * @see scic_controller_allocate_tag() for more information
283 * on allocating a tag.
285 * @return Indicate if the controller successfully started the IO request.
286 * @retval SCI_TASK_SUCCESS if the task request was successfully started.
288 * @see For additional information please refer to: scic_controller_start_task()
290 * @todo Determine the failure situations and return values.
292 SCI_TASK_STATUS scif_controller_start_task(
293 SCI_CONTROLLER_HANDLE_T controller,
294 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
295 SCI_TASK_REQUEST_HANDLE_T task_request,
300 * @brief This method is called by the SCI user to complete a previously
301 * started IO request. After this method is invoked, the user should
302 * consider the IO request as invalid until it is properly reused
303 * (i.e. re-constructed).
305 * @param[in] controller The handle to the controller object for which
306 * to complete the IO request.
307 * @param[in] remote_device The handle to the remote device object for which
308 * to complete the IO request.
309 * @param[in] io_request the handle to the io request object to complete.
311 * @return Indicate if the controller successfully completed the IO request.
312 * @retval SCI_SUCCESS if the completion process was successful.
314 * @see For additional information please refer to:
315 * scic_controller_complete_io()
317 SCI_STATUS scif_controller_complete_io(
318 SCI_CONTROLLER_HANDLE_T controller,
319 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
320 SCI_IO_REQUEST_HANDLE_T io_request
324 * @brief This method will perform framework specific completion operations for
325 * a task management request. After this method is invoked, the user
326 * should consider the task request as invalid until it is properly
327 * reused (i.e. re-constructed).
329 * @param[in] controller The handle to the controller object for which
330 * to complete the task management request.
331 * @param[in] remote_device The handle to the remote device object for which
332 * to complete the task management request.
333 * @param[in] task_request the handle to the task management request object
336 * @return Indicate if the controller successfully completed the task
337 * management request.
338 * @retval SCI_SUCCESS if the completion process was successful.
340 SCI_STATUS scif_controller_complete_task(
341 SCI_CONTROLLER_HANDLE_T controller,
342 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
343 SCI_TASK_REQUEST_HANDLE_T task_request
347 * @brief This method simply provides the user with a unique handle for a
348 * given SAS/SATA domain index.
350 * @param[in] controller This parameter represents the handle to the
351 * controller object from which to retrieve a domain (SAS or
353 * @param[in] port_index This parameter specifies the domain index in
354 * the controller for which to retrieve the domain handle.
355 * @note 0 <= port_index < maximum number of phys.
356 * @param[out] domain_handle This parameter specifies the retrieved domain
357 * handle to be provided to the caller.
359 * @return Indicate if the retrieval of the domain handle was successful.
360 * @retval SCI_SUCCESS This value is returned if the retrieval was successful.
361 * @retval SCI_FAILURE_INVALID_PORT This value is returned if the supplied
362 * port index is not invalid.
364 SCI_STATUS scif_controller_get_domain_handle(
365 SCI_CONTROLLER_HANDLE_T controller,
367 SCI_DOMAIN_HANDLE_T * domain_handle
371 * @brief This method allows the user to configure the SCI Framework
372 * into either a performance mode or a memory savings mode.
374 * @param[in] controller This parameter represents the handle to the
375 * controller object for which to update the operating
377 * @param[in] mode This parameter specifies the new mode for the
380 * @return Indicate if the user successfully change the operating mode
382 * @retval SCI_SUCCESS The user successfully updated the mode.
384 SCI_STATUS scif_controller_set_mode(
385 SCI_CONTROLLER_HANDLE_T controller,
386 SCI_CONTROLLER_MODE mode
390 * @brief This method simply returns the T10 SCSI to ATA Translation (SAT)
391 * specification version to which this translator is compliant for
392 * supported commands.
394 * @return An integer value indicating the SAT version to which this
395 * translator complies.
397 U32 scif_controller_get_sat_compliance_version(
402 * @brief This method simply returns the revision of the T10 SCSI to ATA
403 * Translation (SAT) specification version to which this translator
404 * is compliant for supported commands.
406 * @return An integer value indicating the revision of the SAT version
407 * to which this translator complies.
409 U32 scif_controller_get_sat_compliance_version_revision(
414 * @brief This method is called by the SCI user to start internal io.
416 typedef void (*SCI_START_INTERNAL_IO_ROUTINE)(
417 SCI_CONTROLLER_HANDLE_T controller
420 #if !defined(DISABLE_INTERRUPTS)
422 * @brief This method allows the user to configure the interrupt coalescence.
423 * Please refer to the comment header for
424 * scic_controller_set_interrupt_coalescence() to find details.
426 SCI_STATUS scif_controller_set_interrupt_coalescence(
427 SCI_CONTROLLER_HANDLE_T controller,
433 * @brief This method retrieves the interrupt coalescence information.
434 * Please refer to the comment header for
435 * scic_controller_get_interrupt_coalescence() to find details.
437 void scif_controller_get_interrupt_coalescence(
438 SCI_CONTROLLER_HANDLE_T controller,
439 U32 * coalesce_number,
440 U32 * coalesce_timeout
443 #else // !defined(DISABLE_INTERRUPTS)
445 #define scif_controller_set_interrupt_coalescence(controller, num, timeout) \
447 #define scif_controller_get_interrupt_coalescence(controller, num, timeout)
449 #endif // !defined(DISABLE_INTERRUPTS)
453 #endif // __cplusplus
455 #endif // _SCIF_CONTROLLER_H_