Migrating from PSoC 6 BSP v1.x to v2.x in ModusToolbox v2.2 – KBA231266

Version 2

    Version: **

     

    This KBA describes changes and new features introduced by the Board Support Package (BSP) v2.x release which impact ModusToolbox applications using BSP v1.x (latest-v1.X tag) and provides information on how these applications can be migrated to BSP v2.x (latest-v2.X tag).

     

    Note: BSP v2.x supports both the new “MTB flow” and earlier “lib flow” described in KBA231080. To use the new features of BSP v2.x, you must update your application to the new MTB flow by following KBA231080 - Migrating from ModusToolbox v2.1 to v2.2 before using BSP v2.x.

     

    See the release notes and readme of each BSP for specific details changes in BSP v2.x (release.md file in the TARGET_<BSP> GitHub repo).

     

    The following sections list the high-level changes across BSPs that could impact existing applications.

     

    Migrated pin definitions into design.modus file

     

    Change: The pin definitions such as CYBSP_USER_LED have been moved into the design.modus file from cybsp_types.h.

     

    Impact: This does not impact projects using the Cypress-provided BSPs as-is without any modifications. However, projects using custom design.modus or the ones that use a custom BSP require an update for it to work properly.

     

    • If your application uses a custom BSP: Regenerate the custom BSP (using a v2.x BSP). See the “Creating a BSP for your board” section in the ModusToolbox User Guide.
    • If your application uses a custom design.modus file with BSP v1.x:  Do the following to migrate to use newer BSP v2.X libraries.

     

    1. Follow the instructions in KBA231080 to update the example to the new MTB flow and add the latest v2.x BSP to the project through Library Manager.
    2. Rename the existing <app_folder>\COMPONENT_CUSTOM_DESIGN_MODUS\TARGET_<BSP>\design.modus file as design(1.x).modus to create a backup and move it to a location that is outside the application. Note that your application can have only one .modus file.
    3. Copy the v2.x version of the design.modus file from <app_folder>\..\mtb_shared\TARGET_<BSP>\latest-v2.X\COMPONENT_BSP_DESIGN_MODUS and paste it in <app_folder>\COMPONENT_CUSTOM_DESIGN_MODUS\TARGET_<BSP>\.
    4. Open the newly added design.modus file using the Device Configurator installed with ModusToolbox 2.2 tools (Device-Configurator 2.20.0).
    5. When prompted to find "devicesupport.xml", navigate to <app_folder>\..\mtb_shared\mtb-pdl\latest-v2.X\devicesupport.xml.
    6. Redo the configuration needed by the application. In some cases, you can copy-paste the personality settings from the design(1.x).modus file:
      1. Open another instance of the Device Configurator and open the design(1.x).modus file.
      2. Navigate to devicesupport.xml file as done in Step 5.
      3. Highlight the peripheral and click Copy.
      4. Open the other Device Configurator window and paste the settings into the corresponding peripheral.
        You may need to re-configure pins, clock trees, and any other resources needed for the peripheral.
    7. Delete the design(1.x).modus file.

     

    Updated clock settings - HFCLKs other than HFCLK0 is disabled

     

    This change impacts applications using HFCLKs other than HFCLK0 without setting up the HFCLK using the clock HAL in firmware. For example, USB applications need HFCLK4, while QSPI applications need HFCLK2. These applications would either need to use a custom design.modus with the clocks enabled, or use the clock HAL in firmware to enable/configure the respective HFCLKs and their sources.

     

    The following example snippet shows configuring the FLL to run at 100 MHz use it for the SMIF/QSPI clock (HFCLK2) at 50 MHz:

     

          cy_rslt_t rslt;

        cyhal_clock_t clock_hf2, clock_fll, clock_imo;

     

        /* Initialize FLL first: Get the FLL resource */

        rslt = cyhal_clock_get(&clock_fll, &CYHAL_CLOCK_FLL);

        /* Initialize, take ownership of, the FLL instance */

        rslt = cyhal_clock_init(&clock_fll);

        /* Set the clock source to IMO */

        rslt = cyhal_clock_get(&clock_imo, &CYHAL_CLOCK_IMO);

        rslt = cyhal_clock_set_source(&clock_fll, &clock_imo);

        /* Set the FLL clock frequency to the desired HFCLK2 frequency – 50 MHz, in this case */

        rslt = cyhal_clock_set_frequency(&clock_hf2, 100000000, NULL);

     

        /* If the FLL is not already enabled, enable it */

        if (!cyhal_clock_is_enabled(&clock_fll))

        {

            rslt = cyhal_clock_set_enabled(&clock_fll, true, true);

        }

     

       

        /* Get the HFCLK2 – SMIF clock – resource */

        rslt = cyhal_clock_get(&clock_hf2, &CYHAL_CLOCK_HF[2]);

        /* Initialize, take ownership of, the HFCLK2 instance */

        rslt = cyhal_clock_init(&clock_hf2);

        /* Set the clock source to FLL that we configured earlier */

        rslt = cyhal_clock_set_source(&clock_hf2, &clock_fll);

        /* Set the clock divider to 2, which would result in a 50 MHz SMIF clock */

        rslt = cyhal_clock_set_divider(&clock_hf2, 2);

     

        /* If the clock is not already enabled, enable it */

        if (!cyhal_clock_is_enabled(&clock_hf2))

        {

            rslt = cyhal_clock_set_enabled(&clock_hf2, true, true);

        }

     

        /* If no longer need to directly control the clock, it can be freed */

        cyhal_clock_free(&clock_hf2);

        cyhal_clock_free(&clock_fll);

        cyhal_clock_free(&clock_imo);

     

    Updated MPNs on some boards to non-obsolete parts

     

    Change: The PSoC 62S2 part that ships with CY8CPROTO-062-4343W and CY8CKIT-062S2-43012 has been updated to a new MPN. The MPN has been changed from CY8C624ABZI-D44 to CY8C624ABZI-S2D44. There is no functional or performance change in the device itself. It is simply an MPN update to align with our updated part naming strategy.

     

    Impact: This change does not impact examples using standard design.modus; only the examples using a custom design.modus will be affected. Typically, if you use the custom design.modus porting steps to BSP 2.x, this issue should automatically get fixed. The change that is required is to update the “Device mpn” value in the design.modus file from CY8C624ABZI-D44 to CY8C624ABZI-S2D44. Because this change already has been incorporated in the BSP design.modus file as part of the BSP v2.x release, the MPN is automatically updated when you create a custom design.modus from that file.

     

    Switched psoc6pdl dependency to new mtb-pdl-cat1

     

    Change: BSP v2.x uses the new mtb-pdl-cat1 (an updated and renamed version of psoc6pdl) instead of psoc6pdl. This new naming scheme allows you to organize PDL, HAL, and Makefiles into different categories (cat1, cat2, etc.) of devices/family that use similar underlying architecture.

     

    Impact: There should not be any impact because of this change. You need to update the path only if the application code references any PDL header files directly using absolute or relative path to the psoc6pdl folder such as #include “<APP_PATH>/libs/psoc6pdl/drivers/include/cy_gpio.h”. In such cases, use the new structure: #include “<APP_PATH>/../mtb_shared/mtb-pdl-cat1/drivers/include/cy_gpio.h”.

     

     

    Switched psoc6hal dependency to new mtb-hal-cat1

     

    Change: BSP v2.x uses the new mtb-hal-cat1 (an updated and renamed version of psoc6hal) instead of psoc6hal. This new naming scheme allows you to organize PDL, HAL, and Makefiles into different categories (cat1, cat2, etc.) of devices/family that use similar underlying architecture.

     

    Impact: There should not be any impact because of this change. You need to update the path only if the application code references any PDL header files directly using absolute or relative path to the psoc6pdl folder such as #include “<APP_PATH>/libs/psoc6hal/include/cyhal_gpio.h”. In such cases, use the new structure - #include “<APP_PATH>/../mtb_shared/mtb-hal-cat1/include/cyhal_gpio.h”.

     

    Switched psoc6make dependency to new core-make and recipe-make-cat1a

     

    Change: BSP v2.x uses the new core-make and receipe-make-cat1a instead of psoc6make used in BSP v1.x. This new naming scheme allows you to organize PDL, HAL, and Makefiles into different categories (cat1, cat2, etc.) of devices/family that use similar underlying architecture.

     

    Impact: Minor Makefile updates described in KBA231080.

     

    Note: This version requires ModusToolbox tools 2.2 or later. This version is not backward-compatible with 1.x versions.