Kernel API Documentation

Processor Family

Blackfin

Description

Kernel api abstracts the primitive operating system services and facilitates easy migration of applications to different operating system environments.The basic services include synchronization services, interrupt services, and timer based callback services.kernel-api provides a standard and uniform interface irrespective of the underlying operating environment. This abstraction enables the applications to be portable across different operating system platforms and environments.

Operation of Kernel Interface

The kernel interface is designed to allow it to be provided in both multi-threaded and single threaded environments.The kernel api interface abstracts a minimal set of operating system services that are required by most of the algorithmic and control applications.

Synchronization Services

The kernel api offers counting semaphore as synchronization or communication mechanism among executing entities. Counting semaphores are used to schedule multiple instances of a resource between several executing entities (threads or processes). Each counting semaphore is associated with a maximum-count and initial-count. Maximum count specifies the maximum number of resource instances that can be acquired.If a semaphore is released more than the maximum-count number of times the count will not exceed maximum-count. Initial count specifies the count of the semaphore when its created.If maximum-count is 1 then its a binary semaphore and can be treated as mutex. If the initial-count is 0 (binary semaphore) means its not available so an execution entity will block until its available. To acquire an instance of a resource the associated semaphore count is atomically decremented. If the value is greater than 0 the resource is still available and can be acquired by other execution entities. In a multi-threaded environment all calling threads will block if the count is 0. kernel API interface implementations must document the schedule criteria if multiple threads are blocked on a semaphore when the semaphore is released.

Each semaphore object is allocated a unique identifier by the underlying kernel implementation and this identifier is passed by any application on each function that operates on the object. The unique identifier is a ker_sem_id_t type whose C declaration is as shown below

typedef unsigned int ker_sem_id_t

Applications use the kernel api ker_get_semaphore function to obtain a semaphore object and the ker_rel_semaphore function to release the object and hand the ownership of the object back to the operating system when it is no longer required by the component. Once an object has been obtained, the component calls the ker_pend_semaphore to acquire the synchronization object and the kernel is expected to block the execution entity if the object is not available. Once the object has been acquired it is made available by calling the ker_post_semaphore function. Multiple ker_pend_semaphore may be active on a synchronization object when the ker_post_semaphore function is invoked and in such a scenario the kernel is expected to release only one execution entity on each invocation of ker_post_semaphore function for the object.

An sync service example

If an application's read request on a socket, can not be satisfied then the TCP/IP module will perform a ker_pend_semaphore on the associated synchronization object. Once data is available on the socket then the associated synchronization object is signaled through a call on the ker_post_semaphore function which will unblock the waiting execution entity.

Synchronization Object Criteria

The nature of the implementation of the kernel api's synchronization services will be dependent on the functionality provided by the underlying operating system. The underlying implementation object could be a binary semaphore, mutex or any other specific implementation. The interface does not mandate the implementation mechanism but does require that all implementations meet some specific criteria. Irrespective of its implementation, an kernel api's synchronization object must fulfill the following criteria:

Timer Services

All timer related calls in the kernel API operate on milli-second granularity. The interface abstracts the underlying tick period and timer configuration. The kernel api allows a thread to request that it should block for a specified period by calling the ker_sleep function.

Name Type Description
ker_sem_id_t typdef ker_sem_id_t is the type for the identifier of a Semaphore synchronization object.The kernel api returns an id when a new object is allocated by a call on the ker_get_semaphore function and is used on the other function calls to identify which synchronization object is being operated on.
ker_priority_level_e enum The Priority level enumeration defines the priority levels that are accepted by the ker_disable_interrupts and ker_enable_interrupts functions. These enumerations are valid only for the Blackfin Family of processors running on VDK.

Methods

Name Description
ker_get_semaphore ker_get_semaphore is used obtain the identifier for a new semaphore object.
ker_rel_semaphore ker_rel_semaphore releases a semaphore object and returns ownership of the object to the underlying operating system.
ker_pend_semaphore ker_pend_semaphore enables the caller to acquire a semaphore object.
ker_post_semaphore ker_post_semaphore releases (or signals) the specified synchronization object.
ker_disable_interrupts ker_disable_interrupts disables interrupts up to the priority level specified.
ker_enable_interrupts ker_enable_interrupts re-enables interrupts after a call on ker_disable_interrupts.
ker_sleep Blocks the execution entity for the specified number of milliseconds.
ker_set_lasterror ker_set_lasterror sets the supplied last error value to the executing thread or process specific error of the OS.
ker_get_lasterror ker_get_lasterror returns the last error value for the current executing thread.ker_set_lasterror sets the error value and typically stores in the executing threads context.
ker_get_systime ker_get_systime returns the current system time in milliseconds since the system boot.
ker_get_auxdata Auxiliary data thats passed by the environment to the kernel. This value can be used by the kernel api interface developers to pass in any extra data during the initialization. ker_get_auxdata returns the pointer to the data.
ker_set_auxdata Auxiliary data can be used to pass in any auxiliary information to the underlying OS. For example in VDK environement generic VDK thread template that is used to create lwip threads is passed to kernel interface during initialziation.


typedef ker_sem_id_t

Definition

typedef   unsigned int   ker_sem_id_t

Description

ker_sem_id_t is the type for the identifier of a Semaphore synchronization object.The kernel api returns a ker_sem_id_t when a new object is allocated by a call on the ker_get_semaphore function and is used on the other function calls to identify which synchronization object is being operated on.



enum kernel_results_e

Enum Members

Name
ker_err_sem_cre
ker_err_sem_timeout
ker_err_sem_id
ker_err_ints_off
ker_err_int_priority
ker_err_thread_cre
ker_err_thread_id
ker_err_thread_priority
ker_err_1
ker_err_panic

Description

Kernel APIs typically return 0 upon success.The below error enumeration and the circumstances in which it may be returned by the kernel api functions.

ker_err_sem_cre
ker_get_semaphore returns this error when operating system is not able to create an synchronization object because of lack of memory or a system limit is reached.
ker_err_sem_timeout
ker_pend_semaphore returns this error when a timeout occurs on a synchronization object.
ker_err_sem_id
ker_pend_semaphore, ker_post_semaphore and ker_rel_semaphore may return this error when an invalid synchronization object is passed to them. It is not mandatory for these functions to detect an invalid object identifier, but if they do detect an invalid object identifier they must return this error.
ker_err_ints_off
ker_sleep may return this error when a call is made on the function while interrupts are disabled. It is not mandatory for the ker_sleep function to detect and return this error.



Enum

Enum Members

Name
kPriorityLevel0
kPriorityLevel1
kPriorityLevel2
kPriorityLevel3
kPriorityLevel4
kPriorityLevel5
kPriorityLevel6
kPriorityLevel7
kPriorityLevel8
kPriorityLevel9
kPriorityLevel10
kPriorityLevel11
kPriorityLevel12
kPriorityLevel13
kPriorityLevel14
kPriorityLevel15
kPriorityLevelAll

Description

The Priority level enumeration defines the priority levels that are accepted by the ker_disable_interrupts and ker_enable_interrupts functions. Prioroty level is used enable or disable interrupts up to the specified priority level.The priority level directly maps to the core interrupt priority level. kernel api implementations must clearly document any special behavior with respect to a given priority level. kPriorityLevel0 is the highest priority level and kPriorityLevel15 is lowest for ADSP-BF5xx family.

There are two special priority levels.kPriorityLevelAll is a special priority level which disables all interrupts,except NMI, Emulation and Reset. In multi-threaded environments kPriorityLevelUnSchedule disables the scheduler, so that thread switching is disabled. Kernel API implementations should document the usage of interrupts for implementing kPriorityLevelUnSchedule support.

Priority level enumerations will be different for different processor architectures.

Priority level mappings across ADI family of processors

Blackfin Family (BF5xx)
Priority level BFxxx interrupt level Description
kPriorityLevel0 Emulation (EMU) Invalid Priority level to Enable or Disable Interrupts
kPriorityLevel1 Reset (RST) Invalid Priority level to Enable or Disable Interrupts
kPriorityLevel2 Non Maskable Interrupt (NMI) Invalid Priority level to Enable or Disable Interrupts
kPriorityLevel3 Exception (EVX) Invalid Priority level to Enable or Disable Interrupts
kPriorityLevel4 Reserved Invalid Priority level to Enable or Disable Interrupts
kPriorityLevel5 Hardware Error (IVHW) Valid Priority Level
kPriorityLevel6 Core Timer (IVTMR) Valid Priority Level
kPriorityLevel7 General Purpose Interrupt (IVG7) Valid Priority Level
kPriorityLevel8 General Purpose Interrupt (IVG8) Valid Priority Level
kPriorityLevel9 General Purpose Interrupt (IVG9) Valid Priority Level
kPriorityLevel10 General Purpose Interrupt (IVG10) Valid Priority Level
kPriorityLevel11 General Purpose Interrupt (IVG11) Valid Priority Level
kPriorityLevel12 General Purpose Interrupt (IVG12) Valid Priority Level
kPriorityLevel13 General Purpose Interrupt (IVG13) Valid Priority Level
kPriorityLevel14 General Purpose Interrupt (IVG14) Valid Priority Level
kPriorityLevel15 General Purpose Interrupt (IVG15) Valid Priority Level
kPriorityLevelAll Disables All interrupts Valid Priority Level



ker_get_semaphore

C:    int   ker_get_semaphore(const unsigned int initialCount, const unsigned int maximumCount)

Description

ker_get_semaphore is used obtain the identifier for a new semaphore object. ker_get_semaphore transfers the ownership of the semaphore object from the operating system to the application. In all further interactions this object ID is used as the communication means between the application and the OS. The OS should not reuse or free the memory associated with the synchronization object until the object ownership is returned to the OS by the stack calling ker_rel_semaphore function for the identifier.

ker_get_semaphore initializes the new semaphore object that is created. Operating system may fail to fulfill the ker_get_semaphore request because of any of the following:

If the underlying operating system does not support the dynamic creation of synchronization objects then the kernel api implementation will be responsible for managing the allocation of a pool of statically allocated objects. The kernel implementation documentation must explain how the maximum number of needed synchronization objects can be managed.

Example
The object ID returned by the ker_get_semaphore is used in TCP/IP component for synchronization and signaling. ker_pend_semaphore is used to block the current executing entity until the sync object is posted using ker_post_semaphore function. Typically in a multithreaded environment if a read request on a socket could not be satisfied at the point of a call, then the thread will be blocked on a sync object until some data is available. Once some data is available the associated sync object is posted, so that the corresponding thread resumes execution.

The implementation of the synchronization objects is OS specific. But it should fulfill the synchronization object criteria.The kernel interface can implement synchronization object functionality using binary semaphores, mutex's, events or any other specific mechanisms. All the interactions with the external components are through the ker_sem_id_t obtained by ker_get_semaphore function.

ker_get_semaphore must ensure that the initial count of the new semaphore is as specified by the initialCount and Maximum count as specified by maximumCount

ker_get_semaphore returns ker_err_sem_cre error when operating system is unable to return a new synchronization object because of lack of memory or system maximum limit is reached.

Parameters

Name Type Description
syncObjectID ker_sem_id_t returns a valid synchronization object identifier if the call is successful.
initialCount unsigned int specifies the initial count of the semaphore.
maximumCount unsigned int specifies the maximum count of the semaphore.

Returns

Returns the semaphore id upon success. Retuns -1 upon failure.


ker_rel_semaphore

Prototype

C:    int   ker_rel_semaphore(ker_sem_id_t sem_id)

Description

ker_rel_semaphore releases a semaphore object and returns ownership of the object to the underlying operating system. The object must have been obtained from a previous call to the ker_get_semaphore function.It is preferred (but it is not mandatory) that any attempt to release an object that has been already released or provide an object identifier that was not obtained through ker_get_semaphore should return the ker_err_sem_id error.

When an object is released, the kernel becomes the owner of the object and it may destroy the underlying operating system object immediately. If multiple threads are pending on a semaphore, and the semaphore is released the behavior is un-specified.

The kernel interface implementation may elect to re-use an released synchronization object to satisfy subsequent requests to ker_get_semaphore. In such a scenario the kernel interface must ensure that the state of the re-used object is set to the object attributes specified in ker_get_semaphore before returning the object to the caller.

It is preferable (but not mandatory) that the kernel interface implementation should not re-use object identifiers even if the underlying object is re-used.

ker_rel_semaphore may return the ker_err_sem_id error if an invalid synchronization object identifier is passed. However it is not mandatory that this specific return code is issued.

Parameters

Name Type Description
sem_id ker_sem_id_t Identifies the synchronization object that is to be released.

Returns

Returns 0 upon success. Returns ker_err_sem_id if the passed semaphore is invalid.


ker_pend_semaphore

Prototype

C:    int   ker_pend_semaphore(ker_sem_id_t sem_id, unsigned int timeout_period)

Description

ker_pend_semaphore enables the caller to acquire a semaphore object. If the semaphore object count is zero the caller will block until it does become available or until the specified number of milliseconds have passed. If the specified number of milliseconds is zero then the caller will remain blocked until the object is acquired.

If the semaphore is available (count > 0), then ker_pend_semaphore immediately returns after atomically decrementing the associated count value.Once the count reaches zero, all subsequent ker_pend_semaphore will block.A ker_post_semaphore operation will increment the semaphore count and activate a blocked execution entity. Each acquired object is released by ker_post_semaphore function.

If the requested object does not become available during the specified number of milliseconds then ker_pend_semaphore will unblock and return the error code ker_err_sem_timeout.

In a multi-threaded environment multiple execution entities may be pended for a single semaphore at some point of time. In such a scenario if a ker_post_semaphore occurs then the kernel interface will unblock a single pended execution entity. The choice of execution entity is not specified.

In multi-threaded environments kernel interface must ensure that calls to ker_pend_semaphore from different threads must execute in atomic manner, i.e., one thread's ker_pend_semaphore execution should not corrupt another thread's ker_pend_semaphore on the same object.

The behavior of the ker_pend_semaphore function is undefined if an invalid object identifier is supplied to it.

ker_pend_semaphore may return a ker_err_sem_id result code if an invalid semaphore identifier is passed to it.

ker_pend_semaphore must return a ker_err_sem_timeout error when the requested ker_pend_semaphore times out.

Parameters

Name Type Description
sem_id ker_sem_id_t Identifies the object on which the current calling unit wishes to acquire.
timeout_period unsigned int is the timeout period in millisecond the call will block for while waiting to acquire the semaphore. If timeout_period is zero then ker_pend_semaphore will wait indefinitely to acquire the semaphore.

Returns

Returns 0 upon success. Returns ker_err_sem_timeout upon timeout, and ker_err_sem_id for invalid semaphore id.


ker_post_semaphore

Prototype

C:    int   ker_post_semaphore(ker_sem_id_t sem_id)

Description

ker_post_semaphore releases (or signals) the specified synchronization object. Releasing the object sets the state of the object to be AVAILABLE. If any execution entities are pending on acquiring this object, then the change of state from NOT_AVAILABLE to AVAILABLE allows one of the pending entities to be unblocked. When more than one execution entity is waiting on acquiring the object, then the choice of entity to be unblocked is determined by the kernel interface.

IOE synchronization objects are mutually exclusive i.e. they have binary state and when a thread acquires a synchronization object the state of the object is changed to be NOT_AVAILABLE. The state of the object remains NOT_AVAILABLE until ker_post_semaphore is called for that object. When the object state is NOT_AVAILABLE then all further requests by ker_pend_semaphore will be blocked by the kernel interface.

If an object is already available, a ker_post_semaphore will not have any effect on the state of the object.

ker_post_semaphore on an unknown object identifier or an object that has been released through ker_rel_semaphore may generate a ker_err_sem_id result code.

Parameters

Name Type Description
sem_id sem_id Identifies the synchronization object that is to be signaled.

Returns

Returns 0 upon success and ker_err_sem_idupon invalid semaphore id.


ker_disable_interrupts

Prototype

C:    int   ker_disable_interrupts(int priority_level)

Description

ker_disable_interrupts disables interrupts up to the priority level specified. kPriorityLevelAll disables all interrupts, except NMI,Emulation and Reset interrupts. No interrupts will be serviced after ker_disable_interrupts has been invoked until a matching call on ker_enable_interrupts is made.

The kernel interface is expected to support nested disabling of interrupts i.e. the users of the kernel interface must ensure that for every ker_disable_interrupts call there exists a corresponding ker_enable_interrupts call. Interrupts will only be enabled after a matching number ker_enable_interrupts calls.

The kernel interface is not expected to correct any improper or incorrect usage of the ker_disable_interrupts or ker_enable_interrupts functions. Disabling interrupts will normally prevent any thread switching from occurring unless the application explicitly causes a task switch.

The kernel interface is not responsible for interrupt misses which may arise if interrupts are left disabled for anything but very short periods. It should be noted part of the kernel interface code itself may execute with interrupts disabled.

Disable or Enable interrupts only mask or unmask the interrupts. that are enabled before. IOE component implementations must clearly document any special behavior with respect to a given priority level. The documentation shoule also specify the consequences of directly manipulating the processors interrupt registers.

Parameters

Name Type Description
priority_level priority_level_e All interrupts at or below this level will be disabled.

Returns

Returns 0 upon success. Returns ker_err_int_priority upon invalid priority.


ker_enable_interrupts

Prototype

C:    int   ker_enable_interrupts(int priority_level)

Description

ker_enable_interrupts re-enables interrupts after a call on ker_disable_interrupts. After execution of the function interrupts are re-enabled and serviced. Any invocation of ker_enable_interrupts without a prior use of ker_disable_interrupts should be ignored by the kernel interface. ker_enable_interrupts will enable interrupts up to the given priority level. Typically the passed priority level will be same as used in ker_disable_interrupts. If the enabling priority level is different from that of ker_disable_interrupts then ker_enable_interrupts must enable interrupts up to the given priority level.

The kernel interface is expected to support nested disabling of interrupts i.e. the users of the kernel interface must ensure that for every ker_disable_interrupts call there exists a corresponding ker_enable_interrupts call. Interrupts will only be enabled after a matching number ker_enable_interrupts calls.

The kernel interface is not expected to correct any improper or incorrect usage of the ker_disable_interrupts or ker_enable_interrupts function.

Disable or Enable interrupts only mask or unmask the interrupts. that are enabled before. kernel component implementations must clearly document any special behavior with respect to a given priority level. The documentation should also specify the kernel component behavior if application directly manipulates the processors interrupt registers.

Parameters

Name Type Description
priority_level int All interrupts at or below this level will be enabled. For Blackfin family priority_level_e defines the valid priority levels.

Returns

Returns 0 upon success, Returns ker_err_int_priority upon invalid priority.


ker_sleep

Prototype

C:    int   ker_sleep(const unsigned int sleep_time)

Description

Blocks the execution entity for the specified number of milliseconds.

The kernel interface may detect that interrupts have been disabled when the function has been called and may optionally return the ker_err_ints_off result code.

Parameters

Name Type Description
sleep_time unsigned int Specifies the number of milliseconds to block for.

Returns

Returns 0 upon success.


ker_set_lasterror

Prototype

C:    int   ker_set_lasterror(int last_error)

Description

ker_set_lasterror sets the supplied last error value to the executing thread or process specific error of the OS. The ker_set_lasterror and ker_get_lasterror calls provides means to store and retrieve per-thread errors in multi-threaded environments.

Example: TCP/IP stack uses this function to supply the socket errors thrown with in socket API. As stack is a library and it has no way to keep track of the socket errors thrown by the threads in a multi threaded environments. This function is used by the stack to supply the socket error to the operating system in hand. Operating system must preserve this error value and supply back to the application when they query for it.

Parameters

Name Type Description
last_error int supplies the error value.

Returns

Returns 0 upon success.


ker_get_lasterror

Prototype

C:    int   ker_get_lasterror()

Description

ker_get_lasterror returns the last error value for the current executing thread.ker_set_lasterror sets the error value and typically stores in the executing threads context. ker_get_lasterror returns the last error value set for the requested current thread.The error values are application specific.

Example: TCP/IP stack uses this the SetSockError function to supply the socket errors thrown within the socket API. The GetSockError function is used by the stack to obtain the last store socket error for the currently executing thread. The IOE interface implementation is responsible for preserving this error value separately for each thread and returning it on the ker_get_lasterror function call.

Parameters

Returns

Returns the last error value.


ker_get_systime

Prototype

C:    int   ker_get_systime()

Description

ker_get_systime returns the current system time in milliseconds since the system boot.

Parameters

Returns

Returns the systems time in milli-seconds since the system boottime.

Thread API

Thread API extends the primitive OS services towards the multi-threaded systems. It abstracts the underlying multi-threaded opearting system and faciliates easy migration of components and applications across different multithreaded operating environments.

Name Description
ker_create_thread ker_create_thread creates a seperate executing entity in the given operating environment at a given priority level.
ker_get_current_thread ker_get_current_thread returns the current threadID of the executing thread.
ker_destroy_thread ker_destroy_thread destroys the thread and cleans up the memory associated with that thread.
ker_set_thread_priority ker_set_thread_priority sets the priority of a thread.
ker_get_thread_priority ker_get_thread_priority sets the priority of a thread.kernel interface implementations specify the supported priority levels.
ker_disable_scheduler ker_disable_scheduler is used to disable scheduler.
ker_enable_scheduler ker_enable_scheduler is used to enable scheduler.
ker_set_auxdata Use to pass in any auxiliary information to the kernel implementation. In VDK port thread template id is passed as the auxiliary information.
ker_get_auxdata Returns the auxiliary information set by the environment. Kernel implemtations may choose not to return it.

Description

ker_err_thread_cre
ker_create_thread returns this error when operating system is not able to create a thread object because of lack of memory or a system limit is reached.
ker_err_thread_id
ker_destroy_thread or ker_get_thread_priority or ker_set_thread_priority returns this error when an invalid thread identifier is passed.
ker_err_thread_id
ker_create_thread or ker_set_thread_priority may return this error if invalid priority is passed.




ker_create_thread

Prototype

C:    int   ker_create_thread(void* th_entry_point,void* th_args, int stackSize, const void* th_stack_area, int priority, char *name )

Description

CreateThread creates a seperate executing entity in the given operating environment at a given priority level. Execution of the supplied via a function pointer.

Parameters

Name Type Description
th_entry_point void* is the start address of the thread, in C terms it is a pointer to a function taking one argument of type void* and returning void.
th_args void* is the argument for this thread.
th_stack_sz int is an estimate of the size of stack required for the thread.It may be -1 in which case a default size is used and stackArea is ignored.
th_stack_area void* is the address of an area of memory to be used as this thread's stack. A component may document the fact that it ignores this parameter.(eg a VDK-based system cannot use it) or that it treats the NULL address as a request to provide a stack area itself.
priority int is what you expect it to be. The kernel interface implementations specify the priority values.
name char is an optional string to be attached to this thread. Some kernels allow you to name threads and they include the name in scheduler tracing or table dumps.Supplying a NULL or zero-length string to a component that supports the naming of threads means that the component will invent a name.

Returns

Returns the thread id of the newly created thread upon success.


ker_get_current_thread

Prototype

C:    int   ker_get_current_thread()

Description

ker_get_current_thread returns the current threadID of the executing thread.

Parameters

None

Returns

Returns the thread id of the current excecuting thread.


ker_destroy_thread

Prototype

C:    int   ker_destroy_thread(int thread_id)

Description

ker_destroy_thread destroys the thread and cleans up the memory associated with that thread. Any specific issues with respect to destroying should be documented by the kernel interface implementation.

Parameters

Name Type Description
thread_id int thread_id of the thread to be destroyed.

Returns

Returns 0 upon success. If the thread id is wrong it will return ker_err_thread_id.


ker_set_thread_priority

Prototype

C:    int   ker_set_thread_priority(int thread_id,int thread_priority)

Description

ker_set_thread_priority sets the priority of a thread. kernel interface implementations specify the supported priority levels.

Parameters

Name Type Description
threadID int is the thread_id.
thread_priority int is the new priority of the thread.

Returns

Returns 0 upon success. If the thread id is invalid it return ker_err_thread_id.


ker_get_current_thread

Prototype

C:    int   ker_get_thread_priority(int thread_id)

Description

ker_get_thread_priority sets the priority of a thread.kerel interface implementations specify the supported priority levels.

Parameters

Name Type Description
thread_id int is the thread id.

Returns

Returns priority of the thread identified by the id. If the id is invalid it return ker_err_thread_id.


ker_disable_scheduler

Prototype

C:    int   ker_disable_scheduler()

Description

ker_disable_scheduler is used to disable scheduler. By Disabling the scheduler thread switching will get disabled,i.e., current thread will not relinquish CPU though high priority threads are ready.

Parameters

None

Returns

Returns 0 upon success.


ker_enable_scheduler

Prototype

C:    int   ker_enable_scheduler()

Description

EnableScheduler is used to enable scheduler. By enabling the scheduler thread switching will be enabled,i.e., Any highest priority ready-to-run thread will be scheduled.

Parameters

None

Returns

Returns 0 upon success.