diff options
Diffstat (limited to 'src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design')
7 files changed, 174 insertions, 0 deletions
diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/BluetoothAdapter.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/BluetoothAdapter.txt new file mode 100644 index 0000000000..970aeffd83 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/BluetoothAdapter.txt @@ -0,0 +1,19 @@ +/** @page components_transportmanager_internal_design_transport_adapters_bluetooth_adapter Bluetooth Adapter + * + * Bluetooth adapter handles communication with external devices via bluetooth. It is implemented in + * NsSmartDeviceLink::NsTransportManager::CBluetoothAdapter. + * + * @section components_transportmanager_internal_design_transport_adapters_bluetooth_adapter_discovery Device discovery + * + * When requested by a call to NsSmartDeviceLink::NsTransportManager::CTransportAdapter::scanForNewDevices() bluetooth adapter + * searches for bluetooth devices. For each found device it runs SDP query for service with SmartDeviceLink UUID + * (936DA01F-9ABD-4D9D-80C7-02AF85C822A8). Devices that support this service are added to bluetooth adapter device list. + * Bluetooth device scans are performed only when explicitly requested. + * + * @section components_transportmanager_internal_design_transport_adapters_bluetooth_adapter_connecting_devices Connecting devices + * + * NsSmartDeviceLink::NsTransportManager::CBluetoothAdapter::createConnectionsListForDevice() runs SDP query for specified device + * and fills connection list with connections to all RFCOMM channels on remote device where SmartDeviceLink service has been discovered. + * + * @see @ref components_transportmanager_internal_design_transport_adapters_common_connecting_devices + */ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/TCPAdapter.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/TCPAdapter.txt new file mode 100644 index 0000000000..d81b70dfe8 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/TCPAdapter.txt @@ -0,0 +1,20 @@ +/** @page components_transportmanager_internal_design_transport_adapters_tcp_adapter TCP Adapter + * + * TCP adapter handles communication with remote devices via TCP/IP socket. It is implemented in + * NsSmartDeviceLink::NsTransportManager::CTCPAdapter. + * + * @section components_transportmanager_internal_design_transport_adapters_tcp_adapter_listen Listening for connections + * + * TCP adapter creates listening TCP socket (TCP port is specified in NsSmartDeviceLink::NsTransportManager::CTCPAdapter::cTCPAdapterPort) + * and listens for incoming connections. Devices are identified by their IP address. + * + * @section components_transportmanager_internal_design_transport_adapters_tcp_adapter_accept Accepting connection + * + * When TCP adapter accepts connection it checks if there is a device with IP address matching with IP address of accepted connection. + * If there is no such device, then this device is added and device list is updated. + * + * @section components_transportmanager_internal_design_transport_adapters_tcp_adapter_disconnecting Disconnecting + * + * When socket gets disconnected TCP adapter checks if there is another opened connection for IP address of disconnected application. + * If it was the last application from this IP address then device with this IP address is removed and devices list is updated. + */ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt new file mode 100644 index 0000000000..3a5d0f0e91 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt @@ -0,0 +1,89 @@ +/** @page components_transportmanager_internal_design_transport_adapters Device Adapters + * + * TransportManager communicates with actual devices via device adapters. + * + * @section components_transportmanager_internal_design_transport_adapters_common Common logic + * + * Logic common to all device adapters is implemented in class NsSmartDeviceLink::NsTransportManager::CTransportAdapter. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_devices_map Devices map + * + * Devices map is a map of device handle to internal device structure NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SDevice. + * Devices map is stored in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDevices. Any access to this map must be performed + * with NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDevicesMutex locked. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_connections_map Connections map + * + * Connections map is a map of connection handle to internal connection structure NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection. + * Connections map is stored in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mConnections. Any access to this map must be performed + * with NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mConnectionsMutex locked. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_main_thread Device adapter main thread + * + * Device adapter main thread is started in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::run(). + * Specific device adapter must implement virtual function NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mainThread() + * and implement its specific main thread logic there. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_connection_thread Device adapter connection thread + * + * Device adapter connection thread is started in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::startConnection(). + * Specific device adapter must implement virtual function NsSmartDeviceLink::NsTransportManager::CTransportAdapter::connectionThread() + * and implement its specific connection thread logic there. When connection is established and socket file descriptor is set + * in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mConnectionSocket specific device adapter may call + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::handleCommunication() to handle all communication through this socket + * until connection is terminated. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_threads_termination Termination of device adapter threads + * + * Specific device adapter implementation must call in its destructor NsSmartDeviceLink::NsTransportManager::CTransportAdapter::waitForThreadsTermination() + * to wait for termination of all threads (main thread and connection threads). Device adapter threads must be terminated before specific + * device adapter class is destructed, so it can't be called in the destructor of base class and must be called explicitly from the inherited + * class's destructor. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_device_scan Requesting scan for new devices + * + * Device scan is requested by setting flag NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDeviceScanRequested + * and signaling conditional variable NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDeviceScanRequestedCond, which may be monitored + * by specific device adapter if it supports device scanning. Specific device adaptere may call for this purpose + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::waitForDeviceScanRequest() which will wait on this conditional variable + * until it's signaled or specified timeout expires. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_connecting_devices Connecting devices + * + * Device connection is initiated with a call to NsSmartDeviceLink::NsTransportManager::CTransportAdapter::connectDevice(). + * This method calls virtual function NsSmartDeviceLink::NsTransportManager::CTransportAdapter::createConnectionsListForDevice() + * which may be implemented by specific device adapter to create a list of connections that must be established for the device. + * For each connection created by device adapter it calls NsSmartDeviceLink::NsTransportManager::CTransportAdapter::startConnection() + * which adds connection to connections map and starts connection thread. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_disconnecting_devices Disconnecting devices + * + * Device disconnection is initiated with a call to NsSmartDeviceLink::NsTransportManager::CTransportAdapter::disconnectDevice(). + * This method finds all connections in connections map that corresponds to specified device and calls + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::stopConnection() for each of them. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_handling_communication Handling communication + * + * All frames requested to be sent via NsSmartDeviceLink::NsTransportManager::CTransportAdapter::sendFrame() are stored in + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mFramesToSend. Pipe + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mNotificationPipeFds is used by + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::sendFrame() to notify connection thread that data is available + * to be sent. NsSmartDeviceLink::NsTransportManager::CTransportAdapter::sendFrame() writes one byte to the write end of this pipe. + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::handleCommunication() uses poll() to wait for + * incoming data using connection socket file descriptor and outgoing data using file descriptor of the read end of this pipe. + * When either of them become available for reading or some error occurs (e.g. socket gets disconnected) connection thread + * wakes up and handles this event. Notification pipe is also used to notify connection thread that connection has to be + * terminated using NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mTerminateFlag. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_update_client_device_list Updating client device list. + * + * Specific device adapter may call NsSmartDeviceLink::NsTransportManager::CTransportAdapter::updateClientDeviceList() when its internal + * knowledge about available devices is updated to notify device adapter client (TransportManager) about this update. + * + * @section components_transportmanager_internal_design_transport_adapters_common_specific Specific device adapters + * + * Current TransportManager implementation contains following device adapters: + * + * - @subpage components_transportmanager_internal_design_transport_adapters_bluetooth_adapter "Bluetooth Adapter" + * - @subpage components_transportmanager_internal_design_transport_adapters_tcp_adapter "TCP Adapter" + */ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Interaction.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Interaction.txt new file mode 100644 index 0000000000..655d0a1290 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Interaction.txt @@ -0,0 +1,7 @@ +/*! \page components_transportmanager_internal_design_interaction Sub-Components Interaction + +Internally Transport Manager is a root component for Device Adapters. After running Transport Manager creates Device Adapters and runs them too. + +During system life cycle all messages from Device Adapter are translated via Transport Manager to the clients. In other direction – all requests from clients are re-directed to respective Device Adapters by the Transport Manager. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/MultiThreading.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/MultiThreading.txt new file mode 100644 index 0000000000..6c35f0962f --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/MultiThreading.txt @@ -0,0 +1,9 @@ +/*! \page components_transportmanager_internal_design_multithreading Multi-Threading in Component + +Internally Transport Manager uses different threads for different operations. This design solution was used to provide efficient asynchronous communication with clients and underlying Device Adapters. + +Transport Manager uses one thread to operate with all device-related callbacks. In other word all callbacks declared in NsSmartDeviceLink::NsTransportManager::ITransportManagerDeviceListener will be called from that thread. + +For every active connection one service thread will be created. This thread will be used for all connection-related callbacks. Therefore every implementation of NsSmartDeviceLink::NsTransportManager::ITransportManagerDataListener will be called in separated thread that allows client to support multiple connection simultaneously. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/TrasportManager.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/TrasportManager.txt new file mode 100644 index 0000000000..c96fd46a22 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/TrasportManager.txt @@ -0,0 +1,15 @@ +/*! \page components_transportmanager_internal_design_trasport_manager Trasport Manager Implementation + +Actually Transport Manager component is implemented as classical manager component. It manages connections and abstract devices and provides unified information for the clients. + +Connection-related information encapsulated in structure NsSmartDeviceLink::NsTransportManager::CTransportManager::SConnectionInfo. Transport Manager manages these structures to store information about every active connection. + +Frame processing encapsulated in structure NsSmartDeviceLink::NsTransportManager::CTransportManager::SFrameDataForConnection. Transport Manager manages these structures to store information related to data for specific connection. + +Callback information between transport manager threads passed in form of special structures: +NsSmartDeviceLink::NsTransportManager::CTransportManager::SDeviceListenerCallback. +NsSmartDeviceLink::NsTransportManager::CTransportManager::SDataListenerCallback. + +Client calls to TM guarded by separate mutex. This allows use component from different threads without any risk. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/index.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/index.txt new file mode 100644 index 0000000000..b29ec48dd1 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/index.txt @@ -0,0 +1,15 @@ +/*! \page components_transportmanager_internal_design Component Internal Design + +This chapter is focused on Transport Manager internal design and describes internal sub-components and use of multi-threading. + +Information regarding sub-components is described in following topics: + - \subpage components_transportmanager_internal_design_transport_adapters "Device Adapters" + - \subpage components_transportmanager_internal_design_trasport_manager "Trasport Manager Implementation" + +Detailed description of sub-components interaction is described here: + - \subpage components_transportmanager_internal_design_interaction "Sub-Components Interaction" + +More information about internal usage of multi-threading id described here: + - \subpage components_transportmanager_internal_design_multithreading "Multi-Threading in Component" + +*/ |