sci_base_library.h revision 296373
1238384Sjkim/*- 2280297Sjkim * This file is provided under a dual BSD/GPLv2 license. When using or 3280297Sjkim * redistributing this file, you may do so under either license. 4238384Sjkim * 5238384Sjkim * GPL LICENSE SUMMARY 6238384Sjkim * 7238384Sjkim * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8238384Sjkim * 9238384Sjkim * This program is free software; you can redistribute it and/or modify 10238384Sjkim * it under the terms of version 2 of the GNU General Public License as 11238384Sjkim * published by the Free Software Foundation. 12238384Sjkim * 13238384Sjkim * This program is distributed in the hope that it will be useful, but 14280297Sjkim * WITHOUT ANY WARRANTY; without even the implied warranty of 15238384Sjkim * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16238384Sjkim * General Public License for more details. 17238384Sjkim * 18238384Sjkim * You should have received a copy of the GNU General Public License 19238384Sjkim * along with this program; if not, write to the Free Software 20238384Sjkim * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21238384Sjkim * The full GNU General Public License is included in this distribution 22238384Sjkim * in the file called LICENSE.GPL. 23238384Sjkim * 24238384Sjkim * BSD LICENSE 25238384Sjkim * 26238384Sjkim * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27238384Sjkim * All rights reserved. 28238384Sjkim * 29238384Sjkim * Redistribution and use in source and binary forms, with or without 30238384Sjkim * modification, are permitted provided that the following conditions 31238384Sjkim * are met: 32238384Sjkim * 33238384Sjkim * * Redistributions of source code must retain the above copyright 34238384Sjkim * notice, this list of conditions and the following disclaimer. 35238384Sjkim * * Redistributions in binary form must reproduce the above copyright 36238384Sjkim * notice, this list of conditions and the following disclaimer in 37238384Sjkim * the documentation and/or other materials provided with the 38238384Sjkim * distribution. 39238384Sjkim * 40238384Sjkim * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41238384Sjkim * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42238384Sjkim * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43238384Sjkim * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44238384Sjkim * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45238384Sjkim * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46238384Sjkim * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47238384Sjkim * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48238384Sjkim * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49238384Sjkim * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50238384Sjkim * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51238384Sjkim * 52238384Sjkim * $FreeBSD: releng/10.3/sys/dev/isci/scil/sci_base_library.h 231136 2012-02-07 17:43:58Z jimharris $ 53238384Sjkim */ 54238384Sjkim#ifndef _SCI_BASE_LIBRARY_H_ 55238384Sjkim#define _SCI_BASE_LIBRARY_H_ 56238384Sjkim 57238384Sjkim/** 58238384Sjkim * @file 59238384Sjkim * 60238384Sjkim * @brief This file contains the protected interface structures, constants 61238384Sjkim * and interface methods for the SCI_BASE_LIBRARY object. 62238384Sjkim * 63238384Sjkim */ 64238384Sjkim 65238384Sjkim#ifdef __cplusplus 66280297Sjkimextern "C" { 67280297Sjkim#endif // __cplusplus 68280297Sjkim 69280297Sjkim#include <dev/isci/scil/sci_library.h> 70280297Sjkim#include <dev/isci/scil/sci_pool.h> 71280297Sjkim#include <dev/isci/scil/sci_base_object.h> 72280297Sjkim#include <dev/isci/scil/sci_base_logger.h> 73280297Sjkim#include <dev/isci/scil/sci_controller_constants.h> 74238384Sjkim 75280297Sjkim/** 76280297Sjkim * @struct SCI_BASE_LIBRARY 77280297Sjkim * 78280297Sjkim * @brief This structure contains all of the objects common to all library 79280297Sjkim * sub-objects. 80280297Sjkim */ 81280297Sjkimtypedef struct SCI_BASE_LIBRARY 82238384Sjkim{ 83238384Sjkim /** 84280297Sjkim * This class derives directly from the base object class. As a result, 85280297Sjkim * the field is named "parent" and is the first field contained in the 86280297Sjkim * structure. 87280297Sjkim */ 88280297Sjkim SCI_BASE_OBJECT_T parent; 89280297Sjkim 90280297Sjkim /** 91280297Sjkim * This field provides the logger object to be utilized by all objects 92280297Sjkim * contained inside of a library. 93280297Sjkim */ 94280297Sjkim SCI_BASE_LOGGER_T logger; 95280297Sjkim 96280297Sjkim // Create a pool structure to manage free controller indices. 97269682Sjkim SCI_POOL_CREATE(controller_id_pool, U16, SCI_MAX_CONTROLLERS); 98280297Sjkim 99280297Sjkim} SCI_BASE_LIBRARY_T; 100280297Sjkim 101238384Sjkim 102280297Sjkim/** 103280297Sjkim * @brief This method will construct the base library object. 104238384Sjkim * 105280297Sjkim * @param[in] this_library This parameter specifies the library object 106280297Sjkim * to be constructed. 107238384Sjkim * @param[in] max_controllers This parameter specifies the maximum number 108280297Sjkim * of controllers to be supported by this library. 109280297Sjkim * 110280297Sjkim * @return none 111238384Sjkim */ 112280297Sjkimvoid sci_base_library_construct( 113280297Sjkim SCI_BASE_LIBRARY_T * this_library, 114280297Sjkim U32 max_controllers 115280297Sjkim); 116280297Sjkim 117280297Sjkim/** 118280297Sjkim * This macro provides common code for allocating a controller from a library. 119280297Sjkim * It will ensure that we successfully allocate an available controller index 120280297Sjkim * and return SCI_FAILURE_INSUFFICIENT_RESOURCES if unsuccessful. 121238384Sjkim */ 122280297Sjkim#define SCI_BASE_LIBRARY_ALLOCATE_CONTROLLER( \ 123280297Sjkim library, \ 124291719Sjkim controller_ptr, \ 125291719Sjkim rc \ 126291719Sjkim) \ 127280297Sjkim{ \ 128238384Sjkim U16 index; \ 129280297Sjkim *rc = SCI_SUCCESS; \ 130280297Sjkim if (! sci_pool_empty((library)->parent.controller_id_pool)) \ 131280297Sjkim { \ 132280297Sjkim sci_pool_get((library)->parent.controller_id_pool, index); \ 133238384Sjkim *controller_ptr = (SCI_CONTROLLER_HANDLE_T) \ 134280297Sjkim & (library)->controllers[index]; \ 135238384Sjkim } \ 136280297Sjkim else \ 137306198Sjkim *rc = SCI_FAILURE_INSUFFICIENT_RESOURCES; \ 138280297Sjkim} 139280297Sjkim 140280297Sjkim/** 141280297Sjkim * This macro provides common code for freeing a controller to a library. 142280297Sjkim * It calculates the index to the controller instance in the array by 143280297Sjkim * determining the offset. 144280297Sjkim */ 145280297Sjkim#define SCI_BASE_LIBRARY_FREE_CONTROLLER( \ 146280297Sjkim library, \ 147280297Sjkim controller, \ 148280297Sjkim CONTROLLER_TYPE, \ 149280297Sjkim rc \ 150280297Sjkim) \ 151280297Sjkim{ \ 152280297Sjkim U16 index = (U16) \ 153280297Sjkim ((((char *)(controller)) - ((char *)(library)->controllers))\ 154238384Sjkim / sizeof(CONTROLLER_TYPE)); \ 155280297Sjkim *rc = SCI_SUCCESS; \ 156238384Sjkim if ( (index < SCI_MAX_CONTROLLERS) \ 157280297Sjkim && (! sci_pool_full((library)->parent.controller_id_pool)) ) \ 158238384Sjkim { \ 159280297Sjkim sci_pool_put((library)->parent.controller_id_pool, index); \ 160280297Sjkim } \ 161280297Sjkim else \ 162280297Sjkim *rc = SCI_FAILURE_CONTROLLER_NOT_FOUND; \ 163238384Sjkim} 164280297Sjkim 165280297Sjkim 166280297Sjkim 167280297Sjkim/** 168238384Sjkim * This macro provides common code for constructing library. It 169280297Sjkim * It initialize and fill the library's controller_id_pool. 170280297Sjkim */ 171280297Sjkim#define SCI_BASE_LIBRARY_CONSTRUCT( \ 172280297Sjkim library, \ 173280297Sjkim base_library, \ 174280297Sjkim max_controllers, \ 175280297Sjkim CONTROLLER_TYPE, \ 176280297Sjkim status \ 177280297Sjkim) \ 178280297Sjkim{ \ 179238384Sjkim U32 controller_index; \ 180280297Sjkim sci_base_object_construct(&(base_library)->parent, &(base_library)->logger); \ 181280297Sjkim sci_pool_initialize((base_library)->controller_id_pool); \ 182280297Sjkim for (controller_index = 0; controller_index < max_controller_count; controller_index++) \ 183280297Sjkim { \ 184280297Sjkim SCI_BASE_LIBRARY_FREE_CONTROLLER( \ 185238384Sjkim library, \ 186280297Sjkim &library->controllers[controller_index], \ 187280297Sjkim CONTROLLER_TYPE, \ 188238384Sjkim &status \ 189280297Sjkim ); \ 190238384Sjkim } \ 191280297Sjkim} 192238384Sjkim 193280297Sjkim#ifdef __cplusplus 194280297Sjkim} 195238384Sjkim#endif // __cplusplus 196280297Sjkim 197280297Sjkim#endif // _SCI_BASE_LIBRARY_H_ 198238384Sjkim