LXR 6.1/​bsps/​arm/​beagle/​include/​bsp/​qep.h	Source navigation Diff markup Identifier search General search
	Version: 6.1 Revert   Change

File indexing completed on 2025-05-11 08:22:48

 /**
  * @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 */

This page was automatically generated by the 2.3.7 LXR engine. The LXR team