Src Folder in Drivers - 2024.1 English

Porting Guide for embeddedsw Components System Device Tree Based Build Flow (UG1647)

Document ID
UG1647
Release Date
2024-06-21
Version
2024.1 English

A new file called CMakeLists.txt is introduced in the new flow. Instead of Makefile, every driver should have a CMakeLists.txt file. Almost all driver CMakeLists.txt files look similar. A typical driver CMakeLists.txt file is shown below:

cmake_minimum_required(VERSION 3.15)
project(<driver name>)
find_package(common)
collector_create (PROJECT_LIB_HEADERS "${CMAKE_CURRENT_SOURCE_DIR}")
collector_create (PROJECT_LIB_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}")
include_directories(${CMAKE_BINARY_DIR}/include)
collect (PROJECT_LIB_SOURCES <source file>)
collect (PROJECT_LIB_HEADERS <header file>)
collector_list (_sources PROJECT_LIB_SOURCES)
collector_list (_headers PROJECT_LIB_HEADERS)
file(COPY ${_headers} DESTINATION ${CMAKE_BINARY_DIR}/include)
add_library(<driver name> STATIC ${_sources})
set_target_properties(<driver name> PROPERTIES LINKER_LANGUAGE C)
install(TARGETS <driver name> LIBRARY DESTINATION ${CMAKE_SOURCE_DIR}/build ARCHIVE DESTINATION
${CMAKE_INSTALL_LIBDIR})

A typical CMakeLists.txt file for the CSUDMA driver looks as shown in the following snippet:


# SPDX-License-Identifier: MIT
cmake_minimum_required(VERSION 3.15)
project(csudma)
find_package(common)
collector_create (PROJECT_LIB_HEADERS "${CMAKE_CURRENT_SOURCE_DIR}")
collector_create (PROJECT_LIB_SOURCES "${CMAKE_CURRENT_SOURCE_DIR}")
include_directories(${CMAKE_BINARY_DIR}/include)
collect (PROJECT_LIB_SOURCES xcsudma.c)
collect (PROJECT_LIB_HEADERS xcsudma_hw.h)
collect (PROJECT_LIB_HEADERS xpmcdma.h)
collect (PROJECT_LIB_SOURCES xcsudma_sinit.c)
collect (PROJECT_LIB_SOURCES xcsudma_selftest.c)
collect (PROJECT_LIB_HEADERS xcsudma.h)
collect (PROJECT_LIB_SOURCES xcsudma_g.c)
collect (PROJECT_LIB_SOURCES xcsudma_intr.c)
collector_list (_sources PROJECT_LIB_SOURCES)
collector_list (_headers PROJECT_LIB_HEADERS)
file(COPY ${_headers} DESTINATION ${CMAKE_BINARY_DIR}/include)
add_library(csudma STATIC ${_sources})
set_target_properties(csudma PROPERTIES LINKER_LANGUAGE C)

Changes in Existing Source Files (.c and .h)

AMD drivers have to be generic and the driver sources should not include platform specific configuration details through xparameters.h. The existing embeddedsw driver uses an AMD proprietary parameter called DeviceId in the driver config structure. Because the system device is designed to be fully open source, it no longer uses DeviceId and instead uses BaseAddress.

Note: If you are creating a new driver, use BaseAddress. If you are porting an old driver to the new system device tree based flow, changes are needed to support both the legacy (DeviceId) and new (BaseAddress) flows.

A char * (for name) in the driver *_Config structure has to be used to support the system device tree based flow. This can also be used later for differentiating between different versions of IP in the driver.

This leads to the following changes in source files:

typedef struct {
+#ifndef SDT
        u16 DeviceId;           /**< DeviceId is the unique ID of the
                                  *  device */
+#else
+       char *Name;             /**< Unique name of the device */
+#endif
        UINTPTR BaseAddress;    /**< BaseAddress is the physical base address
                                  *  of the device's registers */
################################################################################
# Changes in *_sinit.c file
################################################################################
 
+#ifndef SDT
 X<Driver>_Config *X<Driver>_LookupConfig(u16 DeviceId);
+#else
+X<Driver>_Config *X<Driver>_LookupConfig(UINTPTR BaseAddress);
+#endif
 
+#ifndef SDT
 #include "xparameters.h"
+#endif
  
 /************************** Constant Definitions *****************************/
  
@@ -65,6 +67,7 @@
 *
 * @note                None.
 ******************************************************************************/
+#ifndef SDT  
X<Driver>_Config *X<Driver>_LookupConfig(u16 DeviceId)
 {
      /* Legacy code */
 }
+#else
+X<Driver>_Config *X<Driver>_LookupConfig(UINTPTR BaseAddress)
+{
+       X<Driver>_Config *CfgPtr = NULL;
+       u32 Index;
+
+       /* Checks all the instances */
+       for (Index = (u32)0x0; X<Driver>_ConfigTable[Index].Name != NULL; Index++) {
+               if ((X<Driver>_ConfigTable[Index].BaseAddress == BaseAddress) ||
+                    !BaseAddress) {
+                       CfgPtr = &X<Driver>_ConfigTable[Index];
+                       break;
+               }
+       }
+
+       return CfgPtr;
+}
+#endif

Example Changes in the CSUDMA Driver

The following code is provided as a sample:

+#ifndef SDT
 extern XCsuDma_Config XCsuDma_ConfigTable[XPAR_XCSUDMA_NUM_INSTANCES];
+#else
+extern XCsuDma_Config XCsuDma_ConfigTable[];
+#endif
  
+#ifndef SDT
 XCsuDma_Config *XCsuDma_LookupConfig(u16 DeviceId);
+#else
+XCsuDma_Config *XCsuDma_LookupConfig(UINTPTR BaseAddress);
+#endif
 
 
+#ifndef SDT
 #include "xparameters.h"
+#endif
  
 /************************** Constant Definitions *****************************/
  
@@ -65,6 +67,7 @@
 *
 * @note                None.
 ******************************************************************************/
+#ifndef SDT
 XCsuDma_Config *XCsuDma_LookupConfig(u16 DeviceId)
 {
        XCsuDma_Config *CfgPtr = NULL;
@@ -81,4 +84,22 @@ XCsuDma_Config *XCsuDma_LookupConfig(u16 DeviceId)
  
        return (XCsuDma_Config *)CfgPtr;
 }
+#else
+XCsuDma_Config *XCsuDma_LookupConfig(UINTPTR BaseAddress)
+{
+       XCsuDma_Config *CfgPtr = NULL;
+       u32 Index;
+
+       /* Checks all the instances */
+       for (Index = (u32)0x0; XCsuDma_ConfigTable[Index].Name != NULL; Index++) {
+               if ((XCsuDma_ConfigTable[Index].BaseAddress == BaseAddress) ||
+                    !BaseAddress) {
+                       CfgPtr = &XCsuDma_ConfigTable[Index];
+                       break;
+               }
+       }
+
+       return (XCsuDma_Config *)CfgPtr;
+}
+#endif