Changes between Version 9 and Version 10 of BuildSystemDev

Timestamp:

Dec 18, 2012, 4:20:23 PM (11 years ago)

Author:

becoulet

Comment:

init tokens stuff

BuildSystemDev

@@ -139 +139 @@
 Having all modules and features initialized in proper order is challenging in a modular and configurable project like MutekH.
 
-The configuration tool offers a way to specify initialization code ordering constraints and to optionally associate them to configuration tokens.
+The configuration tool offers a way to specify initialization code ordering constraints and to associate them to configuration tokens.
 This has several advantages:
  * It allows inserting external modules initialization code in the right place without patching the main tree.
  * It avoids the burdensome work of maintaining initialization function calls and associated `#ifdef` directives.
- * It ensures initialization function invocations do not get badly reordered to satisfy a new constraint, while ignoring an older constraint.
+ * It ensures initialization function invocations do not get badly reordered to satisfy a new constraint, while ignoring an older constraints.
 
 Initialization tokens can be declared for that purpose, each specifying a different stage in the MutekH initialization process.
-These tokens live in a separate name space from configuration tokens and are not exported in the configuration output.
+These tokens live in a separate name space from configuration tokens and are not exported in the configuration header output.
 Instead a set of function prototypes and properly ordered function calls code are written as C macros which can then be invoked at the right place in the kernel code.
 An error will be emitted if constraints can not be satisfied.
 
+The MutekH startup process based on this tool is described in the KernelStartUp page.
+
 === Constraint tags ===
 
 For each configuration token, one may use the following tags:
  `parent CONFIG_TOKEN`::
-   When this tag is present, the initialization rules described in the block are ignored if the associated configuration token is undefined.
+   Defines the parent configuration token associated to the initialization token. The initialization is disabled if the associated configuration token is not defined.
+ `condition CONFIG_TOKEN_CONDITION […]`::
+   This tag can be used to define some conditions which have to be true for the initialization to actually take place. When Multiple condition tag lines are specified, the initialization token is enabled if at least one of lines define a set of conditions which are all true.
  `after INIT_TOKEN`::
    This tag imposes the requirement that the code from current token be executed '''after''' the code associated with INIT_TOKEN.
@@ -160 +164 @@
    This tag imposes the requirement that the code from current token be executed '''before''' the code associated with INIT_TOKEN.
  `during INIT_TOKEN`::
-   This tag makes the current token inherits from constraints expressed for the given INIT_TOKEN. This token must be a place holder token and can not have associated functions.
- `functions init_function_name cleanup_function_name`::
-   This tag associates some initialization and cleanup C function names to the token. The cleanup function is optional.
+   This tag makes the current token inherits from constraints expressed for the given INIT_TOKEN. This tag is used to define a hierarchy between initialization tokens.
+ `function init_function_name cleanup_function_name`::
+   This tag associates some initialization and cleanup C function names to the token. The cleanup function is optional. When this tag is not present, the token is a place holder token.
  `prototype type arg0, type *arg1`::
-   This tag sets a list of arguments used in init and cleanup functions prototypes. It must be used on the root place holder tokens so that the prototype is valid for all functions of children tokens.
-
+   This tag sets a list of arguments used as init and cleanup functions prototype. It may be used on place holder tokens so that the prototype is valid for all function provided by inheriting tokens in the hierarchy.
+ `flags calls`::
+   This flag specifies that C macros with names such as `token_PROTOTYPES`, `token_INIT` and `token_CLEANUP` must be generated. The generated macros contain prototypes and function calls for all enabled inheriting tokens.
+ `flags notempty`::
+   This flag can be used to prevent an initialization stage to be empty. When this flag is present and the token is enabled, at least one function call must be generated by an other enabled inheriting token in the hierachy.
 === Example ===
 
@@ -171 +178 @@
 {{{
 %init INIT_LIBRARIES
+  parent CONFIG_MUTEK
   after INIT_SCHEDULER
   before INIT_APPLICATION
+  flags calls
 %init end
 }}}
@@ -180 +189 @@
   during INIT_LIBRARIES
   after INIT_LIBC_STDIO      # an explanation why this is needed
-  functions great_feature_init great_feature_cleanup
+  function great_feature_init great_feature_cleanup
 %init end
 }}}
 
-This will generate the following macros for use in MutekH source code, provided that the CONFIG_FEATURE token is defined in build configuration:
+This will generate the following C macros for use in the kernel source code, provided that the CONFIG_FEATURE token is defined in the build configuration:
 
 {{{
@@ -197 +206 @@
   great_feature_claenup(__VA_ARGS__); \
 }}}
+
+The BuildSystem page describes how to display active intialization tokens for a given configuration along with function calls order and tokens hierarchy.
 
 = Source tree `Makefile` syntax and rules =