1 /* 2 * Author: Thomas Ingleby <thomas.c.ingleby@intel.com> 3 * Copyright (c) 2014 Intel Corporation. 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining 6 * a copy of this software and associated documentation files (the 7 * "Software"), to deal in the Software without restriction, including 8 * without limitation the rights to use, copy, modify, merge, publish, 9 * distribute, sublicense, and/or sell copies of the Software, and to 10 * permit persons to whom the Software is furnished to do so, subject to 11 * the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be 14 * included in all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 19 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 20 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 21 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 22 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 23 */ 24 25 #pragma once 26 27 /** 28 * @file 29 * @brief Serial Peripheral Interface 30 * 31 * This file defines the spi interface for libmraa. A Spi object in libmraa 32 * represents a spidev device. Linux spidev devices are created per spi bus and 33 * every chip select available on that bus has another spidev 'file'. A lot 34 * more information on spidev devices is available 35 * [here](https://www.kernel.org/doc/Documentation/spi/spidev). 36 * 37 * @snippet spi_mcp4261.c Interesting 38 */ 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 #include <stdio.h> 45 #include <fcntl.h> 46 #include <stdint.h> 47 48 #include "common.h" 49 50 /** 51 * MRAA SPI Modes 52 */ 53 typedef enum { 54 MRAA_SPI_MODE0 = 0, /**< CPOL = 0, CPHA = 0, Clock idle low, data is clocked in on rising edge, 55 output data (change) on falling edge */ 56 MRAA_SPI_MODE1 = 1, /**< CPOL = 0, CPHA = 1, Clock idle low, data is clocked in on falling edge, 57 output data (change) on rising edge */ 58 MRAA_SPI_MODE2 = 2, /**< CPOL = 1, CPHA = 0, Clock idle low, data is clocked in on falling edge, 59 output data (change) on rising edge */ 60 MRAA_SPI_MODE3 = 3, /**< CPOL = 1, CPHA = 1, Clock idle low, data is clocked in on rising, edge 61 output data (change) on falling edge */ 62 } mraa_spi_mode_t; 63 64 /** 65 * Opaque pointer definition to the internal struct _spi 66 */ 67 typedef struct _spi* mraa_spi_context; 68 69 /** 70 * Initialise SPI_context, uses board mapping. Sets the muxes 71 * 72 * @param bus Bus to use, as listed in platform definition, normally 0 73 * @return Spi context or NULL 74 */ 75 mraa_spi_context mraa_spi_init(int bus); 76 77 /** 78 * Initialise SPI_context without any board configuration, selects a bus and a mux. 79 * 80 * @param bus Bus to use as listed by spidev 81 * @param cs Chip select to use as listed in spidev 82 * @return Spi context or NULL 83 */ 84 mraa_spi_context mraa_spi_init_raw(unsigned int bus, unsigned int cs); 85 86 /** 87 * Set the SPI device mode. see spidev 0-3. 88 * 89 * @param dev The Spi context 90 * @param mode The SPI mode, See Linux spidev 91 * @return Result of operation 92 */ 93 mraa_result_t mraa_spi_mode(mraa_spi_context dev, mraa_spi_mode_t mode); 94 95 /** 96 * Set the SPI device operating clock frequency. 97 * 98 * @param dev the Spi context 99 * @param hz the frequency in hz 100 * @return Result of operation 101 */ 102 mraa_result_t mraa_spi_frequency(mraa_spi_context dev, int hz); 103 104 /** 105 * Write Single Byte to the SPI device. 106 * 107 * @param dev The Spi context 108 * @param data Data to send 109 * @return Data received on the miso line or -1 in case of error 110 */ 111 int mraa_spi_write(mraa_spi_context dev, uint8_t data); 112 113 /** 114 *Write Two Bytes to the SPI device. 115 * 116 * @param dev The Spi context 117 * @param data Data to send 118 * @return Data received on the miso line 119 */ 120 uint16_t mraa_spi_write_word(mraa_spi_context dev, uint16_t data); 121 122 /** 123 * Write Buffer of bytes to the SPI device. The pointer return has to be 124 * free'd by the caller. It will return a NULL pointer in cases of error. 125 * 126 * @param dev The Spi context 127 * @param data to send 128 * @param length elements within buffer, Max 4096 129 * @return Data received on the miso line, same length as passed in 130 */ 131 uint8_t* mraa_spi_write_buf(mraa_spi_context dev, uint8_t* data, int length); 132 133 /** 134 * Write Buffer of uint16 to the SPI device. The pointer return has to be 135 * free'd by the caller. It will return a NULL pointer in cases of error. 136 * 137 * @param dev The Spi context 138 * @param data to send 139 * @param length elements (in bytes) within buffer, Max 4096 140 * @return Data received on the miso line, same length as passed in 141 */ 142 uint16_t* mraa_spi_write_buf_word(mraa_spi_context dev, uint16_t* data, int length); 143 144 /** 145 * Transfer Buffer of bytes to the SPI device. Both send and recv buffers 146 * are passed in 147 * 148 * @param dev The Spi context 149 * @param data to send 150 * @param rxbuf buffer to recv data back, may be NULL 151 * @param length elements within buffer, Max 4096 152 * @return Result of operation 153 */ 154 mraa_result_t mraa_spi_transfer_buf(mraa_spi_context dev, uint8_t* data, uint8_t* rxbuf, int length); 155 156 /** 157 * Transfer Buffer of uint16 to the SPI device. Both send and recv buffers 158 * are passed in 159 * 160 * @param dev The Spi context 161 * @param data to send 162 * @param rxbuf buffer to recv data back, may be NULL 163 * @param length elements (in bytes) within buffer, Max 4096 164 * @return Result of operation 165 */ 166 mraa_result_t mraa_spi_transfer_buf_word(mraa_spi_context dev, uint16_t* data, uint16_t* rxbuf, int length); 167 168 /** 169 * Change the SPI lsb mode 170 * 171 * @param dev The Spi context 172 * @param lsb Use least significant bit transmission. 0 for msbi 173 * @return Result of operation 174 */ 175 mraa_result_t mraa_spi_lsbmode(mraa_spi_context dev, mraa_boolean_t lsb); 176 177 /** 178 * Set bits per mode on transaction, defaults at 8 179 * 180 * @param dev The Spi context 181 * @param bits bits per word 182 * @return Result of operation 183 */ 184 mraa_result_t mraa_spi_bit_per_word(mraa_spi_context dev, unsigned int bits); 185 186 /** 187 * De-inits an mraa_spi_context device 188 * 189 * @param dev The Spi context 190 * @return Result of operation 191 */ 192 mraa_result_t mraa_spi_stop(mraa_spi_context dev); 193 194 #ifdef __cplusplus 195 } 196 #endif 197