[[PageOutline]]
= Specifying plan classes in XML =

You can specify plan classes using an XML configuration file with the format
{{{
<plan_classes>
   <plan_class>
      ... specification of a plan class
   </plan_class>
   ... more plan class specifications
</plan_classes>
}}}

Name this file '''plan_class_spec.xml''' and put it in your project directory.
This will '''replace''' the built in plan classes!

== Examples ==

An example configuration file is [http://boinc.berkeley.edu/gitweb/?p=boinc-v2.git;a=blob;f=sched/plan_class_spec.xml.sample here].
This file specifies the [AppPlan predefined plan classes].

== Specification format ==

The specification of a plan class has the following format.
All elements except '''<name>''' are optional.
In version numbers, M is major, m is minor, R is release.

 <name>X</name> :: the name of the plan class
 <max_core_client_version>MMmmrr</max_core_client_version>:: send only to BOINC clients of less than or equal version number.
 <min_core_client_version>MMmmrr</min_core_client_version>:: send only to BOINC clients of greater than or equal version number.
 <projected_flops_scale>x</projected_flops_scale>:: multiply projected FLOPS by this factor.
   Use this to favor one class over another.
   For example, if you have both SSE and non-SSE versions, use 1.1 and 1.0 respectively.
 <os_regex>regex</os_regex>:: send only to hosts whose operating system version matches the given regular expression
 <min_os_version>x</min_os_version>:: send only to hosts with at least this numerical OS version.
   Numerical OS version derived from the host's os_version string as follows:.
   * Mac OS X: Version 10.x is reported as (x+4).y.z.  For example, 10.7.0 is reported as "11.00.00"; the numerical version is 110000.
   * Windows: Windows 7 SP1 is reported as "(Microsoft Windows 7 ..., Service Pack 1, (06.01.7601.00))";
    the numerical version is 601760100.
    More information is [http://en.wikipedia.org/wiki/Comparison_of_Microsoft_Windows_versions here].
   * Linux and Android: the kernel version is reported as "2.6.3"; the numerical version is 20603.
 <max_os_version>x</max_os_version>:: max numerical OS version (see above)
 <cpu_feature>x</cpu_feature>:: a required CPU feature (such as sse3). You can include more than one.
 <host_summary_regex>regex</host_summary_regex>:: send only to hosts with host.serialnum field that matches the given regular expression.
 <cpu_vendor_regex>regex</cpu_vendor_regex>:: send only to hosts whose CPU vendor matches the regular expression.
  Example CPU vendors are "!GenuineIntel" and "AuthenticAMD",
  so to match Intel CPUs you could use
{{{
<cpu_vendor_regext>.*Intel</cpu_vendor_regexp>
}}}

The following elements let you use a project preference to decide whether to use the app version:
 <project_prefs_tag>x</project_prefs_tag>:: the name of the tag
 <project_prefs_regex>x</project_prefs_regex>:: the contents must match this regular expression
 <project_prefs_default_true/>:: treat the absence of the project_prefs_tag (i.e. the user didn't set it yet) as if the project_prefs_regex matched.


=== Fields for multicore apps ===

 <min_ncpus>N</min_ncpus> :: run only on hosts with at least N usable CPUs.
 <max_threads>N</max_threads>:: If N > 1, this is a multicore app.  Use as many CPUs as are available, but no more than N.
 <nthreads_cmdline>0|1</nthreads_cmdline>:: if set, pass command-line args '''--nthreads N'''
  to the app, where N is the number of CPUs to use
  (the lesser of max_threads and the number of CPUs on the host).
 <mem_usage_base>X</mem_usage_base>::
 <mem_usage_per_cpu>Y</mem_usage_per_cpu>:: if specified, estimated memory usage is X + NY, where N is the number of CPUs used.
   

=== Fields for GPU apps ===

Required:
 <gpu_type>X</gpu_type>:: the GPU type (generally '''nvidia''', '''amd''', or '''intel''')

Optional:
 <cpu_frac>x</cpu_frac>:: the fraction of total FLOPs that are done by the CPU.
   This is used to calculate CPU usage and estimated FLOPS.
   Default 0.1.
 <min_gpu_ram_mb>x</min_gpu_ram_mb>:: The minimum amount of GPU RAM.
   This is needed because older clients report total RAM
   but not available RAM.
 <gpu_ram_used_mb>x</gpu_ram_used_mb>:: require this much available GPU RAM
 <gpu_peak_flops_scale>x</gpu_peak_flops_scale>:: scale GPU peak speed by this (default 1).
 <ngpus>x</ngpus>:: how many GPUs will be used (possibly fractional); default 1.
 <min_driver_version>x</min_driver_version>:: minimum display driver version.
  AMD driver versions are represented as MMmmRRRR.
  NVIDIA driver versions are represented as MMMmm.
 <max_driver_version>x</max_driver_version>:: maximum display driver version
 <cuda/>:: CUDA application (NVIDIA)
 <cal/>:: CAL application (AMD)
 <gpu_utilization_tag>x</gpu_utilization_tag>:: you can use a project-specific preferences to let users
   scale the # of GPUs used.
   This is the tag name.
 <without_opencl>0|1</without_opencl>:: send this version only to hosts without OpenCL capability

=== Fields for AMD/ATI GPU apps ===

 <need_ati_libs/>:: Require libraries named "ati", not "amd".
 <need_amd_libs/>:: Require libraries named "amd".
  You can verify which DLLs your application is linked against using 
  [http://www.dependencywalker.com/ Dependency Walker] against your application. 
  If your executable contains DLL names prefixed with 'ati', use this option.
  These flags are usually not needed for OpenCL apps.

 <min_cal_target>N</min_cal_target> ::
 <max_cal_target>N</max_cal_target> ::
  Min and max CAL targets:
{{{
typedef enum CALtargetEnum {
    CAL_TARGET_600,                /**< R600 GPU ISA */     
    CAL_TARGET_610,                /**< RV610 GPU ISA */    
    CAL_TARGET_630,                /**< RV630 GPU ISA */
    CAL_TARGET_670,                /**< RV670 GPU ISA */
    CAL_TARGET_7XX,                /**< R700 class GPU ISA */
    CAL_TARGET_770,                /**< RV770 GPU ISA */
    CAL_TARGET_710,                /**< RV710 GPU ISA */
    CAL_TARGET_730,                /**< RV730 GPU ISA */
    CAL_TARGET_CYPRESS,            /**< CYPRESS GPU ISA */
    CAL_TARGET_JUNIPER,            /**< JUNIPER GPU ISA */
    CAL_TARGET_REDWOOD,            /**< REDWOOD GPU ISA */
    CAL_TARGET_CEDAR,               /**< CEDAR GPU ISA */
    CAL_TARGET_RESERVED0,
    CAL_TARGET_RESERVED1,           
    CAL_TARGET_WRESTLER,            /**< WRESTLER GPU ISA */
    CAL_TARGET_CAYMAN,              /**< CAYMAN GPU ISA */
    CAL_TARGET_KAUAI,           /** added by me **/
    CAL_TARGET_BARTS,               /**< BARTS GPU ISA */
    CAL_TARGET_TURKS,          /** added by me **/
    CAL_TARGET_CAICOS   /** added by me **/
} CALtarget;
}}}

=== Fields for NVIDIA GPU apps ===

 <min_nvidia_compcap>MMmm</min_nvidia_compcap>:: minimum compute capability
 <max_nvidia_compcap>MMmm</max_nvidia_compcap>:: maximum compute capability

=== Fields for CUDA apps ===

 <min_cuda_version>MMmmm</min_cuda_version>:: minimum CUDA version
 <max_cuda_version>MMmmm</max_cuda_version>:: maximum CUDA version

=== Fields for OpenCL apps (CPU or GPU) ===

 <opencl/>:: include this for OpenCL applications
 <min_opencl_version>MMmm</min_opencl_version>:: minimum OpenCL version
 <max_opencl_version>MMmm</max_opencl_version>:: maximum OpenCL version
 <double_precision_fp>:: reject plan class if the device doesn't support double precision floating point math

=== Fields for OpenCL apps for AMD ===
 <min_opencl_driver_revision>MMmmrr</min_opencl_driver_revision>:: minimum OpenCL driver revision
 <max_opencl_driver_revision>MMmmrr</max_opencl_driver_revision>:: maximum OpenCL driver revision

=== Fields for !VirtualBox apps ===

 <virtualbox/> :: !VirtualBox application; send only to hosts with !VirtualBox installed
 <min_vbox_version>MMmmrr</min_vbox_version>:: minimum !VirtualBox version
 <max_vbox_version>MMmmrr</max_vbox_version>:: maximum !VirtualBox version
 <exclude_vbox_version>MMmmrr</exclude_vbox_version>:: exclude a particular !VirtualBox version (can have > 1 of these)
 <is64bit/> :: 64-bit application.
 <vm_accel_required/> ::  send only to hosts with enabled VM hardware acceleration.

Note: !VirtualBox apps can be multicore (set <min_ncpus> and <max_threads>).
However, when sent to hosts without enabled VM hardware acceleration,
they'll be run single-core.

=== Fields for Android apps ===
 <min_android_version>MMmmrr>:: minimum Android version (e.g. 4.1.2 = 40102)
 <max_android_version>MMmmrr>:: maximum Android version

=== Fields for non-compute-intensive apps ===
 <avg_ncpus>x</avg_ncpus>:: average # CPUs used.  Use for non-compute-intensive apps;
   for others it's calculated for you.