2 * SPDX-License-Identifier: BSD-2-Clause OR GPL-2.0
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.
9 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
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.
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.
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.
28 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
29 * All rights reserved.
31 * Redistribution and use in source and binary forms, with or without
32 * modification, are permitted provided that the following conditions
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
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.
56 #ifndef _SCIF_LIBRARY_H_
57 #define _SCIF_LIBRARY_H_
62 * @brief This file contains all of the interface methods that can be called
63 * by an SCI Framework user on the library object. The library is
64 * the container of all other objects being managed (i.e. controllers,
65 * target devices, sas ports, etc.) by SCIF.
72 #include <dev/isci/scil/sci_types.h>
73 #include <dev/isci/scil/sci_status.h>
77 * @brief This method will contsruct the SCI framework library based on the
78 * supplied parameter information. By default, libraries are
79 * considered "ready" as soon as they are constructed.
81 * @param[in] library_memory_p a pointer to the memory at which the
82 * library object is located.
83 * @param[in] max_controller_count the maximum number of controllers that
84 * this library can manage.
86 * @return An opaque library handle to be used by the SCI user for all
87 * subsequent library operations.
89 SCI_LIBRARY_HANDLE_T scif_library_construct(
90 void * library_memory_p,
91 U8 max_controller_count
95 * @brief This method returns the size of the framework library object. The
96 * size of the framework library object includes the associated core
99 * @param[in] max_controller_count the maximum number of controllers that
100 * this library can manage.
102 * @return a positive integer value indicating the size (in bytes) of the
105 U32 scif_library_get_object_size(
106 U8 max_controller_count
110 * @brief This method will allocate the next available framework controller
111 * object that can be managed by this framework library.
113 * @see For additional information please refer to:
114 * scic_library_allocate_controller()
116 * @param[in] library the handle to the library object for which to allocate
118 * @param[out] new_controller_p This parameter specifies a pointer to the
119 * controller handle that was added to the library.
121 * @return Indicate if the controller was successfully allocated or if iti
122 * failed in some way.
123 * @retval SCI_SUCCESS if the controller was successfully allocated.
124 * @retval SCI_FAILURE_INSUFFICIENT_RESOURCES if the library has no more
125 * available controller objects to allocate.
127 SCI_STATUS scif_library_allocate_controller(
128 SCI_LIBRARY_HANDLE_T library,
129 SCI_CONTROLLER_HANDLE_T * new_controller_p
133 * @brief This method will attempt to free the supplied controller to the
136 * @param[in] library the handle to the library object for which to free
138 * @param[in] controller the handle to the controller object to be freed
141 * @return Indicate if the controller was successfully freed or if it failed
143 * @retval SCI_SUCCESS if the controller was successfully freed.
144 * @retval SCI_FAILURE_CONTROLLER_NOT_FOUND if the supplied controller is
145 * not managed by the supplied library.
147 SCI_STATUS scif_library_free_controller(
148 SCI_LIBRARY_HANDLE_T library,
149 SCI_CONTROLLER_HANDLE_T controller
154 * @brief This method returns the SCI Core library handle
155 * associated with this library.
157 * @param[in] scif_library the handle to the library
158 * object for which to retrieve the core specific
161 * @return Return the SCI core library handle associated with
162 * the supplied framework library.
164 SCI_LIBRARY_HANDLE_T scif_library_get_scic_handle(
165 SCI_LIBRARY_HANDLE_T scif_library
170 * @brief This method returns the minimum number of timers needed. If the
171 * user supplies timers less then the number specified via this
172 * call, then the user runs the risk of improper operation. This
173 * call includes the minimum number of timers needed by the core.
175 * @return This method returns a value representing the minimum number of
176 * timers required by this framework implementation
178 U16 scif_library_get_min_timer_count(
183 * @brief This method returns the maximum number of timers that could
184 * be ever be in use by this component at a given time.
186 * @return This method returns a value representing the minimum number of
187 * timers required by this framework implementation
189 U16 scif_library_get_max_timer_count(
195 #endif // __cplusplus
197 #endif // _SCIF_LIBRARY_H_