1/*-
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.
4 *
5 * GPL LICENSE SUMMARY
6 *
7 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
8 *
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.
12 *
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.
17 *
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.
23 *
24 * BSD LICENSE
25 *
26 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
27 * All rights reserved.
28 *
29 * Redistribution and use in source and binary forms, with or without
30 * modification, are permitted provided that the following conditions
31 * are met:
32 *
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
38 *     distribution.
39 *
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.
51 *
52 * $FreeBSD$
53 */
54#ifndef _SCIC_PORT_H_
55#define _SCIC_PORT_H_
56
57/**
58 * @file
59 *
60 * @brief This file contains all of the interface methods that can be called
61 *        by an SCI Core user on a SAS or SATA port.
62 */
63
64#ifdef __cplusplus
65extern "C" {
66#endif // __cplusplus
67
68#include <dev/isci/scil/sci_types.h>
69#include <dev/isci/scil/sci_status.h>
70#include <dev/isci/scil/intel_sas.h>
71
72enum SCIC_PORT_NOT_READY_REASON_CODE
73{
74   SCIC_PORT_NOT_READY_NO_ACTIVE_PHYS,
75   SCIC_PORT_NOT_READY_HARD_RESET_REQUESTED,
76   SCIC_PORT_NOT_READY_INVALID_PORT_CONFIGURATION,
77   SCIC_PORT_NOT_READY_RECONFIGURING,
78
79   SCIC_PORT_NOT_READY_REASON_CODE_MAX
80};
81
82/**
83 * @struct SCIC_PORT_END_POINT_PROPERTIES
84 * @brief  This structure defines the properties that can be retrieved
85 *         for each end-point local or remote (attached) port in the
86 *         controller.
87 */
88typedef struct SCIC_PORT_END_POINT_PROPERTIES
89{
90   /**
91    * This field indicates the SAS address for the associated end
92    * point in the port.
93    */
94   SCI_SAS_ADDRESS_T  sas_address;
95
96   /**
97    * This field indicates the protocols supported by the associated
98    * end-point in the port.
99    */
100   SCI_SAS_IDENTIFY_ADDRESS_FRAME_PROTOCOLS_T  protocols;
101
102} SCIC_PORT_END_POINT_PROPERTIES_T;
103
104/**
105 * @struct SCIC_PORT_PROPERTIES
106 * @brief  This structure defines the properties that can be retrieved
107 *         for each port in the controller.
108 */
109typedef struct SCIC_PORT_PROPERTIES
110{
111   /**
112    * This field specifies the logical index of the port (0 relative).
113    */
114   U32  index;
115
116   /**
117    * This field indicates the local end-point properties for port.
118    */
119   SCIC_PORT_END_POINT_PROPERTIES_T  local;
120
121   /**
122    * This field indicates the remote (attached) end-point properties
123    * for the port.
124    */
125   SCIC_PORT_END_POINT_PROPERTIES_T  remote;
126
127   /**
128    * This field specifies the phys contained inside the port.
129    */
130   U32  phy_mask;
131
132} SCIC_PORT_PROPERTIES_T;
133
134/**
135 * @brief This method simply returns the properties regarding the
136 *        port, such as: physical index, protocols, sas address, etc.
137 *
138 * @param[in]  port this parameter specifies the port for which to retrieve
139 *             the physical index.
140 * @param[out] properties This parameter specifies the properties
141 *             structure into which to copy the requested information.
142 *
143 * @return Indicate if the user specified a valid port.
144 * @retval SCI_SUCCESS This value is returned if the specified port was valid.
145 * @retval SCI_FAILURE_INVALID_PORT This value is returned if the specified port
146 *         is not valid.  When this value is returned, no data is copied to the
147 *         properties output parameter.
148 */
149SCI_STATUS scic_port_get_properties(
150   SCI_PORT_HANDLE_T        port,
151   SCIC_PORT_PROPERTIES_T * properties
152);
153
154/**
155 * @brief This method will add a phy to an existing port.
156 *
157 * @param[in]  port This parameter specifies the port in which to add a new
158 *             phy.
159 * @param[in]  phy This parameter specifies the phy to be added to the port.
160 *
161 * @return Indicate if the phy was successfully added to the port.
162 * @retval SCI_SUCCESS This value is returned if the phy was successfully
163 *         added to the port.
164 * @retval SCI_FAILURE_INVALID_PORT This value is returned if the supplied
165 *         port is not valid.
166 * @retval SCI_FAILURE_INVALID_PHY This value is returned if the supplied
167 *         phy is either invalid or already contained in another port.
168 */
169SCI_STATUS scic_port_add_phy(
170   SCI_PORT_HANDLE_T port,
171   SCI_PHY_HANDLE_T  phy
172);
173
174/**
175 * @brief This method will remove a phy from an existing port.
176 *
177 * @param[in]  port This parameter specifies the port in which to remove a
178 *             phy.
179 * @param[in]  phy This parameter specifies the phy to be removed from the
180 *             port.
181 *
182 * @return Indicate if the phy was successfully removed from the port.
183 * @retval SCI_SUCCESS This value is returned if the phy was successfully
184 *         removed from the port.
185 * @retval SCI_FAILURE_INVALID_PORT This value is returned if the supplied
186 *         port is not valid.
187 * @retval SCI_FAILURE_INVALID_PHY This value is returned if the supplied
188 *         phy is either invalid or
189 *         not contained in the port.
190 */
191SCI_STATUS scic_port_remove_phy(
192   SCI_PORT_HANDLE_T  port,
193   SCI_PHY_HANDLE_T   phy
194);
195
196/**
197 * @brief This method will request the SCI implementation to perform a
198 *        HARD RESET on the SAS Port.  If/When the HARD RESET completes
199 *        the SCI user will be notified via an SCI OS callback indicating
200 *        a direct attached device was found.
201 *
202 * @note The SCI User callback in SCIC_USER_CALLBACKS_T will only be called
203 *       once for each phy in the SAS Port at completion of the hard reset
204 *       sequence.
205 *
206 * @param[in]  port a handle corresponding to the SAS port to be
207 *             hard reset.
208 * @param[in]  reset_timeout This parameter specifies the number of
209 *             milliseconds in which the port reset operation should complete.
210 *
211 * @return Return a status indicating whether the hard reset started
212 *         successfully.
213 * @retval SCI_SUCCESS This value is returned if the hard reset operation
214 *         started successfully.
215 */
216SCI_STATUS scic_port_hard_reset(
217   SCI_PORT_HANDLE_T port,
218   U32               reset_timeout
219);
220
221/**
222 * @brief This API method enables the broadcast change notification from
223 *        underneath hardware.
224 *
225 * @param[in] port The port upon which broadcast change notifications
226 *            (BCN) are to be enabled.
227 *
228 * @return none
229 */
230void scic_port_enable_broadcast_change_notification(
231   SCI_PORT_HANDLE_T  port
232);
233
234#ifdef __cplusplus
235}
236#endif // __cplusplus
237
238#endif // _SCIC_PORT_H_
239
240