drivers/enc/fsl_enc.h

0001 /*
0002  * Copyright (c) 2015, Freescale Semiconductor, Inc.
0003  * Copyright 2016-2021 NXP
0004  * All rights reserved.
0005  *
0006  * SPDX-License-Identifier: BSD-3-Clause
0007  */
0008
0009 #ifndef _FSL_ENC_H_
0010 #define _FSL_ENC_H_
0011
0012 #include "fsl_common.h"
0013
0014 /*!
0015  * @addtogroup enc
0016  * @{
0017  */
0018 /*******************************************************************************
0019  * Definitions
0020  ******************************************************************************/
0021 #define FSL_ENC_DRIVER_VERSION (MAKE_VERSION(2, 1, 0))
0022
0023 /*!
0024  * @brief Interrupt enable/disable mask.
0025  */
0026 enum _enc_interrupt_enable
0027 {
0028     kENC_HOMETransitionInterruptEnable  = (1U << 0U), /*!< HOME interrupt enable. */
0029     kENC_INDEXPulseInterruptEnable      = (1U << 1U), /*!< INDEX pulse interrupt enable. */
0030     kENC_WatchdogTimeoutInterruptEnable = (1U << 2U), /*!< Watchdog timeout interrupt enable. */
0031     kENC_PositionCompareInerruptEnable  = (1U << 3U), /*!< Position compare interrupt enable. */
0032 #if !(defined(FSL_FEATURE_ENC_HAS_NO_CTRL2_SAB_INT) && FSL_FEATURE_ENC_HAS_NO_CTRL2_SAB_INT)
0033     kENC_SimultBothPhaseChangeInterruptEnable =
0034         (1U << 4U), /*!< Simultaneous PHASEA and PHASEB change interrupt enable. */
0035 #endif
0036     kENC_PositionRollOverInterruptEnable  = (1U << 5U), /*!< Roll-over interrupt enable. */
0037     kENC_PositionRollUnderInterruptEnable = (1U << 6U), /*!< Roll-under interrupt enable. */
0038 };
0039
0040 /*!
0041  * @brief Status flag mask.
0042  *
0043  * These flags indicate the counter's events.
0044  */
0045 enum _enc_status_flags
0046 {
0047     kENC_HOMETransitionFlag  = (1U << 0U), /*!< HOME signal transition interrupt request. */
0048     kENC_INDEXPulseFlag      = (1U << 1U), /*!< INDEX Pulse Interrupt Request. */
0049     kENC_WatchdogTimeoutFlag = (1U << 2U), /*!< Watchdog timeout interrupt request. */
0050     kENC_PositionCompareFlag = (1U << 3U), /*!< Position compare interrupt request. */
0051 #if !(defined(FSL_FEATURE_ENC_HAS_NO_CTRL2_SAB_INT) && FSL_FEATURE_ENC_HAS_NO_CTRL2_SAB_INT)
0052     kENC_SimultBothPhaseChangeFlag = (1U << 4U), /*!< Simultaneous PHASEA and PHASEB change interrupt request. */
0053 #endif
0054     kENC_PositionRollOverFlag   = (1U << 5U), /*!< Roll-over interrupt request. */
0055     kENC_PositionRollUnderFlag  = (1U << 6U), /*!< Roll-under interrupt request. */
0056     kENC_LastCountDirectionFlag = (1U << 7U), /*!< Last count was in the up direction, or the down direction. */
0057 };
0058
0059 /*!
0060  * @brief Signal status flag mask.
0061  *
0062  * These flags indicate the counter's signal.
0063  */
0064 enum _enc_signal_status_flags
0065 {
0066     kENC_RawHOMEStatusFlag       = ENC_IMR_HOME_MASK,  /*!< Raw HOME input. */
0067     kENC_RawINDEXStatusFlag      = ENC_IMR_INDEX_MASK, /*!< Raw INDEX input. */
0068     kENC_RawPHBStatusFlag        = ENC_IMR_PHB_MASK,   /*!< Raw PHASEB input. */
0069     kENC_RawPHAEXStatusFlag      = ENC_IMR_PHA_MASK,   /*!< Raw PHASEA input. */
0070     kENC_FilteredHOMEStatusFlag  = ENC_IMR_FHOM_MASK,  /*!< The filtered version of HOME input. */
0071     kENC_FilteredINDEXStatusFlag = ENC_IMR_FIND_MASK,  /*!< The filtered version of INDEX input. */
0072     kENC_FilteredPHBStatusFlag   = ENC_IMR_FPHB_MASK,  /*!< The filtered version of PHASEB input. */
0073     kENC_FilteredPHAStatusFlag   = ENC_IMR_FPHA_MASK,  /*!< The filtered version of PHASEA input. */
0074 };
0075
0076 /*!
0077  * @brief Define HOME signal's trigger mode.
0078  *
0079  * The ENC would count the trigger from HOME signal line.
0080  */
0081 typedef enum _enc_home_trigger_mode
0082 {
0083     kENC_HOMETriggerDisabled = 0U, /*!< HOME signal's trigger is disabled. */
0084     kENC_HOMETriggerOnRisingEdge,  /*!< Use positive going edge-to-trigger initialization of position counters. */
0085     kENC_HOMETriggerOnFallingEdge, /*!< Use negative going edge-to-trigger initialization of position counters. */
0086 } enc_home_trigger_mode_t;
0087
0088 /*!
0089  * @brief Define INDEX signal's trigger mode.
0090  *
0091  * The ENC would count the trigger from INDEX signal line.
0092  */
0093 typedef enum _enc_index_trigger_mode
0094 {
0095     kENC_INDEXTriggerDisabled = 0U, /*!< INDEX signal's trigger is disabled. */
0096     kENC_INDEXTriggerOnRisingEdge,  /*!< Use positive going edge-to-trigger initialization of position counters. */
0097     kENC_INDEXTriggerOnFallingEdge, /*!< Use negative going edge-to-trigger initialization of position counters. */
0098 } enc_index_trigger_mode_t;
0099
0100 /*!
0101  * @brief Define type for decoder work mode.
0102  *
0103  * The normal work mode uses the standard quadrature decoder with PHASEA and PHASEB. When in signal phase count mode,
0104  * a positive transition of the PHASEA input generates a count signal while the PHASEB input and the reverse direction
0105  * control the counter direction. If the reverse direction is not enabled, PHASEB = 0 means counting up and PHASEB = 1
0106  * means counting down. Otherwise, the direction is reversed.
0107  */
0108 typedef enum _enc_decoder_work_mode
0109 {
0110     kENC_DecoderWorkAsNormalMode = 0U,      /*!< Use standard quadrature decoder with PHASEA and PHASEB. */
0111     kENC_DecoderWorkAsSignalPhaseCountMode, /*!< PHASEA input generates a count signal while PHASEB input control the
0112                                                direction. */
0113 } enc_decoder_work_mode_t;
0114
0115 /*!
0116  * @brief Define type for the condition of POSMATCH pulses.
0117  */
0118 typedef enum _enc_position_match_mode
0119 {
0120     kENC_POSMATCHOnPositionCounterEqualToComapreValue = 0U, /*!< POSMATCH pulses when a match occurs between the
0121                                                                position counters (POS) and the compare value (COMP). */
0122     kENC_POSMATCHOnReadingAnyPositionCounter, /*!< POSMATCH pulses when any position counter register is read. */
0123 } enc_position_match_mode_t;
0124
0125 /*!
0126  * @brief Define type for determining how the revolution counter (REV) is incremented/decremented.
0127  */
0128 typedef enum _enc_revolution_count_condition
0129 {
0130     kENC_RevolutionCountOnINDEXPulse = 0U, /*!< Use INDEX pulse to increment/decrement revolution counter. */
0131     kENC_RevolutionCountOnRollOverModulus, /*!< Use modulus counting roll-over/under to increment/decrement revolution
0132                                               counter. */
0133 } enc_revolution_count_condition_t;
0134
0135 /*!
0136  * @brief Define type for direction of self test generated signal.
0137  */
0138 typedef enum _enc_self_test_direction
0139 {
0140     kENC_SelfTestDirectionPositive = 0U, /*!< Self test generates the signal in positive direction. */
0141     kENC_SelfTestDirectionNegative,      /*!< Self test generates the signal in negative direction. */
0142 } enc_self_test_direction_t;
0143
0144 #if (defined(FSL_FEATURE_ENC_HAS_CTRL3) && FSL_FEATURE_ENC_HAS_CTRL3)
0145 /*!
0146  * @brief Define prescaler value for clock in CTRL3.
0147  *
0148  * The clock is prescaled by a value of 2^PRSC which means that the prescaler logic
0149  * can divide the clock by a minimum of 1 and a maximum of 32,768.
0150  */
0151 typedef enum _enc_prescaler
0152 {
0153     kENC_ClockDiv1     = 0,
0154     kENC_ClockDiv2     = 1,
0155     kENC_ClockDiv4     = 2,
0156     kENC_ClockDiv8     = 3,
0157     kENC_ClockDiv16    = 4,
0158     kENC_ClockDiv32    = 5,
0159     kENC_ClockDiv64    = 6,
0160     kENC_ClockDiv128   = 7,
0161     kENC_ClockDiv256   = 8,
0162     kENC_ClockDiv512   = 9,
0163     kENC_ClockDiv1024  = 10,
0164     kENC_ClockDiv2048  = 11,
0165     kENC_ClockDiv4096  = 12,
0166     kENC_ClockDiv8192  = 13,
0167     kENC_ClockDiv16384 = 14,
0168     kENC_ClockDiv32768 = 15,
0169 } enc_prescaler_t;
0170 #endif
0171
0172 /*!
0173  * @brief Define user configuration structure for ENC module.
0174  */
0175 typedef struct _enc_config
0176 {
0177     /* Basic counter. */
0178     bool enableReverseDirection;             /*!< Enable reverse direction counting. */
0179     enc_decoder_work_mode_t decoderWorkMode; /*!< Enable signal phase count mode. */
0180
0181     /* Signal detection. */
0182     enc_home_trigger_mode_t HOMETriggerMode;   /*!< Enable HOME to initialize position counters. */
0183     enc_index_trigger_mode_t INDEXTriggerMode; /*!< Enable INDEX to initialize position counters. */
0184     bool enableTRIGGERClearPositionCounter;    /*!< Clear POSD, REV, UPOS and LPOS on rising edge of TRIGGER, or not. */
0185     bool enableTRIGGERClearHoldPositionCounter; /*!< Enable update of hold registers on rising edge of TRIGGER, or not.
0186                                                  */
0187
0188     /* Watchdog. */
0189     bool enableWatchdog;           /*!< Enable the watchdog to detect if the target is moving or not. */
0190     uint16_t watchdogTimeoutValue; /*!< Watchdog timeout count value. It stores the timeout count for the quadrature
0191                                         decoder module watchdog timer. This field is only available when
0192                                         "enableWatchdog" = true. The available value is a 16-bit unsigned number.*/
0193
0194     /* Filter for PHASEA, PHASEB, INDEX and HOME. */
0195     uint16_t filterCount; /*!< Input Filter Sample Count. This value should be chosen to reduce the probability of
0196                                noisy samples causing an incorrect transition to be recognized. The value represent the
0197                                number of consecutive samples that must agree prior to the input filter accepting an
0198                                input transition. A value of 0x0 represents 3 samples. A value of 0x7 represents 10
0199                                samples. The Available range is 0 - 7.*/
0200     uint16_t filterSamplePeriod; /*!< Input Filter Sample Period. This value should be set such that the sampling period
0201                                       is larger than the period of the expected noise. This value represents the
0202                                       sampling period (in IPBus clock cycles) of the decoder input signals.
0203                                       The available range is 0 - 255. */
0204
0205     /* Position compare. */
0206     enc_position_match_mode_t positionMatchMode; /*!< The condition of POSMATCH pulses. */
0207     uint32_t positionCompareValue;               /*!< Position compare value. The available value is a 32-bit number.*/
0208
0209     /* Modulus counting. */
0210     enc_revolution_count_condition_t revolutionCountCondition; /*!< Revolution Counter Modulus Enable. */
0211     bool enableModuloCountMode;                                /*!< Enable Modulo Counting. */
0212     uint32_t positionModulusValue; /*!< Position modulus value. This value would be available only when
0213                                         "enableModuloCountMode" = true. The available value is a 32-bit number. */
0214     uint32_t positionInitialValue; /*!< Position initial value. The available value is a 32-bit number. */
0215
0216 #if (defined(FSL_FEATURE_ENC_HAS_CTRL3) && FSL_FEATURE_ENC_HAS_CTRL3)
0217     /* Prescaler. */
0218     bool enablePeriodMeasurementFunction; /*!< Enable period measurement function. */
0219     enc_prescaler_t prescalerValue;       /*!< The value of prescaler. */
0220 #endif
0221 } enc_config_t;
0222
0223 /*!
0224  * @brief Define configuration structure for self test module.
0225  *
0226  * The self test module provides a quadrature test signal to the inputs of the quadrature decoder module.
0227  * This is a factory test feature. It is also useful to customers' software development and testing.
0228  */
0229 typedef struct _enc_self_test_config
0230 {
0231     enc_self_test_direction_t signalDirection; /*!< Direction of self test generated signal. */
0232     uint16_t signalCount;  /*!< Hold the number of quadrature advances to generate. The available range is 0 - 255.*/
0233     uint16_t signalPeriod; /*!< Hold the period of quadrature phase in IPBus clock cycles.
0234                                 The available range is 0 - 31. */
0235 } enc_self_test_config_t;
0236
0237 #if defined(__cplusplus)
0238 extern "C" {
0239 #endif
0240
0241 /*******************************************************************************
0242  * API
0243  ******************************************************************************/
0244
0245 /*!
0246  * @name Initialization and De-initialization
0247  * @{
0248  */
0249
0250 /*!
0251  * @brief Initialization for the ENC module.
0252  *
0253  * This function is to make the initialization for the ENC module. It should be called firstly before any operation to
0254  * the ENC with the operations like:
0255  *  - Enable the clock for ENC module.
0256  *  - Configure the ENC's working attributes.
0257  *
0258  * @param base   ENC peripheral base address.
0259  * @param config Pointer to configuration structure. See to "enc_config_t".
0260  */
0261 void ENC_Init(ENC_Type *base, const enc_config_t *config);
0262
0263 /*!
0264  * @brief De-initialization for the ENC module.
0265  *
0266  * This function is to make the de-initialization for the ENC module. It could be called when ENC is no longer used with
0267  * the operations like:
0268  *  - Disable the clock for ENC module.
0269  *
0270  * @param base ENC peripheral base address.
0271  */
0272 void ENC_Deinit(ENC_Type *base);
0273
0274 /*!
0275  * @brief Get an available pre-defined settings for ENC's configuration.
0276  *
0277  * This function initializes the ENC configuration structure with an available settings, the default value are:
0278  * @code
0279  *   config->enableReverseDirection                = false;
0280  *   config->decoderWorkMode                       = kENC_DecoderWorkAsNormalMode;
0281  *   config->HOMETriggerMode                       = kENC_HOMETriggerDisabled;
0282  *   config->INDEXTriggerMode                      = kENC_INDEXTriggerDisabled;
0283  *   config->enableTRIGGERClearPositionCounter     = false;
0284  *   config->enableTRIGGERClearHoldPositionCounter = false;
0285  *   config->enableWatchdog                        = false;
0286  *   config->watchdogTimeoutValue                  = 0U;
0287  *   config->filterCount                           = 0U;
0288  *   config->filterSamplePeriod                    = 0U;
0289  *   config->positionMatchMode                     = kENC_POSMATCHOnPositionCounterEqualToComapreValue;
0290  *   config->positionCompareValue                  = 0xFFFFFFFFU;
0291  *   config->revolutionCountCondition              = kENC_RevolutionCountOnINDEXPulse;
0292  *   config->enableModuloCountMode                 = false;
0293  *   config->positionModulusValue                  = 0U;
0294  *   config->positionInitialValue                  = 0U;
0295  *   config->prescalerValue                        = kENC_ClockDiv1;
0296  *   config->enablePeriodMeasurementFunction       = true;
0297  * @endcode
0298  * @param config Pointer to a variable of configuration structure. See to "enc_config_t".
0299  */
0300 void ENC_GetDefaultConfig(enc_config_t *config);
0301
0302 /*!
0303  * @brief Load the initial position value to position counter.
0304  *
0305  * This function is to transfer the initial position value (UINIT and LINIT) contents to position counter (UPOS and
0306  * LPOS), so that to provide the consistent operation the position counter registers.
0307  *
0308  * @param base ENC peripheral base address.
0309  */
0310 void ENC_DoSoftwareLoadInitialPositionValue(ENC_Type *base);
0311
0312 /*!
0313  * @brief Enable and configure the self test function.
0314  *
0315  * This function is to enable and configuration the self test function. It controls and sets the frequency of a
0316  * quadrature signal generator. It provides a quadrature test signal to the inputs of the quadrature decoder module.
0317  * It is a factory test feature; however, it may be useful to customers' software development and testing.
0318  *
0319  * @param base   ENC peripheral base address.
0320  * @param config Pointer to configuration structure. See to "enc_self_test_config_t". Pass "NULL" to disable.
0321  */
0322 void ENC_SetSelfTestConfig(ENC_Type *base, const enc_self_test_config_t *config);
0323
0324 /*!
0325  * @brief Enable watchdog for ENC module.
0326  *
0327  * @param base ENC peripheral base address
0328  * @param enable Enables or disables the watchdog
0329  */
0330 void ENC_EnableWatchdog(ENC_Type *base, bool enable);
0331
0332 /*!
0333  * @brief Set initial position value for ENC module.
0334  *
0335  * @param base ENC peripheral base address
0336  * @param value Positive initial value
0337  */
0338 void ENC_SetInitialPositionValue(ENC_Type *base, uint32_t value);
0339
0340 /* @} */
0341
0342 /*!
0343  * @name Status
0344  * @{
0345  */
0346 /*!
0347  * @brief  Get the status flags.
0348  *
0349  * @param  base ENC peripheral base address.
0350  *
0351  * @return      Mask value of status flags. For available mask, see to "_enc_status_flags".
0352  */
0353 uint32_t ENC_GetStatusFlags(ENC_Type *base);
0354
0355 /*!
0356  * @brief Clear the status flags.
0357  *
0358  * @param base ENC peripheral base address.
0359  * @param mask Mask value of status flags to be cleared. For available mask, see to "_enc_status_flags".
0360  */
0361 void ENC_ClearStatusFlags(ENC_Type *base, uint32_t mask);
0362
0363 /*!
0364  * @brief  Get the signals' real-time status.
0365  *
0366  * @param  base ENC peripheral base address.
0367  *
0368  * @return      Mask value of signals' real-time status. For available mask, see to "_enc_signal_status_flags"
0369  */
0370 static inline uint16_t ENC_GetSignalStatusFlags(ENC_Type *base)
0371 {
0372     return base->IMR;
0373 }
0374 /* @} */
0375
0376 /*!
0377  * @name Interrupts
0378  * @{
0379  */
0380
0381 /*!
0382  * @brief Enable the interrupts.
0383  *
0384  * @param base ENC peripheral base address.
0385  * @param mask Mask value of interrupts to be enabled. For available mask, see to "_enc_interrupt_enable".
0386  */
0387 void ENC_EnableInterrupts(ENC_Type *base, uint32_t mask);
0388
0389 /*!
0390  * @brief Disable the interrupts.
0391  *
0392  * @param base ENC peripheral base address.
0393  * @param mask Mask value of interrupts to be disabled. For available mask, see to "_enc_interrupt_enable".
0394  */
0395 void ENC_DisableInterrupts(ENC_Type *base, uint32_t mask);
0396
0397 /*!
0398  * @brief  Get the enabled interrupts' flags.
0399  *
0400  * @param  base ENC peripheral base address.
0401  *
0402  * @return      Mask value of enabled interrupts.
0403  */
0404 uint32_t ENC_GetEnabledInterrupts(ENC_Type *base);
0405
0406 /* @} */
0407
0408 /*!
0409  * @name Value Operation
0410  * @{
0411  */
0412
0413 /*!
0414  * @brief  Get the current position counter's value.
0415  *
0416  * @param  base ENC peripheral base address.
0417  *
0418  * @return     Current position counter's value.
0419  */
0420 uint32_t ENC_GetPositionValue(ENC_Type *base);
0421
0422 /*!
0423  * @brief  Get the hold position counter's value.
0424  *
0425  * When any of the counter registers is read, the contents of each counter register is written to the corresponding hold
0426  * register. Taking a snapshot of the counters' values provides a consistent view of a system position and a velocity to
0427  * be attained.
0428  *
0429  * @param  base ENC peripheral base address.
0430  *
0431  * @return      Hold position counter's value.
0432  */
0433 uint32_t ENC_GetHoldPositionValue(ENC_Type *base);
0434
0435 /*!
0436  * @brief  Get the position difference counter's value.
0437  *
0438  * @param  base ENC peripheral base address.
0439  *
0440  * @return     The position difference counter's value.
0441  */
0442 static inline uint16_t ENC_GetPositionDifferenceValue(ENC_Type *base)
0443 {
0444     return base->POSD;
0445 }
0446
0447 /*!
0448  * @brief  Get the hold position difference counter's value.
0449  *
0450  * When any of the counter registers is read, the contents of each counter register is written to the corresponding hold
0451  * register. Taking a snapshot of the counters' values provides a consistent view of a system position and a velocity to
0452  * be attained.
0453  *
0454  * @param  base ENC peripheral base address.
0455  *
0456  * @return      Hold position difference counter's value.
0457  */
0458 static inline uint16_t ENC_GetHoldPositionDifferenceValue(ENC_Type *base)
0459 {
0460     return base->POSDH;
0461 }
0462
0463 /*!
0464  * @brief  Get the position revolution counter's value.
0465  *
0466  * @param  base ENC peripheral base address.
0467  *
0468  * @return     The position revolution counter's value.
0469  */
0470 static inline uint16_t ENC_GetRevolutionValue(ENC_Type *base)
0471 {
0472     return base->REV;
0473 }
0474
0475 /*!
0476  * @brief  Get the hold position revolution counter's value.
0477  *
0478  * When any of the counter registers is read, the contents of each counter register is written to the corresponding hold
0479  * register. Taking a snapshot of the counters' values provides a consistent view of a system position and a velocity to
0480  * be attained.
0481  *
0482  * @param  base ENC peripheral base address.
0483  *
0484  * @return      Hold position revolution counter's value.
0485  */
0486 static inline uint16_t ENC_GetHoldRevolutionValue(ENC_Type *base)
0487 {
0488     return base->REVH;
0489 }
0490
0491 #if (defined(FSL_FEATURE_ENC_HAS_LASTEDGE) && FSL_FEATURE_ENC_HAS_LASTEDGE)
0492 /*!
0493  * @brief  Get the last edge time value.
0494  *
0495  * @param  base ENC peripheral base address.
0496  *
0497  * @return     The last edge time hold value.
0498  */
0499 static inline uint16_t ENC_GetLastEdgeTimeValue(ENC_Type *base)
0500 {
0501     return base->LASTEDGE;
0502 }
0503
0504 /*!
0505  * @brief  Get the last edge time hold value.
0506  *
0507  * @param  base ENC peripheral base address.
0508  *
0509  * @return     The last edge time hold value.
0510  */
0511 static inline uint16_t ENC_GetHoldLastEdgeTimeValue(ENC_Type *base)
0512 {
0513     return base->LASTEDGEH;
0514 }
0515 #endif
0516
0517 #if (defined(FSL_FEATURE_ENC_HAS_POSDPER) && FSL_FEATURE_ENC_HAS_POSDPER)
0518 /*!
0519  * @brief  Get the position difference period value.
0520  *
0521  * @param  base ENC peripheral base address.
0522  *
0523  * @return     The position difference period hold value.
0524  */
0525 static inline uint16_t ENC_GetPositionDifferencePeriodValue(ENC_Type *base)
0526 {
0527     return base->POSDPER;
0528 }
0529
0530 /*!
0531  * @brief  Get the position difference period buffer value.
0532  *
0533  * @param  base ENC peripheral base address.
0534  *
0535  * @return     The position difference period hold value.
0536  */
0537 static inline uint16_t ENC_GetPositionDifferencePeriodBufferValue(ENC_Type *base)
0538 {
0539     return base->POSDPERBFR;
0540 }
0541
0542 /*!
0543  * @brief  Get the position difference period hold value.
0544  *
0545  * @param  base ENC peripheral base address.
0546  *
0547  * @return     The position difference period hold value.
0548  */
0549 static inline uint16_t ENC_GetHoldPositionDifferencePeriodValue(ENC_Type *base)
0550 {
0551     return base->POSDPERH;
0552 }
0553 #endif
0554 /* @} */
0555
0556 #if defined(__cplusplus)
0557 }
0558 #endif
0559
0560 /* @} */
0561
0562 #endif /* _FSL_ENC_H_ */