SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
  Creates a semaphore with the specified properties and returns its identifier.
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}
    - ${../../task/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 new
  semaphore has the user-defined name specified in ``name`` and the initial
  count specified in ``count``.  For control and maintenance of the semaphore,
  RTEMS allocates and initializes a ${/glossary/smcb:/term}.  The
  RTEMS-assigned semaphore identifier is returned in ``id``.  This semaphore
  identifier is used with other semaphore related directives to access the
  semaphore.

  The attribute set specified in ``attribute_set`` defines

  * the scope of the semaphore (local or global),

  * the discipline of the task wait queue used by the semaphore (FIFO or
    priority),

  * the class of the semaphore (counting, binary, or simple binary), and

  * the locking protocol of a binary semaphore (priority inheritance, priority
    ceiling or MrsP).

  The attribute set 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.

  The *scope of a semaphore* is either the local node only (local scope) or all
  nodes in a multiprocessing network (global scope).  The scope is selected by
  the mutually exclusive ${../../attr/if/local:/name} and
  ${../../attr/if/global:/name} attributes.

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

  * The global scope is selected by the ${../../attr/if/global:/name} attribute.  In
    a single node system and the local and global scope are identical.

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

  * The ${/glossary/fifo:/term} 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.  Some 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.

  * Counting semaphores are the default and can be emphasized through use of
    the ${../../attr/if/counting-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.  The binary semaphore class is selected by the
    ${../../attr/if/binary-semaphore:/name} attribute.

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

  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 to use no locking protocol.

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

  * The ${../../attr/if/priority-ceiling:/name} attribute selects the priority
    ceiling locking protocol.  For this locking protocol a priority ceiling
    shall be specified in ``priority_ceiling``.

  * The ${../../attr/if/multiprocessor-resource-sharing:/name} attribute selects the
    MrsP locking protocol in SMP configurations, otherwise it selects the
    priority ceiling protocol.  For this locking protocol a priority ceiling
    shall be specified in ``priority_ceiling``.  This priority is used to set
    the priority ceiling in all scheduler instances.  This can be changed later
    with the ${set-priority:/name} directive using the returned semaphore
    identifier.
enabled-by: true
index-entries: []
interface-type: function
links:
- role: interface-placement
  uid: header
- role: interface-ingroup
  uid: group
name: rtems_semaphore_create
notes: |
  This directive may cause the calling task to be preempted due to an obtain
  and release of the object allocator mutex.

  Semaphores should not be made global unless remote tasks must interact with
  the new 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.

  The total number of global objects, including semaphores, is limited by the
  ${/acfg/if/mp-max-global-objects:/name} application configuration option.

  It is not allowed to create an initially locked MrsP semaphore and the
  ${../../status/if/invalid-number:/name} status code will be returned in SMP
  configurations in this case.  This prevents lock order reversal problems
  with the allocator mutex.
params:
- description: is the object name of the new semaphore.
  dir: null
  name: name
- description: |
    is the initial count of the new semaphore.  If the semaphore is a mutex,
    then a count of 0 will make the calling task the owner of the new mutex and
    a count of 1 will create a mutex without an owner.
  dir: null
  name: count
- description: |
    is the attribute set which defines the properties of the new semaphore.
  dir: null
  name: attribute_set
- description: |
    is the priority ceiling if the new semaphore is a binary semaphore with the
    priority ceiling or MrsP semaphore locking protocol as defined by the
    attribute set.
  dir: null
  name: priority_ceiling
- description: |
    is the pointer to an object identifier variable.  The object identifier of
    the new semaphore 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[3]/name} parameter was ${/c/if/null:/name}.
    value: ${../../status/if/invalid-address:/name}
  - description: |
      The semaphore name was invalid.
    value: ${../../status/if/invalid-name:/name}
  - description: |
      The priority ceiling was invalid.
    value: ${../../status/if/invalid-priority:/name}
  - description: |
      The attribute set was invalid.
    value: ${../../status/if/not-defined:/name}
  - description: |
      There was no inactive semaphore object available to create a new
      semaphore.  The semaphore object maximum is defined by 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 new global semaphore.
    value: ${../../status/if/too-many:/name}
type: interface