# Copyright (c) 2021, STMicroelectronics
# SPDX-License-Identifier: Apache-2.0

description: |
    STM32 OSPI Flash controller supporting the JEDEC CFI interface

    Representation of a serial flash on a octospi bus:

        mx25lm51245: ospi-nor-flash@0 {
                compatible = "st,stm32-ospi-nor";
                reg = <0>;
                data-mode = <OSPI_OPI_MODE>; /* access on 8 data lines */
                data-rate = <OSPI_DTR_TRANSFER>; /* access in DTR */
                ospi-max-frequency = <DT_FREQ_M(50)>;
                size = <DT_SIZE_M(4)>;
                status = "okay";
        };

compatible: "st,stm32-ospi-nor"

include: ["flash-controller.yaml", "jedec,jesd216.yaml"]

on-bus: ospi

properties:
    reg:
      required: true
    ospi-max-frequency:
      type: int
      required: true
      description: Maximum clock frequency of device's OSPI interface in Hz
    size:
      required: true
      description: Flash Memory size in bits
    reset-gpios:
      type: phandle-array
      required: false
      description: RESETn pin
    spi-bus-width:
      type: int
      required: true
      description: |
       The width of (Octo)SPI bus to which flash memory is connected.

       Possible values are :
        - OSPI_SPI_MODE  <1> = SPI mode on 1 data line
        - OSPI_DUAL_MODE <2> = Dual mode on 2 data lines
        - OSPI_QUAD_MODE <4> = Quad mode on 4 data lines
        - OSPI_OPI_MODE  <8> = Octo mode on 8 data lines
      enum:
        - 1
        - 2
        - 4
        - 8
    data-rate:
      type: int
      required: true
      description: |
       The SPI data Rate is STR or DTR

       Possible values are :
        - OSPI_STR_TRANSFER <1> = Single Rate Transfer
        - OSPI_DTR_TRANSFER <2> = Dual Rate Transfer (only with OSPI_OPI_MODE)
      enum:
        - 1
        - 2
    writeoc:
      type: string
      required: false
      enum:
        - "PP"            # Page program, PP (0x02) up to 256 bytes
        - "PP_1_1_2"      # Dual page program, PP 1-1-2 (0xA2)
        - "PP_1_1_4"      # Quad data line SPI, PP 1-1-4 (0x32)
        - "PP_1_4_4"      # Quad data line SPI, PP 1-4-4 (0x38)
      description: |
        The value encodes number of I/O lines used for the opcode,
        address, and data.

        There is no info about quad page program opcodes in the SFDP
        tables, hence it has been assumed that NOR flash memory
        supporting 1-4-4 mode also would support fast page programming.

        Intended for modes other than OSPI_OPI_MODE.

        If absent, then program page opcode is determined by the
        `spi-bus-width`:

        * OSPI_SPI_MODE -> PP 1-1-1 (0x02)
        * OSPI_DUAL_MODE -> PP 1-1-2 (0xA2)
        * OSPI_QUAD_MODE -> PP 1-4-4 (0x38)
    four-byte-opcodes:
      type: boolean
      required: false
      description: |
        Some NOR-Flash ICs use different opcodes when operating in
        4 byte addressing mode.

        When enabled, then 3 byte opcodes will be converted to
        4 byte opcodes.

        * PP 1-1-1 (0x02) -> PP 1-1-1 4B (0x12)
        * PP 1-1-4 (0x32) -> PP 1-1-4 4B (0x34)
        * PP 1-4-4 (0x38) -> PP 1-4-4 4B (0x3E)

        * READ 1-1-1 (0x03) -> READ 1-1-1 4B (0x13)
        * READ FAST 1-1-1 (0x0B) -> READ FAST 1-1-1 4B (0x0C)
        * DREAD 1-1-2 (0x3B) -> DREAD 1-1-2 4B (0x3C)
        * 2READ 1-2-2 (0xBB) -> 2READ 1-2-2 4B (0xBC)
        * QREAD 1-1-4 (0x6B) -> QREAD 1-1-4 4B (0x6C)
        * 4READ 1-4-4 (0xEB) -> 4READ 1-4-4 4B (0xEC)