/**
* @file
*
* @ingroup arm_beagle
*
* @brief eQEP (enhanced Quadrature Encoder Pulse) support API.
*/
/*
* SPDX-License-Identifier: BSD-2-Clause
*
* Copyright (c) 2020, 2021 James Fitzsimons <james.fitzsimons@gmail.com>
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* 2. 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.
*
* 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.
*/
/**
*
* For details of the Enhanced Quadrature Encoder Pulse (eQEP) Module refer to
* page 2511 of the TI Technical Reference Manual
* (https://www.ti.com/lit/ug/spruh73q/spruh73q.pdf)
*
* This driver supports using the QEP modules in Quadrature-clock Mode.
* Direction-count Mode is not currently supported. Similarly the QEPI: Index
* or Zero Marker and QEPS: Strobe Input pins are not currently supported.
*
* The mode can be any one of:
* - Quadrature-count mode - For encoders that generate pulses 90 degrees
* out of phase for determining direction and speed.
* - Direction-count mode - for position encoders that provide direction and
* clock outputs, instead of quadrature outputs.
* - UP-count mode - The counter direction signal is hard-wired for up count
* and the position counter is used to measure the frequency of the QEPA
* input.
* - DOWN-count mode - The counter direction signal is hard-wired for a down
* count and the position counter is used to measure the frequency of the
* QEPA input.
*
* When the eQEP module is configured in quadrature mode, the module
* can either provide an absolute position, or a relative position. Absolute
* simply increments or decrements depending on the direction. Relative
* increments until the unit timer overflows at which point it latches the
* position value, resets the position count to zero and starts again.
*/
#ifndef LIBBSP_ARM_BEAGLE_QEP_H
#define LIBBSP_ARM_BEAGLE_QEP_H
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
#define AM335X_EQEP_REGS (0x00000180)
#define AM335X_EQEP_0_REGS (AM335X_PWMSS0_MMAP_ADDR + AM335X_EQEP_REGS)
#define AM335X_EQEP_1_REGS (AM335X_PWMSS1_MMAP_ADDR + AM335X_EQEP_REGS)
#define AM335X_EQEP_2_REGS (AM335X_PWMSS2_MMAP_ADDR + AM335X_EQEP_REGS)
/* eQEP registers of the PWMSS modules - see page 1672 of the TRM for details */
#define AM335x_EQEP_QPOSCNT 0x0 /* eQEP Position Counter */
#define AM335x_EQEP_QPOSINIT 0x4 /* eQEP Position Counter Initialization */
#define AM335x_EQEP_QPOSMAX 0x8 /* eQEP Maximum Position Count */
#define AM335x_EQEP_QPOSCMP 0xC /* eQEP Position-Compare */
#define AM335x_EQEP_QPOSILAT 0x10 /* eQEP Index Position Latch */
#define AM335x_EQEP_QPOSSLAT 0x14 /* eQEP Strobe Position Latch */
#define AM335x_EQEP_QPOSLAT 0x18 /* eQEP Position Counter Latch */
#define AM335x_EQEP_QUTMR 0x1C /* eQEP Unit Timer */
#define AM335x_EQEP_QUPRD 0x20 /* eQEP Unit Period */
#define AM335x_EQEP_QWDTMR 0x24 /* eQEP Watchdog Timer */
#define AM335x_EQEP_QWDPRD 0x26 /* eQEP Watchdog Period */
#define AM335x_EQEP_QDECCTL 0x28 /* eQEP Decoder Control */
#define AM335x_EQEP_QEPCTL 0x2A /* eQEP Control */
#define AM335x_EQEP_QCAPCTL 0x2C /* eQEP Capture Control */
#define AM335x_EQEP_QPOSCTL 0x2E /* eQEP Position-Compare Control */
#define AM335x_EQEP_QEINT 0x30 /* eQEP Interrupt Enable */
#define AM335x_EQEP_QFLG 0x32 /* eQEP Interrupt Flag */
#define AM335x_EQEP_QCLR 0x34 /* eQEP Interrupt Clear */
#define AM335x_EQEP_QFRC 0x36 /* eQEP Interrupt Force */
#define AM335x_EQEP_QEPSTS 0x38 /* eQEP Status */
#define AM335x_EQEP_QCTMR 0x3A /* eQEP Capture Timer */
#define AM335x_EQEP_QCPRD 0x3C /* eQEP Capture Period */
#define AM335x_EQEP_QCTMRLAT 0x3E /* eQEP Capture Timer Latch */
#define AM335x_EQEP_QCPRDLAT 0x40 /* eQEP Capture Period Latch */
#define AM335x_EQEP_REVID 0x5C /* eQEP Revision ID */
/* bitmasks for eQEP registers */
#define AM335x_EQEP_QEPCTL_UTE (1 << 1)
#define AM335x_EQEP_QEPCTL_QCLM (1 << 2)
#define AM335x_EQEP_QEPCTL_PHEN (1 << 3)
#define AM335x_EQEP_QEPCTL_IEL (1 << 4)
#define AM335x_EQEP_QEPCTL_SWI (1 << 7)
#define AM335x_EQEP_QEPCTL_PCRM (3 << 12)
#define AM335x_EQEP_QDECCTL_QSRC (3 << 14)
#define AM335x_EQEP_QDECCTL_XCR (1 << 11)
#define AM335x_EQEP_QDECCTL_SWAP (1 << 10)
#define AM335x_EQEP_QDECCTL_IGATE (1 << 9)
#define AM335x_EQEP_QDECCTL_QAP (1 << 8)
#define AM335x_EQEP_QDECCTL_QBP (1 << 7)
#define AM335x_EQEP_QDECCTL_QIP (1 << 6)
#define AM335x_EQEP_QDECCTL_QSP (1 << 5)
#define AM335x_EQEP_CLK_EN (1 << 4)
#define AM335x_EQEP_QEINT_UTO (1 << 11)
#define AM335x_EQEP_QFLG_UTO (1 << 11)
#define AM335x_EQEP_QFLG_MASK 0x0FFF
/* The pin mux modes for the QEP input pins on the P8 and P9 headers */
#define BBB_P8_11_MUX_QEP 4
#define BBB_P8_12_MUX_QEP 4
#define BBB_P8_15_MUX_QEP 4
#define BBB_P8_16_MUX_QEP 4
#define BBB_P8_31_MUX_QEP 2
#define BBB_P8_32_MUX_QEP 2
#define BBB_P8_33_MUX_QEP 2
#define BBB_P8_35_MUX_QEP 2
#define BBB_P8_39_MUX_QEP 3
#define BBB_P8_40_MUX_QEP 3
#define BBB_P8_41_MUX_QEP 3
#define BBB_P8_42_MUX_QEP 3
#define BBB_P9_25_MUX_QEP 1
#define BBB_P9_27_MUX_QEP 1
#define BBB_P9_41_MUX_QEP 1
#define BBB_P9_42_MUX_QEP 1
#define NANO_SEC_PER_SEC 1000000000
/* This is the max clock rate for the EPWMSS module. See 15.1.2.2 of the TRM.
* If the CPU was using dynamic scaling this could potentially be wrong */
#define SYSCLKOUT 100000000
/**
* @brief The set of possible eQEP Position Counter Input Modes
*
* Enumerated type to define various modes for the eQEP module. The values
* correspond to the values for the QSRC bits of the QDECCTL register.
*/
typedef enum {
QUADRATURE_COUNT = 0,
DIRECTION_COUNT,
UP_COUNT,
DOWN_COUNT
} BBB_QEP_COUNT_MODE;
/**
* @brief The set of possible modes for Quadrature decode
*
*/
typedef enum {
ABSOLUTE = 0,
RELATIVE
} BBB_QEP_QUADRATURE_MODE;
/**
* @brief The set of possible eQEP input pins
*
*/
typedef enum {
BBB_P8_11_2B_IN,
BBB_P8_12_2A_IN,
BBB_P8_15_2_STROBE,
BBB_P8_16_2_IDX,
BBB_P8_31_1_IDX,
BBB_P8_32_1_STROBE,
BBB_P8_33_1B_IN,
BBB_P8_35_1A_IN,
BBB_P8_39_2_IDX,
BBB_P8_40_2_STROBE,
BBB_P8_41_2A_IN,
BBB_P8_42_2B_IN,
BBB_P9_25_0_STROBE,
BBB_P9_27_0B_IN,
BBB_P9_41_0_IDX,
BBB_P9_42_0A_IN
} bbb_qep_pin;
/**
* @brief This function definition is used to declare a callback function that
* will be called by the interrupt handler of the QEP driver. In order for the
* interrupt event to trigger the driver must be configured in RELATIVE mode
* (using the beagle_qep_get_quadrature_mode function), and the unit timer must
* have been configured (using the beagle_eqep_set_timer_period function).
*
* @param BBB_PWMSS This argument is provided to the user call back function so
* that the user can tell which QEP module raised the interrupt.
*
* @param position The value of the position counter that was latched when the
* unit timer raised this interrupt. This is the value that would be returned
* by calling "beagle_qep_get_position".
*
* @param user This a pointer to a user provided data structure. The user sets
* this pointer value when configuring the unit timer callback via the
* beagle_eqep_set_timer_period function and it is returned here as an argument.
* The driver does not touch this value.
*/
typedef void (*bbb_eqep_timer_callback)(
BBB_PWMSS,
uint32_t position,
void* user
);
/**
* @brief This structure represents an eQEP module instance. The members
* represent the configuration of a specific eQEP module. There are three
* eQEP modules in the AM335x, one associated with each PWMSS unit.
* @var bbb_eqep::pwmss_id The PWMSS unit this eQEP module belongs to.
* @var bbb_eqep::mmio_base The base address for this eQEP modules registers
* @var bbb_eqep::irq The IRQ vector for this eQEP module
* @var bbb_eqep::timer_callback An optional user provided callback function
* when the driver is configured in RELATIVE mode using the unit timer
* @var bbb_eqep::user An optional pointer to user provided data that will be
* handed to the callback function as an argument.
* @var bbb_eqep::count_mode The count mode for this eQEP module. Defaults to
* QUADRATURE.
* @var bbb_eqep::quadrature_mode The mode for QUADRATURE operation. Defaults
* to ABSOLUTE - will count up to overflow or until the user resets the
* position. Can be set to RELATIVE which will trigger a call back of the unit
* timer if configured.
* @var bbb_eqep::invert_qa 1 to invert the A channel input, 0 to leave as is.
* @var bbb_eqep::invert_qb 1 to invert the B channel input, 0 to leave as is.
* @var bbb_eqep::invert_qi 1 to invert the INDEX input, 0 to leave as is.
* @var bbb_eqep::invert_qs 1 to invert the STROBE input, 0 to leave as is.
* @var bbb_eqep::swap_inputs 1 to swap the A and B channel inputs, 0 to leave
* as is.
*
*/
typedef struct {
const BBB_PWMSS pwmss_id;
const uint32_t mmio_base;
const rtems_vector_number irq;
bbb_eqep_timer_callback timer_callback;
void* user;
BBB_QEP_COUNT_MODE count_mode;
BBB_QEP_QUADRATURE_MODE quadrature_mode;
uint32_t invert_qa;
uint32_t invert_qb;
uint32_t invert_qi;
uint32_t invert_qs;
uint32_t swap_inputs;
} bbb_eqep;
/**
* @brief Initialises the eQEP module of the specified PWMSS unit. This
* configures the clocks, sets up the interrupt handler and unit timer,
* The module is configured in Quadrature decode mode using
* absolute position by default.
*
* @param pwmss_id The PWMSS module to configure the eQEP for.
* @return RTEMS_SUCCESSFUL if ok, RTEMS_INVALID_ID if an invalid pwmss_id is
* supplied.
*/
rtems_status_code beagle_qep_init(BBB_PWMSS pwmss_id);
/**
* @brief Enables the eQEP module of the specified PWMSS unit.
*
* @param pwmss_id The PWMSS module which will have the eQEP function enabled.
* @return RTEMS_SUCCESSFUL if ok, RTEMS_INVALID_ID if an invalid pwmss_id is
* supplied.
*/
rtems_status_code beagle_qep_enable(BBB_PWMSS pwmss_id);
/**
* @brief Disables the eQEP module of the specified PWMSS unit.
*
* @param pwmss_id The PWMSS module which will have the eQEP function disabled.
* @return RTEMS_SUCCESSFUL if ok, RTEMS_INVALID_ID if an invalid pwmss_id is
* supplied.
*/
rtems_status_code beagle_qep_disable(BBB_PWMSS pwmss_id);
/**
* @brief Configures a given pin for use with the eQEP function of the supplied
* PWMSS module.
*
* @param pin_no The P9 or P8 header pin to be configured for the eQEP function.
* @param pwmss_id The PWMSS module which will have the eQEP function enabled.
* @param pullup_enable If true then the internal pull up resistor on the
* specified pin will be enabled, if false the pull down will be enabled.
* @return RTEMS_SUCCESSFUL if ok, RTEMS_INVALID_ID if an invalid pwmss_id is
* supplied.
*/
rtems_status_code beagle_qep_pinmux_setup(
bbb_qep_pin pin_no,
BBB_PWMSS pwmss_id,
bool pullup_enable
);
/**
* @brief Returns the current position value of the eQEP function for the
* specified PWMSS module.
*
* @param pwmss_id Identifies which PWMSS module to return the eQEP position for
* @return int32_t The current position value.
*/
int32_t beagle_qep_get_position(BBB_PWMSS pwmss_id);
/**
* @brief Sets the initial position value of the eQEP function for the
* specified PWMSS module.
*
* @param pwmss_id Identifies which PWMSS module to set the eQEP position for
* @param position The value to initialise the position register with.
* @return RTEMS_SUCCESSFUL if ok, RTEMS_INVALID_ID if an invalid pwmss_id is
* supplied.
*/
rtems_status_code beagle_qep_set_position(
BBB_PWMSS pwmss_id,
uint32_t position
);
/**
* @brief Sets the count mode for the eQEP module.
* @param pwmss_id Identifies which PWMSS module to set the eQEP count mode for.
* @param mode One of the above modes to configure the eQEP module for.
* @return RTEMS_SUCCESSFUL if ok, RTEMS_INVALID_ID if an invalid pwmss_id is
* supplied.
*/
rtems_status_code beagle_qep_set_count_mode(
BBB_PWMSS pwmss_id,
BBB_QEP_COUNT_MODE mode
);
/**
* @brief Gets the currently configured count mode for the eQEP module.
* @param pwmss_id Identifies which PWMSS module to set the eQEP count mode for.
* @return An enum value representing the current count mode.
*/
BBB_QEP_COUNT_MODE beagle_qep_get_count_mode(BBB_PWMSS pwmss_id);
/**
* @brief Returns the currently configured quadrature mode - either absolute,
* or relative.
* @param pwmss_id Identifies which PWMSS module to get the eQEP quadrature
* mode for.
* @return BBB_QEP_QUADRATURE_MODE The currently configured quadrature mode.
*/
BBB_QEP_QUADRATURE_MODE beagle_qep_get_quadrature_mode(BBB_PWMSS pwmss_id);
/**
* @brief Sets the quadrature mode to either absolute or relative.
* @param pwmss_id Identifies which PWMSS module to set the eQEP quadrature
* mode for.
* @param mode BBB_QEP_QUADRATURE_MODE Set the mode of the eQEP to either
* absolute or relative.
* @return RTEMS_SUCCESSFUL if ok, RTEMS_INVALID_ID if an invalid pwmss_id is
* supplied.
*/
rtems_status_code beagle_qep_set_quadrature_mode(
BBB_PWMSS pwmss_id,
BBB_QEP_QUADRATURE_MODE mode
);
/**
* @brief Returns the the currently configured unit timer period.
* @param pwmss_id Identifies which PWMSS module to get the eQEP timer value for
* @return uint32_t The current unit timer value in nanoseconds
*/
uint32_t beagle_eqep_get_timer_period(BBB_PWMSS pwmss_id);
/**
* @brief Sets the unit timer period for the eQEP module.
* 0 = off, greater than zero sets the period.
* @param pwmss_id Identifies which PWMSS module to set the eQEP unit timer for.
* @param period The value in nanoseconds to set the unit timer period to.
* @param timer_callback This is the user provided callback function that will
* be called by the interrupt event handler on expiry of the unit timer. The
* user can provide NULL if they don't require a call back.
* @param user This is a pointer to a user provided data structure that will be
* handed back as an argument to the timer callback. The driver does not touch
* this value.
* @return RTEMS_SUCCESSFUL if ok, RTEMS_INVALID_ID if an invalid pwmss_id is
* supplied.
*/
rtems_status_code beagle_eqep_set_timer_period(
BBB_PWMSS pwmss_id,
uint64_t period,
bbb_eqep_timer_callback timer_callback,
void* user
);
#ifdef __cplusplus
}
#endif /* __cplusplus */
#endif /* LIBBSP_ARM_BEAGLE_QEP_H */
