spi.h

Go to the documentation of this file.

/*
 * This file is part of the Ultibo project, https://ultibo.org/
 *
 * The MIT License (MIT)
 *
 * Copyright (c) 2026 Garry Wood <garry@softoz.com.au>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
#ifndef _ULTIBO_SPI_H
#define _ULTIBO_SPI_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "ultibo/globaltypes.h"
#include "ultibo/globalconst.h"
#include "ultibo/devices.h"

#define SPI_NAME_PREFIX "SPI" 
#define SPISLAVE_NAME_PREFIX    "SPISlave" 

#define SPI_TYPE_NONE   0
#define SPI_TYPE_MASTER 1
#define SPI_TYPE_SLAVE  2
 
#define SPI_TYPE_MAX    2

#define SPI_STATE_DISABLED  0
#define SPI_STATE_ENABLED   1
 
#define SPI_STATE_MAX   1

#define SPI_FLAG_NONE   0x00000000
#define SPI_FLAG_SLAVE  0x00000001 
#define SPI_FLAG_4WIRE  0x00000002 
#define SPI_FLAG_3WIRE  0x00000004 
#define SPI_FLAG_LOSSI  0x00000008 
#define SPI_FLAG_CPOL   0x00000010 
#define SPI_FLAG_CPHA   0x00000020 
#define SPI_FLAG_CSPOL  0x00000040 
#define SPI_FLAG_NO_CS  0x00000080 
#define SPI_FLAG_DMA    0x00000100 

#define SPI_TRANSFER_NONE   0x00000000
#define SPI_TRANSFER_DMA    0x00000001 
#define SPI_TRANSFER_PIO    0x00000002 
#define SPI_TRANSFER_DELAY  0x00000004 


typedef struct _SPI_PROPERTIES SPI_PROPERTIES;
struct _SPI_PROPERTIES
{
    uint32_t flags; 
    uint32_t maxsize; 
    uint32_t minclock; 
    uint32_t maxclock; 
    uint32_t selectcount; 
    uint32_t mode; 
    uint32_t clockrate; 
    uint32_t clockphase; 
    uint32_t clockpolarity; 
    uint32_t selectpolarity; 
    uint32_t bytedelay; 
};
 

typedef struct _SPI_CHIP_SELECT SPI_CHIP_SELECT;
struct _SPI_CHIP_SELECT
{
    uint32_t pin; 
    uint32_t mode; 
    uint32_t divider; 
    uint32_t clockrate; 
    uint32_t clockphase; 
    uint32_t clockpolarity; 
    uint32_t selectpolarity; 
    uint32_t bytedelay; 
};
 

typedef struct _SPI_DEVICE SPI_DEVICE;

typedef uint32_t STDCALL (*spi_enumerate_cb)(SPI_DEVICE *spi, void *data);
typedef uint32_t STDCALL (*spi_notification_cb)(DEVICE *device, void *data, uint32_t notification);

typedef uint32_t STDCALL (*spi_device_start_proc)(SPI_DEVICE *spi, uint32_t mode, uint32_t clockrate, uint32_t clockphase, uint32_t clockpolarity);
typedef uint32_t STDCALL (*spi_device_stop_proc)(SPI_DEVICE *spi);
 
typedef uint32_t STDCALL (*spi_device_read_proc)(SPI_DEVICE *spi, uint16_t chipselect, void *dest, uint32_t size, uint32_t flags, uint32_t *count);
typedef uint32_t STDCALL (*spi_device_write_proc)(SPI_DEVICE *spi, uint16_t chipselect, void *source, uint32_t size, uint32_t flags, uint32_t *count);
typedef uint32_t STDCALL (*spi_device_write_read_proc)(SPI_DEVICE *spi, uint16_t chipselect, void *source, void *dest, uint32_t size, uint32_t flags, uint32_t *count);
 
typedef uint32_t STDCALL (*spi_device_get_mode_proc)(SPI_DEVICE *spi);
typedef uint32_t STDCALL (*spi_device_set_mode_proc)(SPI_DEVICE *spi, uint32_t mode);
 
typedef uint32_t STDCALL (*spi_device_get_clock_rate_proc)(SPI_DEVICE *spi, uint16_t chipselect);
typedef uint32_t STDCALL (*spi_device_set_clock_rate_proc)(SPI_DEVICE *spi, uint16_t chipselect, uint32_t clockrate);
 
typedef uint32_t STDCALL (*spi_device_get_clock_phase_proc)(SPI_DEVICE *spi);
typedef uint32_t STDCALL (*spi_device_set_clock_phase_proc)(SPI_DEVICE *spi, uint32_t clockphase);
 
typedef uint32_t STDCALL (*spi_device_get_clock_polarity_proc)(SPI_DEVICE *spi);
typedef uint32_t STDCALL (*spi_device_set_clock_polarity_proc)(SPI_DEVICE *spi, uint32_t clockpolarity);
 
typedef uint32_t STDCALL (*spi_device_get_select_polarity_proc)(SPI_DEVICE *spi, uint16_t chipselect);
typedef uint32_t STDCALL (*spi_device_set_select_polarity_proc)(SPI_DEVICE *spi, uint16_t chipselect, uint32_t selectpolarity);
 
typedef uint32_t STDCALL (*spi_device_get_byte_delay_proc)(SPI_DEVICE *spi);
typedef uint32_t STDCALL (*spi_device_set_byte_delay_proc)(SPI_DEVICE *spi, uint32_t delay);
 
typedef uint32_t STDCALL (*spi_device_get_properties_proc)(SPI_DEVICE *spi, SPI_PROPERTIES *properties);
 
struct _SPI_DEVICE
{
    // Device Properties
    DEVICE device; 
    // SPI Properties
    uint32_t spiid; 
    uint32_t spistate; 
    uint32_t spimode; 
    spi_device_start_proc devicestart; 
    spi_device_stop_proc devicestop; 
    spi_device_read_proc deviceread; 
    spi_device_write_proc devicewrite; 
    spi_device_write_read_proc devicewriteread; 
    spi_device_get_mode_proc devicegetmode; 
    spi_device_set_mode_proc devicesetmode; 
    spi_device_get_clock_rate_proc devicegetclockrate; 
    spi_device_set_clock_rate_proc devicesetclockrate; 
    spi_device_get_clock_phase_proc devicegetclockphase; 
    spi_device_set_clock_phase_proc devicesetclockphase; 
    spi_device_get_clock_polarity_proc devicegetclockpolarity; 
    spi_device_set_clock_polarity_proc devicesetclockpolarity; 
    spi_device_get_select_polarity_proc devicegetselectpolarity; 
    spi_device_set_select_polarity_proc devicesetselectpolarity; 
    spi_device_get_byte_delay_proc devicegetbytedelay; 
    spi_device_set_byte_delay_proc devicesetbytedelay; 
    spi_device_get_properties_proc devicegetproperties; 
    // Statistics Properties
    uint32_t transfercount;
    uint32_t transfererrors;
    // Driver Properties
    MUTEX_HANDLE lock; 
    SEMAPHORE_HANDLE wait; 
    uint32_t divider; 
    uint32_t clockrate; 
    uint32_t clockphase; 
    uint32_t clockpolarity; 
    uint32_t selectpolarity; 
    uint32_t bytedelay; 
    SPI_PROPERTIES properties; 
    SPI_CHIP_SELECT chipselects[SPI_CS_MAX + 1]; 
    // Internal Properties
    SPI_DEVICE *prev; 
    SPI_DEVICE *next; 
};


uint32_t STDCALL spi_device_start(SPI_DEVICE *spi, uint32_t mode, uint32_t clockrate, uint32_t clockphase, uint32_t clockpolarity);

uint32_t STDCALL spi_device_stop(SPI_DEVICE *spi);

uint32_t STDCALL spi_device_read(SPI_DEVICE *spi, uint16_t chipselect, void *dest, uint32_t size, uint32_t flags, uint32_t *count);

uint32_t STDCALL spi_device_write(SPI_DEVICE *spi, uint16_t chipselect, void *source, uint32_t size, uint32_t flags, uint32_t *count);

uint32_t STDCALL spi_device_write_read(SPI_DEVICE *spi, uint16_t chipselect, void *source, void *dest, uint32_t size, uint32_t flags, uint32_t *count);

uint32_t STDCALL spi_device_get_mode(SPI_DEVICE *spi);

uint32_t STDCALL spi_device_set_mode(SPI_DEVICE *spi, uint32_t mode);

uint32_t STDCALL spi_device_get_clock_rate(SPI_DEVICE *spi, uint16_t chipselect);

uint32_t STDCALL spi_device_set_clock_rate(SPI_DEVICE *spi, uint16_t chipselect, uint32_t clockrate);

uint32_t STDCALL spi_device_get_clock_phase(SPI_DEVICE *spi);

uint32_t STDCALL spi_device_set_clock_phase(SPI_DEVICE *spi, uint32_t clockphase);

uint32_t STDCALL spi_device_get_clock_polarity(SPI_DEVICE *spi);

uint32_t STDCALL spi_device_set_clock_polarity(SPI_DEVICE *spi, uint32_t clockpolarity);

uint32_t STDCALL spi_device_get_select_polarity(SPI_DEVICE *spi, uint16_t chipselect);

uint32_t STDCALL spi_device_set_select_polarity(SPI_DEVICE *spi, uint16_t chipselect, uint32_t selectpolarity);

uint32_t STDCALL spi_device_get_byte_delay(SPI_DEVICE *spi);

uint32_t STDCALL spi_device_set_byte_delay(SPI_DEVICE *spi, uint32_t delay);

uint32_t STDCALL spi_device_properties(SPI_DEVICE *spi, SPI_PROPERTIES *properties);

uint32_t STDCALL spi_device_get_properties(SPI_DEVICE *spi, SPI_PROPERTIES *properties);

SPI_DEVICE * STDCALL spi_device_create(void);

SPI_DEVICE * STDCALL spi_device_create_ex(uint32_t size);

uint32_t STDCALL spi_device_destroy(SPI_DEVICE *spi);

uint32_t STDCALL spi_device_register(SPI_DEVICE *spi);

uint32_t STDCALL spi_device_deregister(SPI_DEVICE *spi);

SPI_DEVICE * STDCALL spi_device_find(uint32_t spiid);

SPI_DEVICE * STDCALL spi_device_find_by_name(const char *name);

SPI_DEVICE * STDCALL spi_device_find_by_description(const char *description);

uint32_t STDCALL spi_device_enumerate(spi_enumerate_cb callback, void *data);

uint32_t STDCALL spi_device_notification(SPI_DEVICE *spi, spi_notification_cb callback, void *data, uint32_t notification, uint32_t flags);


uint32_t STDCALL spi_get_count(void);

SPI_DEVICE * STDCALL spi_device_get_default(void);

uint32_t STDCALL spi_device_set_default(SPI_DEVICE *spi);

SPI_DEVICE * STDCALL spi_device_check(SPI_DEVICE *spi);

uint32_t STDCALL spi_type_to_string(uint32_t spitype, char *string, uint32_t len);

uint32_t STDCALL spi_state_to_string(uint32_t spistate, char *string, uint32_t len);
 
uint32_t STDCALL spi_chip_select_to_string(uint16_t chipselect, char *string, uint32_t len);
uint32_t STDCALL spi_mode_to_string(uint32_t mode, char *string, uint32_t len);
uint32_t STDCALL spi_clock_phase_to_string(uint32_t phase, char *string, uint32_t len);
uint32_t STDCALL spi_clock_polarity_to_string(uint32_t polarity, char *string, uint32_t len);
uint32_t STDCALL spi_select_polarity_to_string(uint32_t polarity, char *string, uint32_t len);
 
#ifdef __cplusplus
}
#endif
 
#endif // _ULTIBO_SPI_H