1 /*

     2 * This component and the accompanying materials are made available

     3 * under the terms of the License "Eclipse Public License v1.0"

     4 * which accompanies this distribution, and is available

     5 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     6 *

     7 * Initial Contributors:

     8 * Accenture Ltd

     9 *

    10 * Contributors:

    11 *

    12 * Description: This file is a part of sound driver for Syborg adaptation.

    13 *

    14 */

    15 

    16 #ifndef VIRTIO_H

    17 #define VIRTIO_H

    18 

    19 /// @file virtio.h

    20 /// @brief Delivers the API for dealing with VirtIo device.

    21 ///

    22 /// Mainly a VirtIo device functionality is accessed through the following entities.

    23 /// <li> MIo that deals with basic io space access

    24 /// <li> MQueue that represents a device's transaction queue, which is usually more then one per device

    25 /// <li> MIoHandler that represents a device, takes care of resource management, device initialisation and MIo and MQueue derived objects' lifetime.

    26 ///

    27 /// @p The idea is that MIo, MQueue and MIoHandler comes as a specific set. On top of which it is possible to build various drivers (e.g. Audio or Ethernet) that are agnostic to these virtio specifics (e.g. flat device tree or full PCI).

    28 ///

    29 /// Currently the implementation is not multithread safe. The assumption is that all the routines are driven from a single DFC.

    30 

    31 #include "virtio_defs.h"

    32 

    33 #include <e32lang.h>

    34 #include <assp.h>

    35 

    36 

    37 #ifdef _ENABLE_SYBORG_VIRTIO_DEBUG

    38 #define SYBORG_VIRTIO_DEBUG(x...) Kern::Printf(x)

    39 #else

    40 #define SYBORG_VIRTIO_DEBUG(x...)

    41 #endif

    42 

    43 #undef ASSERT

    44 #define ASSERT(x) (x) || (Kern::Printf("VirtIo: ASSERTION FAILED: "#x),0);

    45 

    46 

    47 namespace VirtIo

    48 {

    49 

    50 /// @brief type of a buffer token.

    51 typedef TAny* Token;

    52 

    53 /// @brief represents a virtual queue's API.

    54 ///

    55 class MQueue

    56 	{

    57 public:

    58 

    59 	/// @brief Adds a buffer at the end of the queue

    60 	///

    61 	/// @param aScatterList - physical address scatter list

    62 	/// @param aOutNum - number of scatter buffers to be sent to the device

    63 	/// @param aInNum - number of scatter buffers to be received from the device (starting at aOutNum index of scatter list)

    64 	/// @param aToken - a value associated with buffer to be returned by getBuf or used with detachBuf

    65 	virtual TInt AddBuf( const TAddrLen aScatterList[], TUint32 aOutNum, 

    66 		TUint32 aInNum, Token aToken) = 0;

    67 

    68 	/// @brief Returns buffer associated with the least recent completed transaction

    69 	/// @return transaction's Token with \a len set to reflect amount of processed bytes or 

    70 	/// 0 if no completed transaction was found. 

    71 	virtual Token GetBuf( TUint& len ) = 0;

    72 	

    73 	/// @brief Posts queued buffers to the device

    74 	virtual void Sync() = 0;

    75 	

    76 	/// @brief Cancels a specified buffer (if it is not yet posted)

    77 	/// To be used at shutdown

    78 	virtual TInt DetachBuf( Token aToken ) = 0;

    79 	

    80 	/// @brief reenable callbacks

    81 	/// @return ETrue - callbacks reenabled, EFalse - callbacks not reenabled as there are pending buffers in

    82 	/// the DQueue.

    83 	virtual TBool Restart() = 0;

    84 	

    85 	/// @brief returns number of buffers that are posted to the DQueue 

    86 	/// but not yet completed

    87 	virtual TInt Processing() = 0;

    88 	

    89 	/// @brief returns number of times the GetBuf function could be called returning a buffer

    90 	virtual TInt Completed() = 0;

    91 	

    92 	/// Returns Id of the queue

    93 	virtual TUint Id() = 0;

    94 	

    95 	};

    96 

    97 

    98 /// @brief API wrapping the VirtIo IO space access.

    99 class MIo

   100 	{

   101 public:

   102 	virtual void SetQueueBase( TUint aId, TAny* iDescRegion ) = 0;

   103 	virtual TAny* GetQueueBase( TUint aId ) = 0;

   104 	virtual void PostQueue( TUint aId ) = 0;

   105 	virtual void GetDeviceIds( TUint32 &aPeripheralId, TUint32 &aDeviceId ) = 0;

   106 	virtual TUint GetQueueCount( TUint aQId ) = 0;

   107 	virtual TBool EnableInterrupt( TBool aEnable ) = 0;

   108 	virtual void SetStatus( TUint status ) = 0;

   109 	virtual void ClearInteruptStatus() = 0;

   110 	virtual TBool InteruptStatus() = 0;

   111 	

   112 	};

   113 

   114 

   115 class MIoCallback;

   116 

   117 /// @brief represents a VirtIo device's API.

   118 ///

   119 /// An API for a handler that takes care of resources, state and asyncrhonous communication of a VirtIo device. Allocates Queues.

   120 class MIoHandler

   121 	{

   122 public:

   123 	/// returns one of the device's queues.

   124 	virtual MQueue& Queue( TUint aId ) = 0;

   125 	

   126 	/// registers a client for buffer notifications.

   127 	virtual void RegisterClient( MIoCallback* aListener ) = 0;	

   128 	

   129 	/// unregisters a client for buffer notifications.

   130 	virtual void UnregisterClient( MIoCallback* aListener )	= 0;

   131 	};

   132 

   133 /// an interface for a MIoHandler's client to implement.

   134 class MIoCallback

   135 	{

   136 public:

   137 	/// Notifies MIoHandler's client that that a buffer processing has been completed.

   138 	///

   139 	/// @return EFalse to defer subsequent buffer processing in the same callback.

   140 	virtual TBool VirtIoCallback( 

   141 		MIoHandler& aVirtIoHandler, MQueue& aQueue, 

   142 		Token aToken, TUint aBytesTransferred ) = 0;

   143 	};

   144 

   145 /// @brief turns virtual address range into a phys scatter gather list

   146 ///

   147 /// If virtual buffer contains a linear buffer then the 

   148 /// function will create one SGL entry.

   149 ///

   150 /// If function is called with aSGL=0 then it will count the linear physical

   151 /// fragments the buffer is build of. 

   152 ///

   153 ///

   154 /// @return KErrArgument if the virtual buffer contains nonconvertible addresses)

   155 TInt LinearToSGL( TAny* aLinear, TUint aSize, TAddrLen aSGL[], TUint& aSGLCount );

   156 

   157 }

   158 

   159 

   160 #endif