1 /** @addtogroup MCD_MCDIMPL_KMOD_API Mobicore Driver Module API 2 * @ingroup MCD_MCDIMPL_KMOD 3 * @{ 4 * Interface to Mobicore Driver Kernel Module. 5 * @file 6 * 7 * <h2>Introduction</h2> 8 * The MobiCore Driver Kernel Module is a Linux device driver, which represents 9 * the command proxy on the lowest layer to the secure world (Swd). Additional 10 * services like memory allocation via mmap and generation of a L2 tables for 11 * given virtual memory are also supported. IRQ functionallity receives 12 * information from the SWd in the non secure world (NWd). 13 * As customary the driver is handled as linux device driver with "open", 14 * "close" and "ioctl" commands. Access to the driver is possible after the 15 * device "/dev/mobicore" has been opened. 16 * The MobiCore Driver Kernel Module must be installed via 17 * "insmod mcDrvModule.ko". 18 * 19 * 20 * <h2>Version history</h2> 21 * <table class="customtab"> 22 * <tr><td width="100px"><b>Date</b></td><td width="80px"><b>Version</b></td> 23 * <td><b>Changes</b></td></tr> 24 * <tr><td>2010-05-25</td><td>0.1</td><td>Initial Release</td></tr> 25 * </table> 26 * 27 * <!-- Copyright Giesecke & Devrient GmbH 2010-2012 --> 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 * 1. Redistributions of source code must retain the above copyright 33 * notice, this list of conditions and the following disclaimer. 34 * 2. Redistributions in binary form must reproduce the above copyright 35 * notice, this list of conditions and the following disclaimer in the 36 * documentation and/or other materials provided with the distribution. 37 * 3. The name of the author may not be used to endorse or promote 38 * products derived from this software without specific prior 39 * written permission. 40 * 41 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS 42 * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 43 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 44 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY 45 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 46 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 47 * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 48 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 49 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 50 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 51 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 52 */ 53 54 #ifndef _MC_LINUX_H_ 55 #define _MC_LINUX_H_ 56 57 #include "version.h" 58 59 #define MC_ADMIN_DEVNODE "mobicore" 60 #define MC_USER_DEVNODE "mobicore-user" 61 62 /** 63 * Data exchange structure of the MC_DRV_MODULE_INIT ioctl command. 64 * INIT request data to SWD 65 */ 66 struct mc_ioctl_init { 67 /** notification buffer start/length [16:16] [start, length] */ 68 uint32_t nq_offset; 69 /** length of notification queue */ 70 uint32_t nq_length; 71 /** mcp buffer start/length [16:16] [start, length] */ 72 uint32_t mcp_offset; 73 /** length of mcp buffer */ 74 uint32_t mcp_length; 75 }; 76 77 78 /** 79 * Data exchange structure of the MC_DRV_MODULE_INFO ioctl command. 80 * INFO request data to the SWD 81 */ 82 struct mc_ioctl_info { 83 uint32_t ext_info_id; /**< extended info ID */ 84 uint32_t state; /**< state */ 85 uint32_t ext_info; /**< extended info */ 86 }; 87 88 /** 89 * Mmap allocates and maps contiguous memory into a process. 90 * We use the third parameter, void *offset, to distinguish between some cases 91 * offset = MC_DRV_KMOD_MMAP_WSM usual operation, pages are registered in 92 * device structure and freed later. 93 * offset = MC_DRV_KMOD_MMAP_MCI get Instance of MCI, allocates or mmaps 94 * the MCI to daemon 95 * 96 * In mmap(), the offset specifies which of several device I/O pages is 97 * requested. Linux only transfers the page number, i.e. the upper 20 bits to 98 * kernel module. Therefore we define our special offsets as multiples of page 99 * size. 100 */ 101 struct mc_ioctl_map { 102 size_t len; /**< Buffer length */ 103 uint32_t handle; /**< WSM handle */ 104 unsigned long addr; /**< Virtual address */ 105 unsigned long phys_addr; /**< physical address of WSM (or NULL) */ 106 bool reused; /**< if WSM memory was reused, or new allocated */ 107 }; 108 109 /** 110 * Data exchange structure of the MC_IO_REG_WSM command. 111 * 112 * Allocates a physical L2 table and maps the buffer into this page. 113 * Returns the physical address of the L2 table. 114 * The page alignment will be created and the appropriated pSize and pOffsetL2 115 * will be modified to the used values. 116 */ 117 struct mc_ioctl_reg_wsm { 118 uint32_t buffer; /**< base address of the virtual address */ 119 uint32_t len; /**< size of the virtual address space */ 120 uint32_t pid; /**< process id */ 121 uint32_t handle; /**< driver handle for locked memory */ 122 uint32_t table_phys; /**< physical address of the L2 table */ 123 }; 124 125 126 /** 127 * Data exchange structure of the MC_DRV_MODULE_FC_EXECUTE ioctl command. 128 * internal, unsupported 129 */ 130 struct mc_ioctl_execute { 131 /**< base address of mobicore binary */ 132 uint32_t phys_start_addr; 133 /**< length of DDR area */ 134 uint32_t length; 135 }; 136 137 /** 138 * Data exchange structure of the MC_IO_RESOLVE_CONT_WSM ioctl command. 139 */ 140 struct mc_ioctl_resolv_cont_wsm { 141 /**< driver handle for buffer */ 142 uint32_t handle; 143 /**< base address of memory */ 144 uint32_t phys; 145 /**< length memory */ 146 uint32_t length; 147 }; 148 149 150 /* @defgroup Mobicore_Driver_Kernel_Module_Interface IOCTL */ 151 152 153 /** 154 * defines for the ioctl mobicore driver module function call from user space. 155 */ 156 /* MobiCore IOCTL magic number */ 157 #define MC_IOC_MAGIC 'M' 158 159 #define MC_IO_INIT _IOWR(MC_IOC_MAGIC, 0, struct mc_ioctl_init) 160 #define MC_IO_INFO _IOWR(MC_IOC_MAGIC, 1, struct mc_ioctl_info) 161 #define MC_IO_VERSION _IOR(MC_IOC_MAGIC, 2, uint32_t) 162 /** 163 * ioctl parameter to send the YIELD command to the SWD. 164 * Only possible in Privileged Mode. 165 * ioctl(fd, MC_DRV_MODULE_YIELD) 166 */ 167 #define MC_IO_YIELD _IO(MC_IOC_MAGIC, 3) 168 /** 169 * ioctl parameter to send the NSIQ signal to the SWD. 170 * Only possible in Privileged Mode 171 * ioctl(fd, MC_DRV_MODULE_NSIQ) 172 */ 173 #define MC_IO_NSIQ _IO(MC_IOC_MAGIC, 4) 174 /** 175 * Free's memory which is formerly allocated by the driver's mmap 176 * command. The parameter must be this mmaped address. 177 * The internal instance data regarding to this address are deleted as 178 * well as each according memory page and its appropriated reserved bit 179 * is cleared (ClearPageReserved). 180 * Usage: ioctl(fd, MC_DRV_MODULE_FREE, &address) with address beeing of 181 * type long address 182 */ 183 #define MC_IO_FREE _IO(MC_IOC_MAGIC, 5) 184 /** 185 * Creates a L2 Table of the given base address and the size of the 186 * data. 187 * Parameter: mc_ioctl_app_reg_wsm_l2_params 188 */ 189 #define MC_IO_REG_WSM _IOWR(MC_IOC_MAGIC, 6, struct mc_ioctl_reg_wsm) 190 #define MC_IO_UNREG_WSM _IO(MC_IOC_MAGIC, 7) 191 #define MC_IO_LOCK_WSM _IO(MC_IOC_MAGIC, 8) 192 #define MC_IO_UNLOCK_WSM _IO(MC_IOC_MAGIC, 9) 193 #define MC_IO_EXECUTE _IOWR(MC_IOC_MAGIC, 10, struct mc_ioctl_execute) 194 195 /** 196 * Mmap allocates and maps contiguous memory into a process. 197 * MC_DRV_KMOD_MMAP_WSM usual operation, pages are registered in 198 * device structure and freed later. 199 * MC_DRV_KMOD_MMAP_MCI get Instance of MCI, allocates or mmaps 200 * the MCI to daemon 201 * MC_DRV_KMOD_MMAP_PERSISTENTWSM special operation, without 202 * registration of pages 203 */ 204 #define MC_IO_MAP_WSM _IOWR(MC_IOC_MAGIC, 11, struct mc_ioctl_map) 205 #define MC_IO_MAP_MCI _IOWR(MC_IOC_MAGIC, 12, struct mc_ioctl_map) 206 #define MC_IO_MAP_PWSM _IOWR(MC_IOC_MAGIC, 13, struct mc_ioctl_map) 207 208 /** 209 * Clean orphaned WSM buffers. Only available to the daemon and should 210 * only be carried out if the TLC crashes or otherwise calls exit() in 211 * an unexpected manner. 212 * The clean is needed toghether with the lock/unlock mechanism so the daemon 213 * has clear control of the mapped buffers so it can close a truslet before 214 * release all the WSM buffers, otherwise the trustlet would be able to write 215 * to possibly kernel memory areas */ 216 #define MC_IO_CLEAN_WSM _IO(MC_IOC_MAGIC, 14) 217 218 /** Get L2 phys address of a buffer handle allocated to the user. Only 219 * available to the daemon */ 220 #define MC_IO_RESOLVE_WSM _IOWR(MC_IOC_MAGIC, 15, uint32_t) 221 222 /** Get the phys address & len of a allocated contiguous buffer. Only available 223 * to the daemon */ 224 #define MC_IO_RESOLVE_CONT_WSM _IOWR(MC_IOC_MAGIC, 16, struct mc_ioctl_execute) 225 226 #endif /* _MC_LINUX_H_ */ 227 /** @} */ 228