sys/dev/isci/scil/scic_phy.h

   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_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 recieved 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