source: rtems-central/spec/rtems/task/if/construct.yml @ 3bdf817

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
  Creates a task from the specified the task configuration.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
definition:
  default:
    body: null
    params:
    - const ${config:/name} *${.:/params[0]/name}
    - ${../../type/if/id:/name} *${.:/params[1]/name}
    return: ${../../status/if/code:/name}
  variants: []
description: null
enabled-by: true
interface-type: function
links:
- role: interface-placement
  uid: header
- role: interface-ingroup
  uid: group
name: rtems_task_construct
notes: |
  In contrast to tasks created by ${create:/name}, the tasks constructed by
  this directive use a user-provided task storage area.  The task storage area
  contains the task stack, the thread-local storage, and the floating-point
  context on architectures with a separate floating-point context.

  It is not recommended to mix ${create:/name} and ${.:/name} in an
  application.  This directive is intended for applications which do not want
  to use the RTEMS Workspace and instead statically allocate all operating
  system resources.  The stack space estimate done by <rtems/confdefs.h>
  assumes that all tasks are created by ${create:/name}.  The estimate can be
  adjusted to take user-provided task storage areas into account through the
  ${/acfg/if/min-tasks-with-user-provided-storage:/name} application
  configuration option.
params:
- description: is the task configuration.
  dir: null
  name: config
- description: |
    is the pointer to an object identifier variable.  The identifier of the
    constructed task object will be stored in this variable, in case of a
    successful operation.
  dir: out
  name: id
return:
  return: null
  return-values:
  - description: |
      The requested operation was successful.
    value: ${../../status/if/successful:/name}
  - description: |
      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
    value: ${../../status/if/invalid-address:/name}
  - description: |
      The task name was invalid.
    value: ${../../status/if/invalid-name:/name}
  - description: |
      The initial task priority was invalid.
    value: ${../../status/if/invalid-priority:/name}
  - description: |
      The thread-local storage size is greater than the maximum thread-local
      storage size specified in the task configuration.  The thread-local
      storage size is determined by the thread-local variables used by the
      application and ${/acfg/if/max-thread-local-storage-size:/name}.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      The task storage area was too small to provide a task stack of the
      configured minimum size, see ${/acfg/if/min-task-stack-size:/name}.
      The task storage area contains the task stack, the thread-local storage,
      and the floating-point context on architectures with a separate
      floating-point context.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      There was no inactive task object available to construct a task.
    value: ${../../status/if/too-many:/name}
  - description: |
      In multiprocessing configurations, there was no inactive global object
      available to construct a global task.
    value: ${../../status/if/too-many:/name}
  - description: |
      One of the task create extensions failed during the task construction.
    value: ${../../status/if/unsatisfied:/name}
  - description: |
      In SMP configurations, the non-preemption mode was not supported.
    value: ${../../status/if/unsatisfied:/name}
  - description: |
      In SMP configurations, the interrupt level mode was not supported.
    value: ${../../status/if/unsatisfied:/name}
type: interface