source: rtems-central/spec/rtems/region/if/create.yml @ 45b6997

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
  Creates a region.
copyrights:
- Copyright (C) 2021 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}
    - void *${.:/params[1]/name}
    - ${/c/if/uintptr_t:/name} ${.:/params[2]/name}
    - ${/c/if/uintptr_t:/name} ${.:/params[3]/name}
    - ${../../attr/if/attribute:/name} ${.:/params[4]/name}
    - ${../../type/if/id:/name} *${.:/params[5]/name}
    return: ${../../status/if/code:/name}
  variants: []
description: |
  This directive creates a region which resides on the local node.  The region
  has the user-defined object name specified in ${.:/params[0]/name}.  The
  assigned object identifier is returned in ${.:/params[5]/name}.  This
  identifier is used to access the region with other region related directives.

  The region manages the **contiguous memory area** which starts at
  ${.:/params[1]/name} and is ${.:/params[2]/name} bytes long.  The memory area
  shall be large enough to contain some internal region administration data.

  The **starting address and length of segments** allocated from the region
  will be an integral multiple of ${.:/params[3]/name}.  The specified page
  size will be aligned to an implementation-dependent minimum alignment if
  necessary.

  The **attribute set** specified in ${.:/params[4]/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 **task wait queue discipline** is selected by the mutually exclusive
  ${../../attr/if/fifo:/name} and ${../../attr/if/priority:/name} attributes.
  The discipline defines the order in which tasks wait for allocatable segments
  on a currently empty region.

  * 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.
enabled-by: true
index-entries:
- create a region
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/max
- role: constraint
  uid: /constraint/obj-unlimited-alloc
name: rtems_region_create
notes: |
  For control and maintenance of the region, RTEMS allocates a
  ${/glossary/rncb:/term} from the local RNCB free pool and initializes it.
params:
- description: |
    is the object name of the region.
  dir: null
  name: name
- description: |
    is the starting address of the memory area managed by the region.
  dir: null
  name: starting_address
- description: |
    is the length in bytes of the memory area managed by the region.
  dir: null
  name: length
- description: |
    is the alignment of the starting address and length of each allocated
    segment of the region.
  dir: null
  name: page_size
- description: |
    is the attribute set of the region.
  dir: null
  name: attribute_set
- description: |
    is the pointer to an object identifier variable.  The identifier of the
    created region 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[0]/name} parameter was invalid.
    value: ${../../status/if/invalid-name:/name}
  - description: |
      The ${.:/params[5]/name} parameter was ${/c/if/null:/name}.
    value: ${../../status/if/invalid-address:/name}
  - description: |
      The ${.:/params[1]/name} parameter was ${/c/if/null:/name}.
    value: ${../../status/if/invalid-address:/name}
  - description: |
      There was no inactive object available to create a region.  The number
      of regions available to the application is configured through the
      ${/acfg/if/max-regions:/name} application configuration option.
    value: ${../../status/if/too-many:/name}
  - description: |
      The ${.:/params[3]/name} parameter was invalid.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      The memory area specified in ${.:/params[1]/name} and
      ${.:/params[2]/name} was too small.
    value: ${../../status/if/invalid-size:/name}
type: interface