Overview Overview eCos Support for I2C, the Inter IC Bus The Inter IC Bus (I2C) is one of a number of serial bus technologies. It can be used to connect a processor to one or more peripheral chips, for example analog-to-digital convertors or real time clocks, using only a small number of pins and PCB tracks. The technology was originally developed by Philips Semiconductors but is supported by many other vendors. The bus specification is freely available. In a typical I2C system the processor acts as the I2C bus master. The peripheral chips act as slaves. The bus consists of just two wires: SCL carries a clock signal generated by the master, and SDA is a bi-directional data line. The normal clock frequency is 100KHz. Each slave has a 7-bit address. With some chips the address is hard-wired, and it is impossible to have two of these chips on the same bus. With other chips it is possible to choose between one of a small number of addresses by connecting spare pins to either VDD or GND. An I2C data transfer involves a number of stages: The bus master generates a start condition, a high-to-low transition on the SDA line while SCL is kept high. This signalling cannot occur during data transfer. The bus master clocks the 7-bit slave address onto the SDA line, followed by a direction bit to distinguish between reads and writes. The addressed device acknowledges. If the master does not see an acknowledgement then this suggests it is using the wrong address for the slave device. If the master is transmitting data to the slave then it will send this data one byte at a time. The slave acknowledges each byte. If the slave is unable to accept more data, for example because it has run out of buffer space, then it will generate a nack and the master should stop sending. If the master is receiving data from the slave then the slave will send this data one byte at a time. The master should acknowledge each byte, until the last one. When the master has received all the data it wants it should generate a nack and the slave will stop sending. This nack is essential because it causes the slave to stop driving the SDA line, releasing it back to the master. It is possible to switch direction in a single transfer, using what is known as a repeated start. This involves generating another start condition, sending the 7-bit address again, followed by a new direction bit. At the end of a transfer the master should generate a stop condition, a low-to-high transition on the SDA line while SCL is kept high. Again this signalling does not occur at other times. There are a number of extensions. The I2C bus supports multiple bus masters and there is an arbitration procedure to allow a master to claim the bus. Some devices can have 10-bit addresses rather than 7-bit addresses. There is a fast mode operating at 400KHz instead of the usual 100KHz, and a high-speed mode operating at 3.4MHz. Currently most I2C-based systems do not involve any of these extensions. At the hardware level I2C bus master support can be implemented in one of two ways. Some processors provide a dedicated I2C device, with the hardware performing much of the work. On other processors the I2C device is implemented in software, by bit-banging some GPIO pins. The latter approach can consume a significant number of cpu cycles, but is often acceptable because only occasional access to the I2C devices is needed. The eCos I2C support for any given platform is spread over a number of different packages: This package, CYGPKG_IO_I2C, exports a generic API for accessing devices attached to an I2C bus. This API handles issues such as locking between threads. The package does not contain any hardware-specific code. Instead it will use a separate I2C bus driver to handle the hardware, and it defines the interface that such bus drivers should provide. The package only provides support for a bus master, not for acting as a slave device. CYGPKG_IO_I2C also provides the hardware-independent portion of a bit-banged bus implementation. This needs to be complemented by a hardware-specific function that actually manipulates the SDA and SCL lines. If the processor has a dedicated I2C device then there will be a bus driver package for that hardware. The processor may be used on many different platforms and the same bus driver can be used on each one. The actual I2C devices attached to the bus will vary from one platform to the next. The generic API depends on cyg_i2c_device data structures. These contain the information needed by a bus driver, for example the device address. Usually the data structures are provided by the platform HAL since it is that package which knows about all the devices on the platform. On some development boards the I2C lines are brought out to expansion connectors, allowing end users to add extra devices. In such cases the platform HAL may not know about all the devices on the board. Data structures for the additional devices can instead be supplied by application code. If the board uses a bit-banged bus then typically the platform HAL will also instantiate the bus instance, providing the function that handles the low-level SDA and SCL manipulation. Usually this code cannot be shared because each board may use different GPIO pins for driving SCL and SDA, so the code belongs in the platform HAL rather than in a separate package. Some types of I2C devices may have their own driver package. For example a common type of I2C device is a battery-backed wallclock, and eCos defines how these devices should be supported. Such an I2C device will have its own wallclock device driver and the device will not be accessed directly by application code. For other types of device eCos does not define an API and there will not be separate device driver packages. Instead application code is expected to use the cyg_i2c_device structures directly to access the hardware. Typically all appropriate packages will be loaded automatically when you configure eCos for a given platform. If the application does not use any of the I2C I/O facilities, directly or indirectly, then linker garbage collection should eliminate all unnecessary code and data. All necessary initialization should happen automatically. However the exact details may depend on the platform, so the platform HAL documentation should be checked for further details. There is one important exception to this: if the I2C devices are attached to an expansion connector then the platform HAL will not know about these devices. Instead more work will have to be done by application code. I2C Interface I2C Functions allow applications and other packages to access I2C devices #include <cyg/io/i2c.h> cyg_uint32 cyg_i2c_tx const cyg_i2c_device* device const cyg_uint8* tx_data cyg_uint32 count cyg_uint32 cyg_i2c_rx const cyg_i2c_device* device cyg_uint8* rx_data cyg_uint32 count void cyg_i2c_transaction_begin const cyg_i2c_device* device cyg_bool cyg_i2c_transaction_begin_nb const cyg_i2c_device* device cyg_uint32 cyg_i2c_transaction_tx const cyg_i2c_device* device cyg_bool send_start const cyg_uint8* tx_data cyg_uint32 count cyg_bool send_stop cyg_uint32 cyg_i2c_transaction_rx const cyg_i2c_device* device cyg_bool send_start cyg_uint8* rx_data cyg_uint32 count cyg_bool send_nack cyg_bool send_stop void cyg_i2c_transaction_stop const cyg_i2c_device* device void cyg_i2c_transaction_end const cyg_i2c_device* device All I2C functions take a pointer to a cyg_i2c_device structure as their first argument. These structures are usually provided by the platform HAL. They contain the information needed by the I2C bus driver to interact with the device, for example the device address. An I2C transaction involves the following stages: Perform thread-level locking on the bus. Only one thread at a time is allowed to access an I2C bus. This eliminates the need to worry about locking at the bus driver level. If a platform involves multiple I2C buses then each one will have its own lock. Generate a start condition, send the address and direction bit, and wait for an acknowledgement from the addressed device. Either transmit data to or receive data from the addressed device. The previous two steps may be repeated several times, allowing data to move in both directions during a single transfer. Generate a stop condition, ending the current data transfer. It is now possible to start another data transfer while the bus is still locked, if desired. End the transaction by unlocking the bus, allowing other threads to access other devices on the bus. The simple functions cyg_i2c_tx and cyg_i2c_rx perform all these steps in a single call, making them suitable for many I/O operations. The alternative transaction-oriented functions provide greater control when appropriate, for example if a repeated start is necessary for a bi-directional data transfer. With the exception of cyg_i2c_transaction_begin_nb all the functions will block until completion. The tx routines will return 0 if the specified device does not respond to its address, or the number of bytes actually transferred. This may be less than the number requested if the device sends an early nack, for example because it has run out of buffer space. The rx routines will return 0 or the number of bytes received. Usually this will be the same as the count parameter. A slave device has no way of indicating to the master that no more data is available, so the rx operation cannot complete early. I2C operations should always be performed at thread-level or during system initialization, and not inside an ISR or DSR. This greatly simplifies locking. Also a typical ISR or DSR should not perform a blocking operation such as an I2C transfer. cyg_i2c_tx and cyg_i2c_rx can be used for simple data transfers. They both go through the following steps: lock the bus, generate the start condition, send the device address and the direction bit, either send or receive the data, generate the stop condition, and unlock the bus. At the end of a transfer the bus is back in its idle state, ready for the next transfer. cyg_i2c_tx returns the number of bytes actually transmitted. This may be 0 if the device does not respond when its address is sent out. It may be less than the number of bytes requested if the device generates an early nack, typically because it has run out of buffer space. cyg_i2c_rx returns 0 if the device does not respond when its address is sent out, or the number of bytes actually received. Usually this will be the number of bytes requested because an I2C slave device has no way of aborting an rx operation early. To allow multiple threads to access devices on the I2C some locking is required. This is encapsulated inside transactions. The cyg_i2c_tx and cyg_i2c_rx functions implicitly use such transactions, but the functionality is also available directly to application code. Amongst other things transactions can be used for more complicated interactions with I2C devices, in particular ones involving repeated starts. cyg_i2c_transaction_begin must be used at the start of a transaction. This performs thread-level locking on the bus, blocking if it is currently in use by another thread. cyg_i2c_transaction_begin_nb is a non-blocking variant, useful for threads which cannot afford to block for an indefinite period. If the bus is currently locked the function returns false immediately. If the bus is not locked then it acts as cyg_i2c_transaction_begin and returns true. Once the bus has been locked it is possible to perform one or more data transfers by calling cyg_i2c_transaction_tx, cyg_i2c_transaction_rx and cyg_i2c_transaction_stop. Code should ensure that a stop condition has been generated by the end of a transaction. Once the transaction is complete cyg_i2c_transaction_end should be called. This unlocks the bus, allowing other threads to perform I2C I/O to devices on the same bus. As an example consider reading the registers in an FS6377 programmable clock generator. The first step is to write a byte 0 to the device, setting the current register to 0. Then a repeated start condition should be generated and it is possible to read the 16 byte-wide registers, starting with the current one. Typical code for this might look like: cyg_uint8 tx_data[1]; cyg_uint8 rx_data[16]; cyg_i2c_transaction_begin(&hal_alaia_i2c_fs6377); tx_data[0] = 0x00; cyg_i2c_transaction_tx(&hal_alaia_i2c_fs6377, true, tx_data, 1, false); cyg_i2c_transaction_rx(&hal_alaia_i2c_fs6377, true, rx_data, 16, true, true); cyg_i2c_transaction_end(&hal_alaia_i2c_fs6377); Here hal_alaia_i2c_fs6377 is a cyg_i2c_device structure provided by the platform HAL. A transaction is begun, locking the bus. Then there is a transmit for a single byte. This transmit involves generating a start condition and sending the address and direction bit, but not a stop condition. Next there is a receive for 16 bytes. This also involves a start condition, which the device will interpret as a repeated start because it has not yet seen a stop. The start condition will be followed by the address and direction bit, and then the device will start transmitting the register contents. Once all 16 bytes have been received the rx routine will send a nack rather than an ack, halting the transfer, and then a stop condition is generated. Finally the transaction is ended, unlocking the bus. The arguments to cyg_i2c_transaction_tx are as follows: const cyg_i2c_device* device This identifies the I2C device that should be used. cyg_bool send_start If true, generate a start condition and send the address and direction bit. If false, skip those steps and go straight to transmitting the actual data. The latter can be useful if the data to be transmitted is spread over several buffers. The first tx call will involve generating the start condition but subsequent tx calls can skip this and just continue from the previous one. send_start must be true if the tx call is the first operation in a transaction, or if the previous call was an rx or stop. const cyg_uint8* tx_data cyg_uint32 count These arguments specify the data to be transmitted to the device. cyg_bool send_stop If true, generate a stop condition at the end of the transmit. Usually this is done only if the transmit is the last operation in a transaction. The arguments to cyg_i2c_transaction_rx are as follows: const cyg_i2c_device* device This identifies the I2C device that should be used. cyg_bool send_start If true, generate a start condition and send the address and direction bit. If false, skip those steps and go straight to receiving the actual data. The latter can be useful if the incoming data should be spread over several buffers. The first rx call will involve generating the start condition but subsequent rx calls can skip this and just continue from the previous one. Another use is for devices which can send variable length data, consisting of an initial length and then the actual data. The first rx will involve generating the start condition and reading the length, a subsequent rx will then just read the data. send_start must be true if the rx call is the first operation in a transaction, if the previous call was a tx or stop, or if the previous call was an an rx and the send_nack flag was set. cyg_uint8* rx_data cyg_uint32 count These arguments specify how much data should be received and where it should be placed. cyg_bool send_nack If true generate a nack instead of an ack for the last byte received. This causes the slave to end its transmit. The next operation should either involve a repeated start or a stop. send_nack should be set to false only if send_stop is also false, the next operation will be another rx, and that rx does not specify send_start. cyg_bool send_stop If true, generate a stop condition at the end of the transmit. Usually this is done only if the transmit is the last operation in a transaction. The final transaction-oriented function is cyg_i2c_transaction_stop. This just generates a stop condition. It should be used if the previous operation was a tx or rx that, for some reason, did not set the send_stop flag. A stop condition must be generated before the transaction is ended. The generic package CYGPKG_IO_I2C arranges for all I2C bus devices to be initialized via a single prioritized C++ static constructor. This constructor will run early on during system startup, before any application code, with priority CYG_INIT_BUS_I2C. Other code should not try to access any of the I2C devices until after the buses have been initialized. Porting to New Hardware Porting Adding I2C support to new hardware Adding I2C support to an eCos port involves a number of steps. The generic I2C package CYGPKG_IO_I2C should be included in the appropriate ecos.db target entry or entries. Next cyg_i2c_device structures should be provided for every device on the bus. Usually this is the responsibility of the platform HAL. In the case of development boards where the I2C SDA and SCL lines are accessible via an expansion connector, more devices may have been added and it will be the application's responsibility to provide the structures. Finally there is a need for one or more cyg_i2c_bus structures. Amongst other things these structures provide functions for actually driving the bus. If the processor has dedicated I2C hardware then this structure will usually be provided by a device driver package. If the bus is implemented by bit-banging then the bus structure will usually be provided by the platform HAL. The eCos I2C API works in terms of cyg_i2c_device structures, and these provide the information needed to access the hardware. A cyg_i2c_device structure contains the following fields: cyg_i2c_bus* i2c_bus This specifies the bus which the slave device is connected to. Most boards will only have a single I2C bus, but multiple buses are possible. cyg_uint16 i2c_address For most devices this will be the 7-bit I2C address the device will respond to. There is room for future expansion, for example to support 10-bit addresses. cyg_uint16 i2c_flags This field is not used at present. It exists for future expansion, for example to allow for fast mode or high-speed mode, and incidentally pads the structure to a 32-bit boundary. cyg_uint32 i2c_delay This holds the clock period which should be used when interacting with the device, in nanoseconds. Usually this will be 10000 ns, corresponding to a 100KHz clock, and the header cyg/io/i2c.h provides a #define CYG_I2C_DEFAULT_DELAY for this. Sometimes it may be desirable to use a slower clock, for example to reduce noise problems. The normal way to instantiate a cyg_i2c_device structure uses the CYG_I2C_DEVICE macro, also provided by cyg/io/i2c.h: #include <cyg/io/i2c.h> CYG_I2C_DEVICE(cyg_i2c_wallclock_ds1307, &hal_alaia_i2c_bus, 0x68, 0x00, CYG_I2C_DEFAULT_DELAY); CYG_I2C_DEVICE(hal_alaia_i2c_fs6377, &hal_alaia_i2c_bus, 0x58, 0x00, CYG_I2C_DEFAULT_DELAY); The arguments to the macro are the variable name, an I2C bus pointer, the device address, the flags field, and the delay field. The above code fragment defines two I2C device variables, cyg_i2c_wallclock_ds1307 and hal_alaia_i2c_fs6377, which can be used for the first argument to the cyg_i2c_ functions. Both devices are on the same bus. The device addresses are 0x68 and 0x58 respectively, and the devices do not have any special requirements. When the platform HAL provides these structures it should also export them for use by the application and other packages. Usually this involves an entry in cyg/hal/plf_io.h, which gets included automatically via one of the main exported HAL header files cyg/hal/hal_io.h. Unfortunately exporting the structures directly can be problematical because of circular dependencies between the I2C header and the HAL headers. Instead the platform HAL should define a macro HAL_I2C_EXPORTED_DEVICES: # define HAL_I2C_EXPORTED_DEVICES \ extern cyg_i2c_bus hal_alaia_i2c_bus; \ extern cyg_i2c_device cyg_i2c_wallclock_ds1307; \ extern cyg_i2c_device hal_alaia_i2c_fs6377; This macro gets expanded automatically by cyg/io/i2c.h once the data structures themselves have been defined, so application code can just include that header and all the buses and devices will be properly exported and usable. There is no single convention for naming the I2C devices. If the device will be used by some other package then typically that specifies the name that should be used. For example the DS1307 wallclock driver expects the I2C device to be called cyg_i2c_wallclock_ds1307, so failing to observe that convention will lead to compile-time and link-time errors. If the device will not be used by any other package then it is up to the platform HAL to select the name, and as long as reasonable care is taken to avoid name space pollution the exact name does not matter. Some processors come with dedicated I2C hardware. On other hardware the I2C bus involves simply connecting some GPIO pins to the SCL and SDA lines and then using software to implement the I2C protocol. This is usually referred to as bit-banging the bus. The generic I2C package CYGPKG_IO_I2C provides the main code for a bit-banged implementation, requiring one platform-specific function that does the actual GPIO pin manipulation. This function is usually hardware-specific because different boards will use different pins for the I2C bus, so typically it is left to the platform HAL to provide this function and instantiate the I2C bus object. There is no point in creating a separate package for this because the code cannot be re-used for other platforms. Instantiating a bit-banged I2C bus requires the following: #include <cyg/io/i2c.h> static cyg_bool hal_alaia_i2c_bitbang(cyg_i2c_bus* bus, cyg_i2c_bitbang_op op) { cyg_bool result = 0; switch(op) { … } return result; } CYG_I2C_BITBANG_BUS(hal_alaia_i2c_bus, &hal_alaia_i2c_bitbang); This gives a structure hal_alaia_i2c_bus which can be used when defining the cyg_i2c_device structures. The second argument specifies the function which will do the actual bit-banging. It takes two arguments. The first identifies the bus, which can be useful if the hardware has multiple I2C buses. The second specifies the bit-bang operation that should be performed. To understand these operations consider how I2C devices should be wired up according to the specification: Master and slave devices are interfaced to the bus in exactly the same way. The default state of the bus is to have both lines high via the pull-up resistors. Any device on the bus can lower either line, when allowed to do so by the protocol. Usually the SDA line only changes while SCL is low, but the start and stop conditions involve SDA changing while SCL is high. All devices have the ability to both read and write both lines. In reality not all bit-banged hardware works quite like this. Instead just two GPIO pins are used, and these are switched between input and output mode as required. The bitbang function should support the following operations: CYG_I2C_BITBANG_INIT This will be called during system initialization, as a side effect of a prioritized C++ static constructor. The bitbang function should ensure that both SCL and SDA are driven high. CYG_I2C_BITBANG_SCL_HIGH CYG_I2C_BITBANG_SCL_LOW CYG_I2C_BITBANG_SDA_HIGH CYG_I2C_BITBANG_SDA_LOW These operations simply set the appropriate lines high or low. CYG_I2C_BITBANG_SCL_HIGH_CLOCKSTRETCH In its simplest form this operation should simply set the SCL line high, indicating that the data on the SDA line is stable. However there is a complication: if a device is not ready yet then it can throttle back the master by keeping the SCL line low. This is known as clock-stretching. Hence for this operation the bitbang function should allow the SCL line to float high, then poll it until it really has become high. If a single pin is used for the SCL line then this pin should be turned back into a high output at the end of the call. CYG_I2C_BITBANG_SCL_LOW_SDA_INPUT This is used when there is a change of direction and the slave device is about to start driving the SDA line. This can be significant if a single pin is used to handle both input and output of SDA, to avoid a situation where both the master and the slave are driving the SDA line for an extended period of time. The operation combines dropping the SCL line and switching SDA to an input in an atomic or near-atomic operation. CYG_I2C_BITBANG_SDA_READ The SDA line is currently set as an input and the bitbang function should sample and return the current state. The bitbang function returns a boolean. For most operations this return value is ignored. For CYG_I2C_BITBANG_SDA_READ it should be the current level of the SDA line. Depending on the hardware some care may have to be taken when manipulating the GPIO pins. Although the I2C subsystem performs the required locking at the bus level, the device registers controlling the GPIO pins may get used by other subsystems or by the application. It is the responsibility of the bitbang function to perform appropriate locking, whether via a mutex or by briefly disabling interrupts around the register accesses. If the processor has dedicated I2C hardware then usually this will involve a separate device driver package in the devs/i2c hierarchy of the eCos component repository. That package should also be included in the appropriate ecos.db target entry or entries. The device driver may exist already, or it may have to be written from scratch. A new I2C driver basically involves creating an cyg_i2c_bus structure. The device driver should supply the following fields: i2c_init_fn This function will be called during system initialization to set up the I2C hardware. The generic I2C code creates a static object with a prioritized constructor, and this constructor will invoke the init functions for the various I2C buses in the system. i2c_tx_fn i2c_rx_fn i2c_stop_fn These functions implement the core I2C functionality. The arguments and results are the same as for the transaction functions cyg_i2c_transaction_tx, cyg_i2c_transaction_rx and cyg_i2c_transaction_stop. void* i2c_extra This field holds any extra information that may be needed by the device driver. Typically it will be a pointer to some driver-specific data structure. To assist with instantiating a cyg_i2c_bus object the header file cyg/io/i2c.h provides a macro. Typical usage would be: struct xyzzy_data { … } xyzzy_object; static void xyzzy_i2c_init(struct cyg_i2c_bus* bus) { … } static cyg_uint32 xyzzy_i2c_tx(const cyg_i2c_device* dev, cyg_bool send_start, const cyg_uint8* tx_data, cyg_uint32 count, cyg_bool send_stop) { … } static cyg_uint32 xyzzy_i2c_rx(const cyg_i2c_device* dev, cyg_bool send_start, cyg_uint8* rx_data, cyg_uint32 count, cyg_bool send_nack, cyg_bool send_stop) { … } static void xyzzy_i2c_stop(const cyg_i2c_device* dev) { … } CYG_I2C_BUS(cyg_i2c_xyzzy_bus, &xyzzy_i2c_init, &xyzzy_i2c_tx, &xyzzy_i2c_rx, &xyzzy_i2c_stop, (void*) &xyzzy_object); The generic I2C code contains these functions for a bit-banged I2C bus device. It can be used as a starting point for new drivers. Note that the bit-bang code uses the i2c_extra field to hold the hardware-specific bitbang function rather than a pointer to some data structure.