/* ChibiOS/RT - Copyright (C) 2006,2007,2008,2009,2010, 2011,2012,2013 Giovanni Di Sirio. This file is part of ChibiOS/RT. ChibiOS/RT is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. ChibiOS/RT is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see . */ /* Concepts and parts of this file have been contributed by Uladzimir Pylinsky aka barthess. */ /** * @file i2c.c * @brief I2C Driver code. * * @addtogroup I2C * @{ */ #include "hal.h" #if HAL_USE_I2C || defined(__DOXYGEN__) /*===========================================================================*/ /* Driver local definitions. */ /*===========================================================================*/ /*===========================================================================*/ /* Driver exported variables. */ /*===========================================================================*/ /*===========================================================================*/ /* Driver local variables and types. */ /*===========================================================================*/ /*===========================================================================*/ /* Driver local functions. */ /*===========================================================================*/ /*===========================================================================*/ /* Driver exported functions. */ /*===========================================================================*/ /** * @brief I2C Driver initialization. * @note This function is implicitly invoked by @p halInit(), there is * no need to explicitly initialize the driver. * * @init */ void i2cInit(void) { i2c_lld_init(); } /** * @brief Initializes the standard part of a @p I2CDriver structure. * * @param[out] i2cp pointer to the @p I2CDriver object * * @init */ void i2cObjectInit(I2CDriver *i2cp) { i2cp->state = I2C_STOP; i2cp->config = NULL; #if I2C_USE_MUTUAL_EXCLUSION osalMutexObjectInit(&i2cp->mutex); #endif /* I2C_USE_MUTUAL_EXCLUSION */ #if defined(I2C_DRIVER_EXT_INIT_HOOK) I2C_DRIVER_EXT_INIT_HOOK(i2cp); #endif } /** * @brief Configures and activates the I2C peripheral. * * @param[in] i2cp pointer to the @p I2CDriver object * @param[in] config pointer to the @p I2CConfig object * * @api */ void i2cStart(I2CDriver *i2cp, const I2CConfig *config) { osalDbgCheck((i2cp != NULL) && (config != NULL)); osalDbgAssert((i2cp->state == I2C_STOP) || (i2cp->state == I2C_READY) || (i2cp->state == I2C_LOCKED), "invalid state"); osalSysLock(); i2cp->config = config; i2c_lld_start(i2cp); i2cp->state = I2C_READY; osalSysUnlock(); } /** * @brief Deactivates the I2C peripheral. * * @param[in] i2cp pointer to the @p I2CDriver object * * @api */ void i2cStop(I2CDriver *i2cp) { osalDbgCheck(i2cp != NULL); osalDbgAssert((i2cp->state == I2C_STOP) || (i2cp->state == I2C_READY) || (i2cp->state == I2C_LOCKED), "invalid state"); osalSysLock(); i2c_lld_stop(i2cp); i2cp->state = I2C_STOP; osalSysUnlock(); } /** * @brief Returns the errors mask associated to the previous operation. * * @param[in] i2cp pointer to the @p I2CDriver object * @return The errors mask. * * @api */ i2cflags_t i2cGetErrors(I2CDriver *i2cp) { osalDbgCheck(i2cp != NULL); return i2c_lld_get_errors(i2cp); } /** * @brief Sends data via the I2C bus. * @details Function designed to realize "read-through-write" transfer * paradigm. If you want transmit data without any further read, * than set @b rxbytes field to 0. * * @param[in] i2cp pointer to the @p I2CDriver object * @param[in] addr slave device address (7 bits) without R/W bit * @param[in] txbuf pointer to transmit buffer * @param[in] txbytes number of bytes to be transmitted * @param[out] rxbuf pointer to receive buffer * @param[in] rxbytes number of bytes to be received, set it to 0 if * you want transmit only * @param[in] timeout the number of ticks before the operation timeouts, * the following special values are allowed: * - @a TIME_INFINITE no timeout. * . * * @return The operation status. * @retval MSG_OK if the function succeeded. * @retval MSG_RESET if one or more I2C errors occurred, the errors can * be retrieved using @p i2cGetErrors(). * @retval MSG_TIMEOUT if a timeout occurred before operation end. * * @api */ msg_t i2cMasterTransmitTimeout(I2CDriver *i2cp, i2caddr_t addr, const uint8_t *txbuf, size_t txbytes, uint8_t *rxbuf, size_t rxbytes, systime_t timeout) { msg_t rdymsg; osalDbgCheck((i2cp != NULL) && (addr != 0) && (txbytes > 0) && (txbuf != NULL) && ((rxbytes == 0) || ((rxbytes > 0) && (rxbuf != NULL))) && (timeout != TIME_IMMEDIATE)); osalDbgAssert(i2cp->state == I2C_READY, "not ready"); osalSysLock(); i2cp->errors = I2C_NO_ERROR; i2cp->state = I2C_ACTIVE_TX; rdymsg = i2c_lld_master_transmit_timeout(i2cp, addr, txbuf, txbytes, rxbuf, rxbytes, timeout); if (rdymsg == MSG_TIMEOUT) i2cp->state = I2C_LOCKED; else i2cp->state = I2C_READY; osalSysUnlock(); return rdymsg; } /** * @brief Receives data from the I2C bus. * * @param[in] i2cp pointer to the @p I2CDriver object * @param[in] addr slave device address (7 bits) without R/W bit * @param[out] rxbuf pointer to receive buffer * @param[in] rxbytes number of bytes to be received * @param[in] timeout the number of ticks before the operation timeouts, * the following special values are allowed: * - @a TIME_INFINITE no timeout. * . * * @return The operation status. * @retval MSG_OK if the function succeeded. * @retval MSG_RESET if one or more I2C errors occurred, the errors can * be retrieved using @p i2cGetErrors(). * @retval MSG_TIMEOUT if a timeout occurred before operation end. * * @api */ msg_t i2cMasterReceiveTimeout(I2CDriver *i2cp, i2caddr_t addr, uint8_t *rxbuf, size_t rxbytes, systime_t timeout){ msg_t rdymsg; osalDbgCheck((i2cp != NULL) && (addr != 0) && (rxbytes > 0) && (rxbuf != NULL) && (timeout != TIME_IMMEDIATE)); osalDbgAssert(i2cp->state == I2C_READY, "not ready"); osalSysLock(); i2cp->errors = I2C_NO_ERROR; i2cp->state = I2C_ACTIVE_RX; rdymsg = i2c_lld_master_receive_timeout(i2cp, addr, rxbuf, rxbytes, timeout); if (rdymsg == MSG_TIMEOUT) i2cp->state = I2C_LOCKED; else i2cp->state = I2C_READY; osalSysUnlock(); return rdymsg; } #if I2C_USE_MUTUAL_EXCLUSION || defined(__DOXYGEN__) /** * @brief Gains exclusive access to the I2C bus. * @details This function tries to gain ownership to the SPI bus, if the bus * is already being used then the invoking thread is queued. * @pre In order to use this function the option @p I2C_USE_MUTUAL_EXCLUSION * must be enabled. * * @param[in] i2cp pointer to the @p I2CDriver object * * @api */ void i2cAcquireBus(I2CDriver *i2cp) { osalDbgCheck(i2cp != NULL); osalMutexLock(&i2cp->mutex); } /** * @brief Releases exclusive access to the I2C bus. * @pre In order to use this function the option @p I2C_USE_MUTUAL_EXCLUSION * must be enabled. * * @param[in] i2cp pointer to the @p I2CDriver object * * @api */ void i2cReleaseBus(I2CDriver *i2cp) { osalDbgCheck(i2cp != NULL); osalMutexUnlock(&i2cp->mutex); } #endif /* I2C_USE_MUTUAL_EXCLUSION */ #endif /* HAL_USE_I2C */ /** @} */ ' href='#n165'>165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 
(**Note:** If you get compiler errors that you don't understand, be sure to consult [Google Mock Doctor](http://code.google.com/p/googlemock/wiki/V1_6_FrequentlyAskedQuestions#How_am_I_supposed_to_make_sense_of_these_horrible_template_error).)

# What Is Google C++ Mocking Framework? #
When you write a prototype or test, often it's not feasible or wise to rely on real objects entirely. A **mock object** implements the same interface as a real object (so it can be used as one), but lets you specify at run time how it will be used and what it should do (which methods will be called? in which order? how many times? with what arguments? what will they return? etc).

**Note:** It is easy to confuse the term _fake objects_ with mock objects. Fakes and mocks actually mean very different things in the Test-Driven Development (TDD) community:

  * **Fake** objects have working implementations, but usually take some shortcut (perhaps to make the operations less expensive), which makes them not suitable for production. An in-memory file system would be an example of a fake.
  * **Mocks** are objects pre-programmed with _expectations_, which form a specification of the calls they are expected to receive.

If all this seems too abstract for you, don't worry - the most important thing to remember is that a mock allows you to check the _interaction_ between itself and code that uses it. The difference between fakes and mocks will become much clearer once you start to use mocks.

**Google C++ Mocking Framework** (or **Google Mock** for short) is a library (sometimes we also call it a "framework" to make it sound cool) for creating mock classes and using them. It does to C++ what [jMock](http://www.jmock.org/) and [EasyMock](http://www.easymock.org/) do to Java.

Using Google Mock involves three basic steps:

  1. Use some simple macros to describe the interface you want to mock, and they will expand to the implementation of your mock class;
  1. Create some mock objects and specify its expectations and behavior using an intuitive syntax;
  1. Exercise code that uses the mock objects. Google Mock will catch any violation of the expectations as soon as it arises.

# Why Google Mock? #
While mock objects help you remove unnecessary dependencies in tests and make them fast and reliable, using mocks manually in C++ is _hard_:

  * Someone has to implement the mocks. The job is usually tedious and error-prone. No wonder people go great distance to avoid it.