1 /*- 2 * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0 3 * 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. 6 * 7 * GPL LICENSE SUMMARY 8 * 9 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 10 * 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. 14 * 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. 19 * 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. 25 * 26 * BSD LICENSE 27 * 28 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 29 * All rights reserved. 30 * 31 * Redistribution and use in source and binary forms, with or without 32 * modification, are permitted provided that the following conditions 33 * are met: 34 * 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 40 * distribution. 41 * 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. 53 */ 54 #ifndef _SCIC_PHY_H_ 55 #define _SCIC_PHY_H_ 56 57 /** 58 * @file 59 * 60 * @brief This file contains all of the interface methods that can be called 61 * by an SCIC user on a phy (SAS or SATA) object. 62 */ 63 64 #ifdef __cplusplus 65 extern "C" { 66 #endif // __cplusplus 67 68 #include <dev/isci/scil/sci_types.h> 69 #include <dev/isci/scil/sci_status.h> 70 71 #include <dev/isci/scil/intel_sata.h> 72 #include <dev/isci/scil/intel_sas.h> 73 74 75 /** 76 * @struct SCIC_PHY_PROPERTIES 77 * @brief This structure defines the properties common to all phys 78 * that can be retrieved. 79 */ 80 typedef struct SCIC_PHY_PROPERTIES 81 { 82 /** 83 * This field specifies the port that currently contains the 84 * supplied phy. This field may be set to SCI_INVALID_HANDLE 85 * if the phy is not currently contained in a port. 86 */ 87 SCI_PORT_HANDLE_T owning_port; 88 89 /** 90 * This field specifies the maximum link rate for which this phy 91 * will negotiate. 92 */ 93 SCI_SAS_LINK_RATE max_link_rate; 94 95 /** 96 * This field specifies the link rate at which the phy is 97 * currently operating. 98 */ 99 SCI_SAS_LINK_RATE negotiated_link_rate; 100 101 /** 102 * This field indicates the identify address frame that will be 103 * transmitted to the connected phy. 104 */ 105 SCI_SAS_IDENTIFY_ADDRESS_FRAME_T transmit_iaf; 106 107 /** 108 * This field specifies the index of the phy in relation to other 109 * phys within the controller. This index is zero relative. 110 */ 111 U8 index; 112 113 } SCIC_PHY_PROPERTIES_T; 114 115 /** 116 * @struct SCIC_SAS_PHY_PROPERTIES 117 * @brief This structure defines the properties, specific to a 118 * SAS phy, that can be retrieved. 119 */ 120 typedef struct SCIC_SAS_PHY_PROPERTIES 121 { 122 /** 123 * This field delineates the Identify Address Frame received 124 * from the remote end point. 125 */ 126 SCI_SAS_IDENTIFY_ADDRESS_FRAME_T received_iaf; 127 128 /** 129 * This field delineates the Phy capabilities structure received 130 * from the remote end point. 131 */ 132 SAS_CAPABILITIES_T received_capabilities; 133 134 } SCIC_SAS_PHY_PROPERTIES_T; 135 136 /** 137 * @struct SCIC_SATA_PHY_PROPERTIES 138 * @brief This structure defines the properties, specific to a 139 * SATA phy, that can be retrieved. 140 */ 141 typedef struct SCIC_SATA_PHY_PROPERTIES 142 { 143 /** 144 * This field delineates the signature FIS received from the 145 * attached target. 146 */ 147 SATA_FIS_REG_D2H_T signature_fis; 148 149 /** 150 * This field specifies to the user if a port selector is connected 151 * on the specified phy. 152 */ 153 BOOL is_port_selector_present; 154 155 } SCIC_SATA_PHY_PROPERTIES_T; 156 157 /** 158 * @enum SCIC_PHY_COUNTER_ID 159 * @brief This enumeration depicts the various pieces of optional 160 * information that can be retrieved for a specific phy. 161 */ 162 typedef enum SCIC_PHY_COUNTER_ID 163 { 164 /** 165 * This PHY information field tracks the number of frames received. 166 */ 167 SCIC_PHY_COUNTER_RECEIVED_FRAME, 168 169 /** 170 * This PHY information field tracks the number of frames transmitted. 171 */ 172 SCIC_PHY_COUNTER_TRANSMITTED_FRAME, 173 174 /** 175 * This PHY information field tracks the number of DWORDs received. 176 */ 177 SCIC_PHY_COUNTER_RECEIVED_FRAME_DWORD, 178 179 /** 180 * This PHY information field tracks the number of DWORDs transmitted. 181 */ 182 SCIC_PHY_COUNTER_TRANSMITTED_FRAME_DWORD, 183 184 /** 185 * This PHY information field tracks the number of times DWORD 186 * synchronization was lost. 187 */ 188 SCIC_PHY_COUNTER_LOSS_OF_SYNC_ERROR, 189 190 /** 191 * This PHY information field tracks the number of received DWORDs with 192 * running disparity errors. 193 */ 194 SCIC_PHY_COUNTER_RECEIVED_DISPARITY_ERROR, 195 196 /** 197 * This PHY information field tracks the number of received frames with a 198 * CRC error (not including short or truncated frames). 199 */ 200 SCIC_PHY_COUNTER_RECEIVED_FRAME_CRC_ERROR, 201 202 /** 203 * This PHY information field tracks the number of DONE (ACK/NAK TIMEOUT) 204 * primitives received. 205 */ 206 SCIC_PHY_COUNTER_RECEIVED_DONE_ACK_NAK_TIMEOUT, 207 208 /** 209 * This PHY information field tracks the number of DONE (ACK/NAK TIMEOUT) 210 * primitives transmitted. 211 */ 212 SCIC_PHY_COUNTER_TRANSMITTED_DONE_ACK_NAK_TIMEOUT, 213 214 /** 215 * This PHY information field tracks the number of times the inactivity 216 * timer for connections on the phy has been utilized. 217 */ 218 SCIC_PHY_COUNTER_INACTIVITY_TIMER_EXPIRED, 219 220 /** 221 * This PHY information field tracks the number of DONE (CREDIT TIMEOUT) 222 * primitives received. 223 */ 224 SCIC_PHY_COUNTER_RECEIVED_DONE_CREDIT_TIMEOUT, 225 226 /** 227 * This PHY information field tracks the number of DONE (CREDIT TIMEOUT) 228 * primitives transmitted. 229 */ 230 SCIC_PHY_COUNTER_TRANSMITTED_DONE_CREDIT_TIMEOUT, 231 232 /** 233 * This PHY information field tracks the number of CREDIT BLOCKED 234 * primitives received. 235 * @note Depending on remote device implementation, credit blocks 236 * may occur regularly. 237 */ 238 SCIC_PHY_COUNTER_RECEIVED_CREDIT_BLOCKED, 239 240 /** 241 * This PHY information field contains the number of short frames 242 * received. A short frame is simply a frame smaller then what is 243 * allowed by either the SAS or SATA specification. 244 */ 245 SCIC_PHY_COUNTER_RECEIVED_SHORT_FRAME, 246 247 /** 248 * This PHY information field contains the number of frames received after 249 * credit has been exhausted. 250 */ 251 SCIC_PHY_COUNTER_RECEIVED_FRAME_WITHOUT_CREDIT, 252 253 /** 254 * This PHY information field contains the number of frames received after 255 * a DONE has been received. 256 */ 257 SCIC_PHY_COUNTER_RECEIVED_FRAME_AFTER_DONE, 258 259 /** 260 * This PHY information field contains the number of times the phy 261 * failed to achieve DWORD synchronization during speed negotiation. 262 */ 263 SCIC_PHY_COUNTER_SN_DWORD_SYNC_ERROR 264 } SCIC_PHY_COUNTER_ID_T; 265 266 /** 267 * @brief This method will enable the user to retrieve information 268 * common to all phys, such as: the negotiated link rate, 269 * the phy id, etc. 270 * 271 * @param[in] phy This parameter specifies the phy for which to retrieve 272 * the properties. 273 * @param[out] properties This parameter specifies the properties 274 * structure into which to copy the requested information. 275 * 276 * @return Indicate if the user specified a valid phy. 277 * @retval SCI_SUCCESS This value is returned if the specified phy was valid. 278 * @retval SCI_FAILURE_INVALID_PHY This value is returned if the specified phy 279 * is not valid. When this value is returned, no data is copied to the 280 * properties output parameter. 281 */ 282 SCI_STATUS scic_phy_get_properties( 283 SCI_PHY_HANDLE_T phy, 284 SCIC_PHY_PROPERTIES_T * properties 285 ); 286 287 /** 288 * @brief This method will enable the user to retrieve information 289 * specific to a SAS phy, such as: the received identify 290 * address frame, received phy capabilities, etc. 291 * 292 * @param[in] phy this parameter specifies the phy for which to 293 * retrieve properties. 294 * @param[out] properties This parameter specifies the properties 295 * structure into which to copy the requested information. 296 * 297 * @return This method returns an indication as to whether the SAS 298 * phy properties were successfully retrieved. 299 * @retval SCI_SUCCESS This value is returned if the SAS properties 300 * are successfully retrieved. 301 * @retval SCI_FAILURE This value is returned if the SAS properties 302 * are not successfully retrieved (e.g. It's not a SAS Phy). 303 */ 304 SCI_STATUS scic_sas_phy_get_properties( 305 SCI_PHY_HANDLE_T phy, 306 SCIC_SAS_PHY_PROPERTIES_T * properties 307 ); 308 309 /** 310 * @brief This method will enable the user to retrieve information 311 * specific to a SATA phy, such as: the received signature 312 * FIS, if a port selector is present, etc. 313 * 314 * @param[in] phy this parameter specifies the phy for which to 315 * retrieve properties. 316 * @param[out] properties This parameter specifies the properties 317 * structure into which to copy the requested information. 318 * 319 * @return This method returns an indication as to whether the SATA 320 * phy properties were successfully retrieved. 321 * @retval SCI_SUCCESS This value is returned if the SATA properties 322 * are successfully retrieved. 323 * @retval SCI_FAILURE This value is returned if the SATA properties 324 * are not successfully retrieved (e.g. It's not a SATA Phy). 325 */ 326 SCI_STATUS scic_sata_phy_get_properties( 327 SCI_PHY_HANDLE_T phy, 328 SCIC_SATA_PHY_PROPERTIES_T * properties 329 ); 330 331 /** 332 * @brief This method allows the SCIC user to instruct the SCIC 333 * implementation to send the SATA port selection signal. 334 * 335 * @param[in] phy this parameter specifies the phy for which to send 336 * the port selection signal. 337 * 338 * @return An indication of whether the port selection signal was 339 * successfully executed. 340 * @retval SCI_SUCCESS This value is returned if the port selection signal 341 * was successfully transmitted. 342 */ 343 SCI_STATUS scic_sata_phy_send_port_selection_signal( 344 SCI_PHY_HANDLE_T phy 345 ); 346 347 /** 348 * @brief This method requests the SCI implementation to begin tracking 349 * information specified by the supplied parameters. 350 * 351 * @param[in] phy this parameter specifies the phy for which to enable 352 * the information type. 353 * @param[in] counter_id this parameter specifies the information 354 * type to be enabled. 355 * 356 * @return Indicate if enablement of the information type was successful. 357 * @retval SCI_SUCCESS This value is returned if the information type was 358 * successfully enabled. 359 * @retval SCI_FAILURE_UNSUPPORTED_INFORMATION_FIELD This value is returned 360 * if the supplied information type is not supported. 361 */ 362 SCI_STATUS scic_phy_enable_counter( 363 SCI_PHY_HANDLE_T phy, 364 SCIC_PHY_COUNTER_ID_T counter_id 365 ); 366 367 /** 368 * @brief This method requests the SCI implementation to stop tracking 369 * information specified by the supplied parameters. 370 * 371 * @param[in] phy this parameter specifies the phy for which to disable 372 * the information type. 373 * @param[in] counter_id this parameter specifies the information 374 * type to be disabled. 375 * 376 * @return Indicate if disablement of the information type was successful. 377 * @retval SCI_SUCCESS This value is returned if the information type was 378 * successfully disabled. 379 * @retval SCI_FAILURE_UNSUPPORTED_INFORMATION_FIELD This value is returned 380 * if the supplied information type is not supported. 381 */ 382 SCI_STATUS scic_phy_disable_counter( 383 SCI_PHY_HANDLE_T phy, 384 SCIC_PHY_COUNTER_ID_T counter_id 385 ); 386 387 /** 388 * @brief This method requests the SCI implementation to retrieve 389 * tracking information specified by the supplied parameters. 390 * 391 * @param[in] phy this parameter specifies the phy for which to retrieve 392 * the information type. 393 * @param[in] counter_id this parameter specifies the information 394 * type to be retrieved. 395 * @param[out] data this parameter is a 32-bit pointer to a location 396 * where the data being retrieved is to be placed. 397 * 398 * @return Indicate if retrieval of the information type was successful. 399 * @retval SCI_SUCCESS This value is returned if the information type was 400 * successfully retrieved. 401 * @retval SCI_FAILURE_UNSUPPORTED_INFORMATION_FIELD This value is returned 402 * if the supplied information type is not supported. 403 */ 404 SCI_STATUS scic_phy_get_counter( 405 SCI_PHY_HANDLE_T phy, 406 SCIC_PHY_COUNTER_ID_T counter_id, 407 U32 * data 408 ); 409 410 /** 411 * @brief This method requests the SCI implementation to clear (reset) 412 * tracking information specified by the supplied parameters. 413 * 414 * @param[in] phy this parameter specifies the phy for which to clear 415 * the information type. 416 * @param[in] counter_id this parameter specifies the information 417 * type to be cleared. 418 * 419 * @return Indicate if clearing of the information type was successful. 420 * @retval SCI_SUCCESS This value is returned if the information type was 421 * successfully cleared. 422 * @retval SCI_FAILURE_UNSUPPORTED_INFORMATION_FIELD This value is returned 423 * if the supplied information type is not supported. 424 */ 425 SCI_STATUS scic_phy_clear_counter( 426 SCI_PHY_HANDLE_T phy, 427 SCIC_PHY_COUNTER_ID_T counter_id 428 ); 429 430 /** 431 * @brief This method will attempt to stop the phy object. 432 * 433 * @param[in] this_phy 434 * 435 * @return SCI_STATUS 436 * @retval SCI_SUCCESS if the phy is going to stop 437 * SCI_INVALID_STATE if the phy is not in a valid state 438 * to stop 439 */ 440 SCI_STATUS scic_phy_stop( 441 SCI_PHY_HANDLE_T phy 442 ); 443 444 /** 445 * @brief This method will attempt to start the phy object. This 446 * request is only valid when the phy is in the stopped 447 * state 448 * 449 * @param[in] this_phy 450 * 451 * @return SCI_STATUS 452 */ 453 SCI_STATUS scic_phy_start( 454 SCI_PHY_HANDLE_T phy 455 ); 456 457 #ifdef __cplusplus 458 } 459 #endif // __cplusplus 460 461 #endif // _SCIC_PHY_H_ 462 463