Author Topic: MultiStart  (Read 5973 times)

Offline hervé

  • Jr. Member
  • **
  • Posts: 98
    • View Profile
MultiStart
« on: November 03, 2009, 10:35:36 AM »
Hello,
Where can I find some documentation and source code, on how to use multistart specialy new_hw_init function ?

Offline mark

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3234
    • View Profile
    • uTasker
Re: MultiStart
« Reply #1 on: November 03, 2009, 09:47:51 PM »
Hi Hervé

There is no documentation about the MULTISTART function so I will write something here:

1) Without MULTISTART the scheduler is configured and started and never stops (until a reset of course).

2) With MULTISTART the scheduler starts in the same manor but, after each schedule of the tasks in the task list, returns with a pointer [MULTISTART_TABLE *]. As long as this pointer remains at its default value of 0 the scheduling is repeated. Therefore there is no difference to the case in 1).

3) However the application which is presently running can decide that it wants to move to a new configuration (typically a boot phase can be followed by an application phase, but also application phases can change). The application that is running needs to modify the pointer MULTISTART_TABLE *ptMultiStartTable by setting it to a corresponding table containing information about the next configuration.
Exactly where this table comes from depends on the application itself but I use the technique in projects which can exchange applications (without necessarily exchanging the OS, stack, etc.) and the table is often embedded in a file which is uploaded to the target later.

Example:
static MULTISTART_TABLE testTable = {
test_new_hw_init,
(HEAP_NEEDS*)&ctOurHeap,
(UTASKTABLEINIT*)&ctTaskTable,
(const CHAR*)&ctNodes};


The table has several defined entries, which are pointers to a list of heap requirements, a new task table and a new node list (as used by a standard project - see TaskConfig.h). The first entry is a pointer to an optional routine (*(*new_hw_init)(JUMP_TABLE *); or *(*new_hw_init)(JUMP_TABLE *, void **, unsigned char);, when DYNAMIC_MULTISTART is configured). I won't discuss DYNAMIC_MULTISTART since it is almost never used.

Based on the pointers in the table the OS will re-initialise HEAP, the task table etc. and then start scheduling the new application configuration. The process can also be repeated if the new application returns a new table pointer.

4) The routine test_new_hw_init(), which you are interested in, is optional in the table - it can be set to zero if no execution is desired. However the routine is called before the new table is used - this means that the variables and configuration of the original application are still valid but a pre-defined routine from the new application is called before the new application is configured.
This routine can be useful to initialise variables to be used by the new application, but specifically it is passed a pointer to a JUMP_TABLE, which has a default value 0, but can be modified by the original application. It is intended for use to pass a list of subroutines belonging to the original application which can then be used by the new application if it desires (for example OS or library calls which are fixed in the code of the first application - the new application will probably make a copy of the list for its own use). Since it is a pointer it can also be 'misused' to pass other information - eg. the location of a bit map image or font table in the first application code which may be of use to the second one, etc.).

This feature is not well known and also now used much, but it can and has been very useful in various projects. It depends on the application whether it offers any benefits. It can also be a little tricky to use and that is probably the main reason why it is a little hidden - and undocumented ;-)

Regards

Mark