Freescale Semiconductor Inc.
Main Page | Data Structures | File List | Data Fields | Globals

etpu_crank_emul.h

Go to the documentation of this file.
00001 /*******************************************************************************
00002 *
00003 * Freescale Semiconductor Inc.
00004 * (c) Copyright 2004-2014 Freescale Semiconductor, Inc.
00005 * ALL RIGHTS RESERVED.
00006 *
00007 ****************************************************************************//*!
00008 *
00009 * @file    etpu_crank_emul.h
00010 *
00011 * @author  Milan Brejl [r54529]
00012 *
00013 * @version 1.0
00014 *
00015 * @date    16-Mar-2014
00016 *
00017 * @brief   This file contains useful macros and prototypes for CRANK_EMUL API.
00018 *
00019 *******************************************************************************/
00020 #ifndef _ETPU_CRANK_H_
00021 #define _ETPU_CRANK_H_
00022 
00023 /*******************************************************************************
00024 * Includes
00025 *******************************************************************************/
00026 #include "etpu_util.h"        /* 24-bit types */
00027 #include "etpu_crank_auto.h"    /* auto generated header file */
00028 #include "etpu_crank_emul_auto.h"    /* auto generated header file */
00029 
00030 /*******************************************************************************
00031 * Type Definitions
00032 *******************************************************************************/
00033 /** A structure to represent an instance of CRANK.
00034  *  It includes static CRANK initialization items. */
00035 struct crank_instance_t
00036 {
00037   const uint8_t  chan_num;  /**< Channel number of the CRANK channel. */
00038   const uint8_t  priority;  /**< Channel priority for the CRANK channel. */
00039   const uint8_t  polarity;  /**< CRANK transition polarity.
00040     It defines which type of transitions are captured. It can be one of:
00041     - @ref FS_ETPU_CRANK_FM0_USE_TRANS_RISING
00042     - @ref FS_ETPU_CRANK_FM0_USE_TRANS_FALLING */
00043   const uint8_t  teeth_till_gap; /**< A number of physical teeth between 2 gaps.
00044     This is the number of physical teeth on the crank wheel divided by
00045     the number of (equally spaced) gaps on the wheel. */
00046   const uint8_t  teeth_in_gap; /**< A number of missing teeth in one gap.
00047     This can be assigned a value of 1, 2, 3 (for eTPU and eTPU2), up to 7
00048     (for eTPU2+), or 0. The value 0 indicates there is an additional tooth
00049     instead of missing teeth. */
00050   const uint8_t  teeth_per_cycle; /**< A number of teeth (including missing
00051     teeth in gap) per an engine cycle (720 degrees). It must be a multiple of
00052     (teeth_till_gap + teeth_in_gap). */
00053   const uint24_t tcr2_ticks_per_tooth; /**< A number of TCR2 angle ticks per one
00054     tooth. It can be any value between 1 and 1024. */
00055   const uint8_t  log_tooth_periods; /**< An option to record tooth_periods.
00056     It can be one of:
00057     - @ref FS_ETPU_CRANK_FM1_TOOTH_PERIODS_LOG_OFF
00058     - @ref FS_ETPU_CRANK_FM1_TOOTH_PERIODS_LOG_ON */
00059   const uint32_t link_cam;  /**< Set of 4 link numbers to send to reset the Cam
00060     log. Up to 4 Cam channel numbers can be used. In case of a single Cam on
00061     channel 1, use 0x01010101. */
00062   const uint32_t link_1;    /**< The first  set of 4 link numbers to send when
00063     stall conditions accure. */
00064   const uint32_t link_2;    /**< The second set of 4 link numbers to send when
00065     stall conditions accure. */
00066   const uint32_t link_3;    /**< The third  set of 4 link numbers to send when
00067     stall conditions accure. */
00068   const uint32_t link_4;    /**< The fourth set of 4 link numbers to send when
00069     stall conditions accure. */
00070         uint32_t *cpba;     /**< Channel parameter base address.
00071     Set cpba = 0 to use automatic allocation of eTPU DATA RAM for CRANK channel
00072     parameters using the eTPU utility function fs_etpu_malloc (recommanded),
00073     or assign the cpba manually by an address where the CRANK channel parameter
00074     space will start from, e.g. 0xC3FC8100. */
00075         uint32_t *cpba_tooth_period_log; /**< Base address of the CRANK tooth
00076     period log buffer in eTPU DATA RAM. Set cpba_tooth_period_log = 0 to use
00077     automatic allocation of eTPU DATA RAM for this buffer using the eTPU utility
00078     function fs_etpu_malloc (recommanded), or assign the p_tooth_period_log
00079     manually by an address where the CRANK buffer will start. The memory does
00080     not need to be allocated if FS_ETPU_CRANK_FM1_TOOTH_PERIODS_LOG_OFF is set.*/
00081 };
00082 
00083 /** A structure to represent a configuration of CRANK.
00084  *  It includes CRANK configuration items which can be changed in
00085  *  run-time. */
00086 struct crank_config_t
00087 {
00088         uint8_t  teeth_per_sync; /**< A number of teeth (including the
00089     missing teeth in gap) corresponding to a segment which is needed for the Cam
00090     to log enough Cam transitions so that it enables to recognize the correct
00091     engine half-cycle and achieve synchronozation. It must be a multiple of
00092     (teeth_till_gap + teeth_in_gap). */
00093         uint24_t blank_time; /**< A TCR1 time period after initialization during
00094     which teeth are ignored. */
00095         uint8_t  blank_teeth; /**< A number of teeth ignored after
00096     initialization. */
00097         ufract24_t gap_ratio; /**< A fraction used to perform the ABA gap test.
00098     For a crank wheel with a gap:
00099       gap_ratio * tooth_period_B > tooth_period_A.
00100     For a crank wheel with an additional tooth:
00101       gap_ratio * tooth_period_A > tooth_period_B. */
00102         ufract24_t win_ratio_normal; /**< A fraction used to derive
00103     the acceptance window for the next normal tooth. */
00104         ufract24_t win_ratio_across_gap; /**< A fraction used to derive
00105     the acceptance window for the first tooth after the gap. */
00106         ufract24_t win_ratio_after_gap; /**< A fraction used to derive
00107     the acceptance window for the second tooth after the gap. */
00108         ufract24_t win_ratio_after_timeout; /**< A fraction used to derive
00109     the acceptance window for the tooth following a timeout condition. */
00110         uint24_t first_tooth_timeout; /**< A TCR1 time period after the first
00111     tooth (after blank_teeth) when a timeout will be deemed to have happened. */
00112 };
00113 
00114 /** A structure to represent internal states of CRANK. */
00115 struct crank_states_t
00116 {
00117         uint8_t error;      /**< This is the error status of CRANK. It includes
00118     the following error flags:
00119     - @ref FS_ETPU_CRANK_ERR_INVALID_TRANS
00120     - @ref FS_ETPU_CRANK_ERR_INVALID_MATCH
00121     - @ref FS_ETPU_CRANK_ERR_TIMEOUT
00122     - @ref FS_ETPU_CRANK_ERR_STALL
00123     - @ref FS_ETPU_CRANK_ERR_INTERNAL
00124     - @ref FS_ETPU_CRANK_ERR_TIMEOUT_BEFORE_GAP
00125     - @ref FS_ETPU_CRANK_ERR_TIMEOUT_AFTER_GAP
00126     - @ref FS_ETPU_CRANK_ERR_TOOTH_IN_GAP
00127     The eTPU sets the error flags, the CPU clears them after reading. */
00128         uint8_t state; /**< This is the state of CRANK. It can be one of:
00129     - @ref FS_ETPU_CRANK_SEEK
00130     - @ref FS_ETPU_CRANK_BLANK_TIME
00131     - @ref FS_ETPU_CRANK_BLANK_TEETH
00132     - @ref FS_ETPU_CRANK_FIRST_TRANS
00133     - @ref FS_ETPU_CRANK_SECOND_TRANS
00134     - @ref FS_ETPU_CRANK_TEST_POSSIBLE_GAP
00135     - @ref FS_ETPU_CRANK_VERIFY_GAP
00136     - @ref FS_ETPU_CRANK_COUNTING
00137     - @ref FS_ETPU_CRANK_COUNTING_TIMEOUT
00138     - @ref FS_ETPU_CRANK_TOOTH_BEFORE_GAP
00139     - @ref FS_ETPU_CRANK_TOOTH_BEFORE_GAP_NOT_HRM
00140       @ref FS_ETPU_CRANK_ADDITIONAL_TOOTH
00141     - @ref FS_ETPU_CRANK_TOOTH_AFTER_GAP  */
00142         uint8_t eng_pos_state; /**< This is the global engine position state.
00143     It can be one of:
00144     - @ref FS_ETPU_ENG_POS_SEEK
00145     - @ref FS_ETPU_ENG_POS_FIRST_HALF_SYNC
00146     - @ref FS_ETPU_ENG_POS_PRE_FULL_SYNC
00147     - @ref FS_ETPU_ENG_POS_FULL_SYNC  */
00148         uint8_t tooth_counter_gap; /**< The actual number of the tooth counter
00149     which counts from 1 to teeth_till_gap and resets on every gap. */
00150         uint8_t tooth_counter_cycle; /**< The actual number of the tooth counter
00151     which counts from 1 to teeth_per_cycle and resets every engine cycle. */
00152        uint24_t last_tooth_period; /**< The last tooth period as a number
00153     of TCR1 ticks. */
00154 };
00155 
00156 /*******************************************************************************
00157 * Function prototypes
00158 *******************************************************************************/
00159 /* Initialize */
00160 uint32_t fs_etpu_crank_init(
00161   struct crank_instance_t *p_crank_instance,
00162   struct crank_config_t   *p_crank_config);
00163 
00164 /* Change configuration */
00165 uint32_t fs_etpu_crank_config(
00166   struct crank_instance_t *p_crank_instance,
00167   struct crank_config_t   *p_crank_config);
00168 
00169 /* Get states */
00170 uint32_t fs_etpu_crank_get_states(
00171   struct crank_instance_t *p_crank_instance,
00172   struct crank_states_t   *p_crank_states);
00173 
00174 /* Set synchronization */
00175 uint32_t fs_etpu_crank_set_sync(
00176   struct crank_instance_t *p_crank_instance,
00177                  uint24_t tcr2_adjustment);
00178 
00179 /* Set speed */
00180 uint32_t fs_etpu_crank_set_speed(
00181   struct crank_instance_t *p_crank_instance,
00182                  uint24_t tooth_period);
00183 
00184 /* Copy tooth_period_log */
00185 uint24_t *fs_etpu_crank_copy_tooth_period_log(
00186   struct crank_instance_t *p_crank_instance,
00187                  uint24_t *p_tooth_period_log);
00188 
00189 
00190 #endif /* _ETPU_CRANK_H_ */
00191 /*******************************************************************************
00192  *
00193  * Copyright:
00194  *  Freescale Semiconductor, INC. All Rights Reserved.
00195  *  You are hereby granted a copyright license to use, modify, and
00196  *  distribute the SOFTWARE so long as this entire notice is
00197  *  retained without alteration in any modified and/or redistributed
00198  *  versions, and that such modified versions are clearly identified
00199  *  as such. No licenses are granted by implication, estoppel or
00200  *  otherwise under any patents or trademarks of Freescale
00201  *  Semiconductor, Inc. This software is provided on an "AS IS"
00202  *  basis and without warranty.
00203  *
00204  *  To the maximum extent permitted by applicable law, Freescale
00205  *  Semiconductor DISCLAIMS ALL WARRANTIES WHETHER EXPRESS OR IMPLIED,
00206  *  INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
00207  *  PARTICULAR PURPOSE AND ANY WARRANTY AGAINST INFRINGEMENT WITH
00208  *  REGARD TO THE SOFTWARE (INCLUDING ANY MODIFIED VERSIONS THEREOF)
00209  *  AND ANY ACCOMPANYING WRITTEN MATERIALS.
00210  *
00211  *  To the maximum extent permitted by applicable law, IN NO EVENT
00212  *  SHALL Freescale Semiconductor BE LIABLE FOR ANY DAMAGES WHATSOEVER
00213  *  (INCLUDING WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS,
00214  *  BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR OTHER
00215  *  PECUNIARY LOSS) ARISING OF THE USE OR INABILITY TO USE THE SOFTWARE.
00216  *
00217  *  Freescale Semiconductor assumes no responsibility for the
00218  *  maintenance and support of this software
00219  ******************************************************************************/
00220 /*******************************************************************************
00221  *
00222  * REVISION HISTORY:
00223  *
00224  * FILE OWNER: Milan Brejl [r54529]
00225  *
00226  * Revision 1.0  2014/03/16  r54529
00227  * Minor comment and formating improvements.
00228  * Ready for eTPU Engine Control Library release 1.0.
00229  *
00230  * Revision 0.2  2014/01/15  r54529
00231  * Improvment of DoxyGen comments.
00232  *
00233  * Revision 0.1  2013/03/29  r54529
00234  * Initial version based on standard etpu_crank.h v0.2.
00235  *
00236  ******************************************************************************/