# Copyright (c) 2022, Basalte bv
# SPDX-License-Identifier: Apache-2.0

description: |
  Atmel Static Memory Controller (SMC).

  The SMC allows to interface with static-memory mapped external devices such as
  SRAM, PSRAM, PROM, EPROM, EEPROM, LCD Module, NOR Flash and NAND Flash.

  The SMC is clocked through the Master Clock (MCK) which is controlled by the
  Power Management Controller (PMC).

  The SMC controller can have up to 4 children defining the connected external
  memory devices. The reg property is set to the device's Chip Select.
  Device Tree example taken from the sam4_xplained board:

  &smc {
    status = "okay";
    pinctrl-0 = <&smc_default>;
    pinctrl-names = "default";

    is66wv51216dbll@0 {
      reg = <0>;

      atmel,smc-write-mode = "nwe";
      atmel,smc-read-mode = "nrd";
      atmel,smc-setup-timing = <1 1 1 1>;
      atmel,smc-pulse-timing = <6 6 6 6>;
      atmel,smc-cycle-timing = <7 7>;
    };
  };

  The above example configures a is66wv51216dbll-55 device. The device is a
  low power static RAM which uses NWE and NRD signals connected to the WE
  and OE inputs respectively. Assuming that MCK is 120MHz (cpu at full speed)
  each MCK cycle will be equivalent to 8ns. Since the memory full cycle is
  55ns, as per specification, it requires atmel,smc-cycle-timing of at least
  7 pulses (56ns). The atmel,smc-cycle-timing is composed of three parts:
  setup, pulse and hold. The setup is used to address the memory. The pulse
  is the time used to read/write. The hold is used to release memory. For the
  is66wv51216dbll-55 a minimum setup of 5ns (1 cycle) with at least 45ns
  (6 cycles) for CPU read/write and no hold time is required.
  Note: Since no hold parameter is available at SMC the atmel,smc-cycle-timing
  should have additional cycles to accommodate for hold values.

    No Hold Time:
    cycle-timing (7) = setup (1) + pulse (6) + hold (0)

    With 3 Hold Times:
    cycle-timing (10) = setup (1) + pulse (6) + hold (3)

  Finally, in order to make the memory available you will need to define new
  memory device/s in DeviceTree:

  sram1: sram@60000000 {
      compatible = "zephyr,memory-region", "mmio-sram";
      device_type = "memory";
      reg = <0x60000000 DT_SIZE_K(512)>;
      zephyr,memory-region = "SRAM1";
  };

compatible: "atmel,sam-smc"

include: [base.yaml, pinctrl-device.yaml]

properties:
  reg:
    required: true

  "#address-cells":
    required: true
    const: 1

  "#size-cells":
    required: true
    const: 0

  peripheral-id:
    type: int
    description: peripheral ID
    required: true

child-binding:
  description: |
    Child device nodes are representing devices connected to the EBI/SMC bus.

  properties:
    reg:
      type: int
      required: true
      description: |
        The device's SMC Chip Select number.
        Valid range: 0 - 3

    atmel,smc-write-mode:
      type: string
      required: true
      description: |
        Select which signal is used for the write operation, either the chip
        select (ncs) or a dedicated write enable pin (nwe). The data is put
        on the bus during the pulse and hold steps of that signal.
        The internal data buffers are switched to output mode after the NCS_WR
        or NWE setup time.
      enum:
        - "ncs"
        - "nwe"

    atmel,smc-read-mode:
      type: string
      required: true
      description: |
        Select which signal is used for the read operation, either the chip
        select (ncs) or a dedicated output enable pin (nrd). The data is read
        from the bus during the pulse and hold steps of that signal.
      enum:
        - "ncs"
        - "nrd"

    atmel,smc-setup-timing:
      type: array
      required: true
      description: |
        This value is used to setup memory region (set address). The setup
        values is an array of the signals NWE, NCS_WR, NRD and NCS_RD
        where each value is configured in terms of MCK cycles. The SMC
        controller allows use of setups value of 0 (no delays) when
        consecutive reads/writes are used. Each value is encoded in
        6 bits where the highest bit adds an offset of 128 cycles.
        The effective value for each element is: 128 x setup[5] + setup[4:0]

    atmel,smc-pulse-timing:
      type: array
      required: true
      description: |
        This value is used to effectivelly read/write at memory region (pulse phase).
        The pulse value is an array of the signals NWE, NCS_WR, NRD and NCS_RD where
        each value is configured in terms of MCK cycles and a value of 0 is forbidden.
        Each value is encoded in 7 bits where the highest bit adds an offset of 256
        cycles. The effective value for each element is: 256 x setup[6] + setup[5:0]

    atmel,smc-cycle-timing:
      type: array
      required: true
      description: |
        SMC timing configurations in cycles for the total write and read
        length respectively.
        This value describes the entire write/read operation timing which
        is defined as: cycle = setup + pulse + hold
        Value has to be greater or equal to setup + pulse timing and
        is encoded in 9 bits where the two highest bits are multiplied
        with an offset of 256.
        Effective value for each element: 256 x cycle[8:7] + cycle[6:0]