head	1.1;
branch	1.1.1;
access;
symbols
	import-20090318:1.1.1.2
	import-20081205:1.1.1.2
	rel-8-1-2-sv:1.1.1.2
	import-20080404:1.1.1.2
	import-20071105:1.1.1.2
	import-20070116:1.1.1.1
	import-20061124:1.1.1.1
	freescale:1.1.1;
locks; strict;
comment	@# @;


1.1
date	2006.11.27.11.19.19;	author seh;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	2006.11.27.11.19.19;	author seh;	state Exp;
branches;
next	1.1.1.2;

1.1.1.2
date	2007.11.06.15.44.45;	author seh;	state Exp;
branches;
next	;
commitid	AdKoH3Xx8FxdUwEs;


desc
@@


1.1
log
@Initial revision
@
text
@%TOPICTITLE%
---

<verbatim>
Copyright  Freescale Semiconductor, Inc. 2004-2005. All rights reserved.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.  A copy of the license is included in the file doc/COPYING
</verbatim>


%TOC%

---+ Introduction

Here is a quick note on various techniques and best practices for maintaining
LTIB BSP.


---+ How to upgrade a BSP (non-maintenance).

---++ Scenario

A BSP exists for a target and some time has gone by.  Now you want to
re-release that BSP, possibly adding new kernels, toolchains bootloaders etc.
What should you do?

---++ Which CVS should I use

After the last release of this BSP, the release team should have merged
back from their branch into the trunk of CVS.  If this has not happened,
you must do this first.  

Now that some time has gone by and you are adding something new not
so much  fixing a bug (even though that may be an indirect consequence)
you should be working to start with on the trunk of CVS.

Once you have added the new stuff and have it basically working, you should
re-branch and follow the release process documented in LtibReleaseProcess


---++ Principles

   1. If we've released something before the selections
   of kernel/bootloader/toolchain should still be available to users
   2. Don't knowingly break older stuff.  
   3. Newer is not always better (to everyone).  Some people really need
   to have the old stuff available to them (even if it's not the default).


---++ What should I do to add a new toolchain and kernel?

Lets say you have new toolchain and a new kernel that you want to
upgrade people to.  Here's what to do:

   * __ADD__ the new toolchain as the next one in the selection list.  
   * __LEAVE__ the old toolchain tokens in place

For example here's a diff that shows I've added a gcc-4.1.0 as a
selection:
<verbatim>
     config TOOLCHAIN1
         bool "gcc 3.4.0" if UCLIBC
+    config TOOLCHAIN2
+        bool "gcc 4.1.0" if UCLIBC
     config TOOLCHAIN_CUSTOM
</verbatim>

Now let's say we want to add our new kernel:  Again add it as the next
available kernel, here's an example:

<verbatim>
     config KERNEL1
        bool "Linux 2.6.11"
+    config KERNEL2
+        bool "Linux 2.6.17"
</verbatim>

---++ Pre-selecting the new stuff

Here's the key to it all.  Having added our new stuff (leaving the old
stuff in place), we simply update the 'defconfig' to reference the new
defaults.  

---++ Why is this important

Imagine you're a poor user using CVS.  Your config is setup and you're
working on (and happy with) a certain toolchain and kernel.  If someone
changes the meaning of TOOLCHAIN1 or KERNEL1, when you do a cvs update,
you'll be subjected to a situation whereby your current configuration is
invalid.  Worse still the old selections you _WANTED_ have disappeared.
How rude....

This situation would likely lead to frustration by users and lots of
extra support traffic.

---++ Conclusion

---+++ Dos

   * Add new stuff
   * Update the defconfig

---+++ Donts

   * Remove old stuff 

---+++ Exceptions

There are always exceptions, but please discuss first on the LTIB list
if you are thinking that your case is an exception.

----

-- Main.StuartHughes - %SERVERTIME%



@


1.1.1.1
log
@Import from fsl 20061124
@
text
@@


1.1.1.2
log
@Import from fsl 20071105
@
text
@d23 1
a23 1
---+ How to upgrade a BSP (i.e. not-maintenance).
d39 1
a39 1
you should be working to start with on the HEAD of the trunk of CVS.
a55 2
---+++ General principles

d62 2
a63 5
---+++ Example: adding a new toolchain

In the patch below, here's an example showing how I added a new toolchain
to the tqm823l platform:

d65 4
a68 15
$  cvs diff -r 1.31 -r 1.32 config/platform/tqm823l/main.lkc
Index: config/platform/tqm823l/main.lkc
===================================================================
RCS file: /cm/vault/ltib/ltib/config/platform/tqm823l/main.lkc,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -r1.31 -r1.32
--- config/platform/tqm823l/main.lkc    24 May 2006 15:41:29 -0000      1.31
+++ config/platform/tqm823l/main.lkc    27 Jul 2006 12:47:30 -0000      1.32
@@@@ -54,6 +54,8 @@@@
         bool "ppc-823 gcc-3.3.2/glibc-2.3.2 soft-float" if GLIBC || LIBC_NONE
     config TOOLCHAIN2
         bool "gcc-3.3.5/uclibc-0.9.2" if UCLIBC || LIBC_NONE
+    config TOOLCHAIN3
+        bool "gcc-4.0.2/glibc-2.3.6 soft float" if GLIBC || LIBC_NONE
a69 25
         bool "custom"
 endchoice
@@@@ -62,11 +64,13 @@@@
     string
     default mtwk-lnx-powerpc-823-gcc-3.3.2-glibc-2.3.2-0.28-7.i686.rpm if TOOLCHAIN1
     default ppc-uclibc-tc-20050308-2.i686.rpm if TOOLCHAIN2
+    default tc-fsl-x86lnx-823-4.0.2-2.i386.rpm if TOOLCHAIN3

 config TOOLCHAIN_PATH
     string
     default "/opt/mtwk/usr/local/powerpc-823-linux/gcc-3.3.2-glibc-2.3.2" if TOOLCHAIN1
     default "/opt/mtwk/usr/local/uclibc/ppc_nofpu" if TOOLCHAIN2
+    default "/opt/freescale/usr/local/gcc-4.0.2-glibc-2.3.6-2/powerpc-823-linux" if TOOLCHAIN3
     string "Supply your toolchain path" if TOOLCHAIN_CUSTOM

 config CUSTOM_TOOLCHAIN_PREFIX
@@@@ -77,7 +81,7 @@@@

 config TOOLCHAIN_PREFIX
     string
-    default "powerpc-823-linux-" if TOOLCHAIN1
+    default "powerpc-823-linux-" if TOOLCHAIN1 || TOOLCHAIN3
     default "powerpc-linux-uclibc-" if TOOLCHAIN2
     default CUSTOM_TOOLCHAIN_PREFIX if TOOLCHAIN_CUSTOM

d72 2
a73 7

---+++ Example: adding a new kernel

Here is an example that shows the addition of a new kernel to a target.

First, here's the patch of the main.lkc file.  I've snipped it back
to remove the hunks we're not interested in:
d76 4
a79 34
$ cvs diff -r 1.2 -r1.3 config/platform/qs875s/main.lkc
Index: config/platform/qs875s/main.lkc
===================================================================
RCS file: /sources/ltib/ltib/config/platform/qs875s/main.lkc,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- config/platform/qs875s/main.lkc     27 Feb 2007 14:43:16 -0000      1.2
+++ config/platform/qs875s/main.lkc     6 Mar 2007 17:20:39 -0000       1.3
@@@@ -121,6 +121,8 @@@@
         bool "2.4.27 (Analogue Micro Ltd)"
     config KERNEL3
         bool "2.6.16 (Analogue Micro Ltd)"
+    config KERNEL4
+        bool "kernel-8xx"
     config KERNEL_DIR_BUILD
         bool "Local Linux directory build"
         help
@@@@ -135,6 +137,7 @@@@
     string
     default "kernel-2.4.27-875"               if KERNEL1
     default "kernel-2.6.16-875"               if KERNEL3
+    default "kernel-8xx"                      if KERNEL4
     default "kernel26-dir-build"              if KERNEL_DIR_BUILD

 source ../../userspace/kernel_dir_build.lkc
@@@@ -153,6 +156,7 @@@@
     string "kernel config"
     default "linux-2.4.x-am_adder_87x.config" if KERNEL1
     default "linux-2.6.16-am_adder_87x.config" if KERNEL3 || KERNEL_DIR_BUILD
+    default "linux-8xx-am_adder_87x.config" if KERNEL4

 config PKG_KERNEL_WANT_CF
     depends ! KERNEL_NONE
a81 33
Here's an explanation:

   * Hunk '@@@@ -121,6 +121,8 @@@@' shows the new menu prompt under the kernel
   choice list selection "kernel-8xx"

   * Hunk '@@@@ -135,6 +137,7 @@@@' Shows that the new kernel (#4) will select
   the spec file who's base name is "kernel-8xx" as the rpm spec file
   that will be used in order to build the kernel.  It is this spec file
   that references the source tarball and patches that belong to this kernel

   * Hunk '@@@@ -153,6 +156,7 @@@@' Shows that the new kernel (#4) will select
   the new linux .config file "linux-8xx-am_adder_87x.config"

In addition to changing this main.lkc for this example I needed do the
following:

   * Create (maybe based on a copy) the file:
   config/platform/qs875s/linux-8xx-am_adder_87x.config

   * Create (maybe based on a copy) the file:
   dist/lfs-5.1/kernel/kernel-8xx.spec.in 


---++ Remember to upload the content to the GPP or send a patch

Before you check-in changes to LTIB CVS that reference new content
(e.g. toolchains, source tarballs and patches), you must uploaded
the to the GPP using this link: http://www.bitshrine.org/cgi-bin/gpp_upload.cgi

In order to use this link you must be a trusted developer with a password.
Until that has been arranged, please send patches to the LTIB public
mailing list

d84 3
a86 22
Having added your changes to main.lkc (leaving the old stuff in place), 
and added any new config files, run:
<verbatim>
./ltib --configure
</verbatim>

Make the changes you need to your overall configuration so that the BSP
works with your updates as you require.  Your configuration points
will now have been captured in:

   * config/platform/&lt;target&gt;/defconfig.dev
   * config/platform/&lt;target&gt;/&lt;linux_config_name&gt;.dev

If you want to make your new overall configuraton the new default, move
the config/platform/&lt;target&gt;/defconfig.dev to 
config/platform/&lt;target&gt;/defconfig and check-in the update.

If you have updated your new Linux configuration file, you should move
this from the '.dev' name to a version without the '.dev'.  Normally
this will be a new file, so you need to 'cvs add' it before checking
it in to cvs.

d119 3
@

