-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathi2c_doc.h
162 lines (162 loc) · 7.99 KB
/
i2c_doc.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
/******************************************************************************
* Filename: i2c_doc.h
* Revised: 2016-03-30 13:03:59 +0200 (Wed, 30 Mar 2016)
* Revision: 45971
*
* Copyright (c) 2015 - 2017, Texas Instruments Incorporated
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* 1) Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* 2) Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* 3) Neither the name of the ORGANIZATION nor the names of its contributors may
* be used to endorse or promote products derived from this software without
* specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*
******************************************************************************/
//! \addtogroup i2c_api
//! @{
//! \section sec_i2c Introduction
//!
//! The Inter-Integrated Circuit (\i2c) API provides a set of functions for using
//! the \ti_device \i2c master and slave module. Functions are provided to perform
//! the following actions:
//! - Initialize the \i2c module.
//! - Send and receive data.
//! - Obtain status.
//! - Manage interrupts for the \i2c module.
//!
//! The \i2c master and slave module provide the ability to communicate to other IC
//! devices over an \i2c bus. The \i2c bus is specified to support devices that can
//! both transmit and receive (write and read) data. Also, devices on the \i2c bus
//! can be designated as either a master or a slave. The \ti_device \i2c module
//! supports both sending and receiving data as either a master or a slave, and also
//! support the simultaneous operation as both a master and a slave. Finally, the
//! \ti_device \i2c module can operate at two speeds: standard (100 kb/s) and fast
//! (400 kb/s).
//!
//! The master and slave \i2c module can generate interrupts. The \i2c master
//! module generates interrupts when a transmit or receive operation
//! completes (or aborts due to an error).
//! The \i2c slave module can generate interrupts when data is
//! sent or requested by a master and when a START or STOP condition is present.
//!
//! \section sec_i2c_master Master Operations
//!
//! When using this API to drive the \i2c master module, the user must first
//! initialize the \i2c master module with a call to \ref I2CMasterInitExpClk(). This
//! function sets the bus speed and enables the master module.
//!
//! The user may transmit or receive data after the successful initialization of
//! the \i2c master module. Data is transferred by first setting the slave address
//! using \ref I2CMasterSlaveAddrSet(). This function is also used to define whether
//! the transfer is a send (a write to the slave from the master) or a receive (a
//! read from the slave by the master). Then, if connected to an \i2c bus that has
//! multiple masters, the \ti_device \i2c master must first call \ref I2CMasterBusBusy()
//! before trying to initiate the desired transaction. After determining that
//! the bus is not busy, if trying to send data, the user must call the
//! \ref I2CMasterDataPut() function. The transaction can then be initiated on the bus
//! by calling the \ref I2CMasterControl() function with any of the following commands:
//! - \ref I2C_MASTER_CMD_SINGLE_SEND
//! - \ref I2C_MASTER_CMD_SINGLE_RECEIVE
//! - \ref I2C_MASTER_CMD_BURST_SEND_START
//! - \ref I2C_MASTER_CMD_BURST_RECEIVE_START
//!
//! Any of these commands result in the master arbitrating for the bus,
//! driving the start sequence onto the bus, and sending the slave address and
//! direction bit across the bus. The remainder of the transaction can then be
//! driven using either a polling or interrupt-driven method.
//!
//! For the single send and receive cases, the polling method involves looping
//! on the return from \ref I2CMasterBusy(). Once the function indicates that the \i2c
//! master is no longer busy, the bus transaction is complete and can be
//! checked for errors using \ref I2CMasterErr(). If there are no errors, then the data
//! has been sent or is ready to be read using \ref I2CMasterDataGet(). For the burst
//! send and receive cases, the polling method also involves calling the
//! \ref I2CMasterControl() function for each byte transmitted or received
//! (using either the \ref I2C_MASTER_CMD_BURST_SEND_CONT or \ref I2C_MASTER_CMD_BURST_RECEIVE_CONT
//! commands), and for the last byte sent or received (using either the
//! \ref I2C_MASTER_CMD_BURST_SEND_FINISH or \ref I2C_MASTER_CMD_BURST_RECEIVE_FINISH
//! commands).
//!
//! If any error is detected during the burst transfer,
//! the appropriate stop command (\ref I2C_MASTER_CMD_BURST_SEND_ERROR_STOP or
//! \ref I2C_MASTER_CMD_BURST_RECEIVE_ERROR_STOP) should be used to call the
//! \ref I2CMasterControl() function.
//!
//! For the interrupt-driven transaction, the user must register an interrupt
//! handler for the \i2c devices and enable the \i2c master interrupt; the interrupt
//! occurs when the master is no longer busy.
//!
//! \section sec_i2c_slave Slave Operations
//!
//! When using this API to drive the \i2c slave module, the user must first
//! initialize the \i2c slave module with a call to \ref I2CSlaveInit(). This function
//! enables the \i2c slave module and initializes the address of the slave. After the
//! initialization completes, the user may poll the slave status using
//! \ref I2CSlaveStatus() to determine if a master requested a send or receive
//! operation. Depending on the type of operation requested, the user can call
//! \ref I2CSlaveDataPut() or \ref I2CSlaveDataGet() to complete the transaction.
//! Alternatively, the \i2c slave can handle transactions using an interrupt handler
//! registered with \ref I2CIntRegister(), and by enabling the \i2c slave interrupt.
//!
//! \section sec_i2c_api API
//!
//! The \i2c API is broken into three groups of functions:
//! those that handle status and initialization, those that
//! deal with sending and receiving data, and those that deal with
//! interrupts.
//!
//! Status and initialization functions for the \i2c module are:
//! - \ref I2CMasterInitExpClk()
//! - \ref I2CMasterEnable()
//! - \ref I2CMasterDisable()
//! - \ref I2CMasterBusBusy()
//! - \ref I2CMasterBusy()
//! - \ref I2CMasterErr()
//! - \ref I2CSlaveInit()
//! - \ref I2CSlaveEnable()
//! - \ref I2CSlaveDisable()
//! - \ref I2CSlaveStatus()
//!
//! Sending and receiving data from the \i2c module is handled by the following functions:
//! - \ref I2CMasterSlaveAddrSet()
//! - \ref I2CSlaveAddressSet()
//! - \ref I2CMasterControl()
//! - \ref I2CMasterDataGet()
//! - \ref I2CMasterDataPut()
//! - \ref I2CSlaveDataGet()
//! - \ref I2CSlaveDataPut()
//!
//! The \i2c master and slave interrupts are handled by the following functions:
//! - \ref I2CIntRegister()
//! - \ref I2CIntUnregister()
//! - \ref I2CMasterIntEnable()
//! - \ref I2CMasterIntDisable()
//! - \ref I2CMasterIntClear()
//! - \ref I2CMasterIntStatus()
//! - \ref I2CSlaveIntEnable()
//! - \ref I2CSlaveIntDisable()
//! - \ref I2CSlaveIntClear()
//! - \ref I2CSlaveIntStatus()
//!
//! @}