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 _SCIC_CONTROLLER_H_
55 #define _SCIC_CONTROLLER_H_
60 * @brief This file contains all of the interface methods that can be called
61 * by an SCIC user on a controller object.
68 #include <dev/isci/scil/sci_types.h>
69 #include <dev/isci/scil/sci_status.h>
70 #include <dev/isci/scil/sci_controller.h>
71 #include <dev/isci/scil/scic_config_parameters.h>
76 * Allowed PORT configuration modes
78 * APC Automatic PORT configuration mode is defined by the OEM configuration
79 * parameters providing no PHY_MASK parameters for any PORT. i.e. There are
80 * no phys assigned to any of the ports at start.
82 * MPC Manual PORT configuration mode is defined by the OEM configuration
83 * parameters providing a PHY_MASK value for any PORT. It is assumed that
84 * any PORT with no PHY_MASK is an invalid port and not all PHYs must be
85 * assigned. A PORT_PHY mask that assigns just a single PHY to a port and no
86 * other PHYs being assigned is sufficient to declare manual PORT configuration.
88 enum SCIC_PORT_CONFIGURATION_MODE
90 SCIC_PORT_MANUAL_CONFIGURATION_MODE,
91 SCIC_PORT_AUTOMATIC_CONFIGURATION_MODE
95 * @enum _SCIC_INTERRUPT_TYPE
97 * @brief This enumeration depicts the various types of interrupts that
98 * are potentially supported by a SCI Core implementation.
100 typedef enum _SCIC_INTERRUPT_TYPE
102 SCIC_LEGACY_LINE_INTERRUPT_TYPE,
103 SCIC_MSIX_INTERRUPT_TYPE,
106 * This enumeration value indicates the use of polling.
110 } SCIC_INTERRUPT_TYPE;
113 * @typedef SCIC_CONTROLLER_INTERRUPT_HANDLER
115 * @brief This method is called by the SCI user in order to have the SCI
116 * implementation handle the interrupt. This method performs
117 * minimal processing to allow for streamlined interrupt time usage.
119 * TRUE: returned if there is an interrupt to process and it was
121 * FALSE: returned if no interrupt was processed.
124 typedef BOOL (*SCIC_CONTROLLER_INTERRUPT_HANDLER)(
125 SCI_CONTROLLER_HANDLE_T controller
129 * @brief This method is called by the SCI user to process completions
130 * generated as a result of a previously handled interrupt. This
131 * method will result in the completion of IO requests and handling
132 * of other controller generated events. This method should be
133 * called some time after the interrupt handler.
135 * @note Most, if not all, of the user callback APIs are invoked from within
136 * this API. As a result, the user should be cognizent of the operating
137 * level at which they invoke this API.
140 typedef void (*SCIC_CONTROLLER_COMPLETION_HANDLER)(
141 SCI_CONTROLLER_HANDLE_T controller
145 * @struct SCIC_CONTROLLER_HANDLER_METHODS
147 * @brief This structure contains an interrupt handler and completion
148 * handler function pointers.
150 typedef struct SCIC_CONTROLLER_HANDLER_METHODS
152 SCIC_CONTROLLER_INTERRUPT_HANDLER interrupt_handler;
153 SCIC_CONTROLLER_COMPLETION_HANDLER completion_handler;
155 } SCIC_CONTROLLER_HANDLER_METHODS_T;
158 * @brief This method will attempt to construct a controller object
159 * utilizing the supplied parameter information.
161 * @param[in] library This parameter specifies the handle to the library
162 * object associated with the controller being constructed.
163 * @param[in] controller This parameter specifies the controller to be
165 * @param[in] user_object This parameter is a reference to the SCIL users
166 * controller object and will be used to associate with the core
169 * @return Indicate if the controller was successfully constructed or if
170 * it failed in some way.
171 * @retval SCI_SUCCESS This value is returned if the controller was
172 * successfully constructed.
173 * @retval SCI_WARNING_TIMER_CONFLICT This value is returned if the
174 * interrupt coalescence timer may cause SAS compliance issues
175 * for SMP Target mode response processing.
176 * @retval SCI_FAILURE_UNSUPPORTED_CONTROLLER_TYPE This value is returned if
177 * the controller does not support the supplied type.
178 * @retval SCI_FAILURE_UNSUPPORTED_INIT_DATA_VERSION This value is returned
179 * if the controller does not support the supplied initialization
182 SCI_STATUS scic_controller_construct(
183 SCI_LIBRARY_HANDLE_T library,
184 SCI_CONTROLLER_HANDLE_T controller,
189 * @brief This method will enable all controller interrupts.
191 * @param[in] controller This parameter specifies the controller for which
192 * to enable interrupts.
196 void scic_controller_enable_interrupts(
197 SCI_CONTROLLER_HANDLE_T controller
201 * @brief This method will disable all controller interrupts.
203 * @param[in] controller This parameter specifies the controller for which
204 * to disable interrupts.
208 void scic_controller_disable_interrupts(
209 SCI_CONTROLLER_HANDLE_T controller
213 * @brief This method will return provide function pointers for the
214 * interrupt handler and completion handler. The interrupt handler
215 * is expected to be invoked at interrupt time. The completion
216 * handler is scheduled to run as a result of the interrupt handler.
217 * The completion handler performs the bulk work for processing
220 * @param[in] interrupt_type This parameter informs the core which type
221 * of interrupt/completion methods are being requested. These
222 * are the types: SCIC_LEGACY_LINE_INTERRUPT_TYPE,
223 * SCIC_MSIX_INTERRUPT_TYPE, SCIC_NO_INTERRUPTS (POLLING)
224 * @param[in] message_count This parameter informs the core the
225 * number of MSI-X messages to be utilized. This parameter must
226 * be 0 when requesting legacy line based handlers.
227 * @param[in] handler_methods The caller provides a pointer to a buffer of
228 * type SCIC_CONTROLLER_HANDLER_METHODS_T. The size depends on
229 * the combination of the interrupt_type and message_count input
231 * SCIC_LEGACY_LINE_INTERRUPT_TYPE:
232 * - size = sizeof(SCIC_CONTROLLER_HANDLER_METHODS_T)
233 * SCIC_MSIX_INTERRUPT_TYPE:
234 * - size = message_count*sizeof(SCIC_CONTROLLER_HANDLER_METHODS_T)
235 * @param[out] handler_methods SCIC fills out the caller's buffer with the
236 * appropriate interrupt and completion handlers based on the info
237 * provided in the interrupt_type and message_count input
238 * parameters. For SCIC_LEGACY_LINE_INTERRUPT_TYPE, the buffer
239 * receives a single SCIC_CONTROLLER_HANDLER_METHODS_T element
240 * regardless that the message_count parameter is zero.
241 * For SCIC_MSIX_INTERRUPT_TYPE, the buffer receives an array of
242 * elements of type SCIC_CONTROLLER_HANDLER_METHODS_T where the
243 * array size is equivalent to the message_count parameter. The
244 * array is zero-relative where entry zero corresponds to
245 * message-vector zero, entry one corresponds to message-vector one,
248 * @return Indicate if the handler retrieval operation was successful.
249 * @retval SCI_SUCCESS This value is returned if retrieval succeeded.
250 * @retval SCI_FAILURE_UNSUPPORTED_MESSAGE_COUNT This value is returned
251 * if the user supplied an unsupported number of MSI-X messages.
252 * For legacy line interrupts the only valid value is 0.
254 SCI_STATUS scic_controller_get_handler_methods(
255 SCIC_INTERRUPT_TYPE interrupt_type,
257 SCIC_CONTROLLER_HANDLER_METHODS_T * handler_methods
261 * @brief This method will initialize the controller hardware managed by
262 * the supplied core controller object. This method will bring the
263 * physical controller hardware out of reset and enable the core to
264 * determine the capabilities of the hardware being managed. Thus,
265 * the core controller can determine it's exact physical (DMA capable)
266 * memory requirements.
268 * @pre The SCI Core user must have called scic_controller_construct()
269 * on the supplied controller object previously.
271 * @param[in] controller This parameter specifies the controller to be
274 * @return Indicate if the controller was successfully initialized or if
275 * it failed in some way.
276 * @retval SCI_SUCCESS This value is returned if the controller hardware
277 * was successfully initialized.
279 SCI_STATUS scic_controller_initialize(
280 SCI_CONTROLLER_HANDLE_T controller
284 * @brief This method returns the suggested scic_controller_start()
285 * timeout amount. The user is free to use any timeout value,
286 * but this method provides the suggested minimum start timeout
287 * value. The returned value is based upon empirical information
288 * determined as a result of interoperability testing.
290 * @param[in] controller the handle to the controller object for which
291 * to return the suggested start timeout.
293 * @return This method returns the number of milliseconds for the
294 * suggested start operation timeout.
296 U32 scic_controller_get_suggested_start_timeout(
297 SCI_CONTROLLER_HANDLE_T controller
301 * @brief This method will start the supplied core controller. This method
302 * will start the staggered spin up operation. The SCI User completion
303 * callback is called when the following conditions are met:
304 * -# the return status of this method is SCI_SUCCESS.
305 * -# after all of the phys have successfully started or been given
306 * the opportunity to start.
308 * @pre The SCI Core user must have filled in the physical memory
309 * descriptor structure via the
310 * sci_controller_get_memory_descriptor_list() method.
311 * @pre The SCI Core user must have invoked the scic_controller_initialize()
312 * method prior to invoking this method.
314 * @pre The controller must be in the INITIALIZED or STARTED state.
316 * @param[in] controller the handle to the controller object to start.
317 * @param[in] timeout This parameter specifies the number of milliseconds
318 * in which the start operation should complete.
320 * @return Indicate if the controller start method succeeded or failed in
322 * @retval SCI_SUCCESS if the start operation succeeded.
323 * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in
325 * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in
326 * the INITIALIZED or STARTED states.
327 * @retval SCI_FAILURE_INVALID_MEMORY_DESCRIPTOR if there are
328 * inconsistent or invalid values in the supplied
329 * SCI_PHYSICAL_MEMORY_DESCRIPTOR array.
331 SCI_STATUS scic_controller_start(
332 SCI_CONTROLLER_HANDLE_T controller,
337 * @brief This method will stop an individual controller object.This method
338 * will invoke the associated user callback upon completion. The
339 * completion callback is called when the following conditions are met:
340 * -# the method return status is SCI_SUCCESS.
341 * -# the controller has been quiesced.
342 * This method will ensure that all IO requests are quiesced, phys
343 * are stopped, and all additional operation by the hardware is halted.
345 * @pre The controller must be in the STARTED or STOPPED state.
347 * @param[in] controller the handle to the controller object to stop.
348 * @param[in] timeout This parameter specifies the number of milliseconds
349 * in which the stop operation should complete.
351 * @return Indicate if the controller stop method succeeded or failed in
353 * @retval SCI_SUCCESS if the stop operation successfully began.
354 * @retval SCI_WARNING_ALREADY_IN_STATE if the controller is already in
356 * @retval SCI_FAILURE_INVALID_STATE if the controller is not either in
357 * the STARTED or STOPPED states.
359 SCI_STATUS scic_controller_stop(
360 SCI_CONTROLLER_HANDLE_T controller,
365 * @brief This method will reset the supplied core controller regardless of
366 * the state of said controller. This operation is considered
367 * destructive. In other words, all current operations are wiped
368 * out. No IO completions for outstanding devices occur. Outstanding
369 * IO requests are not aborted or completed at the actual remote
372 * @param[in] controller the handle to the controller object to reset.
374 * @return Indicate if the controller reset method succeeded or failed in
376 * @retval SCI_SUCCESS if the reset operation successfully started.
377 * @retval SCI_FATAL_ERROR if the controller reset operation is unable to
380 SCI_STATUS scic_controller_reset(
381 SCI_CONTROLLER_HANDLE_T controller
385 * @brief This method is called by the SCI user to send/start an IO request.
386 * If the method invocation is successful, then the IO request has
387 * been queued to the hardware for processing.
390 * - IO tags are a protected resource. It is incumbent upon the
391 * SCI Core user to ensure that each of the methods that may
392 * allocate or free available IO tags are handled in a mutually
393 * exclusive manner. This method is one of said methods requiring
394 * proper critical code section protection (e.g. semaphore,
396 * - For SATA, the user is required to manage NCQ tags. As a
397 * result, it is expected the user will have set the NCQ tag
398 * field in the host to device register FIS prior to calling
399 * this method. There is also a requirement for the user
400 * to call scic_stp_io_set_ncq_tag() prior to invoking the
401 * scic_controller_start_io() method.
403 * @param[in] controller the handle to the controller object for which
404 * to start an IO request.
405 * @param[in] remote_device the handle to the remote device object for which
406 * to start an IO request.
407 * @param[in] io_request the handle to the io request object to start.
408 * @param[in] io_tag This parameter specifies a previously allocated IO tag
409 * that the user desires to be utilized for this request.
410 * This parameter is optional. The user is allowed to supply
411 * SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter.
412 * @see scic_controller_allocate_tag() for more information
413 * on allocating a tag.
415 * @return Indicate if the controller successfully started the IO request.
416 * @retval SCI_IO_SUCCESS if the IO request was successfully started.
418 * @todo Determine the failure situations and return values.
420 SCI_IO_STATUS scic_controller_start_io(
421 SCI_CONTROLLER_HANDLE_T controller,
422 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
423 SCI_IO_REQUEST_HANDLE_T io_request,
427 #if !defined(DISABLE_TASK_MANAGEMENT)
430 * @brief This method is called by the SCIC user to send/start a framework
431 * task management request.
434 * - IO tags are a protected resource. It is incumbent upon the
435 * SCI Core user to ensure that each of the methods that may
436 * allocate or free available IO tags are handled in a mutually
437 * exclusive manner. This method is one of said methods requiring
438 * proper critical code section protection (e.g. semaphore,
440 * - The user must synchronize this task with completion queue
441 * processing. If they are not synchronized then it is possible
442 * for the io requests that are being managed by the task request
443 * can complete before starting the task request.
445 * @param[in] controller the handle to the controller object for which
446 * to start the task management request.
447 * @param[in] remote_device the handle to the remote device object for which
448 * to start the task management request.
449 * @param[in] task_request the handle to the task request object to start.
450 * @param[in] io_tag This parameter specifies a previously allocated IO tag
451 * that the user desires to be utilized for this request. Note
452 * this not the io_tag of the request being managed. It is to
453 * be utilized for the task request itself.
454 * This parameter is optional. The user is allowed to supply
455 * SCI_CONTROLLER_INVALID_IO_TAG as the value for this parameter.
456 * @see scic_controller_allocate_tag() for more information
457 * on allocating a tag.
459 * @return Indicate if the controller successfully started the IO request.
460 * @retval SCI_TASK_SUCCESS if the task request was successfully started.
461 * @retval SCI_TASK_FAILURE_REQUIRES_SCSI_ABORT This value is returned if
462 * there is/are task(s) outstanding that require termination or
463 * completion before this request can succeed.
465 SCI_TASK_STATUS scic_controller_start_task(
466 SCI_CONTROLLER_HANDLE_T controller,
467 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
468 SCI_TASK_REQUEST_HANDLE_T task_request,
473 * @brief This method will perform core specific completion operations for
474 * task management request. After this method is invoked, the user should
475 * consider the task request as invalid until it is properly reused
476 * (i.e. re-constructed).
478 * @param[in] controller The handle to the controller object for which
479 * to complete the task management request.
480 * @param[in] remote_device The handle to the remote device object for which
481 * to complete the task management request.
482 * @param[in] task_request the handle to the task management request object
485 * @return Indicate if the controller successfully completed the task
486 * management request.
487 * @retval SCI_SUCCESS if the completion process was successful.
489 SCI_STATUS scic_controller_complete_task(
490 SCI_CONTROLLER_HANDLE_T controller,
491 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
492 SCI_TASK_REQUEST_HANDLE_T task_request
495 #else // !defined(DISABLE_TASK_MANAGEMENT)
497 #define scic_controller_start_task(controller, dev, task, tag) SCI_TASK_FAILURE
498 #define scic_controller_complete_task(controller, dev, task) SCI_FAILURE
500 #endif // !defined(DISABLE_TASK_MANAGEMENT)
503 * @brief This method is called by the SCI Core user to terminate an ongoing
504 * (i.e. started) core IO request. This does not abort the IO request
505 * at the target, but rather removes the IO request from the host
508 * @param[in] controller the handle to the controller object for which
509 * to terminate a request.
510 * @param[in] remote_device the handle to the remote device object for which
511 * to terminate a request.
512 * @param[in] request the handle to the io or task management request
513 * object to terminate.
515 * @return Indicate if the controller successfully began the terminate process
516 * for the IO request.
517 * @retval SCI_SUCCESS if the terminate process was successfully started for
520 * @todo Determine the failure situations and return values.
522 SCI_STATUS scic_controller_terminate_request(
523 SCI_CONTROLLER_HANDLE_T controller,
524 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
525 SCI_IO_REQUEST_HANDLE_T request
529 * @brief This method will perform core specific completion operations for
530 * an IO request. After this method is invoked, the user should
531 * consider the IO request as invalid until it is properly reused
532 * (i.e. re-constructed).
535 * - IO tags are a protected resource. It is incumbent upon the
536 * SCI Core user to ensure that each of the methods that may
537 * allocate or free available IO tags are handled in a mutually
538 * exclusive manner. This method is one of said methods requiring
539 * proper critical code section protection (e.g. semaphore,
541 * - If the IO tag for a request was allocated, by the SCI Core user,
542 * using the scic_controller_allocate_io_tag() method, then it is
543 * the responsibility of the caller to invoke the
544 * scic_controller_free_io_tag() method to free the tag (i.e. this
545 * method will not free the IO tag).
547 * @param[in] controller The handle to the controller object for which
548 * to complete the IO request.
549 * @param[in] remote_device The handle to the remote device object for which
550 * to complete the IO request.
551 * @param[in] io_request the handle to the io request object to complete.
553 * @return Indicate if the controller successfully completed the IO request.
554 * @retval SCI_SUCCESS if the completion process was successful.
556 SCI_STATUS scic_controller_complete_io(
557 SCI_CONTROLLER_HANDLE_T controller,
558 SCI_REMOTE_DEVICE_HANDLE_T remote_device,
559 SCI_IO_REQUEST_HANDLE_T io_request
564 * @brief This method simply provides the user with a unique handle for a
565 * given SAS/SATA core port index.
567 * @param[in] controller This parameter represents the handle to the
568 * controller object from which to retrieve a port (SAS or
570 * @param[in] port_index This parameter specifies the port index in
571 * the controller for which to retrieve the port handle.
572 * 0 <= port_index < maximum number of phys.
573 * @param[out] port_handle This parameter specifies the retrieved port handle
574 * to be provided to the caller.
576 * @return Indicate if the retrieval of the port handle was successful.
577 * @retval SCI_SUCCESS This value is returned if the retrieval was successful.
578 * @retval SCI_FAILURE_INVALID_PORT This value is returned if the supplied
579 * port id is not in the supported range.
581 SCI_STATUS scic_controller_get_port_handle(
582 SCI_CONTROLLER_HANDLE_T controller,
584 SCI_PORT_HANDLE_T * port_handle
588 * @brief This method simply provides the user with a unique handle for a
589 * given SAS/SATA phy index/identifier.
591 * @param[in] controller This parameter represents the handle to the
592 * controller object from which to retrieve a phy (SAS or
594 * @param[in] phy_index This parameter specifies the phy index in
595 * the controller for which to retrieve the phy handle.
596 * 0 <= phy_index < maximum number of phys.
597 * @param[out] phy_handle This parameter specifies the retrieved phy handle
598 * to be provided to the caller.
600 * @return Indicate if the retrieval of the phy handle was successful.
601 * @retval SCI_SUCCESS This value is returned if the retrieval was successful.
602 * @retval SCI_FAILURE_INVALID_PHY This value is returned if the supplied phy
603 * id is not in the supported range.
605 SCI_STATUS scic_controller_get_phy_handle(
606 SCI_CONTROLLER_HANDLE_T controller,
608 SCI_PHY_HANDLE_T * phy_handle
612 * @brief This method will allocate a tag from the pool of free IO tags.
613 * Direct allocation of IO tags by the SCI Core user is optional.
614 * The scic_controller_start_io() method will allocate an IO
615 * tag if this method is not utilized and the tag is not
616 * supplied to the IO construct routine. Direct allocation of IO tags
617 * may provide additional performance improvements in environments
618 * capable of supporting this usage model. Additionally, direct
619 * allocation of IO tags also provides additional flexibility to the
620 * SCI Core user. Specifically, the user may retain IO tags across
621 * the lives of multiple IO requests.
623 * @warning IO tags are a protected resource. It is incumbent upon the
624 * SCI Core user to ensure that each of the methods that may
625 * allocate or free available IO tags are handled in a mutually
626 * exclusive manner. This method is one of said methods requiring
627 * proper critical code section protection (e.g. semaphore,
630 * @param[in] controller the handle to the controller object for which to
633 * @return An unsigned integer representing an available IO tag.
634 * @retval SCI_CONTROLLER_INVALID_IO_TAG This value is returned if there
635 * are no currently available tags to be allocated.
636 * @retval All return other values indicate a legitimate tag.
638 U16 scic_controller_allocate_io_tag(
639 SCI_CONTROLLER_HANDLE_T controller
643 * @brief This method will free an IO tag to the pool of free IO tags.
644 * This method provides the SCI Core user more flexibility with
645 * regards to IO tags. The user may desire to keep an IO tag after
646 * an IO request has completed, because they plan on re-using the
647 * tag for a subsequent IO request. This method is only legal if
648 * the tag was allocated via scic_controller_allocate_io_tag().
651 * - IO tags are a protected resource. It is incumbent upon the
652 * SCI Core user to ensure that each of the methods that may
653 * allocate or free available IO tags are handled in a mutually
654 * exclusive manner. This method is one of said methods requiring
655 * proper critical code section protection (e.g. semaphore,
657 * - If the IO tag for a request was allocated, by the SCI Core user,
658 * using the scic_controller_allocate_io_tag() method, then it is
659 * the responsibility of the caller to invoke this method to free
662 * @param[in] controller This parameter specifies the handle to the
663 * controller object for which to free/return the tag.
664 * @param[in] io_tag This parameter represents the tag to be freed to the
665 * pool of available tags.
667 * @return This method returns an indication of whether the tag was
668 * successfully put back (freed) to the pool of available tags.
669 * @retval SCI_SUCCESS This return value indicates the tag was successfully
670 * placed into the pool of available IO tags.
671 * @retval SCI_FAILURE_INVALID_IO_TAG This value is returned if the supplied
672 * tag is not a valid IO tag value.
674 SCI_STATUS scic_controller_free_io_tag(
675 SCI_CONTROLLER_HANDLE_T controller,
680 * @brief This method returns the size of the core's scratch RAM.
682 * @return Size of the scratch RAM in dwords.
684 U32 scic_controller_get_scratch_ram_size(
685 SCI_CONTROLLER_HANDLE_T controller
689 * @brief This method allows the user to read a U32 from the core's
692 * @param[in] controller This parameter represents the handle to the
693 * controller object for which to read scratch RAM.
694 * @param[in] offset The offset (in dwords) into the scratch RAM.
695 * @param[out] value The location where the read value should be stored.
697 * @return Indicate if the user specified a valid offset into the
699 * @retval SCI_SUCCESS The scratch RAM was successfully read.
700 * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user specified an
703 SCI_STATUS scic_controller_read_scratch_ram_dword(
704 SCI_CONTROLLER_HANDLE_T controller,
710 * @brief This method allows the user to write a U32 to the core's
713 * @param[in] controller This parameter represents the handle to the
714 * controller object for which to write scratch RAM.
715 * @param[in] offset The offset (in dwords) into the scratch RAM.
716 * @param[out] value The value to be written to scratch RAM.
718 * @return Indicate if the user specified a valid offset into the
720 * @retval SCI_SUCCESS The scratch RAM was successfully written.
721 * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user specified an
724 SCI_STATUS scic_controller_write_scratch_ram_dword(
725 SCI_CONTROLLER_HANDLE_T controller,
731 * @brief This method allows the user to configure the SCI core into
732 * either a performance mode or a memory savings mode.
734 * @param[in] controller This parameter represents the handle to the
735 * controller object for which to update the operating
737 * @param[in] mode This parameter specifies the new mode for the
740 * @return Indicate if the user successfully change the operating mode
742 * @retval SCI_SUCCESS The user successfully updated the mode.
744 SCI_STATUS scic_controller_set_mode(
745 SCI_CONTROLLER_HANDLE_T controller,
746 SCI_CONTROLLER_MODE mode
750 #if !defined(DISABLE_INTERRUPTS)
752 * @brief This method allows the user to configure the interrupt coalescence.
754 * @param[in] controller This parameter represents the handle to the
755 * controller object for which its interrupt coalesce register
758 * @param[in] coalesce_number Used to control the number of entries in the
759 * Completion Queue before an interrupt is generated. If the
760 * number of entries exceed this number, an interrupt will be
761 * generated. The valid range of the input is [0, 256].
762 * A setting of 0 results in coalescing being disabled.
763 * @param[in] coalesce_timeout Timeout value in microseconds. The valid range
764 * of the input is [0, 2700000] . A setting of 0 is allowed and
765 * results in no interrupt coalescing timeout.
767 * @return Indicate if the user successfully set the interrupt coalesce parameters.
768 * @retval SCI_SUCCESS The user successfully updated the interrutp coalescence.
769 * @retval SCI_FAILURE_INVALID_PARAMETER_VALUE The user input value is out of range.
771 SCI_STATUS scic_controller_set_interrupt_coalescence(
772 SCI_CONTROLLER_HANDLE_T controller,
778 * @brief This method retrieves the interrupt coalescing values
780 * @param[in] controller This parameter specifies the controller for
781 * which its interrupt coalescing number is read.
783 * @param[out] coalesce_number, interrupt coalescing number read from controller.
785 * @param[out] coalesce_timeout, timeout value in microseconds.
789 void scic_controller_get_interrupt_coalescence(
790 SCI_CONTROLLER_HANDLE_T controller,
791 U32 * coalesce_number,
792 U32 * coalesce_timeout
794 #else // !defined(DISABLE_INTERRUPTS)
795 #define scic_controller_set_interrupt_coalescence(controller, num, timeout) \
797 #define scic_controller_get_interrupt_coalescence(controller, num, timeout)
798 #endif // !defined(DISABLE_INTERRUPTS)
802 * @brief This method suspend the controller, reinitialize RAMs, then resume
805 * @param[in] controller This parameter specifies the controller which is transitioning.
807 * @param[in] restrict_completions This parameter specifies whether the controller should
808 * ignore completion processing for non-fastpath events. This will cause
809 * the completions to be thrown away.
811 * @return SCI_STATUS The status of controller transition.
813 SCI_STATUS scic_controller_transition(
814 SCI_CONTROLLER_HANDLE_T controller,
815 BOOL restrict_completions
820 * @brief This method suspends the controller.
822 * @param[in] controller This parameter specifies the controller which is to be suspended.
824 * @return SCI_STATUS The status of controller suspend.
826 SCI_STATUS scic_controller_suspend(
827 SCI_CONTROLLER_HANDLE_T controller
831 * @brief This method resumes the controller.
833 * @param[in] controller This parameter specifies the controller which is to be resumed.
835 * @return SCI_STATUS The status of controller resume.
837 SCI_STATUS scic_controller_resume(
838 SCI_CONTROLLER_HANDLE_T controller
841 SCI_STATUS scic_controller_get_max_ports(
842 SCI_CONTROLLER_HANDLE_T controller,
846 SCI_STATUS scic_controller_get_max_phys(
847 SCI_CONTROLLER_HANDLE_T controller,
853 #endif // __cplusplus
855 #endif // _SCIC_CONTROLLER_H_