sci_base_memory_descriptor_list.h revision 231134
1/*- 2 * This file is provided under a dual BSD/GPLv2 license. When using or 3 * redistributing this file, you may do so under either license. 4 * 5 * GPL LICENSE SUMMARY 6 * 7 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8 * 9 * This program is free software; you can redistribute it and/or modify 10 * it under the terms of version 2 of the GNU General Public License as 11 * published by the Free Software Foundation. 12 * 13 * This program is distributed in the hope that it will be useful, but 14 * WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * General Public License for more details. 17 * 18 * You should have received a copy of the GNU General Public License 19 * along with this program; if not, write to the Free Software 20 * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21 * The full GNU General Public License is included in this distribution 22 * in the file called LICENSE.GPL. 23 * 24 * BSD LICENSE 25 * 26 * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27 * All rights reserved. 28 * 29 * Redistribution and use in source and binary forms, with or without 30 * modification, are permitted provided that the following conditions 31 * are met: 32 * 33 * * Redistributions of source code must retain the above copyright 34 * notice, this list of conditions and the following disclaimer. 35 * * Redistributions in binary form must reproduce the above copyright 36 * notice, this list of conditions and the following disclaimer in 37 * the documentation and/or other materials provided with the 38 * distribution. 39 * 40 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51 * 52 * $FreeBSD$ 53 */ 54#ifndef _SCI_BASE_MEMORY_DESCRIPTOR_LIST_H_ 55#define _SCI_BASE_MEMORY_DESCRIPTOR_LIST_H_ 56 57/** 58 * @file 59 * 60 * @brief This file contains the protected interface structures, constants 61 * and interface methods for the SCI_BASE_MEMORY_DESCRIPTOR_LIST 62 * object. 63 */ 64 65#ifdef __cplusplus 66extern "C" { 67#endif // __cplusplus 68 69#include <dev/isci/scil/sci_types.h> 70#include <dev/isci/scil/sci_memory_descriptor_list.h> 71 72 73/** 74 * @struct SCI_BASE_MEMORY_DESCRIPTOR_LIST 75 * 76 * @brief This structure contains all of the fields necessary to implement 77 * a simple stack for managing the list of available controller indices. 78 */ 79typedef struct SCI_BASE_MEMORY_DESCRIPTOR_LIST 80{ 81 /** 82 * This field indicates the length of the memory descriptor entry array. 83 */ 84 U32 length; 85 86 /** 87 * This field is utilized to provide iterator pattern functionality. 88 * It indicates the index of the next memory descriptor in the iteration. 89 */ 90 U32 next_index; 91 92 /** 93 * This field will point to the list of memory descriptors. 94 */ 95 SCI_PHYSICAL_MEMORY_DESCRIPTOR_T * mde_array; 96 97 /** 98 * This field simply allows a user to chain memory descriptor lists 99 * together if desired. This field will be initialized to 100 * SCI_INVALID_HANDLE. 101 */ 102 SCI_MEMORY_DESCRIPTOR_LIST_HANDLE_T next_mdl; 103 104} SCI_BASE_MEMORY_DESCRIPTOR_LIST_T; 105 106/** 107 * @brief This method is invoked to construct an memory descriptor list. 108 * It initializes the fields of the MDL. 109 * 110 * @param[in] mdl This parameter specifies the memory descriptor list 111 * to be constructed. 112 * @param[in] mde_array This parameter specifies the array of memory 113 * descriptor entries to be managed by this list. 114 * @param[in] mde_array_length This parameter specifies the size of the 115 * array of entries. 116 * @param[in] next_mdl This parameter specifies a subsequent MDL object 117 * to be managed by this MDL object. 118 * 119 * @return none. 120 */ 121void sci_base_mdl_construct( 122 SCI_BASE_MEMORY_DESCRIPTOR_LIST_T * mdl, 123 SCI_PHYSICAL_MEMORY_DESCRIPTOR_T * mde_array, 124 U32 mde_array_length, 125 SCI_MEMORY_DESCRIPTOR_LIST_HANDLE_T next_mdl 126); 127 128/** 129 * This macro constructs an memory descriptor entry with the given 130 * alignment and size 131 */ 132#define sci_base_mde_construct(mde, alignment, size, attributes) \ 133{ \ 134 (mde)->constant_memory_alignment = (alignment); \ 135 (mde)->constant_memory_size = (size); \ 136 (mde)->constant_memory_attributes = (attributes); \ 137} 138 139/** 140 * @brief This method validates that the memory descriptor is correctly 141 * filled out by the SCI User 142 * 143 * @param[in] mde This parameter is the mde entry to validate 144 * @param[in] alignment This parameter specifies the expected alignment of 145 * the memory for the mde. 146 * @param[in] size This parameter specifies the memory size expected for 147 * the mde its value should not have been changed by the SCI 148 * User. 149 * @param[in] attributes This parameter specifies the attributes for the 150 * memory descriptor provided. 151 * 152 * @return BOOL This method returns an indication as to whether the 153 * supplied MDE is valid or not. 154 * @retval TRUE The MDE is valid. 155 * @retval FALSE The MDE is not valid. 156 */ 157BOOL sci_base_mde_is_valid( 158 SCI_PHYSICAL_MEMORY_DESCRIPTOR_T *mde, 159 U32 alignment, 160 U32 size, 161 U16 attributes 162); 163 164#ifdef __cplusplus 165} 166#endif // __cplusplus 167 168#endif // _SCI_BASE_MEMORY_DESCRIPTOR_LIST_H_ 169