Documentation on driver development for FlashLink products

Online repository with the required software

All the required software is available at this address: https://cloud.siliflash.com/index.php/s/jZd3JbPnkrMYFjM. All the source code of the drivers is managed using GIT and stored on BitBucket.com servers.

Linux configuration (example for ubuntu or derived distribution)

If you are using the FlashLink Virtual Machine you can skip this part

After Linux OS installation you need to install required package for software development:

sudo apt install build-essential cmake libgl1-mesa-dev
sudo apt install mysql-common
sudo apt install gawk net-tools autoconf libtool texinfo zlib1g zlib1g-dev gcc-multilib  libncurses5-dev libncursesw5-dev

You also need to install Qt open source edition, the installer is available at https://d13lb3tujbc8s0.cloudfront.net/onlineinstallers/qt-unified-linux-x64-4.6.1-online.run. You need to install Qt 5.12.5

Note: Qt require the creation of an account to be able to use the installer.

For the eclipse IDE you need the CDT version that can be dowloaded from: https://www.eclipse.org/downloads/packages

Configuration for various platform

At the moment, FlashLink has two different hardware products that require different drivers to function. The architecture of the software is designed so that the same source code for the driver is used for both platforms, but the software configurations are different, and the compilers used are also different.

The two hardware products are:

  • FN-H4 - The hardware is the same used by NovaFlash with a new OS installed
  • FL1-12 - The new hardware designed for FlashLink

Moreover FlashLink could give support to the old programmer sold by NovaFlash. For this platform the driver source code is not compatible with the one used by FlashLink products and it's not delivered. The develop of NovaFlash product is freezed at the last OS release 1.0.13 and also the driver are not developed anymore.

The development of the drivers is done by using eclipse as the IDE to manage, build and debug. Each driver is a separate Eclipse project that builds a dynamic library and resides in its own directory. All the driver directories must reside in the same directory, where two symbolic links must be present to access the required include files. This two links with the default value are:

  • fn-inc -> ../Hypervisor/fn/Inc
  • gsoap -> ../Hypervisor/fn/gsoap

To import a driver project into eclipse use the menu File->Import, then select General->Existing Projects into Workspace and then just select the root directory of the driver source code.

For the complete project configuration inside eclipse see FlashLink Eclipse Driver Config

All the driver projects are configured to use the environment variable ${CC} as compiler, so it's necessary to set the right environment before running Eclipse in order to be able to compile. To do so you must use the shell command source <sdk> on the shell before to launch eclipse from the same shell, where <sdk> is the path to the shell script installed with the SDK. There is a specific SDK for FL1-12 and a different one for FN-H4.

To compile the driver, you first need to source the correct SDK and then, from the same shell, launch the Eclipse IDE. For example, for the FN-H4 SDK, enter the following two commands in a shell (the paths in this example correspond to those used in the provided VM):

source /opt/fn-sdk/environment-setup-armv7at2hf-neon-angstrom-linux-gnueabi
/opt/eclipse/eclipse &

To compile a driver for FL-12 platform use the following command to launch eclipse

source /opt/fl-sdk/environment-setup-cortexa9t2hf-neon-xilinx-linux-gnueabi
/opt/eclipse/eclipse &

The Hypervisor source file inside the include directory for the 2 platform come from the same source, but one file need to be changed to reflect the correct platform, otherwise you could get some strange error on runtime. The file to be changed is hwDef.h. Inside this file you need to change the lines:

#ifndef HW_TYPE
# define HW_TYPE HWT_FL1_12
#endif
#ifndef BRAND
# define BRAND BRAND_IFLASH
#endif

The correct configuration for FL-12 is:

#ifndef HW_TYPE
# define HW_TYPE HWT_FL1_12
#endif
#ifndef BRAND
# define BRAND BRAND_FL
#endif

The correct configuration for FN-H4 is:

#ifndef HW_TYPE
# define HW_TYPE HWT_LEGACY
#endif
#ifndef BRAND
# define BRAND BRAND_IFREE
#endif

Best Practices

The best practice for developing on the two platforms is to create two separate environments in different directories, one for each platform. The source code of the two environments can be synchronized using Git.

Working with the VM

A VMware Virtual Machine is already configured for developing and debugging the drivers. The VM is based on Kubuntu 22.04 LTS.

User

On the VM, the configured user is flashlink, and the password is flashlink1. This user is configured with sudo rights, allowing you to use it to update the system and install necessary packages.

SDK and IDE

On the VM the eclipse IDE and the required SDK are already installed.

  • Eclipse: installed in the path /opt/eclipse. The executable is /opt/eclipse/eclipse
  • SDK for FL1-12: installed in /opt/fl-sdk. The script to source is /opt/fl-sdk/environment-setup-cortexa9t2hf-neon-xilinx-linux-gnueabi
  • SDK fir FN-H4: installed in /opt/fn-sdk. The script to source is /opt/fn-sdk/environment-setup-armv7at2hf-neon-angstrom-linux-gnueabi

To easily launch Eclipse with the correct configuration, two scripts are available in the HOME directory:

  • The first is fl.sh that launches the IDE with the SDK for FL-12 platform
  • The second is fn.sh that launches the IDE with the SDK for FN-H4 platform

When starting Eclipse, it prompts for the workspace directory. You must select the appropriate workspace corresponding to the SDK in use, as follows:

  • For platform FL1-12 select /home/flashlink/work/FL1-12/eclipse-workspace
  • For platform FN-H4 select /home/flashlink/work/FN-H4/eclipse-workspace

Both workspaces are already configured with all the drivers project loaded.

Source files an projects

All the required source files are located in the ~/FlashLink/work directory. Inside, there are two subdirectories:

  • FL1-12: configured to work for platform FL1-12
  • FN-H4: configured to work for platform FN-H4

For the complete directory structure see FlashLink Eclipse Driver Config.

Source control BitBucket

Source versioning is managed using Git, and the repositories are hosted on BitBucket.com. To access the driver repository, first create an account on BitBucket.com. Then, send an email to roland@eflashlink.com including your BitBucket account username and email, requesting access to the driver you are working on.

In order to be able to perform git push to BitBucket.com you need to add your ssh key to your account on BitBucket.com. On the virtual machine the user flashlink doesn't have any ssh key configured. you can create a new key using the command ssh-keygen (Just launch the command and press enter at all the prompts.)

To add support for a new device to a driver always create a branch from master and name it feature/<name> (where <name> is a descriptive name for your work). Once you have completed and tested your work, push the branch to BitBucket and create a pull request. You can do this via the BitBucket.com web interface or your preferred Git client.

Drivers files structure

The complete files structure is documented in the FlashLink Eclipse Driver Config document.

Inside a driver directory, you will find all the source code for the driver, along with several subdirectories:

Res

This directory contains the FPGA configuration and the uKernels (in binary form) used by the driver.

Also in this directory there is the file DevData.xml with the info on all the devices supported by the driver. This file is generated using the following command:

exportDB <driverName> DevData.xml

where <driverName> must be the name of the driver as saved on the DB. (for info on the DB ses the docs: FlashLink Db Structure.pdf)

uKernels

This directory contains the source code needed to compile the uKernels required by the driver. It is good practice to also include information about the tools and configurations used for compiling the driver, as well as any details that might be helpful for someone who needs to recompile the uKernel in the future. The compiled uKernel must be copied into the Res directory. The uKernel directory is tracked in Git, but the compiled files should be excluded by adding them to the .gitignore file in the driver's main directory.

docs

This directory is intended to contain the documentation related to the driver and the supported devices by it. It includes a file named readme.md with information useful for driver development. It is important to document the meaning of the generic fields in the database used by the driver. Additionally, include any information that may be helpful for future developers working on the driver.

Inside the subdirectory ds we put all the datasheet and reference manuals for the microcontrollers supported by the driver so that any future developer can find them quickly. All the document shuold reachable from the file datahseets.md

Note: It is important to store all documentation related to communication with the microcontroller, the use of the debug interface, and the programming of various types of memory here. Often, this information is not found in the Datasheet or Reference Manual, but in specific documents or application notes, and may sometimes need to be requested from the silicon producer. Moreover, save any other files or utilities used during development that were obtained through direct request or other means, and are not freely available for download on the Silicon Producer's website.

All the documentation is written using the MarkDown format. See https://en.wikipedia.org/wiki/Markdown.

To understand the internal structure of a driver see FlashLink Driver Structure.pdf

Driver Debug

Eclipse on the VM is already configured to debug the drivers on the FlashLink hardware. To debug, first switch to the Debug Perspective using the toolbar button in the upper right corner, and then click on the debug icon in the top toolbar.

At this point on the Debug view (On the left of the window) you see an entry fl1-12 Debug [C/C++ Attach to Application], this is the debug session just started. Right-Click on this entry and select the Connect... menu entry to open a Dialog with all the process running on the programmer. Write flash on the text entry field, select the flash process on the list and click OK.

At this point, Eclipse will connect to the process on the programmer and stop it, allowing you to debug it.