source: rtems-central/spec/rtems/part/if/create.yml @ f3be101

SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
  Creates a partition.
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}
    - void *${.:/params[1]/name}
    - ${/c/if/uintptr_t:/name} ${.:/params[2]/name}
    - ${/c/if/size_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 partition of fixed size buffers from a physically
  contiguous memory space which starts at ${.:/params[1]/name} and is
  ${.:/params[2]/name} bytes in size.  Each allocated buffer is to be of
  ${.:/params[3]/name} in bytes.  The assigned object identifier is returned in
  ${.:/params[5]/name}.  This identifier is used to access the partition with
  other partition related directives.

  The **attribute set** specified in ${.:/params[4]/name} is built through
  a *bitwise or* of the attribute constants described below.  Attributes not
  mentioned below are not evaluated by this directive and have no effect.

  The partition can have **local** or **global** scope in a multiprocessing
  network (this attribute does not refer to SMP systems).

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

  * A **global** scope is established if the ${../../attr/if/global:/name}
    attribute is set.  The memory space used for the partition must reside in
    shared memory.  Setting the global attribute in a single node system has no
    effect.
enabled-by: true
index-entries:
- create a partition
interface-type: function
links:
- role: interface-placement
  uid: header
- role: interface-ingroup
  uid: group
name: rtems_partition_create
notes: |
  This directive may cause the calling task to be preempted due to an obtain
  and release of the object allocator mutex.

  The partition buffer area specified by the ${.:/params[1]/name} must be
  properly aligned.  It must be possible to directly store target architecture
  pointers and also the user data.  For example, if the user data contains some
  long double or vector data types, the partition buffer area and the buffer
  size must take the alignment of these types into account which is usually
  larger than the pointer alignment.  A cache line alignment may be also a
  factor.  Use ${alignment:/name} to specify the minimum alignment of a
  partition buffer type.

  The ${.:/params[3]/name} parameter must be an integral multiple of the
  pointer size on the target architecture.  Additionally,
  ${.:/params[3]/name} must be large enough to hold two pointers on the
  target architecture.  This is required for RTEMS to manage the buffers when
  they are free.

  For control and maintenance of the partition, RTEMS allocates a
  ${/glossary/ptcb:/term} from the local PTCB free pool and initializes it.
  Memory from the partition buffer area is not used by RTEMS to store the PTCB.

  The PTCB for a global partition is allocated on the local node.  Partitions
  should not be made global unless remote tasks must interact with the
  partition.  This is to avoid the overhead incurred by the creation of a
  global partition.  When a global partition is created, the partition'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 partitions, is limited by the
  value of the ${/acfg/if/mp-max-global-objects:/name} application
  configuration option.
params:
- description: is the name of the partition.
  dir: null
  name: name
- description: is the starting address of the buffer area used by the partition.
  dir: null
  name: starting_address
- description: is the length in bytes of the buffer area used by the partition.
  dir: null
  name: length
- description: is the size in bytes of a buffer managed by the partition.
  dir: null
  name: buffer_size
- description: is the attribute set of the partition.
  dir: null
  name: attribute_set
- description: |
    is the pointer to an object identifier variable.  The identifier of the
    created partition 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 partition name 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[2]/name} parameter was 0.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      The ${.:/params[3]/name} parameter was 0.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      The ${.:/params[2]/name} parameter was less than the
      ${.:/params[3]/name} parameter.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      The ${.:/params[3]/name} parameter was not an integral multiple of
      the pointer size.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      The ${.:/params[3]/name} parameter was less than two times the
      pointer size.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      The ${.:/params[1]/name} parameter was not on a pointer size
      boundary.
    value: ${../../status/if/invalid-address:/name}
  - description: |
      There was no inactive object available to create a new partition.  The
      number of partitions available to the application is configured through
      the ${/acfg/if/max-partitions:/name} configuration option.
    value: ${../../status/if/too-many:/name}
type: interface