| Summary: | Document tune files / variables | ||
|---|---|---|---|
| Product: | [Documentation] Reference | Reporter: | Paul Eggleton <bluelightning> |
| Component: | handbook | Assignee: | Scott Rifenbark <srifenbark> |
| Status: | RESOLVED FIXED | QA Contact: | |
| Severity: | enhancement | ||
| Priority: | Medium | CC: | bluelightning, jessica.zhang, mark.hatle, poky.doc.watcher, poky.watcher, srifenbark |
| Version: | unspecified | ||
| Target Milestone: | 1.8 M4 | ||
| Hardware: | All | ||
| OS: | Multiple | ||
| Whiteboard: | 17 March 2015: RESOLVED | ||
| OS type for building Yocto: | --- | Type of Regression: | --- |
| Verified: | Documentation change: | Done (doc changes complete) | |
|
Description
Paul Eggleton
2013-11-05 10:34:48 UTC
Hi, I don't understand the tuning concept in general. We could start by getting me a general overview or explanation of how the whole thing works. Thanks, Scott See the README files in the tree: General variable docs: http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/documentation.conf Generic TUNE information: http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/README ARM Specific: http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/arm/README IA32 Specific: http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/ia32/README MIPS Specific: http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/mips/README Power Specific: http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/powerpc/README SH Specific: http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/sh/README For items that are not in the README files, we should add additional documentation to both the TUNE README file(s) and the product docs. Thanks Mark... good starting point. Scott Enhancement - moving to 1.7 Setting milestone to M3 for 1.7. Hi, So the README files are helpful for basic variable descriptions, which is what I would like to nail down first. Couple questions to resolve the variable definitions..... * The general README and the list of variables that Paul suggested in Bug Description comprise the following: TUNE_ARCH TUNE_CCARGS (We have this already in the glossary) TUNE_LDARGS (No description in the README) TUNE_ASARGS (No description in the README) TUNE_FEATURES AVAILTUNES DEFAULTTUNE TUNEVALID TUNECONFLICTS TARGET_CC_KERNEL_ARCH (No description in the README) TUNEABI ? (No description in the README) TUNEABI_OVERRIDE ? (No description in the README) TUNEABI_WHITELIST ? (No description in the README) ABIEXTENSION TUNE_PKGARCH (We have this in the glossary already) PACKAGE_EXTRA_ARCHS (We have this in the glossary already) PACKAGE_EXTRA_ARCHS_tune (Not sure if this can be incorporated into the above) TARGET_FPU (We have this in the glossary) BASE_LIB I need descriptions for many of these. * Also, there are sub-directories in http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/. They map mostly to what Mark listed out in Comment 2. However, the link Mark used for IA32 specific is bogus. I assume that would be "x86" sub-directory. The point of this question is that each of the README files in these sub-directories lists additional tuning variables presumably specific to that architecture. For example, the sub-directory for ARM (http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/arm/README) has a README that overviews the following variables: ARMPKGARCH ARMPKGSFX_THUMB ARMPKGSFX_DSP ARMPKGSFX_EABI ARMPKGSFX_ENDIAN ARMPKGSFX_FPU Do we need to document all these architecture specific variables in the ref-manual glossary? Changing bug status back to NEEDINFO for now. Thanks, scott (In reply to comment #6) > * The general README and the list of variables that Paul suggested in Bug > Description comprise the following: > > TUNE_ARCH TUNE_ARCH becomes the 'TARGET_ARCH'. So the description is more or less the same: TARGET_ARCH[doc] = "The architecture of the device being built. The OpenEmbedded build system supports the following architectures: arm, mips, ppc, x86, x86-64." The only difference is that the 'TUNE' version is specific to the tune, and eventually becomes the TARGET_ARCH. > TUNE_CCARGS (We have this already in the glossary) > TUNE_LDARGS (No description in the README) > TUNE_ASARGS (No description in the README) Each of the 'ARGS' items can be built up using a number of mechanisms. The LDARGS and the ASARGS and the same as the 'CC' args, only they affect either the linker or the assembler. Note, it's pretty rare that any special arguments are needed there... but occasionally a specific configuration may require them. TARGET_CC_ARCH = TUNE_CCARGS TARGET_AS_ARCH = TUNE_ASARGS TARGET_LD_ARCH = TUNE_LDARGS (HOST_*_ARCH = TARGET_*_ARCH by default) which eventually becomes: export CC = "${CCACHE}${HOST_PREFIX}gcc ${HOST_CC_ARCH}${TOOLCHAIN_OPTIONS}" export CXX = "${CCACHE}${HOST_PREFIX}g++ ${HOST_CC_ARCH}${TOOLCHAIN_OPTIONS}" export FC = "${CCACHE}${HOST_PREFIX}gfortran ${HOST_CC_ARCH}${TOOLCHAIN_OPTIONS}" export CPP = "${HOST_PREFIX}gcc -E${TOOLCHAIN_OPTIONS} ${HOST_CC_ARCH}" export LD = "${HOST_PREFIX}ld${TOOLCHAIN_OPTIONS} ${HOST_LD_ARCH}" export AS = "${HOST_PREFIX}as ${HOST_AS_ARCH}" So each of these items become a "required" set of arguments to the compiler, linker or assembler in order to produce the correct executables. > TUNE_FEATURES These are the 'features' specific to a tune. The features are defined within the tune files and allow various actions (such as the TUNE_*ARGS to be dynamically generated based on 'features'. Features are also verified, that conflicting features are not set together, and that only supported features are permitted. > AVAILTUNES Overall list of tunes that have been defined. There is nothing that indicates that the tunes may or may not be compatible with each other. > DEFAULTTUNE This is set by the machine (either implicitly, or explicitly) as the default tune to be used. The user can override this with one of the available tunes if desired. Again, no indication of compatibility is intended in the AVAILTUNES. > TUNEVALID TUNEVALID[feature] lists the valid features > TUNECONFLICTS TUNECONFLICTS[feature] lists features that conflict with this one. > TARGET_CC_KERNEL_ARCH (No description in the README) This is a specific kernel CC flags for a tune. Rarely used, but occasionally a userspace TUNE_CCARGS is not compatible with the kernel compilation. This allows the kernel (and associated modules) to use a different configuration. > TUNEABI ? (No description in the README) > TUNEABI_OVERRIDE ? (No description in the README) > TUNEABI_WHITELIST ? (No description in the README) I'm working on a patch to these items and will update the README to match. The simple answer is these are used to document what is supported and what is not supported. If they are not defined (the default) then -everything- is allowed. These are primarily used by binary toolchain vendors, or OSVs to restrict access to unsupported tune content. > ABIEXTENSION Extension to the ABI field of the gnu canonical arch name, such as 'eabi'. > TUNE_PKGARCH (We have this in the glossary already) > PACKAGE_EXTRA_ARCHS (We have this in the glossary already) > PACKAGE_EXTRA_ARCHS_tune (Not sure if this can be incorporated into the > above) These are the tune specific versions of the PACKAGE_EXTRA_ARCHs. > TARGET_FPU (We have this in the glossary) > BASE_LIB BASE_LIB is the library directory name for the tune. If multilibs are enabled the BASE_LIB will be used, otherwise 'lib' is the default name. > I need descriptions for many of these. > > * Also, there are sub-directories in > http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/ > include/. They map mostly to what Mark listed out in Comment 2. However, > the link Mark used for IA32 specific is bogus. I assume that would be "x86" > sub-directory. The point of this question is that each of the README files Yes, x86 is the current name of the directory. > in these sub-directories lists additional tuning variables presumably > specific to that architecture. For example, the sub-directory for ARM Correct. > (http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/ > include/arm/README) has a README that overviews the following variables: > > ARMPKGARCH > ARMPKGSFX_THUMB > ARMPKGSFX_DSP > ARMPKGSFX_EABI > ARMPKGSFX_ENDIAN > ARMPKGSFX_FPU > > Do we need to document all these architecture specific variables in the > ref-manual glossary? For those items, I'd simply refer the user to where the README file is and explain that there may be architecturally specific entries as well. Scott, does this need to still be in NEEDINFO, it appears Mark supplied an answer. Thanks for the details Mark. I am setting to IN PROGRESS DESIGN NOW, which for me means I will be getting to it. Scott Hi, I have made some progress on this big issue by first attempting some new variable descriptions. After these settle out, I will add a section on tuning concepts in the "Technical Details" chapter of the reference manual. That is where we will describe overall concepts, etc. I am leaving the architecture-specific variable (e.g. ARMPKGARCH, ARMPKGSFX_THUMB, ARMPKGSFX_DSP, ARMPKGSFX_EABI, ARMPKGSFX_ENDIAN, ARMPKGSFX_FPU, and so forth) concept for that section. We will not add those specific variables to the glossary. For now, I need to get these new variables reviewed and correct. I made many assumptions as I wrote these. I used a combination of Mark's explanations, git grep results within poky, and README files to try and see how and where these variables are used. Here are some links for review: TUNE_ARCH - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TUNE_ARCH TARGET_AS_ARCH - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TARGET_AS_ARCH TUNE_ASARGS - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TUNE_ASARGS TARGET_LD_ARCH - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TARGET_LD_ARCH TUNE_LDARGS - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TUNE_LDARGS TUNE_FEATURES - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TUNE_FEATURES AVAILTUNES - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-AVAILTUNES DEFAULTTUNES - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-DEFAULTTUNES TUNEVALID[feature] - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TUNEVALID TUNECONFLICT[feature] - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TUNECONFLICT TARGET_CC_KERNEL_ARCH - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TARGET_CC_KERNEL_ARCH TUNEABI - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TUNEABI TUNEABI_OVERRIDE - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TUNEABI_OVERRIDE TUNEABI_WHITELIST - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TUNEABI_WHITELIST ABIEXTENSION - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-ABIEXTENSION TUNE_PKGARCH_tune - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-TUNE_PKGARCH_tune BASE_LIB - http://www.yoctoproject.org/docs/1.7/ref-manual/ref-manual.html#var-BASE_LIB Hi, I need a review on these variables. Scott Changed the milestone to M4. Could still use a review on these changes. I am leaving as IN PROGRESS REVIEW. Scott I am setting this target to 8.1 M2. It still needs some review on the variables added and a section on tuning. Scott That would be 1.8 not 8.1 Scott Mark, I updated the TUNE_ASARGS, TUNE_CCARGS, and TUNE_LDARGS variables to expand on the note to indicate more about the BSP selecting the tune and the selected tuning as affecting the tune variables. See http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-TUNE_ASARGS, http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-TUNE_CCARGS, and http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-TUNE_LDARGS for the changes. I also removed the TUNE_PKGARCH_tune variable and combined that information into the TUNE_PKGARCH variable. I think Paul mentioned to me a while back that we really did not need to have TUNE_PKGARCH_tune called out as a separate variable as it is really TUNE_PKGARCH with the override. I combined up the information and got the general syntax in there you indicated in your email to me. See http://www.yoctoproject.org/docs/1.8/ref-manual/ref-manual.html#var-TUNE_PKGARCH for the changes. Let me know if these are okay. Scott Updating milestone to M4. I will not get anywhere on this until I get a review of what is there. Scott Hi, No further feedback on this issue since January when I added the tune variable glossary final touches. If you want further tune documentation then open a new bug for 1.9. Setting this bug to RESOLVED and the doc flag to "done." Thanks, Scott |