sci_memory_descriptor_list.h revision 230557
1181053Srwatson/*- 2188313Srwatson * This file is provided under a dual BSD/GPLv2 license. When using or 3155192Srwatson * redistributing this file, you may do so under either license. 4155192Srwatson * 5155192Srwatson * GPL LICENSE SUMMARY 6155192Srwatson * 7155192Srwatson * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8155192Srwatson * 9155192Srwatson * This program is free software; you can redistribute it and/or modify 10155192Srwatson * it under the terms of version 2 of the GNU General Public License as 11155192Srwatson * published by the Free Software Foundation. 12155192Srwatson * 13180701Srwatson * This program is distributed in the hope that it will be useful, but 14155192Srwatson * WITHOUT ANY WARRANTY; without even the implied warranty of 15155192Srwatson * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16155192Srwatson * General Public License for more details. 17155192Srwatson * 18155192Srwatson * You should have received a copy of the GNU General Public License 19155192Srwatson * along with this program; if not, write to the Free Software 20155192Srwatson * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21155192Srwatson * The full GNU General Public License is included in this distribution 22155192Srwatson * in the file called LICENSE.GPL. 23155192Srwatson * 24155192Srwatson * BSD LICENSE 25155192Srwatson * 26155192Srwatson * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27155192Srwatson * All rights reserved. 28155192Srwatson * 29155192Srwatson * Redistribution and use in source and binary forms, with or without 30155192Srwatson * modification, are permitted provided that the following conditions 31155192Srwatson * are met: 32155192Srwatson * 33155192Srwatson * * Redistributions of source code must retain the above copyright 34155192Srwatson * notice, this list of conditions and the following disclaimer. 35155192Srwatson * * Redistributions in binary form must reproduce the above copyright 36155192Srwatson * notice, this list of conditions and the following disclaimer in 37156882Srwatson * the documentation and/or other materials provided with the 38156882Srwatson * distribution. 39155192Srwatson * 40155192Srwatson * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41155192Srwatson * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42155192Srwatson * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43155192Srwatson * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44155192Srwatson * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45155192Srwatson * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46155192Srwatson * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47155192Srwatson * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48155192Srwatson * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49155192Srwatson * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50155192Srwatson * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51155192Srwatson * 52155192Srwatson * $FreeBSD$ 53195177Ssson */ 54155192Srwatson#ifndef _SCI_MEMORY_DESCRIPTOR_LIST_H_ 55155192Srwatson#define _SCI_MEMORY_DESCRIPTOR_LIST_H_ 56155192Srwatson 57156889Srwatson/** 58156889Srwatson * @file 59155192Srwatson * 60155192Srwatson * @brief This file contains all of the basic data types utilized by an 61155192Srwatson * SCI user or implementor. 62155192Srwatson */ 63155192Srwatson 64155192Srwatson#ifdef __cplusplus 65161813Swsalamonextern "C" { 66161813Swsalamon#endif // __cplusplus 67155192Srwatson 68155192Srwatson#include <dev/isci/scil/sci_types.h> 69155192Srwatson 70155192Srwatson/** 71155192Srwatson * @name SCI_MDE_ATTRIBUTES 72156889Srwatson * 73156889Srwatson * These constants depict memory attributes for the Memory 74156889Srwatson * Descriptor Entries (MDEs) contained in the MDL. 75155192Srwatson */ 76155192Srwatson/*@{*/ 77159269Srwatson#define SCI_MDE_ATTRIBUTE_CACHEABLE 0x0001 78159269Srwatson#define SCI_MDE_ATTRIBUTE_PHYSICALLY_CONTIGUOUS 0x0002 79159269Srwatson/*@}*/ 80155192Srwatson 81155192Srwatson/** 82155192Srwatson * @struct SCI_PHYSICAL_MEMORY_DESCRIPTOR 83155192Srwatson * @brief This structure defines a description of a memory location for 84159269Srwatson * the SCI implementation. 85159269Srwatson */ 86159269Srwatsontypedef struct SCI_PHYSICAL_MEMORY_DESCRIPTOR 87162380Scsjp{ 88162380Scsjp /** 89162380Scsjp * This field contains the virtual address associated with this descriptor 90155192Srwatson * element. This field shall be zero when the descriptor is retrieved from 91155192Srwatson * the SCI implementation. The user shall set this field prior 92155192Srwatson * sci_controller_start() 93155192Srwatson */ 94155192Srwatson void * virtual_address; 95155192Srwatson 96155192Srwatson /** 97155192Srwatson * This field contains the physical address associated with this desciptor 98156889Srwatson * element. This field shall be zero when the descriptor is retrieved from 99156889Srwatson * the SCI implementation. The user shall set this field prior 100156889Srwatson * sci_controller_start() 101156889Srwatson */ 102156889Srwatson SCI_PHYSICAL_ADDRESS physical_address; 103156889Srwatson 104156889Srwatson /** 105155192Srwatson * This field contains the size requirement for this memory descriptor. 106155192Srwatson * A value of zero for this field indicates the end of the descriptor 107155192Srwatson * list. The value should be treated as read only for an SCI user. 108195177Ssson */ 109195177Ssson U32 constant_memory_size; 110155192Srwatson 111155192Srwatson /** 112155192Srwatson * This field contains the alignment requirement for this memory 113180709Srwatson * descriptor. A value of zero for this field indicates the end of the 114155192Srwatson * descriptor list. All other values indicate the number of bytes to 115155192Srwatson * achieve the necessary alignment. The value should be treated as 116156889Srwatson * read only for an SCI user. 117156889Srwatson */ 118156889Srwatson U32 constant_memory_alignment; 119156889Srwatson 120155192Srwatson /** 121155192Srwatson * This field contains an indication regarding the desired memory 122191270Srwatson * attributes for this memory descriptor entry. 123191270Srwatson * Notes: 124191270Srwatson * - If the cacheable attribute is set, the user can allocate 125191270Srwatson * memory that is backed by cache for better performance. It 126191270Srwatson * is not required that the memory be backed by cache. 127191270Srwatson * - If the physically contiguous attribute is set, then the 128191270Srwatson * entire memory must be physically contiguous across all 129191270Srwatson * page boundaries. 130191270Srwatson */ 131191270Srwatson U16 constant_memory_attributes; 132191270Srwatson 133191270Srwatson} SCI_PHYSICAL_MEMORY_DESCRIPTOR_T; 134191270Srwatson 135155192Srwatson/** 136155192Srwatson * @brief This method simply rewinds the MDL iterator back to the first memory 137191270Srwatson * descriptor entry in the list. 138191270Srwatson * 139191270Srwatson * @param[in] mdl This parameter specifies the memory descriptor list that 140155192Srwatson * is to be rewound. 141191270Srwatson * 142191270Srwatson * @return none 143155192Srwatson */ 144155192Srwatsonvoid sci_mdl_first_entry( 145155192Srwatson SCI_MEMORY_DESCRIPTOR_LIST_HANDLE_T mdl 146155192Srwatson); 147155192Srwatson 148155192Srwatson/** 149191270Srwatson * @brief This method simply updates the "current" pointer to the next 150155192Srwatson * sequential memory descriptor. 151155192Srwatson * 152184856Scsjp * @param[in] mdl This parameter specifies the memory descriptor list for 153155192Srwatson * which to return the next memory descriptor entry in the list. 154155192Srwatson * 155155192Srwatson * @return none. 156156889Srwatson */ 157156889Srwatsonvoid sci_mdl_next_entry( 158156889Srwatson SCI_MEMORY_DESCRIPTOR_LIST_HANDLE_T mdl 159155192Srwatson); 160155192Srwatson 161155192Srwatson/** 162155192Srwatson * @brief This method simply returns the current memory descriptor entry. 163155192Srwatson * 164155192Srwatson * @param[in] mdl This parameter specifies the memory descriptor list for 165155192Srwatson * which to return the current memory descriptor entry. 166155192Srwatson * 167155192Srwatson * @return This method returns a pointer to the current physical memory 168155192Srwatson * descriptor in the MDL. 169155192Srwatson * @retval NULL This value is returned if there are no descriptors in the 170155192Srwatson * list. 171155192Srwatson */ 172156889SrwatsonSCI_PHYSICAL_MEMORY_DESCRIPTOR_T * sci_mdl_get_current_entry( 173156889Srwatson SCI_MEMORY_DESCRIPTOR_LIST_HANDLE_T mdl 174156889Srwatson); 175156889Srwatson 176156889Srwatson#ifdef __cplusplus 177156889Srwatson} 178156889Srwatson#endif // __cplusplus 179156889Srwatson 180168688Scsjp#endif // _SCI_MEMORY_DESCRIPTOR_LIST_H_ 181156889Srwatson 182155192Srwatson