# This is the Maestro Core YAML schema, maestro-core.yaml
# Make sure you verify it using maestro-schema-schema.yaml
schema-name: Maestro Core
schema-version: 0

# relative attributes will be grafted below this root:
schema-namespace: ".maestro.core."

# Values permitted in user-defined types used
#schema-type-values:
  # FIXME: user-defined types currently broken
  # values occuring in lifetime-strictness flag
  # - &lifetime-strictness-values enum('optional', 'required')
  # values occuring in lifetime-strictness flag
  #- &access-mode-values enum('rw', 'r')

# user-defined types used in this schema
#schema-types:
  
  # -  typename: lifetime-interval
  #    typespec: map()
  #    documentation: CDO lifetime type

  # -  typename: lifetime-strictness
  #    typespec: *lifetime-strictness-values
  #    documentation: CDO lifetime specifier interpretation

  # -  typename: access-mode
  #    typespec: *access-mode-values
  #    documentation: CDO access mode

# Individual attribute descriptions
maestro-attributes:
  ## TOPLEVEL attributes

  - key: ".maestro.core.cdo.name" # note: this is an absolute attribute name
    type: str()
    required: True
    documentation: The unique name of the CDO

  # note: the ID is not user-visible; it's synthetized during a workflow, documented here only
  # - key: "cdo.id"
  #   type: cdoid
  #   required: True
  #   documentation: The unique ID of the CDO in the workflow

  - key: cdo.raw-ptr
    type: pointer()
    required: False
    default: NIL
    documentation: A user-provided pointer of local storage associated with the CDO.

  - key: cdo.mamba-array
    type: pointer()
    required: False
    default: NIL
    documentation: A mamba-array associated with the local storage of
                   the CDO. Either a (1-d, non-padded, non-aligend)
                   wrapper around the cdo.raw-ptr provided by the
                   user, or maestro-allocated storage (if
                   cdo.maestro-provided-storage is true)

  - key: "cdo.allocate-now" # note: this is a relative attribute name
    type: bool()
    required: False
    default: False
    documentation: Perform immediate allocation for the CDO

  - key: "cdo.persist"
    type: bool()
    required: False
    default: False
    documentation: Ensure a persistent copy of the CDO is preserved
                   when the last copy of the CDO is WITHDRAWN from the
                   pool. (Note the non-trivial semantic interaction
                   with the cdo.desist attribute.)

  - key: "cdo.desist"
    type: bool()
    required: False
    default: True
    documentation: Ensure that all persistent copies of the CDO are
                   removed from persistent storage when the last
                   reference to the CDO is WITHDRAWn from the
                   pool. (Note the non-trivial semantic interaction
                   with the cdo.desist attribute.)

  - key: "cdo.maestro-provided-storage" 
    type: bool()
    required: False
    default: False
    documentation: Request/advise maestro storage management for the
                   CDO (no RAW-PTR will be provided or can be obtained)

  # - key: "cdo.access-mode"
  #   type: access-mode
  #   required: False
  #   default: *access-mode-values
  #   documentation: Indicates how the CDO will be accessed by the user
  #                  (read-write, read-only, etc.).

  - key: "cdo.transfer-asap"
    type: bool()
    required: False
    default: False
    documentation: Indicates that the CDO must be transfered as soon
                   as possible.

  - key: "cdo.never-pooled"
    type: bool()
    required: False
    default: False
    documentation: Indicates that the CDO will be never be used in
                   OFFER/DEMAND, which potentially permits extra
                   performance optimizations.

  - key: "cdo.isgroup"
    type: bool()
    required: False
    default: False
    documentation: Indicates that the CDO is a container for other CDOs,
                   i.e. a CDO group. Users are not expected to utilize or
                   set this attribute. 

  - key: "cdo.group-members"
    type: blob()
    required: False
    default: ""
    documentation: Opaque member descriptor if .maestro.core.cdo.is-group is True.
                  Users are not expected to utilize or set this attribute. 

  ## Lifetime related
  # - key: "cdo.lifetime"
  #   type: lifetime-interval
  #   required: False
  #   documentation: CDO lifetime specification.
  # - key: "cdo.lifetime-strictness"
  #   type: lifetime-strictness
  #   required: False
  #   default: *lifetime-strictness-values
  #   documentation: CDO lifetime specification.

    
  ## SCOPE related
  - key: "cdo.scope.size"
    type: int(min=-1)
    required: False
    default: -1
    documentation: The total size of the CDO. -1 indicates Unknown/Unallocated.

  - key: "cdo.scope.local-size"
    type: int(min=-1)
    required: False
    default: -1
    documentation: The local size of the CDO. -1 indicates Unknown/Unallocated.

  - key: "cdo.scope.layout.regular-1d.element-size" # deprecated
    type: uint()
    required: False
    default: 1
    documentation: Element-size in a 1-d regular layout

  # multidimensional layouts will be added with mamba
  # compatibility; will need enums and user-defined types for the
  # named layout styles like row-major/column-major

# Generic semantics

  - key: "cdo.layout.alignment"
    type: uint(min=0)
    required: False
    default: 0
    documentation: n-bytes boundary alignment request for maestro-allocated array

  - key: "cdo.layout.pre-pad"
    type: uint(min=0)
    required: False
    default: 0
    documentation: The offset at the very beginning of the whole data layout

  - key: "cdo.layout.post-pad"
    type: uint(min=0)
    required: False
    default: 0
    documentation: The offset at the very end of the whole data layout

  ## Layout semantics
  - key: "cdo.layout.element-size"
    type: int(min=1)
    required: False
    default: 1
    documentation: Size of a single element (data type) in bytes.

  - key: "cdo.layout.ndims"
    type: uint(min=1)
    required: False
    default: 1
    documentation: Number of dimensions of the layout.

  - key: cdo.layout.dims-size # FIXME: needs to be changed to at least blob, better array
    type: pointer() #array(uint(min=1))
    required: False
    default: NIL
    documentation: Size of each layout dimension in elements.

  - key: "cdo.layout.order" # could be an int for now
    type: int(min=0) #for now # enum( 'rowmajor', 'colmajor', 'generic-nd') # unimpl; could work immediately with regexp
    required: False
    default: 0
    documentation: General layout access order on the CDO.
#
#   - key: "cdo.layout.pattern"
#     type: array() # of enum ('array', 'structure')
#     required: False
#     default: NIL
#     documentation: Associate to each dimension a sense of contiguous access
#     (array) or strided access (structure). `enum MMB_LAYOUT_ELEMENT_TYPE`
#
#   - key: "cdo.layout.dims-pre-pad"
#     type: array()
#     required: False
#     default: NIL
#     documentation: Pre-padding bytes of each dimension.
#
#   - key: "cdo.layout.dims-post-pad"
#     type: array()
#     required: False
#     default: NIL
#     documentation: Post-padding bytes of each dimension.
#
# # WIP in mamba: block-cyclic and irregular layouts
#
# # Distribution semantics: TBD
#   - key: "cdo.distribution.id"
#     type: uint(min=0)
#     required: False
#     default: 0
#     documentation: Local chunk identifier of a distributed CDO.
#
#
# ## Memory Layer: TBD
#   - key: "cdo.memory.layer"
#     type: string # possible values need to match either mamba
#                          # builtin, or mamba hwloc, or a
#                          # maestro-config time definition of memory layer names
#     required: False
#     default: NIL
#     documentation: Memory layer of the raw-ptr and/or mamba-array for the CDO
#
#
# ## Meta-Information
# ## Each CDO will have meta-data information about, for instance, the memory layer(s) used


# (end of maestro-core.yaml)
 
