marvell-doc/MARVELL_GCC_Extra_Libraries_for_Various_Platforms.txt - toolchains/armada - Git at Google



 Extra Libraries for Various Platforms
 =====================================

 1. Concept
 2. Source Code Layout
 3. Predefined Macros
 4. Notes


 --------------------------------------------------------------------------------
 1. Concept
 --------------------------------------------------------------------------------

     There are many requests from various SOC teams to integrate the platform-
 dependent-optimized routines into the Marvell GCC Toolchain.  Most of them are
 memory handling routines, such as "memcpy", "memset", "strcmp", etc.  There are
 no good reasons to merge all of them into the standard library, especially libc,
 and make things worse if we do so.  It's better to stand these routines alone
 for the users who need them.

     We don't change the standard libraries, and let users select alternative
 platform-dependent-optimized routines and replace the standard ones.  Take
 an example.  There is a special tuned "libmrvl.a" containing "memcpy".  Users
 can link this extra library first instead of the libc.

 	$ arm-marvell-eabi-gcc foo.c -lmrvl

     Since the extra libraries are tuned for some platforms especially, users
 should know what correct platforms they are tuned for.  Different extra
 libraries may not be suitable for each platform and misusing maybe make the
 program running slowly or crash even more worse.

     We would collect all the extra library packages including the source,
 "Makefile", "README", "testsuite", etc, and place them in the source tree of
 the Marvell GCC Toolchain:

 	${MARVELL_TOOLCHAIN_SOURCE}/src/extra-src/${EXTRA_SOURCE}/

 "${MARVELL_TOOLCHAIN_SOURCE}" is the path of the source and scripts of the
 Marvell GCC Toolchain.  "${EXTRA_SOURCE}" is the path name of the extra
 package tuned for a special platform.

     The toolchain's building script will invoke "make" to build the extra
 static libraries and copy them to the Marvell GCC Toolchain installing path.
 E.g.

 	${MARVELL_TOOLCHAIN_INSTALL}/armv5-marvell-eabi-softfp_x86_64/
 	arm-marvell-eabi/lib/lib${EXTRA}.a

 "${MARVELL_TOOLCHAIN_INSTALL}" is the installing path of the Marvell GCC
 Toolchain.  "lib${EXTRA}.a", e.g. "libmrvl.a" example, is the static tuned
 library.  After that, users can link it by adding "-l${EXTRA}" option to link
 these extra routines.

     For simplicity, this work may only support the extra static library with
 the ARM (i.e. non-thumb) code of the platform-dependent-optimized routines.
 These routines are tuned for the various SOC targets and would take the place
 of some routines from the native standard libraries.


 --------------------------------------------------------------------------------
 2. Source Code Layout
 --------------------------------------------------------------------------------

     All of the extra package are collected to the ${EXTRA_SOURCE} subdirectory.
 The below listing shows where the extra source code is:

     ${MARVELL_TOOLCHAIN_SOURCE}	# Marvell-tuned GCC C/C++ Compiler Source Code
     |
     +-- script                  # Building scripts and documents
     |
     +-- src
     |   |
     |   +-- ...-src		# Individual package source, e.g. gcc,
     |   |			# binutils, glibc, etc.
     |   |
     |   +-- extra-src		# Collection of all extra packages from various
     |       |			# SOC teams.
     |       |
     |       +-- README		# i.e. this document.
     |       |
     |       +-- ${EXTRA_SOURCE}	# The extra package.
     |       |   |
     |       |   +-- README	# Document of this extra library.
     |       |   |
     |       |   +-- Makefile	# "make" script
     |       |   |
     |       |   +-- *.s, *.S, *.c, *.C, ...
     |       |   |		# Source code, or puts them in the subdirectory.
     |       |   |
     |       |   +-- testsuite	# Subdirectory for test cases and running
     |       |			# scripts.
     |       |
     |       +-- ...		# Another extra package for alternative SOC.
     |
     +-- Release			# Toolchain's building and installing paths.
         +-- build
         +-- install

     The "${EXTRA_SOURCE}" should provide "Makefile" for building and detail
 "README" document.  After all the packages of the Marvell GCC Toolchain are
 built completely, the building script would copy the whole "${EXTRA_SOURCE}"
 source tree to the "Release/build" subdirectory, changes to that directory and
 executes the following command:

 	$ CC="${MARVELL_TOOLS}-gcc" \
           CXX="${MARVELL_TOOLS}-g++" \
           AS="${MARVELL_TOOLS}-as" \
           LD="${MARVELL_TOOLS}-ld" \
           RANLIB="${MARVELL_TOOLS}-ranlib" \
           AR="${MARVELL_TOOLS}-ar" \
           TOOLS="${MARVELL_TOOLS}" \
           make

     The building script doesn't know how to build the extra packages, and only
 pass the tool names to "make".  "Makefile" directs everything.
 "${MARVELL_TOOLS}" may be the prefix of installed bin with the full path, e.g.

 	$ export MARVELL_TOOLS=/tools/Release/install/armv7-marvell-eabi-softfp_x86_64/bin/arm-marvell-eabi

 If anything is O.K., there sould be new generated static "lib*.a" files.  The
 building script would copy them to the toolchain's installing directory.

     Note that the names of the generated "lib*.a" cannot conflict with the
 existing libraries, e.g. "libc.a", "libm.a", etc.  I suggest that the prefix
 name is leading with "libmrvl-", i.e. "libmrvl-${EXTRA}.a".

     For O.S. execution environment, e.g. Linux, the extra libraries should be
 compiled to PIC code if they are linked into the shared library.


 --------------------------------------------------------------------------------
 3. Predefined Macros
 --------------------------------------------------------------------------------

     The extra library may only be compiled and used under some limited
 conditions.  The programmers should consider the following conditions:

 	0. ARMv5te, ARMv7a, or others
 	1. ARM code, THUMB1 or THUMB2 code
 	   (We may only support ARM code now.)
 	2. non-VFP, VFP variants (e.g. v3-d16, v3, v4), NEON, WMMXT
 	   or Marvell-defined instructions
 	3. linux-gnueabi or eabi
 	4. soft, softfp or hard floating-abi
 	5. little-endian, big-endian including BE32 and BE8
 	6. non-PIC or PIC code
 	   (We may only support non-PIC code now.)
 	7. ..., etc.

     The authors of the extra library may use gcc's predefined macros to limit
 the compiled code.  Use the following command to see all of the gcc's
 predefined macros:

 	$ echo | ${MARVELL_TOOLS}-gcc -E -dM -

     The following predefined macros may be useful for coding:

 . ARM arch5te v.s. arch7a

 #define __ARM_ARCH_5TE__ 1	/* for arch5te */
 #define __ARM_ARCH_7A__ 1	/* for arch7a */

 . -mfloat-abi=soft

 #define __ARM_PCS 1		/* -mfloat-abi=soft/softfp */
 #define __SOFTFP__ 1		/* for non-VFP/NEON */

 . -mfloat-abi=softfp

 #define __ARM_PCS 1		/* -mfloat-abi=soft/softfp */

 . -mfloat-abi=hard

 #define __ARM_PCS_VFP 1		/* --mfloat-abi=hard */

 . Thumb code

 #define __thumb__ 1		/* for thumb1 or thumb2 code */
 #define __thumb2__ 1		/* only for Thumb2 code */

 . Little endian v.s. big endian

 #define __ARMEL__ 1		/* for Little endian */
 #define __ARMEB__ 1		/* for BE32 of arch-v5 or BE8 of arch-v7 */

 . VFP support

 #define __VFP_FP__ 1

 . NEON support

 #define __ARM_NEON__ 1

 . WMMX support

 #define __ARM_IWMMXT__ 1


 --------------------------------------------------------------------------------
 4. Notes
 --------------------------------------------------------------------------------

 . The extra packages are used to replace some routines of the standard
   libraries, especially for "libc.a" or "libm.a".  Please don't put other
   non-standard routines to them.


 . The document of the extra package, i.e. "${EXTRA_SOURCE}/README", should
   describe this extra package detailly, including:

   - About the author, email address, SOC teams, etc..

   - For what platform, execution environment, usage, limitation, and other
     detail description.

   - How to run the test cases in the "${EXTRA_SOURCE}/testsuite/" subdirectory.


 . "${EXTRA_SOURCE}/testsuite/" subdirectory should provide the test cases and
   running scripts for QA.


 . It's better if "${EXTRA_SOURCE}/Makefile" provides "$ make clean" command to
   cleanup generated files including object, ar, intermediate files, etc.


 . If the extra library wants to replace some standard C routines, follow
   the ANSI C requirement.  For example:

 	void *memcpy(void *dest, const void *src, size_t n);

   "memcpy" must return the pointer "dest".


 . Because the extra libraries are very very special for various targets on
   different execution environments, users should make sense about the correct
   usage on the correct environments.  For an example, it may be O.K. for eabi,
   but not for linux-gnueabi.


	Extra Libraries for Various Platforms
	=====================================

	1. Concept
	2. Source Code Layout
	3. Predefined Macros
	4. Notes





	--------------------------------------------------------------------------------
	1. Concept
	--------------------------------------------------------------------------------

	There are many requests from various SOC teams to integrate the platform-
	dependent-optimized routines into the Marvell GCC Toolchain. Most of them are
	memory handling routines, such as "memcpy", "memset", "strcmp", etc. There are
	no good reasons to merge all of them into the standard library, especially libc,
	and make things worse if we do so. It's better to stand these routines alone
	for the users who need them.

	We don't change the standard libraries, and let users select alternative
	platform-dependent-optimized routines and replace the standard ones. Take
	an example. There is a special tuned "libmrvl.a" containing "memcpy". Users
	can link this extra library first instead of the libc.

	$ arm-marvell-eabi-gcc foo.c -lmrvl

	Since the extra libraries are tuned for some platforms especially, users
	should know what correct platforms they are tuned for. Different extra
	libraries may not be suitable for each platform and misusing maybe make the
	program running slowly or crash even more worse.

	We would collect all the extra library packages including the source,
	"Makefile", "README", "testsuite", etc, and place them in the source tree of
	the Marvell GCC Toolchain:

	${MARVELL_TOOLCHAIN_SOURCE}/src/extra-src/${EXTRA_SOURCE}/

	"${MARVELL_TOOLCHAIN_SOURCE}" is the path of the source and scripts of the
	Marvell GCC Toolchain. "${EXTRA_SOURCE}" is the path name of the extra
	package tuned for a special platform.

	The toolchain's building script will invoke "make" to build the extra
	static libraries and copy them to the Marvell GCC Toolchain installing path.
	E.g.

	${MARVELL_TOOLCHAIN_INSTALL}/armv5-marvell-eabi-softfp_x86_64/
	arm-marvell-eabi/lib/lib${EXTRA}.a

	"${MARVELL_TOOLCHAIN_INSTALL}" is the installing path of the Marvell GCC
	Toolchain. "lib${EXTRA}.a", e.g. "libmrvl.a" example, is the static tuned
	library. After that, users can link it by adding "-l${EXTRA}" option to link
	these extra routines.

	For simplicity, this work may only support the extra static library with
	the ARM (i.e. non-thumb) code of the platform-dependent-optimized routines.
	These routines are tuned for the various SOC targets and would take the place
	of some routines from the native standard libraries.





	--------------------------------------------------------------------------------
	2. Source Code Layout
	--------------------------------------------------------------------------------

	All of the extra package are collected to the ${EXTRA_SOURCE} subdirectory.
	The below listing shows where the extra source code is:

	${MARVELL_TOOLCHAIN_SOURCE} # Marvell-tuned GCC C/C++ Compiler Source Code
	\|
	+-- script # Building scripts and documents
	\|
	+-- src
	\| \|
	\| +-- ...-src # Individual package source, e.g. gcc,
	\| \| # binutils, glibc, etc.
	\| \|
	\| +-- extra-src # Collection of all extra packages from various
	\| \| # SOC teams.
	\| \|
	\| +-- README # i.e. this document.
	\| \|
	\| +-- ${EXTRA_SOURCE} # The extra package.
	\| \| \|
	\| \| +-- README # Document of this extra library.
	\| \| \|
	\| \| +-- Makefile # "make" script
	\| \| \|
	\| \| +-- .s, .S, .c, .C, ...
	\| \| \| # Source code, or puts them in the subdirectory.
	\| \| \|
	\| \| +-- testsuite # Subdirectory for test cases and running
	\| \| # scripts.
	\| \|
	\| +-- ... # Another extra package for alternative SOC.
	\|
	+-- Release # Toolchain's building and installing paths.
	+-- build
	+-- install

	The "${EXTRA_SOURCE}" should provide "Makefile" for building and detail
	"README" document. After all the packages of the Marvell GCC Toolchain are
	built completely, the building script would copy the whole "${EXTRA_SOURCE}"
	source tree to the "Release/build" subdirectory, changes to that directory and
	executes the following command:

	$ CC="${MARVELL_TOOLS}-gcc" \
	CXX="${MARVELL_TOOLS}-g++" \
	AS="${MARVELL_TOOLS}-as" \
	LD="${MARVELL_TOOLS}-ld" \
	RANLIB="${MARVELL_TOOLS}-ranlib" \
	AR="${MARVELL_TOOLS}-ar" \
	TOOLS="${MARVELL_TOOLS}" \
	make

	The building script doesn't know how to build the extra packages, and only
	pass the tool names to "make". "Makefile" directs everything.
	"${MARVELL_TOOLS}" may be the prefix of installed bin with the full path, e.g.

	$ export MARVELL_TOOLS=/tools/Release/install/armv7-marvell-eabi-softfp_x86_64/bin/arm-marvell-eabi

	If anything is O.K., there sould be new generated static "lib*.a" files. The
	building script would copy them to the toolchain's installing directory.

	Note that the names of the generated "lib*.a" cannot conflict with the
	existing libraries, e.g. "libc.a", "libm.a", etc. I suggest that the prefix
	name is leading with "libmrvl-", i.e. "libmrvl-${EXTRA}.a".

	For O.S. execution environment, e.g. Linux, the extra libraries should be
	compiled to PIC code if they are linked into the shared library.





	--------------------------------------------------------------------------------
	3. Predefined Macros
	--------------------------------------------------------------------------------

	The extra library may only be compiled and used under some limited
	conditions. The programmers should consider the following conditions:

	0. ARMv5te, ARMv7a, or others
	1. ARM code, THUMB1 or THUMB2 code
	(We may only support ARM code now.)
	2. non-VFP, VFP variants (e.g. v3-d16, v3, v4), NEON, WMMXT
	or Marvell-defined instructions
	3. linux-gnueabi or eabi
	4. soft, softfp or hard floating-abi
	5. little-endian, big-endian including BE32 and BE8
	6. non-PIC or PIC code
	(We may only support non-PIC code now.)
	7. ..., etc.

	The authors of the extra library may use gcc's predefined macros to limit
	the compiled code. Use the following command to see all of the gcc's
	predefined macros:

	$ echo \| ${MARVELL_TOOLS}-gcc -E -dM -

	The following predefined macros may be useful for coding:

	. ARM arch5te v.s. arch7a

	#define __ARM_ARCH_5TE__ 1 /* for arch5te */
	#define __ARM_ARCH_7A__ 1 /* for arch7a */

	. -mfloat-abi=soft

	#define __ARM_PCS 1 /* -mfloat-abi=soft/softfp */
	#define __SOFTFP__ 1 /* for non-VFP/NEON */

	. -mfloat-abi=softfp

	#define __ARM_PCS 1 /* -mfloat-abi=soft/softfp */

	. -mfloat-abi=hard

	#define __ARM_PCS_VFP 1 /* --mfloat-abi=hard */

	. Thumb code

	#define __thumb__ 1 /* for thumb1 or thumb2 code */
	#define __thumb2__ 1 /* only for Thumb2 code */

	. Little endian v.s. big endian

	#define __ARMEL__ 1 /* for Little endian */
	#define __ARMEB__ 1 /* for BE32 of arch-v5 or BE8 of arch-v7 */

	. VFP support

	#define __VFP_FP__ 1

	. NEON support

	#define __ARM_NEON__ 1

	. WMMX support

	#define __ARM_IWMMXT__ 1





	--------------------------------------------------------------------------------
	4. Notes
	--------------------------------------------------------------------------------

	. The extra packages are used to replace some routines of the standard
	libraries, especially for "libc.a" or "libm.a". Please don't put other
	non-standard routines to them.


	. The document of the extra package, i.e. "${EXTRA_SOURCE}/README", should
	describe this extra package detailly, including:

	- About the author, email address, SOC teams, etc..

	- For what platform, execution environment, usage, limitation, and other
	detail description.

	- How to run the test cases in the "${EXTRA_SOURCE}/testsuite/" subdirectory.


	. "${EXTRA_SOURCE}/testsuite/" subdirectory should provide the test cases and
	running scripts for QA.


	. It's better if "${EXTRA_SOURCE}/Makefile" provides "$ make clean" command to
	cleanup generated files including object, ar, intermediate files, etc.


	. If the extra library wants to replace some standard C routines, follow
	the ANSI C requirement. For example:

	void memcpy(void dest, const void *src, size_t n);

	"memcpy" must return the pointer "dest".


	. Because the extra libraries are very very special for various targets on
	different execution environments, users should make sense about the correct
	usage on the correct environments. For an example, it may be O.K. for eabi,
	but not for linux-gnueabi.