1 /****************************************************************************** 2 * * 3 * License Agreement * 4 * * 5 * Copyright (c) 2016 Altera Corporation, San Jose, California, USA. * 6 * All rights reserved. * 7 * * 8 * Permission is hereby granted, free of charge, to any person obtaining a * 9 * copy of this software and associated documentation files (the "Software"), * 10 * to deal in the Software without restriction, including without limitation * 11 * the rights to use, copy, modify, merge, publish, distribute, sublicense, * 12 * and/or sell copies of the Software, and to permit persons to whom the * 13 * Software is furnished to do so, subject to the following conditions: * 14 * * 15 * The above copyright notice and this permission notice shall be included in * 16 * all copies or substantial portions of the Software. * 17 * * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * 19 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * 20 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * 21 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * 22 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING * 23 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER * 24 * DEALINGS IN THE SOFTWARE. * 25 * * 26 * * 27 ******************************************************************************/ 28 29 /*! \file 30 * Altera Avalon I2C Controller API 31 */ 32 33 #ifndef __ALT_AVALON_I2C_H__ 34 #define __ALT_AVALON_I2C_H__ 35 36 #include <stddef.h> 37 #include <errno.h> 38 39 #include "sys/alt_dev.h" 40 #include "alt_types.h" 41 #include "altera_avalon_i2c_regs.h" 42 #include "os/alt_sem.h" 43 #include "os/alt_flag.h" 44 45 #ifdef __cplusplus 46 extern "C" 47 { 48 #endif /* __cplusplus */ 49 50 /* 51 * The function alt_find_dev() is used to search the device list "list" to 52 * locate a device named "name". If a match is found, then a pointer to the 53 * device is returned, otherwise NULL is returned. 54 */ 55 extern alt_dev* alt_find_dev (const char* name, alt_llist* list); 56 57 /* Callback routine type definition */ 58 typedef void (*alt_avalon_i2c_callback)(void *context); 59 60 /******************************************************************************/ 61 /*! \addtogroup ALT_AVALON_I2C I2C Controller API 62 * 63 * This document defines the API for configuring and managing the Avalon I2C controller. 64 * 65 * The I2C controller provides support for a communication link between integrated 66 * circuits on a board. It is a simple two-wire bus which consists of a serial 67 * data line (SDA) and a serial clock (SCL) for use in applications such as 68 * temperature sensors and voltage level translators to EEPROMs, A/D and D/A 69 * converters, CODECs, and many types of microprocessors. 70 * 71 * The Avalon (FPGA) I2C controller IP enables system 72 * software to communicate serially with I2C buses. Each I2C controller can 73 * operate in master mode only, and supports standard mode of up to 100 74 * kilobits per second (Kbps) or fast mode of up to 400 Kbps. 75 * 76 * 77 * Features of the I2C Controller: 78 * * Supports both 100 KBps and 400 KBps modes 79 * * Supports I2C master mode 80 * * Support both 7-bit and 10-bit addressing modes 81 * * Mixed read and write combined-format transactions 82 * * Bulk transmit and receive 83 * * Interrupt support 84 * * CMD and RX Fifos 85 * 86 * For complete details on the configuration and operation of the I2C controller, 87 * consult the following references: 88 * * <em>Altera Avalon I2C Core Functional Description</em> 89 * 90 * @{ 91 */ 92 93 94 95 /* Status Codes */ 96 typedef alt_u32 ALT_AVALON_I2C_STATUS_CODE; 97 #define ALT_AVALON_I2C_TRUE (1) 98 #define ALT_AVALON_I2C_FALSE (0) 99 #define ALT_AVALON_I2C_SUCCESS (0) 100 #define ALT_AVALON_I2C_ERROR (-1) 101 #define ALT_AVALON_I2C_TIMEOUT (-2) 102 #define ALT_AVALON_I2C_BAD_ARG (-3) 103 #define ALT_AVALON_I2C_RANGE (-4) 104 #define ALT_AVALON_I2C_NACK_ERR (-5) 105 #define ALT_AVALON_I2C_ARB_LOST_ERR (-6) 106 #define ALT_AVALON_I2C_BUSY (-7) 107 108 /******************************************************************************/ 109 /*! \addtogroup INSTANCEFUNCTIONS I2C Instance Init Functions 110 * 111 * These functions are used by the system structure when initializing 112 * the I2C instance. These functions are not typically called by a 113 * user of the I2C IP except for the alt_avalon_i2c_open() 114 * function which is required to obtain a pointer to the desired I2C 115 * instance. 116 * 117 * @{ 118 */ 119 120 /* constant used in the alt_avalon_i2c_send_address routine */ 121 #define TARGET_ADDR_MASK_10BIT 0x7800 122 123 /*! 124 * This type enumerates the two addressing modes formats supported by the I2C 125 * controller. 126 * 127 * The I2C controller does not support mixed address format - that is, a 7-bit 128 * address transaction followed by a 10-bit address transaction or vice versa - 129 * combined format transactions. 130 */ 131 typedef enum ALT_AVALON_I2C_ADDR_MODE_e 132 { 133 ALT_AVALON_I2C_ADDR_MODE_7_BIT = 0, 134 /*!< 7-Bit Address Format */ 135 ALT_AVALON_I2C_ADDR_MODE_10_BIT = 1 136 /*!< 10-Bit Address Format */ 137 } ALT_AVALON_I2C_ADDR_MODE_t; 138 139 /*! 140 * A pointer or handle to the I2C controller device instance. The ALT_AVALON_I2C_DEV_t is 141 * initialized by a call to alt_avalon_i2c_init() and subsequently used by the other I2C 142 * controller API functions as a reference to a specific device. 143 * 144 */ 145 typedef struct ALT_AVALON_I2C_DEV_s 146 { 147 148 alt_llist llist; 149 /*!< Device linked-list entry */ 150 const char *name; 151 /*!< Name of i2c in Qsys system */ 152 alt_u32 *i2c_base; 153 /*!< Base address of regs */ 154 alt_u32 irq_controller_ID; 155 /*!< device IRQ controller ID */ 156 alt_u32 irq_ID; 157 /*!< device IRQ ID */ 158 alt_avalon_i2c_callback callback; 159 /*!< Callback routine pointer */ 160 void *callback_context; 161 /*!< Callback context pointer */ 162 alt_u32 control; 163 /*!< user define control setting during interrupt registering*/ 164 alt_u32 master_target_address; 165 /*!< master target address */ 166 alt_u32 cmd_fifo_size; 167 /*!< cmd fifo */ 168 alt_u32 rx_fifo_size; 169 /*!< rx fifo */ 170 alt_u32 ip_freq_in_hz; 171 /*!< freq of clock to ip */ 172 ALT_AVALON_I2C_ADDR_MODE_t address_mode; 173 /*!< address mode 7 or 10 bit */ 174 ALT_SEM (regs_lock); 175 /*!< Semaphore used to control access registers 176 in multi-threaded mode */ 177 } ALT_AVALON_I2C_DEV_t; 178 179 /*! 180 * The allocation of the ALT_AVALON_I2C_DEV_t structure memory 181 * and initial settings. 182 * 183 */ 184 #define ALTERA_AVALON_I2C_INSTANCE(name, dev) \ 185 static ALT_AVALON_I2C_DEV_t dev = \ 186 { \ 187 ALT_LLIST_ENTRY, \ 188 name##_NAME, \ 189 ((alt_u32 *)(name##_BASE)), \ 190 ((alt_u32)(name##_IRQ_INTERRUPT_CONTROLLER_ID)), \ 191 ((alt_u32)(name##_IRQ)), \ 192 ((void *) 0x0), \ 193 ((void *) 0x0), \ 194 ((alt_u32)(0)), \ 195 ((alt_u32)(0)), \ 196 ((alt_u32)(name##_FIFO_DEPTH)), \ 197 ((alt_u32)(name##_FIFO_DEPTH)), \ 198 ((alt_u32)(name##_FREQ)), \ 199 ((ALT_AVALON_I2C_ADDR_MODE_t)(0)), \ 200 }; 201 202 /*! 203 * Initialize the specified I2C controller instance. This routine is called from the 204 * ALTERA_AVALON_I2C_INIT macro and is called automatically by alt_sys_init.c 205 * 206 * This routine disables interrupts, 207 * registers a specific instance of the device with the HAL, 208 * and installs an interrupt handler for the device. 209 * 210 * \param i2c_dev 211 * The Avalon FPGA I2C controller instance to initialize. 212 * 213 * 214 */ 215 void alt_avalon_i2c_init(ALT_AVALON_I2C_DEV_t *i2c_dev); 216 217 /* 218 * The macro ALTERA_AVALON_I2C_INIT is called by the auto-generated function 219 * alt_sys_init() to initialize a given device instance. 220 */ 221 #define ALTERA_AVALON_I2C_INIT(name, dev) alt_avalon_i2c_init(&dev); 222 223 /*! 224 * Retrieve a pointer to the i2c block instance 225 * Search the list of registered i2c instances for one with the supplied name. 226 * 227 * \retval NULL The return value will be NULL on failure 228 * \retval non-NULL Success, ptr to i2c device instance returned. 229 * 230 * \param *name Character pointer to name of i2c peripheral as registered 231 * with the HAL. For example, an i2c controller named "i2c_0" 232 * in Qsys would be opened by asking for "/dev/i2c_0". 233 * 234 */ 235 ALT_AVALON_I2C_DEV_t* alt_avalon_i2c_open(const char* name); 236 237 /*! @} */ 238 239 /******************************************************************************/ 240 /*! \addtogroup SPEEDANDTIMINGFUNCTIONS Speed and Timing Configuration Functions 241 * 242 * These functions are used to set the Speed and Timing parameters. 243 * The ALT_AVALON_I2C_MASTER_CONFIG_t structure 244 * is used to set or get the speed, address mode, and scl/sda timing counts of the instance. 245 * The timing parameters can be set or retrieved in terms of Hz by using the 246 * alt_avalon_i2c_master_config_speed_get and alt_avalon_i2c_master_config_speed_set functions. 247 * 248 * @{ 249 */ 250 251 /*! 252 * This type enumerates the I2C controller operational speed modes. 253 * 254 * The I2C controller can operate in standard mode (with data rates 0 to 100 Kbps) 255 * or fast mode (with data rates less than or equal to 400 Kbps). Additionally, 256 * fast mode devices are downward compatible. For instance, fast mode devices can 257 * communicate with standard mode devices in 0 to 100 Kbps I2C bus 258 * system. However, standard mode devices are not upward compatible and should not 259 * be incorporated in a fast-mode I2C bus system as they cannot follow the higher 260 * transfer rate and therefore unpredictable states would occur. 261 * 262 */ 263 typedef enum ALT_AVALON_I2C_SPEED_e 264 { 265 ALT_AVALON_I2C_SPEED_STANDARD = 0, 266 /*!< Standard mode (0 to 100 Kbps) */ 267 ALT_AVALON_I2C_SPEED_FAST = 1 268 /*!< Fast mode (<= 400 Kbps) */ 269 } ALT_AVALON_I2C_SPEED_t; 270 271 /*! 272 * This type enumerates the I2C controller max min speeds in hz. 273 * 274 * The I2C controller can operate in standard mode (with data rates 0 to 100 Kbps) 275 * or fast mode (with data rates less than or equal to 400 Kbps). 276 * 277 */ 278 typedef enum ALT_AVALON_I2C_MAX_MIN_HZ_e 279 { 280 ALT_AVALON_I2C_FS_MAX_HZ = 400000, 281 /*!< Max speed is 400Khz */ 282 ALT_AVALON_I2C_FS_MIN_HZ = 100000, 283 /*!< Min speed is 100Khz */ 284 ALT_AVALON_I2C_SS_MAX_HZ = 100000, 285 /*!< Max speed is 100Khz */ 286 ALT_AVALON_I2C_SS_MIN_HZ = 1 287 /*!< Min speed is 1hz */ 288 } ALT_AVALON_I2C_MAX_MIN_HZ_t; 289 290 291 #define ALT_AVALON_I2C_DIFF_LCNT_HCNT 60 292 293 /*! 294 * This type defines a structure for configuration of the SCL high and low counts 295 * to ensure proper I/O timing with the device interface. 296 * 297 * See: Clock Frequency Configuration section of <em>Chapter 20. I2C 298 * Controller</em> in the <em>Cyclone V Device Handbook Volume 3: Hard 299 * Processor System Technical Reference Manual</em> for a complete discussion 300 * of calculation of the proper SCL clock high and low times. 301 */ 302 typedef struct ALT_AVALON_I2C_MASTER_CONFIG_s 303 { 304 ALT_AVALON_I2C_ADDR_MODE_t addr_mode; 305 /*!< The address mode (7 or 10 bit) when 306 * acting as a master. 307 */ 308 ALT_AVALON_I2C_SPEED_t speed_mode; 309 /*!< The speed mode of the I2C operation. 310 */ 311 alt_u16 scl_hcnt; 312 /*!< The SCL clock high-period count. 313 */ 314 alt_u16 scl_lcnt; 315 /*!< The SCL clock low-period count. 316 */ 317 alt_u16 sda_cnt; 318 /*!< The SDA clock hold count. 319 */ 320 } ALT_AVALON_I2C_MASTER_CONFIG_t; 321 322 /*! 323 * Populates the master mode configuration structure (type ALT_AVALON_I2C_ADDR_MODE_t) from registers. 324 * 325 * \param i2c_dev 326 * A pointer to the I2C controller device block instance. 327 * 328 * \param cfg 329 * [out] Pointer to a ALT_AVALON_I2C_MASTER_CONFIG_t structure for holding 330 * the returned I2C master mode configuration parameters. 331 * 332 * 333 */ 334 void alt_avalon_i2c_master_config_get(ALT_AVALON_I2C_DEV_t *i2c_dev, 335 ALT_AVALON_I2C_MASTER_CONFIG_t* cfg); 336 337 /*! 338 * Sets the registers based on the master mode configuration structure (type ALT_AVALON_I2C_ADDR_MODE_t). 339 * 340 * \param i2c_dev 341 * A pointer to the I2C controller device block instance. 342 * 343 * \param cfg 344 * Pointer to a ALT_AVALON_I2C_MASTER_CONFIG_t structure holding the desired 345 * I2C master mode operational parameters. 346 * 347 * 348 */ 349 void alt_avalon_i2c_master_config_set(ALT_AVALON_I2C_DEV_t *i2c_dev, 350 const ALT_AVALON_I2C_MASTER_CONFIG_t* cfg); 351 352 /*! 353 * This utility function returns the speed in hz based on the contents of the passed in configuration structure. 354 * 355 * \param i2c_dev 356 * A pointer to the I2C controller device block instance. 357 * 358 * \param cfg 359 * A pointer to a master configuration structure. 360 * 361 * \param speed_in_hz 362 * [out] Speed (Hz) the I2C bus is currently configured at based on 363 * the cfg structure (not necessarily on the hardware settings). 364 * To get the hardware speed first populate the cfg structure 365 * with the alt_avalon_i2c_master_config_get() function. 366 * 367 * \retval ALT_AVALON_I2C_STATUS_CODE 368 * ALT_AVALON_I2C_SUCCESS indicates successful status 369 * otherwise one of the ALT_AVALON_I2C_* status codes 370 * is returned. All failing return values are < 0. 371 */ 372 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_master_config_speed_get(ALT_AVALON_I2C_DEV_t *i2c_dev, 373 const ALT_AVALON_I2C_MASTER_CONFIG_t* cfg, 374 alt_u32 * speed_in_hz); 375 376 /*! 377 * This is a utility function that computes parameters for the I2C master 378 * configuration that best matches the speed requested. Only the cfg 379 * structure passed in is modified. 380 * 381 * \param i2c_dev 382 * A pointer to the I2C controller device block instance. 383 * 384 * \param cfg 385 * A pointer to a master configuration structure. 386 * 387 * \param speed_in_hz 388 * Desired Speed (Hz) of the I2C bus. 389 * 390 * \retval ALT_AVALON_I2C_STATUS_CODE 391 * ALT_AVALON_I2C_SUCCESS indicates successful status 392 * otherwise one of the ALT_AVALON_I2C_* status codes 393 * is returned. All failing return values are < 0. 394 * 395 */ 396 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_master_config_speed_set(ALT_AVALON_I2C_DEV_t *i2c_dev, 397 ALT_AVALON_I2C_MASTER_CONFIG_t * cfg, 398 alt_u32 speed_in_hz); 399 400 /*! @} */ 401 402 /******************************************************************************/ 403 /*! \addtogroup HELPERFUNCTIONS Helper Functions 404 * 405 * These helper functions are used by the I2C transaction functions. 406 * 407 * @{ 408 */ 409 410 /* Descriptive Constants */ 411 #define ALT_AVALON_I2C_READ (1) 412 #define ALT_AVALON_I2C_WRITE (0) 413 #define ALT_AVALON_I2C_NO_RESTART (0) 414 #define ALT_AVALON_I2C_NO_STOP (0) 415 #define ALT_AVALON_I2C_RESTART (1) 416 #define ALT_AVALON_I2C_STOP (1) 417 #define ALT_AVALON_I2C_USE_INTERRUPTS (1) 418 #define ALT_AVALON_I2C_NO_INTERRUPTS (0) 419 420 /*! 421 * Disables the I2C controller. 422 * 423 * When the I2C controller is disabled, the TX_READY_EN interrupt is cleared. 424 * However, the IP is not designed to be able to disable the IP in the middle 425 * of a transaction so this should be avoided. This disable function must 426 * be done at the end of every START -> STOP sequence. 427 * Before doing this function, wait for the IP to not be busy using the 428 * alt_avalon_i2c_is_busy function. 429 * 430 * \param i2c_dev 431 * A pointer to the I2C controller device block instance. 432 * 433 * 434 */ 435 void alt_avalon_i2c_disable(ALT_AVALON_I2C_DEV_t *i2c_dev); 436 437 /*! 438 * Enables the I2C controller. This function is done at the beginning of 439 * every START->STOP sequence. 440 * This function returns ALT_AVALON_I2C_BUSY status if the ip is already 441 * enabled. In that case nothing is done. 442 * 443 * \param i2c_dev 444 * A pointer to the I2C controller device block instance. 445 * 446 * \retval ALT_AVALON_I2C_BUSY 447 * Indicates the I2C controller is already enabled. 448 * \retval ALT_AVALON_I2C_SUCCESS 449 * Indicates the I2C controller has been successfully enabled. 450 * 451 */ 452 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_enable(ALT_AVALON_I2C_DEV_t *i2c_dev); 453 454 /*! 455 * Returns ALT_AVALON_I2C_TRUE if the I2C controller is busy. The I2C controller is busy if 456 * not in the IDLE state 457 * 458 * \param i2c_dev 459 * A pointer to the I2C controller device block instance. 460 * 461 * \retval ALT_AVALON_I2C_TRUE 462 * Indicates the I2C controller is busy. 463 * \retval ALT_AVALON_I2C_FALSE 464 * Indicates the I2C controller is not busy. 465 * 466 */ 467 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_is_busy(ALT_AVALON_I2C_DEV_t *i2c_dev); 468 469 /*! 470 * This function reads all available bytes from the receive FIFO, up to max_bytes_to_read. 471 * If max_bytes_to_read is 0, then all available bytes are read. 472 * 473 * This function is used to perform low level access to the data bytes 474 * received by the I2C controller and buffered in the receive FIFO. It 475 * may be used by master-receivers or slave receivers. 476 * 477 * 478 * \param i2c_dev 479 * A pointer to the I2C controller device block instance. 480 * 481 * \param buffer 482 * [out]The buffer to receive the read data. 483 * 484 * \param max_bytes_to_read 485 * The maximum number of bytes to be read. If 0 then all available bytes are read. 486 * 487 * \param bytes_read 488 * [out] Pointer to variable indicating the number of bytes read. 489 */ 490 void alt_avalon_i2c_rx_read_available(ALT_AVALON_I2C_DEV_t *i2c_dev, alt_u8 *buffer, alt_u32 max_bytes_to_read, alt_u32 *bytes_read); 491 492 /*! 493 * This function reads a single data byte from the receive FIFO. 494 * 495 * This function is used to perform low level access to the data bytes 496 * received by the I2C controller and buffered in the receive FIFO. It 497 * may be used by master-receivers or slave receivers. 498 * 499 * This function checks for valid data in the receive FIFO 500 * before reading the byte. 501 * 502 * \param i2c_dev 503 * A pointer to the I2C controller device block instance. 504 * 505 * \param val 506 * [out] The single data byte read from the receive FIFO. 507 * 508 * \retval ALT_AVALON_I2C_STATUS_CODE 509 * ALT_AVALON_I2C_SUCCESS indicates successful status 510 * otherwise one of the ALT_AVALON_I2C_* status codes 511 * is returned. All failing return values are < 0. 512 * 513 */ 514 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_rx_read(ALT_AVALON_I2C_DEV_t *i2c_dev, alt_u8 *val); 515 516 /*! 517 * This function writes the Transfer Command FIFO. 518 * 519 * This function is used to perform low level writes of data to the 520 * Transfer Command FIFO for transmission by the I2C controller. 521 * The value written includes the Stop and Start bits. 522 * 523 * This function checks for there to be space in Transfer Command FIFO 524 * before writing the register. 525 * 526 * \param i2c_dev 527 * A pointer to the I2C controller device block instance. 528 * 529 * \param val 530 * The data to write to the Transfer Command FIFO. 531 * 532 * \retval ALT_AVALON_I2C_STATUS_CODE 533 * ALT_AVALON_I2C_SUCCESS indicates successful status 534 * otherwise one of the ALT_AVALON_I2C_* status codes 535 * is returned. All failing return values are < 0. 536 * 537 */ 538 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_cmd_write(ALT_AVALON_I2C_DEV_t *i2c_dev, 539 alt_u8 val, 540 alt_u8 issue_restart, 541 alt_u8 issue_stop); 542 543 544 /*! @} */ 545 546 /******************************************************************************/ 547 /*! \addtogroup TARGETADDRESSFUNCTIONS Target Address Functions 548 * 549 * The I2C target address is the address the I2C device being accessed will respond to. 550 * This is a 7 or 10 bit value. alt_avalon_i2c_send_address() will update the 551 * transfer command register with a value containing the target, direction, and restart 552 * bits. 553 * 554 * The alt_avalon_i2c_master_target_set() and alt_avalon_i2c_master_target_get() functions 555 * will set or get the target address that will be used in future I2C transactions. 556 * 557 * The target address must be set before doing any I2C functions. Once set it does not have 558 * to be set again unless changing the device being accessed. 559 * 560 * @{ 561 */ 562 563 /*! 564 * This function sends the address and write or read command with optional 565 * restart bit to the Transfer Command Fifo. If the command 566 * fifo is full the command will wait until space is available. The command 567 * sequence will be 7 or 10 bit depending on the address mode setting. 568 * 569 * \param i2c_dev 570 * A pointer to the I2C controller device block instance. 571 * 572 * \param rw_bit 573 * The I2C Read (1) or Write(0) bit. 574 * 575 * \param issue_restart 576 * If issue_restart is 1, a restart is issued. 577 * 578 * \retval ALT_AVALON_I2C_STATUS_CODE 579 * ALT_AVALON_I2C_SUCCESS indicates successful status 580 * otherwise one of the ALT_AVALON_I2C_* status codes 581 * is returned. All failing return values are < 0. 582 */ 583 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_send_address(ALT_AVALON_I2C_DEV_t *i2c_dev,const alt_u32 rw_bit,const alt_u8 issue_restart); 584 585 /*! 586 * This function returns the current target address. 587 * 588 * 589 * \param i2c_dev 590 * A pointer to the I2C controller device block instance. 591 * 592 * \param target_addr 593 * [out] The 7 or 10 bit slave target address. 594 * 595 */ 596 void alt_avalon_i2c_master_target_get(ALT_AVALON_I2C_DEV_t * i2c_dev, alt_u32 * target_addr); 597 598 /*! 599 * This function updates the target address for any future I2C bus IO. 600 * 601 * This function does not wait for a bus idle state before changing the address. 602 * So is not suitable for being called from an interrupt routine. 603 * 604 * 605 * \param i2c_dev 606 * A pointer to the I2C controller device block instance. 607 * 608 * \param target_addr 609 * The 7 or 10 bit slave target address. 610 * 611 */ 612 void alt_avalon_i2c_master_target_set(ALT_AVALON_I2C_DEV_t * i2c_dev, alt_u32 target_addr); 613 /*! @} */ 614 615 /******************************************************************************/ 616 /*! \addtogroup Avalon I2C Transmit and Receive Functions 617 * 618 * The functions alt_avalon_i2c_master_transmit() and alt_avalon_i2c_master_receive() 619 * are the main functions for performing i2c transactions. These functions can be 620 * combined to create any combination of read-write operations within an I2C 621 * START to STOP sequence. 622 * There are also interrupt versions of the above functions, 623 * alt_avalon_i2c_master_transmit_using_interrupts() and alt_avalon_i2c_master_receive_using_interrupts(). 624 * Though the provided interrupt irq callback is functional and tested, it is mainly provided as an example 625 * starting point for a user to develop their own irq callback routine and to show how the 626 * user callback is registered and used. 627 * 628 * The above functions will return an ALT_AVALON_I2C_BUSY status if the ip is already enabled, 629 * and the function is being called with a START request (ie, restart parameter is not set). 630 * 631 * The functions alt_avalon_i2c_master_tx(), alt_avalon_i2c_master_rx(), and alt_avalon_i2c_master_tx_rx() 632 * are complete START to STOP sequence commands to simplify typical write and read operations and are 633 * basically wrappers for the alt_avalon_i2c_master_transmit() and alt_avalon_i2c_master_receive() functions. 634 * These wrapper functions will do automatic retry if the device is busy. 635 * 636 * @{ 637 */ 638 639 640 /*! 641 * This function transmits START followed by the I2C command 642 * byte(s). Then write requests are sent to fulfill the write request. The final 643 * transaction will issue a STOP. 644 * 645 * This API is not suitable for being called in an interrupt context as it may 646 * wait for certain controller states before completing. 647 * 648 * The target address must have been set before using this function. 649 * 650 * If an ALT_AVALON_I2C_ARB_LOST_ERR, ALT_AVALON_I2C_NACK_ERR, or ALT_AVALON_I2C_BUSY occurs the 651 * command will be retried. ALT_AVALON_I2C_NACK_ERR will occur when the slave 652 * device is not yet ready to accept more data. 653 * 654 * If the use_interrupts parameter is 1, then as soon as all bytes have been 655 * written to the command fifo this function will return. The interrupt handler 656 * will then handle waiting for the device to accept the data and will then complete the 657 * i2c transaction. To use this option the provided optional user interrupt handler 658 * callback must have been registered by calling the alt_avalon_i2c_register_optional_irq_handler 659 * function. 660 * 661 * \param i2c_dev 662 * A pointer to the I2C controller device block instance. 663 * 664 * \param buffer 665 * The data buffer to be sent. 666 * 667 * \param size 668 * The size of the data buffer to write to the I2C bus. 669 * 670 * \param use_interrupts 671 * The optional user interrupt handler callback will be used to handle 672 * sending the data. 673 * 674 * 675 * \retval ALT_AVALON_I2C_STATUS_CODE 676 * ALT_AVALON_I2C_SUCCESS indicates successful status 677 * otherwise one of the ALT_AVALON_I2C_* status codes 678 * is returned. All failing return values are < 0. 679 * 680 */ 681 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_master_tx(ALT_AVALON_I2C_DEV_t *i2c_dev, 682 const alt_u8 * buffer, 683 const alt_u32 size, 684 const alt_u8 use_interrupts); 685 686 687 /*! 688 * This function transmits START followed by the I2C command 689 * byte(s). Then read requests are sent to fulfill the read request. The final 690 * transaction will issue a STOP. 691 * 692 * This API is not suitable for being called in an interrupt context as it may 693 * wait for certain controller states before completing. 694 * 695 * The target address must have been set before using this function. 696 * 697 * If an ALT_AVALON_I2C_ARB_LOST_ERR, ALT_AVALON_I2C_NACK_ERR, ALT_AVALON_I2C_BUSY occurs the 698 * command will be retried. ALT_AVALON_I2C_NACK_ERR will occur when the slave 699 * device is not yet ready to accept more data. 700 * 701 * If the use_interrupts parameter is 1, then as soon as all cmd bytes have been 702 * written to the command fifo this function will return. The interrupt handler 703 * will then handle waiting for the device to send the rx data and will then complete the 704 * i2c transaction. To use this option the provided optional user interrupt handler 705 * callback must have been registered by calling the alt_avalon_i2c_register_optional_irq_handler 706 * function. 707 * 708 * \param i2c_dev 709 * A pointer to the I2C controller device block instance. 710 * 711 * \param buffer 712 * [out] The data buffer to be receive the i2c data. 713 * 714 * \param size 715 * The size of the data buffer to write to the I2C bus. 716 * 717 * \param use_interrupts 718 * The optional user interrupt handler callback will be used to handle 719 * receiving the data. 720 * 721 * \retval ALT_AVALON_I2C_STATUS_CODE 722 * ALT_AVALON_I2C_SUCCESS indicates successful status 723 * otherwise one of the ALT_AVALON_I2C_* status codes 724 * is returned. All failing return values are < 0. 725 * 726 */ 727 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_master_rx(ALT_AVALON_I2C_DEV_t *i2c_dev, 728 alt_u8 * buffer, 729 const alt_u32 size, 730 const alt_u8 use_interrupts); 731 732 733 /*! 734 * This function transmits START followed by the I2C command 735 * byte(s). Then write requests are sent to fulfill the write request. 736 * Then a RESTART is issued and read requests are sent until the read 737 * request is fulfilled. The final transaction will issue a STOP. 738 * 739 * This API is not suitable for being called in an interrupt context as it may 740 * wait for certain controller states before completing. 741 * 742 * The target address must have been set before using this function. 743 * 744 * If an ALT_AVALON_I2C_ARB_LOST_ERR, ALT_AVALON_I2C_NACK_ERR, or ALT_AVALON_I2C_BUSY occurs the 745 * command will be retried. ALT_AVALON_I2C_NACK_ERR will occur when the slave 746 * device is not yet ready to accept or send more data. 747 * 748 * This command will allow easy access of a device requiring an internal register 749 * address to be set before doing a read, for example an eeprom device. 750 * 751 * Example: If an eeprom requires a 2 byte address to be sent before doing a 752 * memory read, the tx buffer would contain the 2 byte address and the txsize 753 * would be set to 2. Then the rxbuffer will recieve the rxsize number of 754 * bytes to read from the eeprom as follows: 755 * To Read 0x10 bytes from eeprom at i2c address 0x51 into buffer: 756 * buffer[0]=2;buffer[1]=0; //set eeprom address 0x200 757 * alt_avalon_i2c_master_tx_rx(i2c_ptr,buffer,2,buffer,0x10,0); 758 * 759 * Notice the tx and rx buffer can be the same buffer if desired. 760 * 761 * If the use_interrupts parameter is 1, then as soon as all cmd bytes have been 762 * written to the command fifo this function will return. The interrupt handler 763 * will then handle waiting for the device to send the rx data and will then complete the 764 * i2c transaction. To use this option the provided optional user interrupt handler 765 * callback must have been registered by calling the alt_avalon_i2c_register_optional_irq_handler 766 * function. 767 * 768 * \param i2c_dev 769 * A pointer to the I2C controller device block instance. 770 * 771 * \param txdata 772 * The send data buffer. 773 * 774 * \param txsize 775 * The size of the send data buffer to write to the I2C bus. 776 * 777 * \param rxdata 778 * [out] The receive data buffer. 779 * 780 * \param rxsize 781 * The size of the receive data buffer. 782 * 783 * \param use_interrupts 784 * The optional user interrupt handler callback will be used to handle 785 * sending and receiving the data. 786 * 787 * \retval ALT_AVALON_I2C_STATUS_CODE 788 * ALT_AVALON_I2C_SUCCESS indicates successful status 789 * otherwise one of the ALT_AVALON_I2C_* status codes 790 * is returned. All failing return values are < 0. 791 * 792 */ 793 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_master_tx_rx(ALT_AVALON_I2C_DEV_t *i2c_dev, 794 const alt_u8 * txbuffer, 795 const alt_u32 txsize, 796 alt_u8 * rxbuffer, 797 const alt_u32 rxsize, 798 const alt_u8 use_interrupts); 799 800 /*! 801 * This function transmits either a START or RESTART followed by the I2C command 802 * byte(s). Then write requests are sent to fulfill the write request. The final 803 * transaction may issue a STOP depending on the issue_stop parameter. 804 * 805 * This API is not suitable for being called in an interrupt context as it may 806 * wait for certain controller states before completing. 807 * 808 * The target address must have been set before using this function. 809 * 810 * If the command returns ALT_AVALON_I2C_ARB_LOST_ERR, ALT_AVALON_I2C_NACK_ERR, or 811 * ALT_AVALON_I2C_BUSY, 812 * the caller is responsible to do a retry (if desired) by calling the function again. 813 * To automatically do a complete write sequence with retry use the 814 * alt_avalon_i2c_master_tx() function. 815 * 816 * 817 * \param i2c_dev 818 * A pointer to the I2C controller device block instance. 819 * 820 * \param data 821 * The data buffer to be sent. 822 * 823 * \param size 824 * The size of the data buffer to write to the I2C bus. 825 * 826 * \param issue_restart 827 * This parameter controls whether a RESTART or START is issued before 828 * the command byte is sent. If: 829 * * \b true \e a RESTART is issued before the command byte is sent. 830 * * \b false \e a START command is issued before the command byte(s) is sent. 831 * 832 * \param issue_stop 833 * This parameter controls whether a STOP is issued after the cmd data is 834 * sent. If: 835 * * \b true - STOP is issued after the final cmd byte is transmitted. 836 * * \b false - STOP is not issued. 837 * 838 * \retval ALT_AVALON_I2C_STATUS_CODE 839 * ALT_AVALON_I2C_SUCCESS indicates successful status 840 * otherwise one of the ALT_AVALON_I2C_* status codes 841 * is returned. All failing return values are < 0. 842 * 843 */ 844 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_master_transmit(ALT_AVALON_I2C_DEV_t *i2c_dev, 845 const alt_u8 * data, 846 alt_u32 size, 847 const alt_u8 issue_restart, 848 const alt_u8 issue_stop); 849 850 851 /*! 852 * This function transmits either a START or RESTART followed by the I2C command 853 * byte(s). Then write requests are sent to fulfill the write request. The final 854 * transaction may issue a STOP depending on the issue_stop parameter. 855 * 856 * This API is not suitable for being called in an interrupt context as it may 857 * wait for certain controller states before completing. 858 * 859 * The target address must have been set before using this function. 860 * 861 * If the command returns ALT_AVALON_I2C_ARB_LOST_ERR or ALT_AVALON_I2C_NACK_ERR or ALT_AVALON_I2C_BUSY, 862 * the caller is responsible to do a retry (if desired) by calling the function again. 863 * To automatically do a complete write sequence with retry use the 864 * alt_avalon_i2c_master_tx() function with the retry option set. 865 * 866 * As soon as all cmd bytes have been 867 * written to the command fifo this function will return. The interrupt handler 868 * will then handle waiting for the device to accept the data completing the 869 * i2c transaction. To use this option the provided optional user interrupt handler 870 * callback must have been registered by calling the alt_avalon_i2c_register_optional_irq_handler 871 * function. 872 * 873 * \param i2c_dev 874 * A pointer to the I2C controller device block instance. 875 * 876 * \param data 877 * The data buffer to be sent. 878 * 879 * \param size 880 * The size of the data buffer to write to the I2C bus. 881 * 882 * \param issue_restart 883 * This parameter controls whether a RESTART or START is issued before 884 * the command byte is sent. If: 885 * * \b true \e a RESTART is issued before the command byte is sent. 886 * * \b false \e a START command is issued before the command byte(s) is sent. 887 * 888 * \param issue_stop 889 * This parameter controls whether a STOP is issued after the cmd data is 890 * sent. If: 891 * * \b true - STOP is issued after the final cmd byte is transmitted. 892 * * \b false - STOP is not issued. 893 * 894 * \retval ALT_AVALON_I2C_STATUS_CODE 895 * ALT_AVALON_I2C_SUCCESS indicates successful status 896 * otherwise one of the ALT_AVALON_I2C_* status codes 897 * is returned. All failing return values are < 0. 898 * 899 */ 900 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_master_transmit_using_interrupts(ALT_AVALON_I2C_DEV_t *i2c_dev, 901 const alt_u8 * buffer, 902 alt_u32 size, 903 const alt_u8 issue_restart, 904 const alt_u8 issue_stop); 905 906 /*! 907 * This function transmits either a START or RESTART followed by the I2C command 908 * byte(s). Then read requests are sent to fulfill the read request. The final 909 * transaction may issue a STOP depending on the issue_stop parameter. 910 * 911 * This API is not suitable for being called in an interrupt context as it may 912 * wait for certain controller states before completing. 913 * 914 * The target address must have been set before using this function. 915 * 916 * If the command returns ALT_AVALON_I2C_ARB_LOST_ERR, ALT_AVALON_I2C_NACK_ERR, 917 * or ALT_AVALON_I2C_BUSY 918 * the caller is responsible to do a retry (if desired) by repeating the i2c 919 * transaction from the call that issued the START, which may not be this one. 920 * To automatically do a complete write-read sequence with retry use the 921 * alt_avalon_i2c_master_tx_rx() function with the retry option set. 922 * 923 * 924 * \param i2c_dev 925 * A pointer to the I2C controller device block instance. 926 * 927 * \param data 928 * [out] The data buffer to receive the requested \e size bytes. 929 * 930 * \param size 931 * The size of the data buffer to read from the RX FIFO. 932 * 933 * \param issue_restart 934 * This parameter controls whether a RESTART or START is issued before 935 * the command byte is sent. If: 936 * * \b true \e a RESTART is issued before the command byte is sent. 937 * * \b false \e a START command is issued before the command byte(s) is sent. 938 * 939 * \param issue_stop 940 * This parameter controls whether a STOP is issued after the cmd data is 941 * sent. If: 942 * * \b true - STOP is issued after the final cmd byte is transmitted. 943 * * \b false - STOP is not issued. 944 * 945 * \retval ALT_AVALON_I2C_STATUS_CODE 946 * ALT_AVALON_I2C_SUCCESS indicates successful status 947 * otherwise one of the ALT_AVALON_I2C_* status codes 948 * is returned. All failing return values are < 0. 949 * 950 */ 951 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_master_receive(ALT_AVALON_I2C_DEV_t *i2c_dev, 952 alt_u8 * data, 953 const alt_u32 size, 954 const alt_u8 issue_restart, 955 const alt_u8 issue_stop); 956 957 958 /*! 959 * This function transmits either a START or RESTART followed by the I2C command 960 * byte(s). Then read requests are sent to fulfill the read request. The final 961 * transaction may issue a STOP depending on the issue_stop parameter. 962 * 963 * This API is not suitable for being called in an interrupt context as it may 964 * wait for certain controller states before completing. 965 * 966 * The target address must have been set before using this function. 967 * 968 * If the command returns ALT_AVALON_I2C_ARB_LOST_ERR or ALT_AVALON_I2C_NACK_ERR or ALT_AVALON_I2C_BUSY 969 * the caller is responsible to do a retry (if desired) by repeating the i2c 970 * transaction from the call that issued the START, which may not be this one. 971 * To automatically do a complete write-read sequence with retry use the 972 * alt_avalon_i2c_master_tx_rx() function with the retry option set. 973 * 974 * As soon as all cmd bytes have been 975 * written to the command fifo this function will return. The interrupt handler 976 * will then handle waiting for the device to send the rx data and will then complete the 977 * i2c transaction. To use this option the provided optional user interrupt handler 978 * callback must have been registered by calling the alt_avalon_i2c_register_optional_irq_handler 979 * function. 980 * 981 * \param i2c_dev 982 * A pointer to the I2C controller device block instance. 983 * 984 * \param data 985 * [out] The data buffer to receive the requested \e size bytes. 986 * 987 * \param size 988 * The size of the data buffer to read from the RX FIFO. 989 * 990 * \param issue_restart 991 * This parameter controls whether a RESTART or START is issued before 992 * the command byte is sent. If: 993 * * \b true \e a RESTART is issued before the command byte is sent. 994 * * \b false \e a START command is issued before the command byte(s) is sent. 995 * 996 * \param issue_stop 997 * This parameter controls whether a STOP is issued after the cmd data is 998 * sent. If: 999 * * \b true - STOP is issued after the final cmd byte is transmitted. 1000 * * \b false - STOP is not issued. 1001 * 1002 * \retval ALT_AVALON_I2C_STATUS_CODE 1003 * ALT_AVALON_I2C_SUCCESS indicates successful status 1004 * otherwise one of the ALT_AVALON_I2C_* status codes 1005 * is returned. All failing return values are < 0. 1006 * 1007 */ 1008 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_master_receive_using_interrupts(ALT_AVALON_I2C_DEV_t *i2c_dev, 1009 alt_u8 * buffer, 1010 const alt_u32 size, 1011 const alt_u8 issue_restart, 1012 const alt_u8 issue_stop); 1013 1014 /*! @} */ 1015 1016 /******************************************************************************/ 1017 /*! \addtogroup ALT_AVALON_I2C_INT Interrupt and Status Conditions 1018 * 1019 * The functions in this group provide management for the I2C controller status 1020 * conditions and interrupts. 1021 * 1022 * Each I2C controller has a single combined interrupt output. 1023 * The following events can generate an interrupt: 1024 * * Arbitation lost 1025 * * NACK Detected 1026 * * Transmit Buffer Empty 1027 * * Receive Buffer Full 1028 * * Receive Overflow 1029 * 1030 * These interrupt status conditions may be monitored either by polling their 1031 * status or by configuring interrupt handlers. 1032 * 1033 * Functions to get the current status, enable or disable (i.e. mass or unmask), 1034 * and clear interrupt status conditions for the I2C controller are defined in 1035 * this section. 1036 * 1037 * @{ 1038 */ 1039 1040 /*! 1041 * This type enumerates interrupt status conditions for the I2C controller. 1042 */ 1043 typedef enum ALT_AVALON_I2C_ISR_e 1044 { 1045 ALT_AVALON_I2C_STATUS_RX_OVER = 1UL << 4, 1046 /*!< Set if the receive buffer is completely 1047 * filled to capacity and an additional byte is 1048 * received from an external I2C device. The I2C 1049 * controller acknowledges this, but any data 1050 * bytes received after the FIFO is full are 1051 * discarded. Writing 1 to this field clears the 1052 * contents to 0. 1053 */ 1054 ALT_AVALON_I2C_STATUS_ARBLOST_DET = 1UL << 3, 1055 /*!< This bit is set to 1 when the i2c controller 1056 * has lost the bus arbitration. Writing 1 to 1057 * this field clears the contents to 0. 1058 */ 1059 ALT_AVALON_I2C_NACK_DET = 1UL << 2, 1060 /*!< This bit is set to 1 when no acknowledgement 1061 * (NACK) is recieved by the i2c controller. The 1062 * MACK can be during the address or data transmission 1063 * phase. Writing 1 to 1064 * this field clears the contents to 0. 1065 */ 1066 ALT_AVALON_I2C_RX_READY = 1UL << 1, 1067 /*!< This bit indicates the RX_DATA fifo level is 1068 * equal or more than the RX_DATA fifo threshold. 1069 * It is automatically cleared when the RX_DATA fifo 1070 * level is less than the RX_DATA fifo threshold. 1071 */ 1072 ALT_AVALON_I2C_TX_READY = 1UL << 0, 1073 /*!< This bit indicates the Transfer Command FIFO is ready 1074 * for data transmission. This bit is asserted when the 1075 * Transfer Command FIFO level is equal to or less than the 1076 * Transfer Command FIFO threshold. 1077 */ 1078 } ALT_AVALON_I2C_STATUS_t; 1079 1080 /* A structure to be used with the optional provided irq callback function*/ 1081 typedef struct IRQ_DATA_s 1082 { 1083 alt_u8 * buffer; 1084 alt_u32 size; 1085 alt_u32 irq_busy; 1086 } IRQ_DATA_t; 1087 1088 /*! 1089 * Associate a user-specific routine with the i2c interrupt handler. 1090 * If a callback is registered, all enabled ISR's will cause the callback to be executed. 1091 * The callback runs as part of the interrupt service routine. 1092 * 1093 * An optional user callback routine is provided in this code and, if used, enables use 1094 * of the alt_avalon_i2c_master_receive_using_interrupts and alt_avalon_i2c_master_transmit_using_interrupts 1095 * functions. To register the optionally provided user callback use the alt_avalon_i2c_register_optional_irq_handler 1096 * function. 1097 * 1098 * \param dev Pointer to i2c device (instance) structure. 1099 * \param callback Pointer to callback routine to execute at interrupt level 1100 * \param control For masking the source interruption and setting configuration 1101 * \param context callback context 1102 * 1103 */ 1104 void alt_avalon_i2c_register_callback( 1105 ALT_AVALON_I2C_DEV_t *i2c_dev, 1106 alt_avalon_i2c_callback callback, 1107 alt_u32 control, 1108 void *context); 1109 1110 /*! 1111 * Associate the optional provided user interrupt callback routine with the i2c handler. 1112 * This is a simple IRQ callback which allows I2C transaction functions to immedietly return 1113 * while the optional callback handles receiving or transmitting the data to the device 1114 * and completing the transaction. This optional callback uses a IRQ_DATA_t structure for 1115 * irq data. The function alt_avalon_i2c_interrupt_transaction_status can be used to check 1116 * for irq transaction complete, or for an transaction error. 1117 * These optionally provided interrupt routines are functional, but are provided 1118 * mainly for the purpose as working examples of using interrupts with the avalon i2c ip. 1119 * A user may want to develop a more detailed irq callback routine tailored for specific 1120 * device hardware. In that case, the user callback would be registered with the 1121 * alt_avalon_i2c_register_callback function. 1122 * 1123 * Using this optionally provided user callback routine enables use 1124 * of the alt_avalon_i2c_master_receive_using_interrupts and alt_avalon_i2c_master_transmit_using_interrupts 1125 * functions. 1126 * 1127 * \param dev Pointer to i2c device (instance) structure. 1128 * 1129 * \param irq_data A structure used for interrupt handler data. 1130 * Nothing needs to be set in this structure by the 1131 * user. The storage merely has to be provided. 1132 * The irq_busy variable can be used to check if the 1133 * transaction is complete. In that case it will be 0. 1134 */ 1135 void alt_avalon_i2c_register_optional_irq_handler(ALT_AVALON_I2C_DEV_t *i2c_dev,IRQ_DATA_t * irq_data); 1136 1137 /*! 1138 * When an interrupt transaction has been initiated using the alt_avalon_i2c_master_tx, 1139 * alt_avalon_i2c_master_rx, or alt_avalon_i2c_master_tx_rx function with the interrupt 1140 * option set, or if using the alt_avalon_i2c_master_transmit_using_interrupts or 1141 * alt_avalon_i2c_master_receive_using_interrupts functions, then this function can be 1142 * used to check the status of that transaction. The only way to ensure error free 1143 * back to back transactions is to use this function after every interrupt transaction 1144 * to ensure the transaction had no errors and is complete, before starting the next transaction. 1145 * Also, if an error is returned from this function, then the user must retry the i2c transaction. 1146 * One reason an error may be returned is if the device is busy, which is likely to occur 1147 * occasionally if doing back to back transactions. 1148 * 1149 * \param dev Pointer to i2c device (instance) structure. 1150 * 1151 * \retval ALT_AVALON_I2C_STATUS_CODE 1152 * ALT_AVALON_I2C_SUCCESS indicates interrupt transaction is 1153 * successfully completed. Another transaction can now be 1154 * started. 1155 * 1156 * ALT_AVALON_I2C_BUSY indicates the interrupt transaction is still 1157 * busy. 1158 * 1159 * ALT_AVALON_NACK_ERROR indicates the device did not ack. This is 1160 * most likely because the device is busy with the previous transaction. 1161 * The transaction must be retried. 1162 * 1163 * otherwise one of the other ALT_AVALON_I2C_* status codes 1164 * is returned. The transaction must be retried. 1165 * 1166 * All failing return values are < 0. 1167 * 1168 */ 1169 ALT_AVALON_I2C_STATUS_CODE alt_avalon_i2c_interrupt_transaction_status(ALT_AVALON_I2C_DEV_t *i2c_dev); 1170 1171 /*! 1172 * This reads the raw NACK status bit regardless of whether or not the corresponding 1173 * interrupt is enabled. The function will update status if the NACK bit is set in the ISR reg/ 1174 * Otherwise nothing is done. 1175 * 1176 * 1177 * \param i2c_dev 1178 * A pointer to the I2C controller device block instance. 1179 * 1180 * \param status 1181 * [in][out] Set to ALT_AVALON_I2C_NACK_ERR if the NACK bit 1182 * in the ISR is set. Otherwise status is not modified. 1183 * 1184 */ 1185 void alt_avalon_i2c_check_nack(ALT_AVALON_I2C_DEV_t *i2c_dev,ALT_AVALON_I2C_STATUS_CODE * status); 1186 1187 /*! 1188 * This reads the raw ARBLOST status bit regardless of whether or not the corresponding 1189 * interrupt is enabled. This function will update status if the ARBLOST bit is set in the ISR reg 1190 * Otherwise nothing is done. 1191 * 1192 * 1193 * \param i2c_dev 1194 * A pointer to the I2C controller device block instance. 1195 * 1196 * \param status 1197 * [in][out] Set to ALT_AVALON_I2C_ARB_LOST_ERR if the ARBLOST bit 1198 * in the ISR is set. Otherwise, status is not modified. 1199 * 1200 */ 1201 void alt_avalon_i2c_check_arblost(ALT_AVALON_I2C_DEV_t *i2c_dev,ALT_AVALON_I2C_STATUS_CODE * status); 1202 1203 /*! 1204 * Returns the current I2C controller interrupt status conditions. 1205 * 1206 * This function returns the current value of the I2C controller interrupt status 1207 * register value which reflects the current I2C controller status conditions that 1208 * are not disabled (i.e. masked). 1209 * 1210 * \param i2c_dev 1211 * A pointer to the I2C controller device block instance. 1212 * 1213 * \param status 1214 * [out] A pointer to a bit mask of the active \ref ALT_AVALON_I2C_STATUS_t 1215 * interrupt and status conditions. 1216 * 1217 */ 1218 void alt_avalon_i2c_int_status_get(ALT_AVALON_I2C_DEV_t *i2c_dev, 1219 alt_u32 *status); 1220 1221 /*! 1222 * Returns the I2C controller raw interrupt status conditions irrespective of 1223 * the interrupt status condition enablement state. 1224 * 1225 * This function returns the current value of the I2C controller raw interrupt 1226 * status register value which reflects the current I2C controller status 1227 * conditions regardless of whether they are disabled (i.e. masked) or not. 1228 * 1229 * \param i2c_dev 1230 * A pointer to the I2C controller device block instance. 1231 * 1232 * \param status 1233 * [out] A pointer to a bit mask of the active \ref ALT_AVALON_I2C_STATUS_t 1234 * interrupt and status conditions. 1235 * 1236 * 1237 */ 1238 void alt_avalon_i2c_int_raw_status_get(ALT_AVALON_I2C_DEV_t *i2c_dev, 1239 alt_u32 *status); 1240 1241 /*! 1242 * Clears the specified I2C controller interrupt status conditions identified 1243 * in the mask. 1244 * 1245 * This function clears one or more of the status conditions as contributors to 1246 * the IRQ interrupt signal state. 1247 * 1248 * \param i2c_dev 1249 * A pointer to the I2C controller device block instance. 1250 * 1251 * \param mask 1252 * Specifies the interrupt status conditions to clear. \e mask 1253 * is a mask of logically OR'ed \ref ALT_AVALON_I2C_STATUS_t values that 1254 * designate the status conditions to clear. 1255 * 1256 */ 1257 void alt_avalon_i2c_int_clear(ALT_AVALON_I2C_DEV_t *i2c_dev, const alt_u32 mask); 1258 1259 /*! 1260 * Disable the specified I2C controller interrupt status conditions identified in 1261 * the mask. 1262 * 1263 * This function disables one or more of the status conditions as contributors to 1264 * the \b ALT_INT_INTERRUPT_I2C<em>n</em>_IRQ interrupt signal state. 1265 * 1266 * NOTE: A cleared bit for any status condition in the mask value does not have 1267 * the effect of enabling it as a contributor to the IRQ interrupt signal state. 1268 * The function alt_avalon_i2c_int_enable() is used to enable status source conditions. 1269 * 1270 * \param i2c_dev 1271 * A pointer to the I2C controller device block instance. 1272 * 1273 * \param mask 1274 * Specifies the status conditions to disable as interrupt source 1275 * contributors. \e mask is a mask of logically OR'ed \ref 1276 * ALT_AVALON_I2C_STATUS_t values that designate the status conditions to 1277 * disable. 1278 * 1279 * 1280 */ 1281 void alt_avalon_i2c_int_disable(ALT_AVALON_I2C_DEV_t *i2c_dev, const alt_u32 mask); 1282 1283 /*! 1284 * Enable the specified I2C controller interrupt status conditions identified in 1285 * the mask. 1286 * 1287 * This function enables one or more of the status conditions as contributors to 1288 * the IRQ interrupt signal state. 1289 * 1290 * NOTE: A cleared bit for any status condition in the mask value does not have 1291 * the effect of disabling it as a contributor to the IRQ interrupt signal state. 1292 * The function alt_avalon_i2c_int_disable() is used to disable status source conditions. 1293 * 1294 * \param i2c_dev 1295 * A pointer to the I2C controller device block instance. 1296 * 1297 * \param mask 1298 * Specifies the status conditions to enable as interrupt source 1299 * contributors. \e mask is a mask of logically OR'ed \ref 1300 * ALT_AVALON_I2C_STATUS_t values that designate the status conditions to 1301 * enable. 1302 * 1303 * 1304 */ 1305 void alt_avalon_i2c_int_enable(ALT_AVALON_I2C_DEV_t *i2c_dev, const alt_u32 mask); 1306 1307 /*! 1308 * Gets the Enabled Interrupts (reads the ISER register) 1309 * 1310 * 1311 * \param i2c_dev 1312 * A pointer to the I2C controller device block instance. 1313 * 1314 * \param enabled_ints 1315 * [out] A pointer to the variable to recieve the data. 1316 * 1317 * 1318 */ 1319 void alt_avalon_i2c_enabled_ints_get(ALT_AVALON_I2C_DEV_t *i2c_dev, alt_u32 * enabled_ints); 1320 1321 /*! @} */ 1322 1323 /******************************************************************************/ 1324 /*! \addtogroup ALT_AVALON_I2C_RX_FIFO RX FIFO Management 1325 * 1326 * The receive FIFO has a configurable threshold value that controls the level of 1327 * entries (or above) that sets the RX_READY status condition and triggers an 1328 * interrupt. The valid ranges are 1, 1/4 full, 1/2 full, or full. 1329 * 1330 * @{ 1331 */ 1332 1333 /*! 1334 * This type enumerates the RX_DATA_FIFO_THRESHOLD for the I2C controller. 1335 */ 1336 typedef enum ALT_AVALON_I2C_RX_DATA_FIFO_THRESHOLD_e 1337 { 1338 ALT_AVALON_I2C_RX_DATA_FIFO_1_ENTRY = 0, 1339 ALT_AVALON_I2C_RX_DATA_FIFO_1_4_FULL = 1, 1340 ALT_AVALON_I2C_RX_DATA_FIFO_1_2_FULL = 2, 1341 ALT_AVALON_I2C_RX_DATA_FIFO_FULL = 3, 1342 } ALT_AVALON_I2C_RX_DATA_FIFO_THRESHOLD_t; 1343 1344 /*! 1345 * Gets the current receive FIFO threshold level value. 1346 * 1347 * \param i2c_dev 1348 * A pointer to the I2C controller device block instance. 1349 * 1350 * \param threshold 1351 * [out] The current threshold value. 1352 * 1353 * 1354 */ 1355 void alt_avalon_i2c_rx_fifo_threshold_get(ALT_AVALON_I2C_DEV_t *i2c_dev, 1356 ALT_AVALON_I2C_RX_DATA_FIFO_THRESHOLD_t *threshold); 1357 1358 /*! 1359 * Sets the current receive FIFO threshold level value. 1360 * 1361 * \param i2c_dev 1362 * A pointer to the I2C controller device block instance. 1363 * 1364 * \param threshold 1365 * The threshold value. 1366 * 1367 * 1368 */ 1369 void alt_avalon_i2c_rx_fifo_threshold_set(ALT_AVALON_I2C_DEV_t *i2c_dev, 1370 const ALT_AVALON_I2C_RX_DATA_FIFO_THRESHOLD_t threshold); 1371 1372 /*! @} */ 1373 1374 /******************************************************************************/ 1375 /*! \addtogroup ALT_AVALON_I2C_TFR_CMD Transfer Command FIFO Management 1376 * 1377 * The Transfer Command FIFO has a configurable threshold value that controls the level of 1378 * entries (or below) that sets the TX_READY status condition and triggers an 1379 * interrupt. The valid range is empty, 1/4 full, 1/2 full, and not full (at least 1 empty entry) 1380 * 1381 * @{ 1382 */ 1383 1384 /*! 1385 * This type enumerates the TFR_CMD_FIFO_THRESHOLD for the I2C controller. 1386 */ 1387 typedef enum ALT_AVALON_I2C_TFR_CMD_FIFO_THRESHOLD_e 1388 { 1389 ALT_AVALON_I2C_TFR_CMD_FIFO_EMPTY = 0, 1390 ALT_AVALON_I2C_TFR_CMD_FIFO_1_4_FULL = 1, 1391 ALT_AVALON_I2C_TFR_CMD_FIFO_1_2_FULL = 2, 1392 ALT_AVALON_I2C_TFR_CMD_FIFO_NOT_FULL = 3, 1393 } ALT_AVALON_I2C_TFR_CMD_FIFO_THRESHOLD_t; 1394 1395 /*! 1396 * Gets the current Transfer Command FIFO threshold level value. 1397 * 1398 * \param i2c_dev 1399 * A pointer to the I2C controller device block instance. 1400 * 1401 * \param threshold 1402 * [out] The current threshold value. 1403 * 1404 * 1405 */ 1406 void alt_avalon_i2c_tfr_cmd_fifo_threshold_get(ALT_AVALON_I2C_DEV_t *i2c_dev, 1407 ALT_AVALON_I2C_TFR_CMD_FIFO_THRESHOLD_t *threshold); 1408 1409 1410 /*! 1411 * Sets the current Transfer Command FIFO threshold level value. 1412 * 1413 * \param i2c_dev 1414 * A pointer to the I2C controller device block instance. 1415 * 1416 * \param threshold 1417 * The threshold value. 1418 * 1419 * 1420 */ 1421 void alt_avalon_i2c_tfr_cmd_fifo_threshold_set(ALT_AVALON_I2C_DEV_t *i2c_dev, 1422 const ALT_AVALON_I2C_TFR_CMD_FIFO_THRESHOLD_t threshold); 1423 1424 1425 /*! @} */ 1426 1427 /*! @} */ 1428 1429 1430 #ifdef __cplusplus 1431 } 1432 #endif /* __cplusplus */ 1433 1434 #endif /* __ALTERA_AVALON_I2C_H__ */ 1435
