1 // Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

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

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // e32\include\e32ldr.h

    15 // 

    16 // WARNING: This file contains some APIs which are internal and are subject

    17 //          to change without notice. Such APIs should therefore not be used

    18 //          outside the Kernel and Hardware Services package.

    19 //

    20 

    21 /**

    22  @file

    23  @internalTechnology

    24 */

    25 

    26 #ifndef __E32LDR_H__

    27 #define __E32LDR_H__

    28 #include <e32cmn.h>

    29 

    30 

    31 const TInt KMaxLibraryEntryPoints=0x100;

    32 

    33 //

    34 // Loader version number.

    35 //

    36 const TInt KLoaderMajorVersionNumber=1;

    37 const TInt KLoaderMinorVersionNumber=0;

    38 

    39 //

    40 // IPC messages to the loader

    41 //

    42 enum TLoaderMsg

    43 	{

    44 	ELoadProcess=1,

    45 	ELoadLibrary=2,

    46 	ELoadLogicalDevice=3,

    47 	ELoadPhysicalDevice=4,

    48 	ELoadLocale=5,

    49 	ELoadFileSystem=6,

    50 	EGetInfo=7,

    51 	ELoaderDebugFunction=8,

    52 	ELoadFSExtension=9,

    53 	EGetInfoFromHeader=10,

    54 	ELoadFSPlugin=11,

    55 	ELoaderCancelLazyDllUnload=12,

    56 	ELdrDelete=13,

    57 	ECheckLibraryHash=14, 

    58 	ELoadFSProxyDrive=15,

    59     ELoadCodePage=16,

    60     EMaxLoaderMsg

    61 	};

    62 //

    63 // Loader message arguments:

    64 //		0 = TLdrInfo

    65 //		1 = Filename

    66 //		2 = Command line (process) or path (library)

    67 //

    68 class TLdrInfo

    69 	{

    70 public:

    71 	IMPORT_C TLdrInfo();		// for BC

    72 public:

    73 	TUidType iRequestedUids;

    74 	TOwnerType iOwnerType;

    75 	TInt iHandle;

    76 	TUint32 iSecureId;

    77 	TUint32 iRequestedVersion;

    78 	TInt iMinStackSize;			// Size of new process stack 

    79 	};

    80 	

    81 

    82 #ifndef __KERNEL_MODE__

    83 #include <e32std.h>

    84 //

    85 // Loader client class

    86 //

    87 class RLoader : public RSessionBase

    88 	{

    89 public:

    90 	IMPORT_C TInt Connect();

    91 	TVersion Version() const;

    92 	TInt LoadProcess(TInt& aHandle, const TDesC& aFileName, const TDesC& aCommand, const TUidType& aUidType, TOwnerType aType);

    93 	IMPORT_C TInt LoadLibrary(TInt& aHandle, const TDesC& aFileName, const TDesC& aPath, const TUidType& aType, TUint32 aModuleVersion);

    94 	IMPORT_C TInt GetInfo(const TDesC& aFileName, TDes8& aInfoBuf);

    95 	TInt LoadDeviceDriver(const TDesC& aFileName, TInt aDeviceType);

    96 	IMPORT_C TInt DebugFunction(TInt aFunction, TInt a1, TInt a2, TInt a3);

    97 	TInt LoadLocale(const TDesC& aLocaleDllName, TLibraryFunction* aExportList);

    98 	TInt GetInfoFromHeader(const TDesC8& aHeader, TDes8& aInfoBuf);

    99 	IMPORT_C TInt CancelLazyDllUnload();

   100 	IMPORT_C TInt Delete(const TDesC& aFileName);

   101     IMPORT_C TInt CheckLibraryHash(const TDesC& aFileName, TBool aValidateHash=EFalse);

   102 	TInt LoadProcess(TInt& aHandle, const TDesC& aFileName, const TDesC& aCommand, const TUidType& aUidType, TInt aMinStackSize, TOwnerType aType);

   103 public:

   104 #ifdef __ARMCC__

   105 	// workaround for possible EDG bug (!!)

   106 	inline TInt SendReceive(TInt aFunction,const TIpcArgs& aArgs) const

   107 	  { return RSessionBase::SendReceive(aFunction, aArgs); }

   108 #else

   109 	using RSessionBase::SendReceive;

   110 #endif

   111 	};

   112 #endif

   113 

   114 //

   115 // Information required to create a new code segment

   116 //

   117 enum TCodeSegAttributes

   118 	{

   119 	ECodeSegAttKernel			=0x00000001,

   120 	ECodeSegAttGlobal			=0x00000002,

   121 	ECodeSegAttFixed			=0x00000004,

   122 	ECodeSegAttABIMask			=0x00000018,	  // same values as in image header

   123 	ECodeSegAttCodePaged		=0x00000200,	  // the code seg is demand paged

   124 	ECodeSegAttDataPaged		=0x00002000,	  // the code seg static data is demand paged

   125 	ECodeSegAttHDll				=(TInt)0x80000000,// Emulator host file type: 1=DLL, 0=EXE

   126 	ECodeSegAttExpVer			=0x40000000,	  // Filename is explicitly versioned

   127 	ECodeSegAttNmdExpData		=0x20000000,	  // Named symbol export data in code seg

   128 	ECodeSegAttSMPSafe			=0x10000000,	  // code seg and its static dependencies are SMP safe

   129 	ECodeSegAttAddrNotUnique	=0x08000000,	  // run address not globally unique (may overlap other codesegs)

   130 	};

   131 

   132 class TBlockMapEntryBase

   133 /**

   134 	Where sections of a file are located on the media.

   135 	The kernel uses this to load in parts of a demand paged file.

   136  */

   137 	{

   138 public:

   139 	TUint iNumberOfBlocks;  // Number of contiguous blocks in map.

   140 	TUint iStartBlock;		// Number for first block in the map.

   141 	};

   142 

   143 struct SBlockMapInfoBase

   144 /**

   145 	Describes context for TBlockMapEntryBase objects.

   146  */

   147 	{

   148 	TUint iBlockGranularity;	// Size of a block in bytes.

   149 	TUint iBlockStartOffset;	// Offset to start of the file or requested file position within a block.

   150 	TInt64 iStartBlockAddress;	// Address of the first block of the partition.

   151 	TInt iLocalDriveNumber;		// Local drive number of where the file lies on.

   152 	};

   153 

   154 // forward declarations from file server

   155 class RFile;

   156 class RFs;

   157 

   158 /**

   159 A Handle used to identify a file on storage media.

   160 @internalTechnology

   161 */

   162 class RFileClamp

   163 	{

   164 public:

   165 	inline RFileClamp()

   166 		{

   167 		iCookie[0] = 0;

   168 		iCookie[1] = 0;

   169 		}

   170 	IMPORT_C TInt Clamp(RFile& aFile);

   171 	IMPORT_C TInt Close(RFs& aFs);

   172 

   173 public:

   174 	TInt64 iCookie[2];

   175 	};

   176 

   177 

   178 class TCodeSegCreateInfo

   179 	{

   180 public:

   181 	TBuf8<KMaxFileName> iFileName;		// not including {MMMMmmmm} version info

   182 	TUidType iUids;				// uid1 indicates EXE or DLL

   183 	TUint32 iAttr;

   184 	TInt iCodeSize;

   185 	TInt iTextSize;

   186 	TInt iDataSize;

   187 	TInt iBssSize;

   188 	TInt iTotalDataSize;

   189 	TUint32 iEntryPtVeneer;		// address of first instruction to be called

   190 	TUint32 iFileEntryPoint;	// address of entry point within this code segment

   191 	TInt iDepCount;

   192 	TUint32 iExportDir;

   193 	TInt iExportDirCount;

   194 	TUint32 iCodeLoadAddress;	// 0 for RAM loaded code, else pointer to TRomImageHeader

   195 	TUint32 iCodeRunAddress;

   196 	TUint32 iDataLoadAddress;

   197 	TUint32 iDataRunAddress;

   198 	TUint32 iExceptionDescriptor;

   199 	TInt iRootNameOffset;

   200 	TInt iRootNameLength;

   201 	TInt iExtOffset;

   202 	TUint32 iModuleVersion;

   203 	SSecurityInfo iS;

   204 	TAny* iHandle;				// pointer to kernel-side DCodeSeg object

   205 	TInt iClientProcessHandle;	// handle to client process for user DLL loads

   206 	/** Code relocation information stored on loader heap. */

   207 	TUint32* iCodeRelocTable;

   208 	/** Size of code relocation table in bytes. */

   209 	TInt iCodeRelocTableSize;

   210 	/** Import fixup information stored on loader heap. */

   211 	TUint32* iImportFixupTable;

   212 	/** Size of import fixup table in bytes. */

   213 	TInt iImportFixupTableSize;

   214 	/** Offset to apply to each code address in the image when it is fixed up. */

   215 	TUint32 iCodeDelta;

   216 	/** Offset to apply to each data address in the image when it is fixed up. */

   217 	TUint32 iDataDelta;

   218 	/**

   219 		Whether the code is paged.  If this is set, then

   220 		TCodeSegCreateInfo::iCodeRelocTable[Size] and

   221 		TCodeSegCreateInfo::iImportFixupTable[Size] contain fixup information

   222 		which the kernel uses to fix up each page.

   223 		(They may be null if the binary has no imports or no code section.)

   224 	 */

   225 	TBool iUseCodePaging;

   226 	/** The UID of the compression scheme in use. */

   227 	TUint32 iCompressionType;

   228 	/**

   229 		Start of compressed pages within the file.  The kernel uses

   230 		this to load compressed pages from byte-pair files when demand

   231 		paging.

   232 	 */

   233 	TInt32* iCodePageOffsets;

   234 	/** Where (possibly compressed) object code starts in iFile. */

   235 	TInt iCodeStartInFile;

   236 	/** Length of (possibly compressed) object code in iFile. */

   237 	TInt iCodeLengthInFile;

   238 	/** Information about block map entries in iCodeBlockMapEntries. */

   239 	SBlockMapInfoBase iCodeBlockMapCommon;

   240 	/** Where object code is located on the media. */

   241 	TBlockMapEntryBase* iCodeBlockMapEntries;

   242 	/** Size of block map entry array in bytes. */

   243 	TInt iCodeBlockMapEntriesSize;

   244 	/**

   245 		File clamp cookie, used to delete the file when the

   246 		codeseg is destroyed.

   247 	 */

   248 	RFileClamp iFileClamp;

   249 public:

   250 	IMPORT_C TPtrC8 RootName() const;

   251 	};

   252 

   253 //

   254 // Information required to create a new process

   255 //

   256 class TProcessCreateInfo : public TCodeSegCreateInfo

   257 	{

   258 public:

   259 	enum TDebugAttributes	// must be the same as RLibrary::TInfoV2::TDebugAttributes

   260 		{

   261 		EDebugAllowed = 1<<0, ///< Flags set if executable may be debugged.

   262 		ETraceAllowed = 1<<1 ///< Flags set if executable may be traced.

   263 		};

   264 	/**

   265 	The flags for process's creation.  Will be set by the loader from the images

   266 	header flags ready for the kernel to use.

   267 	*/

   268 	enum TProcessCreateFlags

   269 		{

   270 		EDataPagingUnspecified	= 0x00000000,	///< Use the global data paging default.

   271 		EDataPaged				= 0x00000001,	///< Page the process's data by default.

   272 		EDataUnpaged			= 0x00000002,	///< Don't page the process's data by default.

   273 		EDataPagingMask			= 0x00000003,	///< Bit mask ofr data paging flags.

   274 		};

   275 

   276 	/** Default constructor that ensures flags are clear. */

   277 	TProcessCreateInfo() : iFlags(0) {};

   278 

   279 	TInt iHeapSizeMin;

   280 	TInt iHeapSizeMax;

   281 	TInt iStackSize;

   282 	TInt iClientHandle;			// handle to loader's client

   283 	TInt iProcessHandle;		// handle to new DProcess

   284 	TInt iFinalHandle;			// handle from loader client to new process

   285 	TOwnerType iOwnerType;

   286 	TProcessPriority iPriority;

   287 	TUint iSecurityZone;

   288 	TUint iDebugAttributes;	///< Set with values from TDebugAttributes.

   289 	TRequestStatus* iDestructStat;

   290 	TUint iFlags;	///< Flags for process creation, should set from TProcessCreateFlags.

   291 	};

   292 

   293 const TUint KSecurityZoneUnique = 0u;

   294 const TUint KSecurityZoneLegacyCode = ~0u;

   295 

   296 //

   297 // Information required to attach a code segment to a process

   298 // in the form of a library.

   299 //

   300 class TLibraryCreateInfo

   301 	{

   302 public:

   303 	TAny* iCodeSegHandle;		// pointer to kernel-side DCodeSeg object

   304 	TInt iClientHandle;			// handle to loader's client

   305 	TInt iLibraryHandle;		// handle to new DLibrary

   306 	TOwnerType iOwnerType;

   307 	};

   308 

   309 //

   310 // Information required to find an existing code segment

   311 //

   312 class TFindCodeSeg

   313 	{

   314 public:

   315 	TUidType iUids;				// required UIDs

   316 	const TAny* iRomImgHdr;		// ROM image header if ROM code required, NULL otherwise

   317 	TUint32 iAttrMask;			// mask for attributes

   318 	TUint32 iAttrVal;			// required value for masked attributes

   319 	TInt iProcess;				// handle to process in which code is required to operate

   320 								// not used if kernel only specified

   321 	SSecurityInfo iS;			// required capabilities/SID

   322 	TUint32 iModuleVersion;		// required version

   323 	TBuf8<KMaxLibraryName> iName;	// name to look for - zero length means any

   324 	};

   325 

   326 //

   327 // Information required to by the reaper from the codeseg.

   328 //

   329 struct TCodeSegLoaderCookie

   330 	{

   331 	RFileClamp iFileClamp;

   332 	TInt64 iStartAddress;

   333 	TInt iDriveNumber;

   334 	};

   335 

   336 //

   337 // Loader magic executive functions

   338 //

   339 class E32Loader

   340 	{

   341 public:

   342 	// used by loader only

   343 	IMPORT_C static TInt CodeSegCreate(TCodeSegCreateInfo& aInfo);

   344 	IMPORT_C static TInt CodeSegLoaded(TCodeSegCreateInfo& aInfo);

   345 	IMPORT_C static TInt LibraryCreate(TLibraryCreateInfo& aInfo);

   346 	IMPORT_C static TInt CodeSegOpen(TAny* aHandle, TInt aClientProcessHandle);

   347 	IMPORT_C static void CodeSegClose(TAny* aHandle);

   348 	IMPORT_C static void CodeSegNext(TAny*& aHandle, const TFindCodeSeg& aFind);

   349 	IMPORT_C static void CodeSegInfo(TAny* aHandle, TCodeSegCreateInfo& aInfo);

   350 	IMPORT_C static TInt CodeSegAddDependency(TAny* aImporter, TAny* aExporter);

   351 	IMPORT_C static void CodeSegDeferDeletes();

   352 	IMPORT_C static void CodeSegEndDeferDeletes();

   353 	IMPORT_C static TInt ProcessCreate(TProcessCreateInfo& aInfo, const TDesC8* aCommandLine);

   354 	IMPORT_C static TInt ProcessLoaded(TProcessCreateInfo& aInfo);

   355 	IMPORT_C static TInt CheckClientState(TInt aClientHandle);

   356 	IMPORT_C static TInt DeviceLoad(TAny* aHandle, TInt aType);

   357 	IMPORT_C static TAny* ThreadProcessCodeSeg(TInt aHandle);

   358 	IMPORT_C static void ReadExportDir(TAny* aHandle, TUint32* aDest);

   359 	IMPORT_C static TInt LocaleExports(TAny* aHandle, TLibraryFunction* aExportsList);

   360 

   361 #ifdef __MARM__

   362 	IMPORT_C static void GetV7StubAddresses(TLinAddr& aExe, TLinAddr& aDll);

   363 	static TInt V7ExeEntryStub();

   364 	static TInt V7DllEntryStub(TInt aReason);

   365 #endif

   366 

   367 	IMPORT_C static TUint32 PagingPolicy();

   368 	

   369 	IMPORT_C static TInt NotifyIfCodeSegDestroyed(TRequestStatus& aStatus);

   370 	IMPORT_C static TInt GetDestroyedCodeSegInfo(TCodeSegLoaderCookie& aCookie);

   371 

   372 public:

   373 	// used by client side

   374 	static TInt WaitDllLock();

   375 	static TInt ReleaseDllLock();

   376 	static TInt LibraryAttach(TInt aHandle, TInt& aNumEps, TLinAddr* aEpList);

   377 	static TInt LibraryAttached(TInt aHandle);

   378 	static TInt StaticCallList(TInt& aNumEps, TLinAddr* aEpList);

   379 	static TInt LibraryDetach(TInt& aNumEps, TLinAddr* aEpList);

   380 	static TInt LibraryDetached();

   381 	};

   382 

   383 typedef TInt (*TSupervisorFunction)(TAny*);

   384 

   385 // Relocation types

   386 /**

   387 @internalTechnology

   388 @released

   389 */

   390 const TUint16 KReservedRelocType        = (TUint16)0x0000;

   391 /**

   392 @internalTechnology

   393 @released

   394 */

   395 const TUint16 KTextRelocType            = (TUint16)0x1000;

   396 /**

   397 @internalTechnology

   398 @released

   399 */

   400 const TUint16 KDataRelocType            = (TUint16)0x2000;

   401 /**

   402 @internalTechnology

   403 @released

   404 */

   405 const TUint16 KInferredRelocType        = (TUint16)0x3000;

   406 

   407 // Compression types

   408 

   409 /**

   410 @internalTechnology

   411 @released

   412 */

   413 const TUint KFormatNotCompressed=0;

   414 /**

   415 @internalTechnology

   416 @released

   417 */

   418 const TUint KUidCompressionDeflate=0x101F7AFC;

   419 

   420 

   421 const TUint KUidCompressionBytePair=0x102822AA;

   422 

   423 

   424 #endif

   425