I2CSlave.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015-2019, Texas Instruments Incorporated
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
12  * * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  *
16  * * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 /*!****************************************************************************
33  * @file I2CSlave.h
34  * @brief Inter-Integrated Circuit (I2C) Slave Driver
35  *
36  * @anchor ti_drivers_I2CSlave_Overview
37  * # Overview
38  *
39  * The I2C Slave driver allows you to send and recieve I2C transfers.
40  * This driver complements the @ref I2C.h driver which operates
41  * as an I2C master.
42  *
43  * <hr>
44  * @anchor ti_drivers_I2CSlave_Usage
45  * # Usage
46  *
47  * This documentation provides a basic @ref ti_drivers_I2CSlave_Synopsis
48  * "usage summary" and a set of @ref ti_drivers_I2CSlave_Examples "examples"
49  * in the form of commented code fragments. Detailed descriptions of the
50  * APIs are provided in subsequent sections.
51 
52 
53  * @anchor ti_drivers_I2CSlave_Synopsis
54  * ## Synopsis #
55  * @anchor ti_drivers_I2CSlave_Synopsis_Code
56  * @code
57  * // Import I2C Slave Driver definitions
58  * #include <ti/drivers/I2CSlave.h>
59  *
60  * // Define name for an index of an I2C Slave
61  * #define MASTER_BUS 0
62  *
63  * // One-time init of I2C driver
64  * I2CSlave_init();
65  *
66  * // initialize optional I2C parameters
67  * I2CSlave_Params params;
68  * I2CSlave_Params_init(&params);
69  * params.transferMode = I2CSLAVE_MODE_BLOCKING;
70  *
71  * // Open I2C Slavefor usage
72  * I2CSlave_Handle i2cHandle = I2CSlave_open(MASTER_BUS, &params);
73  *
74  * // Wait for a write from an I2C master device
75  * I2CSlave_read(i2cHandle, buffer, 4);
76  *
77  * // Write to the I2C master device
78  * I2CSlave_write(i2cHandle, buffer, 2);
79  *
80  * // Close I2C
81  * I2CSlave_close(i2cHandle);
82  * @endcode
83  *
84  * @anchor ti_drivers_I2CSlave_Examples
85  * ## Examples
86  *
87  * @li @ref ti_drivers_I2CSlave_Example_open "Getting an I2C Slave handle"
88  * @li @ref ti_drivers_I2CSlave_Example_transferring "Transferring data"
89  *
90  * @anchor ti_drivers_I2CSlave_Example_open
91  * ## Opening the driver
92  *
93  * @code
94  * // Define name for an index of an I2C Slave
95  * #define MASTER_BUS 0
96  *
97  * I2CSlave_Handle handle;
98  * I2CSlave_Params params;
99  *
100  * // One-time init of I2C Slave driver
101  * I2CSlave_init();
102  *
103  * I2CSlave_Params_init(&params);
104  * params.transferMode = I2CSLAVE_MODE_CALLBACK;
105  * params.transferCallbackFxn = callbackFxn;
106  *
107  * handle = I2CSlave_open(0, &params);
108  * if (handle == NULL) {
109  * // I2C Slave failed to open
110  * while (1) {}
111  * }
112  * @endcode
113  *
114  * @anchor ti_drivers_I2CSlave_Example_transferring
115  * ## Transferring data
116  *
117  * @code
118  * status = I2CSlave_read(handle, buffer, 5)
119  * if (status == false) {
120  * //Unsuccessful I2CSlave read
121  * }
122  *
123  * status = I2CSlave_write(handle, buffer, 3);
124  * if (status == false) {
125  * //Unsuccessful I2CSlave write
126  * }
127  * @endcode
128  *
129  * <hr>
130  * @anchor ti_drivers_I2CSlave_Configuration
131  * # Configuration
132  *
133  * Refer to the @ref driver_configuration "Driver's Configuration" section
134  * for driver configuration information.
135  * <hr>
136  ******************************************************************************
137  */
138 
139 #ifndef ti_drivers_I2CSLAVE__include
140 #define ti_drivers_I2CSLAVE__include
141 
142 #include <stdbool.h>
143 #include <stddef.h>
144 #include <stdint.h>
145 
146 #ifdef __cplusplus
147 extern "C" {
148 #endif
149 
166 #define I2CSLAVE_CMD_RESERVED (32)
167 
180 #define I2CSLAVE_STATUS_RESERVED (-32)
181 
194 #define I2CSLAVE_STATUS_SUCCESS (0)
195 
202 #define I2CSLAVE_STATUS_ERROR (-1)
203 
211 #define I2CSLAVE_STATUS_UNDEFINEDCMD (-2)
212 
222 /* Add I2CSLAVE_CMD_<commands> here */
223 
232 
239 typedef enum {
240  I2CSLAVE_IDLE_MODE = 0,
241  I2CSLAVE_WRITE_MODE = 1,
242  I2CSLAVE_READ_MODE = 2,
243  I2CSLAVE_START_MODE = 3,
244  I2CSLAVE_ERROR = 0xFF
245 } I2CSlave_Mode;
246 
253 typedef enum {
254  /*
255  * In #I2CSLAVE_MODE_BLOCKING, calls to I2CSlave_read() and
256  * I2CSlave_write() block until the transfer completes. Other threads
257  * calling I2CSlave_read() or I2CSlave_write() while a transfer is in
258  * progress are also placed into a blocked state. If multiple threads are
259  * blocked, the thread with the highest priority will be unblocked first.
260  * This implies that arbitration will not be executed in chronological
261  * order.
262  *
263  * @note When using #I2CSLAVE_MODE_BLOCKING, I2CSlave_write() and
264  * I2CSlave_read() must be called from a thread context.
265  */
267 
268  /*
269  * In #I2CSLAVE_MODE_CALLBACK, calls to I2CSlave_read() and
270  * I2CSlave_write() return immediately. The application's callback
271  * function, #I2CSlave_Params.transferCallbackFxn, is called when the
272  * transfer is complete. The #I2CSlave_Params.transferCallbackFxn function
273  * will be called asynchronously as each transaction is completed.
274  */
277 
295 typedef void (*I2CSlave_CallbackFxn)(I2CSlave_Handle handle, bool status);
296 
305 typedef struct {
307  I2CSlave_TransferMode transferMode;
308 
312 
314  void *custom;
316 
322 typedef void (*I2CSlave_CloseFxn) (I2CSlave_Handle handle);
323 
329 typedef int_fast16_t (*I2CSlave_ControlFxn) (I2CSlave_Handle handle,
330  uint_fast16_t cmd,
331  void *arg);
332 
338 typedef void (*I2CSlave_InitFxn) (I2CSlave_Handle handle);
339 
345 typedef I2CSlave_Handle (*I2CSlave_OpenFxn) (I2CSlave_Handle handle,
346  I2CSlave_Params *params);
347 
353 typedef bool (*I2CSlave_WriteFxn) (I2CSlave_Handle handle,
354  const void *buffer, size_t size);
355 
356 
362 typedef bool (*I2CSlave_ReadFxn) (I2CSlave_Handle handle, void *buffer,
363  size_t size);
364 
365 
371 typedef struct {
373  I2CSlave_CloseFxn closeFxn;
374 
376  I2CSlave_ControlFxn controlFxn;
377 
379  I2CSlave_InitFxn initFxn;
380 
382  I2CSlave_OpenFxn openFxn;
383 
385  I2CSlave_ReadFxn readFxn;
386 
388  I2CSlave_WriteFxn writeFxn;
390 
398 typedef struct I2CSlave_Config_ {
402 
404  void *object;
405 
408  void const *hwAttrs;
410 
411 
419 extern void I2CSlave_close(I2CSlave_Handle handle);
420 
441 extern int_fast16_t I2CSlave_control(I2CSlave_Handle handle, uint_fast16_t cmd,
442  void *arg);
443 
449 extern void I2CSlave_init(void);
450 
469 extern I2CSlave_Handle I2CSlave_open(uint_least8_t index,
470  I2CSlave_Params *params);
471 
484 extern void I2CSlave_Params_init(I2CSlave_Params *params);
485 
509 extern bool I2CSlave_read(I2CSlave_Handle handle, void *buffer,
510  size_t size);
511 
537 extern bool I2CSlave_write(I2CSlave_Handle handle, const void *buffer,
538  size_t size);
539 
540 #ifdef __cplusplus
541 }
542 #endif
543 
544 #endif /* ti_drivers_I2CSLAVE__include */
struct I2CSlave_Config_ * I2CSlave_Handle
A handle that is returned from a I2CSlave_open() call.
Definition: I2CSlave.h:231
struct I2CSlave_Config_ I2CSlave_Config
I2C Slave driver&#39;s custom configuration structure.
I2CSlave_TransferMode
Return behavior of I2CSlave_write() and I2CSlave_read() specified in the I2CSlave_Params.
Definition: I2CSlave.h:253
void * object
Definition: I2CSlave.h:404
void I2CSlave_close(I2CSlave_Handle handle)
Function to close an I2CSlave driver instance.
bool I2CSlave_write(I2CSlave_Handle handle, const void *buffer, size_t size)
Perform an I2C write to an I2C master.
I2C Slave driver&#39;s custom configuration structure.
Definition: I2CSlave.h:398
I2CSlave_CallbackFxn transferCallbackFxn
Definition: I2CSlave.h:311
void const * hwAttrs
Definition: I2CSlave.h:408
int_fast16_t I2CSlave_control(I2CSlave_Handle handle, uint_fast16_t cmd, void *arg)
Function performs implementation specific features on a driver instance.
bool I2CSlave_read(I2CSlave_Handle handle, void *buffer, size_t size)
Perform an I2C read from an I2C master.
void(* I2CSlave_CallbackFxn)(I2CSlave_Handle handle, bool status)
The definition of a callback function.
Definition: I2CSlave.h:295
I2CSlave_FxnTable const * fxnTablePtr
Definition: I2CSlave.h:401
void * custom
Definition: I2CSlave.h:314
void I2CSlave_Params_init(I2CSlave_Params *params)
Initialize an I2CSlave_Params structure to its default values.
I2CSlave parameters used with I2CSlave_open().
Definition: I2CSlave.h:305
The definition of a I2CSlave function table that contains the required set of functions to control a ...
Definition: I2CSlave.h:371
I2CSlave_TransferMode transferMode
Definition: I2CSlave.h:307
Definition: I2CSlave.h:275
Definition: I2CSlave.h:266
void I2CSlave_init(void)
Function to initialize the I2C Slave driver.
I2CSlave_Handle I2CSlave_open(uint_least8_t index, I2CSlave_Params *params)
Function to initialize the I2CSlave peripheral.
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale