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_LIBRARY_H_ 55 #define _SCIC_LIBRARY_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 the library object. The library is the 62 * container of all other objects being managed (i.e. controllers, 63 * target devices, sas ports, etc.). 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 74 /** 75 * @enum _SCIC_LIBRARY_IO_MODE 76 * @brief This enumeration depicts the different IO modes in which the SCI 77 * library and it's controllers can operate. 78 */ 79 typedef enum _SCIC_LIBRARY_IO_MODE 80 { 81 /** 82 * In this mode the SCI library will operate in a polling mode for 83 * operations. In other words, the library will not return from a 84 * send io method until the completion for the IO has been received. 85 */ 86 SCIC_IO_MODE_POLLING, 87 88 /** 89 * In this mode the SCI library returns after committing the IO request 90 * to the controller hardware. Completion of the request will occur 91 * asynchronously. 92 */ 93 SCIC_IO_MODE_ASYNCHRONOUS 94 95 } SCIC_LIBRARY_IO_MODE; 96 97 98 struct sci_pci_common_header; 99 100 /** 101 * @brief This method will contsruct the core library based on the supplied 102 * parameter information. By default, libraries are considered 103 * "ready" as soon as they are constructed. 104 * 105 * @param[in] library_memory a pointer to the memory at which the 106 * library object is located. 107 * @param[in] max_controller_count the maximum number of controllers that 108 * this library can manage. 109 * 110 * @return An opaque library handle to be used by the SCI user for all 111 * subsequent library operations. 112 */ 113 SCI_LIBRARY_HANDLE_T scic_library_construct( 114 void * library_memory, 115 U8 max_controller_count 116 ); 117 118 /** 119 * This method sets the PCI header information required for proper 120 * controller object creation/allocation. 121 * 122 * @param[in] library the handle to the library object for which to allocate 123 * a controller. 124 * @param[in] pci_header a pointer to the pci header data for the pci 125 * device for which this library is being created. 126 * 127 * @return none 128 */ 129 void scic_library_set_pci_info( 130 SCI_LIBRARY_HANDLE_T library, 131 struct sci_pci_common_header * pci_header 132 ); 133 134 /** 135 * @brief This method returns the size of the core library object. 136 * 137 * @param[in] max_controller_count the maximum number of controllers that 138 * this library can manage. 139 * 140 * @return a positive integer value indicating the size (in bytes) of the 141 * library object. 142 */ 143 U32 scic_library_get_object_size( 144 U8 max_controller_count 145 ); 146 147 /** 148 * 149 * 150 */ 151 U8 scic_library_get_pci_device_controller_count( 152 SCI_LIBRARY_HANDLE_T library 153 ); 154 155 /** 156 * @brief This method will allocate the next available core controller object 157 * that can be managed by this core library. 158 * 159 * @param[in] library the handle to the library object for which to allocate 160 * a controller. 161 * @param[out] new_controller This parameter specifies a pointer to the 162 * controller handle that was added to the library. 163 164 * @return Indicate if the controller was successfully allocated or if iti 165 * failed in some way. 166 * @retval SCI_SUCCESS if the controller was successfully allocated. 167 * @retval SCI_FAILURE_INSUFFICIENT_RESOURCES if the library has no more 168 * available controller objects to allocate. 169 */ 170 SCI_STATUS scic_library_allocate_controller( 171 SCI_LIBRARY_HANDLE_T library, 172 SCI_CONTROLLER_HANDLE_T * new_controller 173 ); 174 175 /** 176 * @brief This method will attempt to free the supplied controller to the 177 * library. 178 * 179 * @param[in] library the handle to the library object for which to free 180 * a controller. 181 * @param[in] controller the handle to the controller object to be freed 182 * from the library. 183 * 184 * @return Indicate if the controller was successfully freed or if it failed 185 * in some way. 186 * @retval SCI_SUCCESS if the controller was successfully freed. 187 * @retval SCI_FAILURE_CONTROLLER_NOT_FOUND if the supplied controller is 188 * not managed by the supplied library. 189 */ 190 SCI_STATUS scic_library_free_controller( 191 SCI_LIBRARY_HANDLE_T library, 192 SCI_CONTROLLER_HANDLE_T controller 193 ); 194 195 /** 196 * @brief This method returns the maximum size (in bytes) that an individual 197 * SGL element can address using this library. 198 * 199 * @note SGL size is restricted to the lowest common denominator across all 200 * controllers managed by the library. 201 * @todo Does the byte count have to be DWORD aligned? 202 * 203 * @param[in] library the handle to the library object for which to 204 * determine the maximum SGL size. 205 * 206 * @return Return the maximum size (in bytes) for an SGE for any controller 207 * managed by this library. 208 */ 209 U32 scic_library_get_max_sge_size( 210 SCI_LIBRARY_HANDLE_T library 211 ); 212 213 /** 214 * @brief This method returns the maximum number of SGL elements for a 215 * single IO request using this library. 216 * 217 * @note SGE count is restricted to the lowest common denominator across all 218 * controllers managed by the library. 219 * 220 * @param[in] library the handle to the library object for which to 221 * determine the maximum number of SGEs per IO request. 222 * 223 * @return Return the maximum number of SGEs for an IO request for any 224 * controller in this library. 225 */ 226 U32 scic_library_get_max_sge_count( 227 SCI_LIBRARY_HANDLE_T library 228 ); 229 230 /** 231 * @brief This method returns the maximum length for any IO request that 232 * can be handled by the underlying controllers 233 * 234 * @note IO length is restricted to the lowest common denominator across all 235 * controllers managed by the library. 236 * 237 * @param[in] library the handle to the library object for which to 238 * determine the maximum length for all IO requests. 239 * 240 * @return Return the maximum length for all IO requests for any 241 * controller in this library. 242 */ 243 U32 scic_library_get_max_io_length( 244 SCI_LIBRARY_HANDLE_T library 245 ); 246 247 /** 248 * @brief This method returns the minimum number of timers needed. If the 249 * user supplies timers less then the number specified via this 250 * call, then the user runs the risk of improper operation. 251 * 252 * @return This method returns a value representing the minimum number of 253 * timers required by this framework implementation 254 */ 255 U16 scic_library_get_min_timer_count( 256 void 257 ); 258 259 /** 260 * @brief This method returns the maximum number of timers that could 261 * be ever be in use by this component at a given time. 262 * 263 * @return This method returns a value representing the minimum number of 264 * timers required by this framework implementation 265 */ 266 U16 scic_library_get_max_timer_count( 267 void 268 ); 269 270 #ifdef __cplusplus 271 } 272 #endif // __cplusplus 273 274 #endif // _SCIC_LIBRARY_H_ 275 276