dbg_ram_capture.h

00001 /*
00002  * Copyright (c) 2015, Freescale Semiconductor, Inc.
00003  * Copyright 2016-2017 NXP
00004  *
00005  * Redistribution and use in source and binary forms, with or without modification,
00006  * are permitted provided that the following conditions are met:
00007  *
00008  * o Redistributions of source code must retain the above copyright notice, this list
00009  *   of conditions and the following disclaimer.
00010  *
00011  * o Redistributions in binary form must reproduce the above copyright notice, this
00012  *   list of conditions and the following disclaimer in the documentation and/or
00013  *   other materials provided with the distribution.
00014  *
00015  * o Neither the name of Freescale Semiconductor, Inc. nor the names of its
00016  *   contributors may be used to endorse or promote products derived from this
00017  *   software without specific prior written permission.
00018  *
00019  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00020  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00021  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00022  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00023  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00024  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00025  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00026  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00027  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00028  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00029  */
00030 #ifndef _DBG_RAM_CAPTURE_H_
00031 /* clang-format off */
00032 #define _DBG_RAM_CAPTURE_H_
00033 /* clang-format on */
00034 
00035 #include "fsl_common.h"
00036 #include "fsl_device_registers.h"
00037 
00038 /*!
00039  * @addtogroup xcvr
00040  * @{
00041  */
00042 
00043 /*! @file*/
00044 
00045 /*******************************************************************************
00046  * Definitions
00047  ******************************************************************************/
00048 /* Page definitions */
00049 #define DBG_PAGE_IDLE           (0x00)
00050 #define DBG_PAGE_RXDIGIQ        (0x01)
00051 #define DBG_PAGE_RAWADCIQ       (0x04)
00052 #define DBG_PAGE_DCESTIQ        (0x07)
00053 #define DBG_PAGE_RXINPH         (0x0A)
00054 #define DBG_PAGE_DEMOD_HARD     (0x0B)
00055 #define DBG_PAGE_DEMOD_SOFT     (0x0C)
00056 #define DBG_PAGE_DEMOD_DATA     (0x0D)
00057 #define DBG_PAGE_DEMOD_CFO_PH   (0x0E)
00058 
00059 typedef enum _dbgRamStatus
00060 {
00061     DBG_RAM_SUCCESS = 0,
00062     DBG_RAM_FAIL_SAMPLE_NUM_LIMIT = 1,
00063     DBG_RAM_FAIL_PAGE_ERROR = 2,
00064     DBG_RAM_FAIL_NULL_POINTER = 3,
00065     DBG_RAM_INVALID_TRIG_SETTING = 4,
00066     DBG_RAM_FAIL_NOT_ENOUGH_SAMPLES = 5,
00067     DBG_RAM_CAPTURE_NOT_COMPLETE = 6, /* Not an error response, but an indication that capture isn't complete for status polling */
00068 } dbgRamStatus_t;
00069 
00070 #if RADIO_IS_GEN_3P0
00071 typedef enum _dbgRamStartTriggerType
00072 {
00073     NO_START_TRIG = 0,
00074     START_ON_FSK_PREAMBLE_FOUND = 1,
00075     START_ON_FSK_AA_MATCH = 2,
00076     START_ON_ZBDEMOD_PREAMBLE_FOUND = 3,
00077     START_ON_ZBDEMOD_SFD_MATCH = 4,
00078     START_ON_AGC_DCOC_GAIN_CHG = 5,
00079     START_ON_TSM_RX_DIG_EN = 6,
00080     START_ON_TSM_SPARE2_EN = 7,
00081     INVALID_START_TRIG = 8
00082 } dbgRamStartTriggerType;
00083 
00084 typedef enum _dbgRamStopTriggerType
00085 {
00086     NO_STOP_TRIG = 0,
00087     STOP_ON_FSK_PREAMBLE_FOUND = 1,
00088     STOP_ON_FSK_AA_MATCH = 2,
00089     STOP_ON_ZBDEMOD_PREAMBLE_FOUND = 3,
00090     STOP_ON_ZBDEMOD_SFD_MATCH = 4,
00091     STOP_ON_AGC_DCOC_GAIN_CHG = 5,
00092     STOP_ON_TSM_RX_DIG_EN = 6,
00093     STOP_ON_TSM_SPARE3_EN = 7,
00094     STOP_ON_TSM_PLL_UNLOCK = 8,
00095     STOP_ON_BLE_CRC_ERROR_INC = 9,
00096     STOP_ON_CRC_FAIL_ZGBE_GENFSK = 10,
00097     STOP_ON_GENFSK_HEADER_FAIL = 11,
00098     INVALID_STOP_TRIG = 12
00099 } dbgRamStopTriggerType;
00100 #endif /* RADIO_IS_GEN_3P0 */
00101 
00102 /*! *********************************************************************************
00103  * \brief  This function prepares for sample capture to packet RAM.
00104  *
00105  * \return None.
00106  *
00107  * \details 
00108  * This routine assumes that some other functions in the calling routine both set
00109  * the channel and force RX warmup before calling ::dbg_ram_capture().
00110  ***********************************************************************************/
00111 void dbg_ram_init(void);
00112 
00113 /*! *********************************************************************************
00114  * \brief  This function performs any state restoration at the completion of PKT RAM capture.
00115  * 
00116  * \details
00117  * Any clocks enabled to the packet RAM capture circuitry are disabled.
00118  ***********************************************************************************/
00119 void dbg_ram_release(void);
00120 
00121 #if RADIO_IS_GEN_3P0
00122 /*! *********************************************************************************
00123  * \brief  This function initiates the capture of transceiver data to the transceiver packet RAM.
00124  *
00125  * \param[in] dbg_page - The page selector (DBG_PAGE).
00126  * \param[in] dbg_start_trigger - The trigger to start acquisition (must be "no trigger" if a stop trigger is enabled).
00127  * \param[in] dbg_stop_trigger - The trigger to stop acquisition (must be "no trigger" if a start trigger is enabled).
00128  *
00129  * \return Status of the request.
00130  *
00131  * \details 
00132  * This function starts the process of capturing data to the packet RAM. Depending upon the start and stop trigger
00133  * settings, the actual capture process can take an indeterminate amount of time. Other APIs are provided to 
00134  * perform a blocking wait for completion or allow polling for completion of the capture.
00135  * After any capture has completed, a separate routine must be called to postprocess the capture and copy all
00136  * data out of the packet RAM into a normal RAM buffer.
00137  ***********************************************************************************/
00138 dbgRamStatus_t dbg_ram_start_capture(uint8_t dbg_page, dbgRamStartTriggerType start_trig, dbgRamStopTriggerType stop_trig);
00139 
00140 /*! *********************************************************************************
00141  * \brief  This function performs a blocking wait for completion of the capture of transceiver data to the transceiver packet RAM.
00142  *
00143  * \return Status of the request, DBG_RAM_SUCCESS if capture is complete.
00144  *
00145  * \details 
00146  * This function performs a wait loop for capture completion and may take an indeterminate amount of time for 
00147  * some capture trigger types.
00148  ***********************************************************************************/
00149 dbgRamStatus_t dbg_ram_wait_for_complete(void); /* Blocking wait for capture completion, no matter what trigger type */
00150 
00151 /*! *********************************************************************************
00152  * \brief  This function polls the state of the capture of transceiver data to the transceiver packet RAM.
00153  *
00154  * \return Status of the request, DBG_RAM_SUCCESS if capture is complete, DBG_RAM_CAPTURE_NOT_COMPLETE if not complete.
00155  *
00156  ***********************************************************************************/
00157 dbgRamStatus_t dbg_ram_poll_capture_status(void); /* Non-blocking completion check, just reads the current status of the capure */
00158 
00159 /*! *********************************************************************************
00160  * \brief  This function processes the captured data into a usable order and copies from packet RAM to normal RAM.
00161  *
00162  * \param[in] dbg_page - The page selector (DBG_PAGE).
00163  * \param[in] buffer_sz_bytes - The size of the output buffer (in bytes)
00164  * \param[in] result_buffer - The pointer to the output buffer of a size large enough for the samples.
00165  *
00166  * \return None.
00167  *
00168  * \details 
00169  * Data is copied from packet RAM in bytes to ensure no access problems. Data is unpacked from packet RAM 
00170  * (either sequentially captured or simultaneously captured) into a linear RAM buffer in system RAM. 
00171  * If a start trigger is enabled then the first buffer_sz_bytes that are captured are copied out.
00172  * If a stop trigger is enabled then the last buffer_sz_bytes that are captured are copied out.
00173  ***********************************************************************************/
00174 dbgRamStatus_t dbg_ram_postproc_capture(uint8_t dbg_page, uint16_t buffer_sz_bytes, void * result_buffer); /* postprocess a capture to unpack data */
00175 
00176 #else
00177 /*! *********************************************************************************
00178  * \brief  This function captures transceiver data to the transceiver packet RAM.
00179  *
00180  * \param[in] dbg_page - The page selector (DBG_PAGE).
00181  * \param[in] buffer_sz_bytes - The size of the output buffer (in bytes)
00182  * \param[in] result_buffer - The pointer to the output buffer of a size large enough for the samples.
00183  *
00184  * \return None.
00185  *
00186  * \details 
00187  * The capture to packet RAM always captures a full PKT_RAM worth of samples. The samples will be 
00188  * copied to the buffer pointed to by result_buffer parameter until buffer_sz_bytes worth of data have
00189  * been copied. Data will be copied 
00190  * NOTE: This routine has a slight hazard of getting stuck waiting for debug RAM to fill up when RX has
00191  * not been enabled or RX ends before the RAM fills up (such as when capturing packet data ). It is 
00192  * intended to be used with manually triggered RX where RX data will continue as long as needed.
00193  ***********************************************************************************/
00194 dbgRamStatus_t dbg_ram_capture(uint8_t dbg_page, uint16_t buffer_sz_bytes, void * result_buffer);
00195 #endif /* RADIO_IS_GEN_3P0 */
00196 
00197 /* @} */
00198 
00199 #if defined(__cplusplus)
00200 }
00201 #endif
00202 
00203 /*! @}*/
00204 
00205 #endif /* _DBG_RAM_CAPTURE_H_ */
00206