Ryan Malloy a7f62e5d7e Add Silicon Labs CP210x manufacturing library source
- Library source from AN721SW (cp210xmanufacturing_1.0.tar.gz)
- Manufacturing tool source (cp210xsmt)
- Builds 64-bit shared library with: make LIB_ARCH=64
- Datasheets and app notes in docs/
2026-01-30 10:31:39 -07:00

611 lines
20 KiB
C

//-----------------------------------------------------------------------------
// SLAB_USB_SPI.h
//-----------------------------------------------------------------------------
// Copyright 2012-2016 Silicon Laboratories Inc.
// http://www.silabs.com
//-----------------------------------------------------------------------------
/// @file SLAB_USB_SPI.h
/// This file defines the API of the CP2130 Interface Library
#ifndef SLAB_USB_SPI_H
#define SLAB_USB_SPI_H
/////////////////////////////////////////////////////////////////////////////
// Includes
/////////////////////////////////////////////////////////////////////////////
#include "Types.h"
/////////////////////////////////////////////////////////////////////////////
// Variable types
/////////////////////////////////////////////////////////////////////////////
/// @name Variable type definitions
/// @{
typedef void* CP213x_DEVICE;
typedef int USB_SPI_STATUS;
/// @}
/////////////////////////////////////////////////////////////////////////////
// Definitions specific to USB SPI code
/////////////////////////////////////////////////////////////////////////////
/// @name Definitions specific to USB SPI code
/// @{
//#define LIBVERSION_MAJOR 1
//#define LIBVERSION_MINOR 0
//#define LIBVERSION_ISRELEASE true
#define LANGIDENG 0x0409
#define BULK_PACKETSIZE 64
#define EP_BUFSIZE BULK_PACKETSIZE
#define CMD_SIZE 8
#define CMD_TIMEOUT_MS 1000 // Timeout for completion of SPI command (i.e. first packet)
#define STRING_DESCRIPTOR_SIZE 256
#define SIZE_PIN_CONFIG 20
// Maximum block size for WriteRead
#define WRITEREAD_MAX_BLOCKSIZE 256 // Matches size of firmware Read buffer
// Number of GPIO/CS pins
#define CP213x_NUM_GPIO 11
// Chip Select Mode: 0: Idle, 1: Active, 2: Active; all other channels idle
#define CSMODE_IDLE 0
#define CSMODE_ACTIVE 1
#define CSMODE_ACTIVE_OTHERS_IDLE 2
// Mode definitions for GPIO/CS/SpecialFunction pins
#define GPIO_MODE_INPUT 0
#define GPIO_MODE_OUTPUT_OD 1
#define GPIO_MODE_OUTPUT_PP 2
#define GPIO_MODE_CHIPSELECT 3 // Chip select mode
#define GPIO_MODE__RTR_ACTLOW 4
#define GPIO_MODE__RTR_ACTHIGH 5
#define GPIO_MODE__EVTCNTR_RISING 4
#define GPIO_MODE__EVTCNTR_FALLING 5
#define GPIO_MODE__EVTCNTR_NEGPULSE 6
#define GPIO_MODE__EVTCNTR_POSPULSE 7
#define GPIO_MODE__CLK_OUT 4
#define GPIO_MODE__SPI_ACTIVITY 4
#define GPIO_MODE__SUSPEND 4
#define GPIO_MODE__SUSPENDBAR 4
// End of GPIO Mode definitions
// String Buffer Definitions
#define SHORT_STRING_LEN 60
#define LONG_STRING_LEN_1 61
#define LONG_STRING_LEN_2 63
/// @}
////////////////////////////////////////////////////////////////////////////////
// SPI Command and Subcommand definitions
////////////////////////////////////////////////////////////////////////////////
/// @name SPI Data Transfer command and subcommands
/// @{
#define CMD_TRANSFER_DATA 0x0000
// Subcommand definitions for TRANSFER_DATA command
#define SUBCMD_READ 0
#define SUBCMD_WRITE 1
#define SUBCMD_WRITEREAD 2
#define SUBCMD_RTREAD 4
#define SUBCMD_MSB_RELEASE_BUS 0x80
/// @}
/// @name SPI Control Word bitfield definitions
/// @{
// Bits 7-6: Not assigned
// Bit 5: Clock phase (CPHA)
#define SPICTL_CPHA_SHIFT 5
#define SPICTL_CPHA_MASK 0x20
#define SPICTL_CPHA_LEADING_EDGE 0
#define SPICTL_CPHA_TRAILING_EDGE 1
// Bit 4: Clock polarity (CPOL)
#define SPICTL_CPOL_SHIFT 4
#define SPICTL_CPOL_MASK 0x10
#define SPICTL_CPOL_ACTIVE_HIGH 0
#define SPICTL_CPOL_ACTIVE_LOW 1
// Bit 3: Chip Select Mode
#define SPICTL_CSMODE_SHIFT 3
#define SPICTL_CSMODE_MASK 0x08
#define SPICTL_CSMODE_OPENDRAIN 0
#define SPICTL_CSMODE_PUSHPULL 1
// Bit 2-0: Clock rate
#define SPICTL_CLKRATE_SHIFT 0
#define SPICTL_CLKRATE_MASK 0x07
#define SPICTL_CLKRATE_12M 0 // 12 MHz
#define SPICTL_CLKRATE_6M 1 // 6 MHz
#define SPICTL_CLKRATE_3M 2 // 3 MHz
#define SPICTL_CLKRATE_1M5 3 // 1.5 MHz
#define SPICTL_CLKRATE_750K 4 // 750 kHz
#define SPICTL_CLKRATE_375K 5 // 375 kHz
#define SPICTL_CLKRATE_187K5 6 // 187.5 kHz
#define SPICTL_CLKRATE_93K75 7 // 93.75 kHz
/// @}
/////////////////////////////////////////////////////////////////////////////
// Error Definitions
/////////////////////////////////////////////////////////////////////////////
/// @name Return values for BOOL-returning functions
/// @{
#define bRESULT_PASS TRUE
#define bRESULT_FAIL FALSE
/// @}
#define USB_SPI_ERRCODE_SYSTEM_ERROR 0xFFFFFFFE
/// @name CP2130 General Errors
/// @{
#define USB_SPI_ERRCODE_SUCCESS 0x00 /// The function returned successfully.
#define USB_SPI_ERRCODE_ALLOC_FAILURE 0x01 /// Allocation error.
#define USB_SPI_ERRCODE_INVALID_ENUM_VALUE 0x02 /// Invalid enumeration value.
#define USB_SPI_ERRCODE_NULL_POINTER 0x03 /// Null pointer.
#define USB_SPI_ERRCODE_INVALID_CHANNEL_INDEX 0x04 /// Channel index is not in range.
#define USB_SPI_ERRCODE_INVALID_GPIO_MODE 0x05 /// Mode != INPUT, OUTPUT_OD, or OUTPUT_PP.
#define USB_SPI_ERRCODE_UNKNOWN_ERROR 0xFFFFFFFF /// Unknown/unspecified error.
/// @}
//
// API Errors
//
/// @name CP2130 API Errors
/// @{
#define USB_SPI_ERRCODE_INVALID_PARAMETER 0x10 /// Invalid function parameter.
#define USB_SPI_ERRCODE_INVALID_DEVICE_OBJECT 0x11 /// The specified device object pointer is invalid.
/// @}
//
// Device Errors
//
/// @name CP2130 Device Errors
/// @{
// The specified USB device could not be found.
#define USB_SPI_ERRCODE_DEVICE_NOT_FOUND 0x20
// The current USB device is not opened.
#define USB_SPI_ERRCODE_USB_DEVICE_NOT_OPENED 0x21
// The handle is invalid.
#define USB_SPI_ERRCODE_INVALID_HANDLE 0x22
/// @}
//
// Device Hardware Interface Errors
//
/// @name CP2130 Device Hardware Interface Errors
/// @{
// An error occurred while communicating with the device or while retrieving device information.
#define USB_SPI_ERRCODE_HWIF_DEVICE_ERROR 0x30
// A control transfer operation timed out.
#define USB_SPI_ERRCODE_HWIF_TRANSFER_TIMEOUT 0x31
/// @}
/// @name CP2130 Data Transfer Errors
/// @{
#define USB_SPI_ERRCODE_CONTROL_TRANSFER_ERROR 0x50
#define USB_SPI_ERRCODE_INVALID_TRANSFER_SIZE 0x51
#define USB_SPI_ERRCODE_PIPE_INIT_FAIL 0x60
#define USB_SPI_ERRCODE_PIPE_QUERY_FAIL 0x61
#define USB_SPI_ERRCODE_PIPE_WRITE_FAIL 0x62
#define USB_SPI_ERRCODE_PIPE_READ_FAIL 0x63
#define USB_SPI_ERRCODE_PIPE_ABORT_FAIL 0x64
#define USB_SPI_ERRCODE_PIPE_FLUSH_FAIL 0x65
#define USB_SPI_ERRCODE_PIPE_INVALID_ID 0x66
#define USB_SPI_ERRCODE_READ_THREAD_CREATE_FAILURE 0x70
#define USB_SPI_ERRCODE_READ_THREAD_NOT_RUNNING 0x71
#define USB_SPI_ERRCODE_READ_THREAD_START_FAILURE 0x72
#define USB_SPI_ERRCODE_DEVICE_RETURNED_TOO_MUCH_DATA 0x80
/// @}
/// @name CP213x Customization Masks
/// @{
// User-Customizable Field Lock Bitmasks
#define CP213x_LOCK_PRODUCT_STR_1 0x0001
#define CP213x_LOCK_PRODUCT_STR_2 0x0002
#define CP213x_LOCK_SERIAL_STR 0x0004
#define CP213x_LOCK_PIN_CONFIG 0x0008
#define CP213x_LOCK_VID 0x0100
#define CP213x_LOCK_PID 0x0200
#define CP213x_LOCK_POWER 0x0400
#define CP213x_LOCK_POWER_MODE 0x0800
#define CP213x_LOCK_RELEASE_VERSION 0x1000
#define CP213x_LOCK_MFG_STR_1 0x2000
#define CP213x_LOCK_MFG_STR_2 0x4000
#define CP213x_LOCK_TRANSFER_PRIORITY 0x8000
// USB Config Bitmasks
#define CP213x_SET_VID 0x01
#define CP213x_SET_PID 0x02
#define CP213x_SET_POWER 0x04
#define CP213x_SET_POWER_MODE 0x08
#define CP213x_SET_RELEASE_VERSION 0x10
#define CP213x_SET_TRANSFER_PRIORITY 0x80
// String Lengths
#define MFG_STRLEN 62
#define PRODUCT_STRLEN 62
#define SERIAL_STRLEN 30
// MFG_STR
typedef char MFG_STR[MFG_STRLEN];
// PRODUCT_STR
typedef char PRODUCT_STR[PRODUCT_STRLEN];
// SERIAL_STR
typedef char SERIAL_STR[SERIAL_STRLEN];
/////////////////////////////////////////////////////////////////////////////
// Enumerations
/////////////////////////////////////////////////////////////////////////////
enum SET_STATUS {SET_SUCCESS, SET_FAIL, SET_VERIFY_FAIL};
/////////////////////////////////////////////////////////////////////////////
// Pin Definitions
/////////////////////////////////////////////////////////////////////////////
// Pin Config Mode Array Indices
#define CP213x_INDEX_GPIO_0 0
#define CP213x_INDEX_GPIO_1 1
#define CP213x_INDEX_GPIO_2 2
#define CP213x_INDEX_GPIO_3 3
#define CP213x_INDEX_GPIO_4 4
#define CP213x_INDEX_GPIO_5 5
#define CP213x_INDEX_GPIO_6 6
#define CP213x_INDEX_GPIO_7 7
#define CP213x_INDEX_GPIO_8 8
#define CP213x_INDEX_GPIO_9 9
#define CP213x_INDEX_GPIO_10 10
// Pin Bitmasks
#define CP213x_MASK_SCK 0x0001
#define CP213x_MASK_MISO 0x0002
#define CP213x_MASK_MOSI 0x0004
#define CP213x_MASK_GPIO_0 0x0008
#define CP213x_MASK_GPIO_1 0x0010
#define CP213x_MASK_GPIO_2 0x0020
#define CP213x_MASK_GPIO_3 0x0040
#define CP213x_MASK_GPIO_4 0x0080
#define CP213x_MASK_GPIO_5 0x0100
#define CP213x_MASK_GPIO_6 0x0400
#define CP213x_MASK_GPIO_7 0x0800
#define CP213x_MASK_GPIO_8 0x1000
#define CP213x_MASK_GPIO_9 0x2000
#define CP213x_MASK_GPIO_10 0x4000
/// @}
////////////////////////////////////////////////////////////////////////////////
// Structures
////////////////////////////////////////////////////////////////////////////////
/// @name Type and structure definitions
/// @{
/// This struct has the same format as _USB_DEVICE_DESCRIPTOR, as defined in Windows usb100.h.
/// Using this typedef enables portable application code.
typedef struct DEVICE_DESCRIPTOR
{
BYTE bLength;
BYTE bDescriptorType;
WORD bcdUSB;
BYTE bDeviceClass;
BYTE bDeviceSubClass;
BYTE bDeviceProtocol;
BYTE bMaxPacketSize0;
WORD idVendor;
WORD idProduct;
WORD bcdDevice;
BYTE iManufacturer;
BYTE iProduct;
BYTE iSerialNumber;
BYTE bNumConfigurations;
} DEVICE_DESCRIPTOR, *PDEVICE_DESCRIPTOR;
/// SPI Command Word
typedef struct SPI_CMD
{
WORD Cmd;
WORD SubCmd;
DWORD Len;
DWORD blockSize;
DWORD timeoutMs;
DWORD res;
} SPI_CMD, *PSPI_CMD;
// Bitfield masks for delay_mode structure element
#define SPI_INTERBYTE_DELAY_MASK 0x01
#define SPI_CS_POSTASSERT_DELAY_MASK 0x02
#define SPI_CS_PREDEASSERT_DELAY_MASK 0x04
#define SPI_CS_TOGGLE_MASK 0x08
/// @}
/////////////////////////////////////////////////////////////////////////////
// Exported API Functions
/////////////////////////////////////////////////////////////////////////////
/// @name Exported API Functions
/// @{
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
USB_SPI_STATUS
CP213x_GetLibraryVersion( BYTE* major, BYTE* minor, BOOL* release );
//
// CP2130 Device Management
//
/// @name CP2130 Device Management
/// @{
USB_SPI_STATUS
CP213x_GetNumDevices ( DWORD* numDevices, DWORD VID, DWORD PID );
USB_SPI_STATUS
CP213x_Open ( DWORD deviceIndex, CP213x_DEVICE* phDevice, DWORD VID, DWORD PID );
USB_SPI_STATUS
CP213x_Close ( CP213x_DEVICE hDevice );
BOOL
CP213x_IsOpened ( CP213x_DEVICE hDevice);
USB_SPI_STATUS
CP213x_Reset ( CP213x_DEVICE hDevice );
USB_SPI_STATUS
CP213x_GetDeviceVersion ( CP213x_DEVICE hDevice, BYTE* majorVersion, BYTE* minorVersion );
USB_SPI_STATUS
CP213x_GetDeviceDescriptor ( CP213x_DEVICE hDevice,
PDEVICE_DESCRIPTOR pDescriptor );
USB_SPI_STATUS
CP213x_GetStringDescriptor ( CP213x_DEVICE hDevice,
BYTE index,
BYTE stringDescriptor[STRING_DESCRIPTOR_SIZE] );
USB_SPI_STATUS
CP213x_GetUsbConfig ( CP213x_DEVICE hDevice,
WORD* vid,
WORD* pid,
BYTE* power,
BYTE* powerMode,
WORD* releaseVersion,
BYTE* transferPriority );
USB_SPI_STATUS
CP213x_SetUsbConfig ( CP213x_DEVICE hDevice,
WORD vid,
WORD pid,
BYTE power,
BYTE powerMode,
WORD releaseVersion,
BYTE transferPriority,
BYTE mask );
USB_SPI_STATUS
CP213x_GetManufacturingString ( CP213x_DEVICE hDevice, LPSTR manufacturingString, BYTE* strlen );
USB_SPI_STATUS
CP213x_SetManufacturingString ( CP213x_DEVICE hDevice, LPCSTR manufacturingString, BYTE strlen );
USB_SPI_STATUS
CP213x_GetProductString ( CP213x_DEVICE hDevice, LPSTR productString, BYTE* strlen );
USB_SPI_STATUS
CP213x_SetProductString ( CP213x_DEVICE hDevice, LPCSTR productString, BYTE strlen );
USB_SPI_STATUS
CP213x_GetSerialString ( CP213x_DEVICE hDevice, LPSTR serialString, BYTE* strlen );
USB_SPI_STATUS
CP213x_SetSerialString ( CP213x_DEVICE hDevice, LPCSTR serialString, BYTE strlen );
USB_SPI_STATUS
CP213x_GetPinConfig ( CP213x_DEVICE hDevice, BYTE pinConfig[SIZE_PIN_CONFIG] );
USB_SPI_STATUS
CP213x_SetPinConfig ( CP213x_DEVICE hDevice, BYTE pinConfig[SIZE_PIN_CONFIG] );
USB_SPI_STATUS
CP213x_GetLock ( CP213x_DEVICE hDevice, WORD* lockValue );
USB_SPI_STATUS
CP213x_SetLock ( CP213x_DEVICE hDevice, WORD lockValue );
USB_SPI_STATUS
CP213x_ReadProm ( CP213x_DEVICE hDevice, BYTE pReadBuf[] );
USB_SPI_STATUS
CP213x_WriteProm ( CP213x_DEVICE hDevice, BYTE pWriteBuf[] );
/// @}
//
// CP2130 SPI Configuration and Transfer Operations
//
/// @name CP2130 SPI Configuration and Transfer Operations
/// @{
USB_SPI_STATUS
CP213x_GetSpiControlBytes ( CP213x_DEVICE hDevice, BYTE controlBytes[CP213x_NUM_GPIO] );
USB_SPI_STATUS
CP213x_SetSpiControlByte ( CP213x_DEVICE hDevice, BYTE channel, BYTE controlByte );
USB_SPI_STATUS
CP213x_GetSpiDelay ( CP213x_DEVICE hDevice,
BYTE channel,
BYTE* delayMode,
WORD* interByteDelay,
WORD* postAssertDelay,
WORD* preDeassertDelay );
USB_SPI_STATUS
CP213x_SetSpiDelay ( CP213x_DEVICE hDevice,
BYTE channel,
BYTE delayMode,
WORD interByteDelay,
WORD postAssertDelay,
WORD preDeassertDelay );
//not tested
USB_SPI_STATUS
CP213x_GetChipSelect ( CP213x_DEVICE hDevice,
WORD* channelCsEnable,
WORD* pinCsEnable );
//not tested
USB_SPI_STATUS
CP213x_SetChipSelect ( CP213x_DEVICE hDevice, BYTE channel, BYTE mode );
//not tested
USB_SPI_STATUS
CP213x_TransferWrite ( CP213x_DEVICE hDevice,
BYTE pWriteBuf[],
DWORD length,
BOOL releaseBusAfterTransfer,
DWORD timeoutMs,
DWORD* pBytesActuallyWritten );
//not tested
USB_SPI_STATUS
CP213x_TransferWriteRead ( CP213x_DEVICE hDevice,
BYTE pWriteBuf[],
BYTE pReadBuf[],
DWORD length,
BOOL releaseBusAfterTransfer,
DWORD timeoutMs,
DWORD* pBytesActuallyTransferred );
//not tested
USB_SPI_STATUS
CP213x_TransferReadAsync ( CP213x_DEVICE hDevice,
DWORD totalSize,
DWORD blockSize,
BOOL releaseBusAfterTransfer );
USB_SPI_STATUS
CP213x_TransferReadSync ( CP213x_DEVICE hDevice,
BYTE pReadBuf[],
DWORD length,
BOOL releaseBusAfterTransfer,
DWORD timeoutMs,
DWORD* pBytesActuallyRead );
USB_SPI_STATUS
CP213x_TransferReadRtrAsync ( CP213x_DEVICE hDevice,
DWORD totalSize,
DWORD blockSize,
BOOL releaseBusAfterTransfer );
USB_SPI_STATUS
CP213x_TransferReadRtrSync ( CP213x_DEVICE hDevice,
BYTE pReadBuf[],
DWORD totalSize,
DWORD blockSize,
BOOL releaseBusAfterTransfer,
DWORD timeoutMs,
DWORD* pBytesActuallyRead );
USB_SPI_STATUS
CP213x_GetRtrState ( CP213x_DEVICE hDevice, BYTE* isStopped );
USB_SPI_STATUS
CP213x_SetRtrStop ( CP213x_DEVICE hDevice, BYTE stopRtr );
USB_SPI_STATUS
CP213x_ReadPoll ( CP213x_DEVICE hDevice,
BYTE pReadBuf[],
DWORD maxLength,
DWORD* pBytesActuallyRead );
USB_SPI_STATUS
CP213x_ReadAbort ( CP213x_DEVICE hDevice );
USB_SPI_STATUS
CP213x_AbortInputPipe ( CP213x_DEVICE hDevice );
USB_SPI_STATUS
CP213x_FlushInputPipe ( CP213x_DEVICE hDevice );
USB_SPI_STATUS
CP213x_AbortOutputPipe ( CP213x_DEVICE hDevice );
USB_SPI_STATUS
CP213x_FlushOutputPipe ( CP213x_DEVICE hDevice );
USB_SPI_STATUS
CP213x_GetFifoFullThreshold ( CP213x_DEVICE hDevice, BYTE* pFifoFullThreshold );
USB_SPI_STATUS
CP213x_SetFifoFullThreshold ( CP213x_DEVICE hDevice, BYTE fifoFullThreshold );
/// @}
//
// CP2130 GPIO and Auxiliary-Function Pins
//
/// @name CP2130 GPIO and Auxiliary-Function Pins
/// @{
USB_SPI_STATUS
CP213x_GetGpioModeAndLevel ( CP213x_DEVICE hDevice, BYTE channel, BYTE* mode, BYTE* level );
USB_SPI_STATUS
CP213x_SetGpioModeAndLevel ( CP213x_DEVICE hDevice, BYTE channel, BYTE mode, BYTE level );
USB_SPI_STATUS
CP213x_GetGpioValues ( CP213x_DEVICE hDevice, WORD* gpioValues );
USB_SPI_STATUS
CP213x_SetGpioValues ( CP213x_DEVICE hDevice, WORD mask, WORD gpioValues );
USB_SPI_STATUS
CP213x_GetEventCounter ( CP213x_DEVICE hDevice, BYTE* mode, WORD* eventCount );
USB_SPI_STATUS
CP213x_SetEventCounter ( CP213x_DEVICE hDevice, BYTE mode, WORD eventCount );
USB_SPI_STATUS
CP213x_GetClockDivider ( CP213x_DEVICE hDevice, BYTE* clockDivider );
USB_SPI_STATUS
CP213x_SetClockDivider ( CP213x_DEVICE hDevice, BYTE clockDivider );
/// @}
#ifdef __cplusplus
}
#endif // __cplusplus
#endif // SLAB_USB_SPI_H
/////////////////////////////////////////////////////////////////////////////
// End of file
/////////////////////////////////////////////////////////////////////////////