1 /* 2 $License: 3 Copyright 2011 InvenSense, Inc. 4 5 Licensed under the Apache License, Version 2.0 (the "License"); 6 you may not use this file except in compliance with the License. 7 You may obtain a copy of the License at 8 9 http://www.apache.org/licenses/LICENSE-2.0 10 11 Unless required by applicable law or agreed to in writing, software 12 distributed under the License is distributed on an "AS IS" BASIS, 13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 See the License for the specific language governing permissions and 15 limitations under the License. 16 $ 17 */ 18 19 #ifndef __MLSL_H__ 20 #define __MLSL_H__ 21 22 /** 23 * @defgroup MLSL 24 * @brief Motion Library - Serial Layer. 25 * The Motion Library System Layer provides the Motion Library 26 * with the communication interface to the hardware. 27 * 28 * The communication interface is assumed to support serial 29 * transfers in burst of variable length up to 30 * SERIAL_MAX_TRANSFER_SIZE. 31 * The default value for SERIAL_MAX_TRANSFER_SIZE is 128 bytes. 32 * Transfers of length greater than SERIAL_MAX_TRANSFER_SIZE, will 33 * be subdivided in smaller transfers of length <= 34 * SERIAL_MAX_TRANSFER_SIZE. 35 * The SERIAL_MAX_TRANSFER_SIZE definition can be modified to 36 * overcome any host processor transfer size limitation down to 37 * 1 B, the minimum. 38 * An higher value for SERIAL_MAX_TRANSFER_SIZE will favor 39 * performance and efficiency while requiring higher resource usage 40 * (mostly buffering). A smaller value will increase overhead and 41 * decrease efficiency but allows to operate with more resource 42 * constrained processor and master serial controllers. 43 * The SERIAL_MAX_TRANSFER_SIZE definition can be found in the 44 * mlsl.h header file and master serial controllers. 45 * The SERIAL_MAX_TRANSFER_SIZE definition can be found in the 46 * mlsl.h header file. 47 * 48 * @{ 49 * @file mlsl.h 50 * @brief The Motion Library System Layer. 51 * 52 */ 53 54 #include "mltypes.h" 55 #include <linux/mpu.h> 56 57 #ifdef __cplusplus 58 extern "C" { 59 #endif 60 61 /* 62 * NOTE : to properly support Yamaha compass reads, 63 * the max transfer size should be at least 9 B. 64 * Length in bytes, typically a power of 2 >= 2 65 */ 66 #define SERIAL_MAX_TRANSFER_SIZE 128 67 68 #ifndef __KERNEL__ 69 /** 70 * inv_serial_open() - used to open the serial port. 71 * @port The COM port specification associated with the device in use. 72 * @sl_handle a pointer to the file handle to the serial device to be open 73 * for the communication. 74 * This port is used to send and receive data to the device. 75 * 76 * This function is called by inv_serial_start(). 77 * Unlike previous MPL Software releases, explicitly calling 78 * inv_serial_start() is mandatory to instantiate the communication 79 * with the device. 80 * 81 * returns INV_SUCCESS if successful, a non-zero error code otherwise. 82 */ 83 inv_error_t inv_serial_open(char const *port, void **sl_handle); 84 85 /** 86 * inv_serial_close() - used to close the serial port. 87 * @sl_handle a file handle to the serial device used for the communication. 88 * 89 * This port is used to send and receive data to the device. 90 * 91 * This function is called by inv_serial_stop(). 92 * Unlike previous MPL Software releases, explicitly calling 93 * inv_serial_stop() is mandatory to properly shut-down the 94 * communication with the device. 95 * 96 * returns INV_SUCCESS if successful, a non-zero error code otherwise. 97 */ 98 inv_error_t inv_serial_close(void *sl_handle); 99 100 /** 101 * inv_serial_reset() - used to reset any buffering the driver may be doing 102 * returns INV_SUCCESS if successful, a non-zero error code otherwise. 103 */ 104 inv_error_t inv_serial_reset(void *sl_handle); 105 #endif 106 107 /** 108 * inv_serial_single_write() - used to write a single byte of data. 109 * @sl_handle pointer to the serial device used for the communication. 110 * @slave_addr I2C slave address of device. 111 * @register_addr Register address to write. 112 * @data Single byte of data to write. 113 * 114 * It is called by the MPL to write a single byte of data to the MPU. 115 * 116 * returns INV_SUCCESS if successful, a non-zero error code otherwise. 117 */ 118 inv_error_t inv_serial_single_write( 119 void *sl_handle, 120 unsigned char slave_addr, 121 unsigned char register_addr, 122 unsigned char data); 123 124 /** 125 * inv_serial_write() - used to write multiple bytes of data to registers. 126 * @sl_handle a file handle to the serial device used for the communication. 127 * @slave_addr I2C slave address of device. 128 * @register_addr Register address to write. 129 * @length Length of burst of data. 130 * @data Pointer to block of data. 131 * 132 * returns INV_SUCCESS if successful, a non-zero error code otherwise. 133 */ 134 inv_error_t inv_serial_write( 135 void *sl_handle, 136 unsigned char slave_addr, 137 unsigned short length, 138 unsigned char const *data); 139 140 /** 141 * inv_serial_read() - used to read multiple bytes of data from registers. 142 * @sl_handle a file handle to the serial device used for the communication. 143 * @slave_addr I2C slave address of device. 144 * @register_addr Register address to read. 145 * @length Length of burst of data. 146 * @data Pointer to block of data. 147 * 148 * returns INV_SUCCESS == 0 if successful; a non-zero error code otherwise. 149 */ 150 inv_error_t inv_serial_read( 151 void *sl_handle, 152 unsigned char slave_addr, 153 unsigned char register_addr, 154 unsigned short length, 155 unsigned char *data); 156 157 /** 158 * inv_serial_read_mem() - used to read multiple bytes of data from the memory. 159 * This should be sent by I2C or SPI. 160 * 161 * @sl_handle a file handle to the serial device used for the communication. 162 * @slave_addr I2C slave address of device. 163 * @mem_addr The location in the memory to read from. 164 * @length Length of burst data. 165 * @data Pointer to block of data. 166 * 167 * returns INV_SUCCESS == 0 if successful; a non-zero error code otherwise. 168 */ 169 inv_error_t inv_serial_read_mem( 170 void *sl_handle, 171 unsigned char slave_addr, 172 unsigned short mem_addr, 173 unsigned short length, 174 unsigned char *data); 175 176 /** 177 * inv_serial_write_mem() - used to write multiple bytes of data to the memory. 178 * @sl_handle a file handle to the serial device used for the communication. 179 * @slave_addr I2C slave address of device. 180 * @mem_addr The location in the memory to write to. 181 * @length Length of burst data. 182 * @data Pointer to block of data. 183 * 184 * returns INV_SUCCESS == 0 if successful; a non-zero error code otherwise. 185 */ 186 inv_error_t inv_serial_write_mem( 187 void *sl_handle, 188 unsigned char slave_addr, 189 unsigned short mem_addr, 190 unsigned short length, 191 unsigned char const *data); 192 193 /** 194 * inv_serial_read_fifo() - used to read multiple bytes of data from the fifo. 195 * @sl_handle a file handle to the serial device used for the communication. 196 * @slave_addr I2C slave address of device. 197 * @length Length of burst of data. 198 * @data Pointer to block of data. 199 * 200 * returns INV_SUCCESS == 0 if successful; a non-zero error code otherwise. 201 */ 202 inv_error_t inv_serial_read_fifo( 203 void *sl_handle, 204 unsigned char slave_addr, 205 unsigned short length, 206 unsigned char *data); 207 208 /** 209 * inv_serial_write_fifo() - used to write multiple bytes of data to the fifo. 210 * @sl_handle a file handle to the serial device used for the communication. 211 * @slave_addr I2C slave address of device. 212 * @length Length of burst of data. 213 * @data Pointer to block of data. 214 * 215 * returns INV_SUCCESS == 0 if successful; a non-zero error code otherwise. 216 */ 217 inv_error_t inv_serial_write_fifo( 218 void *sl_handle, 219 unsigned char slave_addr, 220 unsigned short length, 221 unsigned char const *data); 222 223 #ifndef __KERNEL__ 224 /** 225 * inv_serial_read_cfg() - used to get the configuration data. 226 * @cfg Pointer to the configuration data. 227 * @len Length of the configuration data. 228 * 229 * Is called by the MPL to get the configuration data 230 * used by the motion library. 231 * This data would typically be saved in non-volatile memory. 232 * 233 * returns INV_SUCCESS if successful, a non-zero error code otherwise. 234 */ 235 inv_error_t inv_serial_read_cfg(unsigned char *cfg, unsigned int len); 236 237 /** 238 * inv_serial_write_cfg() - used to save the configuration data. 239 * @cfg Pointer to the configuration data. 240 * @len Length of the configuration data. 241 * 242 * Is called by the MPL to save the configuration data used by the 243 * motion library. 244 * This data would typically be saved in non-volatile memory. 245 * 246 * returns INV_SUCCESS if successful, a non-zero error code otherwise. 247 */ 248 inv_error_t inv_serial_write_cfg(unsigned char *cfg, unsigned int len); 249 250 /** 251 * inv_serial_read_cal() - used to get the calibration data. 252 * @cfg Pointer to the calibration data. 253 * @len Length of the calibration data. 254 * 255 * It is called by the MPL to get the calibration data used by the 256 * motion library. 257 * This data is typically be saved in non-volatile memory. 258 * 259 * returns INV_SUCCESS if successful, a non-zero error code otherwise. 260 */ 261 inv_error_t inv_serial_read_cal(unsigned char *cal, unsigned int len); 262 263 /** 264 * inv_serial_write_cal() - used to save the calibration data. 265 * 266 * @cfg Pointer to the calibration data. 267 * @len Length of the calibration data. 268 * 269 * It is called by the MPL to save the calibration data used by the 270 * motion library. 271 * This data is typically be saved in non-volatile memory. 272 * returns INV_SUCCESS if successful, a non-zero error code otherwise. 273 */ 274 inv_error_t inv_serial_write_cal(unsigned char *cal, unsigned int len); 275 276 /** 277 * inv_serial_get_cal_length() - Get the calibration length from the storage. 278 * @len lenght to be returned 279 * 280 * returns INV_SUCCESS if successful, a non-zero error code otherwise. 281 */ 282 inv_error_t inv_serial_get_cal_length(unsigned int *len); 283 #endif 284 #ifdef __cplusplus 285 } 286 #endif 287 /** 288 * @} 289 */ 290 #endif /* __MLSL_H__ */ 291