Using STWorkbench with STLinux Building and debugging STFAE using STWorkbench

The STFAE source tree is a version of the STAPI tree used by ST FAEs, application groups and customers.

Import the kernel and tree into STWorkbench

To work with STFAE for STLinux, two projects have to be created - the STLinux kernel and the STFAE tree. Contact your FAE for details on how to get these two trees.

1. On the command line, unzip both tarballs into the directories in which they are to be built.

2. Before starting STWorkbench, edit the file bin/setenv.sh as appropriate (please refer to the STFAE documentation downloaded in the tarball for details), and source it to set up the environment. For example, if you are using an MB411 board containing an STb7100 you would use the command source setenv.sh MB411_7100_LINUX. This sets up the environment for the build which is inherited when STWorkbench is started.

3. Start STWorkbench.

4. Import the kernel as an STLinux Kernel project, taking care to uncheck Build (Incremental build) and Clean in the Advanced settings... > C/C++ Build > Behaviour dialog. This will stop STWorkbench attempting to build the kernel, which is built by the STFAE build system.

5. Import the STFAE tree. To do this, create a new C Project project and on the first page of the wizard, uncheck Use default location and specify the project directory to instead be the top-level directory of the source tree. Your tree is not copied, or altered. The only change is that a number of small hidden files (dotfiles) are placed in the top level of the tree.

   Note: this is the recommended way of importing any large development tree into STWorkbench.

6. Select Makefile Project and the ST40 Linux GCC Toolchain.



7. Click Next and then Advanced settings....

8. In the C/C++ Build section, set the Build command to "gmake -C stapp":



This builds the test application each time a file is saved, which is quite quick. To build the driver tree also, change the build targets from all to apilib all in the Behaviour tab.

Note: the apilib build is slow, even when nothing has changed. The build speed is due to the underlying STAPI Make system, not STWorkbench.

9. Click Finish to create the project. The project settings are always available from Project > Properties.

10. Use the Make Targets view to add make targets for gmake kernel, gmake apilib and gmake all. These targets can be invoked by the user at any time, but are not used by Project > Build Project.

11. To fully build the tree, execute a gmake kernel to build the kernel, a gmake apilib to build the STAPI drivers and a gmake all to build the test application and copy everything to the target filesystem. Once this has been done it is only necessary to rebuild the sections of the tree that have been edited.

Booting the kernel

The kernel can be booted using the normal STWorkbench mechanism. However, there is one complication. The "Board Type" field requires that a gdb connect procedure is defined for the board you wish to use which only connects to the board, without downloading an application. The standard connect procedures supplied with the ST toolsets for ST-designed boards are suitable, and can be used directly.

To use a board for which no such procedure exists (the connection scripts provided in the STFAE tree are not currently suitable), the following workaround is needed.

In this example, we wrap the STFAE connection scripts with a gdb procedure of the required form. Throughout, <board> should be replaced with a board type (e.g. "mb411"), and <soc> should be replaced by an soc type (e.g. "7100").

Step 1: Create the <board>_<soc>_start_file.cmd script, using make:

 % cd stapp
 % source ../bin/setenv.sh <STFAE_CONFIG>
 % make build_start_script_run_main_st40

Step 2: Extract the main connect line from that file.

 % cat platform/<board>/<soc>/<board>_<soc>_start_file.cmd | grep inicommand
<board>_ip 164.129.14.184 "-inicommand <board>_bypass_setup"

Step 3: Add the following new connect procedures to the .shgdbinit file in your home directory:

define start_<board>_<soc>
end

define <board>_stfae
	shell echo > /tmp/mb411_7100_start_file.cmd
        directory /tmp /tmp/STFAE/stapp/platform/<board>/<soc>
        source <board>_<soc>_start_script.cmd
        <board>_ip $arg0 "-inicommand <board>_bypass_setup"
end

Note: The final line of the procedure should be the connect line extracted in step 2, but with the second field changed from an IP address to "$arg0".

Step 4: Test it!

You should then be able to connect to the board successfully with the new procedure:

(gdb) <board>_stfae 164.129.14.184
The target is assumed to be little endian
The target architecture is assumed to be sh4
$tmcIDCODE_n = 32
$tmcIDCODE_0 = 0x00000000
$tmcIDCODE_0 = 00000000000000000000000000000000
0xa0000000 in ?? ()
7100 Cut C.1 detected
Clock settings:

  CLOCKGENA_PLL0_CFG       = 0x00083b06
  CLOCKGENA_PLL0_CLK1_CTRL = 0x00000000
  CLOCKGENA_PLL0_CLK2_CTRL = 0x00000001
  CLOCKGENA_PLL0_CLK3_CTRL = 0x00000000
  CLOCKGENA_PLL0_CLK4_CTRL = 0x00000000
  CLOCKGENA_PLL1_CFG       = 0x0008c81b

Clock frequencies

  PLL0      = 531.0 MHz
  PLL1      = 400.0 MHz
  ST40 CPU  = 265.5 MHz
  ST40 BUS  = 132.8 MHz
  ST40 PER  = 66.4 MHz
  ST231 CPU = 400.0 MHz
  SLIM CPU  = 265.5 MHz
  ST BUS    = 200.0 MHz
  EMI       = 100.0 MHz
  LMI       = 200.0 MHz
(gdb)

The procedure "<board>_setup" can now be used in the "Board Type" field in STWorkbench.

You can view the kernel boot as normal from an embedded kermit instance. From this terminal, you can run the load_*.sh scripts and the test application.

Edit, rebuild and launch a test application

Editing, rebuilding and navigating the test applications uses standard Eclipse/STWorkbench mechanisms. You can boot the kernel using the standard STWorkbench launch configuration.

Set up running load_modules.sh as an external tool where /usr/bin/ssh is the external tool, with the following arguments.

root@target source ~/modules/load_modules.sh

For more information see Running external tools in the STWorkbench user guide online help.

To set up the environment when launching through kermit, run load_env.sh in the terminal where the test application is started.

To set up the environment when launching through STWorkbench, insert the line source /root/modules/load_env.sh into the file ~/.stworkbenchrc on the target before launch and debug. This file is sourced in the new terminal that STWorkbench creates to launch the application.

Edit, rebuild and and use one of the drivers

When the source for the STAPI drivers has changed, you can rebuild the kernel modules using the Make Targets view. The kernel modules can also be rebuilt using Build Automatically or Build Project but it can be slow if there is nothing to rebuild, so some users may prefer to invoke the build only after a long set of changes.

Once built, the Make system copies the kernel modules to the target and they are used by the next boot of the kernel.

Debug a test application

The test application is named for example main_mb411_7100.out. To debug the test application using gdbserver, follow the usual steps for debugging a usermode application. No additional options are required but on the Debugger tab, remember to set the correct path to the target root filesystem.

By default the output from the test application goes to the STWorkbench Console view. This does not support all the advanced terminal features of STAPI TestTool (in particular tab completion), so in the Main tab you may wish to uncheck the Connect process I/O to an STWorkbench console option. STWorkbench then launches an rxvt terminal on the target and launches the test application within it. This terminal does support tab completion. However, you may need to check that the settings of your X server allow the target board to display X applications on your host. This is often not the default.

Debug a Driver

To debug the drivers you must debug the kernel itself. Each of the STAPI drivers is implemented as a kernel module.

1. Build the kernel with debug info. The STFAE tree overwrites any changes to the kernel configuration if you use gmake kernel.

2. Boot the kernel with a debugger attached, using a launch configuration of the type STLinux Kernel. The only additions required for STFAE are:

• to add the correct values in the Memory for the mem= and bigphysarea= kernel parameters,

• to add the path to the kernel modules to the Directories containing the kernel modules table in the Debugger tab. This corresponds to the gdb internal variable search-path, also known as module-search-path,

• to add the STFAE project to the list of contributing projects in the Source tab. This tells STWorkbench that when it hits breakpoints while debugging the kernel project, the source for the breakpoint may be in the STFAE project.

For further details on debugging the kernel and kernel modules see:

• Building an STLinux kernel,
• Debugging an STLinux kernel,
• Managing kernel modules.

You can simultaneously debug the kernel-level drivers, and the test application that uses those drivers.