1 /*

     2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 /**

    20  @file

    21  @internalComponent

    22  @released

    23 */

    24 #ifndef __CRYPTOJOBS__

    25 #define __CRYPTOJOBS__

    26 #include <e32cmn.h>

    27 #include <e32ver.h>

    28 #include <e32def.h>

    29 #include <cryptodriver.h>

    30 

    31 #define TRACE_FUNCTION(funcName) do{ static TraceFunction tf( __FILE__ , funcName ); tf.Inc(); }while(0)

    32 

    33 class TraceFunction

    34 	{

    35 public:

    36 	TraceFunction(const char *aFileName, const char *aFunctionName)

    37 		: iFileName(aFileName),

    38 		  iFunctionName(aFunctionName),

    39 		  iHitCount(0),

    40 		  iNext(HeadRef())

    41 		{

    42 		HeadRef() = this;

    43 		}

    44 	

    45 	void Inc()

    46 		{

    47 		++iHitCount;

    48 		}

    49 

    50 static void DumpCounts()

    51 		{

    52 		Kern::Printf("TraceFunction::DumpCounts\n");

    53 		TraceFunction *p = HeadRef();

    54 		while(p)

    55 			{

    56 			Kern::Printf("%d\t%s:%s\n", p->iHitCount, p->iFileName, p->iFunctionName);

    57 			p->iHitCount = 0;

    58 			p = p->iNext;

    59 			}

    60 		}

    61 

    62 IMPORT_C static TraceFunction *&HeadRef();

    63 

    64 private:

    65 	const char *iFileName;

    66 	const char *iFunctionName;

    67 	TUint32 iHitCount;

    68 

    69 	TraceFunction *iNext;

    70 	};

    71 

    72 

    73 class CryptoJob;

    74 class MCryptoJobCallbacks;

    75 class DCryptoJobScheduler : public DBase

    76 	{

    77 public:

    78 	IMPORT_C DCryptoJobScheduler();

    79 	IMPORT_C ~DCryptoJobScheduler();

    80 

    81 	/**

    82 	   ScheduleJob

    83 

    84 	   If job is already queued, and is the current job, and is not

    85 	   already running, attempt to schedule it and return.  Otherwise,

    86 	   if already in the queue, just return.

    87 

    88 	   If the job is not in the queue, then add it - If the queue is

    89 	   empty it is added at the front and we attempt to run it,

    90 	   otherwise we add it second in the queue for later scheduling.

    91 	 */

    92 	IMPORT_C void ScheduleJob(CryptoJob *aJob);

    93 

    94 	/**

    95 	   Abort the job synchronously

    96 

    97 	   In the EReady state call DoReleaseHw derived function which

    98 	   should, before returning, abort the job.

    99 

   100 	   Changes the state to Idle.

   101 	   

   102 	   Removes from the scheduler.

   103 	   

   104 	   The caller is expected to complete any outstanding user request.

   105 	*/

   106 	IMPORT_C void DeScheduleJob(CryptoJob *aJob);

   107 

   108 	/**

   109 	   SliceComplete

   110 

   111 	   Called by a job when the current slice is complete. The job

   112 	   should update its internal state before calling us.

   113 	   

   114 	   The specified job MUST be the current job.

   115 	 */

   116 	IMPORT_C void SliceComplete(CryptoJob *aJob, TInt aStatus);

   117 

   118 	/**

   119 	   JobComplete

   120 

   121 	   Called by a job when the final slice is complete.

   122 	   

   123 	   The specified job MUST be the current job.

   124 	 */

   125 	IMPORT_C void JobComplete(CryptoJob *aJob, TInt aStatus);

   126 private:

   127 	/**

   128 	   Schedule

   129 	   

   130 	   If current job is not running make it run

   131 	 */

   132 	void Schedule(TBool aReschedule);

   133 

   134 	CryptoJob *iJobList;

   135 	};

   136 

   137 

   138 class DCryptoLddChannel;

   139 class CryptoJob

   140 	{

   141 public:

   142 	IMPORT_C CryptoJob();

   143 	IMPORT_C virtual ~CryptoJob();

   144 	virtual void SetDfcQ(TDfcQue *aDfcQue) = 0;

   145 

   146 	IMPORT_C void Stalled();  // This job MUST be the current job

   147 	IMPORT_C void Resume();

   148 	IMPORT_C void DeScheduleJob();

   149 	IMPORT_C void SetRunning(TBool aRunning);

   150 

   151 	virtual void GetToPddBuffer(TUint8 * &aBuf, TUint32 &aBufLen, TBool &aMore) = 0;

   152 	virtual void BytesWrittenToPdd(TUint32 aBytes) = 0;

   153 

   154 	virtual void GetFromPddBuffer(TUint8 * &aBuf, TUint32 &aBufLen, TBool &aMore) = 0;

   155 	virtual void BytesReadFromPdd(TUint32 aBytes) = 0;

   156 

   157 	enum CryptoJobState 

   158 	{

   159 		ECreated, 			// Not registered with LDD factory

   160 		EReadyForFirstRun, 	// Not running, but could run next for the first time

   161 		ERunning,			// H/w is currently working on this job

   162 		EReady,			  	// Is the current job (h/w is setup), but h/w is idle

   163 		EReadyNoSavedState,	// Ready to run

   164 		EReadySavedState,	// Ready to run, but requires state restore

   165 		// EStalled

   166 		//

   167 		// Three cases:-

   168 		//

   169 		// 1) Already got enough data but LDD hasn't read it yet.

   170 		// 2) No space for more h/w output

   171 		// 3) No more data to feed to h/w

   172 		//

   173 		// Ultimately recoverd by the LDD reading/writing data and/or

   174 		// deleting the job.

   175 		EStalled

   176 	};

   177 

   178  	IMPORT_C CryptoJobState State() const;

   179 	

   180 private:

   181 	friend class DCryptoJobScheduler;

   182 	/**

   183 	   

   184 	 */

   185 	virtual void DoSlice(TBool aFirstSlice) = 0;

   186 

   187 	/**

   188 	   DoSaveState

   189 

   190 	   Save the current job h/w state so that the job can be later

   191 	   restored when we are re-scheduled.

   192 

   193 	   If there is state to save it should return ETrue (in which case

   194 	   DoRestoreState will be called before our DoSlice function is

   195 	   next called).

   196 	   

   197 	   If the h/w state does not require saving/restore it should

   198 	   return EFalse.

   199 	*/

   200 	virtual TBool DoSaveState() = 0;

   201 

   202 	/**

   203 	   DoRestoreState

   204 	   

   205 	   Restore the h/w state. The caller will almost certainly call

   206 	   DoSlice just after this to continue the job.

   207 	*/

   208 	virtual void DoRestoreState() = 0;

   209 

   210 	/**

   211 	   DoReleaseHw

   212 	   

   213 	   Only called in state EReady or ERunning

   214 

   215 	   Should abort the operation and release h/w (unhook ISRs etc)

   216 	   before returning.

   217 

   218 	   Later the caller will probably complete the user request...

   219 	 */

   220 	virtual void DoReleaseHw() = 0;

   221 	

   222 	CryptoJobState iState;

   223 

   224 protected:

   225 	DCryptoJobScheduler *iJobScheduler;

   226 	MCryptoJobCallbacks *iCallbacks;

   227 private:

   228 

   229 	CryptoJob *iNext;

   230 	TBool iInJobList;

   231 	};

   232 

   233 class MCryptoJobCallbacks

   234 	{

   235 public:

   236 	/**

   237 	   DataRequired

   238 

   239 	   PDD is requesting more data to process.

   240 

   241 	   Normally the LDD will write one or more bytes into the supplied

   242 	   buffer and return the number of bytes written. It is also legal

   243 	   for the LDD to not write any bytes and return 0.

   244 

   245 	   If not enough bytes are supplied, the PDD will underrun and

   246 	   stall (this function might not be re-called).

   247 

   248 	   The LDD should provide more data to the h/w via the

   249 	   GetToPddBuffer/BytesWrittenToPdd functions.

   250 

   251 	   @return KErrNone or error code

   252 	*/

   253 	virtual TInt DataRequired() = 0;

   254 

   255 	/**

   256 	   DataAvailable

   257 

   258 	   PDD has output data available for copying to the user.

   259 

   260 	   This function will be called when the PDD is running low out

   261 	   space for storing output data of if all input data has been

   262 	   processed.

   263 

   264 	   Normally the LDD would copy all the supplied data to the user.

   265 

   266 	   It is legal for the LDD to copy less bytes, but this may cause

   267 	   and the PDD to overrun and stall (this function might not be

   268 	   re-called).

   269 

   270 	   The LDD should use the GetFromPddBuffer/BytesReadFromPdd

   271 	   functions to read data from the PDD.

   272 

   273 	   @return KErrNone or error code

   274 

   275 	*/

   276 	virtual TInt DataAvailable() = 0;

   277 

   278 	/**

   279 	   JobComplete

   280 

   281 	   The job scheduler has declared this job complete (maybe with an

   282 	   error), and calls this function to tell the LDD to complete the

   283 	   user request.

   284 	*/

   285 	virtual void JobComplete(TInt aResult) = 0;

   286 	};

   287 

   288 

   289 class CryptoJobRandom : public CryptoJob

   290 	{

   291 public:

   292 	/**

   293 	   SetDetails

   294 	   

   295 	   Setup and start job. Results later available via ResultsBuffer()

   296 

   297 	   @param Ptr to the DCryptoJobScheduler for this type of job

   298 	   @param Ptr to the LDD object for MCryptoJobCallbacks

   299 	   @param aNumOfBytes Total number of random numbers the user requires

   300 	*/

   301 	virtual void SetDetails(DCryptoJobScheduler *aJobScheduler, 

   302 							MCryptoJobCallbacks *aCallbacks,

   303 							TUint32 aNumOfBytes) = 0;

   304 	};

   305 

   306 class CryptoJobAes : public CryptoJob

   307 	{

   308 public:

   309 	/**

   310 	   GetKeyBuffer

   311 

   312 	   Get ptr to KEY buffer to copy user data into. Max key length is

   313 	   32 bytes (256 bits)

   314 

   315 	   @param Pointer to key buffer

   316 	*/

   317 	virtual TUint8 *GetKeyBuffer() = 0;

   318 

   319 	/**

   320 	   GetIVBuffer

   321 

   322 	   Get ptr to IV buffer to copy user IV data into. 16 bytes long.

   323 

   324 	   @param Pointer to IV buffer

   325 	*/

   326 	virtual TUint8 *GetIVBuffer() = 0;

   327 

   328 	/**

   329 	   MaxBytes

   330 

   331 	   @param Length of buffer returned by Buffer().

   332 	*/

   333 	virtual TUint32 MaxBytes() const = 0;

   334 

   335 	/**

   336 	   Buffer

   337 

   338 	   Get ptr to PDD buffer to copy user data into and results from

   339 	   Buffer length <= MaxBytes().

   340 

   341 	   @param Pointer to key buffer

   342 	*/

   343 	virtual TUint8 *GetIOBuffer() = 0;

   344 

   345 	/**

   346 	   SetDetails

   347 

   348 	   @param Ptr to the DCryptoJobScheduler for this type of job

   349 	   @param Ptr to the LDD object for MCryptoJobCallbacks

   350 	   @param aEncrypt True requests encryption, false decryption

   351 	   @param aKeyLength Length of key in bytes

   352 	   @param aMode See RCryptoDriver::TChainingMode

   353 	   @return KErrNone or error code

   354 	*/

   355 	virtual TInt SetDetails(DCryptoJobScheduler *aJobScheduler, 

   356 							MCryptoJobCallbacks *aCallbacks,

   357 							TBool aEncrypt, 

   358 							TInt aKeyLengthBytes,

   359 							RCryptoDriver::TChainingMode aMode) = 0;

   360 

   361 	virtual void NotifyReadRequestLength(TUint32 aReadRequestLength) = 0;

   362 	virtual void HwPerfCheck() = 0;

   363 	};

   364 

   365 #endif