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