DMAI GStreamer Plug-In Submitting Changes

Licensing Guidelines

Please see the Licensing Guidelines for Patches for information on licensing requirements for submitting patches.

Dividing up the Patches

This section covers general ideas on how to split patches and trackers along functional lines. These general ideas will help to make it easier to integrate your changes into the TI GStreamer port faster.

In general you should create a patch tracker item for each functionality that you are adding or bug being fixed. Inside of each tracker you may have multiple patches splitting up the code to be added into easier to read segments. The main goal here is that all patches for a particular enhancement or fix are grouped together in a single tracker, but each fix or enhancement has it’s own tracker item. If you have a fix or enhancement that relies on another fix these should be split into two tracker items but listed as a set as detailed in the “Creating the Tracker Item” section below. To help demonstrate this here is a general example:

In this example there are two changes to be done. To keep this general we will call these change1 and change2. Change1 is a general enhancement applicable to all elements and does not rely on change2. Change2 is an enhancement which requires that change1 be implemented in order for it to work. Furthermore, change1 can be split into 3 smaller units (i.e. add .c and .h files, update build system, add new registration routine). In this example we will submit two tracker items as a patch set and group the patches accordingly. We would create the following tracker items:

[PATCH][1/2] Add functionality x

Details: Describe the specific functionality being added and how this is part of adding functionality x.

Patches:

+ Patch 1 - Add .c and .h files

+ Patch 2 - Update build system

+ Patch 3 - Add new registration routine

[PATCH][2/2] Add functionality x

Details: Describe the specific functionality being added and how this is part of adding functionality x.

Patches:

+ Patch 1 - Add enhancement

Note that in the above example both patches were given a summary name of the functionality being added (in this case x). The details section described the specifics of the changes being made in the patch(es). Using this method it is clear that these two trackers are part of an overall fix/enhancement and that the second tracker depends on the first one.

The benefit of this approach is that when reviewing the patches for inclusion if the second set needs some more work the reviewer can still accept the first set of changes. This allows new code to be integrated into the tree in pieces and prevents holding up the integration of good code while waiting for other code to be made acceptable. This makes tracking when each change was committed easier and helps prevent changes from being missed.

Creating a Patch

Patches should be created in p1 format from the gstreamer_ti directory. This means that your patch should be in a format such that it can be applied from the trunk (or branch) directory using the “patch –p1 < patch_file” command. You can use commands such as “git format-patch” or “svn diff” to generate patches or any other method or tool which you wish to use. Below are some example instructions for various methods of creating patches.

Using Diff

1. Obtain a fresh checkout of the repository. See the Access info link under the SVN tab on the left side of the Licensing Guidelines for Patches project site.
2. Copy the gstreamer_ti directory. This will be your working copy.

   cp -rf gstreamer_ti gstreamer_ti.new

3. Make your changes in the gstreamer_ti.new directory
4. When you have made all your changes create a patch file by doing:

   diff -burpN gstreamer_ti gstreamer_ti.new > patch file

   NOTE: in place of patch file put a descriptive name for what the patch does. i.e. fix_dm6446_compiler_warnings.patch

Using Git

1. Obtain a fresh checkout of the repository. See the Access info link under the SVN tab on the left side of the gstreamer.ti.com project site.

   git svn clone --username-<Your user name or anonymous> https://gstreamer.ti.com/svn/gstreamer_ti --stdlayout

2. Create a working branch

   git checkout -b development

3. Make your changes. You can apply patches using git apply. Each commit that you make on this development branch will create a seperate patch.
4. Create the patches for your changes. NOTE: If you want to consolidate separate commits checkout the git rebase -i command. The command below will create a patch for each commit you have made on your development branch vs. the master branch you checked out. The name of the patch will be 000#-<commit message>.patch

   git format-patch master

5. You now have a patch or series of patches for your change that can be uploaded to the patch tracker system.

Each patch tracker should be created to fix one specific issue or add a specific functionality. For example, if you have a change to fix a compile issue and another change to add a new parameter to an element these should be two separate patches.

In the case of adding a large amount of code you may want to generate a series of patches. For example you may want to create a series of patches that add a new element to the TI plugin. In this case you may want to separate the changes into a series of patches. i.e.

• A patch to add the element .c and .h files
• A patch to add the element into the Makefile.am
• A patch to register the element in the TI plugin

When creating a series of patches it is often useful to append a 000#_ to the beginning of the patch name, where # is a number indicating the order in the series. Git will do this for you automatically. i.e.

0001_add_element_sources.patch

0002_add_element_to_makefile.patch

0003_register_element_in_TI_plugin.patch

Doing this will help others to apply your patches in the correct order. This is particularly important if you are creating patches where one patch relies on another patch already being applied.

Creating the Tracker Item

Patches are submitted using the Patches tracker accessible through the Tracker tab on the left. When submitting a patch to fix a bug listed in the tracker you should still submit the patch to the patches section and then add a note to the bug report listing the tracker number for the patch. After submitting the patch you can add associations by opening the tracker item for the patch and clicking the Associations tab at the bottom of the screen. Select Add Association and enter the associations you want. For example when submitting a patch to fix a bug you may want to create an association with the tracker item for the bug.

The Patches tracker of GStreamer should only be used to post patches to the GStreamer code itself. If you have found a bug in another component such as DMAI it should be submitted to that components bug tacker. i.e. for DMAI patches should be posted to the DMAI project at https://gforge.ti.com/gf/project/dmai

For each functionality you should create a new tracker item to contain the patch(es) with the following information:

• Priority - The priority of the patch
• Assignee - Leave set to none unless you know who to assign it to
• Status - Set to open
• Repository Revision - Revision of the repository this patch was created against
• Component - Which component this patch affects
• Resolution - Leave set to none
• Targeted Platforms - Select the platforms this patch is targeted for
• Other Platform Considerations - If this patch may apply to other platforms but you have not tried them put some information in here about how the patch may work on other platforms.
• Summary - A one line description of the patch (see below)
• Details - More information about what the patch does, testing performed, etc. (see below)

The Summary field should be set with the following format:

[PATCH][x/y] Functionality or bug fix being added

When submitting a series of patches x should be the order of the patch in the series and y should be the total number of patches in the series. If you are submitting a single tracker item you can omit the [x/y] value. For more information on how to divide the patches see the Dividing up the Patches section above.

The Details field must contain the following information:

1. Device(s) tested against
2. Version of software used in testing
   1. Repository revision
   2. DVSDK version
   3. DMAI version
   4. Kernel version and any additional patches applied
3. Patch target (i.e. a specific branch or the trunk)
4. Description of the problem being fixed or the enhancement being added. If the patch is fixing a bug what are the symptoms of the issue?
5. A list of the testing performed

In general the information should be sufficient that others know where to apply the patch, when they have the same issue, and how to reproduce your testing. If the base components such as DMAI or the kernel require a patch for this functionality to work this should be noted and a link to the patch should be posted.

Review Process

Once you have submitted the patch it will be reviewed and any comments will be posted back to the tracker. If the patch is good then it will be applied and the tracker Resolution will be set to Accepted.

If it needs changing create a new patch and append a review# to the patch file name. Post this new patch to the tracker leaving the old patch in place. The new patch should be a whole patch, not a patch to be applied on top of the original one.

New Feature Recommendations

We have a tracker to capture feature requests (accessible via the navigation panel to the left). If you have an idea specifically related to utilizing hardware accelerators on DaVinci devices, please them along.