# ====================================================================
#
#      scheduler.cdl
#
#      configuration data related to the kernel schedulers
#
# ====================================================================
#####COPYRIGHTBEGIN####
#                                                                          
# -------------------------------------------                              
# The contents of this file are subject to the Red Hat eCos Public License 
# Version 1.1 (the "License"); you may not use this file except in         
# compliance with the License.  You may obtain a copy of the License at    
# http://www.redhat.com/                                                   
#                                                                          
# Software distributed under the License is distributed on an "AS IS"      
# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See the 
# License for the specific language governing rights and limitations under 
# the License.                                                             
#                                                                          
# The Original Code is eCos - Embedded Configurable Operating System,      
# released September 30, 1998.                                             
#                                                                          
# The Initial Developer of the Original Code is Red Hat.                   
# Portions created by Red Hat are                                          
# Copyright (C) 1998, 1999, 2000 Red Hat, Inc.                             
# All Rights Reserved.                                                     
# -------------------------------------------                              
#                                                                          
#####COPYRIGHTEND####
# ====================================================================
######DESCRIPTIONBEGIN####
#
# Author(s):      jskov
# Original data:  nickg
# Contributors:
# Date:           1999-07-05
#
#####DESCRIPTIONEND####
#
# ====================================================================

cdl_interface CYGINT_KERNEL_SCHEDULER {
    display  "Number of schedulers in this configuration"
    no_define
    requires 1 == CYGINT_KERNEL_SCHEDULER
}

cdl_interface CYGINT_KERNEL_SCHEDULER_UNIQUE_PRIORITIES {
    display  "Non-zero if the active schedule only has unique priorities"
    description "
        Not all schedulers allow mutiple threads to use the same
        priority. That property is signalled via this option, allowing
        scheduler and tests to behave accordingly."
}

# FIXME: The two below options must be mutually exclusive
cdl_option CYGSEM_KERNEL_SCHED_MLQUEUE {
    display       "Multi-level queue scheduler"
    default_value 1
    implements    CYGINT_KERNEL_SCHEDULER
    description   "
        The multi-level queue scheduler supports multiple priority
        levels and multiple threads at each priority level.
        Preemption between priority levels is automatic. Timeslicing
        within a given priority level is controlled by a separate
        configuration option."
}

cdl_option CYGSEM_KERNEL_SCHED_BITMAP {
    display       "Bitmap scheduler"
    default_value 0
    implements    CYGINT_KERNEL_SCHEDULER
    implements    CYGINT_KERNEL_SCHEDULER_UNIQUE_PRIORITIES
    description   "
        The bitmap scheduler supports multiple priority levels but
        only one thread can exist at each priority level. This means
        that scheduling decisions are very simple and hence the
        scheduler is efficient. Preemption between priority levels is
        automatic. Timeslicing within a given priority level is
        irrelevant since there can be only one thread at each
        priority level."
}

#cdl_option CYGSEM_KERNEL_SCHED_LOTTERY {
#    display      "Lottery scheduler"
#    type          radio
#    description "
#       This scheduler is not yet available."
#}

cdl_option CYGPRI_KERNEL_SCHED_IMPL_HXX {
    display       "Scheduler header file"
    flavor        data
    description   "
	This option sets a preprocessor symbol which names the header
	file for the selected scheduler.  It is used internally by the
	common scheduler code to include the correct header file."
    calculated { \
               CYGSEM_KERNEL_SCHED_BITMAP  ? "<cyg/kernel/bitmap.hxx>"  :\
               CYGSEM_KERNEL_SCHED_MLQUEUE ? "<cyg/kernel/mlqueue.hxx>" :\
               CYGSEM_KERNEL_SCHED_LOTTERY ? "<cyg/kernel/lottery.hxx>" :\
               "!!!-- Configuration broken - no scheduler selected --!!!"}
}



# NOTE: This option only makes sense if the current scheduler
#       supports multiple priority levels.
cdl_component CYGNUM_KERNEL_SCHED_PRIORITIES {
    display       "Number of priority levels"
    flavor        data
    legal_values  1 to 32
    default_value 32
    #active_if     CYGINT_KERNEL_SCHED_PRIORITY_SCHEDULER
    description "
        This option controls the number of priority levels that are
        available. For some types of scheduler including the bitmap
        scheduler this may impose an upper bound on the number of
        threads in the system. For other schedulers such as the
        mlqueue scheduler the number of threads is independent from
        the number of priority levels. Note that the lowest priority
        level is normally used only by the idle thread, although
        application threads can run at this priority if necessary."

    cdl_option CYGNUM_KERNEL_SCHED_BITMAP_SIZE {
        display       "Bitmap size"
        flavor        data
        calculated    {"CYGNUM_KERNEL_SCHED_PRIORITIES"}
	description   "
		This option automatically defines the size of bitmap
		used to track occupied priority levels."
    }

        
    cdl_option CYGIMP_KERNEL_SCHED_SORTED_QUEUES {
        display       "Dequeue oldest threads first"
        flavor        bool
        default_value 0
        description   "
            With this option enabled, threads queued in a thread queue
            will be dequeued in priority order, rather than last in,
            first out (LIFO). Threads of equal priority are dequeued
            oldest first. The only exception is the scheduler run 
            queues where order is less important as each is already
            sorted by priority. Note that this makes the thread queueing
            less deterministic."
    }
}

# ---------------------------------------------------------------------
# Timeslice options

# NOTE: this option only makes sense for some of the schedulers.
# Timeslicing is irrelevant for bitmap schedulers.
cdl_component CYGSEM_KERNEL_SCHED_TIMESLICE {
    display       "Scheduler timeslicing"
    requires      !CYGSEM_KERNEL_SCHED_BITMAP
    requires      CYGVAR_KERNEL_COUNTERS_CLOCK
    default_value 1
    description "
        Some schedulers including the mlqueue scheduler support
        timeslicing. This means that the kernel will check regularly
        whether or not there is another runnable thread with the
        same priority, and if there is such a thread there will be
        an automatic context switch. Not all applications require
        timeslicing, for example because every thread performs a
        blocking operation regularly. For these applications it is
        possible to disable timeslicing, which reduces the overheads
        associated with timer interrupts."

    cdl_option CYGNUM_KERNEL_SCHED_TIMESLICE_TICKS {
        display       "Number of clock ticks between timeslices"
        flavor        data
        legal_values  1 to 65535
        default_value 5
        description "
            Assuming timeslicing is enabled, how frequently should it
            take place? The value of this option corresponds to the
            number of clock ticks that should occur before a timeslice
            takes place, so increasing the value reduces the frequency
            of timeslices."
    }

    cdl_option CYGSEM_KERNEL_SCHED_TIMESLICE_ENABLE {
        display       "Support runtime enable of timeslice per-thread"
        flavor        bool
        default_value false
        description "This option makes timslicing a per-thread runtime
                     option. When enabled, threads may have timeslicing
		     turned on or off dynamically. This is generally used
                     by higher level APIs (such as POSIX) to implement
		     differing scheduling policies."

    }
}

# ---------------------------------------------------------------------
# ASR support options

cdl_component CYGSEM_KERNEL_SCHED_ASR_SUPPORT {
    display       "Enable ASR support"
    flavor        bool
    default_value false
    description   "
         This component controls support for Asynchronous Service
         Routines (ASRs). This is a function that may be called
         from the scheduler when it has just exited the scheduler
         lock. This is primarily for use by API compatibility layers."

    cdl_option CYGSEM_KERNEL_SCHED_ASR_GLOBAL {
	display       "Make ASR function global"
	flavor        bool
	default_value true
	description "
	     This option controls whether the ASR function is shared by
	     all threads, or whether each thread may have its own ASR
	     function."
    }

    cdl_option CYGSEM_KERNEL_SCHED_ASR_DATA_GLOBAL {
	display       "Make ASR data global"
	flavor        bool
	default_value true
	description "
	     This option controls whether the ASR data is shared by
	     all threads, or whether each thread may have its own ASR
	     data. This is independent of the previous option because
	     it may be useful to pass per-thread data to a shared ASR
	     function."
    }
}