aardvark.h

Aardvark Example Source Code Version: 4.00 Date: 2007-04-20 Source code which shows how to use the

/*=========================================================================
| I2C API
 ========================================================================*/
/* Free the I2C bus. */
int aa_i2c_free_bus (
    Aardvark aardvark
);


/*
 * Set the I2C bit rate in kilohertz.  If a zero is passed as the
 * bitrate, the bitrate is unchanged and the current bitrate is
 * returned.
 */
int aa_i2c_bitrate (
    Aardvark aardvark,
    int      bitrate_khz
);


enum AardvarkI2cFlags {
    AA_I2C_NO_FLAGS     = 0x00,
    AA_I2C_10_BIT_ADDR  = 0x01,
    AA_I2C_COMBINED_FMT = 0x02,
    AA_I2C_NO_STOP      = 0x04
};
#ifndef __cplusplus
typedef enum AardvarkI2cFlags AardvarkI2cFlags;
#endif

/* Read a stream of bytes from the I2C slave device. */
int aa_i2c_read (
    Aardvark         aardvark,
    u16              slave_addr,
    AardvarkI2cFlags flags,
    u16              num_bytes,
    u08 *            data_in
);


enum AardvarkI2cStatus {
    AA_I2C_STATUS_OK            = 0,
    AA_I2C_STATUS_BUS_ERROR     = 1,
    AA_I2C_STATUS_SLA_ACK       = 2,
    AA_I2C_STATUS_SLA_NACK      = 3,
    AA_I2C_STATUS_DATA_NACK     = 4,
    AA_I2C_STATUS_ARB_LOST      = 5,
    AA_I2C_STATUS_BUS_LOCKED    = 6,
    AA_I2C_STATUS_LAST_DATA_ACK = 7
};
#ifndef __cplusplus
typedef enum AardvarkI2cStatus AardvarkI2cStatus;
#endif

/*
 * Read a stream of bytes from the I2C slave device.
 * This API function returns the number of bytes read into
 * the num_read variable.  The return value of the function
 * is a status code.
 */
int aa_i2c_read_ext (
    Aardvark         aardvark,
    u16              slave_addr,
    AardvarkI2cFlags flags,
    u16              num_bytes,
    u08 *            data_in,
    u16 *            num_read
);


/* Write a stream of bytes to the I2C slave device. */
int aa_i2c_write (
    Aardvark         aardvark,
    u16              slave_addr,
    AardvarkI2cFlags flags,
    u16              num_bytes,
    const u08 *      data_out
);


/*
 * Write a stream of bytes to the I2C slave device.
 * This API function returns the number of bytes written into
 * the num_written variable.  The return value of the function
 * is a status code.
 */
int aa_i2c_write_ext (
    Aardvark         aardvark,
    u16              slave_addr,
    AardvarkI2cFlags flags,
    u16              num_bytes,
    const u08 *      data_out,
    u16 *            num_written
);


/* Enable/Disable the Aardvark as an I2C slave device */
int aa_i2c_slave_enable (
    Aardvark aardvark,
    u08      addr,
    u16      maxTxBytes,
    u16      maxRxBytes
);


int aa_i2c_slave_disable (
    Aardvark aardvark
);


/*
 * Set the slave response in the event the Aardvark is put
 * into slave mode and contacted by a Master.
 */
int aa_i2c_slave_set_response (
    Aardvark    aardvark,
    u08         num_bytes,
    const u08 * data_out
);


/*
 * Return number of bytes written from a previous
 * Aardvark->I2C_master transmission.  Since the transmission is
 * happening asynchronously with respect to the PC host
 * software, there could be responses queued up from many
 * previous write transactions.
 */
int aa_i2c_slave_write_stats (
    Aardvark aardvark
);


/* Read the bytes from an I2C slave reception */
int aa_i2c_slave_read (
    Aardvark aardvark,
    u08 *    addr,
    u16      num_bytes,
    u08 *    data_in
);


/* Extended functions that return status code     */
int aa_i2c_slave_write_stats_ext (
    Aardvark aardvark,
    u16 *    num_written
);


int aa_i2c_slave_read_ext (
    Aardvark aardvark,
    u08 *    addr,
    u16      num_bytes,
    u08 *    data_in,
    u16 *    num_read
);


/*
 * Enable the I2C bus monitor
 * This disables all other functions on the Aardvark adapter
 */
int aa_i2c_monitor_enable (
    Aardvark aardvark
);


/* Disable the I2C bus monitor */
int aa_i2c_monitor_disable (
    Aardvark aardvark
);


/* Read the data collected by the bus monitor */
#define AA_I2C_MONITOR_DATA 0x00ff
#define AA_I2C_MONITOR_NACK 0x0100
#define AA_I2C_MONITOR_CMD_START 0xff00
#define AA_I2C_MONITOR_CMD_STOP 0xff01
int aa_i2c_monitor_read (
    Aardvark aardvark,
    u16      num_bytes,
    u16 *    data
);


/*
 * Configure the I2C pullup resistors.
 * This is only supported on hardware versions >= 2.00
 */
#define AA_I2C_PULLUP_NONE 0x00
#define AA_I2C_PULLUP_BOTH 0x03
#define AA_I2C_PULLUP_QUERY 0x80
int aa_i2c_pullup (
    Aardvark aardvark,
    u08      pullup_mask
);



/*=========================================================================
| SPI API
 ========================================================================*/
/*
 * Set the SPI bit rate in kilohertz.  If a zero is passed as the
 * bitrate, the bitrate is unchanged and the current bitrate is
 * returned.
 */
int aa_spi_bitrate (
    Aardvark aardvark,
    int      bitrate_khz
);


/*
 * These configuration parameters specify how to clock the
 * bits that are sent and received on the Aardvark SPI
 * interface.
 * 
 *   The polarity option specifies which transition
 *   constitutes the leading edge and which transition is the
 *   falling edge.  For example, AA_SPI_POL_RISING_FALLING
 *   would configure the SPI to idle the SCK clock line low.
 *   The clock would then transition low-to-high on the
 *   leading edge and high-to-low on the trailing edge.
 * 
 *   The phase option determines whether to sample or setup on
 *   the leading edge.  For example, AA_SPI_PHASE_SAMPLE_SETUP
 *   would configure the SPI to sample on the leading edge and
 *   setup on the trailing edge.
 * 
 *   The bitorder option is used to indicate whether LSB or
 *   MSB is shifted first.
 * 
 * See the diagrams in the Aardvark datasheet for
 * more details.
 */
enum AardvarkSpiPolarity {
    AA_SPI_POL_RISING_FALLING = 0,
    AA_SPI_POL_FALLING_RISING = 1
};
#ifndef __cplusplus
typedef enum AardvarkSpiPolarity AardvarkSpiPolarity;
#endif

enum AardvarkSpiPhase {
    AA_SPI_PHASE_SAMPLE_SETUP = 0,
    AA_SPI_PHASE_SETUP_SAMPLE = 1
};
#ifndef __cplusplus
typedef enum AardvarkSpiPhase AardvarkSpiPhase;
#endif

enum AardvarkSpiBitorder {
    AA_SPI_BITORDER_MSB = 0,
    AA_SPI_BITORDER_LSB = 1
};
#ifndef __cplusplus
typedef enum AardvarkSpiBitorder AardvarkSpiBitorder;
#endif

/* Configure the SPI master or slave interface */
int aa_spi_configure (
    Aardvark            aardvark,
    AardvarkSpiPolarity polarity,
    AardvarkSpiPhase    phase,
    AardvarkSpiBitorder bitorder
);


/* Write a stream of bytes to the downstream SPI slave device. */
int aa_spi_write (
    Aardvark    aardvark,
    u16         num_bytes,
    const u08 * data_out,
    u08 *       data_in
);


/* Enable/Disable the Aardvark as an SPI slave device */
int aa_spi_slave_enable (
    Aardvark aardvark
);


int aa_spi_slave_disable (
    Aardvark aardvark
);


/*
 * Set the slave response in the event the Aardvark is put
 * into slave mode and contacted by a Master.
 */
int aa_spi_slave_set_response (
    Aardvark    aardvark,
    u08         num_bytes,
    const u08 * data_out
);


/* Read the bytes from an SPI slave reception */
int aa_spi_slave_read (
    Aardvark aardvark,
    u16      num_bytes,
    u08 *    data_in
);


/*
 * Change the output polarity on the SS line.
 * 
 * Note: When configured as an SPI slave, the Aardvark will
 * always be setup with SS as active low.  Hence this function
 * only affects the SPI master functions on the Aardvark.
 */
enum AardvarkSpiSSPolarity {
    AA_SPI_SS_ACTIVE_LOW  = 0,
    AA_SPI_SS_ACTIVE_HIGH = 1
};
#ifndef __cplusplus
typedef enum AardvarkSpiSSPolarity AardvarkSpiSSPolarity;
#endif

int aa_spi_master_ss_polarity (
    Aardvark              aardvark,
    AardvarkSpiSSPolarity polarity
);



/*=========================================================================
| GPIO API
 ========================================================================*/
/*
 * The following enumerated type maps the named lines on the
 * Aardvark I2C/SPI line to bit positions in the GPIO API.
 * All GPIO API functions will index these lines through an
 * 8-bit masked value.  Thus, each bit position in the mask
 * can be referred back its corresponding line through the
 * enumerated type.
 */
enum AardvarkGpioBits {
    AA_GPIO_SCL  = 0x01,
    AA_GPIO_SDA  = 0x02,
    AA_GPIO_MISO = 0x04,
    AA_GPIO_SCK  = 0x08,
    AA_GPIO_MOSI = 0x10,
    AA_GPIO_SS   = 0x20
};
#ifndef __cplusplus
typedef enum AardvarkGpioBits AardvarkGpioBits;
#endif

/*
 * Configure the GPIO, specifying the direction of each bit.
 * 
 * A call to this function will not change the value of the pullup
 * mask in the Aardvark.  This is illustrated by the following
 * example:
 *   (1) Direction mask is first set to 0x00
 *   (2) Pullup is set to 0x01
 *   (3) Direction mask is set to 0x01
 *   (4) Direction mask is later set back to 0x00.
 * 
 * The pullup will be active after (4).
 * 
 * On Aardvark power-up, the default value of the direction
 * mask is 0x00.
 */
#define AA_GPIO_DIR_INPUT 0
#define AA_GPIO_DIR_OUTPUT 1
int aa_gpio_direction (
    Aardvark aardvark,
    u08      direction_mask
);


/*
 * Enable an internal pullup on any of the GPIO input lines.
 * 
 * Note: If a line is configured as an output, the pullup bit
 * for that line will be ignored, though that pullup bit will
 * be cached in case the line is later configured as an input.
 * 
 * By default the pullup mask is 0x00.
 */
#define AA_GPIO_PULLUP_OFF 0
#define AA_GPIO_PULLUP_ON 1
int aa_gpio_pullup (
    Aardvark aardvark,
    u08      pullup_mask
);


/*
 * Read the current digital values on the GPIO input lines.
 * 
 * The bits will be ordered as described by AA_GPIO_BITS.  If a
 * line is configured as an output, its corresponding bit
 * position in the mask will be undefined.
 */
int aa_gpio_get (
    Aardvark aardvark
);


/*
 * Set the outputs on the GPIO lines.
 * 
 * Note: If a line is configured as an input, it will not be
 * affected by this call, but the output value for that line
 * will be cached in the event that the line is later
 * configured as an output.
 */
int aa_gpio_set (
    Aardvark aardvark,
    u08      value
);


/*
 * Block until there is a change on the GPIO input lines.
 * Pins configured as outputs will be ignored.
 * 
 * The function will return either when a change has occurred or
 * the timeout expires.  The timeout, specified in millisecods, has
 * a precision of ~16 ms. The maximum allowable timeout is
 * approximately 4 seconds. If the timeout expires, this function
 * will return the current state of the GPIO lines.
 *
 * This function will return immediately with the current value
 * of the GPIO lines for the first invocation after any of the
 * following functions are called: aa_configure,
 * aa_gpio_direction, or aa_gpio_pullup.
 *
 * If the function aa_gpio_get is called before calling
 * aa_gpio_change, aa_gpio_change will only register any changes
 * from the value last returned by aa_gpio_get.
 */
int aa_gpio_change (
    Aardvark aardvark,
    u16      timeout
);




#ifdef __cplusplus
}
#endif

#endif  /* __aardvark_h__ */