From: bruceperens Date: Fri, 30 May 2014 00:46:39 +0000 (+0000) Subject: Add some documentation for doxygen. Add modem_codec2_reverse.cpp, for testing. X-Git-Url: http://git.whiteaudio.com/gitweb/?a=commitdiff_plain;h=945f50adf9603a764092301650b218a3f641fb30;p=freetel-svn-tracking.git Add some documentation for doxygen. Add modem_codec2_reverse.cpp, for testing. git-svn-id: https://svn.code.sf.net/p/freetel/code@1610 01035d8c-6547-0410-b346-abe4f91aad63 --- diff --git a/freedv-server/source/codec2.cpp b/freedv-server/source/codec2.cpp index e1b0bd12..c58e9dca 100644 --- a/freedv-server/source/codec2.cpp +++ b/freedv-server/source/codec2.cpp @@ -25,7 +25,7 @@ namespace FreeDV { public: - /// Instantiate the no-op codec. + /// Instantiate the codec. Codec2(const char *); ~Codec2(); @@ -65,7 +65,7 @@ namespace FreeDV { }; Codec2::Codec2(const char * _parameters) - : Codec("no-op", _parameters), c(0), samples_per(0), bytes_per(0) + : Codec("codec2", _parameters), c(0), samples_per(0), bytes_per(0) { int mode = CODEC2_MODE_1600; @@ -112,7 +112,7 @@ namespace FreeDV { std::size_t bytes_read = 0; std::size_t samples_read = 0; - while ( *data_length >= bytes_per || sample_length >= samples_per ) { + while ( *data_length >= bytes_per && sample_length >= samples_per ) { codec2_decode(c, o, i); *data_length -= bytes_per; @@ -134,7 +134,7 @@ namespace FreeDV { std::size_t bytes_read = 0; std::size_t samples_read = 0; - while ( data_length >= bytes_per || *sample_length >= samples_per ) { + while ( data_length >= bytes_per && *sample_length >= samples_per ) { // FIX: Const cast away. Remove if we can get const correctness in // libcodec2. codec2_encode(c, o, (std::int16_t *)i); diff --git a/freedv-server/source/driver_manager.cpp b/freedv-server/source/driver_manager.cpp index a6686582..0b778d54 100644 --- a/freedv-server/source/driver_manager.cpp +++ b/freedv-server/source/driver_manager.cpp @@ -254,6 +254,11 @@ namespace FreeDV { place(key, (base_creator)creator, enumerator, &user_interface_drivers); } + /// Return the address of the global driver manager. + /// This function is used to avoid the C++ static initialization order fiasco. + /// Any static initialization function that registers a driver calls it, + /// and thus it initializes the driver manager regardless of static + /// initialization order. DriverManager * driver_manager() { diff --git a/freedv-server/source/drivers.h b/freedv-server/source/drivers.h index 6d262583..567af728 100644 --- a/freedv-server/source/drivers.h +++ b/freedv-server/source/drivers.h @@ -414,7 +414,8 @@ public: /// \param i The array of audio samples to be encoded, in an array /// of signed 16-bit integers. /// \param o The encoded data, in an array of unsigned 8-bit integers. - /// \param sample_length On call: The number of audio samples to be + /// \param data_length The number of bytes which may be encoded. + /// \param sample_length On call: The number of audio samples which may be /// encoded. On return: The number of 16-bit audio samples that were /// consumed. /// \return The number of std::uint8_t elements in the encoded array. @@ -802,6 +803,12 @@ Framer * FramerNoOp(const char * parameter); /// KeyingOutput * KeyingSink(const char * parameter); +/// Opens the Reverse Codec2 modem, for debugging. +/// \param parameter +/// \return A pointer to the Modem instance. +/// +Modem * Codec2_Reverse(const char * parameter); + /// Opens the FDMDV2 modem. /// \param parameter /// \return A pointer to the Modem instance. diff --git a/freedv-server/source/global.cpp b/freedv-server/source/global.cpp index f35f1eec..61b67e7c 100644 --- a/freedv-server/source/global.cpp +++ b/freedv-server/source/global.cpp @@ -1,6 +1,9 @@ #include "drivers.h" namespace FreeDV { + /// Global name of the program, for error messages. const char * program_name = 0; + + /// Global driver manager object. DriverManager * _globalDriverManager = 0; } diff --git a/freedv-server/source/hid/hid.cpp b/freedv-server/source/hid/hid.cpp index 85f1f9d7..706f15b0 100644 --- a/freedv-server/source/hid/hid.cpp +++ b/freedv-server/source/hid/hid.cpp @@ -12,8 +12,10 @@ #define INTEGER_64 #endif +/// Structure for parsing USB Human Interface Device reports. struct HIDRaw { public: + /// Type field of a Collection object in a HID report. enum CollectionType { Physical = 0, Application = 1, // Mouse or keyboard. @@ -28,6 +30,7 @@ public: VendorEnd = 0xff }; + /// Type field of a Generic Desktop Usage Page in a HID report. enum GenericDesktop { Undefined = 0x00, Pointer = 0x01, @@ -78,6 +81,7 @@ public: D_pad_Left = 0x93 }; + /// Type field of a Global object in a HID report. enum GlobalType { UsagePage = 0, LogicalMinimum = 1, @@ -93,6 +97,7 @@ public: Pop = 11 }; + /// Type field of a Local object in a HID report. enum LocalType { Usage = 0, UsageMinimum = 1, @@ -105,6 +110,8 @@ public: StringMaximum = 9, Delimiter = 10 }; + + /// Type field of a Main object in a HID report. enum MainType { Input = 0x8, Output = 0x9, @@ -114,12 +121,14 @@ public: LongItem = 0x0f, }; + /// Type of a top-level object in a HID report. enum Type { Main = 0, Global = 1, Local = 2 }; + /// Type of Usage Page in a HID report. enum UsagePageTypes { GenericDesktop = 1, Button = 9 diff --git a/freedv-server/source/keying_sink.cpp b/freedv-server/source/keying_sink.cpp index 75436ecd..dca9e9ab 100644 --- a/freedv-server/source/keying_sink.cpp +++ b/freedv-server/source/keying_sink.cpp @@ -25,7 +25,7 @@ namespace FreeDV { /// \param space The maximum number of file descriptors that may be /// stored in the array. /// \return The number of file descriptors written to the array. - int poll_fds(PollType *, int); + int poll_fds(PollType * array, int space); /// If the value is true, transmit. Otherwise receive. /// diff --git a/freedv-server/source/modem_fdmdv2.cpp b/freedv-server/source/modem_fdmdv2.cpp index a657d2cd..c8b187ef 100644 --- a/freedv-server/source/modem_fdmdv2.cpp +++ b/freedv-server/source/modem_fdmdv2.cpp @@ -14,6 +14,7 @@ namespace FreeDV { /// Modem "FDMDV2". class ModemFDMDV2 : public Modem { public: + /// Modem operation mode. These are given as bit-rate + attributes. enum Mode { M_Invalid = -1, M_1400_V0_91_Legacy = 0, // Broken, and hopefully off-the-air by now. @@ -69,6 +70,8 @@ namespace FreeDV { /// of signed 16-bit integers. /// \param data_length On call: The number of bytes of data to be /// modulated. On return: The number of bytes consumed. + /// \param sample_length The number of audio samples which may be + /// modulated. /// \return The number of 16-bit audio samples in the modulated array. virtual std::size_t modulate16( diff --git a/freedv-server/source/modem_noop.cpp b/freedv-server/source/modem_noop.cpp index 79af2139..b12e9c13 100644 --- a/freedv-server/source/modem_noop.cpp +++ b/freedv-server/source/modem_noop.cpp @@ -47,6 +47,8 @@ namespace FreeDV { /// of signed 16-bit integers. /// \param data_length On call: The number of bytes of data to be /// modulated. On return: The number of bytes consumed. + /// \param sample_length The number of audio samples which may be + /// modulated. /// \return The number of 16-bit audio samples in the modulated array. virtual std::size_t modulate16( diff --git a/freedv-server/source/platform/linux/alsa.cpp b/freedv-server/source/platform/linux/alsa.cpp index 738a6ffe..e38c46a8 100644 --- a/freedv-server/source/platform/linux/alsa.cpp +++ b/freedv-server/source/platform/linux/alsa.cpp @@ -303,11 +303,13 @@ namespace FreeDV { if ((error = snd_pcm_sw_params(handle, sw_params)) < 0) do_throw(error, name, stream, "ALSA set software parameters"); +#if 0 // Dump sound parameters, for debugging. snd_output_t * output = 0; snd_output_stdio_attach(&output, stderr, 0); fprintf(stderr, "%s\n", name); snd_pcm_dump_setup(handle, output); +#endif snd_pcm_sw_params_free(sw_params); diff --git a/freedv-server/source/platform/linux/audio_out_alsa.cpp b/freedv-server/source/platform/linux/audio_out_alsa.cpp index 9d914462..73db6912 100644 --- a/freedv-server/source/platform/linux/audio_out_alsa.cpp +++ b/freedv-server/source/platform/linux/audio_out_alsa.cpp @@ -20,13 +20,15 @@ namespace FreeDV { std::ostream & ALSAEnumerate(std::ostream & stream, snd_pcm_stream_t mode); - // If more than this number of frames are queued for audio output, the - // latency is too high. Flush the output and print an overlong-delay message. + /// Maximum frames that an audio stream may be delayed. + /// If more than this number of frames are queued for audio output, the + /// latency is too high. Flush the output and print an overlong-delay message. const unsigned int MaximumDelayFrames = 4; - // At the start of playback, preload the audio output with this many - // frames of zero data. This delays the output enough to avoid later - // buffer-overrun problems. + /// Number of zeroed frames with which to prime an audio output device. + /// At the start of playback, preload the audio output with this many + /// frames of zero data. This delays the output enough to avoid later + /// buffer-overrun problems. const unsigned int FillFrames = 2; /// Audio output "ALSA", Uses the Linux ALSA Audio API. diff --git a/freedv-server/source/platform/linux/evdev.h b/freedv-server/source/platform/linux/evdev.h index 6b98c32d..6bb2632b 100644 --- a/freedv-server/source/platform/linux/evdev.h +++ b/freedv-server/source/platform/linux/evdev.h @@ -8,8 +8,10 @@ #include "drivers.h" namespace FreeDV { + /// Class used to access Linux event devices. class EvDev { public: + /// Structure used to enumerate Linux event devices. struct device_enumeration { char * special_file; char * name; diff --git a/freedv-server/source/run.cpp b/freedv-server/source/run.cpp index 5834b488..72b59f9f 100644 --- a/freedv-server/source/run.cpp +++ b/freedv-server/source/run.cpp @@ -28,7 +28,9 @@ namespace FreeDV { /// class Run { private: - const std::size_t FIFOSize = MaximumFrameSamples * sizeof(int16_t) * 2; + const std::size_t AudioFIFOSize = + MaximumFrameSamples * sizeof(int16_t) * 2; + const std::size_t CodecFIFOSize = 1024; Interfaces * const i; int poll_fd_count; int poll_fd_base; @@ -70,8 +72,8 @@ namespace FreeDV { Run::Run(Interfaces * interfaces) : i(interfaces), poll_fd_count(0), poll_fd_base(0), output_fd_base(-1), - codec_fifo(FIFOSize), in_fifo(FIFOSize), - out_fifo(FIFOSize) + codec_fifo(CodecFIFOSize), in_fifo(AudioFIFOSize), + out_fifo(AudioFIFOSize) { reset(); }