1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 /** 19 * @file pvmf_port_base_impl.h 20 */ 21 #ifndef PVMF_PORT_BASE_IMPL_H_INCLUDED 22 #define PVMF_PORT_BASE_IMPL_H_INCLUDED 23 24 #ifndef OSCL_BASE_H_INCLUDED 25 #include "oscl_base.h" 26 #endif 27 #ifndef OSCL_QUEUE_H_INCLUDED 28 #include "oscl_queue.h" 29 #endif 30 #ifndef PVLOGGER_H_INCLUDED 31 #include "pvlogger.h" 32 #endif 33 #ifndef PVMF_PORT_INTERFACE_H_INCLUDED 34 #include "pvmf_port_interface.h" 35 #endif 36 #ifndef OSCL_STRING_CONTAINERS_H_INCLUDED 37 #include "oscl_string_containers.h" 38 #endif 39 #ifndef PVMF_MEDIA_DATA_H_INCLUDED 40 #include "pvmf_media_data.h" 41 #endif 42 43 /** 44 * When this macro is defined to 1, statistics of this port will be tracked and can be 45 * retrieved for debugging and performance analysis. 46 */ 47 #define PVMF_PORT_BASE_IMPL_STATS (PVLOGGER_INST_LEVEL >= PVLOGMSG_INST_MLDBG) 48 49 /** Structure containing statistics of a port */ 50 struct PvmfPortBaseImplStats 51 { 52 uint32 iOutgoingMsgQueued; /**< Number of outgoing messages queued */ 53 uint32 iOutgoingMsgSent; /**< Number of outgoing messages sent */ 54 uint32 iOutgoingMsgDiscarded; /**< Number of outgoing messages discarded */ 55 uint32 iOutgoingQueueBusy; /**< Number of times outgoing message queue became busy */ 56 uint32 iConnectedPortBusy; /**< Number of times connected port became busy */ 57 uint32 iIncomingMsgRecv; /**< Number of incoming messages received */ 58 uint32 iIncomingMsgConsumed; /**< Number of incoming messages dequeued by the node */ 59 uint32 iIncomingQueueBusy; /**< Number of times incoming message queue became busy */ 60 }; 61 62 /** Queue structure */ 63 class PvmfPortBaseImplQueue 64 { 65 public: 66 void Construct(uint32 aCap, uint32 aReserve, uint32 aThresh); 67 PVMFStatus SetCapacity(uint32); 68 PVMFStatus SetReserve(uint32); 69 PVMFStatus SetThreshold(uint32); 70 71 Oscl_Queue<PVMFSharedMediaMsgPtr, OsclMemAllocator> iQ; 72 73 // Flow control 74 uint32 iCapacity; 75 uint32 iThresholdPercent; /**< Threshold for allowing new messages, in terms of percentage of capacity. */ 76 uint32 iThreshold; /**< Threshold size for allowing new messages */ 77 bool iBusy; 78 }; 79 /** Queue type */ 80 enum TPvmfPortBaseImplQueueType 81 { 82 EPVIncomingDataQueue 83 , EPVOutgoingDataQueue 84 }; 85 86 /** Default data queue capacity */ 87 const uint32 DEFAULT_DATA_QUEUE_CAPACITY = 10; 88 89 /** 90 * Threshold in terms of percentage of the total queue size at which a data queue 91 * will be ready to resume receiving data. After the reaching the maximum queue size 92 * the port would wait until enough queued messages are processed such that the queue 93 * size drops below this threshold before notifying the sender port / node to resume 94 * sending data. 95 */ 96 const uint32 DEFAULT_READY_TO_RECEIVE_THRESHOLD_PERCENT = 60; 97 98 /** 99 * Base implementation of PVMFPortInterface. This implementation provides an incoming 100 * and an outgoing queue for media messages, and depends on the PVMF Node that owns 101 * this port on processing these messages asynchronously. The node will be notified 102 * of the events occurred to this port, and the node implementation will need to 103 * handle these message as necessary in order for this base port implementation to 104 * function. This implementation does not perform capability exchange when two ports 105 * are establishing a connection. The final implementation of a port should derive 106 * from this class and the PvmiConfigAndCapability interface for full functionality 107 * with capability and data exchange. 108 */ 109 class PvmfPortBaseImpl : public PVMFPortInterface 110 { 111 public: 112 /** 113 * Default constructor. Data queue size and ready to receive threshold will be set to 114 * default values. 115 * 116 * @param aTag Port tag associated to this port 117 * @param aNode The node that owns this port. Port events will be reported to this node. 118 * @param name Optional port name. If a name is provided, then datapath logging will 119 * be activated on the port. 120 */ 121 OSCL_IMPORT_REF PvmfPortBaseImpl(int32 aPortTag, PVMFPortActivityHandler* aNode, const char*name = NULL); 122 123 /** 124 * Constructor specifying the data queue size and ready to receive threshold. 125 * 126 * @param aTag Port tag associated to this port 127 * @param aNode The node that owns this port. Port events will be reported to this node. 128 * @param aSize Data queue capacity. The data queue size will not grow beyond this capacity. 129 * @param aReserve Size of data queue for which memory is reserved. This must be 130 * less than or equal to the capacity. If this is less than capacity, memory will be 131 * allocated when the queue grows beyond the reserve size, but will stop growing at 132 * capacity. 133 * @param aThreshold Ready-to-receive threshold, in terms of percentage of the data queue capacity. 134 * This value should be between 0 - 100. 135 * @param name Optional port name. If a name is provided, then datapath logging will 136 * be activated on the port. 137 */ 138 OSCL_IMPORT_REF PvmfPortBaseImpl(int32 aTag 139 , PVMFPortActivityHandler* aNode 140 , uint32 aInputCapacity 141 , uint32 aInputReserve 142 , uint32 aInputThreshold 143 , uint32 aOutputCapacity 144 , uint32 aOutputReserve 145 , uint32 aOutputThreshold 146 , const char*name = NULL); 147 148 /** Destructor */ 149 OSCL_IMPORT_REF virtual ~PvmfPortBaseImpl(); 150 OSCL_IMPORT_REF virtual int32 GetPortTag() const;/*{ return iTag; }*/ 151 OSCL_IMPORT_REF virtual PVMFStatus Connect(PVMFPortInterface* aPort); 152 OSCL_IMPORT_REF virtual PVMFStatus Disconnect(); 153 OSCL_IMPORT_REF virtual PVMFStatus PeerConnect(PVMFPortInterface* aPort); 154 OSCL_IMPORT_REF virtual PVMFStatus PeerDisconnect() ; 155 OSCL_IMPORT_REF virtual PVMFStatus QueueOutgoingMsg(PVMFSharedMediaMsgPtr aMsg); 156 OSCL_IMPORT_REF virtual PVMFStatus Send(); 157 OSCL_IMPORT_REF virtual PVMFStatus Receive(PVMFSharedMediaMsgPtr aMsg); 158 OSCL_IMPORT_REF virtual PVMFStatus DequeueIncomingMsg(PVMFSharedMediaMsgPtr& aMsg); 159 OSCL_IMPORT_REF virtual PVMFStatus ReadyToReceive(); 160 OSCL_IMPORT_REF virtual PVMFStatus ClearMsgQueues(); 161 OSCL_IMPORT_REF virtual uint32 IncomingMsgQueueSize(); 162 OSCL_IMPORT_REF virtual uint32 OutgoingMsgQueueSize(); 163 OSCL_IMPORT_REF virtual bool IsOutgoingQueueBusy(); 164 OSCL_IMPORT_REF virtual bool IsConnectedPortBusy(); 165 OSCL_IMPORT_REF virtual void SuspendInput(); 166 OSCL_IMPORT_REF virtual void ResumeInput(); 167 168 /** 169 * Return capacity of data queues 170 * @return Capacity of data queues 171 */ 172 OSCL_IMPORT_REF uint32 GetCapacity(TPvmfPortBaseImplQueueType); 173 174 /** 175 * Returns ready-to-receive threshold 176 * @return Ready-to-receive threshold, in terms of percentage of the data queue capacity. 177 */ 178 OSCL_IMPORT_REF uint32 GetThreshold(TPvmfPortBaseImplQueueType); 179 180 /** 181 * Update capacity of the data queues. 182 * 183 * @param aCapacity New capacity of the data queues. 184 * @return Completion status. 185 */ 186 OSCL_IMPORT_REF PVMFStatus SetCapacity(TPvmfPortBaseImplQueueType, uint32 aCapacity); 187 /** 188 * Update reserve of the data queues. 189 * 190 * @param aCapacity New capacity of the data queues. 191 * @return Completion status. 192 */ 193 OSCL_IMPORT_REF PVMFStatus SetReserve(TPvmfPortBaseImplQueueType, uint32 aCapacity); 194 195 /** 196 * Update ready-to-receive threshold, in terms of percentage of the data queue capacity. 197 * 198 * @param aThreshold Ready to receive threshold. This value should be between 0 and 100. 199 * @return Completion status 200 */ 201 OSCL_IMPORT_REF PVMFStatus SetThreshold(TPvmfPortBaseImplQueueType, uint32 aThreshold); 202 203 /** 204 * Return statistics of this port. 205 * @param aStats Output parameter where port statistics will be repoted to. 206 * @return Completion status. 207 */ 208 OSCL_IMPORT_REF PVMFStatus GetStats(PvmfPortBaseImplStats& aStats); 209 210 /** 211 * Reports port activity to the activity handler (usually 212 * the node). 213 */ 214 OSCL_IMPORT_REF void PortActivity(PVMFPortActivityType aActivity); 215 216 /** 217 * Derived classes must override this if they 218 * implement the capability and config interface 219 */ QueryInterface(const PVUuid &,OsclAny * & aPtr)220 virtual void QueryInterface(const PVUuid&, OsclAny*&aPtr) 221 { 222 aPtr = NULL; 223 } 224 225 OSCL_IMPORT_REF void Construct(); 226 OSCL_IMPORT_REF virtual void EvaluateIncomingBusy(); 227 OSCL_IMPORT_REF virtual void EvaluateOutgoingBusy(); 228 OSCL_IMPORT_REF virtual bool isIncomingFull(); 229 OSCL_IMPORT_REF virtual bool isOutgoingFull(); 230 231 // Queues 232 PvmfPortBaseImplQueue iIncomingQueue; 233 PvmfPortBaseImplQueue iOutgoingQueue; 234 235 // Flow control 236 bool iConnectedPortBusy; 237 bool iInputSuspended; 238 239 protected: 240 // Port tag 241 int32 iTag; 242 243 // Logging and statistics 244 PVLogger* iLogger; 245 PvmfPortBaseImplStats iStats; 246 247 //For datapath logging. If a port name is provided, either in 248 //the constructor or by calling SetName, then datapath logging will 249 //be activated on the port. 250 OSCL_IMPORT_REF void SetName(const char*name); 251 OSCL_StackString<20> iPortName; 252 PVLogger* iDatapathLogger; PortName()253 char* PortName() 254 { 255 return iPortName.get_str(); 256 } 257 void LogMediaMsgInfo(PVMFSharedMediaMsgPtr aMediaMsg, const char*, PvmfPortBaseImplQueue&); 258 public: 259 //a couple of functions for use by the nodes to log info about other internal 260 //data queues using the port datapath logger. 261 OSCL_IMPORT_REF void LogMediaMsgInfo(PVMFSharedMediaMsgPtr aMediaMsg, const char*, int32); 262 OSCL_IMPORT_REF void LogMediaDataInfo(PVMFSharedMediaDataPtr aMediaData, const char*, int32); 263 }; 264 265 #endif // PVMF_PORT_BASE_IMPL_H_INCLUDED 266