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_DOMAIN_H_
57 #define _SCIF_DOMAIN_H_
62 * @brief This file contains all of the interface methods that can be called
63 * by an SCI Framework user on the SAS/SATA domain object.
70 #include <dev/isci/scil/sci_types.h>
71 #include <dev/isci/scil/sci_status.h>
72 #include <dev/isci/scil/intel_sas.h>
76 * @brief This method enables the framework user to find the SCI Core Port
77 * object through which the supplied domain is accessed.
79 * @param[in] domain This parameter specifies the framework domain object
80 * for which to return the corresponding SCI Core port object.
82 * @return Return a handle to the SCI Core port through which the supplied
84 * @retval SCI_INVALID_HANDLE This value is returned if the core port
85 * object can not be retrieved.
87 SCI_PORT_HANDLE_T scif_domain_get_scic_port_handle(
88 SCI_DOMAIN_HANDLE_T domain
92 * @brief This method will find and retrieve the device associated with the
93 * supplied SAS address if such a device exists.
95 * @param[in] domain This parameter specifies the framework domain object
96 * on which to discover devices.
97 * @param[in] sas_address This parameter specifies the SAS address of the
98 * object to locate in this domain.
100 * @return Indicate if the device was successfully found in the domain.
101 * @retval SCI_INVALID_HANDLE This value is returned if the device is not
102 * found in the domain.
103 * @retval All other values indicate a valid remote device being found.
105 SCI_REMOTE_DEVICE_HANDLE_T scif_domain_get_device_by_sas_address(
106 SCI_DOMAIN_HANDLE_T domain,
107 SCI_SAS_ADDRESS_T * sas_address
111 * @brief This method will attempt to discover the supplied domain.
113 * @warning This method must be synchronized with the controller completion
114 * handler (see scic_controller_get_handler_methods()). The user
115 * may call this method from within the completion handler in which
116 * case, no synchronization is necessary.
119 * - IO requests from the OS driver are held off until discovery
120 * of the domain is complete.
121 * - Discovery may perform SSP or STP IO requests to configure
122 * remote devices prior to informing the SCIF User of their
123 * existence via the remote_device_ready user callback.
125 * @param[in] domain This parameter specifies the framework domain object
126 * on which to discover devices.
127 * @param[in] discover_timeout This parameter specifies the number of
128 * milliseconds in which the domain discovery operation should
130 * @param[in] device_timeout This parameter specifies the number of
131 * milliseconds in which the device configuration and/or reset
132 * operations should complete. Logically, the device_timeout
133 * parameter should be shorter then the domain_timeout value.
134 * Especially considering the domain could be made up of "n"
137 * @return Indicate if the discover operation started successfully.
138 * @retval SCI_SUCCESS This value is returned if the discover operation
139 * started successfully.
140 * @retval SCI_WARNING_TIMER_CONFLICT This value is returned if the SCI
141 * implementation doesn't support the desired timeout amounts or if
142 * the desired timeout amounts conflict in some manner.
144 SCI_STATUS scif_domain_discover(
145 SCI_DOMAIN_HANDLE_T domain,
146 U32 discover_timeout,
150 #if !defined(DISABLE_SCI_ITERATORS)
152 * @brief This method gets an iterator for the list of remote devices in the
155 * @param[in] domain: This parameter specifies the framework domain handle
156 * @param[in] iterator_buffer: This parameters specifies the memory buffer that
157 * will be used to construct the iterator.
159 * @retval Handle to the remote device list iterator.
161 SCI_ITERATOR_HANDLE_T scif_domain_get_remote_device_iterator(
162 SCI_DOMAIN_HANDLE_T domain,
163 void * iterator_buffer
165 #else // !defined(DISABLE_SCI_ITERATORS)
166 #define scif_domain_get_remote_device_iterator(the_domain, the_buffer) \
168 #endif // !defined(DISABLE_SCI_ITERATORS)
171 * @brief This method simply returns a suggest timeout value for discovery.
173 * @param[in] domain The handle to the domain whose discover activity is to
176 * @return The suggested timeout value for domain discover in milli-seconds.
178 U32 scif_domain_get_suggested_discover_timeout(
179 SCI_DOMAIN_HANDLE_T domain
184 #endif // __cplusplus
186 #endif // _SCIF_DOMAIN_H_