Added developer documentation on open/close vs start/stop device and SISO and MIMO hardware handling

ReadmeDevelopper.md

@@ -135,4 +135,81 @@ The `plugins` subdirectory contains the associated plugins used to manage device
         - `xxxsinkgui.h/cpp` : Interface GUI
         - `xxxsinklugin/h/cpp` : Interface plugin manager
         - `xxxsink.pro` : Qt .pro file for Windows/Android build
-        
+        
+<h2>Device interface and GUI lifecycle</h2>
+
+<h3>Overview</h3>
+
+Since version 3.4.0 the opening and closing of the physical device has been split off the start and stop methods of the device interface. The opening and closing of the physical device is handled in private methods called from the constructor and destructor of the device interface respectively.
+
+The device interface is itself created in the constructor of the GUI and is deleted at the destruction of the GUI.
+
+//TODO: add screenshot here
+
+The lifecycle of the GUI is controlled from the device selector in the main window using the plugin manager. When there is a change in the hardware device selection (you can also re-cycle the same device this way) validated by the confirmation button (check sign icon). the following steps are executed in sequence:
+
+  - Stop streaming
+  - Delete the current GUI this will in turn delete the device interface and always close the physical device unless the physical device has a SISO or MIMO architecture (more on that later)
+  - Remove the current device API from the relevant buddies lists. Buddies list are effective only for physical devices with SISO or MIMO architecture (more on that later)
+  - Create the new device API 
+  - Add the new device API to the relevant devices APIs buddies list
+  - creates tne new GUI and hence new device interface. This will always open the physical device unless the physical device has a SISO or MIMO architecture
+
+Here is the relevant par ot the code (source side) in the `MainWindow::on_sampleSource_confirmClicked` method:
+
+    deviceUI->m_deviceSourceAPI->stopAcquisition();
+    deviceUI->m_deviceSourceAPI->setSampleSourcePluginGUI(0); // deletes old GUI and input object
+    deviceUI->m_deviceSourceAPI->clearBuddiesLists(); // clear old API buddies lists
+    m_pluginManager->selectSampleSourceByDevice(devicePtr, deviceUI->m_deviceSourceAPI); // sets the new API
+    // add to buddies list
+    ... here it looks for open tabs with the same physical device and adds the deviceUI->m_deviceSourceAPI to the corresponding m_deviceSourceAPI buddies list ...
+    // constructs new GUI and input object
+    QWidget *gui;
+    PluginManager::SamplingDevice *sampleSourceDevice = (PluginManager::SamplingDevice *) devicePtr; // lightweight representation of the device
+    PluginGUI *pluginGUI = sampleSourceDevice->m_plugin->createSampleSourcePluginGUI(sampleSourceDevice->m_deviceId, &gui, deviceUI->m_deviceSourceAPI);
+    deviceUI->m_deviceSourceAPI->setSampleSourcePluginGUI(pluginGUI);
+    deviceUI->m_deviceSourceAPI->setInputGUI(gui, sampleSourceDevice->m_displayName);
+    
+<h3>SISO and MIMO devices support</h3>
+
+Some SDR hardware have Rx/Tx capabilities in a SISO or MIMO configuration. That is a physical device can handle more than one I/Q sample flow in either direction. Such devices supported by SDRangel are the following:
+
+  - SISO full duplex: BladeRF
+  - SISO half duplex: HackRF
+  - MIMO: LimeSDR
+  
+Note that the following would also work for multiple sample channels Rx or Tx only devices but none exists or is supported at this moment.
+  
+In SDRangel there is a complete receiver or transmitter per I/Q sample flow. These transmitters and receivers are visually represented by the Rn and Tn tabs in the main window. They are created and disposed in the way explained in the previous paragraph using the source or sink selection confirmation button. In fact it acts as if each receiver or transmitter was controlled independently. In single input or single output (none at the moment) devices this is a true independence but with SISO or MIMO devices this cannot be the case and although each receiver or transmitter looks like it was handled independently there are things in common that have to be taken into account. For example it all cases the device handle should be unique and opening and closing the device has to be done only once per physical device usage cycle.
+
+This is where the "buddies list" come into play. Receivers exhibit a generic interface in the form of the DeviceSourceAPI class and transmitter have the DeviceSinkAPI with the same role. Through these APIs some information and control can flow between receivers and trasmitters. The point is that all receivers and/or transmitters pertaining to the same physical device must "know" each other in order to be able to exchange information or control each other. For this purpose the DeviceSourceAPI or DeviceSinkAPI maintain a list of DeviceSourceAPI siblings and a list of DeviceSinkAPI siblings called "buddies". Thus any multi flow Rx/Tx configuration can be handled.
+
+The exact behaviour of these coupled receivers and/or transmitters is dependent on the hardware therefore a generic pointer attached to the API can be used to convey any kind of class or structure taylored for the exact hardware use case. Through this structure the state of the receiver or transmitter can be exposed therefore there is one structure per receiver and transmitter in the device interface. This structure may contain pointers to common areas (dynamically allocated) related to the physical device. One such "area" is the device handle which is present in all cases.
+
+Normally the first buddy would create the common areas (through new) and the last would delete them (through delete) and the superstructure would be on the stack of each buddy. Thus through the superstructure copy a buddy would gain access to common areas from another (already present) buddy along with static information from the other buddy. Exchange of dynamic information between buddies is done using message passing.
+
+The degree of entanglement between the different coupled flows in a single hardware can be very different:
+
+  - BladeRF: a single Rx and Tx in SISO configuration loosely coupled:
+    - independent Rx and Tx sample rates
+    - independent Rx and Tx center frequencies
+    - independent Gain, bandwidth, ...
+    - only the device handle and indication of the presence of the XB200 accesory board is common
+    
+  - HackRF: this is a half duplex device. Rx and Tx might appear as tightly coupled but since you can use only one or the other then in fact you can control them differently as this is done in sequence. In fact only the common device handle has to be taken care of
+  
+  - LimeSDR: dual Rx and dual Tx in MIMO configuration. This implies tightly coupling between receivers on one part and transmitter on the other. But in the case of the LimeSDR (LMS7002M chip) there is even a tight coupling between Rx and Tx parts since the ADC/DAC clock is in common which means both have the same base sample rate that can only be varied by the mean of the hardware decimators and interpolators. This means:
+    - Rx share the same sample rate, hardware decimation factor and center frequency
+    - Tx share the same sample rate, hardware interpolation factor and center frequency
+    - Rx and Tx share the same base sample rate (decimation/interpolation apart)
+    - Independent gains, bandwidths, etc... per Rx or Tx channel
+     
+The openDevice and closeDevice methods of the device interface are designed specifically for each physical device type in order to manage the common resources appropriately at receiver or transmitter construction and destruction. For example opening and closing the device and the related device handle is always done this way:
+
+  - openDevice:
+    - check if there is any "buddy" present in one of the lists
+    - if there is a buddy then grab the device handle and use it for next operations
+    - if there is no buddy open the device and store the handle in the common area so it will be visible for future buddies
+   
+  - closeDevice:
+    - if there are no buddies then effectively close the device else just zero out the own copy of the device handle