PSP Linux Development FAQ

PSP Open Source Development Philosophy

What is PSP development philosophy?

• Our development philosophy is: "Community First, Commercial Complement".
• TI develops and maintains device drivers for its SOC’s based upon the open source Linux kernel.
• TI stabilizes on a kernel version periodically to create a supported Linux PSP product.
  • Patches waiting to be upstreamed are hosted in a staging tree on Arago server.
  • This product is validated against a defined test plan. Different driver benchmarks are also collated as part of this activity.
• TI partners with multiple commercial Linux vendors and Linux consultants as well.
• TI customers have a spectrum of choice from free Linux to commercially-supported Linux products for their development.

What does "Community First" mean?

• TI is taking a more active role in Linux kernel development for its SOC devices by,
  • Actively monitoring and participating in community kernel mailing lists (kernel sub-systems and DaVinci/OMAP)
  • Developing and contributing Linux device drivers upstream to git.kernel.org
  • Making available TI’s kernel sources in Arago Project server.
• Benefits
  • Updates: Access to the latest enhancements, including all peripheral drivers
  • Quality: Higher quality as latest bug fixes are included and TI kernels are exposed to a greater number of use cases through presence in mainline
  • Collaboration: Linux kernels for TI devices will continue to receive generic enhancements and bug fixes with community participation; TI customers can leverage community support much more effectively as this is focused on recent kernel releases
  • Community Support: TI devices can easily be supported in/by the standard Linux distributions

What does "Commercial complement" mean?

• TI recognizes customer need for a commercial Linux product offering that
  • Is driven by a specific set of features and compatibility need
  • Is maintained for an elongated time with good support model (including, selective back-porting of fixes and features)
  • Provides file system, utilities and IDE support for development
  • Provides support for tool-chains and automated builds

• TI has a Linux partner strategy that follows two main vectors
  • Commercial vendors: These partners provide support, off-the-shelf Linux distributions or tools
  • Consultants: These partners provide training, general embedded Linux development expertise, or specific expertise for developing drivers or particular embedded applications. (More info on this page).

• TI’s "community first" model supports "commercial complement"
  • Commercial partners pick up latest Linux PSP from TI and build their product
  • They continue to receive updates and fixes from TI due to the open model of development allowing them to back-port fixes or provide additional features in their products

How does our Linux PSP development strategy relate to open source development (graphically)

What are the Linux PSP Development time-lines?

• Major releases every alternate quarter (6 months) with full testing on all devices supported.
• Download from Product Folder; Documentation on Sitara wiki.
• Stable product releases are supported via E2E community forums.
• Monthly development snapshots with limited testing on select devices (features may regress).
• Snapshot are available from Arago Project.
  • Development milestones are identified by git tags.
• Latest / active development available at Arago Project server almost real time (weekly or less).

Linux PSP Validation

What is our Linux PSP Validation strategy?

• TI validates device drivers supplied as part of the Linux PSP
• TI does NOT validate the kernel itself or its core modules
• TI provides OpenTest automation framework built on open source components
  • Source code for test automation framework is available on Arago Project server
  • TI uses TestLink - an open source test management tool for managing test cases
• TI uses mix of internal and open source tools for driver validation using LFTB (Linux Functional Test bench).
  • Tools like lmbench, ltp, iperf, bonnie, MTD/flash utils, evtest, mplayer are used out-of-box for standard (char, block, networking) device drivers
  • LFTB adds more tests for specific device drivers that require more white box testing and where features features supported by TI devices are not yet exercised by standard tools.

• The validation is performed:
  • Across these vectors for adequacy: functional, compliance, usability, reliability, stress & stability, throughput & performance
  • With varying scope: Full, Regression, Sanity
  • With varying frequency: Daily, Weekly, Monthly and 6 monthly

• The Linux PSP product goes through full test cycle.

• Defects found during validation are logged and 'tracked to closure - including upstream submission (if applicable).

Arago

What is Arago?

• Arago Project is an open integration, build, and test infrastructure that provides a portal into how Texas Instruments creates customer ready Linux SDKs.
• Arago Project is an overlay for OpenEmbedded/Angstrom, which targets TI platforms OMAP3 (EVM and BeagleBoard) and DaVinci (6446, 355, 365, 6467...) and provides a verified, tested and supported subset of packages, built with a free and open toolchain (CodeSourcery Lite for now).
• Many users will want to use the official SDK products from the TI software download page. Others will want the cutting edge of using upstream OpenEmbedded or Angstrom distributions. Arago serves the middle ground where an advanced user wishes to get a peek into an upcoming release or to peek under the hood of an existing release.
  • A vendor may wish to create add-ons that are known to work with TI SDKs
  • You may wish to duplicate some of our testing on your custom board.

What else does Arago Project host?

Arago website also hosts:

• GIT trees for various projects
• Pre-built releases for quick download
• Bugzilla for Arago

How do I get my changes/ bug fixes or patches to Arago GIT trees

• As for u-boot and kernel code is considered, Arago GIT staging area is meant for making TI's latest development code available to developers who wish to follow it.
  • It should provide a snapshot of what the PSP engineers are working on.
  • It is NOT an upstream tree where community and customers can send their patches to and will get upstream - it should not be treated as such.
• Any patch of new feature developed has to be submitted to the upstream trees
• If you feel something needs to be part of the PSP release read through this FAQ to find answers for the same

Linux PSP Development

What are the different GIT trees?

• Upstream Linux Kernel Trees - The ultimate goal and destination of all development is git.kernel.org
  • Linux Kernel Tree - ultimate kernel tree - maintained by Linus Torvalds
  • Linux OMAP Kernel Tree - TI (ARM Cortex-A8) OMAP35x/AM35x/AM37x Linux Kernel tree maintained by Tony Lindgren
  • Linux DaVinci Kernel Tree - TI (ARM9) DaVinci/AM1x Linux Kernel tree maintained by Kevin Hilman

• Upstream u-boot Trees
  • Upstream u-boot tree] - maintained by Wolfgang Denk
  • TI u-boot upstream tree - maintained by Sandeep Paulraj

• TI GIT trees - hosted on Arago Project for latest TI code
  • Kernel Staging Tree for TI (ARM9) DaVinci/AM1x - maintained by Sekhar Nori
  • Kernel Staging Tree for TI (ARM Cortex-A8) OMAP35x/AM35x/AM37x - maintained by Sriramakrishnan G
  • u-boot staging tree for TI (ARM9) [1] - maintained by Sekhar Nori
  • u-boot staging tree for TI (ARM CortexA-8) [2] - maintained by Shriramakrishnan G

Note: TI Arago hosted GIT trees are staging trees - NOT upstream trees - so they do not accept patches like upstream trees.

How does PSP develop Linux Drivers?

• PSP developers follow open source development guidelines to develop Linux kernel device drivers (see: Linux kernel HOWTO).
• All code developed follows Linux Kernel coding guidelines.
• PSP maintains two GIT trees for internal development
  • An open source GIT tree for new patch/driver development - this tree is usually at the tip and every developer clones it to create a patch at the tip of the tree for submissions
  • Release Integration tree - for inclusion of patches in a upcoming release - typically this is a kernel version that was aligned to be part of next release (usually lagging the tip)
• Developers create patches at the tip of linux-omap and linux-davinci trees and submit patches to the relevant mailing list for inclusion in the tree
• Depending upon PSP release time-lines PSP developers may also submit the patches to internal integration tree
• Once the patches get accepted in upstream kernel (linux-omap or linux-davinci) trees then they are automatically pulled into the next release integration tree.

What is contained in the Linux PSP release?

The Linux PSP includes these components (sources and pre-built binaries) for target hardware supported in the release:

• Primary bootloader (e.g. x-loader, ubl, ...), if applicable.
• Secondary bootloader (u-boot) specific to supported devices
• Linux kernel

It also includes these documents:

• Release Notes - indicating supported features, defects fixed, list of known defects, workarounds, etc.
• User Guide - containing instructions to use the target hardware, deploy contained software, enable/disable specific features, etc.
• Feature and Performance Guide - containing the performance data and benchmarks collated during the validation cycle.

NOTE: These documents are also available in this wiki. (Refer to release pages for Sitara and DaVinci processors).

How is Linux PSP releases generated?

• PSP engineers follow these time-lines for releases. The goal of a new release is to migrate to newer kernel version, add support for new silicon and provide bug fixes since previous releases.
• As specified in the release time-lines, PSP engineers fix on a given kernel version for their next release and all patches are integrated in the integration branch and validated for functionality, performance and other aspects as per the validation strategy.

How long is a PSP release supported?

• PSP strives to support its major releases for 6 months post the release date
• Our active development mainly happens on the tip of upstream kernels - so any bugfix or new feature will only be done on the tip of upstream latest kernel version
• For critical fixes, PSP shall create a patch and make it available on our staging GIT trees on top of our last PSP release
• If you need more dedicated / continuous support on a given PSP release, we recommend our Commercial partners for the same

Contributing to Linux PSP

This section outlines the process for customers and 3^rd parties using the Linux PSP - who would like to contribute patches back into the Linux PSP.

The preferred flow for getting patches into the Linux PSP is upstream submission.

• Create a patch against the latest master on the applicable upstream tree - linux-omap/ linux-davinci.
  PSP engineers follow these mailing lists regularly.
• Check if additional subsystem mailing list needs to be copied while posting the patch to either of these mailing lists.
• Submit the patch.
  The patch would require consistent follow-up - based on review comments.
• If the patch is accepted, it would be included automatically, in next PSP release.

However, if there is critical need to apply the patch on current integration branch,

• Refresh the patch against applicable PSP baseline.
• Submit a request for acceptance - via e2e. Attach your patch OR point to a public tree where the patch is available.
• Based on the nature of fix/ enhancement, PSP engineers will indicate the acceptance or otherwise.
  Already upstream patches would automatically have a higher chances of acceptance.

This flowchart illustrates these steps:

NOTE: If your patch/ patch-set implements a new feature and already submitted (and may be accepted) upstream; and there is a urgent need to apply the patch/ patch-set on PSP maintained branches, get in touch with local TI representative. He would need to coordinate with PSP team to allocate support bandwidth. These requests would be evaluated on various engineering aspects before arriving at any decision.

Guidelines for submitting patches

Please read the Documentation/SubmittingPatches and Documentation/CodingStyle before making a patch. Here is a list of some guidelines based on what folks typiclly miss doing. This is not an exhaustive list and kernel documentation wins in case there is a contradiction. These guidelines apply to U-Boot as well. If you have a valid reason to skip any of the guideline, please discuss the same with the branch maintainer.

1. Configure your git environment with the correct email id and full name. This could be done by creating/editting '.gitconfig' in the user home directory (for example, /user/<user_name>/.gitconfig). There are several examples configurations available on the internet, like the one here. Needless to say, your e-mail address should be valid and you should be able to access any replies sent to that address.
2. Follow standard Linux conventions – coding style, driver model, patch sequencing, sign-offs, etc.
3. Commit message
   1. The subject line in the commit message should have the platform name, module name and one line comment on the patch. For example, the integration branch 04.02.00.06 is used for all omap3 and DM816x/DM814x work. Hence it would be good to have the platform name and module name in the commit message. For example, "ti816x: nand: ........". Using lower-case for platform and module is recommended. Please refer some old commit messages.
   2. The subject line in the commit message should be a simple, one-line summary, detailed information should start after a blank line.
   3. Signed-off-by: line is mandatory, it could be added automatically using the -s option while committing the changes (for example, 'git commit -s'). Git configuration file '.gitconfig' should be set correctly for this to work (i.e. point 1 should be taken care)
   4. The commit message should be in present tense not past tense. Example xyz: added support for abc is wrong. Instead use xyz: add support for abc. It makes more sense this way for the person reading or reviewing the commit.
   5. Please check for typos in the commit message.
   6. No tabs and no un-wanted white spaces.
   7. Make sure the commit message does not exceed 74 characters in a line. Multiple lines are allowed.
4. Do not send intermediate or "work in progress" patches. If you have a bunch of patches touching different subsystems, please make an attempt to group them logicaly. This will help the reviewers and will be easy to maintain.
5. No patch should break the build. It is the responsibility of the owner of the patch to check for build failure before and after pushing the patch.
6. Build and Test the code change on all relevant platform families. For example, any change in a nand driver done in the DM816X context should be built and tested in the OMAP3 and DM814X context also.
7. Indicate the testing status for the patch - which platforms, use-cases, etc.
8. Running checkpatch script on the patch is mandatory. This script is available at scripts/checkpatch.pl in the kernel directory.

When helping PSP upstream patches

We welcome all help in getting PSP code reach upstream trees. Please follow these guidelines so we can work together.

1. Please contact the patch's author (on or off the mailing list) *before* sending the patch to the mailing list.
   1. If you are unable to contact the author (mail bounces) or if the author does not respond in reasonable time, please contact the mailing list. There might be new folks who are now responsible for patch.
2. Explain your intention and ask when author himself will be ready to post the patch.
3. Come to an agreement with the author on the timelines and the work involved in making the patch ready for submission.
4. Unless the author and you agree otherwise, the authorship should remain with the original TI author. The means the From: line should contain the original author's name.
5. Do not remove any existing Signed-off-by: lines in the patch.
6. You can add your sign-off line since you are now responsible for the patch as well and are in the path to upstream.
7. A simple way to achieve 4), 5) and 6) above is to use standard git commands like git-cherry-pick, git-am, git-send-email etc.
8. Do not remove any existing TI copyrights. You can add your copyright based on the amount of changes you have done to the original patch. This is left to your best judgment.
9. If you intend to post the patch only to get some more testing done by the broader audience, mention your intention clearly in the patch (under the --- tearline). Sending subtle messages to the maintainer by mentioning "RFC" or "RFT" is not the way to do this. If the maintainer does not find anything obviously wrong, the code might actually make it upstream! A maintainer does not necessarily test all the patches that come his way.

Common Questions Answered Here

What exactly do you support in PSP release?

• Primary/secondary boot-loaders
• Linux base-port for the supported platforms
• Specific drivers implemented for the SOC

Can I get help on the kernel scheduling?

PSP engineers can share their experiences on these (and similar) queries. However, they are not actively involved in kernel development. They could also point you to right people/ mailing lists/ other resources where you can find help.

Can I get help in getting more file system performance from the kernel?

If the performance drop is due to implementation in the driver associated with device on which filesystem is mounted, PSP engineers will definitely help in resolving it.

However, if the issue related to generic improvements in the file system performance, answer to previous question applies.

Which boards are supported?

There is usually an evaluation module (EVM) associated with each SOC. It is, by default, supported in the associated PSP release. Recently, some community boards using TI SOCs have become quite popular. Though, it is difficult to support each community board, select boards are supported in the PSP releases. The list of boards supported in a PSP release is available in the corresponding Release Notes.

PSP technical FAQ

PSP Frequently asked questions section has been moved to PSP FAQ

 

---