cyg_thread_create
Name: cyg_thread_create ( ) - create a new thread
Synopsis:
void cyg_thread_create
(
  cyg_addrword_t     sched_info,  /* scheduling info (priority) */
  cyg_thread_entry_t *entry,      /* thread entry point         */
  cyg_addrword_t     entry_data,  /* entry point argument       */
  char               *name,       /* name of thread             */
  void               *stack_base, /* pointer to stack base      */
  cyg_ucount32       stack_size,  /* size of stack in bytes     */
  cyg_handle_t       *handle,     /* returned thread handle     */
  cyg_thread         *thread      /* space to store thread data */
)
Description: This creates a new thread. The ID of the thread is returned through "*handle". Since eCos does it's best to never use dynamic memory "*thread" is is used to store thread specific information. Once the thread is created it can be manipulated with "handle".

One thing to note is that like Unix, the lower the priority value (i.e. sched_info) the higher the priority. A priority of 0 is the highest possible priority in the system and CYG_THREAD_MIN_PRIORITY is the lowest possible priority. It is a good idea not to run any thread at CYG_THREAD_MIN_PRIORITY since the idle thread runs at that priority.

Priority values depend on the scheduler. Note that if you use the bitmap scheduler, two threads cannot share the same priority.

Note that threads are created in a suspended state. Before the thread will run, you must call cyg_thread_resume.

The entry function prototype is: void cyg_thread_entry(CYG_ADDRWORD data).

Include: #include <cyg/kernel/kapi.h>
Returns: nothing.
See Also: cyg_thread_exit, cyg_thread_delete, cyg_thread_kill, cyg_thread_set_priority, cyg_thread_add_destructor, cyg_thread_rem_destructor

cyg_thread_exit
Name: cyg_thread_exit ( ) - exit a thread
Synopsis:
void cyg_thread_exit
(
  void
)
Description: This stops the calling thread. Be sure that any resources that have been allocated by the thread have been freed before calling this function otherwise you risk deadlocking the system.

This will cause any destructors associated with the thread to be called before the thread exits.

Include: #include <cyg/kernel/kapi.h>
Returns: nothing - this function doesn't return
See Also: cyg_thread_create, cyg_thread_exit, cyg_thread_delete, cyg_thread_resume, cyg_thread_kill, cyg_thread_add_destructor, cyg_thread_rem_destructor

cyg_thread_delete
Name: cyg_thread_delete ( ) - delete a thread
Synopsis:
cyg_bool_t cyg_thread_delete
(
  cyg_handle_t thread /* thread to delete */
)
Description: This deletes a thread. This is a dangerous function to call. If it's possible, send a message to the thread you want to delete and let itself shutdown with cyg_thread_exit.
Include: #include <cyg/kernel/kapi.h>
Returns: "true" is the thread was deleted, "false" otherwise.
See Also: cyg_thread_create, cyg_thread_exit, cyg_thread_kill, cyg_thread_release, cyg_thread_add_destructor, cyg_thread_rem_destructor

cyg_thread_suspend
Name: cyg_thread_suspend ( ) - suspend a thread
Synopsis:
void cyg_thread_suspend
(
  cyg_handle_t thread /* thread to suspend */
)
Description: This suspends a thread. A thread can be suspended multiple times. For each call to cyg_thread_suspend, there must be a call to cyg_thread_resume to take the thread out of the suspended state.
Include: #include <cyg/kernel/kapi.h>
Returns: nothing
See Also: cyg_thread_resume

cyg_thread_resume
Name: cyg_thread_resume ( ) - resume a suspended thread
Synopsis:
void cyg_thread_resume
(
  cyg_handle_t thread /* thread to resume from a suspended state */
)
Description: This decrements the suspend count on a thread. If the suspend count goes to 0, the thread will be resumed and will then continue to run.

If the thread was exited, this will reinitialize the thread.

(? RBW: Will reinitializing thread cause the thread to reinitialize in a suspended state or a running state ? - need to test )

Include: #include <cyg/kernel/kapi.h>
Returns: nothing
See Also: cyg_thread_suspend

cyg_thread_kill
Name: cyg_thread_kill ( ) - kill a thread
Synopsis:
void cyg_thread_kill
(
  cyg_handle_t thread /* thread to kill */
)
Description: This will force another thread to exit and cause it to stop. This is dangerous to use because if the thread that is being killed has any resources allocated (memory, semaphores, mutexes, etc.) they will not be freed when the thread is killed. This can cause the system to deadlock.

This will cause any destructors associated with the thread to be called before the thread is killed.

Include: #include <cyg/kernel/kapi.h>
Returns: nothing
See Also: cyg_thread_create, cyg_thread_exit, cyg_thread_delete

cyg_thread_release
Name: cyg_thread_release ( ) - release a thread from a wait
Synopsis:
void cyg_thread_release
(
  cyg_handle_t thread /* thread to release */
)
Description: This causes a thread that is in a wait to be broken out of it. It is the responsibility of the thread that was released to detect that it was broken out of it's wait. If you make use of this function, you will have to program defensively around any synchronization mechanism.
Include: #include <cyg/kernel/kapi.h>
Returns: nothing
See Also: cyg_thread_delay

cyg_thread_yield
Name: cyg_thread_yield ( ) - yield the thread to another thread of equal priority
Synopsis:
void cyg_thread_yield
(
  void
)
Description: This yields control of the CPU to the next runnable thread of equal priority. If there is no other runnable thread of equal priority this will effectively do nothing.
Include: #include <cyg/kernel/kapi.h>
Returns: nothing
See Also: cyg_thread_delay

cyg_thread_self
Name: cyg_thread_self ( ) - get calling thread's thread ID
Synopsis:
cyg_handle_t cyg_thread_self
(
  void
)
Description: This gets the thread ID of the calling thread.
Include: #include <cyg/kernel/kapi.h>
Returns: the thread ID of the calling thread
See Also: cyg_thread_create

cyg_thread_idle_thread
Name: cyg_thread_idle_thread ( ) - get the idle thread's thread ID
Synopsis:
cyg_handle_t cyg_thread_idle_thread
(
  void
)
Description: This function gets the idle thread's thread ID. Be careful with modifying the idle thread's priority, or in general doing anything with it since it's not a standard thread.
Include: #include <cyg/kernel/kapi.h>
Returns: the thread ID of the idle thread
See Also:

cyg_thread_set_priority
Name: cyg_thread_set_priority ( ) - set the priority of a thread
Synopsis:
void cyg_thread_set_priority
(
  cyg_handle_t   thread,  /* thread ID    */
  cyg_priority_t priority /* new priority */
)
Description: This changes the priority of the specified thread. Like Unix, the lower the value of the priority the higher the priority. A priority of 0 is the highest priority in the system. CYG_THREAD_MIN_PRIORITY is the lowest priority and it's value is dependent on the scheduler that you use.
Include: #include <cyg/kernel/kapi.h>
Returns: nothing
See Also: cyg_thread_create, cyg_thread_get_priority, cyg_thread_get_current_priority

cyg_thread_get_priority
Name: cyg_thread_get_priority ( ) - get the priority of a thread
Synopsis:
cyg_priority_t cyg_thread_get_priority
(
  cyg_handle_t thread /* thread ID */
)
Description: This returns the set priority of the given thread. If the priority of the thread has been modified by a mutex with a ceiling, priority inversion or some other similar mechanism this will not return the current priority, but the "normal" priority of the thread.
Include: #include <cyg/kernel/kapi.h>
Returns: the set priority of the given thread
See Also: cyg_thread_create, cyg_thread_set_priority, cyg_thread_get_current_priority

cyg_thread_get_current_priority
Name: cyg_thread_get_current_priority ( ) - get current priority of a thread
Synopsis:
cyg_priority_t cyg_thread_get_current_priority
(
  cyg_handle_t thread /* thread ID */
)
Description: This returns the current priority of the given thread. If the priority of the thread has been modified by a mutex with a ceiling, priority inversion or some other similar mechanism this will return the current priority, not the "normal" priority of the thread.
Include: #include <cyg/kernel/kapi.h>
Returns: the current running priority of the given thread.
See Also: cyg_thread_create, cyg_thread_set_priority, cyg_thread_get_priority

cyg_thread_delay
Name: cyg_thread_delay ( ) - delay the calling thread for a number of ticks
Synopsis:
void cyg_thread_delay
(
  cyg_tick_count_t delay /* number of ticks to delay */
)
Description: This delays a thread for an arbitrary number of ticks. The length of a tick is provided by the resolution of the system clock. ( RBW: provide more information on getting information on the real time clock )
Include: #include <cyg/kernel/kapi.h>
Returns: nothing
See Also: cyg_thread_release

cyg_thread_get_stack_base
Name: cyg_thread_get_stack_base ( ) - get a thread's stack base address
Synopsis:
cyg_addrword_t cyg_thread_get_stack_base
(
  cyg_handle_t thread /* thread ID */
)
Description: This returns the address of a given thread's stack. This may or may not be what was passed in the creation of the thread since debug capabilities and alignment requirements might modify it somewhat.
Include: #include <cyg/kernel/kapi.h>
Returns: the base address of the thread's stack.
See Also: cyg_thread_create, cyg_thread_get_stack_size, cyg_thread_measure_stack_usage

cyg_thread_get_stack_size
Name: cyg_thread_get_stack_size ( ) - get a thread's stack size
Synopsis:
cyg_uint32 cyg_thread_get_stack_size
(
  cyg_handle_t thread /* thread ID */
)
Description: This returns the size of a given thread's stack. This may or may not be what was passed in the creation of the thread since debug capabilities and alignment requirements might modify it somewhat.
Include: #include <cyg/kernel/kapi.h>
Returns: the size in bytes of the thread's stack.
See Also: cyg_thread_create, cyg_thread_get_stack_base, cyg_thread_measure_stack_usage

cyg_thread_measure_stack_usage
Name: cyg_thread_measure_stack_usage ( ) - get a thread's current stack usage
Synopsis:
cyg_uint32 cyg_thread_measure_stack_usage
(
  cyg_handle_t thread /* thread ID */
)
Description: This gets the number of bytes that have been used so far by the given thread. Note that if this function returns 0, it's likely you will overrun the stack in the future. This is essentially a debug function.
Include: #include <cyg/kernel/kapi.h>
Returns: the number of bytes currently used by the given thread.
See Also: cyg_thread_create, cyg_thread_get_stack_base, cyg_thread_get_stack_size

cyg_thread_new_data_index
Name: cyg_thread_new_data_index ( ) - get a free data index for all threads
Synopsis:
cyg_ucount32 cyg_thread_new_data_index
(
  void
)
Description: This gets a new unused data index. The index allocated is useful for storing data that is specific to each thread. For example, the global variable "errno" may be allocated as a per thread data variable.
Include: #include <cyg/kernel/kapi.h>
Returns: a free data index or -1 if there were no more free indexes.
See Also: cyg_thread_free_data_index, cyg_thread_get_data, cyg_thread_get_data_ptr, cyg_thread_set_data

cyg_thread_free_data_index
Name: cyg_thread_free_data_index ( ) - free a data index for all threads
Synopsis:
void cyg_thread_free_data_index
(
  cyg_ucount32 index /* index to free */
)
Description: This frees a data index and makes it available for use again by the system.
Include: #include <cyg/kernel/kapi.h>
Returns: nothing
See Also: cyg_thread_new_data_index, cyg_thread_get_data, cyg_thread_get_data_ptr, cyg_thread_set_data

cyg_thread_get_data
Name: cyg_thread_get_data ( ) - read per thread data from a given index
Synopsis:
CYG_ADDRWORD cyg_thread_get_data
(
  cyg_ucount32 index /* index of per thread data */
)
Description: Get per thread data. Be careful with this, giving a bad index will cause an ASSERT if you have it turned on, but no other error checking is performed otherwise.
Include: #include <cyg/kernel/kapi.h>
Returns: the per thread data stored at a specified index.
See Also: cyg_thread_new_data_index, cyg_thread_free_data_index, cyg_thread_get_data_ptr, cyg_thread_set_data

cyg_thread_get_data_ptr
Name: cyg_thread_get_data_ptr ( ) - get a data pointer to per thread data
Synopsis:
CYG_ADDRWORD *cyg_thread_get_data_ptr
(
  cyg_ucount32 index /* index of per thread data */
)
Description: Get a pointer to per thread data. You can use this function in lieu of cyg_thread_get_data or cyg_thread_set_data, and it's a little faster to use. The pointer, of course, is only valid in the context of the calling thread.
Include: #include <cyg/kernel/kapi.h>
Returns: a pointer to per thread data at the given index.
See Also: cyg_thread_new_data_index, cyg_thread_free_data_index, cyg_thread_get_data, cyg_thread_set_data

cyg_thread_set_data
Name: cyg_thread_set_data ( ) - set per thread data at a given index
Synopsis:
void cyg_thread_set_data
(
  cyg_ucount32 index, /* index of per thread data */
  CYG_ADDRWORD data   /* data to write            */
)
Description: Set per thread data. Be careful with this, giving a bad index will cause an ASSERT if you have it turned on, but no other error checking is performed otherwise.
Include: #include <cyg/kernel/kapi.h>
Returns: nothing
See Also: cyg_thread_new_data_index, cyg_thread_free_data_index, cyg_thread_get_data, cyg_thread_get_data_ptr

cyg_thread_add_destructor
Name: cyg_thread_add_destructor ( ) - add a destructor
Synopsis:
cyg_bool_t cyg_thread_add_destructor
(
  cyg_thread_destructor_fn fn,  /* destructor function    */
  cyg_addrword_t           data /* argument to destructor */
)
Description: This causes a destructor to be added to the calling thread. Destructors are called before the thread exits or is killed.
Include: #include <cyg/kernel/kapi.h>
Returns: "true" if the thread was added successfully, "false" otherwise.
See Also: cyg_thread_exit, cyg_thread_delete, cyg_thread_kill, cyg_thread_rem_destructor

cyg_thread_rem_destructor
Name: cyg_thread_rem_destructor ( ) - remove (disable) a destructor
Synopsis:
cyg_bool_t cyg_thread_rem_destructor
(
  cyg_thread_destructor_fn fn,  /* destructor function    */
  cyg_addrword_t           data /* argument to destructor */
)
Description: This causes a destructor to be removed from the calling thread. Destructors are called before the thread exits or is killed. In order to successfully remove a destructor, both the "fn" and "data" argument must match exactly a previously installed destructor.
Include: #include <cyg/kernel/kapi.h>
Returns: "true" if a destructor was removed successfully, "false" otherwise.
See Also: cyg_thread_exit, cyg_thread_delete, cyg_thread_kill, cyg_thread_add_destructor, cyg_thread_rem_destructor