i2c.h

Go to the documentation of this file.

/*
 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */
 
#ifndef _HARDWARE_I2C_H
#define _HARDWARE_I2C_H
 
#include "pico.h"
#include "pico/time.h"
#include "hardware/structs/i2c.h"
#include "hardware/regs/dreq.h"
 
// PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_HARDWARE_I2C, Enable/disable assertions in the hardware_i2c module, type=bool, default=0, group=hardware_i2c
#ifndef PARAM_ASSERTIONS_ENABLED_HARDWARE_I2C
#ifdef PARAM_ASSERTIONS_ENABLED_I2C // backwards compatibility with SDK < 2.0.0
#define PARAM_ASSERTIONS_ENABLED_HARDWARE_I2C PARAM_ASSERTIONS_ENABLED_I2C
#else
#define PARAM_ASSERTIONS_ENABLED_HARDWARE_I2C 0
#endif
#endif
#ifdef __cplusplus
extern "C" {
#endif

 
typedef struct i2c_inst i2c_inst_t;
 
// PICO_CONFIG: PICO_DEFAULT_I2C, Define the default I2C for a board, min=0, max=1, default=Usually provided via board header, group=hardware_i2c
// PICO_CONFIG: PICO_DEFAULT_I2C_SDA_PIN, Define the default I2C SDA pin, min=0, max=47 on RP2350B, 29 otherwise, default=Usually provided via board header, group=hardware_i2c
// PICO_CONFIG: PICO_DEFAULT_I2C_SCL_PIN, Define the default I2C SCL pin, min=0, max=47 on RP2350B, 29 otherwise, default=Usually provided via board header, group=hardware_i2c

extern i2c_inst_t i2c0_inst;
extern i2c_inst_t i2c1_inst;
 
#define i2c0 (&i2c0_inst) 
#define i2c1 (&i2c1_inst) 
 
#if !defined(PICO_DEFAULT_I2C_INSTANCE) && defined(PICO_DEFAULT_I2C)
#define PICO_DEFAULT_I2C_INSTANCE() (__CONCAT(i2c,PICO_DEFAULT_I2C))
#endif


#ifdef PICO_DEFAULT_I2C_INSTANCE
#define i2c_default PICO_DEFAULT_I2C_INSTANCE()
#endif

 
// ----------------------------------------------------------------------------
// Setup

uint i2c_init(i2c_inst_t *i2c, uint baudrate);

void i2c_deinit(i2c_inst_t *i2c);

uint i2c_set_baudrate(i2c_inst_t *i2c, uint baudrate);

void i2c_set_slave_mode(i2c_inst_t *i2c, bool slave, uint8_t addr);
 
// ----------------------------------------------------------------------------
// Generic input/output

struct i2c_inst {
    i2c_hw_t *hw;          
    bool restart_on_next;  
};

#ifndef I2C_NUM
static_assert(NUM_I2CS == 2, "");
#define I2C_NUM(i2c) ((i2c) == i2c1)
#endif

#ifndef I2C_INSTANCE
static_assert(NUM_I2CS == 2, "");
#define I2C_INSTANCE(num) ((num) ? i2c1 : i2c0)
#endif

#ifndef I2C_IS_INSTANCE
static_assert(NUM_I2CS == 2, "");
#define I2C_IS_INSTANCE(i2c) ((i2c) == i2c0 || (i2c) == i2c1)
#endif

#ifndef I2C_DREQ_NUM
static_assert(DREQ_I2C0_RX == DREQ_I2C0_TX + 1, "");
static_assert(DREQ_I2C1_RX == DREQ_I2C1_TX + 1, "");
static_assert(DREQ_I2C1_TX == DREQ_I2C0_TX + 2, "");
#define I2C_DREQ_NUM(i2c,is_tx) (DREQ_I2C0_TX + I2C_NUM(i2c) * 2 + !(is_tx))
#endif

#ifndef I2C_RESET_NUM
#include "hardware/resets.h"
#define I2C_RESET_NUM(i2c) (i2c_get_index(i2c) ? RESET_I2C1 : RESET_I2C0)
#endif

static inline uint i2c_get_index(i2c_inst_t *i2c) {
    valid_params_if(HARDWARE_I2C, I2C_IS_INSTANCE(i2c));
    return I2C_NUM(i2c);
}
 
// backward compatibility
#define i2c_hw_index(i2c) i2c_get_index(i2c)

static inline i2c_hw_t *i2c_get_hw(i2c_inst_t *i2c) {
    i2c_hw_index(i2c); // check it is a hw i2c
    return i2c->hw;
}

static inline i2c_inst_t *i2c_get_instance(uint num) {
    invalid_params_if(HARDWARE_I2C, num >= NUM_I2CS);
    return I2C_INSTANCE(num);
}

int i2c_write_blocking_until(i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t len, bool nostop, absolute_time_t until);

int i2c_read_blocking_until(i2c_inst_t *i2c, uint8_t addr, uint8_t *dst, size_t len, bool nostop, absolute_time_t until);

static inline int i2c_write_timeout_us(i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t len, bool nostop, uint timeout_us) {
    absolute_time_t t = make_timeout_time_us(timeout_us);
    return i2c_write_blocking_until(i2c, addr, src, len, nostop, t);
}
 
int i2c_write_timeout_per_char_us(i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t len, bool nostop, uint timeout_per_char_us);

static inline int i2c_read_timeout_us(i2c_inst_t *i2c, uint8_t addr, uint8_t *dst, size_t len, bool nostop, uint timeout_us) {
    absolute_time_t t = make_timeout_time_us(timeout_us);
    return i2c_read_blocking_until(i2c, addr, dst, len, nostop, t);
}
 
int i2c_read_timeout_per_char_us(i2c_inst_t *i2c, uint8_t addr, uint8_t *dst, size_t len, bool nostop, uint timeout_per_char_us);

int i2c_write_blocking(i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t len, bool nostop);

int i2c_write_burst_blocking(i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t len);

int i2c_read_blocking(i2c_inst_t *i2c, uint8_t addr, uint8_t *dst, size_t len, bool nostop);

int i2c_read_burst_blocking(i2c_inst_t *i2c, uint8_t addr, uint8_t *dst, size_t len);

static inline size_t i2c_get_write_available(i2c_inst_t *i2c) {
    const size_t IC_TX_BUFFER_DEPTH = 16;
    return IC_TX_BUFFER_DEPTH - i2c_get_hw(i2c)->txflr;
}

static inline size_t i2c_get_read_available(i2c_inst_t *i2c) {
    return i2c_get_hw(i2c)->rxflr;
}

static inline void i2c_write_raw_blocking(i2c_inst_t *i2c, const uint8_t *src, size_t len) {
    for (size_t i = 0; i < len; ++i) {
        // TODO NACK or STOP on end?
        while (!i2c_get_write_available(i2c))
            tight_loop_contents();
        i2c_get_hw(i2c)->data_cmd = *src++;
    }
}

static inline void i2c_read_raw_blocking(i2c_inst_t *i2c, uint8_t *dst, size_t len) {
    for (size_t i = 0; i < len; ++i) {
        while (!i2c_get_read_available(i2c))
            tight_loop_contents();
        *dst++ = (uint8_t)i2c_get_hw(i2c)->data_cmd;
    }
}

static inline uint8_t i2c_read_byte_raw(i2c_inst_t *i2c) {
    i2c_hw_t *hw = i2c_get_hw(i2c);
    assert(hw->status & I2C_IC_STATUS_RFNE_BITS); // Rx FIFO must not be empty
    return (uint8_t)hw->data_cmd;
}

static inline void i2c_write_byte_raw(i2c_inst_t *i2c, uint8_t value) {
    i2c_hw_t *hw = i2c_get_hw(i2c);
    assert(hw->status & I2C_IC_STATUS_TFNF_BITS); // Tx FIFO must not be full
    hw->data_cmd = value;
}

static inline uint i2c_get_dreq(i2c_inst_t *i2c, bool is_tx) {
    return I2C_DREQ_NUM(i2c, is_tx);
}
 
#ifdef __cplusplus
}
#endif
 
#endif