1 /*******************************************************************************
\r
2 * (c) Copyright 2007-2008 Actel Corporation. All rights reserved.
\r
4 * SmartFusion microcontroller subsystem I2C bare metal software driver public
\r
7 * SVN $Revision: 2150 $
\r
8 * SVN $Date: 2010-02-11 14:39:24 +0000 (Thu, 11 Feb 2010) $
\r
10 /*=========================================================================*//**
\r
11 @mainpage SmartFusion MSS I2C Bare Metal Driver.
\r
13 @section intro_sec Introduction
\r
14 The SmartFusion™ microcontroller subsystem (MSS) includes two I2C peripherals
\r
15 for serial communication. This driver provides a set of functions for
\r
16 controlling the MSS I2Cs as part of a bare metal system where no operating
\r
17 system is available. These drivers can be adapted for use as part of an
\r
18 operating system, but the implementation of the adaptation layer between this
\r
19 driver and the operating system's driver model is outside the scope of this
\r
22 @section hw_dependencies Hardware Flow Dependencies
\r
23 The configuration of all features of the MSS I2Cs is covered by this driver
\r
24 with the exception of the SmartFusion IOMUX configuration. SmartFusion allows
\r
25 multiple non-concurrent uses of some external pins through IOMUX configuration.
\r
26 This feature allows optimization of external pin usage by assigning external
\r
27 pins for use by either the microcontroller subsystem or the FPGA fabric. The
\r
28 MSS I2Cs serial signals are routed through IOMUXes to the SmartFusion device
\r
29 external pins. These IOMUXes are automatically configured correctly by the MSS
\r
30 configurator tool in the hardware flow when the MSS I2Cs are enabled in that
\r
31 tool. You must ensure that the MSS I2Cs are enabled by the MSS configurator
\r
32 tool in the hardware flow; otherwise the serial inputs and outputs will not be
\r
33 connected to the chip's external pins. For more information on IOMUX, refer to
\r
34 the IOMUX section of the SmartFusion Datasheet.
\r
35 The base address, register addresses and interrupt number assignment for the
\r
36 MSS I2C blocks are defined as constants in the SmartFusion CMSIS-PAL. You must
\r
37 ensure that the SmartFusion CMSIS-PAL is either included in the software tool
\r
38 chain used to build your project or is included in your project.
\r
40 @section theory_op Theory of Operation
\r
41 The MSS I2C driver functions are grouped into the following categories:
\r
42 • Initialization and configuration functions
\r
44 • I2C master operations – functions to handle write, read and write-read transactions
\r
45 • I2C slave operations – functions to handle write, read and write-read transactions
\r
47 Initialization and Configuration
\r
48 The MSS I2C driver is initialized through a call to the MSS_I2C_init()
\r
49 function. This function takes the MSS I2C's configuration as parameters. The
\r
50 MSS_I2C_init() function must be called before any other MSS I2C driver
\r
51 functions can be called. The first parameter of the MSS_I2C_init() function
\r
52 is a pointer to one of two global data structures used by the driver to
\r
53 store state information for each MSS I2C. A pointer to these data structures
\r
54 is also used as first parameter to any of the driver functions to identify
\r
55 which MSS I2C will be used by the called function. The names of these two
\r
56 data structures are g_mss_i2c0 and g_mss_i2c1. Therefore any call to an MSS
\r
57 I2C driver function should be of the form MSS_I2C_function_name( &g_mss_i2c0, ... )
\r
58 or MSS_I2C_function_name( &g_mss_i2c1, ... ).
\r
59 The MSS_I2C_init() function call for each MSS I2C also takes the I2C serial
\r
60 address assigned to the MSS I2C and the serial clock divider to be used to
\r
61 generate its I2C clock as configuration parameters.
\r
64 The MSS I2C driver is interrupt driven and it enables and disables the
\r
65 generation of interrupts by MSS I2C at various times when it is operating.
\r
66 The driver automatically handles MSS I2C interrupts internally, including
\r
67 enabling disabling and clearing MSS I2C interrupts in the Cortex-M3
\r
68 interrupt controller when required.
\r
69 The function MSS_I2C_register_write_handler() is used to register a write
\r
70 handler function with the MSS I2C driver that it will call on completion of
\r
71 an I2C write transaction by the MSS I2C slave. It is your responsibility to
\r
72 create and register the implementation of this handler function that will
\r
73 process or trigger the processing of the received data.
\r
75 The MSS I2C driver is designed to handle three types of I2C transaction:
\r
76 • Write transactions
\r
78 • Write-read transactions
\r
81 The master I2C device initiates a write transaction by sending a START bit
\r
82 as soon as the bus becomes free. The START bit is followed by the 7-bit
\r
83 serial address of the target slave device followed by the read/write bit
\r
84 indicating the direction of the transaction. The slave acknowledges receipt
\r
85 of it’s address with an acknowledge bit. The master sends data one byte at
\r
86 a time to the slave, which must acknowledge receipt of each byte for the
\r
87 next byte to be sent. The master sends a STOP bit to complete the transaction.
\r
88 The slave can abort the transaction by replying with a non-acknowledge bit
\r
89 instead of an acknowledge.
\r
90 The application programmer can choose not to send a STOP bit at the end of
\r
91 the transaction causing the next transaction to begin with a repeated START bit.
\r
94 The master I2C device initiates a read transaction by sending a START bit
\r
95 as soon as the bus becomes free. The START bit is followed by the 7-bit
\r
96 serial address of the target slave device followed by the read/write bit
\r
97 indicating the direction of the transaction. The slave acknowledges receipt
\r
98 of it’s slave address with an acknowledge bit. The slave sends data one byte
\r
99 at a time to the master, which must acknowledge receipt of each byte for the
\r
100 next byte to be sent. The master sends a non-acknowledge bit following the
\r
101 last byte it wishes to read followed by a STOP bit.
\r
102 The application programmer can choose not to send a STOP bit at the end of
\r
103 the transaction causing the next transaction to begin with a repeated START bit.
\r
105 Write-read transaction
\r
106 The write-read transaction is a combination of a write transaction
\r
107 immediately followed by a read transaction. There is no STOP bit between
\r
108 the write and read phases of a write-read transaction. A repeated START
\r
109 bit is sent between the write and read phases.
\r
110 The write-read transaction is typically used to send a command or offset
\r
111 in the write transaction specifying the logical data to be transferred
\r
112 during the read phase.
\r
113 The application programmer can choose not to send a STOP bit at the end of
\r
114 the transaction causing the next transaction to begin with a repeated START bit.
\r
117 The application can use the MSS_I2C_write(), MSS_I2C_read() and MSS_I2C_write_read()
\r
118 functions to initiate an I2C bus transaction. The application can then wait
\r
119 for the transaction to complete using the MSS_I2C_wait_complete() function
\r
120 or poll the status of the I2C transaction using the MSS_I2C_get_status()
\r
121 function until it returns a value different from MSS_I2C_IN_PROGRESS.
\r
124 The configuration of the MSS I2C driver to operate as an I2C slave requires
\r
125 the use of the following functions:
\r
126 • MSS_I2C_set_slave_tx_buffer()
\r
127 • MSS_I2C_set_slave_rx_buffer()
\r
128 • MSS_I2C_set_slave_mem_offset_length()
\r
129 • MSS_I2C_register_write_handler()
\r
130 • MSS_I2C_enable_slave_rx()
\r
131 Use of all functions is not required if the slave I2C does not need to support
\r
132 all types of I2C read transactions. The subsequent sections list the functions
\r
133 that must be used to support each transaction type.
\r
135 Responding to read transactions
\r
136 The following functions are used to configure the MSS I2C driver to respond
\r
137 to I2C read transactions:
\r
138 • MSS_I2C_set_slave_tx_buffer()
\r
139 • MSS_I2C_enable_slave_rx()
\r
140 The function MSS_I2C_set_slave_tx_buffer() specifies the data buffer that
\r
141 will be transmitted when the I2C slave is the target of an I2C read
\r
142 transaction. It is then up to the application to manage the content of that
\r
143 buffer to control the data that will be transmitted to the I2C master as a
\r
144 result of the read transaction.
\r
145 The function MSS_I2C_enable_slave_rx() enables the MSS I2C hardware instance
\r
146 to respond to I2C transactions. It must be called after the MSS I2C driver
\r
147 has been configured to respond to the required transaction types.
\r
149 Responding to write transactions
\r
150 The following functions are used to configure the MSS I2C driver to respond
\r
151 to I2C write transactions:
\r
152 • MSS_I2C_set_slave_rx_buffer()
\r
153 • MSS_I2C_register_write_handler()
\r
154 • MSS_I2C_enable_slave_rx()
\r
155 The function MSS_I2C_set_slave_rx_buffer() specifies the data buffer that
\r
156 will be used to store the data received by the I2C slave when it is the
\r
157 target an I2C write transaction.
\r
158 The function MSS_I2C_register_write_handler() specifies the handler function
\r
159 that must be called on completion of the I2C write transaction. It is this
\r
160 handler function that will process or trigger the processing of the received
\r
162 The function MSS_I2C_enable_slave_rx() enables the MSS I2C hardware instance
\r
163 to respond to I2C transactions. It must be called after the MSS I2C driver
\r
164 has been configured to respond to the required transaction types.
\r
166 Responding to write-read transactions
\r
167 The following functions are used to configure the MSS I2C driver to respond
\r
168 to write-read transactions:
\r
169 • MSS_I2C_set_slave_tx_buffer()
\r
170 • MSS_I2C_set_slave_rx_buffer()
\r
171 • MSS_I2C_set_slave_mem_offset_length()
\r
172 • MSS_I2C_enable_slave_rx()
\r
173 The function MSS_I2C_set_slave_mem_offset_length() specifies the number of
\r
174 bytes expected by the I2C slave during the write phase of the write-read
\r
176 The function MSS_I2C_set_slave_tx_buffer() specifies the data that will be
\r
177 transmitted to the I2C master during the read phase of the write-read
\r
178 transaction. The value received by the I2C slave during the write phase of
\r
179 the transaction will be used as an index into the transmit buffer specified
\r
180 by this function to decide which part of the transmit buffer will be
\r
181 transmitted to the I2C master as part of the read phase of the write-read
\r
183 The function MSS_I2C_set_slave_rx_buffer() specifies the data buffer that
\r
184 will be used to store the data received by the I2C slave during the write
\r
185 phase of the write-read transaction. This buffer must be at least large
\r
186 enough to accommodate the number of bytes specified through the
\r
187 MSS_I2C_set_slave_mem_offset_length() function.
\r
188 The function MSS_I2C_enable_slave_rx() enables the MSS I2C hardware
\r
189 instance to respond to I2C transactions. It must be called after the MSS
\r
190 I2C driver has been configured to respond to the required transaction types.
\r
191 *//*=========================================================================*/
\r
195 #include "../../CMSIS/a2fxxxm3.h"
\r
197 /* FreeRTOS includes. */
\r
198 #include "FreeRTOS.h"
\r
200 #include "semphr.h"
\r
206 /*-------------------------------------------------------------------------*//**
\r
207 The mss_i2c_clock_divider_t type is used to specify the divider to be applied
\r
208 to the MSS I2C BCLK signal in order to generate the I2C clock.
\r
210 typedef enum mss_i2c_clock_divider {
\r
211 MSS_I2C_PCLK_DIV_256 = 0,
\r
212 MSS_I2C_PCLK_DIV_224,
\r
213 MSS_I2C_PCLK_DIV_192,
\r
214 MSS_I2C_PCLK_DIV_160,
\r
215 MSS_I2C_PCLK_DIV_960,
\r
216 MSS_I2C_PCLK_DIV_120,
\r
217 MSS_I2C_PCLK_DIV_60,
\r
219 } mss_i2c_clock_divider_t;
\r
221 /*-------------------------------------------------------------------------*//**
\r
222 The MSS_I2C_RELEASE_BUS constant is used to specify the options parameter to
\r
223 functions MSS_I2C_read(), MSS_I2C_write() and MSS_I2C_write_read() to indicate
\r
224 that a STOP bit must be generated at the end of the I2C transaction to release
\r
227 #define MSS_I2C_RELEASE_BUS 0x00
\r
229 /*-------------------------------------------------------------------------*//**
\r
230 The MSS_I2C_HOLD_BUS constant is used to specify the options parameter to
\r
231 functions MSS_I2C_read(), MSS_I2C_write() and MSS_I2C_write_read() to indicate
\r
232 that a STOP bit must not be generated at the end of the I2C transaction in
\r
233 order to retain the bus ownership. This will cause the next transaction to
\r
234 begin with a repeated START bit and no STOP bit between the transactions.
\r
236 #define MSS_I2C_HOLD_BUS 0x01
\r
238 /*-------------------------------------------------------------------------*//**
\r
239 The mss_i2c_status_t type is used to report the status of I2C transactions.
\r
241 typedef enum mss_i2c_status
\r
243 MSS_I2C_SUCCESS = 0,
\r
244 MSS_I2C_IN_PROGRESS,
\r
246 } mss_i2c_status_t;
\r
248 /*-------------------------------------------------------------------------*//**
\r
249 The mss_i2c_slave_handler_ret_t type is used by slave write handler functions
\r
250 to indicate whether the received data buffer should be released or not.
\r
252 typedef enum mss_i2c_slave_handler_ret {
\r
253 MSS_I2C_REENABLE_SLAVE_RX = 0,
\r
254 MSS_I2C_PAUSE_SLAVE_RX = 1
\r
255 } mss_i2c_slave_handler_ret_t;
\r
257 /*-------------------------------------------------------------------------*//**
\r
258 Slave write handler functions prototype.
\r
259 ------------------------------------------------------------------------------
\r
260 This defines the function prototype that must be followed by MSS I2C slave
\r
261 write handler functions. These functions are registered with the MSS I2C driver
\r
262 through the MSS_I2C_register_write_handler() function.
\r
264 Declaring and Implementing Slave Write Handler Functions:
\r
265 Slave write handler functions should follow the following prototype:
\r
266 mss_i2c_slave_handler_ret_t write_handler( uint8_t * data, uint16_t size );
\r
268 The data parameter is a pointer to a buffer (received data buffer) holding
\r
269 the data written to the MSS I2C slave.
\r
270 The size parameter is the number of bytes held in the received data buffer.
\r
271 Handler functions must return one of the following values:
\r
272 • MSS_I2C_REENABLE_SLAVE_RX
\r
273 • MSS_I2C_PAUSE_SLAVE_RX.
\r
274 If the handler function returns MSS_I2C_REENABLE_SLAVE_RX, the driver will
\r
275 release the received data buffer and allow further I2C write transactions to
\r
276 the MSS I2C slave to take place.
\r
277 If the handler function returns MSS_I2C_PAUSE_SLAVE_RX, the MSS I2C slave
\r
278 will respond to subsequent write requests with a non-acknowledge bit (NACK),
\r
279 until the received data buffer content has been processed by some other part
\r
280 of the software application.
\r
281 A call to MSS_I2C_enable_slave_rx() is required at some point after
\r
282 returning MSS_I2C_PAUSE_SLAVE_RX in order to release the received data
\r
283 buffer so it can be used to store data received by subsequent I2C write
\r
286 typedef mss_i2c_slave_handler_ret_t (*mss_i2c_slave_wr_handler_t)( uint8_t *, uint16_t );
\r
288 /*-------------------------------------------------------------------------*//**
\r
290 ------------------------------------------------------------------------------
\r
291 There is one instance of this structure for each of the microcontroller
\r
292 subsystem's I2Cs. Instances of this structure are used to identify a specific
\r
293 I2C. A pointer to an instance of the mss_i2c_instance_t structure is passed as
\r
294 the first parameter to MSS I2C driver functions to identify which I2C should
\r
295 perform the requested operation.
\r
297 typedef struct mss_i2c_instance
\r
299 uint_fast8_t ser_address;
\r
300 /* Transmit related info:*/
\r
301 uint_fast8_t target_addr;
\r
303 /* Current transaction type (WRITE, READ, RANDOM_READ)*/
\r
304 uint8_t transaction;
\r
306 uint_fast16_t random_read_addr;
\r
310 /* I2C hardware instance identification */
\r
312 I2C_TypeDef * hw_reg;
\r
313 I2C_BitBand_TypeDef * hw_reg_bit;
\r
316 const uint8_t * tx_buffer;
\r
317 uint_fast16_t tx_size;
\r
318 uint_fast16_t tx_idx;
\r
322 uint8_t * rx_buffer;
\r
323 uint_fast16_t rx_size;
\r
324 uint_fast16_t rx_idx;
\r
326 /* status variable: */
\r
327 volatile mss_i2c_status_t status;
\r
330 uint_fast8_t slave_mem_offset_length;
\r
331 mss_i2c_slave_wr_handler_t slave_write_handler;
\r
333 /* Used to get access to and wait for completion of an I2C transaction. */
\r
334 xSemaphoreHandle xI2CCompleteSemaphore;
\r
336 } mss_i2c_instance_t;
\r
338 /*-------------------------------------------------------------------------*//**
\r
339 This instance of mss_i2c_instance_t holds all data related to the operations
\r
340 performed by MSS I2C 0. A pointer to g_mss_i2c0 is passed as the first
\r
341 parameter to MSS I2C driver functions to indicate that MSS I2C 0 should
\r
342 perform the requested operation.
\r
344 extern mss_i2c_instance_t g_mss_i2c0;
\r
346 /*-------------------------------------------------------------------------*//**
\r
347 This instance of mss_i2c_instance_t holds all data related to the operations
\r
348 performed by MSS I2C 1. A pointer to g_mss_i2c1 is passed as the first
\r
349 parameter to MSS I2C driver functions to indicate that MSS I2C 1 should
\r
350 perform the requested operation.
\r
352 extern mss_i2c_instance_t g_mss_i2c1;
\r
354 /*-------------------------------------------------------------------------*//**
\r
355 MSS I2C initialisation routine.
\r
356 ------------------------------------------------------------------------------
\r
357 The MSS_I2C_init() function initializes and configures hardware and data
\r
358 structures of one of the SmartFusion MSS I2Cs.
\r
359 ------------------------------------------------------------------------------
\r
361 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
362 identifying the MSS I2C hardware block to be initialized. There are two such
\r
363 data structures, g_mss_i2c0 and g_mss_i2c1, associated with MSS I2C 0 and
\r
364 MSS I2C 1 respectively. This parameter must point to either the g_mss_i2c0
\r
365 or g_mss_i2c1 global data structure defined within the I2C driver.
\r
367 @param ser_address:
\r
368 This parameter sets the I2C serial address being initialized. It is the I2C
\r
369 bus address to which the MSS I2C instance will respond. Any 8 bit address is
\r
372 @param ser_clock_speed:
\r
373 This parameter sets the I2C serial clock frequency. It selects the divider
\r
374 that will be used to generate the serial clock from the APB clock. It can be
\r
375 one of the following:
\r
376 • MSS_I2C_PCLK_DIV_256
\r
377 • MSS_I2C_PCLK_DIV_224
\r
378 • MSS_I2C_PCLK_DIV_192
\r
379 • MSS_I2C_PCLK_DIV_160
\r
380 • MSS_I2C_PCLK_DIV_960
\r
381 • MSS_I2C_PCLK_DIV_120
\r
382 • MSS_I2C_PCLK_DIV_60
\r
383 • MSS_I2C_BCLK_DIV_8
\r
387 mss_i2c_instance_t * this_i2c,
\r
388 uint8_t ser_address,
\r
389 mss_i2c_clock_divider_t ser_clock_speed
\r
392 /*******************************************************************************
\r
393 *******************************************************************************
\r
395 * Master specific functions
\r
397 * The following functions are only used within an I2C master's implementation.
\r
400 /*-------------------------------------------------------------------------*//**
\r
401 I2C master write function.
\r
402 ------------------------------------------------------------------------------
\r
403 This function initiates an I2C master write transaction. This function returns
\r
404 immediately after initiating the transaction. The content of the write buffer
\r
405 passed as parameter should not be modified until the write transaction
\r
406 completes. It also means that the memory allocated for the write buffer should
\r
407 not be freed or go out of scope before the write completes. You can check for
\r
408 the write transaction completion using the MSS_I2C_status() function.
\r
409 ------------------------------------------------------------------------------
\r
411 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
412 identifying the MSS I2C hardware block that will perform the requested
\r
413 function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,
\r
414 associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must
\r
415 point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined
\r
416 within the I2C driver.
\r
418 @param serial_addr:
\r
419 This parameter specifies the serial address of the target I2C device.
\r
421 @param write_buffer:
\r
422 This parameter is a pointer to a buffer holding the data to be written to
\r
423 the target I2C device.
\r
424 Care must be taken not to release the memory used by this buffer before the
\r
425 write transaction completes. For example, it is not appropriate to return
\r
426 from a function allocating this buffer as an array variable before the write
\r
427 transaction completes as this would result in the buffer's memory being
\r
428 de-allocated from the stack when the function returns. This memory could
\r
429 then be subsequently reused and modified causing unexpected data to be
\r
430 written to the target I2C device.
\r
433 Number of bytes held in the write_buffer to be written to the target I2C
\r
437 The options parameter is used to indicate if the I2C bus should be released
\r
438 on completion of the write transaction. Using the MSS_I2C_RELEASE_BUS
\r
439 constant for the options parameter causes a STOP bit to be generated at the
\r
440 end of the write transaction causing the bus to be released for other I2C
\r
441 devices to use. Using the MSS_I2C_HOLD_BUS constant as options parameter
\r
442 prevents a STOP bit from being generated at the end of the write
\r
443 transaction, preventing other I2C devices from initiating a bus transaction.
\r
447 mss_i2c_instance_t * this_i2c,
\r
448 uint8_t serial_addr,
\r
449 const uint8_t * write_buffer,
\r
450 uint16_t write_size,
\r
454 /*-------------------------------------------------------------------------*//**
\r
456 ------------------------------------------------------------------------------
\r
457 This function initiates an I2C master read transaction. This function returns
\r
458 immediately after initiating the transaction.
\r
459 The content of the read buffer passed as parameter should not be modified
\r
460 until the read transaction completes. It also means that the memory allocated
\r
461 for the read buffer should not be freed or go out of scope before the read
\r
462 completes. You can check for the read transaction completion using the
\r
463 MSS_I2C_status() function.
\r
464 ------------------------------------------------------------------------------
\r
466 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
467 identifying the MSS I2C hardware block that will perform the requested
\r
468 function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,
\r
469 associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must
\r
470 point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined
\r
471 within the I2C driver.
\r
473 @param serial_addr:
\r
474 This parameter specifies the serial address of the target I2C device.
\r
477 Pointer to a buffer where the data received from the target device will be
\r
479 Care must be taken not to release the memory used by this buffer before the
\r
480 read transaction completes. For example, it is not appropriate to return
\r
481 from a function allocating this buffer as an array variable before the read
\r
482 transaction completes as this would result in the buffer's memory being
\r
483 de-allocated from the stack when the function returns. This memory could
\r
484 then be subsequently reallocated resulting in the read transaction
\r
485 corrupting the newly allocated memory.
\r
488 This parameter is the number of bytes to read from the target device. This
\r
489 size must not exceed the size of the read_buffer buffer.
\r
492 The options parameter is used to indicate if the I2C bus should be released
\r
493 on completion of the read transaction. Using the MSS_I2C_RELEASE_BUS
\r
494 constant for the options parameter causes a STOP bit to be generated at the
\r
495 end of the read transaction causing the bus to be released for other I2C
\r
496 devices to use. Using the MSS_I2C_HOLD_BUS constant as options parameter
\r
497 prevents a STOP bit from being generated at the end of the read transaction,
\r
498 preventing other I2C devices from initiating a bus transaction.
\r
502 mss_i2c_instance_t * this_i2c,
\r
503 uint8_t serial_addr,
\r
504 uint8_t * read_buffer,
\r
505 uint16_t read_size,
\r
509 /*-------------------------------------------------------------------------*//**
\r
510 I2C master write-read
\r
511 ------------------------------------------------------------------------------
\r
512 This function initiates an I2C write-read transaction where data is first
\r
513 written to the target device before issuing a restart condition and changing
\r
514 the direction of the I2C transaction in order to read from the target device.
\r
515 ------------------------------------------------------------------------------
\r
517 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
518 identifying the MSS I2C hardware block that will perform the requested
\r
519 function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,
\r
520 associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must
\r
521 point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined
\r
522 within the I2C driver.
\r
524 @param serial_addr:
\r
525 This parameter specifies the serial address of the target I2C device.
\r
527 @param addr_offset:
\r
528 This parameter is a pointer to the buffer containing the data that will be
\r
529 sent to the slave during the write phase of the write-read transaction. This
\r
530 data is typically used to specify an address offset specifying to the I2C
\r
531 slave device what data it must return during the read phase of the
\r
532 write-read transaction.
\r
534 @param offset_size:
\r
535 This parameter specifies the number of offset bytes to be written during the
\r
536 write phase of the write-read transaction. This is typically the size of the
\r
537 buffer pointed to by the addr_offset parameter.
\r
539 @param read_buffer:
\r
540 This parameter is a pointer to the buffer where the data read from the I2C
\r
541 slave will be stored.
\r
544 This parameter specifies the number of bytes to read from the target I2C
\r
545 slave device. This size must not exceed the size of the buffer pointed to by
\r
546 the read_buffer parameter.
\r
549 The options parameter is used to indicate if the I2C bus should be released
\r
550 on completion of the write-read transaction. Using the MSS_I2C_RELEASE_BUS
\r
551 constant for the options parameter causes a STOP bit to be generated at the
\r
552 end of the write-read transaction causing the bus to be released for other
\r
553 I2C devices to use. Using the MSS_I2C_HOLD_BUS constant as options parameter
\r
554 prevents a STOP bit from being generated at the end of the write-read
\r
555 transaction, preventing other I2C devices from initiating a bus transaction.
\r
557 void MSS_I2C_write_read
\r
559 mss_i2c_instance_t * this_i2c,
\r
560 uint8_t serial_addr,
\r
561 const uint8_t * addr_offset,
\r
562 uint16_t offset_size,
\r
563 uint8_t * read_buffer,
\r
564 uint16_t read_size,
\r
568 /*-------------------------------------------------------------------------*//**
\r
570 ------------------------------------------------------------------------------
\r
571 This function indicates the current state of a MSS I2C instance.
\r
572 ------------------------------------------------------------------------------
\r
574 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
575 identifying the MSS I2C hardware block that will perform the requested
\r
576 function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,
\r
577 associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must
\r
578 point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined
\r
579 within the I2C driver.
\r
580 ------------------------------------------------------------------------------
\r
582 The return value indicates the current state of a MSS I2C instance or the
\r
583 outcome of the previous transaction if no transaction is in progress.
\r
584 Possible return values are:
\r
586 The last I2C transaction has completed successfully.
\r
588 There is an I2C transaction in progress.
\r
590 The last I2C transaction failed.
\r
593 mss_i2c_status_t MSS_I2C_get_status
\r
595 mss_i2c_instance_t * this_i2c
\r
598 /*-------------------------------------------------------------------------*//**
\r
599 Wait for I2C transaction completion.
\r
600 ------------------------------------------------------------------------------
\r
601 This function waits for the current I2C transaction to complete. The return
\r
602 value indicates whether the last I2C transaction was successful, or is still
\r
603 in progress, or failed.
\r
604 ------------------------------------------------------------------------------
\r
606 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
607 identifying the MSS I2C hardware block that will perform the requested
\r
608 function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,
\r
609 associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must
\r
610 point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined
\r
611 within the I2C driver.
\r
612 ------------------------------------------------------------------------------
\r
614 The return value indicates the outcome of the last I2C transaction. It can
\r
615 be one of the following:
\r
617 The last I2C transaction has completed successfully.
\r
618 MSS_I2C_IN_PROGRESS
\r
619 The current I2C transaction is still in progress.
\r
621 The last I2C transaction failed.
\r
623 mss_i2c_status_t MSS_I2C_wait_complete
\r
625 mss_i2c_instance_t * this_i2c
\r
629 /*******************************************************************************
\r
630 *******************************************************************************
\r
632 * Slave specific functions
\r
634 * The following functions are only used within the implementation of an I2C
\r
638 /*-------------------------------------------------------------------------*//**
\r
639 I2C slave transmit buffer configuration.
\r
640 ------------------------------------------------------------------------------
\r
641 This function specifies the memory buffer holding the data that will be sent
\r
642 to the I2C master when this MSS I2C instance is the target of an I2C read or
\r
643 write-read transaction.
\r
644 ------------------------------------------------------------------------------
\r
646 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
647 identifying the MSS I2C hardware block that will perform the requested
\r
648 function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,
\r
649 associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must
\r
650 point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined
\r
651 within the I2C driver.
\r
654 This parameter is a pointer to the memory buffer holding the data to be
\r
655 returned to the I2C master when this MSS I2C instance is the target of an
\r
656 I2C read or write-read transaction.
\r
659 Size of the transmit buffer pointed to by the tx_buffer parameter.
\r
661 void MSS_I2C_set_slave_tx_buffer
\r
663 mss_i2c_instance_t * this_i2c,
\r
664 uint8_t * tx_buffer,
\r
668 /*-------------------------------------------------------------------------*//**
\r
669 I2C slave receive buffer configuration.
\r
670 ------------------------------------------------------------------------------
\r
671 This function specifies the memory buffer that will be used by the MSS I2C
\r
672 instance to receive data when it is a slave. This buffer is the memory where
\r
673 data will be stored when the MSS I2C is the target of an I2C master write
\r
674 transaction (i.e. when it is the slave).
\r
675 ------------------------------------------------------------------------------
\r
677 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
678 identifying the MSS I2C hardware block that will perform the requested
\r
679 function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,
\r
680 associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must
\r
681 point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined
\r
682 within the I2C driver.
\r
685 This parameter is a pointer to the memory buffer allocated by the caller
\r
686 software to be used as a slave receive buffer.
\r
689 Size of the slave receive buffer. This is the amount of memory that is
\r
690 allocated to the buffer pointed to by rx_buffer.
\r
691 Note: This buffer size will indirectly specify the maximum I2C write
\r
692 transaction length this MSS I2C instance can be the target of. This
\r
693 is because this MSS I2C instance will respond to further received
\r
694 bytes with a non-acknowledge bit (NACK) as soon as its receive
\r
695 buffer is full. This will cause the write transaction to fail.
\r
697 void MSS_I2C_set_slave_rx_buffer
\r
699 mss_i2c_instance_t * this_i2c,
\r
700 uint8_t * rx_buffer,
\r
704 /*-------------------------------------------------------------------------*//**
\r
705 I2C slave memory offset length configuration.
\r
706 ------------------------------------------------------------------------------
\r
707 This function is used as part of the configuration of a MSS I2C instance for
\r
708 operation as a slave supporting write-read transactions. It specifies the
\r
709 number of bytes expected as part of the write phase of a write-read
\r
710 transaction. The bytes received during the write phase of a write-read
\r
711 transaction will be interpreted as an offset into the slave’s transmit buffer.
\r
712 This allows random access into the I2C slave transmit buffer from a remote
\r
714 ------------------------------------------------------------------------------
\r
716 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
717 identifying the MSS I2C hardware block that will perform the requested
\r
718 function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,
\r
719 associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must
\r
720 point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined
\r
721 within the I2C driver.
\r
723 @param offset_length:
\r
724 The offset_length parameter configures the number of bytes to be interpreted
\r
725 by the MSS I2C slave as a memory offset value during the write phase of
\r
726 write-read transactions.
\r
728 void MSS_I2C_set_slave_mem_offset_length
\r
730 mss_i2c_instance_t * this_i2c,
\r
731 uint8_t offset_length
\r
734 /*-------------------------------------------------------------------------*//**
\r
735 I2C write handler registration.
\r
736 ------------------------------------------------------------------------------
\r
737 Register the function that will be called to process the data written to this
\r
738 MSS I2C instance when it is the slave in an I2C write transaction.
\r
739 Note: The write handler is not called as a result of a write-read transaction.
\r
740 The write data of a write read transaction is interpreted as an offset
\r
741 into the slave’s transmit buffer and handled by the driver.
\r
742 ------------------------------------------------------------------------------
\r
744 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
745 identifying the MSS I2C hardware block that will perform the requested
\r
746 function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,
\r
747 associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must
\r
748 point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined
\r
749 within the I2C driver.
\r
752 Pointer to the function that will process the I2C write request.
\r
754 void MSS_I2C_register_write_handler
\r
756 mss_i2c_instance_t * this_i2c,
\r
757 mss_i2c_slave_wr_handler_t handler
\r
760 /*-------------------------------------------------------------------------*//**
\r
761 I2C slave receive enable.
\r
762 ------------------------------------------------------------------------------
\r
763 Enables the MSS I2C instance identified through the this_i2c parameter to
\r
764 receive data when it is the target of an I2C write or write-read transaction.
\r
765 ------------------------------------------------------------------------------
\r
767 The this_i2c parameter is a pointer to an mss_i2c_instance_t structure
\r
768 identifying the MSS I2C hardware block that will perform the requested
\r
769 function. There are two such data structures, g_mss_i2c0 and g_mss_i2c1,
\r
770 associated with MSS I2C 0 and MSS I2C 1 respectively. This parameter must
\r
771 point to either the g_mss_i2c0 or g_mss_i2c1 global data structure defined
\r
772 within the I2C driver.
\r
774 void MSS_I2C_enable_slave_rx
\r
776 mss_i2c_instance_t * this_i2c
\r
783 #endif /*MSS_I2C_H_*/
\r