SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
brief: |
  Constructs a message queue from the specified the message queue
  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_message_queue_construct
notes: |
  In contrast to message queues created by ${create:/name}, the message queues
  constructed by this directive use a user-provided message buffer storage
  area.
 
  This directive is intended for applications which do not want to use the
  RTEMS Workspace and instead statically allocate all operating system
  resources.  An application based solely on static allocation can avoid any
  runtime memory allocators.  This can simplify the application architecture
  as well as any analysis that may be required.
 
  The value for ${/acfg/if/message-buffer-memory:/name} should not include
  memory for message queues constructed by ${.:/name}.
params:
- description: is the message queue configuration.
  dir: null
  name: config
- description: |
    is the pointer to an object identifier variable.  The identifier of the
    constructed message queue 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 message queue name in the configuration was invalid.
    value: ${../../status/if/invalid-name:/name}
  - description: |
      The maximum number of pending messages in the configuration was zero.
    value: ${../../status/if/invalid-number:/name}
  - description: |
      The maximum message size in the configuration was zero.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      There was no inactive message queue object available to construct a
      message queue.
    value: ${../../status/if/too-many:/name}
  - description: |
      In multiprocessing configurations, there was no inactive global object
      available to construct a global message queue.
    value: ${../../status/if/too-many:/name}
  - description: |
      The maximum message size in the configuration was too big and resulted in
      integer overflows in calculations carried out to determine the size of
      the message buffer area.
    value: ${../../status/if/invalid-size:/name}
  - description: |
      The maximum number of pending messages in the configuration was too big
      and resulted in integer overflows in calculations carried out to
      determine the size of the message buffer area.
    value: ${../../status/if/invalid-number:/name}
  - description: |
      The message queue storage area begin pointer in the configuration was
      ${/c/if/null:/name}.
    value: ${../../status/if/unsatisfied:/name}
  - description: |
      The message queue storage area size in the configuration was not equal to
      the size calculated from the maximum number of pending messages and the
      maximum message size.
    value: ${../../status/if/unsatisfied:/name}
type: interface