sci_memory_descriptor_list.h revision 231134
1147078Sgshapiro/*- 2261370Sgshapiro * This file is provided under a dual BSD/GPLv2 license. When using or 3147078Sgshapiro * redistributing this file, you may do so under either license. 4147078Sgshapiro * 5147078Sgshapiro * GPL LICENSE SUMMARY 6147078Sgshapiro * 7147078Sgshapiro * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 8147078Sgshapiro * 9147078Sgshapiro * This program is free software; you can redistribute it and/or modify 10147078Sgshapiro * it under the terms of version 2 of the GNU General Public License as 11266711Sgshapiro * published by the Free Software Foundation. 12147078Sgshapiro * 13147078Sgshapiro * This program is distributed in the hope that it will be useful, but 14147078Sgshapiro * WITHOUT ANY WARRANTY; without even the implied warranty of 15147078Sgshapiro * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16203004Sgshapiro * General Public License for more details. 17147078Sgshapiro * 18147078Sgshapiro * You should have received a copy of the GNU General Public License 19157001Sgshapiro * along with this program; if not, write to the Free Software 20147078Sgshapiro * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA. 21147078Sgshapiro * The full GNU General Public License is included in this distribution 22147078Sgshapiro * in the file called LICENSE.GPL. 23147078Sgshapiro * 24147078Sgshapiro * BSD LICENSE 25147078Sgshapiro * 26147078Sgshapiro * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved. 27147078Sgshapiro * All rights reserved. 28147078Sgshapiro * 29147078Sgshapiro * Redistribution and use in source and binary forms, with or without 30147078Sgshapiro * modification, are permitted provided that the following conditions 31147078Sgshapiro * are met: 32147078Sgshapiro * 33147078Sgshapiro * * Redistributions of source code must retain the above copyright 34147078Sgshapiro * notice, this list of conditions and the following disclaimer. 35147078Sgshapiro * * Redistributions in binary form must reproduce the above copyright 36147078Sgshapiro * notice, this list of conditions and the following disclaimer in 37147078Sgshapiro * the documentation and/or other materials provided with the 38147078Sgshapiro * distribution. 39147078Sgshapiro * 40147078Sgshapiro * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 41147078Sgshapiro * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 42157001Sgshapiro * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 43147078Sgshapiro * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 44147078Sgshapiro * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45147078Sgshapiro * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 46147078Sgshapiro * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 47147078Sgshapiro * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 48147078Sgshapiro * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 49147078Sgshapiro * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 50147078Sgshapiro * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 51147078Sgshapiro * 52147078Sgshapiro * $FreeBSD$ 53147078Sgshapiro */ 54147078Sgshapiro#ifndef _SCI_MEMORY_DESCRIPTOR_LIST_H_ 55147078Sgshapiro#define _SCI_MEMORY_DESCRIPTOR_LIST_H_ 56147078Sgshapiro 57147078Sgshapiro/** 58147078Sgshapiro * @file 59147078Sgshapiro * 60147078Sgshapiro * @brief This file contains all of the basic data types utilized by an 61147078Sgshapiro * SCI user or implementor. 62147078Sgshapiro */ 63147078Sgshapiro 64147078Sgshapiro#ifdef __cplusplus 65147078Sgshapiroextern "C" { 66147078Sgshapiro#endif // __cplusplus 67147078Sgshapiro 68147078Sgshapiro#include <dev/isci/scil/sci_types.h> 69147078Sgshapiro 70147078Sgshapiro/** 71147078Sgshapiro * @name SCI_MDE_ATTRIBUTES 72157001Sgshapiro * 73147078Sgshapiro * These constants depict memory attributes for the Memory 74147078Sgshapiro * Descriptor Entries (MDEs) contained in the MDL. 75147078Sgshapiro */ 76147078Sgshapiro/*@{*/ 77157001Sgshapiro#define SCI_MDE_ATTRIBUTE_CACHEABLE 0x0001 78147078Sgshapiro#define SCI_MDE_ATTRIBUTE_PHYSICALLY_CONTIGUOUS 0x0002 79147078Sgshapiro/*@}*/ 80147078Sgshapiro 81147078Sgshapiro/** 82147078Sgshapiro * @struct SCI_PHYSICAL_MEMORY_DESCRIPTOR 83147078Sgshapiro * @brief This structure defines a description of a memory location for 84147078Sgshapiro * the SCI implementation. 85147078Sgshapiro */ 86147078Sgshapirotypedef struct SCI_PHYSICAL_MEMORY_DESCRIPTOR 87147078Sgshapiro{ 88147078Sgshapiro /** 89147078Sgshapiro * This field contains the virtual address associated with this descriptor 90147078Sgshapiro * element. This field shall be zero when the descriptor is retrieved from 91147078Sgshapiro * the SCI implementation. The user shall set this field prior 92147078Sgshapiro * sci_controller_start() 93147078Sgshapiro */ 94147078Sgshapiro void * virtual_address; 95147078Sgshapiro 96147078Sgshapiro /** 97147078Sgshapiro * This field contains the physical address associated with this desciptor 98147078Sgshapiro * element. This field shall be zero when the descriptor is retrieved from 99147078Sgshapiro * the SCI implementation. The user shall set this field prior 100147078Sgshapiro * sci_controller_start() 101147078Sgshapiro */ 102147078Sgshapiro SCI_PHYSICAL_ADDRESS physical_address; 103147078Sgshapiro 104147078Sgshapiro /** 105147078Sgshapiro * This field contains the size requirement for this memory descriptor. 106147078Sgshapiro * A value of zero for this field indicates the end of the descriptor 107147078Sgshapiro * list. The value should be treated as read only for an SCI user. 108147078Sgshapiro */ 109147078Sgshapiro U32 constant_memory_size; 110147078Sgshapiro 111147078Sgshapiro /** 112147078Sgshapiro * This field contains the alignment requirement for this memory 113147078Sgshapiro * descriptor. A value of zero for this field indicates the end of the 114147078Sgshapiro * descriptor list. All other values indicate the number of bytes to 115147078Sgshapiro * achieve the necessary alignment. The value should be treated as 116147078Sgshapiro * read only for an SCI user. 117147078Sgshapiro */ 118147078Sgshapiro U32 constant_memory_alignment; 119147078Sgshapiro 120147078Sgshapiro /** 121147078Sgshapiro * This field contains an indication regarding the desired memory 122147078Sgshapiro * attributes for this memory descriptor entry. 123147078Sgshapiro * Notes: 124147078Sgshapiro * - If the cacheable attribute is set, the user can allocate 125147078Sgshapiro * memory that is backed by cache for better performance. It 126147078Sgshapiro * is not required that the memory be backed by cache. 127147078Sgshapiro * - If the physically contiguous attribute is set, then the 128147078Sgshapiro * entire memory must be physically contiguous across all 129147078Sgshapiro * page boundaries. 130147078Sgshapiro */ 131147078Sgshapiro U16 constant_memory_attributes; 132147078Sgshapiro 133147078Sgshapiro} SCI_PHYSICAL_MEMORY_DESCRIPTOR_T; 134147078Sgshapiro 135147078Sgshapiro/** 136147078Sgshapiro * @brief This method simply rewinds the MDL iterator back to the first memory 137147078Sgshapiro * descriptor entry in the list. 138147078Sgshapiro * 139147078Sgshapiro * @param[in] mdl This parameter specifies the memory descriptor list that 140147078Sgshapiro * is to be rewound. 141147078Sgshapiro * 142147078Sgshapiro * @return none 143147078Sgshapiro */ 144147078Sgshapirovoid sci_mdl_first_entry( 145147078Sgshapiro SCI_MEMORY_DESCRIPTOR_LIST_HANDLE_T mdl 146147078Sgshapiro); 147147078Sgshapiro 148147078Sgshapiro/** 149147078Sgshapiro * @brief This method simply updates the "current" pointer to the next 150147078Sgshapiro * sequential memory descriptor. 151147078Sgshapiro * 152147078Sgshapiro * @param[in] mdl This parameter specifies the memory descriptor list for 153147078Sgshapiro * which to return the next memory descriptor entry in the list. 154147078Sgshapiro * 155147078Sgshapiro * @return none. 156147078Sgshapiro */ 157147078Sgshapirovoid sci_mdl_next_entry( 158147078Sgshapiro SCI_MEMORY_DESCRIPTOR_LIST_HANDLE_T mdl 159147078Sgshapiro); 160147078Sgshapiro 161147078Sgshapiro/** 162147078Sgshapiro * @brief This method simply returns the current memory descriptor entry. 163147078Sgshapiro * 164147078Sgshapiro * @param[in] mdl This parameter specifies the memory descriptor list for 165147078Sgshapiro * which to return the current memory descriptor entry. 166147078Sgshapiro * 167147078Sgshapiro * @return This method returns a pointer to the current physical memory 168147078Sgshapiro * descriptor in the MDL. 169147078Sgshapiro * @retval NULL This value is returned if there are no descriptors in the 170147078Sgshapiro * list. 171147078Sgshapiro */ 172147078SgshapiroSCI_PHYSICAL_MEMORY_DESCRIPTOR_T * sci_mdl_get_current_entry( 173147078Sgshapiro SCI_MEMORY_DESCRIPTOR_LIST_HANDLE_T mdl 174147078Sgshapiro); 175147078Sgshapiro 176147078Sgshapiro#ifdef __cplusplus 177147078Sgshapiro} 178147078Sgshapiro#endif // __cplusplus 179147078Sgshapiro 180147078Sgshapiro#endif // _SCI_MEMORY_DESCRIPTOR_LIST_H_ 181147078Sgshapiro 182147078Sgshapiro