10SN/A/*- 29330SN/A * This file is provided under a dual BSD/GPLv2 license. When using or 30SN/A * redistributing this file, you may do so under either license. 40SN/A * 50SN/A * GPL LICENSE SUMMARY 60SN/A * 72362SN/A * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 80SN/A * 92362SN/A * This program is free software; you can redistribute it and/or modify 100SN/A * it under the terms of version 2 of the GNU General Public License as 110SN/A * published by the Free Software Foundation. 120SN/A * 130SN/A * This program is distributed in the hope that it will be useful, but 140SN/A * WITHOUT ANY WARRANTY; without even the implied warranty of 150SN/A * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 160SN/A * General Public License for more details. 170SN/A * 180SN/A * You should have received a copy of the GNU General Public License 190SN/A * along with this program; if not, write to the Free Software 200SN/A * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 212362SN/A * The full GNU General Public License is included in this distribution 222362SN/A * in the file called LICENSE.GPL. 232362SN/A * 240SN/A * BSD LICENSE 250SN/A * 260SN/A * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 270SN/A * All rights reserved. 280SN/A * 290SN/A * Redistribution and use in source and binary forms, with or without 300SN/A * modification, are permitted provided that the following conditions 310SN/A * are met: 320SN/A * 330SN/A * * Redistributions of source code must retain the above copyright 340SN/A * notice, this list of conditions and the following disclaimer. 350SN/A * * Redistributions in binary form must reproduce the above copyright 360SN/A * notice, this list of conditions and the following disclaimer in 370SN/A * the documentation and/or other materials provided with the 380SN/A * distribution. 390SN/A * 400SN/A * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 410SN/A * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 420SN/A * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 431338SN/A * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 440SN/A * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 453787SN/A * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 463787SN/A * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 473787SN/A * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 483787SN/A * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 493787SN/A * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 5012808Schegar * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 5112808Schegar * 523787SN/A * $FreeBSD$ 533787SN/A */ 543787SN/A#ifndef _SCIC_REMOTE_DEVICE_H_ 550SN/A#define _SCIC_REMOTE_DEVICE_H_ 560SN/A 570SN/A/** 580SN/A * @file 590SN/A * 600SN/A * @brief This file contains all of the interface methods that can be called 610SN/A * by an SCIC user on the device object. 620SN/A */ 630SN/A 640SN/A#ifdef __cplusplus 650SN/Aextern "C" { 660SN/A#endif // __cplusplus 670SN/A 680SN/A#include <dev/isci/scil/sci_types.h> 690SN/A#include <dev/isci/scil/sci_status.h> 700SN/A#include <dev/isci/scil/intel_sas.h> 710SN/A 720SN/A 730SN/A/** 740SN/A * @brief 750SN/A */ 760SN/Atypedef enum SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE 770SN/A{ 788238SN/A SCIC_REMOTE_DEVICE_NOT_READY_START_REQUESTED, 790SN/A SCIC_REMOTE_DEVICE_NOT_READY_STOP_REQUESTED, 800SN/A SCIC_REMOTE_DEVICE_NOT_READY_SATA_REQUEST_STARTED, 810SN/A SCIC_REMOTE_DEVICE_NOT_READY_SATA_SDB_ERROR_FIS_RECEIVED, 820SN/A SCIC_REMOTE_DEVICE_NOT_READY_SMP_REQUEST_STARTED, 830SN/A 840SN/A SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE_MAX 850SN/A 860SN/A} SCIC_REMOTE_DEVICE_NOT_READY_REASON_CODE_T; 870SN/A 880SN/A/** 890SN/A * @brief This method simply returns the maximum memory space needed to 900SN/A * store a remote device object. 910SN/A * 920SN/A * @return a positive integer value indicating the size (in bytes) of the 930SN/A * remote device object. 940SN/A */ 950SN/AU32 scic_remote_device_get_object_size( 960SN/A void 970SN/A); 980SN/A 990SN/A/** 1000SN/A * @brief This method will perform the construction common to all 1010SN/A * remote device objects. 1020SN/A * 1030SN/A * @note It isn't necessary to call scic_remote_device_destruct() for 1040SN/A * device objects that have only called this method for construction. 1050SN/A * Once subsequent construction methods have been invoked (e.g. 1060SN/A * scic_remote_device_da_construct()), then destruction should occur. 1070SN/A * @note 1080SN/A * 1090SN/A * @param[in] port This parameter specifies the SAS/SATA Port handle 1100SN/A * corresponding to the port through which this device 1110SN/A * is to be accessed. 1120SN/A * @param[in] remote_device_memory This parameter specifies the memory 1130SN/A * location to be used by the SCIC implementation to store the 1140SN/A * SCIC REMOTE DEVICE. 1150SN/A * @param[out] new_remote_device_handle An opaque remote device handle to 1160SN/A * be used by the SCIC user for all subsequent remote device 1170SN/A * operations. 1180SN/A * 1190SN/A * @return none 1200SN/A */ 1210SN/Avoid scic_remote_device_construct( 1220SN/A SCI_PORT_HANDLE_T port, 1230SN/A void * remote_device_memory, 1240SN/A SCI_REMOTE_DEVICE_HANDLE_T * new_remote_device_handle 1250SN/A); 1260SN/A 1270SN/A/** 1280SN/A * @brief This method will construct a SCIC_REMOTE_DEVICE object for a 1290SN/A * direct attached (da) device. The information (e.g. IAF, Signature 1300SN/A * FIS, etc.) necessary to build the device is known to the SCI Core 1310SN/A * since it is contained in the scic_phy object. 1320SN/A * 1330SN/A * @pre The user must have previously called scic_remote_device_construct() 1340SN/A * 1350SN/A * @note Remote device objects are a limited resource. As such, they 1360SN/A * must be protected. Thus calls to construct and destruct are 1370SN/A * mutually exclusive and non-reentrant. 1380SN/A * 1390SN/A * @param[in] remote_device This parameter specifies the remote device to be 1400SN/A * destructed. 1410SN/A * 1420SN/A * @return Indicate if the remote device was successfully constructed. 1430SN/A * @retval SCI_SUCCESS Returned if the device was successfully constructed. 1440SN/A * @retval SCI_FAILURE_DEVICE_EXISTS Returned if the device has already 1450SN/A * been constructed. If it's an additional phy for the target, then 1460SN/A * call scic_remote_device_da_add_phy(). 1470SN/A * @retval SCI_FAILURE_UNSUPPORTED_PROTOCOL Returned if the supplied 1480SN/A * parameters necessitate creation of a remote device for which 1490SN/A * the protocol is not supported by the underlying controller 1500SN/A * hardware. 1510SN/A * @retval SCI_FAILURE_INSUFFICIENT_RESOURCES This value is returned if 1520SN/A * the core controller associated with the supplied parameters 1530SN/A * is unable to support additional remote devices. 1540SN/A */ 1550SN/ASCI_STATUS scic_remote_device_da_construct( 1560SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device 1570SN/A); 1580SN/A 1590SN/A/** 1600SN/A * @brief This method will construct an SCIC_REMOTE_DEVICE object for an 1610SN/A * expander attached (ea) device from an SMP Discover Response. 1620SN/A * 1630SN/A * @pre The user must have previously called scic_remote_device_construct() 1640SN/A * 1650SN/A * @note Remote device objects are a limited resource. As such, they 1660SN/A * must be protected. Thus calls to construct and destruct are 1670SN/A * mutually exclusive and non-reentrant. 1680SN/A * 1690SN/A * @param[in] remote_device This parameter specifies the remote device to be 1700SN/A * destructed. 1710SN/A * @param[in] discover_response This parameter specifies the SMP 1720SN/A * Discovery Response to be used in device creation. 1730SN/A * 1740SN/A * @return Indicate if the remote device was successfully constructed. 1750SN/A * @retval SCI_SUCCESS Returned if the device was successfully constructed. 1760SN/A * @retval SCI_FAILURE_DEVICE_EXISTS Returned if the device has already 1770SN/A * been constructed. If it's an additional phy for the target, then 1780SN/A * call scic_ea_remote_device_add_phy(). 1790SN/A * @retval SCI_FAILURE_UNSUPPORTED_PROTOCOL Returned if the supplied 1800SN/A * parameters necessitate creation of a remote device for which 1810SN/A * the protocol is not supported by the underlying controller 1820SN/A * hardware. 1830SN/A * @retval SCI_FAILURE_INSUFFICIENT_RESOURCES This value is returned if 1840SN/A * the core controller associated with the supplied parameters 1850SN/A * is unable to support additional remote devices. 1860SN/A */ 1870SN/ASCI_STATUS scic_remote_device_ea_construct( 1880SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device, 1890SN/A SMP_RESPONSE_DISCOVER_T * discover_response 1900SN/A); 1910SN/A 1920SN/A/** 1930SN/A * @brief This method is utilized to free up a core's remote device object. 1940SN/A * 1950SN/A * @note Remote device objects are a limited resource. As such, they 1960SN/A * must be protected. Thus calls to construct and destruct are 1970SN/A * mutually exclusive and non-reentrant. 1980SN/A * 1990SN/A * @param[in] remote_device This parameter specifies the remote device to be 2000SN/A * destructed. 2010SN/A * 2020SN/A * @return The return value shall indicate if the device was successfully 2030SN/A * destructed or if some failure occurred. 2040SN/A * @retval SCI_STATUS This value is returned if the device is successfully 2050SN/A * destructed. 2060SN/A * @retval SCI_FAILURE_INVALID_REMOTE_DEVICE This value is returned if the 2070SN/A * supplied device isn't valid (e.g. it's already been destoryed, 2080SN/A * the handle isn't valid, etc.). 2090SN/A */ 2100SN/ASCI_STATUS scic_remote_device_destruct( 2110SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device 2120SN/A); 21312839Sprr 2140SN/A#if !defined(DISABLE_WIDE_PORTED_TARGETS) 2150SN/A/** 2160SN/A * @brief This method will attempt to set port width for a remote device. 2170SN/A * 2180SN/A * @param[in] remote_device This parameter specifies the remote device 2190SN/A * object for which to set new port width. 2200SN/A * @param[in] new_port_width The new port width to update. 2210SN/A * 2220SN/A * @return Indicate if the device port width was successfully updated. 2230SN/A * @retval SCI_SUCCESS This value is returned when port width update was successful. 2240SN/A * @retval SCI_FAILURE The port width update failed. 2250SN/A */ 2260SN/ASCI_STATUS scic_remote_device_set_port_width( 2270SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device, 2280SN/A U8 new_port_width 2290SN/A); 2300SN/A 2310SN/A/** 2320SN/A * @brief This method retrieve the SCIC's record of a remote device's port width. 2330SN/A * 2340SN/A * @param[in] remote_device This parameter specifies the remote device 2350SN/A * object for which to retrieve the port width value. 2360SN/A * 2370SN/A * @return The SCIC's record of a remote device's port width 2380SN/A */ 2390SN/AU8 scic_remote_device_get_port_width( 2400SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device 2410SN/A); 2420SN/A 2430SN/A#define scic_remote_device_da_add_phy(device, phy) SCI_FAILURE 2440SN/A#define scic_remote_device_ea_add_phy(device, response) SCI_FAILURE 2450SN/A#define scic_remote_device_remove_phy(device) SCI_FAILURE 2460SN/A 2470SN/A#else // !defined(DISABLE_WIDE_PORTED_TARGETS) 2480SN/A 2490SN/A#define scic_remote_device_set_port_width(device, port_width) SCI_FAILURE 2500SN/A#define scic_remote_device_get_port_width(device) (1) 2510SN/A 2520SN/A#define scic_remote_device_da_add_phy(device, phy) SCI_FAILURE 2530SN/A#define scic_remote_device_ea_add_phy(device, response) SCI_FAILURE 2540SN/A#define scic_remote_device_remove_phy(device) SCI_FAILURE 2550SN/A 2560SN/A#endif // !defined(DISABLE_WIDE_PORTED_TARGETS) 2570SN/A 2580SN/A/** 2590SN/A * @brief This method will start the supplied remote device. This method 2600SN/A * enables normal IO requests to flow through to the remote device. 2610SN/A * 2620SN/A * @param[in] remote_device This parameter specifies the device to be 2630SN/A * started. 2640SN/A * @param[in] timeout This parameter specifies the number of milliseconds 2650SN/A * in which the start operation should complete. 2660SN/A * 2670SN/A * @return An indication of whether the device was successfully started. 2680SN/A * @retval SCI_SUCCESS This value is returned if the device was successfully 2690SN/A * started. 2700SN/A * @retval SCI_FAILURE_INVALID_PHY This value is returned if the user attempts 2710SN/A * to start the device when there have been no phys added to it. 2720SN/A */ 2730SN/ASCI_STATUS scic_remote_device_start( 2740SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device, 2750SN/A U32 timeout 2760SN/A); 2770SN/A 2780SN/A/** 2790SN/A * @brief This method will stop both transmission and reception of link 2800SN/A * activity for the supplied remote device. This method disables 2810SN/A * normal IO requests from flowing through to the remote device. 2820SN/A * 2830SN/A * @param[in] remote_device This parameter specifies the device to be 2840SN/A * stopped. 2850SN/A * @param[in] timeout This parameter specifies the number of milliseconds 2860SN/A * in which the stop operation should complete. 2870SN/A * 2880SN/A * @return An indication of whether the device was successfully stopped. 2890SN/A * @retval SCI_SUCCESS This value is returned if the transmission and reception 2900SN/A * for the device was successfully stopped. 2910SN/A */ 2920SN/ASCI_STATUS scic_remote_device_stop( 2930SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device, 2940SN/A U32 timeout 2950SN/A); 2960SN/A 2971338SN/A/** 2981338SN/A * @brief This method will reset the device making it ready for operation. 2991338SN/A * This method must be called anytime the device is reset either 3000SN/A * through a SMP phy control or a port hard reset request. 3010SN/A * 3020SN/A * @note This method does not actually cause the device hardware to be reset. 3030SN/A * This method resets the software object so that it will be operational 3040SN/A * after a device hardware reset completes. 3050SN/A * 3060SN/A * @param[in] remote_device This parameter specifies the device to be 3070SN/A * reset. 3080SN/A * 3090SN/A * @return An indication of whether the device reset was accepted. 3100SN/A * @retval SCI_SUCCESS This value is returned if the device reset is started. 3110SN/A */ 3120SN/ASCI_STATUS scic_remote_device_reset( 3130SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device 3140SN/A); 3150SN/A 3160SN/A/** 3170SN/A * @brief This method informs the device object that the reset operation is 3180SN/A * complete and the device can resume operation again. 3190SN/A * 3200SN/A * @param[in] remote_device This parameter specifies the device which is to 3210SN/A * be informed of the reset complete operation. 3220SN/A * 3230SN/A * @return An indication that the device is resuming operation. 3240SN/A * @retval SCI_SUCCESS the device is resuming operation. 3250SN/A */ 3260SN/ASCI_STATUS scic_remote_device_reset_complete( 3270SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device 3280SN/A); 3290SN/A 3300SN/A/** 3310SN/A * @brief This method returns the suggested target reset timeout. SAS and 3320SN/A * SATA devices have different timeout values in milliseconds for 3330SN/A * target reset operations. 3340SN/A * 3350SN/A * @param[in] remote_device This parameter specifies the device which is to 3360SN/A * be informed of the reset complete operation. 3370SN/A * 3380SN/A * @return The suggested reset timeout value for the specified target device 3390SN/A * in milliseconds. 3400SN/A */ 3410SN/AU32 scic_remote_device_get_suggested_reset_timeout( 3420SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device 3430SN/A); 3440SN/A 3450SN/A/** 3460SN/A * @brief This method will set the maximum link speed to be utilized 3470SN/A * when connections are established for the supplied remote device. 3480SN/A * 3490SN/A * @pre The remote device must previously have been stopped for this 3500SN/A * call to succeed. 3510SN/A * 3520SN/A * @param[in] remote_device This parameter specifies the device for which 3530SN/A * to set the maximum connection rate. 3540SN/A * @param[in] connection_rate This parameter specifies the maximum link rate 3550SN/A * to be utilized for all connections to the supplied remote 3560SN/A * device. 3573370SN/A * 3580SN/A * @return An indication as to whether the connection rate was successfully 3590SN/A * updated. 3600SN/A * @retval SCI_SUCCESS This value is returned if the connection rate was 3610SN/A * successfully updated. 3620SN/A * @retval SCI_FAILURE_INVALID_STATE This value is returned if the remote 3630SN/A * device is not in a stopped state or some other state that allows 3640SN/A * for a maximum connection rate change. 3650SN/A */ 3660SN/ASCI_STATUS scic_remote_device_set_max_connection_rate( 3670SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device, 3680SN/A SCI_SAS_LINK_RATE connection_rate 3690SN/A); 3700SN/A 3710SN/A/** 3720SN/A * @brief This method simply returns the link rate at which communications 3730SN/A * to the remote device occur. 3740SN/A * 3750SN/A * @param[in] remote_device This parameter specifies the device for which 3760SN/A * to get the connection rate. 3770SN/A * 3780SN/A * @return Return the link rate at which we transfer for the supplied 3790SN/A * remote device. 3800SN/A */ 3810SN/ASCI_SAS_LINK_RATE scic_remote_device_get_connection_rate( 3820SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device 3830SN/A); 3840SN/A 3850SN/A/** 3860SN/A * @brief This method will indicate which protocols are supported by this 3870SN/A * remote device. 3880SN/A * 3890SN/A * @param[in] remote_device This parameter specifies the device for which 3900SN/A * to return the protocol. 3910SN/A * @param[out] protocols This parameter specifies the output values, from 3920SN/A * the remote device object, which indicate the protocols 3933370SN/A * supported by the supplied remote_device. 3940SN/A * 3950SN/A * @return The type of protocols supported by this device. The values are 3960SN/A * returned as part of a bit mask in order to allow for multi-protocol 3970SN/A * support. 3980SN/A */ 3990SN/Avoid scic_remote_device_get_protocols( 4000SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device, 4010SN/A SMP_DISCOVER_RESPONSE_PROTOCOLS_T * protocols 4020SN/A); 4030SN/A 4040SN/A/** 4050SN/A * @brief This method will indicate the SAS address for the remote device. 4060SN/A * 4070SN/A * @param[in] remote_device This parameter specifies the device for which 4080SN/A * to return the SAS address. 4090SN/A * @param[out] sas_address This parameter specifies a pointer to a SAS 4100SN/A * address structure into which the core will copy the SAS 4110SN/A * address for the remote device. 4120SN/A * 4130SN/A * @return none 4140SN/A */ 4150SN/Avoid scic_remote_device_get_sas_address( 4160SN/A SCI_REMOTE_DEVICE_HANDLE_T remote_device, 4170SN/A SCI_SAS_ADDRESS_T * sas_address 4180SN/A); 4193370SN/A 4200SN/A#if !defined(DISABLE_ATAPI) 4210SN/A/** 4220SN/A * This method first decide whether a device is a stp target, then 4230SN/A * decode the signature fis of a DA STP device to tell whether it 4240SN/A * is a standard end disk or an ATAPI device. 4250SN/A * 4260SN/A * @param[in] this_device The device whose type is to be decided. 4270SN/A * 4280SN/A * @return BOOL Indicate a device is ATAPI device or not. 4290SN/A */ 4300SN/ABOOL scic_remote_device_is_atapi( 4310SN/A SCI_REMOTE_DEVICE_HANDLE_T device_handle 4320SN/A); 4330SN/A#else // !defined(DISABLE_ATAPI) 4340SN/A#define scic_remote_device_is_atapi(device_handle) FALSE 4350SN/A#endif // !defined(DISABLE_ATAPI) 4360SN/A 4370SN/A#ifdef __cplusplus 4380SN/A} 4390SN/A#endif // __cplusplus 4400SN/A 4410SN/A#endif // _SCIC_REMOTE_DEVICE_H_ 4420SN/A 4430SN/A