williamr@4: // Copyright (c) 2004-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@4: // All rights reserved.
williamr@4: // This component and the accompanying materials are made available
williamr@4: // under the terms of the License "Eclipse Public License v1.0"
williamr@4: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@4: //
williamr@4: // Initial Contributors:
williamr@4: // Nokia Corporation - initial contribution.
williamr@4: //
williamr@4: // Contributors:
williamr@4: //
williamr@4: // Description:
williamr@4: // e32\include\drivers\camerasc.h
williamr@4: // 
williamr@4: //
williamr@4: 
williamr@4: /**
williamr@4:  @file
williamr@4:  @internalAll
williamr@4:  @prototype
williamr@4: */
williamr@4: 
williamr@4: #ifndef __CAMERASC_H__
williamr@4: #define __CAMERASC_H__
williamr@4: 
williamr@4: #include <d32camerasc.h>
williamr@4: #include <platform.h>
williamr@4: #include <kernel/kpower.h>
williamr@4: #include <e32ver.h>
williamr@4: 
williamr@4: /** The default number of buffers available to the client. */
williamr@4: const TInt KDefaultNumClientBuffers=6;
williamr@4: 
williamr@4: /** The maximum number of client capture requests which may be outstanding at any time. */
williamr@4: const TInt KMaxCamScRequestsPending=8;
williamr@4: 
williamr@4: /**
williamr@4: @internalAll
williamr@4: @prototype
williamr@4: */
williamr@4: struct SBufSpecList
williamr@4: 	{
williamr@4: 	/** The first entry of the buffer offset list. This list holds the offset from the start of the chunk
williamr@4: 	for each buffer. This list is only valid if the flag KScFlagBufOffsetListInUse is set in
williamr@4: 	TSharedChunkBufConfigBase::iFlags. */
williamr@4: 	TInt iBufferOffset;
williamr@4: 	TInt iBufferId;
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4: @internalAll
williamr@4: @prototype
williamr@4: */
williamr@4: class TCameraSharedChunkBufConfig : public TSharedChunkBufConfigBase
williamr@4: 	{
williamr@4: public:
williamr@4:  	struct SBufSpecList iSpec;
williamr@4: 	};
williamr@4: 
williamr@4: // Forward declarations
williamr@4: class TImageBuffer;
williamr@4: class DCameraScLdd;
williamr@4: class DBufferManager;
williamr@4: 
williamr@4: /**
williamr@4: The physical device driver (PDD) base class for the camera driver.
williamr@4: @internalAll
williamr@4: @prototype
williamr@4: */
williamr@4: class DCameraScPdd : public DBase
williamr@4: 	{
williamr@4: public:
williamr@4: 	/**
williamr@4:     Return the DFC queue to be used by this device.
williamr@4:     @param aUnit The unit number for which to get the DFC queue.
williamr@4:     @return The DFC queue to use.
williamr@4:     */
williamr@4: 	virtual TDfcQue* DfcQ(TInt aUnit)=0;
williamr@4: 
williamr@4: 	/**
williamr@4: 	Return the capabilities of this camera device.
williamr@4: 	@param aCapsBuf A packaged TCameraCapsV02 object to be filled with the capabilities of the
williamr@4: 		device. This descriptor is in kernel memory and can be accessed directly.
williamr@4: 	@see TCameraCapsV02.
williamr@4: 	*/
williamr@4: 	virtual void Caps(TDes8& aCapsBuf) const=0;
williamr@4: 
williamr@4: 	/**
williamr@4: 	Return data format information for a custom camera data format setting. Only required where support is
williamr@4: 	required for a data format that isn't supported by the LDD. Platforms which don't require support
williamr@4: 	for custom data settings need not implement this method.
williamr@4: 	@param aConfigBuf A packaged TCameraConfigV02 object containing the current camera driver configuration
williamr@4: 		(including an identifier for the custom setting required). This configuration object should be
williamr@4: 		updated by the PDD with the appropriate settings for the data format concerned. This descriptor
williamr@4: 		is in kernel memory and can be accessed directly.
williamr@4: 	@return KErrNone if successful, otherwise one of the other system wide error codes.
williamr@4: 	*/
williamr@4: 	virtual TInt SpecifyCustomConfig(TDes8& aConfigBuf);
williamr@4: 
williamr@4: 	/**
williamr@4: 	Return the shared chunk create information to be used by this device.
williamr@4: 	@param aChunkCreateInfo A chunk create info. object to be to be filled with the settings
williamr@4: 							required for this device.
williamr@4: 	*/
williamr@4: 	virtual void GetChunkCreateInfo(TChunkCreateInfo& aChunkCreateInfo)=0;
williamr@4: 
williamr@4: 	/**
williamr@4: 	Configure or reconfigure the device using the the configuration supplied.
williamr@4: 	@param aConfigBuf A packaged TCameraConfigV02 object which contains the new configuration settings.
williamr@4: 		This descriptor is in kernel memory and can be accessed directly.
williamr@4: 	@return KErrNone if successful, otherwise one of the other system wide error codes.
williamr@4: 	@see TCameraConfigV02.
williamr@4: 	*/
williamr@4: 	virtual TInt SetConfig(const TDesC8& aConfigBuf)=0;
williamr@4: 
williamr@4: 	/**
williamr@4:     Start the camera - start pixel sourcing.
williamr@4:     @param aCaptureMode The capture mode to start. @see TDevCamCaptureMode.
williamr@4:     @param aLinAddr The linear address of the start of the first buffer to use for image capture.
williamr@4: 	@param aPhysAddr The physical address that corresponds to the linear address: aLinAddr.
williamr@4:     @return KErrNone if successful;
williamr@4:     		otherwise one of the other system wide error codes.
williamr@4:     */
williamr@4: 	virtual TInt Start(TDevCamCaptureMode aCaptureMode,TLinAddr aLinAddr,TPhysAddr aPhysAddr)=0;
williamr@4: 
williamr@4: 	/**
williamr@4: 	Sets the address of the buffer into which the next image will be captured.
williamr@4:     @param aLinAddr The linear address of the start of the buffer to use to capture the image frame.
williamr@4: 	@param aPhysAddr The physical address that corresponds to the linear address: aLinAddr.
williamr@4:     @return KErrNone if the capture has been initiated successfully;
williamr@4:   			KErrNotReady if the device is unable to accept the request for the moment;
williamr@4: 		  	otherwise one of the other system-wide error codes.
williamr@4:     */
williamr@4: 	virtual TInt CaptureNextImage(TLinAddr aLinAddr,TPhysAddr aPhysAddr)=0;
williamr@4: 
williamr@4: 	/**
williamr@4:     Stop the camera - stop pixel sourcing.
williamr@4:     @return KErrNone if successful, otherwise one of the other system wide error codes.
williamr@4:     */
williamr@4: 	virtual TInt Stop()=0;
williamr@4: 
williamr@4: 	/**
williamr@4: 	Power down the camera.
williamr@4: 	*/
williamr@4: 	virtual void PowerDown()=0;
williamr@4: 
williamr@4: 	/**
williamr@4: 	Queries the driver for the size of the structure to be passed to RDevCameraSc::Caps().
williamr@4: 	*/
williamr@4: 	virtual TInt CapsSize()=0;
williamr@4: 
williamr@4: 	/**
williamr@4: 	Returns the supported frame sizes that correspond to the desired capture mode and pixel format passed in.
williamr@4: 	@param aCaptureMode The capture mode for which to obtain the information.
williamr@4: 	@param aUidPixelFormat The pixel format for which to obtain the information.
williamr@4: 	@param aFrameSizeCapsBuf An appropriately sized buffer to be filled with the supported frame sizes.
williamr@4: 	@return KErrNone, if successful,
williamr@4: 			KErrArgument, if an invalid capture mode or pixel format is specified, or if aFrameSizeCapsBuf is too small;
williamr@4: 			otherwise one of the other system-wide error codes.
williamr@4: 	@see SDevCamFrameSize
williamr@4: 	*/
williamr@4: 	virtual TInt FrameSizeCaps(TDevCamCaptureMode aCaptureMode, TUidPixelFormat aUidPixelFormat, TDes8& aFrameSizeCapsBuf)=0;
williamr@4: 
williamr@4: 	/**
williamr@4: 	Sets the sensor brightness to the desired setting.
williamr@4: 
williamr@4: 	@param aValue A verified brightness setting.
williamr@4: 	@return KErrNone if successful, KErrNotSupported if not supported.
williamr@4: 	*/
williamr@4: 	virtual TInt SetBrightness(TUint aValue) = 0;
williamr@4: 
williamr@4: 	// SYM_BRANCH: Add support for setting of Dynamic Attributes. Contrast.
williamr@4: 	/**
williamr@4: 	Sets the sensor contrast to the desired setting.
williamr@4: 
williamr@4: 	@param aValue A verified contrast setting.
williamr@4: 	@return KErrNone if successful, KErrNotSupported if not supported.
williamr@4: 	*/
williamr@4: 	virtual TInt SetContrast(TUint aValue) = 0;
williamr@4: 
williamr@4: 	// SYM_BRANCH: Add support for setting of Dynamic Attributes. Colour Effect.
williamr@4: 	/**
williamr@4: 	Sets the sensor color effect to the desired setting.
williamr@4: 
williamr@4: 	@param aValue A verified color effect setting.
williamr@4: 	@return KErrNone if successful, KErrNotSupported if not supported.
williamr@4: 	*/
williamr@4: 	virtual TInt SetColorEffect(TUint aValue) = 0;
williamr@4: 
williamr@4: public:
williamr@4: 	DCameraScLdd* iLdd;
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4: The logical device (factory class) for the camera driver.
williamr@4: */
williamr@4: class DCameraScLddFactory : public DLogicalDevice
williamr@4: 	{
williamr@4: public:
williamr@4: 	DCameraScLddFactory();
williamr@4: 	virtual TInt Install();
williamr@4: 	virtual void GetCaps(TDes8 &aDes) const;
williamr@4: 	virtual TInt Create(DLogicalChannelBase*& aChannel);
williamr@4: 	TBool IsUnitOpen(TInt aUnit);
williamr@4: 	TInt SetUnitOpen(TInt aUnit,TBool aIsOpenSetting);
williamr@4: private:
williamr@4: 	/** Mask to keep track of which units have a channel open on them. */
williamr@4: 	TUint iUnitsOpenMask;
williamr@4: 	/** A mutex to protect access to the unit info. mask. */
williamr@4: 	NFastMutex iUnitInfoMutex;
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4: The class representing a single image buffer.
williamr@4: */
williamr@4: class TImageBuffer : public SDblQueLink
williamr@4: 	{
williamr@4: public:
williamr@4: 	TImageBuffer();
williamr@4: 	~TImageBuffer();
williamr@4: 	TInt Create(DChunk* aChunk,TInt aOffset,TInt aSize,TInt aId,TBool aIsContiguous);
williamr@4: 	void SyncMemoryBeforeDmaRead();
williamr@4: 	void SyncMemoryAfterDmaRead();
williamr@4: public:
williamr@4: 	/** The buffer id */
williamr@4: 	TInt iId;
williamr@4: 	/** The chunk used for this buffer */
williamr@4: 	DChunk* iChunk;
williamr@4: 	/** The offset, in bytes, of the start of the buffer within the chunk. */
williamr@4: 	TInt iChunkOffset;
williamr@4: 	/** The size of the buffer in bytes. */
williamr@4: 	TInt iSize;
williamr@4: 	/** The virtual address of buffer. */
williamr@4: 	TLinAddr iLinearAddress;
williamr@4: 	/** The physical address of buffer. KPhysAddrInvalid if the buffer is not physically contiguous. */
williamr@4: 	TPhysAddr iPhysicalAddress;
williamr@4: 	/** A list of physical addresses for buffer pages. 0 if the buffer is physically contiguous. */
williamr@4: 	TPhysAddr* iPhysicalPages;
williamr@4: 	/** This is the result of the transfer into this buffer. */
williamr@4: 	TInt iResult;
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4: An object encapsulating an image capture request from the client.
williamr@4: */
williamr@4: class TCameraScRequest : public SDblQueLink
williamr@4: 	{
williamr@4: public:
williamr@4: 	inline TCameraScRequest()
williamr@4: 		{}
williamr@4: public:
williamr@4: 	/** The request status associated with the request - used to signal completion of the request and pass back a
williamr@4: 	completion code. */
williamr@4: 	TRequestStatus* iStatus;
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4: An object encapsulating a queue of image capture requests from the client.
williamr@4: */
williamr@4: class TCameraScRequestQueue
williamr@4: 	{
williamr@4: public:
williamr@4: 	TCameraScRequestQueue(NFastMutex* aMutexPtr);
williamr@4: 	~TCameraScRequestQueue();
williamr@4: 	TInt Create(DThread* anOwningThread);
williamr@4: 	TInt Add(TRequestStatus* aStatus);
williamr@4: 	TRequestStatus* Remove();
williamr@4: 	void Cancel(TRequestStatus* aStatus);
williamr@4: 	void CancelAll();
williamr@4: 	inline TBool IsEmpty();
williamr@4: private:
williamr@4: 	/** The queue of pending capture requests. */
williamr@4: 	SDblQue iPendRequestQ;
williamr@4: 	/** The queue of unused capture requests. */
williamr@4: 	SDblQue iUnusedRequestQ;
williamr@4: 	/** The actual array of request objects. */
williamr@4: 	TCameraScRequest* iRequest[KMaxCamScRequestsPending];
williamr@4: 	NFastMutex* iMutexPtr;
williamr@4: 	DThread* iOwningThread;
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4: The buffer manager base class.
williamr@4: */
williamr@4: class DBufferManager : public DBase
williamr@4: 	{
williamr@4: public:
williamr@4: 	DBufferManager(DCameraScLdd* aLdd);
williamr@4: 	~DBufferManager();
williamr@4: 	TInt Create(TInt aNumBuffers,TInt aBufferSize);
williamr@4: 	TInt Create(TCameraSharedChunkBufConfig& aBufConfig,TInt aChunkHandle,DThread* anOwningThread);
williamr@4: 	void GetBufConfig(TCameraSharedChunkBufConfig& aBufConfig);
williamr@4: 	void Reset();
williamr@4: 	void Purge(TImageBuffer* aBuffer);
williamr@4: 	TImageBuffer* GetImageForClient(TBool aRemoveLast);
williamr@4: 	TImageBuffer* SetImageCaptured(TInt aResult);
williamr@4: 	TInt ReleaseImage(TInt aChunkOffset);
williamr@4: 	TImageBuffer* NextAvailableForCapture();
williamr@4: 	TImageBuffer* FindInUseImage(TInt aChunkOffset);
williamr@4: protected:
williamr@4: 	TInt CreateBufferLists(TInt aNumBuffers);
williamr@4: 	TInt CommitMemoryForBuffer(TInt aChunkOffset,TInt aSize,TBool& aIsContiguous);
williamr@4: protected:
williamr@4: 	/** The owning LDD object. */
williamr@4: 	DCameraScLdd* iLdd;
williamr@4: 	/** The chunk which contains the buffers. */
williamr@4: 	DChunk* iChunk;
williamr@4: 	/** The linear address in kernel process for the start of the chunk. */
williamr@4: 	TLinAddr iChunkBase;
williamr@4: 	/**< MMU mapping attributes that the chunk has actually been mapped with. */
williamr@4: 	TUint32 iChunkMapAttr;
williamr@4: 	/** The number of buffers. */
williamr@4: 	TInt iNumBuffers;
williamr@4: 	/** The actual array of buffer objects. */
williamr@4: 	TImageBuffer* iImageBuffer;
williamr@4: 	/** The buffer currently being filled by image capture. (Not in any list). */
williamr@4: 	TImageBuffer* iCurrentBuffer;
williamr@4: 	/** The next buffer to use for image capture. (Not in any list). */
williamr@4: 	TImageBuffer* iNextBuffer;
williamr@4: 	/** A queue of those buffers which are currently free. */
williamr@4: 	SDblQue iFreeBufferQ;
williamr@4: 	/** A queue of those buffers which currently contain captured images (and which aren't being used by the client). */
williamr@4: 	SDblQue iCompletedBufferQ;
williamr@4: 	/** A queue of those buffers which are currently being used by the client. */
williamr@4: 	SDblQue iInUseBufferQ;
williamr@4: private:
williamr@4: 	friend class DCameraScLdd;
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4: The configuration class that is specific for each capture mode. This allows the driver to maintain different configurations,
williamr@4: one for each capture mode, and make switching between capture modes faster.
williamr@4: */
williamr@4: class TCaptureModeConfig
williamr@4: 	{
williamr@4: 	private:
williamr@4: 		/** The handle to the chunk that is returned to the user side code. */
williamr@4: 		TInt iChunkHandle;
williamr@4: 		/** The current configuration of the capture mode */
williamr@4: 		TCameraConfigV02 iCamConfig;
williamr@4: 		/** The current configuration of the chunk. */
williamr@4: 		TCameraSharedChunkBufConfig* iBufConfig;
williamr@4: 		/** The size in bytes of the chunk configuration info. structure. */
williamr@4: 		TInt iBufConfigSize;
williamr@4: 		/** The current frame height. */
williamr@4: 		TInt iFrameHeight;
williamr@4: 		/** The current frame width. */
williamr@4: 		TInt iFrameWidth;
williamr@4: 		/** The buffer manager. */
williamr@4: 		DBufferManager* iBufManager;
williamr@4: 	private:
williamr@4: 		friend class DCameraScLdd;
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4: The camera driver power handler class.
williamr@4: */
williamr@4: class DCameraScPowerHandler : public DPowerHandler
williamr@4: 	{
williamr@4: public:
williamr@4: 	DCameraScPowerHandler(DCameraScLdd* aChannel);
williamr@4: 	// Inherited from DPowerHandler
williamr@4: 	void PowerUp();
williamr@4: 	void PowerDown(TPowerState aPowerState);
williamr@4: private:
williamr@4: 	DCameraScLdd* iChannel;
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4: The logical channel class for the camera driver.
williamr@4: */
williamr@4: class DCameraScLdd : public DLogicalChannel
williamr@4: 	{
williamr@4: public:
williamr@4: 	enum TState
williamr@4: 		{
williamr@4: 		/** Channel open - but not configured. */
williamr@4: 		EOpen,
williamr@4: 		/** Channel configured - but inactive. */
williamr@4: 		EConfigured,
williamr@4: 		/** Channel is active - capturing images. */
williamr@4: 		ECapturing
williamr@4: 		};
williamr@4: public:
williamr@4: 	DCameraScLdd();
williamr@4: 	virtual ~DCameraScLdd();
williamr@4: 	// Inherited from DLogicalChannel
williamr@4: 	virtual TInt DoCreate(TInt aUnit, const TDesC8* anInfo, const TVersion& aVer);
williamr@4: 	virtual TInt Request(TInt aReqNo, TAny* a1, TAny* a2);
williamr@4: 	virtual void HandleMsg(TMessageBase* aMsg);
williamr@4: 	virtual TInt RequestUserHandle(DThread* aThread, TOwnerType aType);
williamr@4: 	inline DThread* OwningThread();
williamr@4: 	inline TInt CurrentFrameHeight();
williamr@4: 	inline TInt CurrentFrameWidth();
williamr@4: 	void Shutdown();
williamr@4: 	virtual TInt ImageCaptureCallback(TDevCamCaptureMode aCaptureMode,TInt aResult,TLinAddr* aLinAddr,TPhysAddr* aPhysAddr);
williamr@4: 	virtual void PanicClientThread(TInt aReason);
williamr@4: private:
williamr@4: 	TInt DoControl(TInt aFunction, TAny* a1, TAny* a2);
williamr@4: 	TInt DoRequest(TInt aFunction, TRequestStatus* aStatus, TAny* a1, TAny* a2);
williamr@4: 	TInt DoCancel(TUint aMask);
williamr@4: 	TInt SetCaptureMode(TInt aCaptureMode);
williamr@4: 	TInt SetCamConfig(TInt aCaptureMode, const TDesC8* aCamConfigBuf);
williamr@4: 	TInt SetBufConfig(TInt aCaptureMode, const TDesC8* aBufferConfigBuf,TInt aChunkHandle);
williamr@4: 	TInt SetBufConfig(TInt aCaptureMode, TInt aNumBuffers);
williamr@4: 	TInt ChunkClose(TInt aCaptureMode);
williamr@4: 	TInt Start();
williamr@4: 	TInt NotifyNewImage(TRequestStatus* aStatus);
williamr@4: 	TInt ReleaseBuffer(TInt aChunkOffset);
williamr@4: 	TInt DoSetConfig(TInt aCaptureMode, const TDesC8* aCamConfigBuf);
williamr@4: 	TInt ValidateConfig(TInt aCaptureMode, TCameraConfigV02 &aConfig);
williamr@4: 	TInt DoValidateConfig(TCameraCapsV02* aCamCaps, TInt &aCaptureMode, TCameraConfigV02 &aConfig);
williamr@4: 	TInt DoStart();
williamr@4: 	TInt ReAllocBufferConfigInfo(TInt aCaptureMode, TInt aNumBuffers);
williamr@4: 	TInt ReAllocBufferConfigInfo(TInt aNumBuffers);
williamr@4: 	TInt GetSensorCaps(TAny* a1);
williamr@4: 	TInt GetFrameSizeCaps(TAny* a1, TAny* a2);
williamr@4: 	TInt GetDynamicAttribute(TInt aAttribute, TUint& aValue);
williamr@4: 	TInt SetDynamicAttribute(TInt aAttribute, TUint aValue);
williamr@4: 	inline DCameraScPdd* Pdd();
williamr@4: 	static void RestartDfc(TAny* aChannel);
williamr@4: 	static void PowerUpDfc(TAny* aPtr);
williamr@4: 	static void PowerDownDfc(TAny* aPtr);
williamr@4: private:
williamr@4: 	/** An array of configurations for each capture mode. */
williamr@4: 	TCaptureModeConfig* iCaptureModeConfig;
williamr@4: 	/** The unit number of this channel. */
williamr@4: 	TInt iUnit;
williamr@4: 	/** The operating state of the channel. */
williamr@4: 	TState iState;
williamr@4: 	/** A pointer to the owning client thread. */
williamr@4: 	DThread* iOwningThread;
williamr@4: 	/** The current capture mode of the camera. */
williamr@4: 	TDevCamCaptureMode iCaptureMode;
williamr@4: 	/** The pending request queue. */
williamr@4: 	TCameraScRequestQueue iRequestQueue;
williamr@4: 	/** A mutex to protect access to the buffer lists and the pending request list. */
williamr@4: 	NFastMutex iMutex;
williamr@4: 	/** The camera driver power handler. */
williamr@4: 	DCameraScPowerHandler* iPowerHandler;
williamr@4: 	/** DFC used to re-start the PDD following a data capture error. */
williamr@4: 	TDfc iRestartDfc;
williamr@4: 	/** DFC used to handle power down requests from the power manager before a transition into system shutdown/standby. */
williamr@4: 	TDfc iPowerDownDfc;
williamr@4: 	/** DFC used to handle power up requests from the power manager following a transition out of system standby. */
williamr@4: 	TDfc iPowerUpDfc;
williamr@4: 	
williamr@4: 	// Used as a cache for values successfully set by SetDynamicAttribute().
williamr@4: 	TUint iBrightnessValue;
williamr@4: 	TUint iContrastValue;
williamr@4: 	TUint iColorEffectValue;
williamr@4: 	
williamr@4: 	friend class DCameraScPowerHandler;
williamr@4: 	friend class DBufferManager;
williamr@4: 	};
williamr@4: 
williamr@4: #include <drivers/camerasc.inl>
williamr@4: 
williamr@4: #endif	// __CAMERASC_H__