Class RChunk

class RChunk : public RHandleBase;

Description

A handle to a chunk.

The chunk itself is a kernel side object.

Derivation

• RHandleBase - A handle to an object.

• RChunk - A handle to a chunk.

Members

Defined in RChunk:

• Adjust(TInt)constChanges the number of bytes committed to the chunk.
• AdjustDoubleEnded(TInt,TInt)constChanges the number of bytes and the position of this double ended chunk's commit...
• Allocate(TInt)constAllocates and commits to a disconnected chunk.
• Base()constGets a pointer to the base of the chunk's reserved region.
• Bottom()constGets the offset of the bottom of the double ended chunk's committed region from ...
• Commit(TInt,TInt)constCommits memory to a disconnected chunk.
• Create(TChunkCreateInfo &)Creates a chunk of the type specified by the parameter aCreateInfo.
• CreateDisconnectedGlobal(const TDesC &,TInt,TInt,TInt,TOwnerType)Creates a global, disconnected, chunk.
• CreateDisconnectedLocal(TInt,TInt,TInt,TOwnerType)Creates a local, disconnected chunk.
• CreateDoubleEndedGlobal(const TDesC &,TInt,TInt,TInt,TOwnerType)Creates a global, double ended, chunk.
• CreateDoubleEndedLocal(TInt,TInt,TInt,TOwnerType)Creates a local, double ended, chunk.
• CreateGlobal(const TDesC &,TInt,TInt,TOwnerType)Creates a global chunk.
• CreateLocal(TInt,TInt,TOwnerType)Creates a local chunk.
• CreateLocalCode(TInt,TInt,TOwnerType)Creates a user writable chunk that is marked by the kernel as containing code.
• Decommit(TInt,TInt)constDecommits memory from a disconnected chunk.
• EPreventAdjust
• IsReadable()constTests whether the chunk is mapped into its process address space.
• IsWritable()constTests whether the chunk mapped into its process address space and is writable.
• MaxSize()constGets the maximum size of this chunk.
• Open(RMessagePtr2,TInt,TBool,TOwnerType)Opens a handle to a chunk using a handle number sent by a client to a server.
• Open(TInt,TOwnerType)Opens a handle to a chunk using a handle number passed as an environment data it...
• Open(const TFindChunk &,TOwnerType)Opens a handle to the global chunk found using a TFindChunk object.
• OpenGlobal(const TDesC &,TBool,TOwnerType)Opens a handle to a specific named global chunk.
• SetRestrictions(TUint)Sets or removes restrictions on the ability of the chunk to change.
• Size()constGets the current size of this chunk's committed region.
• TRestrictionsSet of flags used by RChunk::SetRestrictions(TUint).
• Top()constGets the offset of the top of the double ended chunk's committed region from the...

Inherited from RHandleBase:

• Attributes()const
• BTraceId()constReturns a unique object identifier for use with BTrace
• Close()Closes the handle.
• Duplicate(const RThread &,TOwnerType)Creates a valid handle to the kernel object for which the specified thread alrea...
• FullName()constGets the full name of the handle.
• FullName(TDes &)constGets the full name of the handle.
• Handle()constRetrieves the handle-number of the object associated with this handle.
• HandleInfo(THandleInfo *)Gets information about the handle.
• Name()constGets the name of the handle.
• Open(const TFindHandleBase &,TOwnerType)Opens a handle to a kernel side object found using a find-handle object.
• RHandleBase(TInt)Copy constructor.
• SetHandle(TInt)Sets the handle-number of this handle to the specified value.
• SetHandleNC(TInt)Sets the handle-number of this handle to the specified value, and marks it as no...
• SetReturnedHandle(TInt)Sets the handle-number of this handle to the specified value.
• iHandle

inline TInt Open(const TFindChunk &aFind, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to the global chunk found using a TFindChunk object.

ATFindChunk object is used to find all chunks whose full names match a specified pattern.

By default, ownership of this chunk handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

Return value

IMPORT_C TInt CreateLocal(TInt aSize, TInt aMaxSize, TOwnerType aType=EOwnerProcess);

Description

Creates a local chunk.

The chunk is local to the process creating it; i.e. it is private to the process creating it and is not intended for access by other user processes.

aMaxSize specifies the maximum size of the chunk and aSize specifies the number of bytes to be committed on creation of the chunk. Both values are rounded up to the next nearest processor page boundary value if they are not already on a processor page boundary.

The committed region always starts at the bottom of the reserved region.

By default, ownership of this chunk handle is vested in the current process. Ownership of the chunk handle can be vested in the current thread by passing EOwnerThread as the third parameter to this function.

Parameters

Return value

Panic codes

IMPORT_C TInt CreateLocalCode(TInt aSize, TInt aMaxSize, TOwnerType aType=EOwnerProcess);

Description

Creates a user writable chunk that is marked by the kernel as containing code.

The chunk is local to the process creating it, i.e. it is private to the process creating it and is not intended for access by other user processes.

On systems using a Harvard cache, this type of chunk removes the need to flush the instruction cache (I-Cache) on a context switch. However, the instruction Translation Look-aside Buffer (ITLB) still needs to be flushed when switching to or from a process with one of these chunks in its address space. Systems with a dynamic branch predictor may also need to flush their branch target buffer when switching from one process using this type of chunk to another.

Parameters

Return value

Panic codes

See also:

• UserHeap::ChunkHeap(const TDesC *,TInt,TInt,TInt,TInt,TBool)Creates a heap in a local or global chunk.
• User::IMB_Range(TAny *,TAny *)Does the necessary preparations to guarantee correct execution of code in the sp...

IMPORT_C TInt CreateGlobal(const TDesC &aName, TInt aSize, TInt aMaxSize, TOwnerType aType=EOwnerProcess);

Description

Creates a global chunk.

The chunk is global; i.e. it is potentially visible to all processes and is intended for access by other user processes.

aMaxSize specifies the maximum size of the chunk and aSize specifies the number of bytes to be committed on creation of the chunk. Both values are rounded up to the next nearest processor page boundary value ,if they are not already on a processor page boundary value.

The committed region always starts at the bottom of the reserved region.

The descriptor aName contains the name to be assigned to this global chunk. If this name is empty, the chunk will be anonymous. Anonymous chunks cannot be accessed by other processes unless the creator explicitly passes them a handle to the chunk - this can be used to transfer large amounts of data between processes in a secure fashion.

By default, ownership of this chunk handle is vested in the current process. Ownership of the chunk handle can be vested in the current thread by passing EOwnerThread as the third parameter to this function.

Parameters

Return value

Panic codes

IMPORT_C TInt CreateDoubleEndedLocal(TInt aInitialBottom, TInt aInitialTop, TInt aMaxSize, TOwnerType aType=EOwnerProcess);

Description

Creates a local, double ended, chunk.

The chunk is local to the process creating it; i.e. it is private to the process creating it and is not intended for access by other user processes.

The committed region of a double ended chunk can be any contiguous subset of the reserved region.

aMaxSize specifies the maximum size of the chunk.

The difference between aInitialTop and aInitialBottom gives the number of bytes to be committed, on creation of the chunk; aInitialBottom gives the offset of the bottom of the committed region from the base of the chunk's reserved region; aInitialTop gives the offset of the top of the committed region from the base of the chunk's reserved region.

Both aInitialBottom and aInitialTop are rounded up to the next nearest processor page boundary value, if they are not already on a processor page boundary value.

By default, ownership of this chunk handle is vested in the current process. Ownership of the chunk handle can be vested in the current thread by passing EOwnerThread as the third parameter to this function.

Note that:

1. the lowest valid address in a double ended chunk is the sum of the base of the chunk's reserved region plus the adjusted value of aInitialBottom

2. the highest valid address in a double ended chunk is the the sum of the base of the chunk's reserved region plus the adjusted value of aInitialTop - 1.

Parameters

Return value

Panic codes

IMPORT_C TInt CreateDoubleEndedGlobal(const TDesC &aName, TInt aInitialBottom, TInt aInitialTop, TInt aMaxSize, TOwnerType aType=EOwnerProcess);

Description

Creates a global, double ended, chunk.

The chunk is global; i.e. it is visible to all processes and is intended for access by other user processes.

The committed region of a double ended chunk can be any contiguous subset of the reserved region.

aMaxSize specifies the maximum size of the chunk.

The difference between aInitialTop and aInitialBottom gives the number of bytes to be committed, on creation of the chunk; aInitialBottom gives the offset of the bottom of the committed region from the base of the chunk's reserved region; aInitialTop gives the offset of the top of the committed region from the base of the chunk's reserved region.

Both aInitialBottom and aInitialTop are rounded up to the next nearest processor page boundary value, if they are not already on a processor page boundary value.

The descriptor aName contains the name to be assigned to this global chunk.

By default, ownership of this chunk handle is vested in the current process. Ownership of the chunk handle can be vested in the current thread by passing EOwnerThread as the third parameter to this function.

Note that:

1. the lowest valid address in a double ended chunk is the sum of the base of the chunk's reserved region plus the adjusted value of aInitialBottom

2. the highest valid address in a double ended chunk is the the sum of the base of the chunk's reserved region plus the adjusted value of aInitialTop - 1.

Parameters

Return value

Panic codes

IMPORT_C TInt CreateDisconnectedLocal(TInt aInitialBottom, TInt aInitialTop, TInt aMaxSize, TOwnerType aType=EOwnerProcess);

Description

Creates a local, disconnected chunk.

The chunk is local to the process creating it; i.e. it is private to the process creating it and is not intended for access by other user processes.

A disconnected chunk has a committed region consisting of an arbitrary set of MMU pages within the reserved region, i.e. each page-sized address range within the reserved region which begins on a page boundary may be committed independently.

aMaxSize specifies the maximum size of the chunk.

The difference between aInitialTop and aInitialBottom gives the number of bytes to be committed, on creation of the chunk; aInitialBottom gives the offset of the bottom of the committed region from the base of the chunk's reserved region; aInitialTop gives the offset of the top of the committed region from the base of the chunk's reserved region.

Both aInitialBottom and aInitialTop are rounded up to the next nearest processor page boundary value, if they are not already on a processor page boundary value.

By default, ownership of this chunk handle is vested in the current process. Ownership of the chunk handle can be vested in the current thread by passing EOwnerThread as the third parameter to this function.

Parameters

Return value

Panic codes

IMPORT_C TInt CreateDisconnectedGlobal(const TDesC &aName, TInt aInitialBottom, TInt aInitialTop, TInt aMaxSize, TOwnerType aType=EOwnerProcess);

Description

Creates a global, disconnected, chunk.

The chunk is global; i.e. it is visible to all processes and is intended for access by other user processes.

A disconnected chunk has a committed region consisting of an arbitrary set of MMU pages within the reserved region, i.e. each page-sized address range within the reserved region which begins on a page boundary may be committed independently.

aMaxSize specifies the maximum size of the chunk.

The difference between aInitialTop and aInitialBottom gives the number of bytes to be committed, on creation of the chunk; aInitialBottom gives the offset of the bottom of the committed region from the base of the chunk's reserved region; aInitialTop gives the offset of the top of the committed region from the base of the chunk's reserved region.

Both aInitialBottom and aInitialTop are rounded up to the next nearest processor page boundary value, if they are not already on a processor page boundary value.

The descriptor aName contains the name to be assigned to this global chunk.

By default, ownership of this chunk handle is vested in the current process. Ownership of the chunk handle can be vested in the current thread by passing EOwnerThread as the third parameter to this function.

Parameters

Return value

Panic codes

IMPORT_C TInt Create(TChunkCreateInfo &aCreateInfo);

Description

Creates a chunk of the type specified by the parameter aCreateInfo.

Parameters

Return value

Panic codes

IMPORT_C TInt SetRestrictions(TUint aFlags);

Description

Sets or removes restrictions on the ability of the chunk to change.

For example, to adjust, commit etc

Parameters

Return value

See also:

• RChunk::TRestrictionsSet of flags used by RChunk::SetRestrictions(TUint).

IMPORT_C TInt OpenGlobal(const TDesC &aName, TBool isReadOnly, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to a specific named global chunk.

Full read/write access can be allowed or access can be limited to read only.

By default, ownership of this process handle is vested in the current process, but can be vested in the current thread by passing EOwnerThread as the second parameter to this function.

Parameters

Return value

IMPORT_C TInt Open(RMessagePtr2 aMessage, TInt aParam, TBool isReadOnly, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to a chunk using a handle number sent by a client to a server.

This function is called by the server.

Parameters

Return value

IMPORT_C TInt Open(TInt aArgumentIndex, TOwnerType aType=EOwnerProcess);

Description

Opens a handle to a chunk using a handle number passed as an environment data item to the child process during the creation of that child process.

Note that this function can only be called successfully once.

Parameters

Return value

See also:

• RProcess::SetParameter(TInt,RHandleBase)Sets the specified handle into the specified environment data slot for this proc...

IMPORT_C TInt Adjust(TInt aNewSize) const;

Description

Changes the number of bytes committed to the chunk.

This value is always rounded up to the next nearest processor page boundary.

Parameters

Return value

Panic codes

IMPORT_C TInt AdjustDoubleEnded(TInt aBottom, TInt aTop) const;

Description

Changes the number of bytes and the position of this double ended chunk's committed region.

The difference between aTop and aBottom gives the new size of the committed region; aBottom gives the offset of the bottom of the committed region from the base of the chunk's reserved region.

Both aBottom and aTop are rounded up to the next nearest processor page boundary.

The function fails if this chunk is not a double ended chunk; for a standard chunk, use the RChunk::Adjust(TInt)const function.

Note that if the initial and final committed regions intersect, the contents of the intersection are unchanged. Other parts of the committed region have undefined contents.

Note also that:

1. the lowest valid address in a double ended chunk is the sum of the base of the chunk's reserved region plus the adjusted value of aBottom

2. the highest valid address in a double ended chunk is the the sum of the base of the chunk's reserved region plus the adjusted value of aTop - 1.

Parameters

Return value

Panic codes

IMPORT_C TInt Commit(TInt anOffset, TInt aSize) const;

Description

Commits memory to a disconnected chunk.

Memory is committed in blocks of the MMU page size. E.g. Commit(pageSize-1,2) which asks for the last byte of the first page and the first byte of the second page and will result in the first 2 pages in the chunk being committed. For this reason it is best to only use values for aOffset and aSize which are multiples of the MMU page size. This size can be obtained with the following code.

TInt pageSize;
HAL::Get(HAL::EMemoryPageSize,pageSize)

Parameters

Return value

Panic codes

IMPORT_C TInt Allocate(TInt aSize) const;

Description

Allocates and commits to a disconnected chunk.

Parameters

Return value

Panic codes

IMPORT_C TInt Decommit(TInt anOffset, TInt aSize) const;

Description

Decommits memory from a disconnected chunk.

Memory is decommitted in blocks of the MMU page size. E.g. Decommit(pageSize-1,2) which asks for the last byte of the first page and the first byte of the second page and will result in the first 2 pages in the chunk being decommitted. For this reason it is best to only use values for aOffset and aSize which are multiples of the MMU page size. This size can be obtained with the following code.

TInt pageSize;
HAL::Get(HAL::EMemoryPageSize,pageSize)

Parameters

Return value

Panic codes

IMPORT_C TUint8* Base() const;

Description

Gets a pointer to the base of the chunk's reserved region.

Return value

IMPORT_C TInt Size() const;

Description

Gets the current size of this chunk's committed region.

Return value

IMPORT_C TInt Bottom() const;

Description

Gets the offset of the bottom of the double ended chunk's committed region from the base of the chunk's reserved region.

Note that the lowest valid address in a double ended chunk is the sum of the base of the chunk's reserved region plus the value of RChunk::Bottom()const.

Return value

IMPORT_C TInt Top() const;

Description

Gets the offset of the top of the double ended chunk's committed region from the base of the chunk's reserved region.

Note that the highest valid address in a double ended chunk is the the sum of the base of the chunk's reserved region plus the value of RChunk::Top()const - 1.

Return value

IMPORT_C TInt MaxSize() const;

Description

Gets the maximum size of this chunk.

This maximum size of this chunk is set when the chunk is created.

Return value

inline TBool IsReadable() const;

Description

Tests whether the chunk is mapped into its process address space.

Return value

inline TBool IsWritable() const;

Description

Tests whether the chunk mapped into its process address space and is writable.

Return value

TRestrictions

Description

Set of flags used by RChunk::SetRestrictions(TUint).

See also:

• RChunk::SetRestrictions(TUint)Sets or removes restrictions on the ability of the chunk to change.