Using the Target Filesystem Editor

The Target Filesystem Editor is a tool to assist embedded Linux developers to construct a smaller target filesystem, suitable to be written into on-board flash in a production system.

Constructing a consistent filesystem manually, with all internal dependencies resolved, is both time-consuming and error-prone. The Target Filesystem Editor allows users to select files from the complete STLinux filesystem (which is far too large for inclusion in a production system) and transfer them to into the user's own filesystem. It automatically resolves all shared library dependencies, and optionally prompts the user with all the other files provided in the same RPM package, allowing easy identification of required config files, documentation, and so forth.

The resulting filesystem can be exported as a definition in a text file, or in a variety of popular filesystem formats, including initrd, JFFS2, CRAMFS and UBIFS.

The Target Filesystem Editor is supplied with STLinux 2.4. It is invoked from /opt/STM/STLinux-2.4/host/bin/targetfseditor.

Usage

When you load the Target Filesystem Editor you are presented with the interface shown in the screenshot below. By default, the root directory is /opt/STM/STLinux-2.4/devkit/sh4/target (although an alternative path can be specified on the targetfseditor command line, if required). The root directory can also be changed with the option (File -> Change Root).

On the left is the selected directory with all the files and folders that it contains. By default hidden files (.name files) are not shown but they can be turned on by selecting the check-box. An area at the bottom of the pane shows information about the file or folder currently selected.

On the right is the directory of the filesystem you are creating. This is initially blank, but folders and files can be added by moving items from one side to the other using either the buttons or the hotkeys. Again, an area at the bottom of the pane displays information about selected items within this pane.

In the centre are the buttons and options that allow you to manipulate and create your desired filesystem.

Screenshot of the program's interface

Buttons

(file and folder are interchangeable for these descriptions)

> Add
Hotkey: Ctrl + D
Moves the file you have selected in the left hand pane into the right hand pane, also moving all it's shared library dependencies as well (calculated using "ldd"). If 'Include RPM files' is selected then all the files contained in the same RPM package are also moved. Optionally, the application will prompt with a list of those files, allowing a subset to be selected.

Prompt when trying to move a folder across

< Remove
Hotkey: Ctrl + S
Removes the file you have selected in the right hand pane from the directory. This command ONLY moves the selected file, all dependencies and RPM files remain.

<< Remove All
Hotkey: Ctrl + Z
Clears the right hand pane, removing all the files. This is essentially the same as 'New' (Ctrl + N) from the 'File' menu bar and allows you to start over.

Prompt when trying to remove all files

Import
Hotkey: Ctrl + Q
Allows you to import a ramfs.txt file, automatically generating the correct right hand pane. This process checks all the dependencies and will alert you to any missing files, dependencies, as well as report any updated symbolic links.

Example RAMFS.txt file that you can import/export

Example import report

Export
Hotkey: Ctrl + E
Displays the output wizard allowing you to export your generated filesystem. See below for more information ('How to Export').

Show hidden files
Displays all the hidden files in the left hand pane (.name files) that are not shown by default on the system.

Example interface with hidden files shown

Move RPM files
When selected, any files that you move across will automatically move the rest of the files from the same RPM package over as well.

Prompt RPM files
Adds a confirmation window when you move files, giving a list of all the files in the same RPM with check boxes for you to select or deselect which package files you would like to move across.

Example RPM prompt

How to Export

Once you have designed your desired filesystem you can begin the export process. Upon clicking the centre 'Export' button or pressing 'Ctrl + E' the following interface will appear;

Output Wizard

In total there are 5 different ways to export your generated filesystem:

RAMFS.txt

text representation of your desired filesystem, used for creating an initrd ramdisk and can be imported to automatically generate the saved filesystem.

INITRD

initrd file that is created from a RAMFS.txt file. Extra arguments are not needed, however you need to specify a ramdisk size. This output type is harder to generate than the rest and errors are more likely to appear in a dialog window.

CRAMFS

image file that is created based on a folder and is ready to be copied into flash. Again, a blocksize must be provided, and optionally you can add extra arguments that will be passed to the underlying image creation tool.

JFFS2

image file that is created based on a folder and is ready to be copied into flash. Note that the eraseblock size is dependent on the flash chip you will be using, and must be supplied. Eraseblock size can be found in /proc/mtd on the target system. Optionally you can add extra arguments that will be passed to the underlying image creation tool.

UBIFS

image file that is created based on a folder, but which requires further processing before it can be copied to flash. You need to provide an eraseblock size and the extra arguments provides are not optional, however you can add more.

If you do not select 'Delete temporary files' then the folders and .txt file will remain after your image file has been created.

Note: If you are not root you will receive an error and UBIFS, CRAMFS and JFFS2 will not export correctly. This is due to permission errors when trying to copy files into the temporary folder, or create device nodes.

Incorrect User Warning

Note: Creating a working filesystem requires device nodes to be created in the temporary folder. Some filesystems (for example some home directories) may forbid this, so the temporary folder should be placed in a filesystem that allows device node creation.

About

SPEAr1340 Android hardware pack

Android hardware pack are proprietary libraries for STMicroelectronics SPEAr eMPUs (SPEAr1340).
The complete Android package can be found on http://code.google.com/p/floid/

To obtain the SPEAr1340 Android hardware pack read carefully the license agreement, then proceed with the steps outlined in the "Procedure" section.

Section 1: License

LIMITED LICENSE AGREEMENT FOR ST MATERIALS

IMPORTANT-READ CAREFULLY: This Limited License Agreement ("LLA") is made between you (either an individual person or a single legal entity, who will be referred to in this LLA as "You" or “Licensee”) and STMicroelectronics International NV, a company incorporated under the laws of Switzerland acting for the purpose of this LLA through its Swiss branch (hereinafter “ST”) for the software licensed materials that accompany this LLA, including any associated media, printed materials and electronic documentation (the "Licensed Materials"). The Licensed Materials include any software updates and supplements, that ST may provide You or make available to You after the date You obtain the Licensed Materials to the extent that such items are not accompanied by a separate license agreement or terms of use. By installing, copying, downloading, accessing or otherwise using the Licensed Materials, You agree to be bound by the terms of this LLA. If You do not agree with any and all the terms of this LLA, do not install, access or use the Licensed Materials; in such event return the Licensed Materials (as applicable) to ST or the authorized provider as applicable.

1. LIMITED LICENSE

Subject to the terms and conditions of this LLA and applicable Open Source Terms (as defined hereafter) and during the term of this LLA, ST hereby grants You a non-exclusive, non-transferable, paid-up, copyright license, without the right to sub-license (except as expressly stipulated herein), to use and reproduce the Licensed Materials in object code solely and exclusively with ST chipsets or integrated circuits (“ST Chipsets”) for incorporation in a Licensee Product (as defined hereinafter) and subsequent distribution directly or indirectly of said Licensee Product embedding Licensed Materials (“Limited License Purpose”).

Subject to the terms and conditions of this LLA, You will be authorized to sub-license the Licensed Materials solely as part of your software or hardware application (“Licensee Product”) and not as a stand-alone product, solely in executable code and only for use in conjunction with ST Chipsets as embedded in the Licensee Product ultimately by end user. You will enter into an agreement with your customer under terms and conditions no less stringent as the terms of this LLA. Upon request, You shall provide all requested contact information of your customers to ST.

Subject to the terms and conditions of this LLA, ST hereby grants You a non-exclusive, non-transferable, personal, paid-up, copyright license, to use internally the Licensed Materials made available as comments, annotations, instructions, manuals, and other written materials, whether in printed or electronic form, including without limitation installation manuals, user’s guides, and programmer guides (“Documentation”) only within Licensee's organization, solely to support and exercise the rights granted under this article 1, without the right to sub-license or distribute totally or partially such Documentation.

You acknowledge that the Licensed Materials has not been specifically designed to meet Your individual requirements and that You have all information necessary to evaluate whether the Licensed Materials meets your requirements and any software item substantially complies with the Documentation. Therefore the Licensed Materials shall be deemed accepted upon delivery to Licensee. You shall use, at your own risk, the Licensed Materials and any development that is obtained from such use. You acknowledge that ST cannot in any way be held responsible for the consequences resulting from use of the Licensed Materials and any development made following such use of the Licensed Materials. Notwithstanding anything to the contrary herein, You are not authorized to sublicense to or have used the Licensed Materials by a competitor of ST.

You acknowledge that the Licensed Materials are being provided under license and that you are receiving the Licensed Materials under license and not as a purchaser of the Licensed Materials.

2. RESTRICTIONS

Unless otherwise expressly stipulated under Article 1, You shall not, and shall not permit any third party to: (i) copy, reproduce or duplicate the Licensed Materials; (ii) translate, modify, adapt, decompile, disassemble or reverse engineer and make derivative works of (any portion of) the Licensed Materials; (iii) rent, disclose, publish, sell, assign, lease, lend, sublicense, market, transfer, distribute or otherwise provide third parties access to (any portion of) the Licensed Materials for any purpose; (iv) attempt to derive the source code, algorithmic nature or structure of any object code portions of the Licensed Materials; (v) use the Licensed Materials to create any product that competes with the Licensed Materials; (vi) remove or circumvent any protection or other restrictive technology mechanism of the Licensed Materials or ST Chipsets; (vii) disclose the results of the Licensed Materials’ performance benchmarks to any third party; or (viii) otherwise use (any portion of) the Licensed Materials in any manner not expressly authorized by this LLA.

Other than the limited expressed license granted to You under Article 1 herein, no other rights or licenses are granted, or implied by estoppel or otherwise, under any intellectual property rights of ST and/or its affiliated companies or any intellectual property of a third-party residing in the Licensed Materials or any other confidential information furnished by ST, including (i) for the combination of such Licensed Materials or other confidential information with one or more other items (including items acquired from ST and/or its affiliated companies) even if such items have no substantial use other than as part of such combination (ii) with respect to any trademark, trade or brand name, a corporate name of ST and/or its affiliated companies, or any other name or mark, or contraction abbreviation or simulation thereof, (iii) under any intellectual property rights covering any standard set by a standard setting body and any de facto standards.

ST has no obligation to provide You with maintenance, technical support or updates for the Licensed Materials.

3. OWNERSHIP

The Licensed Materials are and will remain the exclusive property of ST or its licensors, whether or not specifically recognized or perfected under the laws of the country where the Licensed Materials are located and used. You will not take any action that jeopardizes ST's or its licensors' proprietary rights or acquire any rights in the Licensed Materials, except the limited rights specified in Article 1 within the scope of the license granted herein.

4. CONFIDENTIALITY

The Licensed Materials include confidential and proprietary information and materials and may include trade secrets. You may only use the Licensed Materials for the Limited License Purpose and shall take necessary precautions to maintain the confidentiality of the Licensed Materials provided by ST under this LLA. You shall not disclose, provide or make available the Licensed Materials and/or part thereof, including copies, to any person other than your employees who have a need to know for the Limited License Purpose, and, for the avoidance of any doubt, only as long as such employee is employed by You. You shall not remove any proprietary, copyright, trade secret and warning legends from the Licensed Materials and/or parts thereof, and You shall reproduce, without any amendment or change thereto, any proprietary rights legend and marking of ST or its third party suppliers in any Licensed Materials provided by ST.

ST has made substantial investment in the development of the Licensed Materials. The Licensed Materials and any and all parts thereof are of utmost confidential and importance to ST. Any disclosure thereof by You to unauthorized persons and/or any use of the Licensed Materials and/or parts thereof in conflict with the terms and conditions of this LLA may create substantial and irreparable harm to ST.

All employees having access to the Licensed Materials have undertaken confidentiality obligations on terms no less onerous than (i) your internal confidentiality policies as regards your own information and products of like sensitivity and importance and (ii) the terms of this LLA, and that such confidentiality terms include an obligation to maintain confidentiality also after termination or expiry of the employment with You. You are liable towards ST for any damages incurred due to a failure by any employee or customer having access to the Licensed Materials to comply with the provisions in this LLA. You further commit to record and account for all copies of the Licensed Materials and to record the names of employees and customers having access to the Licensed Materials. Such information will be provided to ST at any time upon ST’s request.

You shall immediately notify ST of any unauthorised use or disclosure of, or of any unauthorised access to, or of any theft or loss of any copies of the Licensed Materials or part thereof, which comes to your notice.

Notwithstanding this Article 4, You shall not be prevented to disclose the Licensed Materials or parts thereof if (i) such disclosure is in response to a valid order of a court or any other governmental body having jurisdiction over this LLA or (ii) such disclosure is otherwise required by law, provided that You, to the extent possible, have given prior written notice to ST to allow it to seek protective or other court orders, and provided that You have made all reasonable efforts to protect the Licensed Materials and any and all parts thereof in connection with such disclosure.

These confidentiality obligations shall survive any termination or expiration of the LLA for whatever cause. You will have no confidentiality obligation with respect to any portion of the Licensed Materials that became available to the public other than as a result of Your act or omission.

5. DISCLAIMER OF WARRANTY

YOU ACKNOWLEDGE THAT THE LICENSED MATERIALS AND ANY AND ALL PARTS THEREOF ARE PROVIDED “AS IS”. ST MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE LICENSED MATERIALS AND OR PARTS THEREOF WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. SPECIFICALLY, WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, ST MAKES NO REPRESENTATION OR WARRANTY THAT (I) THE USE AND DISTRIBUTION OF THE LICENSED MATERIALS AND OR PARTS THEREOF WILL BE UNINTERRUPTED OR ERROR FREE, AND OR (II) ANY USE AND DISTRIBUTION OF THE LICENSED MATERIALS AND OR PARTS THEREOF, WHETHER INTEGRATED INTO OTHER EQUIPMENT OR NOT, ARE FREE FROM INFRINGEMENT OF ANY THIRD PARTY INTELLECTUAL PROPERTY RIGHTS. IT SHALL BE YOUR SOLE RESPONSIBILITY TO MAKE SUCH DETERMINATION AS NECESSARY WITH RESPECT TO THE ACQUISITION OF LICENSES UNDER PATENTS AND OTHER INTELLECTUAL PROPERTY RIGHTS OF THIRD PARTIES. CONSEQUENTLY, ST DISCLAIMS ANY LIABILITY IN CASE ANY SUCH USE and distribution INFRINGE ANY THIRD PARTY’S INTELLECTUAL PROPERTY RIGHTS. FURTHERMORE ST HEREBY DISCLAIMS ANY WARRANTY AND LIABILITY WHATSOEVER FOR ANY DEVELOPMENT CREATED BY OR FOR YOU and by or for your customers.

YOU acknowledge that you have relied on no warranties other than the express warranties in this lla and that no warranties are made by ST or granted by law whenever it is permitted by law.

6. EXPORT RESTRICTIONS

You acknowledge that the Licensed Materials are subject to export controls restrictions. In accordance with the applicable export control laws and regulations, You agree that You will not knowingly export, re-export Licensed Materials, directly or indirectly, to any country to the extent export to such country at the time of export requires an export license or other governmental approval under any export control laws and regulations, without first obtaining such license or approval.

7. OPEN SOURCE

Some portion of the Licensed Materials might contain Open Source Software. Such Open Source Software might be subject to Open Source Terms applicable for each such portion, as further specified in the Licensed Materials. Such Open Source Software is supplied to You solely under the applicable Open Source Terms and is not subject to the terms of this LLA to the extent the terms of this LLA are in conflict with such applicable Open Source Terms.

Except for Open Source Software, You agrees that You have no rights under this LLA to, and may not under any circumstances use the Licensed Materials, and/or any parts thereof such that they become subject to any Open Source Terms. These actions include but are not limited to combining the Licensed Materials by means of incorporation or linking or otherwise.

For the purpose of this LLA, “Open Source Terms” shall mean any open source license that complies with the Open Source Definition specified at www.opensource.org and any other comparable open source license such as for example GNU General Public License (GPL), Eclipse Public License (EPL), Apache Software License, BSD license and MIT license, and “Open Source Software” shall mean any software that is licensed or distributed under Open Source Terms as specified in the Licensed Materials.

8. COMPLIANCE

You agree not to use the Licensed Materials in violation of any law, statute, ordinance or other regulation or any obligation to which You are bound. You agree to comply with all applicable laws and regulations regarding the use of the Licensed Materials.

Some Licensed Materials may (i) require patent licenses from third parties claiming patent rights covering implementation of the Licensed Materials or (ii) be based on industry recognized standards or software programs published by industry recognized standards bodies and certain third parties may claim to own patents or copyrights that cover implementation of those standards. You acknowledge and agree that this LLA does not convey a license to any such third party patents and copyrights and that you are responsible for any fees or royalties that may be payable to any third party based on such third party's interests in the Licensed Materials. You agree to indemnify ST and to defend any claim, suit or proceeding brought against ST based on your failure to pay such third-party.

You have or will have all necessary licenses from third parties, which are required in order for You to execute the license rights granted by ST to You herein, without infringing such third parties intellectual property rights.

You shall be responsible for the due and proper compliance with the terms and conditions of this LLA by your customers and shall be jointly and severally liable to ST for any and all damages incurred by ST and its suppliers and licensors in connection with any such third-party’s non-compliance therewith. You shall enforce each agreement with your customer with at least the same degree of diligence that You use to enforce similar agreements for your own (software and/or hardware) products, but in no event with less than reasonable efforts. You shall immediately notify ST if You becomes aware of any material breach of any such agreement affecting the Licensed Materials.

9. COPYRIGHT AND TRADEMARKS.

All titles, trademarks and copyrights in and pertaining to the Licensed Materials, the accompanying printed materials, and any copies of the Licensed Materials, are owned or licensed by ST or its affiliated companies or suppliers. The Licensed Materials are protected by copyright and trademark laws and international treaty provisions. You shall ensure that such notice is reproduced in any copy of the whole or any part of the Licensed Materials. You shall not remove, modify or alter any ST copyright or trademark notice from any part of the Licensed Materials, including but not limited to any such notices contained in the physical and/or electronic media or documentation, in the ST ‘about’ boxes, in any of the runtime resources and/or in any web-presence or web-enabled notices, code or other embodiments originally contained in or otherwise created by the Licensed Materials.

10. DISCLAIMER OF DAMAGES

in no event shall ST and its affiliates shall be liable to the licensee and its customers for any indirect, incidental, punitive, special or consequential damages and lost profits or lost savings, loss of bargain or opportunity, professional fees or expenses, business interruption, lost revenues or sales, damage to associated product or equipment or to facilities, costs of substitute product, facilities or services, costs associated with down time, goodwill, loss of data and any similar or dissimilar losses, WHETHER FORESEEABLE OR UNFORESEEABLE AND whether or not such damages are based on warranty, contract or any other legal theory – even if licensee has been advised, or is aware, of the possibility of such damages ARISING FROM ANY USE AND OR DISTRIBUTION OF THE LICENSED MATERIALS AND OR PARTS THEREOF, WHETHER INTEGRATED INTO OTHER EQUIPMENT OR NOT, AND OR ARISING BY REASON OF THE FACT THAT THE LICENSED MATERIALS AND OR ANY PARTS THEREOF ARE DEFECTIVE OR NON-CONFORMING AND OR ARISING FROM THIS LLA. IN NO EVENT SHALL ST and its affiliates BE LIABLE FOR ANY DAMAGE, COSTS OR EXPENSES ASSOCIATED WITH WARRANTY OR INTELLECTUAL PROPERTY INFRINGEMENT CLAIMS WHETHER FOR THE REPLACEMENT OR REPAIR OF PRODUCTS, INCLUDING LABOR, INSTALLATION OR OTHER COSTS INCURRED BY LICENSEE AND, IN PARTICULAR, ANY COSTS RELATED TO THE REMOVAL OR REPLACEMENT OF ANY PRODUCTS SOLDERED OR OTHERWISE PERMANENTLY AFFIXED TO ANY PRINTED CIRCUIT BOARD, EXCESS PROCUREMENT COSTS, OR REWORK CHARGES. ST aggregate AND CUMULATIVE liability towards Licensee under THIS LLA shall not exceed 1000 USD.

The limitations set forth above in this ARTICLE 10 shall only apply to the MAXIMUM extent permitted by applicable law.

11. TERM AND TERMINATION

This LLA shall continue until terminated. You may terminate the LLA at any time by destroying all Licensed Materials and all related information or by returning those to ST. ST may terminate this LLA if (i) You fail to comply with the terms and conditions of this LLA, or (ii) You file litigation against ST or its affiliated companies, or (iii) to the extent permitted by laws, a voluntary or involuntary petition in bankruptcy or winding up is filed against Licensee, any proceedings in insolvency or bankruptcy are instituted against Licensee, a trustee or receiver is appointed over Licensee, or any assignment is made for the benefit of creditors of Licensee. Additionally, ST may at any time terminate this LLA, without cause, upon 3 months prior written notice to You. Upon termination you shall delete, destroy, or return to ST all Licensed Materials in your possession and You shall stop using the Licensed Materials for any purpose whatsoever.

The rights and obligations under Articles from 2 to 13 will survive the termination or expiration of this LLA.

12. MISCELLANEOUS

If a court or agency of competent jurisdiction holds any term of this LLA invalid, illegal, or unenforceable for any reason, the remainder of this LLA shall be valid and enforceable and You and ST shall negotiate in good faith a substitute, valid, enforceable provision which most nearly effects the parties intent in entering into this LLA.

The failure by ST to enforce any provisions of this LLA or to exercise any right in respect thereto shall not be construed as constituting a waiver of its rights thereof.

No agency, joint venture, partnership or other business organisation shall be created or be construed as being created by reason of this LLA. You will not have the right or authority to, and shall not, assume or create any obligation of any nature whatsoever on behalf of ST or bind ST in any respect whatsoever. You and ST are independent parties. Nothing in this LLA shall be construed as making You an employee, agent or legal representative of ST.

This LLA contains the entire agreement between You and ST on the subject matter of this LLA, and supersedes all representations, undertakings and agreements previously made between You and ST with respect to the subject matter of this LLA. Any amendment to this LLA shall be agreed in writing and be duly signed by You and ST and shall make reference to this LLA.

13. APPLICABLE LAW

This LLA is governed by the laws of Switzerland, without regard to its conflict of law rules. All disputes, differences or questions arising out of or in connection with this LLA shall be finally settled by the competent courts of Geneva, Switzerland. Notwithstanding the aforesaid, nothing in this LLA shall prevent You or ST from seeking any interim or final injunctive or equitable relief by a court of competent jurisdiction.

ST IS WILLING TO LICENSE THE LICENSED MATERIALS TO YOU ON THE CONDITION THAT YOU ACCEPT THE TERMS AND CONDITIONS OF THIS LLA. BY CLICKING ON THE "I ACCEPT" BUTTON OR BY ACCESSING, INSTALLING OR USING THE LICENSED MATERIALS, YOU AGREE TO BE BOUND BY ANY AND ALL THE TERMS OF THIS LLA. IF YOU DO NOT AGREE TO BE BOUND BY THE TERMS OF THIS LLA, THEN DO NOT PROCEED FURTHER AND/OR CLICK THE "I DO NOT ACCEPT" BUTTON BELOW AS APPLICABLE.

Section 2: Procedure

To receive the materials, you must send an email to spear-android-support@st.com with the following text:
”
I accept all terms and conditions listed in the "LIMITED LICENSE AGREEMENT FOR ST MATERIALS"
and I would like to receive the "SPEAr1340 Android hardware pack" SW package covered by it.

Name Surname
Company Name
Country/Region
Application
Volume range 1k/10k/100k/>100k

MyPGP public key:
Xxxxxxxxxxxxxxxxxxx
Xxxxxxxxxxxxxxxxxxx
…
xxxxxxxxxxxxxxxxxxx
”

The key could be also an attach ASCII file.
The package will be send by mail encrypted with the public key provided.
A copy of the license will be provided in the package.

Peeking physical addresses on ARMv7

The JTAG kernel debugger can be used to peek out the contents of physical addresses on ARMv7-based SoCs, for example to query memory-mapped registers. However, the MMU must be disabled before doing it to get the correct values, and re-enabled afterwards. Special "st" commands are available to do this, for example:

(gdb) st mmu off
(gdb) x 0xfd6d50b4 
0xfd6d50b4:     0x0000237c
(gdb) st mmu on

If this is something you need to do often, you may find it convinient to define a GDB helper function in your .armgdbinit file, like this:

define phys_x
        st mmu off 
        x $arg0
        st mmu on
end

Values can then be queried with a single GDB command:

(gdb) phys_x 0xfd6d50b4
0xfd6d50b4:     0x0000237c

Installing the ARM bring-up tools

A set of tools is available for developing non-Linux code on Cortex A9 cores. These tools are distributed as part of the ST Linux Distribution and can be installed using the ST Linux Distribution installer script. The installer script can be downloaded from the ST Linux FTP server here.

The ST Linux FTP server contains all the necessary tools for installing the distribution from the file system, or over the internet. The installer script uses yum to handle the installation and dependency checking of RPM files. Details on how to use the ST version of yum without using the installer script can be found here.

After downloading the installer script run the following commands to install the ARM bring-up tools:

host% chmod +x install

Then as root:

host# ./install bare-armv7

The following packages will be automatically installed:

stlinux24-bare-armv7-filesystem
stlinux24-bare-armv7-binutils
stlinux24-bare-armv7-binutils-dev
stlinux24-bare-armv7-binutils-doc
stlinux24-bare-armv7-cpp
stlinux24-bare-armv7-cpp-doc
stlinux24-bare-armv7-g++
stlinux24-bare-armv7-gcc
stlinux24-bare-armv7-gcc-doc
stlinux24-bare-armv7-hw-init-examples
stlinux24-bare-armv7-newlib
stlinux24-bare-armv7-protoize
stlinux24-cross-armv7-filesystem
stlinux24-cross-armv7-armdebug
stlinux24-cross-armv7-gdb
stlinux24-host-filesystem
stlinux24-host-stmc
stlinux24-host-targetpacks

Path setup

Developers should add the following directories to their PATH environment:

/opt/STM/STLinux-2.4/bare/armv7/bin
/opt/STM/STLinux-2.4/devkit/armv7/bin
/opt/STM/STLinux-2.4/host/bin

Keeping the toolset up to date

If one of the above packages is updated, it is recommended to use the stmyum utility to install the latest updates.

Update all packages with:

host# /opt/STM/STLinux-2.4/host/bin/stmyum update

ARM Bring-Up Tools

The ARM bring-up development tools are distributed as RPM files and must be installed on a host PC running a Linux distribution. There are many Linux distributions freely available on the Internet. Although the RPM packages can be installed on any Linux distribution, only the following 32-bit Linux Distributions are supported:

• RedHat Enterprise version 4 and above
• Fedora 6 and above

• the installation of the ARM bring-up tools
• a brief tutorial showing how to build and run a simple application
• instructions on how to report bugs about, and request enhancements to, the ARM bring-up tools

Building an ARM bare machine application

The following tools installed in /opt/STM/STLinux-2.4/bare/armv7/bin are used to build an ARM bare machine application:

• arm-none-eabi-addr2line
• arm-none-eabi-ar
• arm-none-eabi-as
• arm-none-eabi-c++
• arm-none-eabi-c++filt
• arm-none-eabi-cpp
• arm-none-eabi-elfedit
• arm-none-eabi-g++
• arm-none-eabi-gcc
• arm-none-eabi-gcov
• arm-none-eabi-gprof
• arm-none-eabi-ld
• arm-none-eabi-nm
• arm-none-eabi-objcopy
• arm-none-eabi-objdump
• arm-none-eabi-ranlib
• arm-none-eabi-readelf
• arm-none-eabi-size
• arm-none-eabi-strings
• arm-none-eabi-strip

For documentation on each of these tools please refer to their user manuals (installed in /opt/STM/STLinux-2.4/bare/armv7/info).

To build a simple hello, world application for a B2020-STiH415 target the use the following command:

host% arm-none-eabi-gcc hello.c -o hello.out -Wl,--defsym,__start=0x40000000,--defsym,__stack=0x60000000

where --defsym,__start=0x40000000 specifies the address where the application will be loaded and --defsym,__stack=0x60000000 specifies the address of the stack for the application. In this example the application has been allocated 512MB of RAM starting at the base of RAM.

Notes:

• The stack grows downward from the address specified by the __stack symbol and the heap grows upward from the end of the BSS section of the application (identified by the __end__ symbol).

  -------------------- 0x40000000
  | CODE             |
  --------------------
  | RO DATA          |
  --------------------
  | DATA             |
  --------------------
  | BSS              |
  --------------------
  | Heap             |
  |                  |
  |                  |
  | Stack            |
  -------------------- 0x60000000

• Only identity mapped virtual to physical addresses are supported.
• Hardware initialisation is limited to only that required by the C runtime library and to ensure safe execution. This means that only the following is performed:
  1. disable all interrupts (IRQ and FIQ),
  2. turn off the MMU and caches,
  3. ensure that only core 0 is executing,
     • the other cores enter sleep mode (by executing the wfe instruction)
     • the sleeping cores can be woken up by performing the following steps:
       1. write an address to the variable __cpu_nostack_init_holding_pen_release_address
       2. raise an event (by executing the sev instruction)
  4. turn on the ARM Neon floating point co-processor.

Getting started with the ARM bring-up tools

This section provides a brief introduction to building and running an application using the ARM bring-up tools (to install the ARM bring-up tools see Installing the ARM bring-up tools).

Reporting bugs and enhancements

Please submit any bug reports or enhancement requests in the ARM Bringup Tools product category in the STLinux Bugzilla database.

When reporting an issue please provide the following information:

• the version of the installed ARM bring-up tools (GCC, binutils and newlib) packages:

  host% rpm -qa | grep -e "stlinux24-bare-armv7-"

• the version of the installed STLinux ARM GDB and ST Micro Connect packages:

  host% rpm -qa | grep -e "stlinux24-cross-armv7-(armdebug|gdb)-|stlinux24-host-(stmc|targetpacks)-"

Note that Open lists all the currently unresolved issues against the ARM bring-up tools in the STLinux Bugzilla database and Closed lists all the resolved issues.

Building ARM bare machine applications without host I/O

By default the ARM bring-up tools build bare machine applications with host I/O enabled. These applications can only be loaded and run on a ARM target using armv7-linux-gdb; they cannot be run without the use of armv7-linux-gdb since the applications will perform I/O requests during their start up and if armv7-linux-gdb is not used to run the application will not execute correctly.

host% arm-none-eabi-gcc hello.o -o hello.out -Wl,--defsym,__start=0x40000000,--defsym,__stack=0x60000000 -mno-host-io

Introduction to KPTrace

KPTrace is an innovative tracing solution for STLinux on ST40 and ARM. It allows dynamic tracepoints to be added anywhere in the system, and provides a simple interface to collect and analyze the trace. Over three hundred useful tracepoints are pre-defined, including interrupts, context switches, system calls, and much more.

All the pre-defined tracepoints are inside the kernel but other tracepoints can be added anywhere in the kernel or in kernel modules. New tracepoints can be added on any symbol without rebuilding or rebooting the system. All tracepoints can be enabled and disabled at runtime. The system intrusion is minimized as only the enabled tracepoints produces traces.

The traces can be collected either into files in filesystem or through STM trace port (System Trace Module). The STM is an on-chip hardware block which handles system execution traces of the whole SoC and outputs them through the STM-trace port or, more simply, the STM port. It is available only on ARM based boards.Using STM trace port requires a connection with STM-Probe. The major benefits from the STM trace port are the lower intrusiveness and the support for multi-core system tracing. In addition, latest version of KPTrace (v4.0) relies on MTT trace technology (available only for ARM targets).

KPTrace can be driven from command line or graphical interface. For the GUI, refer to STPTK section which provides sophisticated trace viewers.

Build

To use KPTrace, the kernel must be built with the following option enabled:

-> Kernel hacking 
   [*] KPTrace
   [*] Multi-Target Trace (MTT) infrastructure support

If you use an ARM based target and requires to send traces over STM, you need to activate System Trace Module. To do it, you need to enable STM as follows:

-> Kernel hacking
   [*] System Trace Module

Dynamic System Tracing

To use KPTrace, follow these steps:

Pre-requesites

• Boot a kernel that has been built with KPTrace support.
• Mount a debugfs filesystem on the target, e.g.

[target] mount -t debugfs nodev /sys/kernel/debug

You may find it more convenient to mount it by default from the fstab, by adding this line:

debug           /sys/kernel/debug          debugfs defaults                        00

It is also necessary to have a sysfs filesystem mounted under /sys. This is usually the case by default.

Tracepoints configuration

KPTrace is very configurable. Configuration is carried out on the target by editing the file /etc/kptrace.conf.

kptrace.conf defines which tracepoints are on, and whether callstacks should be collected for them.

The format is as follows:

set <tracepoint set> <on|off>

Pre-defined tracepoints are divided into sets. You can turn a whole set on or off by setting the final argument to "on" or "off". If a set is off, none of the tracepoints in that set are added.

Note that the "memory_events" set generates a very large number of trace records, so it is disabled by default.

tracepoint <tracepoint> <yes|no>

All uncommented tracepoints in an enabled group will be added. To suppress an individual tracepoint, comment it out with a #. The final yes/no argument indicates whether a callstack should be output in the tracefile every time the tracepoint is hit (supported on SH4 only). Use this with care - although callstack generation is as fast as we can make it, it inevitably increases intrusiveness.

The final set, "user", allows additional user-defined tracepoints to be added. For example, to add a tracepoint on the symbol show_cpuinfo, simply add the following line to the set:

tracepoint show_cpuinfo no

No recompilation is required - the tracepoint will be used next time KPTrace is invoked.

The list of kernel symbols which can be added as user-defined tracepoint is available in /proc/kallsym

User-defined tracepoints can also be used to start and stop the logging of trace records. The syntax is this:

stopon show_cpuinfo no
starton zoneinfo_show no

In this case, no trace records will be logged after the show_cpuinfo tracepoint is hit until zoneinfo_show is reached. Tracing then continues as normal. The most useful application for this feature is to put a stop-point on an error case in flight-recorder mode to ensure that the trace leading up to the error is preserved. It is not necessary to restart the logging unless this is specifically required.

Kernel tracing with KPTrace

KPTrace mainly provides dynamic kernel tracing capabilities. Dynamic user space tracing is possible on SH4 platforms only. To use KPTrace:

• Run the executable kptrace on a target console
• This will gather trace until stopped with Ctrl-C
• The trace is generated either on trace files, or by using STM (available only in KPTrace version 4 onwards)

Kernel tracing using version 3.4 or older

Two output files are placed by default in /root/kptrace/ directory in target (older versions of kptrace could use the current working directory):

• .kpm: this file is the symbol map of your system. It includes the symbols from all currently loaded kernel modules.
• .kpt: these files are the trace files. They contain traces in ASCII format. You will have as many files as available cores for STLinux in your system.

Kernel tracing using version 4.0 onward

With this new KPTrace version, traces are gathered in a session directory. By default, session directory is /root/kptrace and file default name is kptrace. There are different kinds of files recorded during the session:

• .kpm: this file is the symbol map of your system (as described above)
• .meta: this file is the map running processes when kptrace is launched
• .mtt: These files are the trace files. With this new KPTrace version, they are logged in a raw binary format (i.e. without any text conversion done within the session). This allows significantly reducing the trace generation intrusiveness.

There is an utility that allows to extract .kpt KPTrace files from raw traces called (target side). This utility invokes the trace daemon running on your board to locate where the trace session is, so you do not need to specify any argument:

[target] mtt2kpt
Current Working Directory = /root
Trying folder /root/kptrace:
        mtt2kpt: Convert /root/kptrace/kptrace-00.mtt
                 to /root/kptrace/kptrace-00.kpt
        mtt2kpt: Convert /root/kptrace/kptrace-01.mtt
                 to /root/kptrace/kptrace-01.kpt

From this point, you can use STPTK to analyze the trace. Launch STPTK then open kptrace-0X.kpt files (File > Open Trace File...<code> then select the <code>.kpt file). Note that it's also possible to open the .mtt files from STPTK which will manage the conversion to .kpt automatically.

KPTrace options

KPTrace provides various other command-line options, including amon other features:

• -v to print the version
• -m to select the medium to use to capture traces ("files", "probe")
• -r to use a "flight recorder" mode (i.e. to use a ring buffer and keep only the last buffers upon stop)
• -d to set a trace capture duration in seconds
• -b to change the tracebuffer size
• -h to list all available options

Trace Analysis

Analysis with STPTK

Starting from version 4.0, KPTrace can be run from SoC Traces & Profiling Toolkit (a.k.a. STPTK).

STPTK is a lightweight UI application based on Eclipse technologies providing the whole flow of KPTrace: configure, control & capture, decode, display the traces. In particular, STPTK provides advanced analysis features and sophisticated trace viewers such as: Trace log messages viewer, System Execution time chart, Global execution views, Outline views, Statistics, Search tools, etc

With this tool, there is no more need of STWorkbench to work with traces or profiling data. Note that features available in STWorkbench for KPTrace and presented in these webcasts remains valid for STPTK.

For versions prior to version 4.0, KPTrace can be run from STWorkbench. See here the webcasts for more information using KPTrace in STWorkbench.

Using kptrace statistics scripts

On the host, there is one script  kptrace_stat.sh to compute statistics on KPTrace trace.

In current version, these statistics could be either:

• CPU load
• Processes/threads usage
• Functions usage

This script is available on host workstation when installing STPTK:

/opt/STM/STLinux-2.4/stptk/bin

This script can be used on existing or generated traces for post-mortem statisctics. This scripts also encapsulate different actions to get some performance indicators statistics. In particular, it starts/stops kptrace, collects the trace and computes statisctics from a single command (from user point of view). You can use it to capture a trace then get the statistics.

[host] kptrace_stats.sh -h

Post-process of traces with kptrace.pl (legacy script)

On the host, you can use the kptrace.pl perl script to extract human readable data from .kpt files, together with a set of statistics:

[host] /opt/STM/STLinux-2.4/host/bin/kptrace.pl kptrace.kpt kptrace.kpm

The processed output goes to stdout. The trace is rendered in a human-readable format, and detailed system statistics from the traced period are generated.

Note that when there are multiple CPU with a .kpt by CPU, the statistics given by this script is for the a given CPU.

Trace API

KPTrace provides two different APIs:

• A kernel API
• An user space API<§li>

Kernel API

A kernel API is provided to interface with KPTrace.

kpprintf(const char *format, ...)

provides a printf-style interface to the KPTrace trace buffer. The string has a timestamp and pid prepended to it, and is added to the trace output.

kptrace_write_record(const char *)

prepends a timestamp and pid to a constant string and adds it to the trace output.

kptrace_write_record_notime(const char *)

prepends a pid to the string and adds it to the trace output. Note that no timestamp is added; this allows this function to be used in some scheduler functions where a call to do_gettimeofday would cause a deadlock.

kptrace_pause(void)

stops the logging of trace records. This is equivalent to hitting a stop-point.

kptrace_restart(void)

restarts the logging of trace records. This is equivalent to hitting a start-point.

kptrace_mark(void)

indicates that this point in the code is significant. Marked points are indicated in the trace file, making it easier to find the most relevant parts of the trace. It is intended that marked points will be prominently indicated in the GUI.

All of these functions are defined in the file asm-sh/kptrace.h.

User space API

It is also possible to write printf()-style strings to the KPTrace trace buffer from a user space application. To do this, the following steps are required:

• Include the header file <kptrace.h>
• Link the application with the KPTrace library providing this function, with -lkptrace.

The function kpprintf() will then be available, which takes printf()-style arguments and will write directly into the trace buffer with a timestamp and process ID prepended.

kpprintf output is indicated in STPTK by yellow flags on the trace, and can be located by searching for the symbol kptrace_write_record.