SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
  Creates a semaphore.
copyrights:
- Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
- Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
definition:
  default:
    attributes: null
    body: null
    params:
    - ${../../type/if/name:/name} ${.:/params[0]/name}
    - ${/c/if/uint32_t:/name} ${.:/params[1]/name}
    - ${../../attr/if/attribute:/name} ${.:/params[2]/name}
    - ${../../type/if/priority:/name} ${.:/params[3]/name}
    - ${../../type/if/id:/name} *${.:/params[4]/name}
    return: ${../../status/if/code:/name}
  variants: []
description: |
  This directive creates a semaphore which resides on the local node.  The
  semaphore has the user-defined object name specified in ${.:/params[0]/name}
  and the initial count specified in ${.:/params[1]/name}.  The assigned object
  identifier is returned in ${.:/params[4]/name}.  This identifier is used to
  access the semaphore with other semaphore related directives.

  The **attribute set** specified in ${.:/params[2]/name} is built through a
  *bitwise or* of the attribute constants described below.  Not all
  combinations of attributes are allowed.  Some attributes are mutually
  exclusive.  If mutually exclusive attributes are combined, the behaviour is
  undefined.  Attributes not mentioned below are not evaluated by this
  directive and have no effect.  Default attributes can be selected by using
  the ${../../attr/if/default:/name} constant.  The attribute set defines

  * the scope of the semaphore: ${../../attr/if/local:/name} (default) or
    ${../../attr/if/global:/name},

  * the task wait queue discipline used by the semaphore:
    ${../../attr/if/fifo:/name} (default) or ${../../attr/if/priority:/name},

  * the class of the semaphore: ${../../attr/if/counting-semaphore:/name}
    (default), ${../../attr/if/binary-semaphore:/name}, or
    ${../../attr/if/simple-binary-semaphore:/name}, and

  * the locking protocol of a binary semaphore: no locking protocol (default),
    ${../../attr/if/inherit-priority:/name},
    ${../../attr/if/priority-ceiling:/name}, or
    ${../../attr/if/multiprocessor-resource-sharing:/name}.

  The semaphore has a local or global **scope** in a multiprocessing network
  (this attribute does not refer to SMP systems).  The scope is selected by the
  mutually exclusive ${../../attr/if/local:/name} and
  ${../../attr/if/global:/name} attributes.

  * A **local scope** is the default and can be emphasized through the use of
    the ${../../attr/if/local:/name} attribute.  A local semaphore can be only
    used by the node which created it.

  * A **global scope** is established if the ${../../attr/if/global:/name}
    attribute is set.  Setting the global attribute in a single node system has
    no effect.

  The **task wait queue discipline** is selected by the mutually exclusive
  ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.

  * The **FIFO discipline** is the default and can be emphasized
    through use of the ${../../attr/if/fifo:/name} attribute.

  * The **priority discipline** is selected by the
    ${../../attr/if/priority:/name} attribute.  The locking protocols require
    the priority discipline.

  The **semaphore class** is selected by the mutually exclusive
  ${../../attr/if/counting-semaphore:/name},
  ${../../attr/if/binary-semaphore:/name}, and
  ${../../attr/if/simple-binary-semaphore:/name} attributes.

  * The **counting semaphore class** is the default and can be emphasized
    through use of the ${../../attr/if/counting-semaphore:/name} attribute.

  * The **binary semaphore class** is selected by the
    ${../../attr/if/binary-semaphore:/name} attribute.  Binary semaphores are
    mutual exclusion (mutex) synchronization primitives which may have an
    owner.  The count of a binary semaphore is restricted to 0 and 1 values.

  * The **simple binary semaphore class** is selected by the
    ${../../attr/if/simple-binary-semaphore:/name} attribute.  Simple binary
    semaphores have no owner.  They may be used for task and interrupt
    synchronization.  The count of a simple binary semaphore is restricted to 0
    and 1 values.

  Binary semaphores may use a **locking protocol**.  If a locking protocol is
  selected, then the scope shall be local and the priority task wait queue
  discipline shall be selected.  The locking protocol is selected by the
  mutually exclusive ${../../attr/if/inherit-priority:/name},
  ${../../attr/if/priority-ceiling:/name}, and
  ${../../attr/if/multiprocessor-resource-sharing:/name} attributes.

  * The default is **no locking protocol**.  This can be emphasized
    through use of the ${../../attr/if/no-inherit-priority:/name},
    ${../../attr/if/no-multiprocessor-resource-sharing:/name}, and
    ${../../attr/if/no-priority-ceiling:/name} attributes.

  * The **priority inheritance locking protocol** is selected by the
    ${../../attr/if/inherit-priority:/name} attribute.

  * The **priority ceiling locking protocol** is selected by the
    ${../../attr/if/priority-ceiling:/name} attribute.  For this locking protocol
    a priority ceiling shall be specified in ${.:/params[3]/name}.

  * The **MrsP locking protocol** is selected by the
    ${../../attr/if/multiprocessor-resource-sharing:/name} attribute in SMP
    configurations, otherwise this attribute selects the **priority ceiling
    locking protocol**.  For these locking protocols a priority ceiling shall be
    specified in ${.:/params[3]/name}.  This priority is used to set the
    priority ceiling for all schedulers.  This can be changed later with the
    ${set-priority:/name} directive using the returned object identifier.
enabled-by: true
index-entries:
- create a semaphore
interface-type: function
links:
- role: interface-placement
  uid: header
- role: interface-ingroup
  uid: group
- role: constraint
  uid: /constraint/directive-ctx-devinit
- role: constraint
  uid: /constraint/directive-ctx-task
- role: constraint
  uid: /constraint/object-allocator
- role: constraint
  uid: /constraint/mp-send
- role: constraint
  uid: ../constraint/max
- role: constraint
  uid: /constraint/obj-unlimited-alloc
- role: constraint
  uid: ../../constraint/mp-max-global-objects
name: rtems_semaphore_create
notes: |
  For control and maintenance of the semaphore, RTEMS allocates a
  ${/glossary/smcb:/term} from the local SMCB free pool and initializes it.

  The SMCB for a global semaphore is allocated on the local node.  Semaphores
  should not be made global unless remote tasks must interact with the
  semaphore.  This is to avoid the system overhead incurred by the creation of
  a global semaphore.  When a global semaphore is created, the semaphore's name
  and identifier must be transmitted to every node in the system for insertion
  in the local copy of the global object table.
params:
- description: |
    is the object name of the semaphore.
  dir: null
  name: name
- description: |
    is the initial count of the semaphore.  If the semaphore is a binary semaphore,
    then a count of 0 will make the calling task the owner of the binary semaphore and
    a count of 1 will create a binary semaphore without an owner.
  dir: null
  name: count
- description: |
    is the attribute set of the semaphore.
  dir: null
  name: attribute_set
- description: |
    is the priority ceiling if the semaphore is a binary semaphore with the
    priority ceiling or MrsP locking protocol as defined by the attribute set.
  dir: null
  name: priority_ceiling
- description: |
    is the pointer to an object identifier variable.  When the directive call
    is successful, the identifier of the created semaphore will be stored in
    this variable.
  dir: out
  name: id
return:
  return: null
  return-values:
  - description: |
      The requested operation was successful.
    value: ${../../status/if/successful:/name}
  - description: |
      The ${.:/params[0]/name} parameter was invalid.
    value: ${../../status/if/invalid-name:/name}
  - description: |
      The ${.:/params[4]/name} parameter was ${/c/if/null:/name}.
    value: ${../../status/if/invalid-address:/name}
  - description: |
      The ${.:/params[1]/name} parameter was invalid.
    value: ${../../status/if/invalid-number:/name}
  - description: |
      The ${.:/params[2]/name} parameter was invalid.
    value: ${../../status/if/not-defined:/name}
  - description: |
      There was no inactive object available to create a semaphore.  The number
      of semaphores available to the application is configured through the
      ${/acfg/if/max-semaphores:/name} application configuration option.
    value: ${../../status/if/too-many:/name}
  - description: |
      In multiprocessing configurations, there was no inactive global object
      available to create a global semaphore.  The number of global objects
      available to the application is configured through the
      ${/acfg/if/mp-max-global-objects:/name} application configuration option.
    value: ${../../status/if/too-many:/name}
  - description: |
      The ${.:/params[3]/name} parameter was invalid.
    value: ${../../status/if/invalid-priority:/name}
type: interface