Syllable System Calls

Functions
area_id	sys_clone_area (const char *pzName, void **ppAddress, flags_t nProtection, flags_t nLockMode, area_id hSrcArea)
	Clones the specified area at a new address.
area_id	sys_create_area (const char *pzName, void **ppAddress, size_t nSize, flags_t nProtection, flags_t nLockMode)
	Creates a new memory area with the specified attributes.
status_t	sys_delete_area (area_id hArea)
	Deletes the specified area.
status_t	sys_get_area_info (area_id hArea, AreaInfo_s *psInfo)
	Returns an AreaInfo_s for the specified area.
status_t	sys_remap_area (area_id hArea, void *pPhysAddress)
	Remaps the specified area to use a different region of physical memory.
void *	sys_sbrk (int nDelta)
	Adjusts the upper bound of a user process's data segment.
int	alloc_tld (void)
	Allocates a TLD slot.
void *	get_tld_addr (int nHandle)
	Gives the address on the stack of the TLD.
int	free_tld (int nHandle)
	Releases a TLD slot previously allocated with alloc_tld().
int	sys_get_raw_system_time (bigtime_t *pRes)
	Returns the time elapsed since last system boot, in microseconds.
int	sys_get_raw_real_time (bigtime_t *pRes)
	Returns the number of microseconds since 1970-01-01.
int	sys_get_raw_idle_time (bigtime_t *pRes, int nProcessor)
	Returns the total idle time for the given CPU, in microseconds.
int	sys_set_real_time (uint32 nTimeLow, uint32 nTimeHigh)
	Sets the system clock to a new time.
void	set_tld (int nHandle, int nValue)
	Assign a value to a TLD slot.
int	get_tld (int nHandle)
	Retrieve the value stored in a TLD.

---

Function Documentation

int alloc_tld

(

void

)

Allocates a TLD slot.

Description:

Allocates a TLD. A TLD (thread local storage) is an integer that is allocated on the process level but accessed by threads. A thread can assign an arbitrary value to a TLD and then retrieve the value later. The TLD handle can be distributed among the threads but each thread will have its own private storage for the TLD. This means that both thread A and thread B can store different values to the same TLD without overwriting each other's TLD. This is for example used to give each thread a private "errno" global variable.

Returns:

On success a positive handle is returned.

On error -1 is returned; "errno" will receive the error code.

Error codes:

ENOMEM All TLD slots are in use.

See also:

free_tld(), set_tld(), get_tld()

Author:

Kurt Skauen ([email protected])

int free_tld

(

int

nHandle

)

Releases a TLD slot previously allocated with alloc_tld().

Parameters:

nHandle

The TLD slot to release.

Returns:

On success 0 is returned.

On error -1 is returned "errno" will receive the error code.

Error codes:

• EINVAL Invalid TLD handle.

See also:

alloc_tld(), set_tld(), get_tld()

Author:

Kurt Skauen ([email protected])

int get_tld

(

int

nHandle

)

Retrieve the value stored in a TLD.

Description:

Retrieve the value stored earlier by *this* thread.

Parameters:

nHandle

The TLD to examine.

Returns:

The value of the given TLD

See also:

set_tld(), alloc_tld(), free_tld()

Author:

Kurt Skauen ([email protected])

void* get_tld_addr

(

int

nHandle

)

Gives the address on the stack of the TLD.

Parameters:

nHandle

The TLD to calculate the address for. Deprecated & marked for removal.

Returns:

On success the address of the TLD is returned. On failure, NULL is returned.

Error codes:

• NULL Invalid TLD handle.

See also:

alloc_tld(), set_tld(), get_tld()

Author:

Kristian Van Der Vliet ([email protected])

void set_tld	(	int	nHandle,
		int	nValue
	)

Assign a value to a TLD slot.

Description:

Assign a value to the calling thread's storage associated with the given TLD handle. This will not affect the value of the same TLD in another thread and the value can only be read back by the thread that actually assigned it.

Parameters:

	nHandle	Handle to a TLD slot previously allocated by alloc_tld()
	nValue	The value to assign to the TLD.

See also:

get_tld(), alloc_tld(), free_tld()

Author:

Kurt Skauen ([email protected])

area_id sys_clone_area	(	const char *	pzName,
		void **	ppAddress,
		flags_t	nProtection,
		flags_t	nLockMode,
		area_id	hSrcArea
	)

Clones the specified area at a new address.

Parameters:

	pzName	a pointer to the string containing the name of the new area.
	ppAddress	a pointer to the variable where the start address of the new area will be stored, or NULL. If non- NULL, the previous value of the variable it points to will be used as the preferred start address of the new area.
	nProtection	a protection bitmask containing any combination of: AREA_READ, AREA_WRITE, AREA_EXEC, AREA_KERNEL, and AREA_WRCOMB.
	nLockMode	the locking mode to use: AREA_NO_LOCK, AREA_LAZY_LOCK, AREA_FULL_LOCK, or AREA_CONTIGUOUS.
	hSrcArea	the area_id of the area to clone.

Returns:

-EFAULT if there is a memory access violation while copying pzName; -EINVAL if the preferred starting address at *ppAddress is not a multiple of PAGE_SIZE; the area_id of the new area otherwise.

See also:

alloc_area()

Author:

Kurt Skauen ([email protected])

area_id sys_create_area	(	const char *	pzName,
		void **	ppAddress,
		size_t	nSize,
		flags_t	nProtection,
		flags_t	nLockMode
	)

Creates a new memory area with the specified attributes.

Parameters:

	pzName	a pointer to the string containing the name for the new area.
	ppAddress	a pointer to the variable where the start address of the new area will be stored, or NULL. If non- NULL, the previous value of the variable it points to will be used as the preferred start address of the new area.
	nSize	the size in bytes of the requested area.
	nProtection	a protection bitmask containing any combination of AREA_READ, AREA_WRITE, AREA_EXEC, AREA_KERNEL, and AREA_WRCOMB.
	nLockMode	the locking mode to use: AREA_NO_LOCK, AREA_LAZY_LOCK, AREA_FULL_LOCK, or AREA_CONTIGUOUS.

Returns:

-EFAULT if there is a memory access violation while copying pzName; -EINVAL if the preferred start address at *ppAddress is not a multiple of PAGE_SIZE; -ENOADDRSPC if there isn't enough virtual address space, -ENOMEM if there isn't enough physical memory; the area_id of the new area otherwise.

See also:

alloc_area(), do_create_area()

Author:

Kurt Skauen ([email protected])

status_t sys_delete_area

(

area_id

hArea

)

Deletes the specified area.

Parameters:

hArea

a handle to the area to delete.

Returns:

-EINVAL if the area handle is invalid or if the area doesn't belong to this process; 0 otherwise.

See also:

do_delete_area()

Author:

Kurt Skauen ([email protected])

status_t sys_get_area_info	(	area_id	hArea,
		AreaInfo_s *	psInfo
	)

Returns an AreaInfo_s for the specified area.

Parameters:

	hArea	a handle to the area for which to return info.
	psInfo	a pointer to the AreaInfo_s in which to store the results.

Returns:

-EINVAL if the area handle is invalid or the area doesn't belong to this process; -EFAULT if there is a memory access violation while copying to psInfo; 0 otherwise.

Author:

Kurt Skauen ([email protected])

int sys_get_raw_idle_time	(	bigtime_t *	pRes,
		int	nProcessor
	)

Returns the total idle time for the given CPU, in microseconds.

Parameters:

	pRes	a pointer to the bigtime_t in which to store the CPU idle time.
	nProcessor	the processor for which to return the idle time.

Author:

Kurt Skauen ([email protected])

int sys_get_raw_real_time

(

bigtime_t *

pRes

)

Returns the number of microseconds since 1970-01-01.

Parameters:

pRes

a pointer to the bigtime_t in which to store the current time.

Author:

Kurt Skauen ([email protected])

int sys_get_raw_system_time

(

bigtime_t *

pRes

)

Returns the time elapsed since last system boot, in microseconds.

Parameters:

pRes

a pointer to the bigtime_t in which to store the system time.

Author:

Kurt Skauen ([email protected])

status_t sys_remap_area	(	area_id	hArea,
		void *	pPhysAddress
	)

Remaps the specified area to use a different region of physical memory.

Parameters:

	hArea	a handle to the area to remap.
	pPhysAddress	the new start address in physical memory for the region.

Returns:

-EINVAL if the area handle is invalid or if nPhysAddress isn't a multiple of PAGE_SIZE; 0 otherwise.

See also:

do_remap_area()

Author:

Kurt Skauen ([email protected])

void* sys_sbrk

(

int

nDelta

)

Adjusts the upper bound of a user process's data segment.

Parameters:

nDelta

the number of bytes by which to increase or decrease the data segment.

Returns:

-1 if there was an error adjusting the data segment; otherwise, the old upper bound of the process's data segment.

Author:

Kurt Skauen ([email protected])

int sys_set_real_time	(	uint32	nTimeLow,
		uint32	nTimeHigh
	)

Sets the system clock to a new time.

Does not set the RTC.

Parameters:

	nTimeLow	the low 32 bits of the new system time, in microseconds since 1970-01-01.
	nTimeHigh	the high 32 bits of the new system time

Returns:

Always returns 0.

Attention:

Missing check for sufficient privileges to set the system clock.

Author:

Kurt Skauen ([email protected])

---