MCC Melody API

The characteristics of MCC Melody API, including Blocking vs. Non-blocking, ISRs, Callbacks and Task routines.

The Application Programming Interface (API) of MCC Melody Components (Libraries/Drivers/PLIBs) consists of the functions/APIs they generate, which can be used to develop an embedded application. The generated API can vary depending on how the MCC Melody Component is configured in the MCC Melody GUI. For example, the API implementation will change depending on whether interrupts are enabled. Below are some principles behind which the MCC Melody API is developed.

MCC Melody API - Characteristics Related to Design Patterns

The following are MCC Melody API characteristics directly related to the choice of a control flow design pattern, such as Polled or Interrupt/Callback.

MCC Melody API are Non-Blocking

Non-blocking API functions can be turned into blocking functions relatively easily, e.g., by adding a busy waiting loop on a specific condition. However, if a function is created as blocking, it is much more difficult to remove the blocking nature of the function. So, MCC Melody Components will always provide non-blocking functions. Certain blocking functions may be provided to ease development. Since blocking functions are the exception, they will always be identified in the function header description.

The following MCC Melody API characteristics provide a great basis for supporting various control flow design patterns:
  • A component’s API should avoid blocking while waiting for external events or tasks to complete
    Attention: Doing nothing and looping until the UART receives data is avoided because it will block the execution of the embedded program.
  • Rather than waiting for external events, the API is broken into several smaller non-blocking functions. If a calling function needs to know when an operation has been completed, a status function is provided, or a callback function is registered.
  • APIs avoid blocking using a “busy waiting” loop that does nothing but repeatedly check for a given condition to change even if the condition is based on something internal to the processor, that should always happen promptly. However, sometimes, it is more effective to spend several microseconds than several milliseconds entirely switching context.
    Tip: Serial Peripheral Interface (SPI) Exchange and UART Write are valid examples of blocking as the operation finishing time does not depend on external stimuli.
  • In general, for good program flow, MCC Melody API function processing time is kept as short as possible, even when doing helpful work

MCC Melody provides Polling and/or Interrupt Modes

  • Each component may provide a polling mode, an interrupt mode, or both

MCC Melody Interrupt Service Routines (ISRs)

ISRs are generally very short, consisting of only the following tasks:

  • Clearing the associated interrupt flag
  • Calling the registered callback function
    Tip: A default empty callback will be called if no callback has been registered.
  • These procedures are executed when MCU peripherals require specific operations before clearing the interrupt flag
MCC Melody Callback Functions
  • Interrupt mode, i.e., interrupts enabled, will have an associated callback function
  • Polling mode, i.e., interrupts disabled, may provide a callback function
  • The ComponentName_XXXCallbackRegister API is used to set a callback routine (where *XXX is a feature such as Read, Error, Write, Timeout)
Task Routine
  • Polling mode - For given components, Task Routines may be provided

MCC Melody API: General Characteristics

MCC Melody API Naming Conventions

  • API names and globally-visible constants and definitions are prefixed by the abbreviated component name (custom name, if provided) followed by an underscore.

    E.g., TMR_, ADC_

  • The component name is followed by the specific distinctions from general to specific
  • The verb (Get, Set, Enable, Disable, etc.) comes at the end of the interface function
  • Sub-component

    • When a sub-component is being used, API names and globally-visible constants and definitions are prefixed by the abbreviated component name (or custom name, if provided) followed by an underscore and a sub-component name followed by an underscore

      E.g., DMA_CRC_, SPI_DMA_

Initialize Routine
  • Only the required registers are initialized
  • Read-only registers are not initialized in this routine
  • For interrupt initialization, flags are cleared before enabling the corresponding interrupt
  • Component enable is only done at the end of the routine, unless a specific sequence is required for the MCU peripheral initialization