xref: /freebsd/sys/dev/isci/scil/scic_library.h (revision cc426dd31990b8b50b210efc450e404596548ca1)
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