eCosTM Reference Manual
Prev | Chapter 5. Native kernel C language API | Next

# Thread operations

`void cyg_scheduler_start`(void);

Starts the scheduler with the threads that have been created. It never returns. The scheduler has been chosen at configuration time. eCos currently ships with three schedulers: a bitmap scheduler, a multi-level scheduler (selected by default), and an experimental “lottery” scheduler which should not be used.

The configuration tool can be used to select between schedulers. The configuration options (described in the section called Component: Kernel schedulers in Chapter 17) are `CYGSEM_SCHED_BITMAP`, `CYGSEM_SCHED_MLQUEUE` and `CYGSEM_SCHED_LOTTERY`.

> Note: Interrupts are not enabled until the scheduler has been started with `cyg_scheduler_start()`.

`void cyg_scheduler_lock`(void);

Locks the scheduler so that a context switch cannot occur. This can be used to protect data shared between a thread and a DSR, or between multiple threads, by surrounding the critical region with `cyg_scheduler_lock()` and `cyg_scheduler_unlock()`.

`void cyg_scheduler_unlock`(void);

Unlocks the scheduler so that context switching can occur again.

`void cyg_thread_create`(cyg_addrword_t sched_info, cyg_thread_entry_t *entry, cyg_addrword_t entry_data, char *name, void *stack_base, cyg_ucount32 stack_size, cyg_handle_t *handle, cyg_thread *thread);

Creates a thread in a suspended state. The thread will not run until it has been resumed with `cyg_thread_resume()` and the scheduler has been started with `cyg_scheduler_start()`.

Here is a description of the parameters of `cyg_thread_create()`:

`sched_info`

  Information to be passed to the scheduler. For almost all schedulers this is a simple priority value, and you can simply pass a non-negative integer when you create the thread.

`entry`

  A user-supplied function: it is a routine that begins execution of the new thread. This function takes a single argument of type cyg_addrword_t, which is usually a pointer to a block of data, which allows `cyg_scheduler_start()` to pass data to this particular thread.

  Here is a typedef for the `entry` function:

      typedef void cyg_thread_entry_t(cyg_addrword_t);

`entry_data`

  A data value passed to the `entry` function. This may be either a machine word datum or the address of a block of data.

`name`

  A C string with the name of this thread.

`stack_base`

  The address of the stack base. If this value is `NULL` then `cyg_thread_create()` will choose a stack base.

  > Note: Passing a stack base of `NULL` is not supported in this release. You must pass a real address for the stack base.

`stack_size`

  The size of the stack for this thread. If this is 0, the default stack size will be used for this thread.

  > Note: Passing a stack size of 0 is not supported in this release. You must pass a real stack size.

`handle`

  `cyg_thread_create()` returns the thread handle in this location.

`thread`

  The thread housekeeping information is placed in the memory pointed to by this parameter. If this pointer is `NULL` then the memory will be allocated.

  > Note: Passing a NULL value for the thread data structure address is not supported in this release. You must pass a valid address.

`void cyg_thread_exit`(void);

Exits the current thread. At present this simply puts the thread into suspended state.

`void cyg_thread_suspend`(cyg_handle_t thread);

Suspends the `thread`. A thread may be suspended multiple times, in which case it will need to be resumed the same number of times before it will run.

`void cyg_thread_resume`(cyg_handle_t thread);

Resumes `thread`. If a thread has been suspended multiple times it will need to be resumed the same number of times before it will run. Threads are created in a suspended state and must be resumed before they will run.

`void cyg_thread_yield`(void);

Yields control to the next runnable thread of equal priority. If no such thread exists, then this function has no effect.

`void cyg_thread_kill`(cyg_handle_t thread);

Kills `thread`.

`cyg_handle_t cyg_thread_self`(void);

Returns the handle of the current thread.

`void cyg_thread_release`(cyg_handle_t thread);

Break the thread out of any wait it is currently in. Exactly how the thread returns from the wait operation, and how, if at all, the break is indicated, depends on the synchronization object it was waiting on.

`cyg_ucount32 cyg_thread_new_data_index`(void);

Allocates a new per-thread data index from those still available. If no more indexes are available, and assertions are enabled, an assertion will be raised.

`void cyg_thread_free_data_index`(cyg_ucount32 index);

Return the per-thread data index to the pool.

`CYG_ADDRWORD cyg_thread_get_data`(cyg_ucount32 index);

Retrieve the per-thread data at the given index for the current thread.

`CYG_ADDRWORD *cyg_thread_get_data_ptr`(cyg_ucount32 index);

Return a pointer to the per-thread data at the given index for the current thread. This should be used with some care since in some future implementation the per-thread data may be managed by a dynamic mechanism that might invalidate this pointer at any time. This pointer should only be considered valid until the next call to the per-thread data functions.

`void cyg_thread_set_data`(cyg_ucount32 index, CYG_ADDRWORD data ));

Store the data in the per-thread data for the current thread at the given index.

Prev | Home | Next
Native kernel C language API | Up | Priority manipulation