From 4da05d206be2ef36cc9b9d9a7a31041b18834b41 Mon Sep 17 00:00:00 2001 From: Bryan Biedenkapp Date: Wed, 3 Jul 2024 10:20:26 -0400 Subject: [PATCH] convert documentation format to Doxygen; --- CWIdTX.cpp | 45 ++--- CWIdTX.h | 54 ++++-- CalRSSI.cpp | 32 ++-- CalRSSI.h | 39 ++-- Debug.h | 22 +-- Defines.h | 24 +-- Globals.h | 41 +++-- IO.cpp | 140 +++++---------- IO.h | 240 +++++++++++++++++++------ IODue.cpp | 108 +++++------ IOSTM.cpp | 150 +++++++--------- RSSIBuffer.cpp | 60 +++---- RSSIBuffer.h | 63 +++++-- RingBuffer.h | 30 ++-- STM_UART.cpp | 71 ++++---- STM_UART.h | 100 ++++++++--- SampleBuffer.cpp | 62 +++---- SampleBuffer.h | 65 +++++-- SerialBuffer.cpp | 73 +++----- SerialBuffer.h | 79 +++++--- SerialDue.cpp | 71 +++----- SerialPort.cpp | 234 ++++++++---------------- SerialPort.h | 429 ++++++++++++++++++++++++++++++-------------- SerialSTM.cpp | 103 ++++------- Utils.cpp | 26 +-- Utils.h | 39 ++-- dmr/CalDMR.cpp | 64 +++---- dmr/CalDMR.h | 74 +++++--- dmr/DMRDMORX.cpp | 75 +++----- dmr/DMRDMORX.h | 88 ++++++--- dmr/DMRDMOTX.cpp | 80 +++------ dmr/DMRDMOTX.h | 78 +++++--- dmr/DMRDefines.h | 33 ++-- dmr/DMRIdleRX.cpp | 64 +++---- dmr/DMRIdleRX.h | 67 +++++-- dmr/DMRRX.cpp | 51 ++---- dmr/DMRRX.h | 55 ++++-- dmr/DMRSlotRX.cpp | 78 +++----- dmr/DMRSlotRX.h | 87 ++++++--- dmr/DMRSlotType.cpp | 64 ++----- dmr/DMRSlotType.h | 59 ++++-- dmr/DMRTX.cpp | 222 +++++++++-------------- dmr/DMRTX.h | 159 +++++++++++----- nxdn/CalNXDN.cpp | 40 ++--- nxdn/CalNXDN.h | 53 ++++-- nxdn/NXDNDefines.h | 17 +- nxdn/NXDNRX.cpp | 80 +++------ nxdn/NXDNRX.h | 87 ++++++--- nxdn/NXDNTX.cpp | 100 ++++------- nxdn/NXDNTX.h | 101 ++++++++--- p25/CalP25.cpp | 38 ++-- p25/CalP25.h | 53 ++++-- p25/P25Defines.h | 53 +++--- p25/P25RX.cpp | 100 ++++------- p25/P25RX.h | 109 ++++++++--- p25/P25TX.cpp | 105 ++++------- p25/P25TX.h | 105 ++++++++--- 57 files changed, 2608 insertions(+), 2231 deletions(-) diff --git a/CWIdTX.cpp b/CWIdTX.cpp index 4ea9987..91dab27 100644 --- a/CWIdTX.cpp +++ b/CWIdTX.cpp @@ -1,17 +1,13 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2017 Jonathan Naylor, G4KLX -* Copyright (C) 2016 Colin Durbridge, G4EML -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2009-2017 Jonathan Naylor, G4KLX + * Copyright (C) 2016 Colin Durbridge, G4EML + * + */ #include "Globals.h" #include "CWIdTX.h" @@ -84,9 +80,8 @@ const struct { // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the CWIdTX class. -/// +/* Initializes a new instance of the CWIdTX class. */ + CWIdTX::CWIdTX() : m_poBuffer(), m_poLen(0U), @@ -96,9 +91,8 @@ CWIdTX::CWIdTX() : /* stub */ } -/// -/// Process local buffer and transmit on the air interface. -/// +/* Process local buffer and transmit on the air interface. */ + void CWIdTX::process() { if (m_poLen == 0U) @@ -129,12 +123,8 @@ void CWIdTX::process() } } -/// -/// Write CW ID data to the local buffer. -/// -/// -/// -/// +/* Write CW ID data to the local buffer. */ + uint8_t CWIdTX::write(const uint8_t* data, uint8_t length) { ::memset(m_poBuffer, 0x00U, 1000U * sizeof(uint8_t)); @@ -175,9 +165,8 @@ uint8_t CWIdTX::write(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Helper to reset data values to defaults. -/// +/* Helper to reset data values to defaults. */ + void CWIdTX::reset() { m_poLen = 0U; diff --git a/CWIdTX.h b/CWIdTX.h index f8210df..5e8dd69 100644 --- a/CWIdTX.h +++ b/CWIdTX.h @@ -1,17 +1,23 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * @package DVM / Modem Firmware + * @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) + * @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) + * + * Copyright (C) 2009-2015 Jonathan Naylor, G4KLX + * Copyright (C) 2016 Colin Durbridge, G4EML + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2015 Jonathan Naylor, G4KLX -* Copyright (C) 2016 Colin Durbridge, G4EML -* -*/ + * @file CWIdTX.h + * @ingroup modem_fw + * @file CWIdTX.cpp + * @ingroup modem_fw + */ #if !defined(__CWID_TX_H__) #define __CWID_TX_H__ @@ -19,21 +25,35 @@ // --------------------------------------------------------------------------- // Class Declaration -// Implements logic to transmit a CW ID. // --------------------------------------------------------------------------- +/** + * @brief Implements logic to transmit a CW ID. + * @ingroup modem_fw + */ class DSP_FW_API CWIdTX { public: - /// Initializes a new instance of the CWIdTX class. + /** + * @brief Initializes a new instance of the CWIdTX class. + */ CWIdTX(); - /// Process local buffer and transmit on the air interface. + /** + * @brief Process local buffer and transmit on the air interface. + */ void process(); - /// Write CW ID data to the local buffer. + /** + * @brief Write CW ID data to the local buffer. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t write(const uint8_t* data, uint8_t length); - /// Helper to reset data values to defaults. + /** + * @brief Helper to reset data values to defaults. + */ void reset(); private: diff --git a/CalRSSI.cpp b/CalRSSI.cpp index 5aa8c9d..b867a4b 100644 --- a/CalRSSI.cpp +++ b/CalRSSI.cpp @@ -1,16 +1,12 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2016 Jonathan Naylor, G4KLX -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2016 Jonathan Naylor, G4KLX + * + */ #include "Globals.h" #include "CalRSSI.h" #include "Utils.h" @@ -19,9 +15,8 @@ // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the CalRSSI class. -/// +/* Initializes a new instance of the CalRSSI class. */ + CalRSSI::CalRSSI() : m_count(0U), m_accum(0U), @@ -31,11 +26,8 @@ CalRSSI::CalRSSI() : /* stub */ } -/// -/// Sample RSSI values from the air interface. -/// -/// -/// +/* Sample RSSI values from the air interface. */ + void CalRSSI::samples(const uint16_t* rssi, uint8_t length) { for (uint16_t i = 0U; i < length; i++) { diff --git a/CalRSSI.h b/CalRSSI.h index 56651b7..628c149 100644 --- a/CalRSSI.h +++ b/CalRSSI.h @@ -1,16 +1,18 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2016 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2016 Jonathan Naylor, G4KLX -* -*/ + * @file CalRSSI.h + * @ingroup modem_fw + * @file CalRSSI.cpp + * @ingroup modem_fw + */ #if !defined(__CAL_RSSI_H__) #define __CAL_RSSI_H__ @@ -18,15 +20,24 @@ // --------------------------------------------------------------------------- // Class Declaration -// Implements logic for RSSI calibration mode. // --------------------------------------------------------------------------- +/** + * @brief Implements logic for RSSI calibration mode. + * @ingroup modem_fw + */ class DSP_FW_API CalRSSI { public: - /// Initializes a new instance of the CalRSSI class. + /** + * @brief Initializes a new instance of the CalRSSI class. + */ CalRSSI(); - /// Sample RSSI values from the air interface. + /** + * @brief Sample RSSI values from the air interface. + * @param rssi + * @param length + */ void samples(const uint16_t* rssi, uint8_t length); private: diff --git a/Debug.h b/Debug.h index fb88d8b..c8a4115 100644 --- a/Debug.h +++ b/Debug.h @@ -1,16 +1,16 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* -*/ + * @file Debug.h + * @ingroup modem_fw + */ #if !defined(__DEBUG_H__) #define __DEBUG_H__ diff --git a/Defines.h b/Defines.h index 6ffb5e1..0ce09d7 100644 --- a/Defines.h +++ b/Defines.h @@ -1,17 +1,17 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2018 Bryan Biedenkapp, N2PLL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2018 Bryan Biedenkapp, N2PLL -* -*/ + * @file Defines.h + * @ingroup modem_fw + */ #if !defined(__DEFINES_H__) #define __DEFINES_H__ diff --git a/Globals.h b/Globals.h index 630c96d..b09a6d3 100644 --- a/Globals.h +++ b/Globals.h @@ -1,17 +1,22 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2017-2021 Bryan Biedenkapp, N2PLL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2017-2021 Bryan Biedenkapp, N2PLL -* -*/ + * @defgroup modem_fw Modem Firmware + * @brief Digital Voice Modem - Modem Firmware + * @details Firmware that is used for repeater interface boards. + * @ingroup modem_fw + * + * @file Globals.h + * @ingroup modem_fw + */ #if !defined(__GLOBALS_H__) #define __GLOBALS_H__ @@ -85,30 +90,30 @@ extern bool m_dcd; extern SerialPort serial; extern IO io; -/** DMR BS */ +/* DMR BS */ extern dmr::DMRIdleRX dmrIdleRX; extern dmr::DMRRX dmrRX; extern dmr::DMRTX dmrTX; -/** DMR MS-DMO */ +/* DMR MS-DMO */ extern dmr::DMRDMORX dmrDMORX; extern dmr::DMRDMOTX dmrDMOTX; -/** P25 BS */ +/* P25 BS */ extern p25::P25RX p25RX; extern p25::P25TX p25TX; -/** NXDN BS */ +/* NXDN BS */ extern nxdn::NXDNRX nxdnRX; extern nxdn::NXDNTX nxdnTX; -/** Calibration */ +/* Calibration */ extern dmr::CalDMR calDMR; extern p25::CalP25 calP25; extern nxdn::CalNXDN calNXDN; extern CalRSSI calRSSI; -/** CW */ +/* CW */ extern CWIdTX cwIdTX; #endif // __GLOBALS_H__ diff --git a/IO.cpp b/IO.cpp index 1b8ea7a..291bc70 100644 --- a/IO.cpp +++ b/IO.cpp @@ -1,19 +1,15 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2015 Jim Mclaughlin, KI6ZUM -* Copyright (C) 2016 Colin Durbridge, G4EML -* Copyright (C) 2017-2022 Bryan Biedenkapp, N2PLL -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2015 Jim Mclaughlin, KI6ZUM + * Copyright (C) 2016 Colin Durbridge, G4EML + * Copyright (C) 2017-2022 Bryan Biedenkapp, N2PLL + * + */ #include "Globals.h" #include "IO.h" @@ -69,9 +65,8 @@ const uint16_t DC_OFFSET = 2048U; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the IO class. -/// +/* Initializes a new instance of the IO class. */ + IO::IO() : m_started(false), m_rxBuffer(RX_RINGBUFFER_SIZE), @@ -140,9 +135,8 @@ IO::IO() : selfTest(); } -/// -/// Starts air interface sampler. -/// +/* Starts air interface sampler. */ + void IO::start() { if (m_started) @@ -155,9 +149,8 @@ void IO::start() setMode(); } -/// -/// Process samples from air interface. -/// +/* Process samples from air interface. */ + void IO::process() { m_ledCount++; @@ -356,13 +349,8 @@ void IO::process() } } -/// -/// Write samples to air interface. -/// -/// -/// -/// -/// +/* Write samples to air interface. */ + void IO::write(DVM_STATE mode, q15_t* samples, uint16_t length, const uint8_t* control) { if (!m_started) @@ -409,19 +397,15 @@ void IO::write(DVM_STATE mode, q15_t* samples, uint16_t length, const uint8_t* c } } -/// -/// Helper to get how much space the transmit ring buffer has for samples. -/// -/// +/* Helper to get how much space the transmit ring buffer has for samples. */ + uint16_t IO::getSpace() const { return m_txBuffer.getSpace(); } -/// -/// -/// -/// +/* */ + void IO::setDecode(bool dcd) { if (dcd != m_dcd) @@ -430,18 +414,15 @@ void IO::setDecode(bool dcd) m_dcd = dcd; } -/// -/// -/// -/// +/* */ + void IO::setADCDetection(bool detect) { m_detect = detect; } -/// -/// Helper to set the modem air interface state. -/// +/* Helper to set the modem air interface state. */ + void IO::setMode() { DVM_STATE relativeState = m_modemState; @@ -458,9 +439,8 @@ void IO::setMode() setNXDNInt(relativeState == STATE_NXDN); } -/// -/// Helper to assert or deassert radio PTT. -/// +/* Helper to assert or deassert radio PTT. */ + void IO::setTransmit() { // Switch the transmitter on if needed @@ -474,19 +454,8 @@ void IO::setTransmit() } } -/// -/// Sets various air interface parameters. -/// -/// Flag indicating the Rx polarity should be inverted. -/// Flag indicating the Tx polarity should be inverted. -/// Flag indicating the PTT polarity should be inverted. -/// -/// -/// -/// -/// -/// -/// +/* Sets various air interface parameters. */ + void IO::setParameters(bool rxInvert, bool txInvert, bool pttInvert, uint8_t rxLevel, uint8_t cwIdTXLevel, uint8_t dmrTXLevel, uint8_t p25TXLevel, uint8_t nxdnTXLevel, uint16_t txDCOffset, uint16_t rxDCOffset) { @@ -513,10 +482,8 @@ void IO::setParameters(bool rxInvert, bool txInvert, bool pttInvert, uint8_t rxL } } -/// -/// Sets the software Rx sample level. -/// -/// +/* Sets the software Rx sample level. */ + void IO::setRXLevel(uint8_t rxLevel) { m_rxLevel = q15_t(rxLevel * 128); @@ -525,11 +492,8 @@ void IO::setRXLevel(uint8_t rxLevel) m_rxLevel = -m_rxLevel; } -/// -/// Helper to get the state of the ADC and DAC overflow flags. -/// -/// -/// +/* Helper to get the state of the ADC and DAC overflow flags. */ + void IO::getOverflow(bool& adcOverflow, bool& dacOverflow) { adcOverflow = m_adcOverflow > 0U; @@ -539,53 +503,43 @@ void IO::getOverflow(bool& adcOverflow, bool& dacOverflow) m_dacOverflow = 0U; } -/// -/// Flag indicating the TX ring buffer has overflowed. -/// -/// +/* Flag indicating the TX ring buffer has overflowed. */ + bool IO::hasTXOverflow() { return m_txBuffer.hasOverflowed(); } -/// -/// Flag indicating the RX ring buffer has overflowed. -/// -/// +/* Flag indicating the RX ring buffer has overflowed. */ + bool IO::hasRXOverflow() { return m_rxBuffer.hasOverflowed(); } -/// -/// Flag indicating the air interface is locked out from transmitting. -/// -/// +/* Flag indicating the air interface is locked out from transmitting. */ + bool IO::hasLockout() const { return m_lockout; } -/// -/// -/// +/* */ + void IO::resetWatchdog() { m_watchdog = 0U; } -/// -/// -/// -/// +/* */ + uint32_t IO::getWatchdog() { return m_watchdog; } -/// -/// -/// +/* */ + void IO::selfTest() { bool ledValue = false; diff --git a/IO.h b/IO.h index 53dcba4..a901ea3 100644 --- a/IO.h +++ b/IO.h @@ -1,17 +1,23 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2017-2022 Bryan Biedenkapp, N2PLL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2017-2022 Bryan Biedenkapp, N2PLL -* -*/ + * @file IO.h + * @ingroup modem_fw + * @file IO.cpp + * @ingroup modem_fw + * @file IODue.cpp + * @ingroup modem_fw + * @file IOSTM.cpp + * @ingroup modem_fw + */ #if !defined(__IO_H__) #define __IO_H__ @@ -22,88 +28,178 @@ // --------------------------------------------------------------------------- // Class Declaration -// Implements the input/output data path with the radio air interface. // --------------------------------------------------------------------------- +/** + * @brief Implements the input/output data path with the radio air interface. + * @ingroup modem_fw + */ class DSP_FW_API IO { public: - /// Initializes a new instance of the IO class. + /** + * @brief Initializes a new instance of the IO class. + */ IO(); - /// Starts air interface sampler. + /** + * @brief Starts air interface sampler. + */ void start(); - /// Process samples from air interface. + /** + * @brief Process samples from air interface. + */ void process(); - /// Write samples to air interface. + /** + * @brief Write samples to air interface. + * @param mode + * @param samples Samples to write. + * @param length Length of samples buffer. + * @param control + */ void write(DVM_STATE mode, q15_t* samples, uint16_t length, const uint8_t* control = NULL); - /// Helper to get how much space the transmit ring buffer has for samples. + /** + * @brief Helper to get how much space the transmit ring buffer has for samples. + * @returns uint16_t Amount of space in the transmit ring buffer for samples. + */ uint16_t getSpace() const; - /// + /** + * @brief + * @param dcd + */ void setDecode(bool dcd); - /// + /** + * @brief + * @param detect + */ void setADCDetection(bool detect); - /// Helper to set the modem air interface state. + /** + * @brief Helper to set the modem air interface state. + */ void setMode(); - /// Helper to assert or deassert radio PTT. + /** + * @brief Helper to assert or deassert radio PTT. + */ void setTransmit(); - /// Hardware interrupt handler. + /** + * @brief Hardware interrupt handler. + */ void interrupt(); - /// Sets various air interface parameters. + /** + * @brief Sets various air interface parameters. + * @param rxInvert Flag indicating the Rx polarity should be inverted. + * @param txInvert Flag indicating the Tx polarity should be inverted. + * @param pttInvert Flag indicating the PTT polarity should be inverted. + * @param rxLevel Rx Level. + * @param cwIdTXLevel CWID Transmit Level. + * @param dmrTXLevel DMR Transmit Level. + * @param p25TXLevel P25 Transmit Level. + * @param nxdnTXLevel NXDN Transmit Level. + * @param txDCOffset Tx DC offset parameter. + * @param rxDCOffset Rx DC offset parameter. + */ void setParameters(bool rxInvert, bool txInvert, bool pttInvert, uint8_t rxLevel, uint8_t cwIdTXLevel, uint8_t dmrTXLevel, uint8_t p25TXLevel, uint8_t nxdnTXLevel, uint16_t txDCOffset, uint16_t rxDCOffset); - /// Sets the software Rx sample level. + /** + * @brief Sets the software Rx sample level. + * @param rxLevel Rx Level. + */ void setRXLevel(uint8_t rxLevel); - /// Helper to get the state of the ADC and DAC overflow flags. + /** + * @brief Helper to get the state of the ADC and DAC overflow flags. + * @param[out] adcOverflow + * @param[out] dacOverflow + */ void getOverflow(bool& adcOverflow, bool& dacOverflow); - /// Flag indicating the TX ring buffer has overflowed. + /** + * @brief Flag indicating the TX ring buffer has overflowed. + * @returns bool Flag indicating the TX ring buffer has overflowed. + */ bool hasTXOverflow(); - /// Flag indicating the RX ring buffer has overflowed. + /** + * @brief Flag indicating the RX ring buffer has overflowed. + * @returns bool Flag indicating the RX ring buffer has overflowed. + */ bool hasRXOverflow(); - /// Flag indicating the air interface is locked out from transmitting. + /** + * @brief Flag indicating the air interface is locked out from transmitting. + * @returns bool Flag indicating the air interface is locked out from transmitting. + */ bool hasLockout() const; - /// + /** + * @brief + */ void resetWatchdog(); - /// + /** + * @brief + * @returns uint32_t + */ uint32_t getWatchdog(); - /// Gets the CPU type the firmware is running on. + /** + * @brief Gets the CPU type the firmware is running on. + * @returns uint8_t + */ uint8_t getCPU() const; - /// Gets the unique identifier for the air interface. + /** + * @brief Gets the unique identifier for the air interface. + * @param buffer + */ void getUDID(uint8_t* buffer); - /// + /** + * @brief + */ void selfTest(); #if SPI_ENABLED - /// + /** + * @brief + * @param bytes + * @param length + */ void SPI_Write(uint8_t* bytes, uint8_t length); - /// + /** + * @brief + * @returns uint16_t + */ uint16_t SPI_Read(); #endif #if DIGIPOT_ENABLED - /// + /** + * @brief + * @param value + */ void SetDigipot(uint8_t value); - /// + /** + * @brief + * @param value + */ void SetTxDigipot(uint8_t value); - /// + /** + * @brief + * @param value + */ void SetRxDigipot(uint8_t value); - /// + /** + * @brief + * @param value + */ void SetRsDigipot(uint8_t value); #endif @@ -160,36 +256,74 @@ class DSP_FW_API IO { bool m_lockout; // Hardware specific routines - /// Initializes hardware interrupts. + /** + * @brief Initializes hardware interrupts. + */ void initInt(); - /// Starts hardware interrupts. + /** + * @brief Starts hardware interrupts. + */ void startInt(); - /// + /** + * @brief + */ bool getCOSInt(); - /// + /** + * @brief + * @param on + */ void setLEDInt(bool on); - /// + /** + * @brief + * @param on + */ void setPTTInt(bool on); - /// + /** + * @brief + * @param on + */ void setCOSInt(bool on); - /// + /** + * @brief + * @param on + */ void setDMRInt(bool on); - /// + /** + * @brief + * @param on + */ void setP25Int(bool on); - /// + /** + * @brief + * @param on + */ void setNXDNInt(bool on); - /// + /** + * @brief + * @param dly + */ void delayInt(unsigned int dly); - /// + /** + * @brief + * @param arg + * @returns void* + */ static void* txThreadHelper(void* arg); - /// + /** + * @brief + * @param interruptRx + */ void interruptRx(); - /// + /** + * @brief + * @param arg + * @returns void* + */ static void* rxThreadHelper(void* arg); }; diff --git a/IODue.cpp b/IODue.cpp index 88637d7..8d72178 100644 --- a/IODue.cpp +++ b/IODue.cpp @@ -1,19 +1,15 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2015 Jim Mclaughlin, KI6ZUM -* Copyright (C) 2016 Colin Durbridge, G4EML -* Copyright (C) 2017-2018 Bryan Biedenkapp, N2PLL -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2015 Jim Mclaughlin, KI6ZUM + * Copyright (C) 2016 Colin Durbridge, G4EML + * Copyright (C) 2017-2018 Bryan Biedenkapp, N2PLL + * + */ #include "Globals.h" #include "IO.h" @@ -62,19 +58,15 @@ const uint16_t DC_OFFSET = 2048U; // --------------------------------------------------------------------------- extern "C" { - void ADC_Handler() - { - io.interrupt(); - } + void ADC_Handler() { io.interrupt(); } } // --------------------------------------------------------------------------- // Public Class Members // --------------------------------------------------------------------------- -/// -/// Hardware interrupt handler. -/// +/* Hardware interrupt handler. */ + void IO::interrupt() { if ((ADC->ADC_ISR & ADC_ISR_EOC_Chan) == ADC_ISR_EOC_Chan) { // Ensure there was an End-of-Conversion and we read the ISR reg @@ -95,22 +87,17 @@ void IO::interrupt() } } -/// -/// Gets the CPU type the firmware is running on. -/// -/// +/* Gets the CPU type the firmware is running on. */ + uint8_t IO::getCPU() const { return CPU_TYPE_ARDUINO_DUE; } -/// -/// Gets the unique identifier for the air interface. -/// -/// -/// Code taken from https://github.com/emagii/at91sam3s/blob/master/examples/eefc_uniqueid/main.c -/// -/// +/* Gets the unique identifier for the air interface. + * Code taken from https://github.com/emagii/at91sam3s/blob/master/examples/eefc_uniqueid/main.c + */ + void IO::getUDID(uint8_t* buffer) { uint32_t status; @@ -137,9 +124,8 @@ void IO::getUDID(uint8_t* buffer) // Private Class Members // --------------------------------------------------------------------------- -/// -/// Initializes hardware interrupts. -/// +/* Initializes hardware interrupts. */ + void IO::initInt() { // Set up the TX, COS and LED pins @@ -153,9 +139,8 @@ void IO::initInt() pinMode(PIN_P25, OUTPUT); } -/// -/// Starts hardware interrupts. -/// +/* Starts hardware interrupts. */ + void IO::startInt() { if (ADC->ADC_ISR & ADC_ISR_EOC_Chan) // Ensure there was an End-of-Conversion and we read the ISR reg @@ -222,79 +207,78 @@ void IO::startInt() digitalWrite(PIN_LED, HIGH); } -/// -/// +/* */ + bool IO::getCOSInt() { return digitalRead(PIN_COS) == HIGH; } -/// -/// +/* */ + void IO::setLEDInt(bool on) { digitalWrite(PIN_LED, on ? HIGH : LOW); } -/// -/// +/* */ + void IO::setPTTInt(bool on) { digitalWrite(PIN_PTT, on ? HIGH : LOW); } -/// -/// +/* */ + void IO::setCOSInt(bool on) { digitalWrite(PIN_COSLED, on ? HIGH : LOW); } -/// -/// +/* */ + void IO::setDMRInt(bool on) { digitalWrite(PIN_DMR, on ? HIGH : LOW); } -/// -/// +/* */ + void IO::setP25Int(bool on) { digitalWrite(PIN_P25, on ? HIGH : LOW); } -/// -/// +/* */ + void IO::setNXDNInt(bool on) { /* stub */ } -/// -/// +/* */ + void IO::delayInt(unsigned int dly) { delay(dly); } -/// -/// -/// +/* */ + void* IO::txThreadHelper(void* arg) { return NULL; } -/// +/* */ + void IO::interruptRx() { /* stub */ } -/// -/// -/// +/* */ + void* IO::rxThreadHelper(void* arg) { return NULL; diff --git a/IOSTM.cpp b/IOSTM.cpp index 2885c9f..816ef1c 100644 --- a/IOSTM.cpp +++ b/IOSTM.cpp @@ -1,20 +1,16 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2016 Jim McLaughlin, KI6ZUM -* Copyright (C) 2016,2017,2018 Andy Uribe, CA6JAU -* Copyright (C) 2017,2018 Jonathan Naylor, G4KLX -* Copyright (C) 2017-2018 Bryan Biedenkapp, N2PLL -* Copyright (C) 2022 Natalie Moore -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2016 Jim McLaughlin, KI6ZUM + * Copyright (C) 2016,2017,2018 Andy Uribe, CA6JAU + * Copyright (C) 2017,2018 Jonathan Naylor, G4KLX + * Copyright (C) 2017-2018 Bryan Biedenkapp, N2PLL + * Copyright (C) 2022 Natalie Moore + * + */ #include "Globals.h" #include "IO.h" @@ -369,9 +365,8 @@ extern "C" { // Public Class Members // --------------------------------------------------------------------------- -/// -/// Hardware interrupt handler. -/// +/* Hardware interrupt handler. */ + void IO::interrupt() { uint8_t control = MARK_NONE; @@ -405,29 +400,23 @@ void IO::interrupt() m_watchdog++; } -/// -/// Gets the CPU type the firmware is running on. -/// -/// +/* Gets the CPU type the firmware is running on. */ + uint8_t IO::getCPU() const { return CPU_TYPE_STM32; } -/// -/// Gets the unique identifier for the air interface. -/// -/// +/* Gets the unique identifier for the air interface. */ + void IO::getUDID(uint8_t* buffer) { ::memcpy(buffer, (void*)STM32_UUID, 12U); } #if SPI_ENABLED -/// -/// Sends a byte over SPI -/// -/// +/* Sends a byte over SPI */ + void IO::SPI_Write(uint8_t* bytes, uint8_t length) { // Write the first byte @@ -445,10 +434,8 @@ void IO::SPI_Write(uint8_t* bytes, uint8_t length) while (SPI_I2S_GetFlagStatus(SPI_PERIPH, SPI_I2S_FLAG_BSY) == SET); } -/// -/// Receives a byte from SPI -/// -/// the received byte +/* Receives a byte from SPI */ + uint16_t IO::SPI_Read() { //while (SPI_I2S_GetFlagStatus(SPI_PERIPH, SPI_I2S_FLAG_RXNE) == RESET); @@ -460,10 +447,8 @@ uint16_t IO::SPI_Read() #endif #if DIGIPOT_ENABLED -/// -/// Sends the digipot set value command over SPI (chip select must be set first) -/// -/// +/* Sends the digipot set value command over SPI (chip select must be set first) */ + void IO::SetDigipot(uint8_t value) { uint8_t bytes[2]; @@ -472,10 +457,8 @@ void IO::SetDigipot(uint8_t value) SPI_Write(bytes, 2); } -/// -/// -/// -/// +/* */ + void IO::SetTxDigipot(uint8_t value) { // Set CS for TX pot to low @@ -484,10 +467,8 @@ void IO::SetTxDigipot(uint8_t value) GPIO_WriteBit(PORT_CS_TXPOT, PIN_CS_TXPOT, Bit_SET); } -/// -/// -/// -/// +/* */ + void IO::SetRxDigipot(uint8_t value) { // Set CS for RX pot to low @@ -496,10 +477,8 @@ void IO::SetRxDigipot(uint8_t value) GPIO_WriteBit(PORT_CS_RXPOT, PIN_CS_RXPOT, Bit_SET); } -/// -/// -/// -/// +/* */ + void IO::SetRsDigipot(uint8_t value) { // Set CS for TX pot to low @@ -514,9 +493,8 @@ void IO::SetRsDigipot(uint8_t value) // Private Class Members // --------------------------------------------------------------------------- -/// -/// Initializes hardware interrupts. -/// +/* Initializes hardware interrupts. */ + void IO::initInt() { GPIO_InitTypeDef GPIO_InitStruct; @@ -616,9 +594,8 @@ void IO::initInt() #endif } -/// -/// Starts hardware interrupts. -/// +/* Starts hardware interrupts. */ + void IO::startInt() { if ((ADC_GetFlagStatus(ADC1, ADC_FLAG_EOC) != RESET)) @@ -778,97 +755,92 @@ void IO::startInt() GPIO_SetBits(PORT_LED, PIN_LED); } -/// -/// +/* */ + bool IO::getCOSInt() { return GPIO_ReadInputDataBit(PORT_COS, PIN_COS) == Bit_SET; } -/// -/// +/* */ + void IO::setLEDInt(bool on) { GPIO_WriteBit(PORT_LED, PIN_LED, on ? Bit_SET : Bit_RESET); } -/// -/// +/* */ + void IO::setPTTInt(bool on) { GPIO_WriteBit(PORT_PTT, PIN_PTT, on ? Bit_SET : Bit_RESET); } -/// -/// +/* */ + void IO::setCOSInt(bool on) { GPIO_WriteBit(PORT_COSLED, PIN_COSLED, on ? Bit_SET : Bit_RESET); } -/// -/// +/* */ + void IO::setDMRInt(bool on) { GPIO_WriteBit(PORT_DMR, PIN_DMR, on ? Bit_SET : Bit_RESET); } -/// -/// +/* */ + void IO::setP25Int(bool on) { GPIO_WriteBit(PORT_P25, PIN_P25, on ? Bit_SET : Bit_RESET); } -/// -/// +/* */ + void IO::setNXDNInt(bool on) { GPIO_WriteBit(PORT_NXDN, PIN_NXDN, on ? Bit_SET : Bit_RESET); } -/// -/// -/// Simple delay function for STM32 -/// Example from: http://thehackerworkshop.com/?p=1209 -/// -/// +/* */ + void IO::delayInt(unsigned int dly) { unsigned int loopsPerMillisecond = (SystemCoreClock / 1000) / 3; for (; dly > 0; dly--) { - asm volatile //this routine waits (approximately) one millisecond + asm volatile // this routine waits (approximately) one millisecond ( - "mov r3, %[loopsPerMillisecond] \n\t" //load the initial loop counter + "mov r3, %[loopsPerMillisecond] \n\t" // load the initial loop counter "loop: \n\t" "subs r3, #1 \n\t" "bne loop \n\t" - : //empty output list - : [loopsPerMillisecond] "r" (loopsPerMillisecond) //input to the asm routine - : "r3", "cc" //clobber list + : // empty output list + : [loopsPerMillisecond] "r" (loopsPerMillisecond) // input to the asm routine + : "r3", "cc" // clobber list ); } } -/// -/// -/// +/* */ + void* IO::txThreadHelper(void* arg) { return NULL; } -/// +/* */ + void IO::interruptRx() { /* stub */ } -/// -/// -/// +/* */ + void* IO::rxThreadHelper(void* arg) { return NULL; diff --git a/RSSIBuffer.cpp b/RSSIBuffer.cpp index 8e4eea6..60f1abf 100644 --- a/RSSIBuffer.cpp +++ b/RSSIBuffer.cpp @@ -1,27 +1,21 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016 Jonathan Naylor, G4KLX -* Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016 Jonathan Naylor, G4KLX + * Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM + * + */ #include "RSSIBuffer.h" // --------------------------------------------------------------------------- // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the RSSIBuffer class. -/// -/// +/* Initializes a new instance of the RSSIBuffer class. */ + RSSIBuffer::RSSIBuffer(uint16_t length) : m_length(length), m_rssi(NULL), @@ -33,10 +27,8 @@ RSSIBuffer::RSSIBuffer(uint16_t length) : m_rssi = new uint16_t[length]; } -/// -/// Helper to get how much space the ring buffer has for samples. -/// -/// +/* Helper to get how much space the ring buffer has for samples. */ + uint16_t RSSIBuffer::getSpace() const { uint16_t n = 0U; @@ -54,10 +46,8 @@ uint16_t RSSIBuffer::getSpace() const return n; } -/// -/// -/// -/// +/* */ + uint16_t RSSIBuffer::getData() const { if (m_tail == m_head) @@ -68,11 +58,8 @@ uint16_t RSSIBuffer::getData() const return m_length - m_tail + m_head; } -/// -/// -/// -/// -/// +/* */ + bool RSSIBuffer::put(uint16_t rssi) { if (m_full) { @@ -92,11 +79,8 @@ bool RSSIBuffer::put(uint16_t rssi) return true; } -/// -/// -/// -/// -/// +/* */ + bool RSSIBuffer::get(uint16_t& rssi) { if (m_head == m_tail && !m_full) @@ -113,10 +97,8 @@ bool RSSIBuffer::get(uint16_t& rssi) return true; } -/// -/// Flag indicating whether or not the ring buffer has overflowed. -/// -/// +/* Flag indicating whether or not the ring buffer has overflowed. */ + bool RSSIBuffer::hasOverflowed() { bool overflow = m_overflow; diff --git a/RSSIBuffer.h b/RSSIBuffer.h index 395c4b2..f0288b6 100644 --- a/RSSIBuffer.h +++ b/RSSIBuffer.h @@ -1,17 +1,19 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016 Jonathan Naylor, G4KLX + * Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016 Jonathan Naylor, G4KLX -* Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM -* -*/ + * @file RSSIBuffer.h + * @ingroup modem_fw + * @file RSSIBuffer.cpp + * @ingroup modem_fw + */ #if !defined(__RSSI_RB_H__) #define __RSSI_RB_H__ @@ -19,27 +21,50 @@ // --------------------------------------------------------------------------- // Class Declaration -// Implements a circular buffer for RSSI data. // --------------------------------------------------------------------------- +/** + * @brief Implements a circular buffer for RSSI data. + * @ingroup modem_fw + */ class DSP_FW_API RSSIBuffer { public: - /// Initializes a new instance of the RSSIBuffer class. + /** + * @brief Initializes a new instance of the RSSIBuffer class. + * @param length Length of buffer. + */ RSSIBuffer(uint16_t length); - /// Helper to get how much space the ring buffer has for samples. + /** + * @brief Helper to get how much space the ring buffer has for data. + * @returns uint16_t Amount of space remaining for data. + */ uint16_t getSpace() const; - /// + /** + * @brief + * @returns uint16_t + */ uint16_t getData() const; - /// + /** + * @brief + * @param rssi + * @returns bool + */ bool put(uint16_t rssi); - /// + /** + * @brief + * @param[out] rssi + * @returns bool + */ bool get(uint16_t& rssi); - /// Flag indicating whether or not the ring buffer has overflowed. + /** + * @brief Flag indicating whether or not the ring buffer has overflowed. + * @returns bool Flag indicating whether or not the ring buffer has overflowed. + */ bool hasOverflowed(); private: diff --git a/RingBuffer.h b/RingBuffer.h index 3aeee2f..49e0597 100644 --- a/RingBuffer.h +++ b/RingBuffer.h @@ -1,24 +1,24 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2017 Wojciech Krutnik, N0CALL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2017 Wojciech Krutnik, N0CALL -* -*/ + * @file RingBuffer.h + * @ingroup modem_fw + */ #if !defined(__RING_BUFFER_H__) #define __RING_BUFFER_H__ /* -* FIFO ring buffer source: -* http://stackoverflow.com/questions/6822548/correct-way-of-implementing-a-uart-receive-buffer-in-a-small-arm-microcontroller (modified) -* -*/ + * FIFO ring buffer source: + * http://stackoverflow.com/questions/6822548/correct-way-of-implementing-a-uart-receive-buffer-in-a-small-arm-microcontroller (modified) + * + */ #include "Defines.h" diff --git a/STM_UART.cpp b/STM_UART.cpp index eb4d42f..78428e1 100644 --- a/STM_UART.cpp +++ b/STM_UART.cpp @@ -1,17 +1,13 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (c) 2020 Jonathan Naylor, G4KLX -* Copyright (c) 2020 Geoffrey Merck, F4FXL - KC3FRA -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (c) 2020 Jonathan Naylor, G4KLX + * Copyright (c) 2020 Geoffrey Merck, F4FXL - KC3FRA + * + */ #if defined(STM32F4XX) #include "STM_UART.h" @@ -20,25 +16,30 @@ // Public Class Members // --------------------------------------------------------------------------- - /// - /// Initializes a new instance of the STM_UART class. - /// +/* Initializes a new instance of the STM_UART class. */ + STM_UART::STM_UART() : m_usart(NULL) { /* stub */ } -/// -/// +/* Initializes the UART. */ + void STM_UART::init(USART_TypeDef* usart) { m_usart = usart; } -/// -/// -/// +/* */ + +uint8_t STM_UART::read() +{ + return m_rxFifo.get(); +} + +/* */ + void STM_UART::write(const uint8_t* data, uint16_t length) { if (length == 0U || m_usart == NULL) @@ -46,23 +47,17 @@ void STM_UART::write(const uint8_t* data, uint16_t length) m_txFifo.put(data[0]); - USART_ITConfig(m_usart, USART_IT_TXE, ENABLE);//switch TX IRQ is on + USART_ITConfig(m_usart, USART_IT_TXE, ENABLE); // switch TX IRQ is on for (uint16_t i = 1U; i < length; i++) { m_txFifo.put(data[i]); } - USART_ITConfig(m_usart, USART_IT_TXE, ENABLE);//make sure TX IRQ is on + USART_ITConfig(m_usart, USART_IT_TXE, ENABLE); // make sure TX IRQ is on } -/// -/// -uint8_t STM_UART::read() -{ - return m_rxFifo.get(); -} +/* */ -/// void STM_UART::handleIRQ() { if (m_usart == NULL) @@ -85,12 +80,8 @@ void STM_UART::handleIRQ() } } -/// -/// Flushes the transmit shift register. -/// -/// -/// This call is blocking! -/// +/* Flushes the transmit shift register. */ + void STM_UART::flush() { if (m_usart == NULL) @@ -101,15 +92,15 @@ void STM_UART::flush() ; } -/// -/// +/* */ + uint16_t STM_UART::available() { return m_rxFifo.isEmpty() ? 0U : 1U; } -/// -/// +/* */ + uint16_t STM_UART::availableForWrite() { return m_txFifo.isFull() ? 0U : 1U; diff --git a/STM_UART.h b/STM_UART.h index 364cf1f..7b58c29 100644 --- a/STM_UART.h +++ b/STM_UART.h @@ -1,17 +1,19 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (c) 2020 Jonathan Naylor, G4KLX + * Copyright (c) 2020 Geoffrey Merck, F4FXL - KC3FRA + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (c) 2020 Jonathan Naylor, G4KLX -* Copyright (c) 2020 Geoffrey Merck, F4FXL - KC3FRA -* -*/ + * @file STM_UART.h + * @ingroup modem_fw + * @file STM_UART.cpp + * @ingroup modem_fw + */ #if defined(STM32F4XX) #if !defined(__STM_UART_H__) #define __STM_UART_H__ @@ -27,12 +29,17 @@ const uint16_t BUFFER_MASK = BUFFER_SIZE - 1; // --------------------------------------------------------------------------- // Class Declaration -// This class represents a FIFO buffer on a STM32 UART. // --------------------------------------------------------------------------- +/** + * @brief This class represents a FIFO buffer on a STM32 UART. + * @ingroup modem_fw + */ class DSP_FW_API STM_UARTFIFO { public: - /// Initializes a new instance of the STM_UARTFIFO class. + /** + * @brief Initializes a new instance of the STM_UARTFIFO class. + */ STM_UARTFIFO() : m_head(0U), m_tail(0U) @@ -40,32 +47,42 @@ class DSP_FW_API STM_UARTFIFO { /* stub */ } - /// + /** + * @brief + */ uint8_t get() { return m_buffer[BUFFER_MASK & (m_tail++)]; } - /// + /** + * @brief + */ void put(uint8_t data) { m_buffer[BUFFER_MASK & (m_head++)] = data; } - /// Helper to reset data values to defaults. + /** + * @brief Helper to reset data values to defaults. + */ void reset() { m_tail = 0U; m_head = 0U; } - /// + /** + * @brief + */ bool isEmpty() { return m_tail == m_head; } - /// + /** + * @brief + */ bool isFull() { return ((m_head + 1U) & BUFFER_MASK) == (m_tail & BUFFER_MASK); @@ -79,32 +96,59 @@ class DSP_FW_API STM_UARTFIFO { // --------------------------------------------------------------------------- // Class Declaration -// This class represents an STM32 UART. // --------------------------------------------------------------------------- +/** + * @brief This class represents an STM32 UART. + * @ingroup modem_fw + */ class STM_UART { public: - /// Initializes a new instance of the STM_UART class. + /** + * @brief Initializes a new instance of the STM_UART class. + */ STM_UART(); - /// + /** + * @brief Initializes the UART. + * @param usart + */ void init(USART_TypeDef* usart); - /// + /** + * @brief + * @returns uint8_t + */ uint8_t read(); - /// + /** + * @brief + * @param[in] data + * @param length + */ void write(const uint8_t* data, uint16_t length); - /// + /** + * @brief + */ void handleIRQ(); - /// Flushes the transmit shift register. + /** + * @brief Flushes the transmit shift register. + * + * This call is blocking! + */ void flush(); - /// + /** + * @brief + * @returns uint16_t + */ uint16_t available(); - /// + /** + * @brief + * @returns uint16_t + */ uint16_t availableForWrite(); private: diff --git a/SampleBuffer.cpp b/SampleBuffer.cpp index a5d8319..960b682 100644 --- a/SampleBuffer.cpp +++ b/SampleBuffer.cpp @@ -1,27 +1,21 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016 Jonathan Naylor, G4KLX -* Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016 Jonathan Naylor, G4KLX + * Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM + * + */ #include "SampleBuffer.h" // --------------------------------------------------------------------------- // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the SampleBuffer class. -/// -/// +/* Initializes a new instance of the SampleBuffer class. */ + SampleBuffer::SampleBuffer(uint16_t length) : m_length(length), m_samples(NULL), @@ -35,10 +29,8 @@ SampleBuffer::SampleBuffer(uint16_t length) : m_control = new uint8_t[length]; } -/// -/// Helper to get how much space the ring buffer has for samples. -/// -/// +/* Helper to get how much space the ring buffer has for samples. */ + uint16_t SampleBuffer::getSpace() const { uint16_t n = 0U; @@ -56,10 +48,8 @@ uint16_t SampleBuffer::getSpace() const return n; } -/// -/// -/// -/// +/* */ + uint16_t SampleBuffer::getData() const { if (m_tail == m_head) @@ -70,12 +60,8 @@ uint16_t SampleBuffer::getData() const return m_length - m_tail + m_head; } -/// -/// -/// -/// -/// -/// +/* */ + bool SampleBuffer::put(uint16_t sample, uint8_t control) { if (m_full) { @@ -96,12 +82,8 @@ bool SampleBuffer::put(uint16_t sample, uint8_t control) return true; } -/// -/// -/// -/// -/// -/// +/* */ + bool SampleBuffer::get(uint16_t& sample, uint8_t& control) { if (m_head == m_tail && !m_full) @@ -119,10 +101,8 @@ bool SampleBuffer::get(uint16_t& sample, uint8_t& control) return true; } -/// -/// Flag indicating whether or not the ring buffer has overflowed. -/// -/// +/* Flag indicating whether or not the ring buffer has overflowed. */ + bool SampleBuffer::hasOverflowed() { bool overflow = m_overflow; diff --git a/SampleBuffer.h b/SampleBuffer.h index 1c92c5b..cc96f17 100644 --- a/SampleBuffer.h +++ b/SampleBuffer.h @@ -1,17 +1,19 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016 Jonathan Naylor, G4KLX + * Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016 Jonathan Naylor, G4KLX -* Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM -* -*/ + * @file SampleBuffer.h + * @ingroup modem_fw + * @file SampleBuffer.cpp + * @ingroup modem_fw + */ #if !defined(__SAMPLE_RB_H__) #define __SAMPLE_RB_H__ @@ -19,27 +21,52 @@ // --------------------------------------------------------------------------- // Class Declaration -// Implements a circular buffer for sample data. // --------------------------------------------------------------------------- +/** + * @brief Implements a circular ring buffer for sample data. + * @ingroup modem_fw + */ class DSP_FW_API SampleBuffer { public: - /// Initializes a new instance of the SampleBuffer class. + /** + * @brief Initializes a new instance of the SampleBuffer class. + * @param length Length of buffer. + */ SampleBuffer(uint16_t length); - /// Helper to get how much space the ring buffer has for samples. + /** + * @brief Helper to get how much space the ring buffer has for samples. + * @returns uint16_t Amount of space remaining for samples. + */ uint16_t getSpace() const; - /// + /** + * @brief + * @returns uint16_t + */ uint16_t getData() const; - /// + /** + * @brief + * @param sample + * @param control + * @returns bool + */ bool put(uint16_t sample, uint8_t control); - /// + /** + * @brief + * @param[out] sample + * @param[out] control + * @returns bool + */ bool get(uint16_t& sample, uint8_t& control); - /// Flag indicating whether or not the ring buffer has overflowed. + /** + * @brief Flag indicating whether or not the ring buffer has overflowed. + * @returns bool Flag indicating whether or not the ring buffer has overflowed. + */ bool hasOverflowed(); private: diff --git a/SerialBuffer.cpp b/SerialBuffer.cpp index e9e8d43..3542bab 100644 --- a/SerialBuffer.cpp +++ b/SerialBuffer.cpp @@ -1,26 +1,21 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016 Jonathan Naylor, G4KLX -* Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016 Jonathan Naylor, G4KLX + * Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM + * + */ #include "SerialBuffer.h" // --------------------------------------------------------------------------- // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the SerialBuffer class. -/// +/* Initializes a new instance of the SerialBuffer class. */ + SerialBuffer::SerialBuffer(uint16_t length) : m_length(length), m_buffer(NULL), @@ -31,18 +26,15 @@ SerialBuffer::SerialBuffer(uint16_t length) : m_buffer = new uint8_t[length]; } -/// -/// Finalizes a instance of the SerialBuffer class. -/// +/* Finalizes a instance of the SerialBuffer class. */ + SerialBuffer::~SerialBuffer() { delete[] m_buffer; } -/// -/// Helper to get how much space the ring buffer has for samples. -/// -/// +/* Helper to get how much space the ring buffer has for data. */ + uint16_t SerialBuffer::getSpace() const { uint16_t n = 0U; @@ -60,10 +52,8 @@ uint16_t SerialBuffer::getSpace() const return n; } -/// -/// -/// -/// +/* */ + uint16_t SerialBuffer::getData() const { if (m_tail == m_head) @@ -74,9 +64,8 @@ uint16_t SerialBuffer::getData() const return m_length - m_tail + m_head; } -/// -/// Helper to reset data values to defaults. -/// +/* Helper to reset data values to defaults. */ + void SerialBuffer::reset() { m_head = 0U; @@ -84,9 +73,8 @@ void SerialBuffer::reset() m_full = false; } -/// -/// Helper to reset and reinitialize data values to defaults. -/// +/* Helper to reset and reinitialize data values to defaults. */ + void SerialBuffer::reinitialize(uint16_t length) { reset(); @@ -97,11 +85,8 @@ void SerialBuffer::reinitialize(uint16_t length) m_buffer = new uint8_t[length]; } -/// -/// -/// -/// -/// +/* */ + bool SerialBuffer::put(uint8_t c) { if (m_full) @@ -119,19 +104,15 @@ bool SerialBuffer::put(uint8_t c) return true; } -/// -/// -/// -/// +/* */ + uint8_t SerialBuffer::peek() const { return m_buffer[m_tail]; } -/// -/// -/// -/// +/* */ + uint8_t SerialBuffer::get() { uint8_t value = m_buffer[m_tail]; diff --git a/SerialBuffer.h b/SerialBuffer.h index d4212b1..8a992f5 100644 --- a/SerialBuffer.h +++ b/SerialBuffer.h @@ -1,17 +1,23 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * @package DVM / Modem Firmware + * @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) + * @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) + * + * Copyright (C) 2015,2016 Jonathan Naylor, G4KLX + * Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016 Jonathan Naylor, G4KLX -* Serial FIFO Control Copyright (C) 2015 by James McLaughlin, KI6ZUM -* -*/ + * @file SerialBuffer.h + * @ingroup modem_fw + * @file SerialBuffer.cpp + * @ingroup modem_fw + */ #if !defined(__SERIAL_RB_H__) #define __SERIAL_RB_H__ @@ -25,34 +31,63 @@ const uint16_t SERIAL_RINGBUFFER_SIZE = 396U; // --------------------------------------------------------------------------- // Class Declaration -// Implements a circular buffer for serial data. // --------------------------------------------------------------------------- +/** + * @brief Implements a circular ring buffer for serial data. + * @ingroup modem_fw + */ class DSP_FW_API SerialBuffer { public: - /// Initializes a new instance of the SerialBuffer class. + /** + * @brief Initializes a new instance of the SerialBuffer class. + * @param length Length of buffer. + */ SerialBuffer(uint16_t length = SERIAL_RINGBUFFER_SIZE); - /// Finalizes a instance of the SerialBuffer class. + /** + * @brief Finalizes a instance of the SerialBuffer class. + */ ~SerialBuffer(); - /// Helper to get how much space the ring buffer has for samples. + /** + * @brief Helper to get how much space the ring buffer has for data. + * @returns uint16_t Amount of space remaining for data. + */ uint16_t getSpace() const; - /// + /** + * @brief + * @returns uint16_t + */ uint16_t getData() const; - /// Helper to reset data values to defaults. + /** + * @brief Helper to reset data values to defaults. + */ void reset(); - /// Helper to reset and reinitialize data values to defaults. + /** + * @brief Helper to reset and reinitialize data values to defaults. + * @param length Length of buffer. + */ void reinitialize(uint16_t length); - /// + /** + * @brief + * @param c + * @returns bool + */ bool put(uint8_t c); - /// + /** + * @brief + * @returns uint8_t + */ uint8_t peek() const; - /// + /** + * @brief + * @returns uint8_t + */ uint8_t get(); private: diff --git a/SerialDue.cpp b/SerialDue.cpp index 8a18ba9..5dbd721 100644 --- a/SerialDue.cpp +++ b/SerialDue.cpp @@ -1,17 +1,13 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2018,2022 Bryan Biedenkapp, N2PLL -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2018,2022 Bryan Biedenkapp, N2PLL + * + */ #include "Globals.h" #include "SerialPort.h" @@ -20,9 +16,8 @@ // --------------------------------------------------------------------------- #if (defined(__SAM3X8E__) || defined(__MK20DX256__) || defined(__MK64FX512__) || defined(__MK66FX1M0__)) && defined(ARDUINO_SAM_DUE) -/// -/// -/// +/* Reads data from the modem flash parititon. */ + void SerialPort::flashRead() { DEBUG1("SerialPort: flashRead(): unsupported on Arduino Due"); @@ -30,11 +25,8 @@ void SerialPort::flashRead() // unused on Arduino Due based dedicated modems } -/// -/// -/// -/// -/// +/* Writes data to the modem flash partition. */ + uint8_t SerialPort::flashWrite(const uint8_t* data, uint8_t length) { DEBUG1("SerialPort: flashWrite(): unsupported on Arduino Due"); @@ -42,11 +34,8 @@ uint8_t SerialPort::flashWrite(const uint8_t* data, uint8_t length) return RSN_NO_INTERNAL_FLASH; } -/// -/// -/// -/// -/// +/* */ + void SerialPort::beginInt(uint8_t n, int speed) { switch (n) { @@ -64,11 +53,8 @@ void SerialPort::beginInt(uint8_t n, int speed) } } -/// -/// -/// -/// -/// +/* */ + int SerialPort::availableInt(uint8_t n) { switch (n) { @@ -83,11 +69,8 @@ int SerialPort::availableInt(uint8_t n) } } -/// -/// -/// -/// -/// +/* */ + int SerialPort::availableForWriteInt(uint8_t n) { switch (n) { @@ -102,11 +85,8 @@ int SerialPort::availableForWriteInt(uint8_t n) } } -/// -/// -/// -/// -/// +/* */ + uint8_t SerialPort::readInt(uint8_t n) { switch (n) { @@ -121,13 +101,8 @@ uint8_t SerialPort::readInt(uint8_t n) } } -/// -/// -/// -/// -/// -/// -/// +/* */ + void SerialPort::writeInt(uint8_t n, const uint8_t* data, uint16_t length, bool flush) { switch (n) { diff --git a/SerialPort.cpp b/SerialPort.cpp index fbebb8f..4b766f6 100644 --- a/SerialPort.cpp +++ b/SerialPort.cpp @@ -1,18 +1,14 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2013,2015,2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2016 Colin Durbridge, G4EML -* Copyright (C) 2017-2024 Bryan Biedenkapp, N2PLL -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2013,2015,2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2016 Colin Durbridge, G4EML + * Copyright (C) 2017-2024 Bryan Biedenkapp, N2PLL + * + */ #include "Globals.h" #include "SerialPort.h" @@ -29,9 +25,8 @@ const uint8_t PROTOCOL_VERSION = 4U; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the SerialPort class. -/// +/* Initializes a new instance of the SerialPort class. */ + SerialPort::SerialPort() : m_buffer(), m_ptr(0U), @@ -43,17 +38,15 @@ SerialPort::SerialPort() : // stub } -/// -/// Starts serial port communications. -/// +/* Starts serial port communications. */ + void SerialPort::start() { beginInt(1U, SERIAL_SPEED); } -/// -/// Process data from serial port. -/// +/* Process data from serial port. */ + void SerialPort::process() { while (availableInt(1U)) { @@ -377,11 +370,8 @@ void SerialPort::process() } } -/// -/// Helper to check if the modem is in a calibration state. -/// -/// -/// +/* Helper to check if the modem is in a calibration state. */ + bool SerialPort::isCalState(DVM_STATE state) { // calibration mode check @@ -396,11 +386,8 @@ bool SerialPort::isCalState(DVM_STATE state) return false; } -/// -/// Helper to determine digital mode if the modem is in a calibration state. -/// -/// -/// +/* Helper to determine digital mode if the modem is in a calibration state. */ + DVM_STATE SerialPort::calRelativeState(DVM_STATE state) { if (isCalState(state)) { @@ -419,12 +406,8 @@ DVM_STATE SerialPort::calRelativeState(DVM_STATE state) return STATE_CW; } -/// -/// Write DMR frame data to serial port. -/// -/// -/// -/// +/* Write DMR frame data to serial port. */ + void SerialPort::writeDMRData(bool slot, const uint8_t* data, uint8_t length) { if (m_modemState != STATE_DMR && m_modemState != STATE_IDLE) @@ -451,10 +434,8 @@ void SerialPort::writeDMRData(bool slot, const uint8_t* data, uint8_t length) writeInt(1U, reply, length + 3U); } -/// -/// Write lost DMR frame data to serial port. -/// -/// +/* Write lost DMR frame data to serial port. */ + void SerialPort::writeDMRLost(bool slot) { if (m_modemState != STATE_DMR && m_modemState != STATE_IDLE) @@ -472,11 +453,8 @@ void SerialPort::writeDMRLost(bool slot) writeInt(1U, reply, 3); } -/// -/// Write P25 frame data to serial port. -/// -/// -/// +/* Write P25 frame data to serial port. */ + void SerialPort::writeP25Data(const uint8_t* data, uint16_t length) { if (m_modemState != STATE_P25 && m_modemState != STATE_IDLE) @@ -514,9 +492,8 @@ void SerialPort::writeP25Data(const uint8_t* data, uint16_t length) } } -/// -/// Write lost P25 frame data to serial port. -/// +/* Write lost P25 frame data to serial port. */ + void SerialPort::writeP25Lost() { if (m_modemState != STATE_P25 && m_modemState != STATE_IDLE) @@ -534,11 +511,8 @@ void SerialPort::writeP25Lost() writeInt(1U, reply, 3); } -/// -/// Write NXDN frame data to serial port. -/// -/// -/// +/* Write NXDN frame data to serial port. */ + void SerialPort::writeNXDNData(const uint8_t* data, uint8_t length) { if (m_modemState != STATE_NXDN && m_modemState != STATE_IDLE) @@ -565,9 +539,8 @@ void SerialPort::writeNXDNData(const uint8_t* data, uint8_t length) writeInt(1U, reply, length + 3U); } -/// -/// Write lost NXDN frame data to serial port. -/// +/* Write lost NXDN frame data to serial port. */ + void SerialPort::writeNXDNLost() { if (m_modemState != STATE_NXDN && m_modemState != STATE_IDLE) @@ -585,11 +558,8 @@ void SerialPort::writeNXDNLost() writeInt(1U, reply, 3); } -/// -/// Write calibration frame data to serial port. -/// -/// -/// +/* Write calibration frame data to serial port. */ + void SerialPort::writeCalData(const uint8_t* data, uint8_t length) { if (length + 3U > 130U) { @@ -610,11 +580,8 @@ void SerialPort::writeCalData(const uint8_t* data, uint8_t length) writeInt(1U, reply, length + 3U); } -/// -/// Write RSSI frame data to serial port. -/// -/// -/// +/* Write RSSI frame data to serial port. */ + void SerialPort::writeRSSIData(const uint8_t* data, uint8_t length) { if (m_modemState != STATE_RSSI_CAL) @@ -638,10 +605,8 @@ void SerialPort::writeRSSIData(const uint8_t* data, uint8_t length) writeInt(1U, reply, length + 3U); } -/// -/// -/// -/// +/* */ + void SerialPort::writeDebug(const char* text) { if (!m_debug) @@ -663,11 +628,8 @@ void SerialPort::writeDebug(const char* text) writeInt(1U, reply, count, true); } -/// -/// -/// -/// -/// +/* */ + void SerialPort::writeDebug(const char* text, int16_t n1) { if (!m_debug) @@ -692,12 +654,8 @@ void SerialPort::writeDebug(const char* text, int16_t n1) writeInt(1U, reply, count, true); } -/// -/// -/// -/// -/// -/// +/* */ + void SerialPort::writeDebug(const char* text, int16_t n1, int16_t n2) { if (!m_debug) @@ -725,13 +683,8 @@ void SerialPort::writeDebug(const char* text, int16_t n1, int16_t n2) writeInt(1U, reply, count, true); } -/// -/// -/// -/// -/// -/// -/// +/* */ + void SerialPort::writeDebug(const char* text, int16_t n1, int16_t n2, int16_t n3) { if (!m_debug) @@ -762,14 +715,8 @@ void SerialPort::writeDebug(const char* text, int16_t n1, int16_t n2, int16_t n3 writeInt(1U, reply, count, true); } -/// -/// -/// -/// -/// -/// -/// -/// +/* */ + void SerialPort::writeDebug(const char* text, int16_t n1, int16_t n2, int16_t n3, int16_t n4) { if (!m_debug) @@ -803,11 +750,8 @@ void SerialPort::writeDebug(const char* text, int16_t n1, int16_t n2, int16_t n3 writeInt(1U, reply, count, true); } -/// -/// -/// -/// -/// +/* */ + void SerialPort::writeDump(const uint8_t* data, uint16_t length) { if (!m_debug) @@ -849,9 +793,8 @@ void SerialPort::writeDump(const uint8_t* data, uint16_t length) // Private Class Members // --------------------------------------------------------------------------- -/// -/// Write acknowlegement. -/// +/* Write acknowlegement. */ + void SerialPort::sendACK() { uint8_t reply[4U]; @@ -864,10 +807,8 @@ void SerialPort::sendACK() writeInt(1U, reply, 4); } -/// -/// Write negative acknowlegement. -/// -/// +/* Write negative acknowlegement. */ + void SerialPort::sendNAK(uint8_t err) { uint8_t reply[5U]; @@ -881,9 +822,8 @@ void SerialPort::sendNAK(uint8_t err) writeInt(1U, reply, 5); } -/// -/// Write modem DSP status. -/// +/* Write modem DSP status. */ + void SerialPort::getStatus() { io.resetWatchdog(); @@ -960,9 +900,8 @@ void SerialPort::getStatus() writeInt(1U, reply, 12); } -/// -/// Write modem DSP version. -/// +/* Write modem DSP version. */ + void SerialPort::getVersion() { uint8_t reply[200U]; @@ -988,11 +927,8 @@ void SerialPort::getVersion() writeInt(1U, reply, count); } -/// -/// Helper to validate the passed modem state is valid. -/// -/// -/// +/* Helper to validate the passed modem state is valid. */ + uint8_t SerialPort::modemStateCheck(DVM_STATE state) { // invalid mode check @@ -1018,12 +954,8 @@ uint8_t SerialPort::modemStateCheck(DVM_STATE state) return RSN_OK; } -/// -/// Set modem DSP configuration from serial port data. -/// -/// -/// -/// +/* Set modem DSP configuration from serial port data. */ + uint8_t SerialPort::setConfig(const uint8_t* data, uint8_t length) { if (length < 21U) @@ -1126,12 +1058,8 @@ uint8_t SerialPort::setConfig(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Set modem DSP mode from serial port data. -/// -/// -/// -/// +/* Set modem DSP mode from serial port data. */ + uint8_t SerialPort::setMode(const uint8_t* data, uint8_t length) { if (length < 1U) @@ -1151,10 +1079,8 @@ uint8_t SerialPort::setMode(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Sets the modem state. -/// -/// +/* Sets the modem state. */ + void SerialPort::setMode(DVM_STATE modemState) { switch (modemState) { @@ -1264,12 +1190,8 @@ void SerialPort::setMode(DVM_STATE modemState) io.setMode(); } -/// -/// Sets the fine-tune symbol levels. -/// -/// -/// -/// +/* Sets the fine-tune symbol levels. */ + uint8_t SerialPort::setSymbolLvlAdj(const uint8_t* data, uint8_t length) { if (length < 6U) @@ -1321,12 +1243,8 @@ uint8_t SerialPort::setSymbolLvlAdj(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Sets the software Rx sample level. -/// -/// -/// -/// +/* Sets the software Rx sample level. */ + uint8_t SerialPort::setRXLevel(const uint8_t* data, uint8_t length) { if (length < 1U) @@ -1339,24 +1257,16 @@ uint8_t SerialPort::setRXLevel(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Sets the RF parameters. -/// -/// -/// -/// +/* Sets the RF parameters. */ + uint8_t SerialPort::setRFParams(const uint8_t* data, uint8_t length) { // unused on dedicated modem -- see firmware_hs for implementation return RSN_OK; } -/// -/// Sets the protocol ring buffer sizes. -/// -/// -/// -/// +/* Sets the protocol ring buffer sizes. */ + uint8_t SerialPort::setBuffers(const uint8_t* data, uint8_t length) { if (length < 1U) diff --git a/SerialPort.h b/SerialPort.h index b8a9b97..74b21a6 100644 --- a/SerialPort.h +++ b/SerialPort.h @@ -1,17 +1,23 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2018,2021-2024 Bryan Biedenkapp, N2PLL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2018,2021-2024 Bryan Biedenkapp, N2PLL -* -*/ + * @file SerialPort.h + * @ingroup modem_fw + * @file SerialPort.cpp + * @ingroup modem_fw + * @file SerialDue.cpp + * @ingroup modem_fw + * @file SerialSTM.cpp + * @ingroup modem_fw + */ #if !defined(__SERIAL_PORT_H__) #define __SERIAL_PORT_H__ @@ -23,167 +29,256 @@ // Constants // --------------------------------------------------------------------------- +/** + * @addtogroup modem + * @{ + */ + +/** + * @brief Modem operation states. + */ enum DVM_STATE { - STATE_IDLE = 0U, + STATE_IDLE = 0U, //! Idle // DMR - STATE_DMR = 1U, + STATE_DMR = 1U, //! DMR // Project 25 - STATE_P25 = 2U, + STATE_P25 = 2U, //! Project 25 // NXDN - STATE_NXDN = 3U, + STATE_NXDN = 3U, //! NXDN // CW - STATE_CW = 10U, + STATE_CW = 10U, //! Continuous Wave // Calibration States - STATE_P25_CAL_1K = 92U, + STATE_P25_CAL_1K = 92U, //! Project 25 Calibration 1K - STATE_DMR_DMO_CAL_1K = 93U, - STATE_DMR_CAL_1K = 94U, - STATE_DMR_LF_CAL = 95U, + STATE_DMR_DMO_CAL_1K = 93U, //! DMR DMO Calibration 1K + STATE_DMR_CAL_1K = 94U, //! DMR Calibration 1K + STATE_DMR_LF_CAL = 95U, //! DMR Low Frequency Calibration - STATE_RSSI_CAL = 96U, + STATE_RSSI_CAL = 96U, //! RSSI Calibration - STATE_P25_CAL = 97U, - STATE_DMR_CAL = 98U, - STATE_NXDN_CAL = 99U + STATE_P25_CAL = 97U, //! Project 25 Calibration + STATE_DMR_CAL = 98U, //! DMR Calibration + STATE_NXDN_CAL = 99U //! NXDN Calibration }; +/** + * @brief Modem commands. + */ enum DVM_COMMANDS { - CMD_GET_VERSION = 0x00U, - CMD_GET_STATUS = 0x01U, - CMD_SET_CONFIG = 0x02U, - CMD_SET_MODE = 0x03U, - - CMD_SET_SYMLVLADJ = 0x04U, - CMD_SET_RXLEVEL = 0x05U, - CMD_SET_RFPARAMS = 0x06U, - - CMD_CAL_DATA = 0x08U, - CMD_RSSI_DATA = 0x09U, - - CMD_SEND_CWID = 0x0AU, - - CMD_SET_BUFFERS = 0x0FU, - - CMD_DMR_DATA1 = 0x18U, - CMD_DMR_LOST1 = 0x19U, - CMD_DMR_DATA2 = 0x1AU, - CMD_DMR_LOST2 = 0x1BU, - CMD_DMR_SHORTLC = 0x1CU, - CMD_DMR_START = 0x1DU, - CMD_DMR_ABORT = 0x1EU, - CMD_DMR_CACH_AT_CTRL = 0x1FU, - CMD_DMR_CLEAR1 = 0x20U, - CMD_DMR_CLEAR2 = 0x21U, - - CMD_P25_DATA = 0x31U, - CMD_P25_LOST = 0x32U, - CMD_P25_CLEAR = 0x33U, - - CMD_NXDN_DATA = 0x41U, - CMD_NXDN_LOST = 0x42U, - CMD_NXDN_CLEAR = 0x43U, - - CMD_ACK = 0x70U, - CMD_NAK = 0x7FU, - - CMD_FLSH_READ = 0xE0U, - CMD_FLSH_WRITE = 0xE1U, - - CMD_DEBUG1 = 0xF1U, - CMD_DEBUG2 = 0xF2U, - CMD_DEBUG3 = 0xF3U, - CMD_DEBUG4 = 0xF4U, - CMD_DEBUG5 = 0xF5U, - CMD_DEBUG_DUMP = 0xFAU, + CMD_GET_VERSION = 0x00U, //! Get Modem Version + CMD_GET_STATUS = 0x01U, //! Get Modem Status + CMD_SET_CONFIG = 0x02U, //! Set Modem Configuration + CMD_SET_MODE = 0x03U, //! Set Modem Mode + + CMD_SET_SYMLVLADJ = 0x04U, //! Set Symbol Level Adjustments + CMD_SET_RXLEVEL = 0x05U, //! Set Rx Level + CMD_SET_RFPARAMS = 0x06U, //! (Hotspot) Set RF Parameters + + CMD_CAL_DATA = 0x08U, //! Calibration Data + CMD_RSSI_DATA = 0x09U, //! RSSI Data + + CMD_SEND_CWID = 0x0AU, //! Send Continous Wave ID (Morse) + + CMD_SET_BUFFERS = 0x0FU, //! Set FIFO Buffer Lengths + + CMD_DMR_DATA1 = 0x18U, //! DMR Data Slot 1 + CMD_DMR_LOST1 = 0x19U, //! DMR Data Lost Slot 1 + CMD_DMR_DATA2 = 0x1AU, //! DMR Data Slot 2 + CMD_DMR_LOST2 = 0x1BU, //! DMR Data Lost Slot 2 + CMD_DMR_SHORTLC = 0x1CU, //! DMR Short Link Control + CMD_DMR_START = 0x1DU, //! DMR Start Transmit + CMD_DMR_ABORT = 0x1EU, //! DMR Abort + CMD_DMR_CACH_AT_CTRL = 0x1FU, //! DMR Set CACH AT Control + CMD_DMR_CLEAR1 = 0x20U, //! DMR Clear Slot 1 Buffer + CMD_DMR_CLEAR2 = 0x21U, //! DMR Clear Slot 2 Buffer + + CMD_P25_DATA = 0x31U, //! Project 25 Data + CMD_P25_LOST = 0x32U, //! Project 25 Data Lost + CMD_P25_CLEAR = 0x33U, //! Project 25 Clear Buffer + + CMD_NXDN_DATA = 0x41U, //! NXDN Data + CMD_NXDN_LOST = 0x42U, //! NXDN Data Lost + CMD_NXDN_CLEAR = 0x43U, //! NXDN Clear Buffer + + CMD_ACK = 0x70U, //! Command ACK + CMD_NAK = 0x7FU, //! Command NACK + + CMD_FLSH_READ = 0xE0U, //! Read Flash Partition + CMD_FLSH_WRITE = 0xE1U, //! Write Flash Partition + + CMD_DEBUG1 = 0xF1U, //! + CMD_DEBUG2 = 0xF2U, //! + CMD_DEBUG3 = 0xF3U, //! + CMD_DEBUG4 = 0xF4U, //! + CMD_DEBUG5 = 0xF5U, //! + CMD_DEBUG_DUMP = 0xFAU, //! }; +/** + * @brief Modem response reason codes. + */ enum CMD_REASON_CODE { - RSN_OK = 0U, - RSN_NAK = 1U, + RSN_OK = 0U, //! OK + RSN_NAK = 1U, //! Negative Acknowledge - RSN_ILLEGAL_LENGTH = 2U, - RSN_INVALID_REQUEST = 4U, - RSN_RINGBUFF_FULL = 8U, + RSN_ILLEGAL_LENGTH = 2U, //! Illegal Length + RSN_INVALID_REQUEST = 4U, //! Invalid Request + RSN_RINGBUFF_FULL = 8U, //! Ring Buffer Full - RSN_INVALID_FDMA_PREAMBLE = 10U, - RSN_INVALID_MODE = 11U, - - RSN_INVALID_DMR_CC = 12U, - RSN_INVALID_DMR_SLOT = 13U, - RSN_INVALID_DMR_START = 14U, - RSN_INVALID_DMR_RX_DELAY = 15U, + RSN_INVALID_FDMA_PREAMBLE = 10U, //! Invalid FDMA Preamble Length + RSN_INVALID_MODE = 11U, //! Invalid Mode - RSN_INVALID_P25_CORR_COUNT = 16U, + RSN_INVALID_DMR_CC = 12U, //! Invalid DMR CC + RSN_INVALID_DMR_SLOT = 13U, //! Invalid DMR Slot + RSN_INVALID_DMR_START = 14U, //! Invaild DMR Start Transmit + RSN_INVALID_DMR_RX_DELAY = 15U, //! Invalid DMR Rx Delay - RSN_NO_INTERNAL_FLASH = 20U, - RSN_FAILED_ERASE_FLASH = 21U, - RSN_FAILED_WRITE_FLASH = 22U, - RSN_FLASH_WRITE_TOO_BIG = 23U, + RSN_INVALID_P25_CORR_COUNT = 16U, //! Invalid P25 Correlation Count - RSN_DMR_DISABLED = 63U, - RSN_P25_DISABLED = 64U, - RSN_NXDN_DISABLED = 65U + RSN_NO_INTERNAL_FLASH = 20U, //! No Internal Flash + RSN_FAILED_ERASE_FLASH = 21U, //! Failed to erase flash partition + RSN_FAILED_WRITE_FLASH = 22U, //! Failed to write flash partition + RSN_FLASH_WRITE_TOO_BIG = 23U, //! Data to large for flash partition + + RSN_DMR_DISABLED = 63U, //! DMR Disabled + RSN_P25_DISABLED = 64U, //! Project 25 Disabled + RSN_NXDN_DISABLED = 65U //! NXDN Disabled }; const uint8_t DVM_SHORT_FRAME_START = 0xFEU; const uint8_t DVM_LONG_FRAME_START = 0xFDU; #define SERIAL_SPEED 115200 +/** @} */ // --------------------------------------------------------------------------- // Class Declaration -// Implements the RS232 serial bus to communicate with the HOST S/W. // --------------------------------------------------------------------------- +/** + * @brief Implements the RS232 serial bus to communicate with the HOST S/W. + * @ingroup modem_fw + */ class DSP_FW_API SerialPort { public: - /// Initializes a new instance of the SerialPort class. + /** + * @brief Initializes a new instance of the SerialPort class. + */ SerialPort(); - /// Starts serial port communications. + /** + * @brief Starts serial port communications. + */ void start(); - /// Process data from serial port. + /** + * @brief Process data from serial port. + */ void process(); - /// Helper to check if the modem is in a calibration state. + /** + * @brief Helper to check if the modem is in a calibration state. + * @param state + * @returns bool + */ bool isCalState(DVM_STATE state); - /// Helper to determine digital mode if the modem is in a calibration state. + /** + * @brief Helper to determine digital mode if the modem is in a calibration state. + * @param state + * @returns DVM_STATE + */ DVM_STATE calRelativeState(DVM_STATE state); - /// Write DMR frame data to serial port. + /** + * @brief Write DMR frame data to serial port. + * @param slot DMR slot number. + * @param[in] data Data to write. + * @param length Length of data to write. + */ void writeDMRData(bool slot, const uint8_t* data, uint8_t length); - /// Write lost DMR frame data to serial port. + /** + * @brief Write lost DMR frame data to serial port. + * @param slot DMR slot number. + */ void writeDMRLost(bool slot); - /// Write P25 frame data to serial port. + /** + * @brief Write P25 frame data to serial port. + * @param[in] data Data to write. + * @param length Length of data to write. + */ void writeP25Data(const uint8_t* data, uint16_t length); - /// Write lost P25 frame data to serial port. + /** + * @brief Write lost P25 frame data to serial port. + */ void writeP25Lost(); - /// Write NXDN frame data to serial port. + /** + * @brief Write NXDN frame data to serial port. + * @param[in] data Data to write. + * @param length Length of data to write. + */ void writeNXDNData(const uint8_t* data, uint8_t length); - /// Write lost NXDN frame data to serial port. + /** + * @brief Write lost NXDN frame data to serial port. + */ void writeNXDNLost(); - /// Write calibration frame data to serial port. + /** + * @brief Write calibration frame data to serial port. + * @param[in] data + * @param length + */ void writeCalData(const uint8_t* data, uint8_t length); - /// Write RSSI frame data to serial port. + /** + * @brief Write RSSI frame data to serial port. + * @param[in] data Data to write. + * @param length Length of data to write. + */ void writeRSSIData(const uint8_t* data, uint8_t length); - /// + /** + * @brief + * @param[in] text + */ void writeDebug(const char* text); - /// + /** + * @brief + * @param[in] text + * @param n1 + */ void writeDebug(const char* text, int16_t n1); - /// + /** + * @brief + * @param[in] text + * @param n1 + * @param n2 + */ void writeDebug(const char* text, int16_t n1, int16_t n2); - /// + /** + * @brief + * @param[in] text + * @param n1 + * @param n2 + * @param n3 + */ void writeDebug(const char* text, int16_t n1, int16_t n2, int16_t n3); - /// + /** + * @brief + * @param[in] text + * @param n1 + * @param n2 + * @param n3 + * @param n4 + */ void writeDebug(const char* text, int16_t n1, int16_t n2, int16_t n3, int16_t n4); - /// + /** + * @brief + * @param[in] data + * @param length + */ void writeDump(const uint8_t* data, uint16_t length); private: @@ -196,46 +291,118 @@ class DSP_FW_API SerialPort { SerialBuffer m_repeat; - /// Write acknowlegement. + /** + * @brief Write acknowlegement. + */ void sendACK(); - /// Write negative acknowlegement. + /** + * @brief Write negative acknowlegement. + * @param err + */ void sendNAK(uint8_t err); - /// Write modem DSP status. + /** + * @brief Write modem DSP status. + */ void getStatus(); - /// Write modem DSP version. + /** + * @brief Write modem DSP version. + */ void getVersion(); - /// Helper to validate the passed modem state is valid. + /** + * @brief Helper to validate the passed modem state is valid. + * @param state + * @returns uint8_t Reason code. + */ uint8_t modemStateCheck(DVM_STATE state); - /// Set modem DSP configuration from serial port data. + /** + * @brief Set modem DSP configuration from serial port data. + * @param[in] data Buffer containing configuration frame. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t setConfig(const uint8_t* data, uint8_t length); - /// Set modem DSP mode from serial port data. + /** + * @brief Set modem DSP mode from serial port data. + * @param[in] data Buffer containing mode frame. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t setMode(const uint8_t* data, uint8_t length); - /// Sets the modem state. + /** + * @brief Sets the modem state. + * @param modemState + */ void setMode(DVM_STATE modemState); - /// Sets the fine-tune symbol levels. + /** + * @brief Sets the fine-tune symbol levels. + * @param[in] data Buffer containing symbol level frame. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t setSymbolLvlAdj(const uint8_t* data, uint8_t length); - /// Sets the software Rx sample level. + /** + * @brief Sets the software Rx sample level. + * @param[in] data Buffer containing RX level frame. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t setRXLevel(const uint8_t* data, uint8_t length); - /// Sets the RF parameters. + /** + * @brief Sets the RF parameters. + * @param[in] data Buffer containing RF parameters frame. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t setRFParams(const uint8_t* data, uint8_t length); - /// Sets the protocol ring buffer sizes. + /** + * @brief Sets the protocol ring buffer sizes. + * @param[in] data Buffer containing set buffers frame. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t setBuffers(const uint8_t* data, uint8_t length); - /// + /** + * @brief Reads data from the modem flash parititon. + */ void flashRead(); - /// + /** + * @brief Writes data to the modem flash partition. + * @param[in] data Buffer containing data to write to flash partition. + * @param length Length of buffer. + * @returns uint8_t + */ uint8_t flashWrite(const uint8_t* data, uint8_t length); // Hardware specific routines - /// + /** + * @brief + * @param n + * @param speed + */ void beginInt(uint8_t n, int speed); - /// + /** + * @brief + * @param n + */ int availableInt(uint8_t n); - /// + /** + * @brief + * @param n + */ int availableForWriteInt(uint8_t n); - /// + /** + * @brief + * @param n + */ uint8_t readInt(uint8_t n); - /// + /** + * @brief + * @param n + * @param[in] data + * @param length + * @param flush + */ void writeInt(uint8_t n, const uint8_t* data, uint16_t length, bool flush = false); }; diff --git a/SerialSTM.cpp b/SerialSTM.cpp index ebc382e..fa81b79 100644 --- a/SerialSTM.cpp +++ b/SerialSTM.cpp @@ -1,19 +1,15 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2016 Jim McLaughlin, KI6ZUM -* Copyright (C) 2016,2017,2018 Andy Uribe, CA6JAU -* Copyright (c) 2017 Jonathan Naylor, G4KLX -* Copyright (C) 2018,2022,2024 Bryan Biedenkapp, N2PLL -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2016 Jim McLaughlin, KI6ZUM + * Copyright (C) 2016,2017,2018 Andy Uribe, CA6JAU + * Copyright (c) 2017 Jonathan Naylor, G4KLX + * Copyright (C) 2018,2022,2024 Bryan Biedenkapp, N2PLL + * + */ #include "Globals.h" #include "SerialPort.h" #include "STM_UART.h" @@ -55,18 +51,18 @@ extern "C" { static STM_UART m_USART1; -/// -/// -/// +/** + * @brief Helper to handle the USART1 IRQ. + */ void USART1_IRQHandler() { m_USART1.handleIRQ(); } -/// -/// -/// -/// +/** + * @brief Initializes the USART1. + * @param speed Port speed. + */ void InitUSART1(int speed) { // USART1 - TXD PA9 - RXD PA10 - pins on mmdvm pi board @@ -119,18 +115,18 @@ void InitUSART1(int speed) static STM_UART m_USART5; -/// -/// -/// +/** + * @brief Helper to handle the USART5 IRQ. + */ void UART5_IRQHandler() { m_USART5.handleIRQ(); } -/// -/// -/// -/// +/** + * @brief Initializes the USART5. + * @param speed Port speed. + */ void InitUART5(int speed) { // UART5 - TXD PC12 - RXD PD2 @@ -184,9 +180,8 @@ void InitUART5(int speed) // Private Class Members // --------------------------------------------------------------------------- -/// -/// -/// +/* Reads data from the modem flash parititon. */ + void SerialPort::flashRead() { uint8_t reply[249U]; @@ -200,11 +195,8 @@ void SerialPort::flashRead() writeInt(1U, reply, 249U); } -/// -/// -/// -/// -/// +/* Writes data to the modem flash partition. */ + uint8_t SerialPort::flashWrite(const uint8_t* data, uint8_t length) { if (length > 249U) { @@ -250,11 +242,8 @@ uint8_t SerialPort::flashWrite(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// -/// -/// -/// +/* */ + void SerialPort::beginInt(uint8_t n, int speed) { switch (n) { @@ -271,11 +260,8 @@ void SerialPort::beginInt(uint8_t n, int speed) } } -/// -/// -/// -/// -/// +/* */ + int SerialPort::availableInt(uint8_t n) { switch (n) { @@ -290,11 +276,8 @@ int SerialPort::availableInt(uint8_t n) } } -/// -/// -/// -/// -/// +/* */ + int SerialPort::availableForWriteInt(uint8_t n) { switch (n) { @@ -309,11 +292,8 @@ int SerialPort::availableForWriteInt(uint8_t n) } } -/// -/// -/// -/// -/// +/* */ + uint8_t SerialPort::readInt(uint8_t n) { switch (n) { @@ -328,13 +308,8 @@ uint8_t SerialPort::readInt(uint8_t n) } } -/// -/// -/// -/// -/// -/// -/// +/* */ + void SerialPort::writeInt(uint8_t n, const uint8_t* data, uint16_t length, bool flush) { switch (n) { diff --git a/Utils.cpp b/Utils.cpp index a142ce1..0c5520c 100644 --- a/Utils.cpp +++ b/Utils.cpp @@ -1,16 +1,12 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015 Jonathan Naylor, G4KLX -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015 Jonathan Naylor, G4KLX + * + */ #include "Utils.h" // --------------------------------------------------------------------------- @@ -28,11 +24,15 @@ const uint8_t BITS_TABLE[] = { // Global Functions // --------------------------------------------------------------------------- +/* Returns the count of bits in the passed 8 byte value. */ + uint8_t countBits8(uint8_t bits) { return BITS_TABLE[bits]; } +/* Returns the count of bits in the passed 32 byte value. */ + uint8_t countBits32(uint32_t bits) { uint8_t* p = (uint8_t*)&bits; @@ -44,6 +44,8 @@ uint8_t countBits32(uint32_t bits) return n; } +/* Returns the count of bits in the passed 64 byte value. */ + uint8_t countBits64(ulong64_t bits) { uint8_t* p = (uint8_t*)&bits; diff --git a/Utils.h b/Utils.h index f37e46a..70ea1ae 100644 --- a/Utils.h +++ b/Utils.h @@ -1,16 +1,18 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016 Jonathan Naylor, G4KLX -* -*/ + * @file Utils.h + * @ingroup modem_fw + * @file Utils.cpp + * @ingroup modem_fw + */ #if !defined(__UTILS_H__) #define __UTILS_H__ @@ -20,8 +22,23 @@ // Global Functions // --------------------------------------------------------------------------- +/** + * @brief Returns the count of bits in the passed 8 byte value. + * @param bits uint8_t to count bits for. + * @returns uint8_t Count of bits in passed value. + */ DSP_FW_API uint8_t countBits8(uint8_t bits); +/** + * @brief Returns the count of bits in the passed 32 byte value. + * @param bits uint32_t to count bits for. + * @returns uint8_t Count of bits in passed value. + */ DSP_FW_API uint8_t countBits32(uint32_t bits); +/** + * @brief Returns the count of bits in the passed 64 byte value. + * @param bits ulong64_t to count bits for. + * @returns uint8_t Count of bits in passed value. + */ DSP_FW_API uint8_t countBits64(ulong64_t bits); #endif // __UTILS_H__ diff --git a/dmr/CalDMR.cpp b/dmr/CalDMR.cpp index d6bbb51..706c84b 100644 --- a/dmr/CalDMR.cpp +++ b/dmr/CalDMR.cpp @@ -1,18 +1,14 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2015 Jonathan Naylor, G4KLX -* Copyright (C) 2016 Colin Durbridge, G4EML -* Copyright (C) 2018 Andy Uribe, CA6JAU -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2009-2015 Jonathan Naylor, G4KLX + * Copyright (C) 2016 Colin Durbridge, G4EML + * Copyright (C) 2018 Andy Uribe, CA6JAU + * + */ #include "Globals.h" #include "dmr/CalDMR.h" @@ -79,9 +75,8 @@ const uint8_t SHORTLC_1K[] = { 0x33U, 0x3AU, 0xA0U, 0x30U, 0x00U, 0x55U, 0xA6U, // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the CalDMR class. -/// +/* Initializes a new instance of the CalDMR class. */ + CalDMR::CalDMR() : m_transmit(false), m_state(DMRCAL1K_IDLE), @@ -92,9 +87,8 @@ CalDMR::CalDMR() : ::memcpy(m_dmr1k, VOICE_1K, DMR_FRAME_LENGTH_BYTES + 1U); } -/// -/// Process local state and transmit on the air interface. -/// +/* Process local state and transmit on the air interface. */ + void CalDMR::process() { switch (m_modemState) { @@ -119,10 +113,8 @@ void CalDMR::process() } } -/// -/// -/// -/// +/* */ + void CalDMR::createData1k(uint8_t n) { for (uint8_t i = 0; i < 5U; i++) @@ -134,10 +126,8 @@ void CalDMR::createData1k(uint8_t n) m_dmr1k[20U] |= SYNCEMB_1K[n][6] & 0xF0U; } -/// -/// -/// -/// +/* */ + void CalDMR::createDataDMO1k(uint8_t n) { for (uint8_t i = 0; i < 5U; i++) @@ -149,9 +139,8 @@ void CalDMR::createDataDMO1k(uint8_t n) m_dmr1k[20U] |= SYNCEMB_DMO1K[n][6] & 0xF0U; } -/// -/// -/// +/* */ + void CalDMR::dmr1kcal() { dmrTX.process(); @@ -198,9 +187,8 @@ void CalDMR::dmr1kcal() } } -/// -/// -/// +/* */ + void CalDMR::dmrDMO1kcal() { dmrDMOTX.process(); @@ -236,12 +224,8 @@ void CalDMR::dmrDMO1kcal() } } -/// -/// Write DMR calibration state. -/// -/// -/// -/// +/* Write DMR calibration state. */ + uint8_t CalDMR::write(const uint8_t* data, uint8_t length) { if (length != 1U) diff --git a/dmr/CalDMR.h b/dmr/CalDMR.h index 42d94e6..3b26099 100644 --- a/dmr/CalDMR.h +++ b/dmr/CalDMR.h @@ -1,18 +1,20 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2009-2015 Jonathan Naylor, G4KLX + * Copyright (C) 2016 Colin Durbridge, G4EML + * Copyright (C) 2018 Andy Uribe, CA6JAU + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2015 Jonathan Naylor, G4KLX -* Copyright (C) 2016 Colin Durbridge, G4EML -* Copyright (C) 2018 Andy Uribe, CA6JAU -* -*/ + * @file CalDMR.h + * @ingroup dmr_mfw + * @file CalDMR.h + * @ingroup dmr_mfw + */ #if !defined(__CAL_DMR_H__) #define __CAL_DMR_H__ @@ -25,12 +27,15 @@ namespace dmr // Constants // --------------------------------------------------------------------------- + /** + * @brief Calibration States + */ enum DMR1KCAL { - DMRCAL1K_IDLE, - DMRCAL1K_VH, - DMRCAL1K_VOICE, - DMRCAL1K_VT, - DMRCAL1K_WAIT + DMRCAL1K_IDLE, //! Idle + DMRCAL1K_VH, //! Voice Header + DMRCAL1K_VOICE, //! Voice + DMRCAL1K_VT, //! Voice Terminator + DMRCAL1K_WAIT //! }; // --------------------------------------------------------------------------- @@ -40,23 +45,42 @@ namespace dmr class DSP_FW_API CalDMR { public: - /// Initializes a new instance of the CalDMR class. + /** + * @brief Initializes a new instance of the CalDMR class. + */ CalDMR(); - /// Process local state and transmit on the air interface. + /** + * @brief Process local state and transmit on the air interface. + */ void process(); - /// + /** + * @brief + * @param n + */ void createData1k(uint8_t n); - /// + /** + * @brief + * @param n + */ void createDataDMO1k(uint8_t n); - /// + /** + * @brief + */ void dmr1kcal(); - /// + /** + * @brief + */ void dmrDMO1kcal(); - /// Write DMR calibration state. + /** + * @brief Write DMR calibration state. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t write(const uint8_t* data, uint8_t length); private: diff --git a/dmr/DMRDMORX.cpp b/dmr/DMRDMORX.cpp index 9e9e9a3..26aca92 100644 --- a/dmr/DMRDMORX.cpp +++ b/dmr/DMRDMORX.cpp @@ -1,16 +1,12 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2017 Jonathan Naylor, G4KLX -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2009-2017 Jonathan Naylor, G4KLX + * + */ #include "Globals.h" #include "dmr/DMRDMORX.h" #include "dmr/DMRSlotType.h" @@ -39,9 +35,8 @@ const uint8_t CONTROL_DATA = 0x40U; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the DMRDMORX class. -/// +/* Initializes a new instance of the DMRDMORX class. */ + DMRDMORX::DMRDMORX() : m_bitBuffer(), m_buffer(), @@ -65,9 +60,8 @@ DMRDMORX::DMRDMORX() : /* stub */ } -/// -/// Helper to reset data values to defaults. -/// +/* Helper to reset data values to defaults. */ + void DMRDMORX::reset() { m_syncPtr = 0U; @@ -79,12 +73,8 @@ void DMRDMORX::reset() m_endPtr = NOENDPTR; } -/// -/// Sample DMR values from the air interface. -/// -/// -/// -/// +/* Sample DMR values from the air interface. */ + void DMRDMORX::samples(const q15_t* samples, const uint16_t* rssi, uint8_t length) { bool dcd = false; @@ -95,10 +85,8 @@ void DMRDMORX::samples(const q15_t* samples, const uint16_t* rssi, uint8_t lengt io.setDecode(dcd); } -/// -/// Sets the DMR color code. -/// -/// Color code. +/* Sets the DMR color code. */ + void DMRDMORX::setColorCode(uint8_t colorCode) { m_colorCode = colorCode; @@ -108,12 +96,8 @@ void DMRDMORX::setColorCode(uint8_t colorCode) // Private Class Members // --------------------------------------------------------------------------- -/// -/// Helper to perform sample processing. -/// -/// -/// -/// +/* Helper to perform sample processing. */ + bool DMRDMORX::processSample(q15_t sample, uint16_t rssi) { m_buffer[m_dataPtr] = sample; @@ -268,10 +252,8 @@ bool DMRDMORX::processSample(q15_t sample, uint16_t rssi) return m_state != DMORXS_NONE; } -/// -/// Frame synchronization correlator. -/// -/// +/* Frame synchronization correlator. */ + void DMRDMORX::correlateSync(bool first) { uint8_t errs = countBits32((m_bitBuffer[m_bitPtr] & DMR_SYNC_SYMBOLS_MASK) ^ DMR_MS_DATA_SYNC_SYMBOLS); @@ -422,15 +404,8 @@ void DMRDMORX::correlateSync(bool first) } } -/// -/// -/// -/// -/// -/// -/// -/// -/// +/* */ + void DMRDMORX::samplesToBits(uint16_t start, uint8_t count, uint8_t* buffer, uint16_t offset, q15_t centre, q15_t threshold) { for (uint8_t i = 0U; i < count; i++) { @@ -467,10 +442,8 @@ void DMRDMORX::samplesToBits(uint16_t start, uint8_t count, uint8_t* buffer, uin } } -/// -/// -/// -/// +/* */ + void DMRDMORX::writeRSSIData(uint8_t* frame) { #if defined(SEND_RSSI_DATA) diff --git a/dmr/DMRDMORX.h b/dmr/DMRDMORX.h index 3cda841..6f4100a 100644 --- a/dmr/DMRDMORX.h +++ b/dmr/DMRDMORX.h @@ -1,16 +1,22 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * @package DVM / Modem Firmware + * @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) + * @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* -*/ + * @file DMRDMORX.h + * @ingroup dmr_mfw + * @file DMRDMORX.h + * @ingroup dmr_mfw + */ #if !defined(__DMR_DMO_RX_H__) #define __DMR_DMO_RX_H__ @@ -25,29 +31,47 @@ namespace dmr const uint16_t DMO_BUFFER_LENGTH_SAMPLES = 1440U; // 60ms at 24 kHz + /** + * @brief DMR DMO Receiver State + */ enum DMORX_STATE { - DMORXS_NONE, - DMORXS_VOICE, - DMORXS_DATA + DMORXS_NONE, //! None + DMORXS_VOICE, //! Voice Data + DMORXS_DATA //! PDU Data }; // --------------------------------------------------------------------------- // Class Declaration - // Implements receiver logic for DMR DMO mode operation. // --------------------------------------------------------------------------- + /** + * @brief Implements receiver logic for DMR DMO mode operation. + * @ingroup dmr_mfw + */ class DSP_FW_API DMRDMORX { public: - /// Initializes a new instance of the DMRDMORX class. + /** + * @brief Initializes a new instance of the DMRDMORX class. + */ DMRDMORX(); - /// Helper to reset data values to defaults. + /** + * @brief Helper to reset data values to defaults. + */ void reset(); - /// Sample DMR values from the air interface. + /** + * @brief Sample DMR values from the air interface. + * @param[in] samples + * @param[in] rssi + * @param length + */ void samples(const q15_t* samples, const uint16_t* rssi, uint8_t length); - /// Sets the DMR color code. + /** + * @brief Sets the DMR color code. + * @param colorCode + */ void setColorCode(uint8_t colorCode); private: @@ -78,15 +102,33 @@ namespace dmr uint16_t m_rssi[DMO_BUFFER_LENGTH_SAMPLES]; - /// Helper to perform sample processing. + /** + * @brief Helper to perform sample processing. + * @param sample + * @param rssi + */ bool processSample(q15_t sample, uint16_t rssi); - /// Frame synchronization correlator. + /** + * @brief Frame synchronization correlator. + * @param first + */ void correlateSync(bool first); - /// + /** + * @brief + * @param start + * @param count + * @param buffer + * @param offset + * @param centre + * @param threshold + */ void samplesToBits(uint16_t start, uint8_t count, uint8_t* buffer, uint16_t offset, q15_t centre, q15_t threshold); - /// + /** + * @brief + * @param frame + */ void writeRSSIData(uint8_t* frame); }; } // namespace dmr diff --git a/dmr/DMRDMOTX.cpp b/dmr/DMRDMOTX.cpp index 263da8c..242ae8c 100644 --- a/dmr/DMRDMOTX.cpp +++ b/dmr/DMRDMOTX.cpp @@ -1,19 +1,15 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2017 Jonathan Naylor, G4KLX -* Copyright (C) 2016 Colin Durbridge, G4EML -* Copyright (C) 2017 Andy Uribe, CA6JAU -* Copyright (C) 2020 Bryan Biedenkapp, N2PLL -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2009-2017 Jonathan Naylor, G4KLX + * Copyright (C) 2016 Colin Durbridge, G4EML + * Copyright (C) 2017 Andy Uribe, CA6JAU + * Copyright (C) 2020 Bryan Biedenkapp, N2PLL + * + */ #include "Globals.h" #include "dmr/DMRSlotType.h" @@ -47,9 +43,8 @@ const uint8_t PR_FILL[] = // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the DMRDMOTX class. -/// +/* Initializes a new instance of the DMRDMOTX class. */ + DMRDMOTX::DMRDMOTX() : m_fifo(DMR_TX_BUFFER_LEN), m_modFilter(), @@ -69,9 +64,8 @@ DMRDMOTX::DMRDMOTX() : m_modFilter.pState = m_modState; } -/// -/// Process local buffer and transmit on the air interface. -/// +/* Process local buffer and transmit on the air interface. */ + void DMRDMOTX::process() { if (m_poLen == 0U && m_fifo.getData() > 0U) { @@ -117,12 +111,8 @@ void DMRDMOTX::process() } } -/// -/// Write data to the local buffer. -/// -/// -/// -/// +/* Write data to the local buffer. */ + uint8_t DMRDMOTX::writeData(const uint8_t* data, uint8_t length) { if (length != (DMR_FRAME_LENGTH_BYTES + 1U)) @@ -139,10 +129,8 @@ uint8_t DMRDMOTX::writeData(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Sets the FDMA preamble count. -/// -/// Count of preambles. +/* Sets the FDMA preamble count. */ + void DMRDMOTX::setPreambleCount(uint8_t preambleCnt) { uint32_t preambles = (uint32_t)((float)preambleCnt / 0.2083F); @@ -153,11 +141,8 @@ void DMRDMOTX::setPreambleCount(uint8_t preambleCnt) m_preambleCnt = 1200U; } -/// -/// Sets the fine adjust 4FSK symbol levels. -/// -/// +3/-3 symbol adjust. -/// +1/-1 symbol adjust. +/* Sets the fine adjust 4FSK symbol levels. */ + void DMRDMOTX::setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj) { m_symLevel3Adj = level3Adj; @@ -176,20 +161,16 @@ void DMRDMOTX::setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj) m_symLevel1Adj = 0; } -/// -/// Helper to resize the FIFO buffer. -/// -/// +/* Helper to resize the FIFO buffer. */ + void DMRDMOTX::resizeBuffer(uint16_t size) { m_fifo.reset(); m_fifo.reinitialize(size); } -/// -/// Helper to get how much space the ring buffer has for samples. -/// -/// +/* Helper to get how much space the ring buffer has for samples. */ + uint8_t DMRDMOTX::getSpace() const { return m_fifo.getSpace() / (DMR_FRAME_LENGTH_BYTES + 2U); @@ -199,10 +180,8 @@ uint8_t DMRDMOTX::getSpace() const // Private Class Members // --------------------------------------------------------------------------- -/// -/// -/// -/// +/* Helper to write a raw byte to the DAC. */ + void DMRDMOTX::writeByte(uint8_t c) { q15_t inBuffer[4U]; @@ -232,9 +211,8 @@ void DMRDMOTX::writeByte(uint8_t c) io.write(STATE_DMR, outBuffer, DMR_RADIO_SYMBOL_LENGTH * 4U); } -/// -/// -/// +/* */ + void DMRDMOTX::writeSilence() { q15_t inBuffer[4U] = { 0x00U, 0x00U, 0x00U, 0x00U }; diff --git a/dmr/DMRDMOTX.h b/dmr/DMRDMOTX.h index c43ebcd..2920cc8 100644 --- a/dmr/DMRDMOTX.h +++ b/dmr/DMRDMOTX.h @@ -1,18 +1,20 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2016 Colin Durbridge, G4EML + * Copyright (C) 2020 Bryan Biedenkapp, N2PLL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2016 Colin Durbridge, G4EML -* Copyright (C) 2020 Bryan Biedenkapp, N2PLL -* -*/ + * @file DMRDMOTX.h + * @ingroup dmr_mfw + * @file DMRDMOTX.h + * @ingroup dmr_mfw + */ #if !defined(__DMR_DMO_TX_H__) #define __DMR_DMO_TX_H__ @@ -31,29 +33,54 @@ namespace dmr // --------------------------------------------------------------------------- // Class Declaration - // Implements transmitter logic for DMR DMO mode operation. // --------------------------------------------------------------------------- + /** + * @brief Implements transmitter logic for DMR DMO mode operation. + * @ingroup dmr_mfw + */ class DSP_FW_API DMRDMOTX { public: - /// Initializes a new instance of the DMRDMOTX class. + /** + * @brief Initializes a new instance of the DMRDMOTX class. + */ DMRDMOTX(); - /// Process local buffer and transmit on the air interface. + /** + * @brief Process local buffer and transmit on the air interface. + */ void process(); - /// Write data to the local buffer. + /** + * @brief Write data to the local buffer. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t writeData(const uint8_t* data, uint8_t length); - /// Sets the FDMA preamble count. + /** + * @brief Sets the FDMA preamble count. + * @param preambleCnt FDMA preamble count. + */ void setPreambleCount(uint8_t preambleCnt); - /// Sets the fine adjust 4FSK symbol levels. + /** + * @brief Sets the fine adjust 4FSK symbol levels. + * @param level3Adj +3/-3 Level Adjustment + * @param level1Adj +1/-1 Level Adjustment + */ void setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj); - /// Helper to resize the FIFO buffer. + /** + * @brief Helper to resize the FIFO buffer. + * @param size + */ void resizeBuffer(uint16_t size); - /// Helper to get how much space the ring buffer has for samples. + /** + * @brief Helper to get how much space the ring buffer has for samples. + * @returns uint8_t Amount of space in ring buffer for samples. + */ uint8_t getSpace() const; private: @@ -72,9 +99,14 @@ namespace dmr int8_t m_symLevel3Adj; int8_t m_symLevel1Adj; - /// + /** + * @brief Helper to write a raw byte to the DAC. + * @param c Byte. + */ void writeByte(uint8_t c); - /// + /** + * @brief + */ void writeSilence(); }; } // namespace dmr diff --git a/dmr/DMRDefines.h b/dmr/DMRDefines.h index 60f1a51..b8da4aa 100644 --- a/dmr/DMRDefines.h +++ b/dmr/DMRDefines.h @@ -1,16 +1,20 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * +* Copyright (C) 2009-2016 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2016 Jonathan Naylor, G4KLX -* -*/ + * @defgroup dmr_mfw Digital Mobile Radio + * @brief Implementation for the ETSI TS-102 Digital Mobile Radio (DMR) standard. + * @ingroup modem_fw + * + * @file DMRDefines.h + * @ingroup dmr_mfw + */ #if !defined(__DMR_DEFINES_H__) #define __DMR_DEFINES_H__ @@ -22,6 +26,11 @@ namespace dmr // Constants // --------------------------------------------------------------------------- + /** + * @addtogroup dmr_mfw + * @{ + */ + const uint32_t DMR_RADIO_SYMBOL_LENGTH = 5U; // At 24 kHz sample rate const uint32_t DMR_FRAME_LENGTH_BYTES = 33U; @@ -105,6 +114,8 @@ namespace dmr const uint8_t DT_RATE_34_DATA = 8U; const uint8_t DT_IDLE = 9U; const uint8_t DT_RATE_1_DATA = 10U; + + /** @} */ } // namespace dmr #endif // __DMR_DEFINES_H__ diff --git a/dmr/DMRIdleRX.cpp b/dmr/DMRIdleRX.cpp index 9a483ea..d7dd7df 100644 --- a/dmr/DMRIdleRX.cpp +++ b/dmr/DMRIdleRX.cpp @@ -1,16 +1,16 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2017 Jonathan Naylor, G4KLX -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * @package DVM / Modem Firmware + * @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) + * @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) + * + * Copyright (C) 2009-2017 Jonathan Naylor, G4KLX + * + */ #include "Globals.h" #include "dmr/DMRIdleRX.h" #include "dmr/DMRSlotType.h" @@ -36,9 +36,8 @@ const uint8_t CONTROL_DATA = 0x40U; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the DMRIdleRX class. -/// +/* Initializes a new instance of the DMRIdleRX class. */ + DMRIdleRX::DMRIdleRX() : m_bitBuffer(), m_buffer(), @@ -53,9 +52,8 @@ DMRIdleRX::DMRIdleRX() : /* stub */ } -/// -/// Helper to reset data values to defaults. -/// +/* Helper to reset data values to defaults. */ + void DMRIdleRX::reset() { m_dataPtr = 0U; @@ -66,21 +64,16 @@ void DMRIdleRX::reset() m_endPtr = NOENDPTR; } -/// -/// Sample DMR values from the air interface. -/// -/// -/// +/* Sample DMR values from the air interface. */ + void DMRIdleRX::samples(const q15_t* samples, uint8_t length) { for (uint8_t i = 0U; i < length; i++) processSample(samples[i]); } -/// -/// Sets the DMR color code. -/// -/// Color code. +/* Sets the DMR color code. */ + void DMRIdleRX::setColorCode(uint8_t colorCode) { m_colorCode = colorCode; @@ -90,10 +83,8 @@ void DMRIdleRX::setColorCode(uint8_t colorCode) // Private Class Members // --------------------------------------------------------------------------- -/// -/// Helper to perform sample processing. -/// -/// +/* Helper to perform sample processing. */ + void DMRIdleRX::processSample(q15_t sample) { m_bitBuffer[m_bitPtr] <<= 1; @@ -201,15 +192,8 @@ void DMRIdleRX::processSample(q15_t sample) m_bitPtr = 0U; } -/// -/// -/// -/// -/// -/// -/// -/// -/// +/* */ + void DMRIdleRX::samplesToBits(uint16_t start, uint8_t count, uint8_t* buffer, uint16_t offset, q15_t centre, q15_t threshold) { for (uint8_t i = 0U; i < count; i++) { diff --git a/dmr/DMRIdleRX.h b/dmr/DMRIdleRX.h index a9be82f..cfd0330 100644 --- a/dmr/DMRIdleRX.h +++ b/dmr/DMRIdleRX.h @@ -1,16 +1,22 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * @package DVM / Modem Firmware + * @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) + * @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) + * + * Copyright (C) 2015 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015 Jonathan Naylor, G4KLX -* -*/ + * @file DMRIdleRX.h + * @ingroup dmr_mfw + * @file DMRIdleRX.h + * @ingroup dmr_mfw + */ #if !defined(__DMR_IDLE_RX_H__) #define __DMR_IDLE_RX_H__ @@ -21,21 +27,35 @@ namespace dmr { // --------------------------------------------------------------------------- // Class Declaration - // Implements receiver logic for idle DMR mode operation. // --------------------------------------------------------------------------- + /** + * @brief Implements receiver logic for idle DMR mode operation. + * @ingroup dmr_mfw + */ class DSP_FW_API DMRIdleRX { public: - /// Initializes a new instance of the DMRIdleRX class. + /** + * @brief Initializes a new instance of the DMRIdleRX class. + */ DMRIdleRX(); - /// Helper to reset data values to defaults. + /** + * @brief Helper to reset data values to defaults. + */ void reset(); - /// Sample DMR values from the air interface. + /** + * @brief Sample DMR values from the air interface. + * @param[in] samples + * @param length + */ void samples(const q15_t* samples, uint8_t length); - /// Sets the DMR color code. + /** + * @brief Sets the DMR color code. + * @param colorCode + */ void setColorCode(uint8_t colorCode); private: @@ -51,10 +71,21 @@ namespace dmr uint8_t m_colorCode; - /// Helper to perform sample processing. + /** + * @brief Helper to perform sample processing. + * @param sample + */ void processSample(q15_t sample); - /// + /** + * @brief + * @param start + * @param count + * @param buffer + * @param offset + * @param centre + * @param threshold + */ void samplesToBits(uint16_t start, uint8_t count, uint8_t* buffer, uint16_t offset, q15_t centre, q15_t threshold); }; } // namespace dmr diff --git a/dmr/DMRRX.cpp b/dmr/DMRRX.cpp index 759fe3e..1d25187 100644 --- a/dmr/DMRRX.cpp +++ b/dmr/DMRRX.cpp @@ -1,16 +1,12 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016 Jonathan Naylor, G4KLX -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016 Jonathan Naylor, G4KLX + * + */ #include "Globals.h" #include "dmr/DMRRX.h" @@ -20,9 +16,8 @@ using namespace dmr; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the DMRRX class. -/// +/* Initializes a new instance of the DMRRX class. */ + DMRRX::DMRRX() : m_slot1RX(false), m_slot2RX(true) @@ -30,22 +25,16 @@ DMRRX::DMRRX() : /* stub */ } -/// -/// Helper to reset data values to defaults. -/// +/* Helper to reset data values to defaults. */ + void DMRRX::reset() { m_slot1RX.reset(); m_slot2RX.reset(); } -/// -/// Sample DMR values from the air interface. -/// -/// -/// -/// -/// +/* Sample DMR values from the air interface. */ + void DMRRX::samples(const q15_t* samples, const uint16_t* rssi, const uint8_t* control, uint8_t length) { bool dcd1 = false; @@ -70,20 +59,16 @@ void DMRRX::samples(const q15_t* samples, const uint16_t* rssi, const uint8_t* c io.setDecode(dcd1 || dcd2); } -/// -/// Sets the DMR color code. -/// -/// Color code. +/* Sets the DMR color code. */ + void DMRRX::setColorCode(uint8_t colorCode) { m_slot1RX.setColorCode(colorCode); m_slot2RX.setColorCode(colorCode); } -/// -/// Sets the number of samples to delay before processing. -/// -/// Number of samples to delay. +/* Sets the number of samples to delay before processing. */ + void DMRRX::setRxDelay(uint8_t delay) { m_slot1RX.setRxDelay(delay); diff --git a/dmr/DMRRX.h b/dmr/DMRRX.h index 3acd9f3..c215df9 100644 --- a/dmr/DMRRX.h +++ b/dmr/DMRRX.h @@ -1,16 +1,18 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016 Jonathan Naylor, G4KLX -* -*/ + * @file DMRRX.h + * @ingroup dmr_mfw + * @file DMRRX.h + * @ingroup dmr_mfw + */ #if !defined(__DMR_RX_H__) #define __DMR_RX_H__ @@ -21,23 +23,42 @@ namespace dmr { // --------------------------------------------------------------------------- // Class Declaration - // Implements receiver logic for duplex DMR mode operation. // --------------------------------------------------------------------------- + /** + * @brief Implements receiver logic for duplex DMR mode operation. + * @ingroup dmr_mfw + */ class DSP_FW_API DMRRX { public: - /// Initializes a new instance of the DMRRX class. + /** + * @brief Initializes a new instance of the DMRRX class. + */ DMRRX(); - /// Helper to reset data values to defaults. + /** + * @brief Helper to reset data values to defaults. + */ void reset(); - /// Sample DMR values from the air interface. + /** + * @brief Sample DMR values from the air interface. + * @param[in] samples + * @param[in] rssi + * @param[in] control + * @param length + */ void samples(const q15_t* samples, const uint16_t* rssi, const uint8_t* control, uint8_t length); - /// Sets the DMR color code. + /** + * @brief Sets the DMR color code. + * @param colorCode + */ void setColorCode(uint8_t colorCode); - /// Sets the number of samples to delay before processing. + /** + * @brief Sets the number of samples to delay before processing. + * @param delay + */ void setRxDelay(uint8_t delay); private: diff --git a/dmr/DMRSlotRX.cpp b/dmr/DMRSlotRX.cpp index 7bb9b56..7b8de26 100644 --- a/dmr/DMRSlotRX.cpp +++ b/dmr/DMRSlotRX.cpp @@ -1,16 +1,12 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2017 Jonathan Naylor, G4KLX -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2009-2017 Jonathan Naylor, G4KLX + * + */ #include "Globals.h" #include "dmr/DMRSlotRX.h" #include "dmr/DMRSlotType.h" @@ -42,9 +38,8 @@ const uint8_t CONTROL_DATA = 0x40U; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the DMRSlotRX class. -/// +/* Initializes a new instance of the DMRSlotRX class. */ + DMRSlotRX::DMRSlotRX(bool slot) : m_slot(slot), m_bitBuffer(), @@ -71,9 +66,8 @@ DMRSlotRX::DMRSlotRX(bool slot) : /* stub */ } -/// -/// Helper to set data values for start of Rx. -/// +/* Helper to set data values for start of Rx. */ + void DMRSlotRX::start() { m_dataPtr = 0U; @@ -83,9 +77,8 @@ void DMRSlotRX::start() m_control = CONTROL_NONE; } -/// -/// Helper to reset data values to defaults. -/// +/* Helper to reset data values to defaults. */ + void DMRSlotRX::reset() { m_syncPtr = 0U; @@ -100,12 +93,8 @@ void DMRSlotRX::reset() m_endPtr = NOENDPTR; } -/// -/// Perform DMR slot sample processing. -/// -/// -/// -/// +/* Perform DMR slot sample processing. */ + bool DMRSlotRX::processSample(q15_t sample, uint16_t rssi) { m_delayPtr++; @@ -251,19 +240,15 @@ bool DMRSlotRX::processSample(q15_t sample, uint16_t rssi) return m_state != DMRRXS_NONE; } -/// -/// Sets the DMR color code. -/// -/// Color code. +/* Sets the DMR color code. */ + void DMRSlotRX::setColorCode(uint8_t colorCode) { m_colorCode = colorCode; } -/// -/// Sets the number of samples to delay before processing. -/// -/// Number of samples to delay. +/* Sets the number of samples to delay before processing. */ + void DMRSlotRX::setRxDelay(uint8_t delay) { m_delay = delay; @@ -273,10 +258,8 @@ void DMRSlotRX::setRxDelay(uint8_t delay) // Private Class Members // --------------------------------------------------------------------------- -/// -/// Frame synchronization correlator. -/// -/// +/* Frame synchronization correlator. */ + void DMRSlotRX::correlateSync(bool first) { uint8_t errs = countBits32((m_bitBuffer[m_bitPtr] & DMR_SYNC_SYMBOLS_MASK) ^ DMR_MS_DATA_SYNC_SYMBOLS); @@ -408,15 +391,8 @@ void DMRSlotRX::correlateSync(bool first) } } -/// -/// -/// -/// -/// -/// -/// -/// -/// +/* */ + void DMRSlotRX::samplesToBits(uint16_t start, uint8_t count, uint8_t* buffer, uint16_t offset, q15_t centre, q15_t threshold) { for (uint8_t i = 0U; i < count; i++, start += DMR_RADIO_SYMBOL_LENGTH) { @@ -449,10 +425,8 @@ void DMRSlotRX::samplesToBits(uint16_t start, uint8_t count, uint8_t* buffer, ui } } -/// -/// -/// -/// +/* */ + void DMRSlotRX::writeRSSIData(uint8_t* frame) { #if defined(SEND_RSSI_DATA) diff --git a/dmr/DMRSlotRX.h b/dmr/DMRSlotRX.h index 21625ba..4974612 100644 --- a/dmr/DMRSlotRX.h +++ b/dmr/DMRSlotRX.h @@ -1,16 +1,18 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* -*/ + * @file DMRSlotRX.h + * @ingroup dmr_mfw + * @file DMRSlotRX.h + * @ingroup dmr_mfw + */ #if !defined(__DMR_SLOT_RX_H__) #define __DMR_SLOT_RX_H__ @@ -23,33 +25,56 @@ namespace dmr // Constants // --------------------------------------------------------------------------- + /** + * @brief DMR Slot Receiver State + */ enum DMRRX_STATE { - DMRRXS_NONE, - DMRRXS_VOICE, - DMRRXS_DATA + DMRRXS_NONE, //! None + DMRRXS_VOICE, //! Voice Data + DMRRXS_DATA //! PDU Data }; // --------------------------------------------------------------------------- // Class Declaration - // Implements receiver logic for DMR slots. // --------------------------------------------------------------------------- + /** + * @brief Implements receiver logic for DMR slots. + * @ingroup dmr_mfw + */ class DSP_FW_API DMRSlotRX { public: - /// Initializes a new instance of the DMRSlotRX class. + /** + * @brief Initializes a new instance of the DMRSlotRX class. + * @param slot + */ DMRSlotRX(bool slot); - /// Helper to set data values for start of Rx. + /** + * @brief Helper to set data values for start of Rx. + */ void start(); - /// Helper to reset data values to defaults. + /** + * @brief Helper to reset data values to defaults. + */ void reset(); - /// Perform DMR slot sample processing. + /** + * @brief Perform DMR slot sample processing. + * @param sample + * @param rssi + */ bool processSample(q15_t sample, uint16_t rssi); - /// Sets the DMR color code. + /** + * @brief Sets the DMR color code. + * @param colorCode + */ void setColorCode(uint8_t colorCode); - /// Sets the number of samples to delay before processing. + /** + * @brief Sets the number of samples to delay before processing. + * @param delay + */ void setRxDelay(uint8_t delay); private: @@ -85,12 +110,26 @@ namespace dmr uint16_t m_rssi[900U]; - /// Frame synchronization correlator. + /** + * @brief Frame synchronization correlator. + * @param first + */ void correlateSync(bool first); - /// + /** + * @brief + * @param start + * @param count + * @param buffer + * @param offset + * @param centre + * @param threshold + */ void samplesToBits(uint16_t start, uint8_t count, uint8_t* buffer, uint16_t offset, q15_t centre, q15_t threshold); - /// + /** + * @brief + * @param frame + */ void writeRSSIData(uint8_t* frame); }; } // namespace dmr diff --git a/dmr/DMRSlotType.cpp b/dmr/DMRSlotType.cpp index d16f415..f3c1cf4 100644 --- a/dmr/DMRSlotType.cpp +++ b/dmr/DMRSlotType.cpp @@ -1,16 +1,12 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015 Jonathan Naylor, G4KLX -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015 Jonathan Naylor, G4KLX + * + */ #include "Globals.h" #include "dmr/DMRSlotType.h" @@ -213,20 +209,15 @@ const uint32_t DECODING_TABLE_1987[] = { // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the DMRSlotType class. -/// +/* Initializes a new instance of the DMRSlotType class. */ + DMRSlotType::DMRSlotType() { /* stub */ } -/// -/// Decodes DMR slot type. -/// -/// -/// -/// +/* Decodes DMR slot type. */ + void DMRSlotType::decode(const uint8_t* frame, uint8_t& colorCode, uint8_t& dataType) const { uint8_t slotType[3U]; @@ -245,12 +236,8 @@ void DMRSlotType::decode(const uint8_t* frame, uint8_t& colorCode, uint8_t& data dataType = (code >> 0) & 0x0FU; } -/// -/// Encodes DMR slot type. -/// -/// -/// -/// +/* Encodes DMR slot type. */ + void DMRSlotType::encode(uint8_t colorCode, uint8_t dataType, uint8_t* frame) const { uint8_t slotType[3U]; @@ -272,11 +259,8 @@ void DMRSlotType::encode(uint8_t colorCode, uint8_t dataType, uint8_t* frame) co // Private Class Members // --------------------------------------------------------------------------- -/// -/// -/// -/// -/// +/* */ + uint8_t DMRSlotType::decode2087(const uint8_t* data) const { uint32_t code = (data[0U] << 11) + (data[1U] << 3) + (data[2U] >> 5); @@ -289,20 +273,8 @@ uint8_t DMRSlotType::decode2087(const uint8_t* data) const return code >> 11; } -/// -/// -/// -/// -/// Compute the syndrome corresponding to the given pattern, i.e., the -/// remainder after dividing the pattern (when considering it as the vector -/// representation of a polynomial) by the generator polynomial, GENPOL. -/// In the program this pattern has several meanings: (1) pattern = infomation -/// bits, when constructing the encoding table; (2) pattern = error pattern, -/// when constructing the decoding table; and (3) pattern = received vector, to -/// obtain its syndrome in decoding. -/// -/// -/// +/* */ + uint32_t DMRSlotType::getSyndrome1987(uint32_t pattern) const { unsigned int aux = X18; diff --git a/dmr/DMRSlotType.h b/dmr/DMRSlotType.h index 4c22754..7973274 100644 --- a/dmr/DMRSlotType.h +++ b/dmr/DMRSlotType.h @@ -1,16 +1,18 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015 Jonathan Naylor, G4KLX -* -*/ + * @file DMRSlotType.h + * @ingroup dmr_mfw + * @file DMRSlotType.h + * @ingroup dmr_mfw + */ #if !defined(__DMR_SLOT_TYPE_H__) #define __DMR_SLOT_TYPE_H__ @@ -20,23 +22,46 @@ namespace dmr { // --------------------------------------------------------------------------- // Class Declaration - // // --------------------------------------------------------------------------- + /** + * @brief Represents DMR slot type. + * @ingroup dmr_mfw + */ class DSP_FW_API DMRSlotType { public: - /// Initializes a new instance of the DMRSlotType class. + /** + * @brief Initializes a new instance of the DMRSlotType class. + */ DMRSlotType(); - /// Decodes DMR slot type. + /** + * @brief Decodes DMR slot type. + * @param[in] frame + * @param[out] colorCode + * @param[out] dataType + */ void decode(const uint8_t* frame, uint8_t& colorCode, uint8_t& dataType) const; - /// Encodes DMR slot type. + /** + * @brief Encodes DMR slot type. + * @param colorCode + * @param dataType + * @param[out] frame + */ void encode(uint8_t colorCode, uint8_t dataType, uint8_t* frame) const; private: - /// + /** + * @brief + * @param[in] data + * @returns uint8_t + */ uint8_t decode2087(const uint8_t* data) const; - /// + /** + * @brief + * @param pattern + * @returns uint32_t + */ uint32_t getSyndrome1987(uint32_t pattern) const; }; } // namespace dmr diff --git a/dmr/DMRTX.cpp b/dmr/DMRTX.cpp index 643d43a..b7f68a2 100644 --- a/dmr/DMRTX.cpp +++ b/dmr/DMRTX.cpp @@ -1,19 +1,15 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2017 Jonathan Naylor, G4KLX -* Copyright (C) 2016 Colin Durbridge, G4EML -* Copyright (C) 2017 Andy Uribe, CA6JAU -* Copyright (C) 2022 Bryan Biedenkapp, N2PLL -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2009-2017 Jonathan Naylor, G4KLX + * Copyright (C) 2016 Colin Durbridge, G4EML + * Copyright (C) 2017 Andy Uribe, CA6JAU + * Copyright (C) 2022 Bryan Biedenkapp, N2PLL + * + */ #include "Globals.h" #include "dmr/DMRSlotType.h" @@ -61,9 +57,8 @@ const uint32_t ABORT_COUNT = 6U; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the DMRTX class. -/// +/* Initializes a new instance of the DMRTX class. */ + DMRTX::DMRTX() : m_fifo(), m_modFilter(), @@ -104,9 +99,8 @@ DMRTX::DMRTX() : m_abortCount[1U] = 0U; } -/// -/// Process local buffer and transmit on the air interface. -/// +/* Process local buffer and transmit on the air interface. */ + void DMRTX::process() { if (m_state == DMRTXSTATE_IDLE) @@ -165,12 +159,8 @@ void DMRTX::process() } } -/// -/// Write slot 1 data to the local buffer. -/// -/// -/// -/// +/* Write slot 1 data to the local buffer. */ + uint8_t DMRTX::writeData1(const uint8_t* data, uint8_t length) { if (length != (DMR_FRAME_LENGTH_BYTES + 1U)) @@ -198,12 +188,8 @@ uint8_t DMRTX::writeData1(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Write slot 2 data to the local buffer. -/// -/// -/// -/// +/* Write slot 2 data to the local buffer. */ + uint8_t DMRTX::writeData2(const uint8_t* data, uint8_t length) { if (length != (DMR_FRAME_LENGTH_BYTES + 1U)) @@ -231,12 +217,8 @@ uint8_t DMRTX::writeData2(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Write short LC data to the local buffer. -/// -/// -/// -/// +/* Write short LC data to the local buffer. */ + uint8_t DMRTX::writeShortLC(const uint8_t* data, uint8_t length) { if (length != 9U) @@ -253,12 +235,8 @@ uint8_t DMRTX::writeShortLC(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Write abort data to the local buffer. -/// -/// -/// -/// +/* Write abort data to the local buffer. */ + uint8_t DMRTX::writeAbort(const uint8_t* data, uint8_t length) { if (length != 1U) @@ -280,10 +258,8 @@ uint8_t DMRTX::writeAbort(const uint8_t* data, uint8_t length) } } -/// -/// Helper to set the start state for Tx. -/// -/// +/* Helper to set the start state for Tx. */ + void DMRTX::setStart(bool start) { m_state = start ? DMRTXSTATE_SLOT1 : DMRTXSTATE_IDLE; @@ -296,37 +272,29 @@ void DMRTX::setStart(bool start) m_abort[1U] = false; } -/// -/// Helper to set the calibration state for Tx. -/// -/// +/* Helper to set the calibration state for Tx. */ + void DMRTX::setCal(bool start) { m_state = start ? DMRTXSTATE_CAL : DMRTXSTATE_IDLE; } -/// -/// Helper to get how much space the slot 1 ring buffer has for samples. -/// -/// +/* Helper to get how much space the slot 1 ring buffer has for samples. */ + uint8_t DMRTX::getSpace1() const { return m_fifo[0U].getSpace() / (DMR_FRAME_LENGTH_BYTES + 2U); } -/// -/// Helper to get how much space the slot 2 ring buffer has for samples. -/// -/// +/* Helper to get how much space the slot 2 ring buffer has for samples. */ + uint8_t DMRTX::getSpace2() const { return m_fifo[1U].getSpace() / (DMR_FRAME_LENGTH_BYTES + 2U); } -/// -/// Sets the ignore flags for setting the CACH Access Type bit. -/// -/// +/* Sets the ignore flags for setting the CACH Access Type bit. */ + void DMRTX::setIgnoreCACH_AT(uint8_t slot) { m_cachATControl = slot; @@ -335,10 +303,8 @@ void DMRTX::setIgnoreCACH_AT(uint8_t slot) } } -/// -/// Sets the DMR color code. -/// -/// Color code. +/* Sets the DMR color code. */ + void DMRTX::setColorCode(uint8_t colorCode) { ::memcpy(m_idle, IDLE_DATA, DMR_FRAME_LENGTH_BYTES); @@ -347,11 +313,8 @@ void DMRTX::setColorCode(uint8_t colorCode) slotType.encode(colorCode, DT_IDLE, m_idle); } -/// -/// Sets the fine adjust 4FSK symbol levels. -/// -/// +3/-3 symbol adjust. -/// +1/-1 symbol adjust. +/* Sets the fine adjust 4FSK symbol levels. */ + void DMRTX::setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj) { m_symLevel3Adj = level3Adj; @@ -370,26 +333,22 @@ void DMRTX::setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj) m_symLevel1Adj = 0; } -/// -/// Helper to reset data values to defaults for slot 1 FIFO. -/// +/* Helper to reset data values to defaults for slot 1 FIFO. */ + void DMRTX::resetFifo1() { m_fifo[0U].reset(); } -/// -/// Helper to reset data values to defaults for slot 2 FIFO. -/// +/* Helper to reset data values to defaults for slot 2 FIFO. */ + void DMRTX::resetFifo2() { m_fifo[1U].reset(); } -/// -/// Helper to resize the FIFO buffer. -/// -/// +/* Helper to resize the FIFO buffer. */ + void DMRTX::resizeBuffer(uint16_t size) { m_fifo[0U].reset(); @@ -398,10 +357,8 @@ void DMRTX::resizeBuffer(uint16_t size) m_fifo[1U].reinitialize(size); } -/// -/// -/// -/// +/* */ + uint32_t DMRTX::getFrameCount() { return m_frameCount; @@ -411,10 +368,8 @@ uint32_t DMRTX::getFrameCount() // Private Class Members // --------------------------------------------------------------------------- -/// -/// -/// -/// +/* Helper to generate data. */ + void DMRTX::createData(uint8_t slotIndex) { if (m_fifo[slotIndex].getData() >= DMR_FRAME_LENGTH_BYTES && m_frameCount >= STARTUP_COUNT && m_abortCount[slotIndex] >= ABORT_COUNT) { @@ -436,47 +391,8 @@ void DMRTX::createData(uint8_t slotIndex) m_poPtr = 0U; } -/// -/// -/// -void DMRTX::createCal() -{ - // 1.2 kHz sine wave generation - if (m_modemState == STATE_DMR_CAL) { - for (unsigned int i = 0U; i < DMR_FRAME_LENGTH_BYTES; i++) { - m_poBuffer[i] = DMR_START_SYNC; - m_markBuffer[i] = MARK_NONE; - } - - m_poLen = DMR_FRAME_LENGTH_BYTES; - } - - // 80 Hz square wave generation - if (m_modemState == STATE_DMR_LF_CAL) { - for (unsigned int i = 0U; i < 7U; i++) { - m_poBuffer[i] = 0x55U; // +3, +3, ... pattern - m_markBuffer[i] = MARK_NONE; - } - - m_poBuffer[7U] = 0x5FU; // +3, +3, -3, -3 pattern - - for (unsigned int i = 8U; i < 15U; i++) { - m_poBuffer[i] = 0xFFU; // -3, -3, ... pattern - m_markBuffer[i] = MARK_NONE; - } +/* Helper to generate the common access channel. */ - m_poLen = 15U; - } - - m_poLen = DMR_FRAME_LENGTH_BYTES; - m_poPtr = 0U; -} - -/// -/// -/// -/// -/// void DMRTX::createCACH(uint8_t txSlotIndex, uint8_t rxSlotIndex) { m_frameCount++; @@ -536,11 +452,43 @@ void DMRTX::createCACH(uint8_t txSlotIndex, uint8_t rxSlotIndex) m_cachPtr += 3U; } -/// -/// -/// -/// -/// +/* Helper to generate calibration data. */ + +void DMRTX::createCal() +{ + // 1.2 kHz sine wave generation + if (m_modemState == STATE_DMR_CAL) { + for (unsigned int i = 0U; i < DMR_FRAME_LENGTH_BYTES; i++) { + m_poBuffer[i] = DMR_START_SYNC; + m_markBuffer[i] = MARK_NONE; + } + + m_poLen = DMR_FRAME_LENGTH_BYTES; + } + + // 80 Hz square wave generation + if (m_modemState == STATE_DMR_LF_CAL) { + for (unsigned int i = 0U; i < 7U; i++) { + m_poBuffer[i] = 0x55U; // +3, +3, ... pattern + m_markBuffer[i] = MARK_NONE; + } + + m_poBuffer[7U] = 0x5FU; // +3, +3, -3, -3 pattern + + for (unsigned int i = 8U; i < 15U; i++) { + m_poBuffer[i] = 0xFFU; // -3, -3, ... pattern + m_markBuffer[i] = MARK_NONE; + } + + m_poLen = 15U; + } + + m_poLen = DMR_FRAME_LENGTH_BYTES; + m_poPtr = 0U; +} + +/* Helper to write a raw byte to the DAC. */ + void DMRTX::writeByte(uint8_t c, uint8_t control) { q15_t inBuffer[4U]; diff --git a/dmr/DMRTX.h b/dmr/DMRTX.h index 87d4c4f..87c9b8b 100644 --- a/dmr/DMRTX.h +++ b/dmr/DMRTX.h @@ -1,18 +1,20 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2016 Colin Durbridge, G4EML + * Copyright (C) 2021-2022 Bryan Biedenkapp, N2PLL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2016 Colin Durbridge, G4EML -* Copyright (C) 2021-2022 Bryan Biedenkapp, N2PLL -* -*/ + * @file DMRTX.h + * @ingroup dmr_mfw + * @file DMRTX.h + * @ingroup dmr_mfw + */ #if !defined(__DMR_TX_H__) #define __DMR_TX_H__ @@ -26,64 +28,126 @@ namespace dmr // Constants // --------------------------------------------------------------------------- + /** + * @brief DMR Duplex Transmitter State + */ enum DMRTXSTATE { - DMRTXSTATE_IDLE, - DMRTXSTATE_SLOT1, - DMRTXSTATE_CACH1, - DMRTXSTATE_SLOT2, - DMRTXSTATE_CACH2, - DMRTXSTATE_CAL + DMRTXSTATE_IDLE, //! Idle + DMRTXSTATE_SLOT1, //! Slot 1 + DMRTXSTATE_CACH1, //! Common Access Channel 1 + DMRTXSTATE_SLOT2, //! Slot 2 + DMRTXSTATE_CACH2, //! Common Access Channel 2 + DMRTXSTATE_CAL //! Calibration }; // --------------------------------------------------------------------------- // Class Declaration - // Implements receiver logic for duplex DMR mode operation. // --------------------------------------------------------------------------- + /** + * @brief Implements transmitter logic for duplex DMR mode operation. + * @ingroup dmr_mfw + */ class DSP_FW_API DMRTX { public: - /// Initializes a new instance of the DMRTX class. + /** + * @brief Initializes a new instance of the DMRTX class. + */ DMRTX(); - /// Process local buffer and transmit on the air interface. + /** + * @brief Process local buffer and transmit on the air interface. + */ void process(); - /// Write slot 1 data to the local buffer. + /** + * @brief Write slot 1 data to the local buffer. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t writeData1(const uint8_t* data, uint8_t length); - /// Write slot 2 data to the local buffer. + /** + * @brief Write slot 2 data to the local buffer. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t writeData2(const uint8_t* data, uint8_t length); - /// Write short LC data to the local buffer. + /** + * @brief Write short LC data to the local buffer. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t writeShortLC(const uint8_t* data, uint8_t length); - /// Write abort data to the local buffer. + /** + * @brief Write abort data to the local buffer. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t writeAbort(const uint8_t* data, uint8_t length); - /// Helper to set the start state for Tx. + /** + * @brief Helper to set the start state for Tx. + * @param start + */ void setStart(bool start); - /// Helper to set the calibration state for Tx. + /** + * @brief Helper to set the calibration state for Tx. + * @param start + */ void setCal(bool start); - /// Helper to get how much space the slot 1 ring buffer has for samples. + /** + * @brief Helper to get how much space the slot 1 ring buffer has for samples. + * @returns uint8_t Amount of space in the slot 1 ring buffer. + */ uint8_t getSpace1() const; - /// Helper to get how much space the slot 2 ring buffer has for samples. + /** + * @brief Helper to get how much space the slot 2 ring buffer has for samples. + * @returns uint8_t Amount of space in the slot 2 ring buffer. + */ uint8_t getSpace2() const; - /// Sets the ignore flags for setting the CACH Access Type bit. + /** + * @brief Sets the ignore flags for setting the CACH Access Type bit. + * @param slot DMR slot number. + */ void setIgnoreCACH_AT(uint8_t slot); - /// Sets the DMR color code. + /** + * @brief Sets the DMR color code. + * @param colorCode Color code. + */ void setColorCode(uint8_t colorCode); - /// Sets the fine adjust 4FSK symbol levels. + /** + * @brief Sets the fine adjust 4FSK symbol levels. + * @param level3Adj +3/-3 Level Adjustment + * @param level1Adj +1/-1 Level Adjustment + */ void setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj); - /// Helper to reset data values to defaults for slot 1 FIFO. + /** + * @brief Helper to reset data values to defaults for slot 1 FIFO. + */ void resetFifo1(); - /// Helper to reset data values to defaults for slot 2 FIFO. + /** + * @brief Helper to reset data values to defaults for slot 2 FIFO. + */ void resetFifo2(); - /// Helper to resize the FIFO buffer. + /** + * @brief Helper to resize the FIFO buffer. + * @param size + */ void resizeBuffer(uint16_t size); - /// + /** + * @brief + * @returns uint32_t + */ uint32_t getFrameCount(); private: @@ -117,14 +181,27 @@ namespace dmr uint8_t m_cachATControl; - /// + /** + * @brief Helper to generate data. + * @param slotIndex + */ void createData(uint8_t slotIndex); - /// + /** + * @brief Helper to generate the common access channel. + * @param txSlotIndex + * @param rxSlotIndex + */ void createCACH(uint8_t txSlotIndex, uint8_t rxSlotIndex); - /// + /** + * @brief Helper to generate calibration data. + */ void createCal(); - /// + /** + * @brief Helper to write a raw byte to the DAC. + * @param c Byte. + * @param control + */ void writeByte(uint8_t c, uint8_t control); }; } // namespace dmr diff --git a/nxdn/CalNXDN.cpp b/nxdn/CalNXDN.cpp index 69710cb..98f5e66 100644 --- a/nxdn/CalNXDN.cpp +++ b/nxdn/CalNXDN.cpp @@ -1,17 +1,13 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2018 Andy Uribe, CA6JAU -* Copyright (C) 2020 Jonathan Naylor, G4KLX -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2018 Andy Uribe, CA6JAU + * Copyright (C) 2020 Jonathan Naylor, G4KLX + * + */ #include "Globals.h" #include "nxdn/CalNXDN.h" @@ -56,9 +52,8 @@ const uint8_t NXDN_CAL1K[4][49] = { // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the CalNXDN class. -/// +/* Initializes a new instance of the CalNXDN class. */ + CalNXDN::CalNXDN() : m_transmit(false), m_state(NXDNCAL1K_IDLE), @@ -67,9 +62,8 @@ CalNXDN::CalNXDN() : /* stub */ } -/// -/// Process local state and transmit on the air interface. -/// +/* Process local state and transmit on the air interface. */ + void CalNXDN::process() { if (m_transmit) { @@ -104,12 +98,8 @@ void CalNXDN::process() } } -/// -/// Write P25 calibration data to the local buffer. -/// -/// -/// -/// +/* Write P25 calibration data to the local buffer. */ + uint8_t CalNXDN::write(const uint8_t* data, uint16_t length) { if (length != 1U) diff --git a/nxdn/CalNXDN.h b/nxdn/CalNXDN.h index 97ec2d1..90f5f97 100644 --- a/nxdn/CalNXDN.h +++ b/nxdn/CalNXDN.h @@ -1,17 +1,19 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2018 Andy Uribe, CA6JAU + * Copyright (C) 2020 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2018 Andy Uribe, CA6JAU -* Copyright (C) 2020 Jonathan Naylor, G4KLX -* -*/ + * @file CalNXDN.h + * @ingroup nxdn_mfw + * @file CalNXDN.h + * @ingroup nxdn_mfw + */ #if !defined(__CAL_NXDN_H__) #define __CAL_NXDN_H__ @@ -24,25 +26,40 @@ namespace nxdn // Constants // --------------------------------------------------------------------------- + /** + * @brief Calibration States + */ enum NXDNCAL1K { - NXDNCAL1K_IDLE, - NXDNCAL1K_TX + NXDNCAL1K_IDLE, //! Idle + NXDNCAL1K_TX //! Transmit }; // --------------------------------------------------------------------------- // Class Declaration - // Implements logic for NXDN calibration mode. // --------------------------------------------------------------------------- + /** + * @brief Implements logic for NXDN calibration mode. + * @ingroup nxdn_mfw + */ class DSP_FW_API CalNXDN { public: - /// Initializes a new instance of the CalNXDN class. + /** + * @brief Initializes a new instance of the CalNXDN class. + */ CalNXDN(); - /// Process local state and transmit on the air interface. + /** + * @brief Process local state and transmit on the air interface. + */ void process(); - /// Write NXDN calibration state. + /** + * @brief Write NXDN calibration state. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t write(const uint8_t* data, uint16_t length); private: diff --git a/nxdn/NXDNDefines.h b/nxdn/NXDNDefines.h index 5542263..05b655d 100644 --- a/nxdn/NXDNDefines.h +++ b/nxdn/NXDNDefines.h @@ -8,9 +8,17 @@ * @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) * @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) * -* Copyright (C) 2016,2017,2018 Jonathan Naylor, G4KLX +* Copyright (C) 2016,2017,2018 Jonathan Naylor, G4KLX * */ +/** + * @defgroup nxdn_mfw Next Generation Digital Narrowband + * @brief Implementation for the NXDN standard. + * @ingroup modem_fw + * + * @file NXDNDefines.h + * @ingroup nxdn_mfw + */ #if !defined(__NXDN_DEFINES_H__) #define __NXDN_DEFINES_H__ @@ -22,6 +30,11 @@ namespace nxdn // Constants // --------------------------------------------------------------------------- + /** + * @addtogroup nxdn_mfw + * @{ + */ + const uint32_t NXDN_RADIO_SYMBOL_LENGTH = 10U; // At 24 kHz sample rate const uint32_t NXDN_FRAME_LENGTH_BITS = 384U; @@ -54,6 +67,8 @@ namespace nxdn // 538 = NXDN_FRAME_LENGTH_BYTES * 11 + 10 (BUFFER_LEN = NXDN_FRAME_LENGTH_BYTES * NO_OF_FRAMES) const uint32_t NXDN_TX_BUFFER_LEN = 538U; // 11 frames + pad + + /** @} */ } // namespace nxdn #endif // __NXDN_DEFINES_H__ diff --git a/nxdn/NXDNRX.cpp b/nxdn/NXDNRX.cpp index 5d0b5b1..1b7ee77 100644 --- a/nxdn/NXDNRX.cpp +++ b/nxdn/NXDNRX.cpp @@ -1,16 +1,12 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2018,2020 Jonathan Naylor, G4KLX -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2009-2018,2020 Jonathan Naylor, G4KLX + * + */ #include "Globals.h" #include "nxdn/NXDNRX.h" #include "Utils.h" @@ -39,9 +35,8 @@ const uint16_t NOENDPTR = 9999U; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the NXDNRX class. -/// +/* Initializes a new instance of the NXDNRX class. */ + NXDNRX::NXDNRX() : m_bitBuffer(), m_buffer(), @@ -68,9 +63,8 @@ NXDNRX::NXDNRX() : /* stub */ } -/// -/// Helper to reset data values to defaults. -/// +/* Helper to reset data values to defaults. */ + void NXDNRX::reset() { m_bitPtr = 0U; @@ -97,12 +91,8 @@ void NXDNRX::reset() m_rssiCount = 0U; } -/// -/// Sample P25 values from the air interface. -/// -/// -/// -/// +/* Sample P25 values from the air interface. */ + void NXDNRX::samples(const q15_t* samples, uint16_t* rssi, uint8_t length) { for (uint8_t i = 0U; i < length; i++) { @@ -136,10 +126,8 @@ void NXDNRX::samples(const q15_t* samples, uint16_t* rssi, uint8_t length) } } -/// -/// Sets the NXDN sync correlation countdown. -/// -/// Correlation Countdown Count. +/* Sets the NXDN sync correlation countdown. */ + void NXDNRX::setCorrCount(uint8_t count) { m_corrCountdown = count; @@ -149,10 +137,8 @@ void NXDNRX::setCorrCount(uint8_t count) // Private Class Members // --------------------------------------------------------------------------- -/// -/// Helper to process NXDN samples. -/// -/// +/* Helper to process NXDN samples. */ + void NXDNRX::processSample(q15_t sample) { bool ret = correlateSync(); @@ -188,10 +174,8 @@ void NXDNRX::processSample(q15_t sample) } } -/// -/// Helper to process NXDN data samples. -/// -/// +/* Helper to process NXDN data samples. */ + void NXDNRX::processData(q15_t sample) { if (m_minFSWPtr < m_maxFSWPtr) { @@ -262,10 +246,8 @@ void NXDNRX::processData(q15_t sample) } } -/// -/// Frame synchronization correlator. -/// -/// +/* Frame synchronization correlator. */ + bool NXDNRX::correlateSync() { if (countBits32((m_bitBuffer[m_bitPtr] & NXDN_FSW_SYMBOLS_MASK) ^ NXDN_FSW_SYMBOLS) <= MAX_FSW_SYMBOLS_ERRS) { @@ -355,11 +337,8 @@ bool NXDNRX::correlateSync() return false; } -/// -/// -/// -/// -/// +/* */ + void NXDNRX::calculateLevels(uint16_t start, uint16_t count) { q15_t maxPos = -16000; @@ -424,15 +403,8 @@ void NXDNRX::calculateLevels(uint16_t start, uint16_t count) m_thresholdVal >>= 4; } -/// -/// -/// -/// -/// -/// -/// -/// -/// +/* */ + void NXDNRX::samplesToBits(uint16_t start, uint16_t count, uint8_t* buffer, uint16_t offset, q15_t centre, q15_t threshold) { for (uint16_t i = 0U; i < count; i++) { diff --git a/nxdn/NXDNRX.h b/nxdn/NXDNRX.h index 5b2245a..ef89d33 100644 --- a/nxdn/NXDNRX.h +++ b/nxdn/NXDNRX.h @@ -1,16 +1,18 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017,2018,2020 Jonathan Naylor, G4KLX + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017,2018,2020 Jonathan Naylor, G4KLX -* -*/ + * @file NXDNRX.h + * @ingroup nxdn_mfw + * @file NXDNRX.h + * @ingroup nxdn_mfw + */ #if !defined(__NXDN_RX_H__) #define __NXDN_RX_H__ @@ -23,28 +25,46 @@ namespace nxdn // Constants // --------------------------------------------------------------------------- + /** + * @brief NXDN Receiver State + */ enum NXDNRX_STATE { - NXDNRXS_NONE, - NXDNRXS_DATA + NXDNRXS_NONE, //! None + NXDNRXS_DATA //! Data }; // --------------------------------------------------------------------------- // Class Declaration - // Implements receiver logic for DMR slots. // --------------------------------------------------------------------------- + /** + * @brief Implements receiver logic for NXDN mode operation. + * @ingroup nxdn_mfw + */ class DSP_FW_API NXDNRX { public: - /// Initializes a new instance of the NXDNRX class. + /** + * @brief Initializes a new instance of the NXDNRX class. + */ NXDNRX(); - /// Helper to reset data values to defaults. + /** + * @brief Helper to reset data values to defaults. + */ void reset(); - /// Sample NXDN values from the air interface. + /** + * @brief Sample NXDN values from the air interface. + * @param[in] samples + * @param rssi + * @param length + */ void samples(const q15_t* samples, uint16_t* rssi, uint8_t length); - /// Sets the NXDN sync correlation countdown. + /** + * @brief Sets the NXDN sync correlation countdown. + * @param count Sync Correlation Countdown. + */ void setCorrCount(uint8_t count); private: @@ -78,17 +98,38 @@ namespace nxdn uint32_t m_rssiAccum; uint16_t m_rssiCount; - /// Helper to process NXDN samples. + /** + * @brief Helper to process NXDN samples. + * @param sample + */ void processSample(q15_t sample); - /// Helper to process NXDN data samples. + /** + * @brief Helper to process NXDN data samples. + * @param sample + */ void processData(q15_t sample); - /// Frame synchronization correlator. + /** + * @brief Frame synchronization correlator. + * @returns bool + */ bool correlateSync(); - /// + /** + * @brief + * @param start + * @param count + */ void calculateLevels(uint16_t start, uint16_t count); - /// + /** + * @brief + * @param start + * @param count + * @param buffer + * @param offset + * @param centre + * @param threshold + */ void samplesToBits(uint16_t start, uint16_t count, uint8_t* buffer, uint16_t offset, q15_t centre, q15_t threshold); }; } // namespace nxdn diff --git a/nxdn/NXDNTX.cpp b/nxdn/NXDNTX.cpp index daceeb8..9e807cf 100644 --- a/nxdn/NXDNTX.cpp +++ b/nxdn/NXDNTX.cpp @@ -1,18 +1,14 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2018,2020 Jonathan Naylor, G4KLX -* Copyright (C) 2017 Andy Uribe, CA6JAU -* Copyright (C) 2022 Bryan Biedenkapp, N2PLL -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2009-2018,2020 Jonathan Naylor, G4KLX + * Copyright (C) 2017 Andy Uribe, CA6JAU + * Copyright (C) 2022 Bryan Biedenkapp, N2PLL + * + */ #include "Globals.h" #include "nxdn/NXDNTX.h" #include "nxdn/NXDNDefines.h" @@ -65,9 +61,8 @@ const q15_t NXDN_LEVELD = -735; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the NXDNTX class. -/// +/* Initializes a new instance of the NXDNTX class. */ + NXDNTX::NXDNTX() : m_fifo(NXDN_TX_BUFFER_LEN), m_state(NXDNTXSTATE_NORMAL), @@ -97,9 +92,8 @@ NXDNTX::NXDNTX() : m_sincFilter.pCoeffs = NXDN_SINC_FILTER; } -/// -/// Process local buffer and transmit on the air interface. -/// +/* Process local buffer and transmit on the air interface. */ + void NXDNTX::process() { if (m_fifo.getData() == 0U && m_poLen == 0U && m_tailCnt > 0U && @@ -159,12 +153,8 @@ void NXDNTX::process() } } -/// -/// Write data to the local buffer. -/// -/// -/// -/// +/* Write data to the local buffer. */ + uint8_t NXDNTX::writeData(const uint8_t* data, uint8_t length) { if (length != (NXDN_FRAME_LENGTH_BYTES + 1U)) @@ -181,18 +171,15 @@ uint8_t NXDNTX::writeData(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Clears the local buffer. -/// +/* Clears the local buffer. */ + void NXDNTX::clear() { m_fifo.reset(); } -/// -/// Sets the FDMA preamble count. -/// -/// Count of preambles. +/* Sets the FDMA preamble count. */ + void NXDNTX::setPreambleCount(uint8_t preambleCnt) { m_preambleCnt = 300U + uint16_t(preambleCnt) * 6U; // 500ms + tx delay @@ -201,20 +188,15 @@ void NXDNTX::setPreambleCount(uint8_t preambleCnt) m_preambleCnt = 1200U; } -/// -/// Sets the Tx hang time. -/// -/// Transmit hang time in seconds. +/* Sets the Tx hang time. */ + void NXDNTX::setTxHang(uint8_t txHang) { m_txHang = txHang * NXDN_FIXED_TX_HANG; } -/// -/// Sets the fine adjust 4FSK symbol levels. -/// -/// +3/-3 symbol adjust. -/// +1/-1 symbol adjust. +/* Sets the fine adjust 4FSK symbol levels. */ + void NXDNTX::setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj) { m_symLevel3Adj = level3Adj; @@ -233,29 +215,23 @@ void NXDNTX::setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj) m_symLevel1Adj = 0; } -/// -/// Helper to set the calibration state for Tx. -/// -/// +/* Helper to set the calibration state for Tx. */ + void NXDNTX::setCal(bool start) { m_state = start ? NXDNTXSTATE_CAL : NXDNTXSTATE_NORMAL; } -/// -/// Helper to resize the FIFO buffer. -/// -/// +/* Helper to resize the FIFO buffer. */ + void NXDNTX::resizeBuffer(uint16_t size) { m_fifo.reset(); m_fifo.reinitialize(size); } -/// -/// Helper to get how much space the ring buffer has for samples. -/// -/// +/* Helper to get how much space the ring buffer has for samples. */ + uint8_t NXDNTX::getSpace() const { return m_fifo.getSpace() / NXDN_FRAME_LENGTH_BYTES; @@ -265,9 +241,8 @@ uint8_t NXDNTX::getSpace() const // Private Class Members // --------------------------------------------------------------------------- -/// -/// -/// +/* Helper to generate data. */ + void NXDNTX::createData() { if (!m_tx) { @@ -288,10 +263,8 @@ void NXDNTX::createData() m_poPtr = 0U; } -/// -/// -/// -/// +/* Helper to write a raw byte to the DAC. */ + void NXDNTX::writeByte(uint8_t c) { q15_t inBuffer[4U]; @@ -324,9 +297,8 @@ void NXDNTX::writeByte(uint8_t c) io.write(STATE_NXDN, outBuffer, NXDN_RADIO_SYMBOL_LENGTH * 4U); } -/// -/// -/// +/* */ + void NXDNTX::writeSilence() { q15_t inBuffer[4U] = {0x00U, 0x00U, 0x00U, 0x00U}; diff --git a/nxdn/NXDNTX.h b/nxdn/NXDNTX.h index 90059c6..74af399 100644 --- a/nxdn/NXDNTX.h +++ b/nxdn/NXDNTX.h @@ -1,17 +1,19 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017,2018,2020 Jonathan Naylor, G4KLX + * Copyright (C) 2022 by Bryan Biedenkapp, N2PLL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017,2018,2020 Jonathan Naylor, G4KLX -* Copyright (C) 2022 by Bryan Biedenkapp, N2PLL -* -*/ + * @file NXDNTX.h + * @ingroup nxdn_mfw + * @file NXDNTX.h + * @ingroup nxdn_mfw + */ #if !defined(__NXDN_TX_H__) #define __NXDN_TX_H__ @@ -26,43 +28,79 @@ namespace nxdn #define NXDN_FIXED_TX_HANG 600 + /** + * @brief NXDN Transmitter States + */ enum NXDNTXSTATE { - NXDNTXSTATE_NORMAL, - NXDNTXSTATE_CAL + NXDNTXSTATE_NORMAL, //! Normal + NXDNTXSTATE_CAL //! Calibration }; // --------------------------------------------------------------------------- // Class Declaration - // Implements transmitter logic for NXDN mode operation. // --------------------------------------------------------------------------- + /** + * @brief Implements transmitter logic for NXDN mode operation. + * @ingroup nxdn_mfw + */ class DSP_FW_API NXDNTX { public: - /// Initializes a new instance of the NXDNTX class. + /** + * @brief Initializes a new instance of the NXDNTX class. + */ NXDNTX(); - /// Process local buffer and transmit on the air interface. + /** + * @brief Process local buffer and transmit on the air interface. + */ void process(); - /// Write data to the local buffer. + /** + * @brief Write data to the local buffer. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t writeData(const uint8_t* data, uint8_t length); - /// Clears the local buffer. + /** + * @brief Clears the local buffer. + */ void clear(); - /// Sets the FDMA preamble count. + /** + * @brief Sets the FDMA preamble count. + * @param preambleCnt FDMA preamble count. + */ void setPreambleCount(uint8_t preambleCnt); - /// Sets the transmit hang time. + /** + * @brief Sets the transmit hang time. + * @param txHang Transmit hang time. + */ void setTxHang(uint8_t txHang); - /// Sets the fine adjust 4FSK symbol levels. + /** + * @brief Sets the fine adjust 4FSK symbol levels. + * @param level3Adj +3/-3 Level Adjustment + * @param level1Adj +1/-1 Level Adjustment + */ void setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj); - /// Helper to set the calibration state for Tx. + /** + * @brief Helper to set the calibration state for Tx. + * @param start + */ void setCal(bool start); - /// Helper to resize the FIFO buffer. + /** + * @brief Helper to resize the FIFO buffer. + * @param size + */ void resizeBuffer(uint16_t size); - /// Helper to get how much space the ring buffer has for samples. + /** + * @brief Helper to get how much space the ring buffer has for samples. + * @returns uint8_t Amount of space in ring buffer for samples. + */ uint8_t getSpace() const; private: @@ -87,12 +125,19 @@ namespace nxdn int8_t m_symLevel3Adj; int8_t m_symLevel1Adj; - /// + /** + * @brief Helper to generate data. + */ void createData(); - /// + /** + * @brief Helper to write a raw byte to the DAC. + * @param c Byte. + */ void writeByte(uint8_t c); - /// + /** + * @brief + */ void writeSilence(); }; } // namespace nxdn diff --git a/p25/CalP25.cpp b/p25/CalP25.cpp index e2dd805..829435b 100644 --- a/p25/CalP25.cpp +++ b/p25/CalP25.cpp @@ -1,16 +1,12 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2018 Andy Uribe, CA6JAU -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2018 Andy Uribe, CA6JAU + * + */ #include "Globals.h" #include "p25/CalP25.h" @@ -54,9 +50,8 @@ unsigned char LDU2_1K[] = { 0x00, // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the CalP25 class. -/// +/* Initializes a new instance of the CalP25 class. */ + CalP25::CalP25() : m_transmit(false), m_state(P25CAL1K_IDLE) @@ -64,9 +59,8 @@ CalP25::CalP25() : /* stub */ } -/// -/// Process local state and transmit on the air interface. -/// +/* Process local state and transmit on the air interface. */ + void CalP25::process() { if (m_modemState == STATE_P25_CAL) { @@ -107,12 +101,8 @@ void CalP25::process() } } -/// -/// Write P25 calibration data to the local buffer. -/// -/// -/// -/// +/* Write P25 calibration data to the local buffer. */ + uint8_t CalP25::write(const uint8_t* data, uint8_t length) { if (length != 1U) diff --git a/p25/CalP25.h b/p25/CalP25.h index a3ea28e..0138872 100644 --- a/p25/CalP25.h +++ b/p25/CalP25.h @@ -1,16 +1,18 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2018 Andy Uribe, CA6JAU + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2018 Andy Uribe, CA6JAU -* -*/ + * @file CalP25.h + * @ingroup p25_mfw + * @file CalP25.h + * @ingroup p25_mfw + */ #if !defined(__CAL_P25_H__) #define __CAL_P25_H__ @@ -23,26 +25,41 @@ namespace p25 // Constants // --------------------------------------------------------------------------- + /** + * @brief Calibration States + */ enum P25CAL1K { - P25CAL1K_IDLE, - P25CAL1K_LDU1, - P25CAL1K_LDU2 + P25CAL1K_IDLE, //! Idle + P25CAL1K_LDU1, //! LDU1 + P25CAL1K_LDU2 //! LDU2 }; // --------------------------------------------------------------------------- // Class Declaration - // Implements logic for P25 calibration mode. // --------------------------------------------------------------------------- + /** + * @brief Implements logic for P25 calibration mode. + * @ingroup p25_mfw + */ class DSP_FW_API CalP25 { public: - /// Initializes a new instance of the CalP25 class. + /** + * @brief Initializes a new instance of the CalP25 class. + */ CalP25(); - /// Process local state and transmit on the air interface. + /** + * @brief Process local state and transmit on the air interface. + */ void process(); - /// Write P25 calibration state. + /** + * @brief Write P25 calibration state. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t write(const uint8_t* data, uint8_t length); private: diff --git a/p25/P25Defines.h b/p25/P25Defines.h index b12b0f4..c82b1f4 100644 --- a/p25/P25Defines.h +++ b/p25/P25Defines.h @@ -1,17 +1,21 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2017-2024 Bryan Biedenkapp, N2PLL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2017-2024 Bryan Biedenkapp, N2PLL -* -*/ + * @defgroup p25_mfw Project 25 + * @brief Implementation for the TIA-102 Project 25 standard. + * @ingroup modem_fw + * + * @file P25Defines.h + * @ingroup p25_mfw + */ #if !defined(__P25_DEFINES_H__) #define __P25_DEFINES_H__ @@ -23,6 +27,11 @@ namespace p25 // Constants // --------------------------------------------------------------------------- + /** + * @addtogroup p25_mfw + * @{ + */ + const uint32_t P25_RADIO_SYMBOL_LENGTH = 5U; // At 24 kHz sample rate const uint32_t P25_HDU_FRAME_LENGTH_BYTES = 99U; @@ -89,15 +98,17 @@ namespace p25 const uint32_t P25_TX_BUFFER_LEN = 522U; // Data Unit ID(s) - const uint8_t P25_DUID_HDU = 0x00U; // Header Data Unit - const uint8_t P25_DUID_TDU = 0x03U; // Simple Terminator Data Unit - const uint8_t P25_DUID_LDU1 = 0x05U; // Logical Link Data Unit 1 - const uint8_t P25_DUID_VSELP1 = 0x06U; // Motorola VSELP 1 - const uint8_t P25_DUID_TSDU = 0x07U; // Trunking System Data Unit - const uint8_t P25_DUID_VSELP2 = 0x09U; // Motorola VSELP 2 - const uint8_t P25_DUID_LDU2 = 0x0AU; // Logical Link Data Unit 2 - const uint8_t P25_DUID_PDU = 0x0CU; // Packet Data Unit - const uint8_t P25_DUID_TDULC = 0x0FU; // Terminator Data Unit with Link Control + const uint8_t P25_DUID_HDU = 0x00U; //! Header Data Unit + const uint8_t P25_DUID_TDU = 0x03U; //! Simple Terminator Data Unit + const uint8_t P25_DUID_LDU1 = 0x05U; //! Logical Link Data Unit 1 + const uint8_t P25_DUID_VSELP1 = 0x06U; //! Motorola VSELP 1 + const uint8_t P25_DUID_TSDU = 0x07U; //! Trunking System Data Unit + const uint8_t P25_DUID_VSELP2 = 0x09U; //! Motorola VSELP 2 + const uint8_t P25_DUID_LDU2 = 0x0AU; //! Logical Link Data Unit 2 + const uint8_t P25_DUID_PDU = 0x0CU; //! Packet Data Unit + const uint8_t P25_DUID_TDULC = 0x0FU; //! Terminator Data Unit with Link Control + + /** @} */ } // namespace p25 #endif // __P25_DEFINES_H__ diff --git a/p25/P25RX.cpp b/p25/P25RX.cpp index e5a4b06..0446a52 100644 --- a/p25/P25RX.cpp +++ b/p25/P25RX.cpp @@ -1,17 +1,13 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2009-2017 Jonathan Naylor, G4KLX -* Copyright (C) 2017-2024 Bryan Biedenkapp, N2PLL -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2009-2017 Jonathan Naylor, G4KLX + * Copyright (C) 2017-2024 Bryan Biedenkapp, N2PLL + * + */ #include "Globals.h" #include "p25/P25RX.h" #include "Utils.h" @@ -39,9 +35,8 @@ const uint8_t NOAVEPTR = 99U; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the P25RX class. -/// +/* Initializes a new instance of the P25RX class. */ + P25RX::P25RX() : m_bitBuffer(), m_buffer(), @@ -71,9 +66,8 @@ P25RX::P25RX() : /* stub */ } -/// -/// Helper to reset data values to defaults. -/// +/* Helper to reset data values to defaults. */ + void P25RX::reset() { m_minSyncPtr = 0U; @@ -100,12 +94,8 @@ void P25RX::reset() m_rssiCount = 0U; } -/// -/// Sample P25 values from the air interface. -/// -/// -/// -/// +/* Sample P25 values from the air interface. */ + void P25RX::samples(const q15_t* samples, uint16_t* rssi, uint8_t length) { for (uint8_t i = 0U; i < length; i++) { @@ -186,19 +176,15 @@ void P25RX::samples(const q15_t* samples, uint16_t* rssi, uint8_t length) } } -/// -/// Sets the P25 NAC. -/// -/// NAC. +/* Sets the P25 NAC. */ + void P25RX::setNAC(uint16_t nac) { m_nac = nac; } -/// -/// Sets the P25 sync correlation countdown. -/// -/// Correlation Countdown Count. +/* Sets the P25 sync correlation countdown. */ + void P25RX::setCorrCount(uint8_t count) { m_corrCountdown = count; @@ -208,10 +194,8 @@ void P25RX::setCorrCount(uint8_t count) // Private Class Members // --------------------------------------------------------------------------- -/// -/// Helper to process P25 samples. -/// -/// +/* Helper to process P25 samples. */ + void P25RX::processSample(q15_t sample) { if (m_minSyncPtr < m_maxSyncPtr) { @@ -339,10 +323,8 @@ void P25RX::processSample(q15_t sample) } } -/// -/// Helper to process LDU P25 samples. -/// -/// +/* Helper to process LDU P25 samples. */ + void P25RX::processVoice(q15_t sample) { if (m_minSyncPtr < m_maxSyncPtr) { @@ -439,10 +421,8 @@ void P25RX::processVoice(q15_t sample) } } -/// -/// Helper to process PDU P25 samples. -/// -/// +/* Helper to process PDU P25 samples. */ + void P25RX::processData(q15_t sample) { if (m_minSyncPtr < m_maxSyncPtr) { @@ -510,10 +490,8 @@ void P25RX::processData(q15_t sample) } } -/// -/// Frame synchronization correlator. -/// -/// +/* Frame synchronization correlator. */ + bool P25RX::correlateSync() { uint8_t errs = countBits32((m_bitBuffer[m_bitPtr] & P25_SYNC_SYMBOLS_MASK) ^ P25_SYNC_SYMBOLS); @@ -609,10 +587,8 @@ bool P25RX::correlateSync() return false; } -/// -/// Helper to decode the P25 NID. -/// -/// +/* Helper to decode the P25 NID. */ + bool P25RX::decodeNid(uint16_t start) { uint16_t nidStartPtr = start + P25_SYNC_LENGTH_SAMPLES; @@ -641,11 +617,8 @@ bool P25RX::decodeNid(uint16_t start) return false; } -/// -/// -/// -/// -/// +/* */ + void P25RX::calculateLevels(uint16_t start, uint16_t count) { q15_t maxPos = -16000; @@ -712,15 +685,8 @@ void P25RX::calculateLevels(uint16_t start, uint16_t count) m_thresholdVal >>= 4; } -/// -/// -/// -/// -/// -/// -/// -/// -/// +/* */ + void P25RX::samplesToBits(uint16_t start, uint16_t count, uint8_t* buffer, uint16_t offset, q15_t centre, q15_t threshold) { for (uint16_t i = 0U; i < count; i++) { diff --git a/p25/P25RX.h b/p25/P25RX.h index 6021261..59d6bc0 100644 --- a/p25/P25RX.h +++ b/p25/P25RX.h @@ -1,17 +1,19 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2017-2024 Bryan Biedenkapp, N2PLL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2015,2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2017-2024 Bryan Biedenkapp, N2PLL -* -*/ + * @file P25RX.h + * @ingroup p25_mfw + * @file P25RX.h + * @ingroup p25_mfw + */ #if !defined(__P25_RX_H__) #define __P25_RX_H__ @@ -24,32 +26,53 @@ namespace p25 // Constants // --------------------------------------------------------------------------- + /** + * @brief P25 Receiver State + */ enum P25RX_STATE { - P25RXS_NONE, - P25RXS_SYNC, - P25RXS_VOICE, - P25RXS_DATA + P25RXS_NONE, //! None + P25RXS_SYNC, //! Found Sync + P25RXS_VOICE, //! Voice Data + P25RXS_DATA //! PDU Data }; // --------------------------------------------------------------------------- // Class Declaration - // Implements receiver logic for P25 mode operation. // --------------------------------------------------------------------------- + /** + * @brief Implements receiver logic for P25 mode operation. + * @ingroup p25_mfw + */ class DSP_FW_API P25RX { public: - /// Initializes a new instance of the P25RX class. + /** + * @brief Initializes a new instance of the P25RX class. + */ P25RX(); - /// Helper to reset data values to defaults. + /** + * @brief Helper to reset data values to defaults. + */ void reset(); - /// Sample P25 values from the air interface. + /** + * @brief Sample P25 values from the air interface. + * @param[in] samples + * @param rssi + * @param length + */ void samples(const q15_t* samples, uint16_t* rssi, uint8_t length); - /// Sets the P25 NAC. + /** + * @brief Sets the P25 NAC. + * @param nac Network Access Code. + */ void setNAC(uint16_t nac); - /// Sets the P25 sync correlation countdown. + /** + * @brief Sets the P25 sync correlation countdown. + * @param count Sync Correlation Countdown. + */ void setCorrCount(uint8_t count); private: @@ -88,22 +111,50 @@ namespace p25 uint32_t m_rssiAccum; uint16_t m_rssiCount; - /// Helper to process P25 samples. + /** + * @brief Helper to process P25 samples. + * @param sample + */ void processSample(q15_t sample); - /// Helper to process LDU P25 samples. + /** + * @brief Helper to process LDU P25 samples. + * @param sample + */ void processVoice(q15_t sample); - /// Helper to process PDU P25 samples. + /** + * @brief Helper to process PDU P25 samples. + * @param sample + */ void processData(q15_t sample); - /// Frame synchronization correlator. + /** + * @brief Frame synchronization correlator. + * @returns bool + */ bool correlateSync(); - /// Helper to decode the P25 NID. + /** + * @brief Helper to decode the P25 NID. + * @param start + * @returns bool True, if P25 NID was decoded, otherwise false. + */ bool decodeNid(uint16_t start); - /// + /** + * @brief + * @param start + * @param count + */ void calculateLevels(uint16_t start, uint16_t count); - /// + /** + * @brief + * @param start + * @param count + * @param buffer + * @param offset + * @param centre + * @param threshold + */ void samplesToBits(uint16_t start, uint16_t count, uint8_t* buffer, uint16_t offset, q15_t centre, q15_t threshold); }; } // namespace p25 diff --git a/p25/P25TX.cpp b/p25/P25TX.cpp index bf58710..04cd71a 100644 --- a/p25/P25TX.cpp +++ b/p25/P25TX.cpp @@ -1,18 +1,14 @@ // SPDX-License-Identifier: GPL-2.0-only -/** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2016,2017 Jonathan Naylor, G4KLX -* Copyright (C) 2017 Andy Uribe, CA6JAU -* Copyright (C) 2020-2022 Bryan Biedenkapp, N2PLL -* -*/ +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2016,2017 Jonathan Naylor, G4KLX + * Copyright (C) 2017 Andy Uribe, CA6JAU + * Copyright (C) 2020-2022 Bryan Biedenkapp, N2PLL + * + */ #include "Globals.h" #include "p25/P25TX.h" #include "p25/P25Defines.h" @@ -58,9 +54,8 @@ const q15_t P25_LEVELD = -1220; // Public Class Members // --------------------------------------------------------------------------- -/// -/// Initializes a new instance of the P25TX class. -/// +/* Initializes a new instance of the P25TX class. */ + P25TX::P25TX() : m_fifo(P25_TX_BUFFER_LEN), m_state(P25TXSTATE_NORMAL), @@ -90,9 +85,8 @@ P25TX::P25TX() : m_lpFilter.pCoeffs = LOWPASS_FILTER; } -/// -/// Process local buffer and transmit on the air interface. -/// +/* Process local buffer and transmit on the air interface. */ + void P25TX::process() { if (m_fifo.getData() == 0U && m_poLen == 0U && m_tailCnt > 0U && @@ -155,12 +149,8 @@ void P25TX::process() } } -/// -/// Write data to the local buffer. -/// -/// -/// -/// +/* Write data to the local buffer. */ + uint8_t P25TX::writeData(const uint8_t* data, uint8_t length) { if (length < (P25_TDU_FRAME_LENGTH_BYTES + 1U)) @@ -180,18 +170,15 @@ uint8_t P25TX::writeData(const uint8_t* data, uint8_t length) return RSN_OK; } -/// -/// Clears the local buffer. -/// +/* Clears the local buffer. */ + void P25TX::clear() { m_fifo.reset(); } -/// -/// Sets the FDMA preamble count. -/// -/// Count of preambles. +/* Sets the FDMA preamble count. */ + void P25TX::setPreambleCount(uint8_t preambleCnt) { m_preambleCnt = P25_FIXED_DELAY + preambleCnt; @@ -201,10 +188,8 @@ void P25TX::setPreambleCount(uint8_t preambleCnt) m_preambleCnt = 1200U; } -/// -/// Sets the Tx hang time. -/// -/// Transmit hang time in seconds. +/* Sets the Tx hang time. */ + void P25TX::setTxHang(uint8_t txHang) { if (txHang > 0U) @@ -217,11 +202,8 @@ void P25TX::setTxHang(uint8_t txHang) m_txHang = 13U * 1200U; } -/// -/// Sets the fine adjust 4FSK symbol levels. -/// -/// +3/-3 symbol adjust. -/// +1/-1 symbol adjust. +/* Sets the fine adjust 4FSK symbol levels. */ + void P25TX::setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj) { m_symLevel3Adj = level3Adj; @@ -240,29 +222,23 @@ void P25TX::setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj) m_symLevel1Adj = 0; } -/// -/// Helper to set the calibration state for Tx. -/// -/// +/* Helper to set the calibration state for Tx. */ + void P25TX::setCal(bool start) { m_state = start ? P25TXSTATE_CAL : P25TXSTATE_NORMAL; } -/// -/// Helper to resize the FIFO buffer. -/// -/// +/* Helper to resize the FIFO buffer. */ + void P25TX::resizeBuffer(uint16_t size) { m_fifo.reset(); m_fifo.reinitialize(size); } -/// -/// Helper to get how much space the ring buffer has for samples. -/// -/// +/* Helper to get how much space the ring buffer has for samples. */ + uint8_t P25TX::getSpace() const { return m_fifo.getSpace() / P25_LDU_FRAME_LENGTH_BYTES; @@ -272,9 +248,8 @@ uint8_t P25TX::getSpace() const // Private Class Members // --------------------------------------------------------------------------- -/// -/// -/// +/* Helper to generate data. */ + void P25TX::createData() { if (!m_tx) { @@ -292,9 +267,8 @@ void P25TX::createData() m_poPtr = 0U; } -/// -/// -/// +/* Helper to generate calibration data. */ + void P25TX::createCal() { // 1.2 kHz sine wave generation @@ -310,10 +284,8 @@ void P25TX::createCal() m_poPtr = 0U; } -/// -/// -/// -/// +/* Helper to write a raw byte to the DAC. */ + void P25TX::writeByte(uint8_t c) { q15_t inBuffer[4U]; @@ -346,9 +318,8 @@ void P25TX::writeByte(uint8_t c) io.write(STATE_P25, outBuffer, P25_RADIO_SYMBOL_LENGTH * 4U); } -/// -/// -/// +/* */ + void P25TX::writeSilence() { q15_t inBuffer[4U] = { 0x00U, 0x00U, 0x00U, 0x00U }; diff --git a/p25/P25TX.h b/p25/P25TX.h index b43986f..03bff3e 100644 --- a/p25/P25TX.h +++ b/p25/P25TX.h @@ -1,17 +1,19 @@ // SPDX-License-Identifier: GPL-2.0-only +/* + * Digital Voice Modem - Modem Firmware + * GPLv2 Open Source. Use is subject to license terms. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright (C) 2016,2017,2020 Jonathan Naylor, G4KLX + * Copyright (C) 2020-2022 Bryan Biedenkapp, N2PLL + * + */ /** -* Digital Voice Modem - Modem Firmware -* GPLv2 Open Source. Use is subject to license terms. -* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -* -* @package DVM / Modem Firmware -* @derivedfrom MMDVM (https://github.com/g4klx/MMDVM) -* @license GPLv2 License (https://opensource.org/licenses/GPL-2.0) -* -* Copyright (C) 2016,2017,2020 Jonathan Naylor, G4KLX -* Copyright (C) 2020-2022 Bryan Biedenkapp, N2PLL -* -*/ + * @file P25TX.h + * @ingroup p25_mfw + * @file P25TX.h + * @ingroup p25_mfw + */ #if !defined(__P25_TX_H__) #define __P25_TX_H__ @@ -27,43 +29,79 @@ namespace p25 #define P25_FIXED_DELAY 90 // 90 = 20ms #define P25_FIXED_TX_HANG 750 // 750 = 625ms + /** + * @brief P25 Transmitter State + */ enum P25TXSTATE { - P25TXSTATE_NORMAL, - P25TXSTATE_CAL + P25TXSTATE_NORMAL, //! Normal + P25TXSTATE_CAL //! Calibration }; // --------------------------------------------------------------------------- // Class Declaration - // Implements transmitter logic for P25 mode operation. // --------------------------------------------------------------------------- + /** + * @brief Implements transmitter logic for P25 mode operation. + * @ingroup p25_mfw + */ class DSP_FW_API P25TX { public: - /// Initializes a new instance of the P25TX class. + /** + * @brief Initializes a new instance of the P25TX class. + */ P25TX(); - /// Process local buffer and transmit on the air interface. + /** + * @brief Process local buffer and transmit on the air interface. + */ void process(); - /// Write data to the local buffer. + /** + * @brief Write data to the local buffer. + * @param[in] data Buffer. + * @param length Length of buffer. + * @returns uint8_t Reason code. + */ uint8_t writeData(const uint8_t* data, uint8_t length); - /// Clears the local buffer. + /** + * @brief Clears the local buffer. + */ void clear(); - /// Sets the FDMA preamble count. + /** + * @brief Sets the FDMA preamble count. + * @param preambleCnt FDMA preamble count. + */ void setPreambleCount(uint8_t preambleCnt); - /// Sets the transmit hang time. + /** + * @brief Sets the transmit hang time. + * @param txHang Transmit hang time. + */ void setTxHang(uint8_t txHang); - /// Sets the fine adjust 4FSK symbol levels. + /** + * @brief Sets the fine adjust 4FSK symbol levels. + * @param level3Adj +3/-3 Level Adjustment + * @param level1Adj +1/-1 Level Adjustment + */ void setSymbolLvlAdj(int8_t level3Adj, int8_t level1Adj); - /// Helper to set the calibration state for Tx. + /** + * @brief Helper to set the calibration state for Tx. + * @param start + */ void setCal(bool start); - /// Helper to resize the FIFO buffer. + /** + * @brief Helper to resize the FIFO buffer. + * @param size + */ void resizeBuffer(uint16_t size); - /// Helper to get how much space the ring buffer has for samples. + /** + * @brief Helper to get how much space the ring buffer has for samples. + * @returns uint8_t Amount of space in ring buffer for samples. + */ uint8_t getSpace() const; private: @@ -88,14 +126,23 @@ namespace p25 int8_t m_symLevel3Adj; int8_t m_symLevel1Adj; - /// + /** + * @brief Helper to generate data. + */ void createData(); - /// + /** + * @brief Helper to generate calibration data. + */ void createCal(); - /// + /** + * @brief Helper to write a raw byte to the DAC. + * @param c Byte. + */ void writeByte(uint8_t c); - /// + /** + * @brief + */ void writeSilence(); }; } // namespace p25