ADCBufMSP432E4.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018-2019, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!****************************************************************************
 *  @file       ADCBufMSP432E4.h
 *
 *  @brief      ADCBuf driver implementation for a MSP432E4 analog-to-digital
 *              converter
 *
 *  # Overview #
 *  This driver takes \p n samples using the ADC and stores the results in a
 *  buffer. This implementation supports both #ADCBuf_RECURRENCE_MODE_ONE_SHOT
 *  and #ADCBuf_RECURRENCE_MODE_CONTINUOUS. The ADCBuf_MSP432E4 driver
 *  supports use of both ADC peripherals and their sample sequencers.
 *
 *  # General Behavior #
 *  The MSP342E4 microcontroller has two ADC modules and each ADC module has
 *  four sample sequencers, SS0-SS3, that control and capture sample data.
 *  Sequencer priority can be initialized in #ADCBufMSP432E4_HWAttrsV1 by
 *  creating an array that holds the corresponding #ADCBufMSP432E4_SequencePriorities.
 *
 *  To initialize the sequencers, in the board file "MSP_EXP432E401Y.c"/board.h
 *  - Specify the sequencer to use by setting ".adcSequence" in the array
 *    #ADCBufMSP432E4_Channels for each channel/sequencer combination needed.
 *  - Change the sequencer priority for each sequencer to be used in the array
 *    #ADCBufMSP432E4_SequencePriorities.
 *
 *  @anchor ti_drivers_adcbuf_ADCBufMSP432E4_SequencePriorities
 *  ## Sequencer Priorities - #ADCBufMSP432E4_SequencePriorities
 *
 *  @code
 *  static ADCBufMSP432E4_SequencePriorities seqPriorities[ADCBufMSP432E4_SEQUENCER_COUNT] = {
 *      ADCBufMSP432E4_Priority_0,
 *      ADCBufMSP432E4_Seq_Disable,
 *      ADCBufMSP432E4_Seq_Disable,
 *      ADCBufMSP432E4_Seq_Disable
 *  };
 *  @endcode
 *
 *  The MSP432E4 ADC sample sequencers can be triggered by several
 *  different types of software and hardware events. The driver currently
 *  only supports  #ADCBufMSP432E4_SOFTWARE_AUTOMATIC_TRIGGER and
 *  #ADCBufMSP432E4_TIMER_TRIGGER trigger sources. Multiple sequencers
 *  can share the same trigger source. An unique #ADCBufMSP432E4_TriggerSource
 *  array can be defined for each ADCBuf instance. That is, each
 *  #ADCBufMSP432E4_HWAttrsV1.adcTriggerSource can point to a unique
 *  #ADCBufMSP432E4_TriggerSource array.
 *
 *  The application is responsible for defining a #ADCBufMSP432E4_Channels
 *  array. Each index corresponds to a ADC channel configuration. A unique
 *  #ADCBufMSP432E4_Channels array can be defined for each ADCBuf instance.
 *  That is, each #ADCBufMSP432E4_HWAttrsV1.channelSetting can point to a unique
 *  #ADCBufMSP432E4_Channels array.
 *
 *  The #ADCBufMSP432E4_Channels array lets the user select the #ADCBufMSP432E4_Sequencer,
 *  #ADCBufMSP432E4_DifferentialMode, the differential pins if needed, MSP432E4
 *  specific ADC modes like #ADCBufMSP432E4_TEMPERATURE_MODE that let the user
 *  configure the internal temperature mode
 *
 *  @anchor ti_drivers_adcbuf_ADCBufMSP432E4_ADCBufMSP432E4_Channels
 *  ## Channel section - #ADCBufMSP432E4_Channels
 *  @code
 *  ADCBufMSP432E4_Channels adcBuf0MSP432E4Channels[ADCBUF0CHANNELCOUNT] = {
 *  {
 *      .adcPin = ADCBufMSP432E4_PE_3_A0,
 *      .adcSequence = ADCBufMSP432E4_Seq_0,
 *      .adcInputMode = ADCBufMSP432E4_SINGLE_ENDED,
 *      .adcDifferentialPin = ADCBufMSP432E4_PIN_NONE,
 *      .adcInternalSource = ADCBufMSP432E4_INTERNAL_SOURCE_MODE_OFF,
 *      .refVoltage = 3300000
 *  },
 *  {
 *      .adcPin = ADCBufMSP432E4_PE_2_A1,
 *      .adcSequence = ADCBufMSP432E4_Seq_1,
 *      .adcInputMode = ADCBufMSP432E4_SINGLE_ENDED,
 *      .adcDifferentialPin = ADCBufMSP432E4_PIN_NONE,
 *      .adcInternalSource = ADCBufMSP432E4_INTERNAL_SOURCE_MODE_OFF,
 *      .refVoltage = 3300000
 *  },
 *  @endcode
 *
 *  Please refer to #ADCBufMSP432E4_HWAttrsV1 structure for other hardware
 *  dependent configuration settings Some examples include voltage reference
 *  source selection and optional DMA usage.
 *
 *  This driver supports various modes of operation and sampling.
 *  #ADCBufMSP432E4_HWAttrsV1.useDMA can be set to \p 1 to improve performance.
 *  Additionally, samples can be performed using #ADCBufMSP432E4_DIFFERENTIAL
 *  or #ADCBufMSP432E4_TEMPERATURE_MODE modes.
 *

 *
 *  In the application,
 *  - Call ADCBuf_init() once per ADC module.
 *  - Each ADC module requires a separate ADCBuf_open() call.
 *  - Create and initialize "ADCBuf_Conversion" object for each sequencer.
 *  - To make each sequencer sample multiple channels, create the conversion
 *    object as an array, example ADCBuf_Conversion continuousConversion[2]
 *    and initialize each channel within the conversion object.
 *
 *  Refer to @ref ADCBuf.h for a complete description of APIs & example use.
 *
 ******************************************************************************
 */

#ifndef ti_drivers_adcbuf_ADCBufMSP432E4__include
#define ti_drivers_adcbuf_ADCBufMSP432E4__include

#include <stdint.h>
#include <stdbool.h>

#include <ti/drivers/ADCBuf.h>
#include <ti/drivers/dpl/HwiP.h>
#include <ti/drivers/dpl/SemaphoreP.h>
#include <ti/drivers/dma/UDMAMSP432E4.h>
#include <ti/devices/msp432e4/driverlib/adc.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 *  ADCBuf port/pin defines for pin configuration.  Ports B, D, E, and K are
 *  configurable through the port mapping controller.  None of the port
 *  mappings support ADC.
 *  Channel specifies the ADC channel and ranges from 0 to 23.
 *  pin range: 0 - 7, port range: 0 - 15
 *
 *      31-24        23-16      15-8     7-0
 *  -------------------------------------------
 *  |  RESERVED  |  CHANNEL  |  PORT  |  PIN  |
 *  -------------------------------------------
 *
 *  channel = (((config) >> 16) & 0x10F)
 *  port    = (((config << 4) & 0x000FF000) | 0x40000000)
 *  pin     = ((config) & 0xFF)
 *
 */

#define ADCBufMSP432E4_PB_4_A10 ((10 << 16) | 0x5910)

#define ADCBufMSP432E4_PB_5_A11 ((11 << 16) | 0x5920)

#define ADCBufMSP432E4_PD_0_A15 ((15 << 16) | 0x5B01)

#define ADCBufMSP432E4_PD_1_A14 ((14 << 16) | 0x5B02)

#define ADCBufMSP432E4_PD_2_A13 ((13 << 16) | 0x5B04)

#define ADCBufMSP432E4_PD_3_A12 ((12 << 16) | 0x5B08)

#define ADCBufMSP432E4_PD_4_A7  ((7 << 16) | 0x5B10)

#define ADCBufMSP432E4_PD_5_A6  ((6 << 16) | 0x5B20)

#define ADCBufMSP432E4_PD_6_A5  ((5 << 16) | 0x5B40)

#define ADCBufMSP432E4_PD_7_A4  ((4 << 16) | 0x5B80)

#define ADCBufMSP432E4_PE_0_A3  ((3 << 16) | 0x5C01)

#define ADCBufMSP432E4_PE_1_A2  ((2 << 16) | 0x5C02)

#define ADCBufMSP432E4_PE_2_A1  ((1 << 16) | 0x5C04)

#define ADCBufMSP432E4_PE_3_A0  ((0 << 16) | 0x5C08)

#define ADCBufMSP432E4_PE_4_A9  ((9 << 16) | 0x5C10)

#define ADCBufMSP432E4_PE_5_A8  ((8 << 16) | 0x5C20)

#define ADCBufMSP432E4_PE_6_A20  (((20-16) << 16) | 0x5C40 | 0x01000000)

#define ADCBufMSP432E4_PE_7_A21  (((21-16) << 16) | 0x5C80 | 0x01000000)

#define ADCBufMSP432E4_PK_0_A16 (((16-16) << 16) | 0x6101 | 0x01000000)

#define ADCBufMSP432E4_PK_1_A17 (((17-16) << 16) | 0x6102 | 0x01000000)

#define ADCBufMSP432E4_PK_2_A18 (((18-16) << 16) | 0x6104 | 0x01000000)

#define ADCBufMSP432E4_PK_3_A19 (((19-16) << 16) | 0x6108 | 0x01000000)

#define ADCBufMSP432E4_PP_6_A23  (((23-16) << 16) | 0x6540 | 0x01000000)

#define ADCBufMSP432E4_PP_7_A22  (((22-16) << 16) | 0x6580 | 0x01000000)

#define ADCBufMSP432E4_PIN_NONE  0

#define MSP432E4_NUM_ADC_CHANNELS (24)

#define ADCBufMSP432E4_SEQUENCER_COUNT 4

/* ADC function table pointer */
extern const ADCBuf_FxnTable ADCBufMSP432E4_fxnTable;

typedef enum {
    ADCBufMSP432E4_Priority_0 = 0,

    ADCBufMSP432E4_Priority_1 = 1,

    ADCBufMSP432E4_Priority_2 = 2,

    ADCBufMSP432E4_Priority_3 = 3,

    ADCBufMSP432E4_Seq_Disable = 4
} ADCBufMSP432E4_SequencePriorities;

typedef enum {
    ADCBufMSP432E4_Seq_0 = 0,

    ADCBufMSP432E4_Seq_1 = 1,

    ADCBufMSP432E4_Seq_2 = 2,

    ADCBufMSP432E4_Seq_3 = 3
} ADCBufMSP432E4_Sequencer;

typedef enum {
    ADCBufMSP432E4_INTERNAL_SOURCE_MODE_OFF = 0,

    ADCBufMSP432E4_TEMPERATURE_MODE = ADC_CTL_TS,
} ADCBufMSP432E4_InternalSourceMode;

typedef enum {
    ADCBufMSP432E4_SINGLE_ENDED = 0,

    ADCBufMSP432E4_DIFFERENTIAL = ADC_CTL_D
} ADCBufMSP432E4_DifferentialMode;

typedef enum {
    ADCBufMSP432E4_SOFTWARE_AUTOMATIC_TRIGGER = ADC_TRIGGER_ALWAYS,

    ADCBufMSP432E4_TIMER_TRIGGER = ADC_TRIGGER_TIMER,
}ADCBufMSP432E4_TriggerSource;

typedef enum {
    ADCBufMSP432E4_Phase_Delay_0 = ADC_PHASE_0,

    ADCBufMSP432E4_Phase_Delay_22_5 = ADC_PHASE_22_5,

    ADCBufMSP432E4_Phase_Delay_45 = ADC_PHASE_45,

    ADCBufMSP432E4_Phase_Delay_67_5 = ADC_PHASE_67_5,

    ADCBufMSP432E4_Phase_Delay_90 = ADC_PHASE_90,

    ADCBufMSP432E4_Phase_Delay_112_5 = ADC_PHASE_112_5,

    ADCBufMSP432E4_Phase_Delay_135 = ADC_PHASE_135,

    ADCBufMSP432E4_Phase_Delay_157_5 = ADC_PHASE_157_5,

    ADCBufMSP432E4_Phase_Delay_180 = ADC_PHASE_180,

    ADCBufMSP432E4_Phase_Delay_202_5 = ADC_PHASE_202_5,

    ADCBufMSP432E4_Phase_Delay_225 = ADC_PHASE_225,

    ADCBufMSP432E4_Phase_Delay_247_5 = ADC_PHASE_247_5,

    ADCBufMSP432E4_Phase_Delay_270 = ADC_PHASE_270,

    ADCBufMSP432E4_Phase_Delay_292_5 = ADC_PHASE_292_5,

    ADCBufMSP432E4_Phase_Delay_315 = ADC_PHASE_315,

    ADCBufMSP432E4_Phase_Delay_337_5 = ADC_PHASE_337_5,
} ADCBufMSP432E4_Phase;

typedef enum {
    ADCBufMSP432E4_SamplingDuration_PULSE_WIDTH_4 = ADC_CTL_SHOLD_4,

    ADCBufMSP432E4_SamplingDuration_PULSE_WIDTH_8 = ADC_CTL_SHOLD_8,

    ADCBufMSP432E4_SamplingDuration_PULSE_WIDTH_16 = ADC_CTL_SHOLD_16,

    ADCBufMSP432E4_SamplingDuration_PULSE_WIDTH_32 = ADC_CTL_SHOLD_32,

    ADCBufMSP432E4_SamplingDuration_PULSE_WIDTH_64 = ADC_CTL_SHOLD_64,

    ADCBufMSP432E4_SamplingDuration_PULSE_WIDTH_128 = ADC_CTL_SHOLD_128,

    ADCBufMSP432E4_SamplingDuration_PULSE_WIDTH_256 = ADC_CTL_SHOLD_256
} ADCBufMSP432E4_SamplingDuration;

typedef enum {
    ADCBufMSP432E4_VREF_INTERNAL = ADC_REF_INT,

    ADCBufMSP432E4_VREF_EXTERNAL_3V = ADC_REF_EXT_3V
} ADCBufMSP432E4_ReferenceSource;

typedef struct {
    ADCBufMSP432E4_SamplingDuration samplingDuration;
} ADCBufMSP432E4_ParamsExtension;

typedef struct {
    uint32_t refVoltage;

    uint32_t adcPin;

    ADCBufMSP432E4_Sequencer adcSequence;

    ADCBufMSP432E4_DifferentialMode adcInputMode;

    ADCBufMSP432E4_InternalSourceMode adcInternalSource;

    uint32_t adcDifferentialPin;
} ADCBufMSP432E4_Channels;

typedef struct {
    uint32_t intPriority;

    uint32_t adcBase;

    uint32_t adcTimerSource;

    ADCBufMSP432E4_Channels *channelSetting;

    ADCBufMSP432E4_TriggerSource *adcTriggerSource;

    ADCBufMSP432E4_Phase modulePhase;

    ADCBufMSP432E4_ReferenceSource refSource;

    ADCBufMSP432E4_SequencePriorities *sequencePriority;

    uint8_t useDMA;
} ADCBufMSP432E4_HWAttrsV1;

/*
 *  @brief  ADCBufMSP432E4 Object
 *
 *  The application must not access any member variables of this structure!
 */
typedef struct {
    /* Grants exclusive access to ADC */
    SemaphoreP_Handle   mutex;
    /* Notify finished ADC convert */
    SemaphoreP_Handle   convertComplete;

    /* Hardware interrupt handles, one per sequencer */
    HwiP_Handle         sequencerHwiHandles[4];

    /* PingPong flag indicates which sample buffer is active in the conversion */
    uint_fast8_t        pingpongFlag[4];
    /* Count of sampling channels */
    uint_fast8_t        channelCount[4];
    ADCBuf_Conversion   *conversions[4];

    /* Callback function pointer */
    ADCBuf_Callback     callBackFxn;

    uint16_t            *sampleBuffer[4];
    /* Internal dec. conversion buffer counter */
    uint_fast16_t        sampleIndex[4];
    /* Total sampling count per channel */
    uint_fast16_t        sampleCount[4];

    /* ADC sampling duration */
    ADCBufMSP432E4_SamplingDuration samplingDuration;
    /* Timeout for read semaphore in ADCBuf_RETURN_MODE_BLOCKING */
    uint32_t                        semaphoreTimeout;
    /* Frequency in Hz at which the ADC is triggered */
    uint32_t                        samplingFrequency;
    /* Should we convert continuously or one-shot */
    ADCBuf_Recurrence_Mode          recurrenceMode;
    /* Mode for all conversions */
    ADCBuf_Return_Mode              returnMode;
    UDMAMSP432E4_Handle dmaHandle;
    /* To determine if the ADC is open */
    bool                isOpen;
} ADCBufMSP432E4_Object;

#ifdef __cplusplus
}
#endif

#endif /* ti_drivers_adcbuf_ADCBufMSP432E4__include */