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