Description

	Note
	Application developers should not normally need to concern themselves with the internal API between this common layer and the H/W specific device drivers. The following information is primarily for H/W device driver developers.

In most cases the platform (PLF) declares the individual flash driver instances. The top-level descriptor as used with the flash API (CYGPKG_IO_FLASH) should reference the flash API functions provided by this package (cyg_devs_flash_common_funs) as well as provide a per-instance cyg_flash_csm_context_t structure initialised with a reference to the instance-specific hardware driver descriptor in the p_hwdriver field.

The driver instance specific cyg_spi_common_hwdriver_t descriptor is used to describe the hardware driver specific features to this common layer.

Flash API                      Common                                  H/W Driver
(struct cyg_flash_dev).priv -> (cyg_flash_csm_context_t).p_hwdriver -> (cyg_spi_common_hwdriver_t)

All architecture/platform/HAL eCos xSPI device drivers using the CYGPKG_DEVS_FLASH_SPI_COMMON package must implement a standard interface defined by the header <cyg/io/flash_csm_dev.h>. The interface descriptor structure includes a private pointer for the H/W driver context, a “features” set and a set of function pointers for various operations: initialization, memory operation, memory-mapped access and general configuration.

struct cyg_spi_common_hwdriver {
    // H/W driver private (opaque) context:
    const void *p_io; // H/W driver specific I/O information

    // H/W driver feature set descriptor:
    const cyg_flash_csm_features_t * const p_features;

    // Common H/W driver API
    cyg_spi_common_hwdriver_init *init; // initialisation function
    cyg_spi_common_hwdriver_op *op; // single command operation function
    cyg_spi_common_hwdriver_mm_start *mm_start; // memory-mapped start/enable
    cyg_spi_common_hwdriver_mm_stop *mm_stop; // memory-mapped stop/disable
    cyg_spi_common_hwdriver_config *config; // get/set config+control
};

Hardware Driver Features

The p_features structure provides fixed information used to describe to this common layer the features and settings of the H/W driver instance:

typedef struct cyg_flash_csm_features {
    cyg_uint32 avail; // bitmask of H/W driver available features
    cyg_uint32 mmaddr; // if MM capable, base address for MM region
    // Since early JESD216 standards do not provide a mechanism for the device
    // to report its maximum frequency we allow the platform/variant HAL to be
    // configured with maximum rates.
    cyg_uint32 max_sdr; // if non-zero platform/variant HAL provided maximum SDR baudrate
    cyg_uint32 max_ddr; // if non-zero platform/variant HAL provided maximum DDR baudrate
    cyg_uint32 nmodes; // number of modes present in modes vector
    const cyg_uint32 * const p_modes; // pointer to vector of FLASH_CSM_OP_MODE_MASK
                                      // covered bitmasks for available modes
} cyg_flash_csm_features_t;

The p_features structure allows the H/W driver to report the SPI modes capable by the device driver. This can, for example, be used in conjunction with information gathered from the device using SFDP to select the common subset of supported access methods: e.g. Quad (QSPI) vs Octal (OSPI).

The current set of available feature flags indicating H/W driver support is:

The p_modes pointer references the nmodes deep vector of access modes supported, encoded using the same OP bitmask encoding as used for the individual memory operations. For example an Octal (OSPI) capable driver might define:

// List of possible modes for this driver:
static const cyg_uint32 cyg_hwdriver_modes[] = {
    // 8-line Octal (OSPI)
    FLASH_CSM_OP_MODE_1S1S8S, //  0
    FLASH_CSM_OP_MODE_1S8S8S, //  1
    FLASH_CSM_OP_MODE_8S8S8S, //  2
    FLASH_CSM_OP_MODE_8D8D8D, //  3
    // 4-line QSPI
    FLASH_CSM_OP_MODE_1S1S4S, //  4
    FLASH_CSM_OP_MODE_1S4S4S, //  5
    FLASH_CSM_OP_MODE_4S4S4S, //  6
    FLASH_CSM_OP_MODE_4S4D4D, //  7
    // 2-line
    FLASH_CSM_OP_MODE_1S1S2S, //  8
    FLASH_CSM_OP_MODE_1S2S2S, //  9
    FLASH_CSM_OP_MODE_2S2S2S, // 10
    // 1-line
    FLASH_CSM_OP_MODE_1S1S1S, // 11
};

Referencing the vector in its feature descriptor:

static const cyg_flash_csm_features_t hwdriver1_features = {
    ..elided..
    .nmodes = NUMOF_(cyg_hwdriver_modes),
    .p_modes = &cyg_hwdriver_modes[0]
};

Hardware Driver-Specific Structure

The p_io pointer allows the H/W device driver to hold per-instance private data as needed for the operation of the driver.

Normally the driver context would be split into read-only, constant, data that could be held in the code with only the truly dynamic context occupying RAM space. See the Hardware Example below for an outline.

Functions

The H/W driver provides its common driver API via the cyg_spi_common_hwdriver_t descriptor. For the function pointers the NULL value can be used to indicate that the relevant support is not required. Only the op function must be provided, though it is unlikely that the driver would not require a init function to be called at startup.

typedef int cyg_spi_common_hwdriver_init(const void *p_info, cyg_bool do_reset, cyg_uint32 baudrate);

typedef cyg_bool cyg_spi_common_hwdriver_op(const void *p_info, const cyg_flash_csm_op_t *p_op);

typedef struct cyg_flash_csm_op {
    cyg_uint32 mode; // Encoded bus information and control
    cyg_uint32 cmdflags; // Instruction CMD and extra control flags
    cyg_uint32 address; // Device relative address
    cyg_uint32 opt; // Upto 32-bits of OPT (mode-bits; alternate) data
    cyg_uint32 timeout; // Millisecond timeout for operation
    cyg_uint32 nbytes; // Non-zero is number of valid bytes from p_buff
    cyg_uint8 *p_buff; // Pointer to data buffer for transfer
} cyg_flash_csm_op_t;

typedef cyg_bool cyg_spi_common_hwdriver_mm_start(const void *p_info);

typedef cyg_bool cyg_spi_common_hwdriver_mm_stop(const void *p_info);

typedef cyg_bool cyg_spi_common_hwdriver_config(const void *p_info,
                                                cyg_uint32 key, void *p_buff, cyg_uint32 *p_len);

Example

The following section provides an example skeleton of how a H/W driver instance can be declared.

Since device drivers normally have a requirement for some fixed (constant) information describing the hardware configuration as well as possibly some dynamic state to hold run-time information (e.g. ISR or DSR state) the example below shows a simple framework. The example hw_driver_ctx_t structure used for the dynamic context and the hw_driver_io_t structure holding the constant/fixed information are specific to the H/W driver implementation and the underlying H/W controller requirements.

For our example instance in the H/W driver source we can provide a RAM based private context for the dynamic state:

static hw_driver_ctx_t hw_dynamic1 = {};

This can then be referenced from a constant (normally placed in read-only memory by the linker) structure with the fixed information for the driver along with a pointer to the RAM based dynamic run-time context structure:

static const hw_driver_io_t hw_context1 {
    .p_ctx = &hw_driver_dynamic1, // dynamic H/W driver state
    // The fixed information needed by the H/W driver
    .intr_vec = <HAL_INTERRUPT_NUMBER>
    .pin_sclk = <HAL/PLF_SCLK_PIN_DESCRIPTOR>
    ..elided..
};

The driver can then provide a per-instance common H/W driver API structure referencing the H/W driver context and the features and functions provided by the driver:

const cyg_spi_common_hwdriver_t cyg_dev_flash_csm_example1= {
    .p_io = &hw_context1,
    .p_features = &hw_features,
    .init = hw_init,
    .op = hw_op,
    .mm_start = NULL, // op interface sufficient for this driver
    .mm_stop = NULL, // op interface sufficient for this driver
    .config = hw_config
};

With the H/W driver providing the cyg_spi_common_hwdriver_t structure the platform specific sources would then reference the H/W driver instance when declaring the flash object in the platform/HAL specific source file:

static struct cyg_flash_block_info cyg_flash_common_block_info;

static cyg_flash_csm_context_t cyg_flash_common_ctx = {
    .p_hwdriver = &cyg_dev_flash_csm_example1, // reference H/W instance
};

CYG_FLASH_DRIVER(cyg_common_device,
                 &cyg_devs_flash_common_funs,
                 0,
                 <BASE_ADDR>, // start (normally same as p_features.mmaddr field
                 <BASE_ADDR>, // end (depends on detected device, so filled in at run-time)
                 1, // number of flash block info structures
                 &cyg_flash_common_block_info,
                 &cyg_flash_common_ctx);

After successful flash device initialisation the struct cyg_flash_dev field end will hold the end address for the flash area. The start and end addresses are used by the flash API to select the relevant device descriptor when accessing a flashg area.

When called, the common layer code can use the p_hwdriver field to access the specific H/W instance used to access the actual flash device for the area, with the H/W driver subsequently de-referencing its own structures to access the fixed and dynamic portions of its context.