sys/dev/isci/scil/scic_port.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_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
  65 extern "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
  72 enum 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  */
  88 typedef 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  */
 109 typedef 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  */
 149 SCI_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  */
 169 SCI_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  */
 191 SCI_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  */
 216 SCI_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  */
 230 void 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