T-Kernel 2.0 Specification
Prev	T-Kernel/SM Functions	Next

Address Space Management Functions

Address space management functions perform various operations or managements on logical address spaces. These functions are mainly realized by operating on MMUs or page tables, and offer address space configuration functions to set a task space, address space checking that checks access privilege, locking memory space (resident), and conversion and mapping between logical address and physical address.

These functions are used to not only implement system programs such as device drivers and subsystems but also to realize a virtual memory system by combining subsystems that process a demand paging related processing.

APIs for address space management functions are provided even for systems that do not use MMUs. In consideration of portability and expandability, it is preferable for applications to use these APIs appropriately even on the systems that do not use MMUs.

In T-Kernel, four levels from 0 to 3 (meaning privileged mode, user mode, etc.) are defined as the protection level at runtime, and also four levels from 0 to 3 are defined as the protection level of memory to be accessed. The currently running execution task can access only to the memory with the same or lower protection level. An MMU is responsible for checking the memory privileges at runtime. This function is useful for protecting a system such as OS from being illegally accessed by programs. To realize a memory access privileges check function, T-Kernel sets configuration of MMU and others appropriately.

Caller access privilege information of memory is held for each task to indicate the access right of a protection level immediately before an extended SVC is called. As the information indicates the protection level prior to an extended SVC, it may not be identical to the current protection level at runtime. For example, when a task that is running at protection level 3 calls an extended SVC that usually runs at protection level 0, the task will have an access right of protection level 3. When extended SVC (a) calls extended SVC (b), making a nested call, the caller access privilege information at the extended SVC (b) that is called in a nested manner has a protection level of immediately before the extended SVC (b) has been called, which means the protection level 0 under which the extended SVC (a) is running.

Caller access privilege information of memory is set as follows.

Immediately after a task is started, the protection level at runtime specified when the task was created is set as the caller access privilege information.
When an extended SVC is called, the protection level at the time of the call is set as the caller access privilege information.
Upon return from the extended SVC, the caller access privilege information reverts to that at the time the extended SVC was called.
When SetTaskSpace() is issued, the protection level of the specified task just before the call to an extended SVC is set as the caller access privilege information of the invoking task. When the call to extended SVC is nested, the protection level at runtime just before the last call to the extended SVC is set. When the specified task is running a task portion, the protection level at runtime specified when the task was created is set as the caller access privilege information of the running task.

Caller access privilege information of memory is maintained in order for extended SVC to support operations depending on the protection levels of callers. For example, address space checking functions (ChkSpaceXXX) can be used in extended SVC to check memory access privilege of the caller, as it utilizes caller access privilege information instead of current protection level at runtime.

Address Space Configuration

How to handle T-Kernel address space is explained in the Section called Address Space in the Chapter called T-Kernel Concepts. Address space configuration functions provide APIs for setting task address spaces and caller access privilege information.

SetTaskSpace - Set Task Space

C Language Interface

#include <tk/tkernel.h>

ER ercd = SetTaskSpace (ID tskid );

Parameter

ID tskid Task ID Task ID of the task which has the source address space

Return Parameter

ER ercd Error Code Error code

Error Code

E_OK	Normal completion
E_ID	`tskid` is invalid
E_NOEXS	Object does not exist (the task specified in `tskid` does not exist)
E_OBJ	Invoking task specified by other than `TSK_SELF`

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Sets the task space and caller access privilege information of the invoking task according to the task specified in tskid. As a result, the task that executed this API has the same address space as the task with tskid, and the protection level of the specified task just before the call to an extended SVC is set as the caller access privilege information of the invoking task. When the call to extended SVC is nested, the protection level at runtime just before the last call to the extended SVC is set. When the specified task is running a task portion, the protection level at runtime specified when the specified task was created is set as the caller access privilege information of the invoking task.

Note that, even if the address space or caller access privilege information of the task tskid (target task) is changed after executing this API, the address space or caller access privilege information of the invoking task is not affected. This means that only the state of the target task at the time when executing this API is reflected to that of the invoking task. The invoking task does not follow the later states of the target task.

When this API is executed during an extended SVC and the extended SVC returns to the caller, its caller access privilege information is restored to the state prior to calling the extended SVC. However, its task space is not restored. The task space set by this API is still valid after the extended SVC returned to the caller.

The task ID of the invoking task cannot be specified in tskid. If TSK_SELF is used to specify the invoking task, caller access privilege information is set to the currently running protection level; task space is not switched in this case.

Note that the protection level at runtime is not altered after changing caller access privilege information.

Additional Notes

In the situation that a task A (a task that calls an extended SVC for the device management or subsystem) requests another task B to manage a device driver or subsystem, SetTaskSpace() is used to set the task space and caller access privilege information of the managing task B as the same as those of the requestor task A.

For example, it is assumed that the managing task B for the device driver reads the input data from the device and stores it in the buffer X specified by the requestor task A. If the address of the buffer X is included in the task space of the task A, and the requestor task A and the managing task B have different task spaces, the managing task B cannot access the buffer X and store the input data in it.

In such a case, the managing task B can execute SetTaskSpace() in advance to set its task space as the same as that of the requestor task A to access the buffer X. Since the caller access privilege information of the managing task B becomes the same as that of the requestor task A, it is checked appropriately when storing the input data in the buffer X.

Use tk_set_tsp to set the task space only without setting the caller access privilege information.

Address Space Checking

The following functions check whether access is allowed to the specified memory space, based on the current caller access privilege information.

APIs named ChkSpaceXXX() are provided for such checking. The last letter of API name means as follows:

R: Check for read access privilege.
RW: Check for read and write access privilege.
RE: Check for read and execute access privilege.

If the current caller access privilege information does not allow access to the target memory space, or memory does not exist in the target memory space, an error code E_MACV is returned. The same error code E_MACV is returned when the access is not allowed for a part of the target memory space, or a part of memory does not exist in the target memory space.

If the target memory space for checking is a task space, the currently set task space is used.

	Additional Notes
	When a general application task A running at lower protection level requests a device driver or subsystem running at higher protection level for a processing, if a parameter or return parameter of the processing is placed in the memory space X, a check should be performed by the device driver or subsystem side to check if the requesting task A has access privileges for the memory space X. If this check is not performed, task A can, for example, easily access the disallowed memory space via a device driver or subsystem illegally. APIs for address space checking are functions that are assumed to be used to perform such a check in these situation.

Additional Notes

When a general application task A running at lower protection level requests a device driver or subsystem running at higher protection level for a processing, if a parameter or return parameter of the processing is placed in the memory space X, a check should be performed by the device driver or subsystem side to check if the requesting task A has access privileges for the memory space X. If this check is not performed, task A can, for example, easily access the disallowed memory space via a device driver or subsystem illegally. APIs for address space checking are functions that are assumed to be used to perform such a check in these situation.

ChkSpaceR - Check Read Access Privilege

C Language Interface

#include <tk/tkernel.h>

ER ercd = ChkSpaceR (void *addr , INT len );

Parameter

void*	`addr`	Memory Start Address	Start address of the target memory
INT	`len`	Length	Size of the target memory (in bytes)

Return Parameter

ER ercd Error Code Error code

Error Code

E_OK	Normal completion
E_MACV	Memory cannot be accessed

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Based on the current caller access privilege information, checks whether read access is allowed to the len bytes memory area from the address specified in addr. E_OK is returned if access is allowed; E_MACV is returned otherwise.

ChkSpaceRW - Check Read-Write Access Privilege

C Language Interface

#include <tk/tkernel.h>

ER ercd = ChkSpaceRW (void *addr , INT len );

Parameter

void*	`addr`	Memory Start Address	Start address of the target memory
INT	`len`	Length	Size of the target memory (in bytes)

Return Parameter

ER ercd Error Code Error code

Error Code

E_OK	Normal completion
E_MACV	Memory cannot be accessed

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Based on the current caller access privilege information, checks whether both read and write accesses are allowed to the len bytes memory area from the address specified in addr. E_OK is returned if both accesses are allowed; E_MACV is returned if at least one is prohibited.

ChkSpaceRE - Check Read-Execute Access Privilege

C Language Interface

#include <tk/tkernel.h>

ER ercd = ChkSpaceRE (void *addr , INT len );

Parameter

void*	`addr`	Memory Start Address	Start address of the target memory
INT	`len`	Length	Size of the target memory (in bytes)

Return Parameter

ER ercd Error Code Error code

Error Code

E_OK	Normal completion
E_MACV	Memory cannot be accessed

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Based on the current caller access privilege information, checks whether read access is allowed to the len bytes memory area from the address specified in addr and whether that memory area can be executed as a program. E_OK is returned if both are allowed; E_MACV is returned if at least one is prohibited.

ChkSpaceBstrR - Check Read Access Privilege (String)

C Language Interface

#include <tk/tkernel.h>

INT rlen = ChkSpaceBstrR (CONST UB *str , INT max );

Parameter

CONST UB*	`str`	String	Start address of the target string
INT	`max`	Max Length	Maximum length of the target string

Return Parameter

INT rlen Result Length Length of the accessible string (in bytes)

Error Code

E_MACV

Memory cannot be accessed

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Based on the current caller access privilege information, checks whether read access and write access is allowed to the memory area from str to the string termination ('\0') or to the number of characters (bytes) specified in max, whichever comes first. If max = 0 is set, privilege is checked up to the string termination.

If access is allowed, the length of the string (in bytes) is returned. If the string termination occurs before max bytes, the length to the character before '\0' is returned; if max characters are scanned before the string termination is seen, max is returned.

If access is prohibited, the error code E_MACV is returned.

ChkSpaceBstrRW - Check Read-Write Access Privilege (String)

C Language Interface

#include <tk/tkernel.h>

INT rlen = ChkSpaceBstrRW (CONST UB *str , INT max );

Parameter

CONST UB*	`str`	String	Start address of the target string
INT	`max`	Max Length	Maximum length of the target string

Return Parameter

INT rlen Result Length Length of the accessible string (in bytes)

Error Code

E_MACV

Memory cannot be accessed

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

If both read and write access is allowed, the length of the string (bytes) is returned. If the string termination occurs before max bytes, the length to the character before '\0' is returned; if max characters are scanned before the string termination is seen, max is returned.

If at least one of read and write accesses is prohibited, the error code E_MACV is returned.

ChkSpaceTstrR - Check Read Access Privilege (TRON Code)

C Language Interface

#include <tk/tkernel.h>

INT rlen = ChkSpaceTstrR (CONST TC *str , INT max );

Parameter

CONST TC*	`str`	String	Start address of the target string
INT	`max`	Max Length	Maximum length of the target string

Return Parameter

INT rlen Result Length Length of the accessible string (in TRON code characters)

Error Code

E_MACV

Memory cannot be accessed

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Based on the current caller access privilege information, checks whether read access is allowed to the memory area from str to the TRON code string termination (TNULL = 0x0000) or to the number of characters (number of TRON code characters) specified in max, whichever comes first. If max = 0 is set, privilege is checked up to the string termination.

If access is allowed, the length of the string (number of TRON code characters) is returned. If the string termination occurs before max TRON code characters, the length to the character before TNULL is returned; if max characters are scanned before the string termination is seen, max is returned.

If access is prohibited, the error code E_MACV is returned.

str must be an even-numbered address.

ChkSpaceTstrRW - Check Read-Write Access Privilege (TRON Code)

C Language Interface

#include <tk/tkernel.h>

INT rlen = ChkSpaceTstrRW (CONST TC *str , INT max );

Parameter

CONST TC*	`str`	String	Start address of the target string
INT	`max`	Max Length	Maximum length of the target string (in TRON code characters)

Return Parameter

INT rlen Result Length Length of the accessible string

Error Code

E_MACV

Memory cannot be accessed

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Based on the current caller access privilege information, checks whether read access is and write access allowed to the memory area from str to the TRON code string termination (TNULL = 0x0000) or to the number of characters (number of TRON code characters) specified in max, whichever comes first. If max = 0 is set, privilege is checked up to the string termination.

If both read and write access is allowed, the length of the string (number of TRON code characters) is returned. If the string termination occurs before max TRON code characters, the length to the character before TNULL is returned; if max characters are scanned before the string termination is seen, max is returned.

If at least one of read and write accesses is prohibited, the error code E_MACV is returned.

str must be an even-numbered address.

Logical Address Space Management

Logical address space management functions provide APIs relating to converting address (conversion from a logical address to a physical address), making memory resident, and setting memory access privileges.

T-Kernel performs the address conversion (conversion from a logical address to a physical address) using MMUs in order to manage the access privileges for memory, realize a task space, and use memory efficiently. While usual programs does not need to handle any physical address because they are running in a logical address space, some system programs that directly operate a hardware device such as a device driver that performs DMA transfer may handle physical addresses. Since mapping between a logical address and a physical address must be retrieved or set, CnvPhysicalAddr(), MapMemory(), and UnmapMemory() are provided as APIs for these operations.

When a virtual memory system is constructed on T-Kernel, a situation occurs where memory being accessed from program A does not physically exist in main memory (paged out state). When there is an access to the paged-out memory, in the case of some CPU, an MMU detects the access and raises a page fault CPU exception, letting the virtual memory system that processes the exception returns (pages in) the paged out memory content from an external disk (secondary storage device) to memory. As this processing is performed, program A can proceed with its processing regardless of whether the accessed memory is paged out or not. This is the general implementation method of a virtual memory system.

The above page-in processing cannot be performed when a page fault occurs, however, for those programs which are during execution of task-independent portion, dispatch disabled, or interrupts disabled. For this reason, to avoid page faults during execution of a program, all the memory to be accessed must be made resident in advance by paging them in. The same action also needs to be performed when performing a DMA transfer or executing a strictly time-constrained program. LockSpace() for locking (making resident) memory space and UnlockSpace() for releasing the locked memory space are provided as APIs for this kind of situation.

In addition to this, GetSpaceInfo() to retrieve various information on address space, SetMemoryAccess() to set memory access privileges, etc. are provided as APIs.

APIs that perform processing related to DMA transfer also perform memory cache control optimized to the DMA transfer. Specifically, when performing a conversion from a logical address to a physical address using CnvPhysicalAddr(), memory caching for the target memory space is turned off so that DMA transfer can be performed. After completing the DMA transfer, making memory nonresident by executing UnlockSpace() returns memory caching to the on state.

	Additional Notes
	T-Kernel/SM sets or operates MMUs and page tables in order to manage correspondence relationship (mapping) between a logical space and a physical space, memory access privileges, page nonexistence, making a page resident, etc. However, T-Kernel is not the sole entity to realize a virtual memory system. In order to actually realize a virtual memory system, other various processings such as page in/out between the physical memory and the disk (secondary storage device) are required. These processings are performed by subsystems (part of T-Kernel Extension) for realizing a virtual memory system rather than T-Kernel itself.

Additional Notes

T-Kernel/SM sets or operates MMUs and page tables in order to manage correspondence relationship (mapping) between a logical space and a physical space, memory access privileges, page nonexistence, making a page resident, etc. However, T-Kernel is not the sole entity to realize a virtual memory system. In order to actually realize a virtual memory system, other various processings such as page in/out between the physical memory and the disk (secondary storage device) are required. These processings are performed by subsystems (part of T-Kernel Extension) for realizing a virtual memory system rather than T-Kernel itself.

LockSpace - Lock Memory Space

C Language Interface

#include <tk/tkernel.h>

ER ercd = LockSpace (CONST void *addr , INT len );

Parameter

CONST void*	`addr`	Memory Start Address	Start address of memory to be locked
INT	`len`	Length	Size of memory to be locked (in bytes)

Return Parameter

ER ercd Error Code Error code

Error Code

E_OK	Normal completion
E_PAR	Parameter error (`len` ≦ 0)
E_MACV	An area out of the memory space is specified
E_NOMEM	Insufficient memory (page in memory for resident cannot be allocated)
E_LIMIT	Lock attempts exceed the upper limit of the number of locks

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Locks (makes resident) the len bytes memory area from the logical address addr (target area). After making an area resident with this API, the target area will not be paged out, and is always mapped to a physical address space and allocated to the real memory (physical memory).

When a part of the target area has been paged out, it is paged in before making the area resident. If the real memory cannot be allocated for paging in, the error code E_NOMEM is returned.

LockSpace() can be executed more than once for the same memory area. In this case, the number of LockSpace() operations is counted and the same number of UnlockSpace() operations can make the area nonresident. That is, the resident state can be nested by LockSpace(). However, there is an implementation-dependent upper limit to the nesting depth (difference between the numbers of LockSpace() and UnlockSpace() operations). If LockSpace() is executed exceeding the upper limit, the error code E_LIMIT is returned.

If 0 or less is specified in len, the error code E_PAR is returned. If the target area includes an area out of the memory space (logical address that is not assumed to be allocated to memory), the error code E_MACV is returned.

The lock operation (making resident) with this API is performed in units of page, using the MMU function. Therefore, if addr is not the start address of a page or len is not an integral multiple of the page size, the entire pages containing the range specified by addr and len are taken as the target area. For example, if 1 is specified in len, one page area is locked.

In a system without MMU, all the memory can be considered resident. Thus, no specific operation must be performed in LockSpace(), but E_OK must be returned rather than an error code, in consideration of compatibility with a system using MMU. In a system without MMU, whether or not to check errors such as E_PAR is implementation-dependent.

Additional Notes

Among memory resident operations with LockSpace(), the page-in and some other operations are performed by calling the subsystem to realize a virtual memory system. The calling interface is implementation-dependent.

An area in logical address space allocated by MapMemory() must not be included in the target area for LockSpace(). The subsequent correct behavior of the whole system in such a case is not guaranteed.

UnlockSpace - Unlock Memory Space

C Language Interface

#include <tk/tkernel.h>

ER ercd = UnlockSpace (CONST void *addr , INT len );

Parameter

CONST void*	`addr`	Memory Start Address	Start address of memory to be unlocked
INT	`len`	Length	Size of memory to be unlocked (in bytes)

Return Parameter

ER ercd Error Code Error code

Error Code

E_OK	Normal completion
E_PAR	Parameter error (`len` ≦ 0)
E_MACV	An area out of the memory space is specified
E_LIMIT	Non-locked area was specified

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Unlocks (makes nonresident) the len bytes area from the logical address addr (target area). After being made nonresident with this API, the target area will be subject to page-out.

If the memory cache mode was off for the target area, it is turned on.

The target area must be the same area that was specified when LockSpace() was issued to lock it. Note that it is not possible to unlock just a part of a locked area. In addition, T-Kernel cannot detect such an operation as an error. The caller is responsible for specifying the same area.

When LockSpace() was executed more than once for the same memory area, the same number of UnlockSpace() operations can make it nonresident. UnlockSpace() returns E_OK rather than an error even if the memory area is not made nonresident because the number of UnlockSpace() operations does not reach the number of LockSpace() operations. On the other hand, if a non-locked area is specified for the target area, E_LIMIT is returned as the lock count error.

The unlock operation (making nonresident) with this API is performed in units of page, using the MMU function. Therefore, if addr is not the start address of a page or len is not an integral multiple of the page size, the entire pages containing the range specified by addr and len are taken as the target area. For example, if 1 is specified in len, one page area is unlocked.

In a system without MMU, all the memory can be considered resident. Thus, no specific operation must be performed in UnlockSpace() as well as LockSpace(), but E_OK must be returned rather than an error code, in consideration of compatibility with a system using MMU. In a system without MMU, whether or not to check errors such as E_PAR is implementation-dependent.

Additional Notes

A logical address area allocated by MapMemory() must not be included in the target area for UnlockSpace(). The subsequent correct behavior of the whole system is not guaranteed in such a case.

When performing the DMA transfer, the buffer memory area must be made resident and the buffer physical address must be set on the DMA controller after turning off the memory cache mode setting. Normal steps are as follows:

Use LockSpace() to make the buffer resident.
Use CnvPhysicalAddr() to get the buffer physical address and turn off the buffer memory cache mode setting.
Perform the DMA transfer between the buffer and the I/O device.
Use UnlockSpace() to make the buffer nonresident and turn on the buffer memory cache mode setting.

UnlockSpace() always turns on the memory cache mode setting regardless of previously issued APIs as shown above. Note that the memory cache mode setting may be changed by executing UnlockSpace().

CnvPhysicalAddr - Get Physical Address

C Language Interface

#include <tk/tkernel.h>

INT rlen = CnvPhysicalAddr (CONST void *vaddr , INT len , void **paddr );

Parameter

CONST void*	`vaddr`	Virtual Address	Logical address of the source
INT	`len`	Length	Memory area size (in bytes)
void**	`paddr`	Pointer to Physical Address	Pointer to the area to return the physical address corresponding to the logical address

Return Parameter

INT	`rlen`	Result Length	Size of contiguous physical address area (in bytes)
or		Error Code	Error code
void*	`paddr`	Physical Address	Physical address corresponding to the logical address

Error Code

E_OK	Normal completion
E_PAR	Parameter error (cache of the target area cannot be controlled)
E_MACV	An area out of the memory space is specified

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Gets the physical address corresponding to the logical address vaddr, returning the result in paddr. Also returns the contiguous size (in bytes) of the corresponding physical address in the return code rlen, within the len bytes memory area from vaddr. That is, the contiguous correspondence between the logical address and the physical address exists only for rlen in size (rlen≦len). The contiguous area in the logical address space from vaddr for rlen corresponds to the contiguous area in the physical address space from paddr for rlen.

Also turns off the memory cache mode setting for the physical address area from paddr for rlen (target area). This assumes that the DMA transfer is performed after executing CnvPhysicalAddr(). If it is not possible to make memory cached off partly by a hardware limitation, this API flush the cache memory (that is, write back it and invalidate it).

CnvPhysicalAddr() does not make the target area resident. Before performing the DMA transfer, the buffer area must be made resident (locked) by separately issuing LockSpace() for the buffer area.

If 0 or less is specified in len, the error code E_PAR is returned. If the len bytes memory area from vaddr includes an area out of the memory space (logical address that is not assumed to be allocated to memory), the error code E_MACV is returned.

Additional Notes

The CnvPhysicalAddr() API is intended to be used for preparing the DMA transfer. For concrete usage for the DMA transfer, see the additional note for UnlockSpace().

For the target area of CnvPhysicalAddr(), it is best to set the memory attribute that guarantees the completion of memory access in addition to turning off the cache mode setting.

MapMemory - Map Memory

C Language Interface

#include <tk/tkernel.h>

ER ercd = MapMemory (CONST void *paddr , INT len , UINT attr , void **laddr );

Parameter

CONST void*	`paddr`	Physical Address	Physical address to be mapped
INT	`len`	Length	Size of memory to be mapped (in bytes)
UINT	`attr`	Attribute	Memory attribute for mapping
void**	`laddr`	Pointer to Logical Address	Pointer to the area to return the mapped logical address

Return Parameter

ER	`ercd`	Error Code	Error code
void*	`laddr`	Logical Address	Mapped logical address

Error Code

E_OK	Normal completion
E_PAR	Parameter error (`len` ≦ 0)
E_LIMIT	Insufficient logical address space to be mapped
E_NOMEM	Insufficient real memory for allocating or insufficient memory for managing logical address space

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Maps the len bytes contiguous area from the physical address paddr to a logical address space and returns the mapped logical start address in laddr. The mapped memory area is made resident (locked). The attributes specified in attr are set for the mapped memory area.

The following attributes can be specified in attr:

attr := (MM_USER || MM_SYSTEM) | [MM_READ] | [MM_WRITE] | [MM_EXECUTE] | [MM_CDIS]

`MM_USER`	User level access
`MM_SYSTEM`	System level access
`MM_READ`	Read access
`MM_WRITE`	Write access
`MM_EXECUTE`	Execution
`MM_CDIS`	Disable cache

Other attributes may be specified depending on the hardware or implementation.

If NULL is specified in paddr, the actual contiguous len bytes physical memory is allocated for address and the real memory physical address space is mapped to the logical address space.

If 0 or less is specified in len, the error code E_PAR is returned. If the allocation fails due to insufficient mapped logical address space, the error code E_LIMIT is returned. If the memory required to manage the logical address space cannot be allocated or the real memory cannot be allocated when NULL is specified in paddr, the error code E_NOMEM is returned.

Additional Notes

MapMemory() has the function to map the space for an I/O device (Video RAM etc.) located in the physical address space to the logical address space that can be accessed directly from a program such as a device driver.

The mapped logical address laddr is automatically allocated during execution of this API. The mapped logical address cannot be specified.

An address within the system memory managed by T-Kernel cannot be specified in paddr. When you want to reserve the system memory with MapMemory(), specify NULL in paddr to use the system memory that is automatically allocated by T-Kernel.

Values corresponding to symbols (mnemonics) for attributes specified in attr may vary depending on implementation. Therefore, the above symbols should be used for attr, in consideration of compatibility.

MapMemory() must not be executed for the physical address area that is already a target of MapMemory(). The memory allocated by MapMemory() is a resident memory and cannot be made nonresident, so UnlockSpace() should not be called to make it nonresident. The caller is responsible for preventing such usage.

After executing MapMemory(), directly accessing paddr or subsequent physical address using other method rather than via the logical address allocated as laddr may cause cache inconsistency or other problem. With such an access, the caller is responsible for paying careful attention to data consistency.

If MM_CDIS is specified for attr, the memory attribute should guarantee the completion of memory access in addition to not using cache.

UnmapMemory - Unmap Memory

C Language Interface

#include <tk/tkernel.h>

ER ercd = UnmapMemory (CONST void *laddr );

Parameter

CONST void* laddr Logical Address Logical address to be unmapped

Return Parameter

ER ercd Error Code Error code

Error Code

E_OK	Normal completion
E_PAR	Parameter error (invalid `laddr`)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Unmaps (releases) a logical address area allocated by MapMemory(). The logical address of the area to be unmapped is specified in laddr. It must be the value retrieved from the return parameter laddr of MapMemory().

If paddr = NULL is specified to allocate the real memory when executing MapMemory(), it is also released by executing UnmapMemory().

GetSpaceInfo - Get Various Information about Address Space

C Language Interface

#include <tk/tkernel.h>

ER ercd = GetSpaceInfo (CONST void *addr , INT len , T_SPINFO *pk_spinfo );

Parameter

CONST void*	`addr`	Start Address	Start logical address to get the information for
INT	`len`	Length	Space size to get the information for (in bytes)
T_SPINFO*	`pk_spinfo`	Packet to Return Address Space Info	Pointer to the area to return the address space information

Return Parameter

ER ercd Error Code Error code

pk_spinfo Detail:

void*	`paddr`	Physical Address	Physical address corresponding to `addr`
void*	`page`	Page Start Address	Start physical address of the page that `addr` belongs to
INT	`pagesz`	Page Size	Page size (in bytes)
INT	`cachesz`	Cache Line Size	Cache line size (in bytes)
INT	`cont`	Continuous Length	Contiguous physical address space size (in bytes)
(Other implementation-dependent parameters may be added beyond this point.)

Error Code

E_OK	Normal completion
E_PAR	Parameter error (`addr`, `len`, or `pk_spinfo` is invalid or cannot be used)
E_MACV	Memory cannot be accessed; memory access privilege error

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Gets the address space information about the len bytes space from the logical address addr and returns it in the return parameter pk_spinfo. Returns the physical address corresponding to addr in paddr. Returns the start physical address of the page that addr belongs to in page.

Returns the page size in pagesz. The page size is defined in MMU and the same value as is used as unit for setting the memory access permission in SetMemoryAccess() or the cache mode in SetCacheMode().

Returns the cache line size in cachesz. The cache line size is the same value as is used as unit for controlling the cache in ControlCache().

Returns the contiguous size (in bytes) of the corresponding physical address in cont, within the len bytes space from addr. That is, the contiguous correspondence between the logical address and the physical address exists only for cont in size (cont≦len). The contiguous area in the logical address space from addr for cont corresponds to the contiguous area in the physical address space from paddr for cont.

If a paged out area exists in the range, physical addresses up to just before it are considered contiguous. Particularly, if a page to which addr belongs is paged out, cont = 0 is returned. In this case, E_OK is returned in the return code ercd and the contents other than cont in the return parameters of pk_spinfo are undefined.

If 0 or less is specified in len, the error code E_PAR is returned. When an error occurs, the contents set in pk_spinfo are undefined.

Difference from T-Kernel 1.0

This API was added in T-Kernel 2.0.

SetMemoryAccess - Set Memory Access Privilege

C Language Interface

#include <tk/tkernel.h>

INT rlen = SetMemoryAccess (CONST void *addr , INT len , UINT mode );

Parameter

CONST void*	`addr`	Start Address	Start logical address of the memory area to set the access permission for
INT	`len`	Length	Size of the memory area to set the access permission for (in bytes)
UINT	`mode`	Memory Access Mode	Mode indicating the memory access permission to be set

Return Parameter

INT	`rlen`	Result Length	Size of the area for which the memory access permission could be set (in bytes)
or		Error Code	Error code

Error Code

E_OK	Normal completion
E_PAR	Parameter error (`addr`, `len`, or `mode` is invalid or cannot be used)
E_NOSPT	Unsupported function (function specified in `mode` is unsupported)

Valid Context

Task portion	Quasi-task portion	Task-independent portion
YES	YES	NO

Description

Sets the memory access permission specified in mode for the len bytes memory area from the logical address addr. Returns the size (in bytes) of the area for which the memory access permission can actually be set, in the return code rlen.

The following memory access permissions are specified in mode:

mode := ( MM_EXECUTE | MM_READ | MM_WRITE )
                MM_EXECUTE      Execution access
                MM_READ         Read access
                MM_WRITE        Write access
                    ...
                /* Implementation-dependent mode may be added */

Setting the memory access permission with this API is performed in units of page, using the MMU function. Therefore, if addr is not the start address of a page or len is not an integral multiple of the page size, the entire pages containing the range specified by addr and len are taken as the target area for setting the memory access permission. For example, if 1 is specified in len, the memory access permission for one page is set.

Other memory access permissions may be specified depending on the hardware or implementation. Some or all of the above memory access permissions may not be set depending on the hardware or implementation. If any unavailable memory access permission is specified in mode, the error code E_NOSPT is returned.

Additional Notes

For the memory area used by normal applications, appropriate memory access permissions are set in advance by T-Kernel. Therefore, normal applications do not need to use SetMemoryAccess(). SetMemoryAccess() is intended for use by special-purpose programs rather than normal applications, for example, to allocate the system memory, dynamically manage the security, or debug programs.

The memory access permissions specified in mode are the same as some attributes specified in attr of MapMemory.

Difference from T-Kernel 1.0

This API was added in T-Kernel 2.0.

Prev	Home	Next
T-Kernel/SM Functions	Up	Device Management Functions