simstats.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://gem5.org/simstats.schema.json",

  "title": "Architecture Simulator Statistics",
  "description": "A set of statistics or results output from a computer architecture simulation. This schema is for a dump at a single point in time. For time-series data, you can have a file with many of these objects.",

  "definitions": {

    "storageType": {
      "type": "string",
      "enum": ["u32", "u64", "s32", "s64", "f32", "f64"],
      "description": "The underlying storage type",

      "$comment": "We may or may not want to keep this. So far, we haven't found a need for it."
    },

    "timeConversion": {
      "type": "object",
      "title": "Simulated time",
      "description": "A conversion from the simulator's concept of 'time' to seconds. This is a scale value to apply to any 'Time' type to get *simulated seconds*. Examples would include the simulator quantum and a clock cycle. For any 'time' type, you can take the closest 'timeConversion' object in the model hierarchy and calculate the simulated time in seconds by multiplying by `scaleFactor`.",
      "properties": {
        "scaleFactor": { "type": "number" },
        "description": { "type": "string" }
      },
      "required": ["scaleFactor"]
    },

    "statistic" : {
      "type": "object",
      "title": "Statistic",
      "description": "A simulator statistic. The name of the property is the name of this statistic. All statistics must have a `value` property. Each unique type should have its own schema. The `unit` should be some common unit of measure (e.g., seconds, meters, cycles, etc.). The `time` unit is special and can be converted to seconds by finding the closest `timeConversion` in the json hierarchy.",
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of statistic (e.g., Scalar, Distribution, etc.). Some specializations are defined in this schema. Any extensions are allowed."
        },
        "value": {
          "description": "The value of the stat. Generally, this can by any JSON type, but it may be specified in a specialization. This is the only required property, and in other output formats may be the only property for a stat."
        },
        "unit": {
          "type": "string",
          "description": "The unit of measure for this statistic. Useful for documentation. Not required, but highly suggested."
        },
        "description": { "type": "string" }
      },
      "required": ["value"],

      "$comment": "This is a generic statistic. It is 'extended' below as more specific statistic types through the use of `allOf`. By defining this general statistic type, we also allow others to compatibly add new types of statistics. For the general statistic, we don't have any specific type for value, it can take on any json type. This allows specialized statistics (e.g., Distribution) whose value is an array."
    },

    "scalar": {
      "allOf": [ {"$ref": "#/definitions/statistic"} ],
      "title": "Scalar",
      "description": "A scalar statistic value (e.g., a count, latency, etc.). The `value` property holds the value of the statistic with an optional datatype specification. They `type` property must match 'Scalar'.",

      "properties": {
        "type": { "const": "Scalar" },
        "value": { "type": "number" },
        "datatype": { "$ref": "#/definitions/storageType" }
      },

      "$comment": "The above `allOf` is similar to `extends` in java or other inheritance in object oriented languages. We're saying that a scalar must have all of the properties of a statistic, and also a value and datatype (optionally)."
    },

    "distribution": {
      "allOf": [ {"$ref": "#/definitions/statistic"} ],
      "title": "Distribution",
      "description": "A distribution of statistic values. This is an aggregated statistic which is a summary of many sampled simulator events. The `value` property holds the number of instances in each bin (i.e., this is a histogram). Bins can be defined either with a set size by using `binSize` and `numBins`, or `bins` can be defined with an array. The value should be an array with a length equal to `numBins` or the length of `bins` - 1. If defined as an array, the `bins` property has the following form: `[bin0 start, bin0 end, bin1 end, bin2 end, ... binN end]`. `count` is the total number of things added to the histogram. `min` and `max` are the minimum and maximum of the samples added to the distribution. `sumSquared` is the sum of each sample squared.",

      "properties": {
        "type": { "const": "Distribution" },
        "value": {
          "type": "array",
          "items": { "type": "integer", "minimum": 0 }
          },
        "bins": {
          "type": "array",
          "items": { "type": "number" }
        },
        "binSize": { "type": "number", "minimum": 0 },
        "numBins": { "type": "integer", "minimum": 1 },
        "count": { "type": "integer", "minimum": 0 },
        "min": { "type": "number"},
        "max": { "type": "number"},
        "sumSquared": { "type": "integer", "minimum": 0 }
      },
      "oneOf": [
        {
          "required": ["value", "bins"]
        },
        {
          "required": ["value", "binSize", "numBins"]
        }
      ],

      "$comment": "The `oneOf` above requires either `value` and `bins` or `value`, `binSize`, and `numBins` to allow either description of a distribution."
    },

    "accumulator": {
      "allOf": [ {"$ref": "#/definitions/statistic"} ],
      "title": "Accumulator",
      "description": "An accumulation of statistic values. This is an aggregated statistic which is a summary of many samples of simulator events. The `value` is the total sum of all of the samples added to the accumulator. `count` is the total number of things added to the histogram. `min` and `max` are the minimum and maximum of the samples added to the distribution. `sumSquared` is the sum of each sample squared. The datatype specifies the type of `value`, `min`, `max`, and `sumSquared`.",

      "properties": {
        "type": { "const": "Accumulator" },
        "value": { "type": "number" },
        "count": { "type": "integer", "minimum": 0 },
        "min": { "type": "number" },
        "max": { "type": "number" },
        "sumSquared": { "type": "integer", "minimum": 0},
        "datatype": { "$ref": "#/definitions/storageType" }
      },

      "required": ["value", "count"]
    },

    "strictStats" : {
      "anyOf": [
        {"$ref": "#/definitions/scalar"},
        {"$ref": "#/definitions/accumulator"},
        {"$ref": "#/definitions/distribution"}
      ],

      "$comment": "By using `strictStats` instead of just `statistic` as a reference you can constrain the validator to only accept 'standard' statistic types. This is useful for testing and development of this schema, but will likely be relaxed and change to any `statistic` in the final version."
    },

    "model": {
      "type": "object",
      "title": "Model",
      "description": "A simulated model which has statistics and possibly other sub models. The property with sub models can optionally be an array (e.g., an array of CPUs). The name of the property is the name of this model. Models can also have an optional `type` or a generic model type (e.g., a cache, a core, etc.). Specific types are defined in this schema. An optional `timeConversion` property defines how this model and all children models and statistics can convert `time` types to seconds.",
      "properties": {
        "type": { "type": "string" },
        "timeConversion": { "$ref": "#/definitions/timeConversion" }
      },
      "additionalProperties": {
        "oneOf": [
          { "$ref": "#/definitions/strictStats" },
          { "$ref": "#/definitions/model" },
          {
            "type": "array",
            "items": { "$ref": "#/definitions/model" }
          }
        ]
      },
      "minProperties": 1,

      "$comment": "Right now, models cannot be empty. We may want to revisit this. I'd like to enforce that a model doesn't have a `value` property so it can easily be differentiated from stats, but I can't figure out how."
    },

    "cache": {
      "title": "Generic cache statistics",
      "description": "Contains generic statistics that all caches should report to allow compatibility between simulators.",
      "allOf": [
        {"$ref": "#/definitions/model"},
        {
          "properties": {
            "type": { "const": "Cache" },
            "hits": { "$ref": "#/definitions/scalar" },
            "misses": { "$ref": "#/definitions/scalar" },
            "accesses": { "$ref": "#/definitions/scalar" }
          },
          "required": ["type", "hits", "misses", "accesses"]
        }
      ],

      "$comment": "This is just an example of a potential shared model type."
    }

  },

  "type": "object",

  "properties": {
    "creationTime": {
      "description": "The time this output was generated (wall clock time) in Date format",
      "type": "string",
      "format": "date-time"
    },
    "timeConversion": { "$ref": "#/definitions/timeConversion" },
    "simulatedEndTime": {
      "description": "Time (in simulator time) that these statistics were generated.",
      "type": "number"
    },
    "simulatedBeginTime": {
      "description": "Time (in simulator time) that these statistics were first generated. If missing, this value should be assumed to be 0 (the beginning of time).",
      "type": "number"
    }
  },

  "additionalProperties": {
    "anyOf": [
      { "$ref": "#/definitions/strictStats" },
      { "$ref": "#/definitions/model" },
      {
        "type": "array",
        "items": { "$ref": "#/definitions/model" }
      }
    ]
  }

}