# SPDX-License-Identifier: Apache-2.0
#
# Copyright (c) 2023, Nordic Semiconductor ASA

## A pykwalify schema for basic validation of the structure of a SoC
## metadata YAML file.
##
# The soc.yml file is a simple list of key value pairs containing SoCs
# located and the current structure level.
schema;cpucluster-schema:
  required: false
  type: seq
  sequence:
    - type: map
      mapping:
        name:
          required: true
          type: str

schema;soc-schema:
  required: false
  type: seq
  sequence:
    - type: map
      mapping:
        name:
          required: true # Note: either name or extend is required, but that is handled in python
          type: str
        cpuclusters:
          include: cpucluster-schema

schema;soc-extend-schema:
  required: false
  type: seq
  sequence:
    - type: map
      mapping:
        name:
          required: false # Note: either name or extend is required, but that is handled in python
          type: str
        extend:
          required: false # Note: either name or extend is required, but that is handled in python
          type: str
        cpuclusters:
          include: cpucluster-schema

schema;series-schema:
  required: false
  type: seq
  sequence:
    - type: map
      mapping:
        name:
          required: true
          type: str
        socs:
          required: false
          include: soc-schema

type: map
mapping:
  family:
    required: false
    type: seq
    sequence:
      - type: map
        mapping:
          name:
            required: true
            type: str
          series:
            include: series-schema
          socs:
            include: soc-schema
  series:
    include: series-schema
  socs:
    include: soc-extend-schema
  vendor:
    required: false
    type: str
    desc: SoC series of the SoC.
          This field is of informational use and can be used for filtering of SoCs.
  comment:
    required: false
    type: str
    desc: Free form comment with extra information regarding the SoC.
  runners:
    type: map
    mapping:
      priority:
        type: int
        desc: |
              Priority of this flash run once configuration. The highest value data will be used
              instead of any with lower priorities. If omitted, will default to 0.
      run_once:
        type: map
        desc: |
              Allows for restricting west flash commands when using sysbuild to run once per given
              grouping of board targets. This is to allow for future image program cycles to not
              erase the flash of a device which has just been programmed by another image.
        mapping:
          regex;(.*):
            type: seq
            desc: |
                  A dictionary of commands which should be limited to running once per invocation
                  of west flash for a given set of flash runners and board targets.
            sequence:
              - type: map
                mapping:
                  run:
                    required: true
                    type: str
                    enum: ['first', 'last']
                    desc: |
                          If first, will run this command once when the first image is flashed, if
                          last, will run this command once when the final image is flashed.
                  runners:
                    required: true
                    type: seq
                    sequence:
                      - type: str
                        desc: |
                              A list of flash runners that this applies to, can use `all` to apply
                              to all runners.
                  groups:
                    required: true
                    type: seq
                    sequence:
                      - type: map
                        desc: |
                              A grouping of board targets which the command should apply to. Can
                              be used multiple times to have multiple groups.
                        mapping:
                          qualifiers:
                            required: true
                            type: seq
                            sequence:
                              - type: str
                                desc: |
                                      A board qualifier to match against in regex form. Must be one
                                      entry per board target, a single regex entry will not match
                                      two board targets even if they both match.