1. Introduction
Altera® (Intel®) SoC FPGAs (hereinafter "SoC FPGAs") provide a library called the Hardware Library (hereinafter "HWLib") for easy use of peripherals in the Hard Processor System (hereinafter "HPS") from software programs. Users can simplify the design by using the required HWLib.
This article explains how to add HWLibs via Makefile.
2. What is HWLib?
HWLib is a library that simplifies the use of HPS peripherals.
HWLib consists of two components a SoC abstraction layer (hereinafter "SoCAL") and a hardware manager (hereinafter "HWMgr").
SoCAL:
A macro-based abstraction layer (header file) for accessing HPS peripherals.
HWMgr:
A collection of APIs in C and assembly language to access HPS peripherals, including source files defining the APIs and header files to be included when using the APIs.
The source/header files provided as HWLib are stored in the following location
<SoC EDS installation directory>/ip/altera/hps/altera_hps/hwlib
SoCAL is a layer for hardware abstraction, but SoCAL is also used in the implementation of HWMgr. HWMgr is a collection of APIs for accessing HPS peripherals, so it is positioned as a higher layer than SoCAL.
Therefore, the image is as shown below.
[Figure 1] Positioning of HWLib
The user includes the necessary header files and uses the SoCAL definitions and HWMgr API.
NOTES:
Since SoCAL and HWMgr have header files with the same name, when including SoCAL header files, it is necessary to distinguish them by including the path to the socal directory, such as #include "socal/xxx.h".
3. Documentation of HWLib
HWLib documentation can be found in the following ways.
3-1. Referring from the SoC Embedded Design Suite (SoC EDS) installation directory
Documentation is available in the following directories.
SoCAL Documentation:
<SoC EDS installation directory>/ip/altera/hps/altera_hps/doc/socal/html/index.html
HWMgr documentation:
<SoC EDS installation directory>/ip/altera/hps/altera_hps/doc/hwmgr/html/index.html
3-2. Reference from Windows start menu
Refer to the figure below to select SoC EDS HWLIBs Cyclone V Arria V Documentation (or SoC EDS HWLIB Arria 10 Documentation for Arria® 10) to browse the document.
[Figure 2] Refer to the documentation from the Windows start menu
4. How to add HWLib by Makefile
It is recommended to copy the HWLib source code under the directory directly under the software project, because unintentional modification of the original code may occur if the source code of HWLib is not copied and directly referenced.
You may copy it manually on Windows Explorer, but many reference designs add HWLib in the Makefile.
When developing based on such reference designs, it is convenient to add HWLib in the Makefile.
For reference, the following reference design included with SoC EDS shows where the HWLib to be added can be found in the Makefile (Figure 2).
<SoC EDS installation directory>/example/software/Altera-SoCFPGA-HardwareLib-Timer-CV-GNU.tar.gz
NOTES:
The structure of the Makefile may vary depending on the version of SoC EDS and the type of reference design.
[Figure 3] Excerpt from the Makefile
This reference design specifies the HWLibs to be added to HWLIBS_SRC. The files specified in HWLIBS_SRC will be copied under the software project at build time (Source files for user applications that do not require copying are added to EXAMPLE_SRC).
It is useful to keep in mind that many of the reference designs are configured to be added to HWLIBS_SRC in this way.
5. Sample introduction
As mentioned in chapter 4, to use HWLib, it is necessary to add it on Explorer or in the Makefile, which is a bit time-consuming.
In the sample shown below, all the source code provided as HWLib is already registered, and all the APIs can be used by including the HWLib header file you want to use.
Please use this sample as a very useful starting point when building bare-metal applications.
SoC FPGA Bare Metal All-in-One Application Sample