doc/doxygen/inside_extending.doc

   1 /*!
   2 \page inside_extending Extending SimGrid
   3
   4 We start to put TAGS in simgrid source code for having tutorials to see where is the important parts ans steps to create:
   5 \li a new MSG functions or a new API.
   6 \li a new model in surf.
   7 \li new tags in xml files
   8
   9 \section simgrid_dev_guide_api How to add a new MSG function?
  10 Search for expression \"TUTORIAL: New API\".
  11 \verbatim
  12 user@caraja:~/workspace/simgrid/src$ cg "TUTORIAL: New API"
  13  0 msg/msg_new_api.c             15 /* TUTORIAL: New API*/
  14  1 simix/smx_smurf.c            582 /* TUTORIAL: New API*/
  15  2 simix/smx_smurf.c            616 /* TUTORIAL: New API*/
  16  3 simix/smx_smurf_private.h    102 /* TUTORIAL: New API*/
  17  4 simix/smx_smurf_private.h    629 /* TUTORIAL: New API*/
  18  5 simix/smx_private.h           28 /* TUTORIAL: New API*/
  19  6 simix/smx_private.h          101 /* TUTORIAL: New API*/
  20  7 simix/smx_private.h          182 /* TUTORIAL: New API*/
  21  8 simix/smx_global.c           454 /* TUTORIAL: New API*/
  22  9 simix/smx_new_api.c            8 /* TUTORIAL: New API*/
  23 10 simix/smx_user.c            1684 /* TUTORIAL: New API*/
  24 11 simix/smx_new_api_private.h    8 /* TUTORIAL: New API*/
  25 12 simix/smx_process.c          338 /* TUTORIAL: New API*/
  26 \endverbatim
  27
  28 \section simgrid_dev_guide_model How to add a new model in surf?
  29 Search for expression \"TUTORIAL: New model\".
  30 \verbatim
  31 user@caraja:~/workspace/simgrid/src$ cg "TUTORIAL: New model"
  32 0 surf/new_model_private.h   2 /* TUTORIAL: New model
  33 1 surf/surf.c              213 /* TUTORIAL: New model*/
  34 2 surf/surf_config.c       380 /* TUTORIAL: New model*/
  35 3 surf/surf_config.c       746 /* TUTORIAL: New model*/
  36 4 surf/new_model.c           8 /* TUTORIAL: New model*/
  37 5 include/surf/surf.h      157 /* TUTORIAL: New model*/
  38 6 include/surf/surf.h      345 /* TUTORIAL: New model*/
  39 7 include/surf/surf.h      661 /* TUTORIAL: New model*/
  40 \endverbatim
  41
  42 \section simgrid_dev_guide_simcall How to add a new simcall?
  43 To add a simcall called `<name>` with three arguments `arg1`, `arg2` and `arg3`
  44 of type `targ1`, `targ2`, `targ3` respectively and which return a value of
  45 type `tret` you must first define the simcall function in the the
  46 `include/simgrid/simix.h` and make it call the automatically generated `BODY`
  47 function which will do all the bad stuff.
  48
  49 ~~~~{.c}
  50 tret simcall_<NAME>(targ1 arg1, targ2 arg2, targ3 arg3){
  51   return simcall_BODY_<NAME>(arg1, arg2, arg3);
  52 }
  53 ~~~~
  54
  55 Then you must add an new line in the list `SIMCALL_LIST1` of simcall actions in
  56 `src/simix/smx_smurf_private.h`. The arguments of the `ACTION` are:
  57 - the simcall enum name,
  58 - the `<name>` of the simcall,
  59 - if the result must be automatically saved in the simcall
  60  (`WITH_ANSWER`/`WITHOUT_ANSWER`)
  61 - the return type,
  62 - the arguments.
  63
  64 The return type and the arguments must be define by using `TSPEC(name, type)`,
  65 or one of the predefined type (e.g., `TSTRING(n)`, `TINT(n)`, `TVOID(n)`,
  66 `TPTR(n)`, …). You must get something like this:
  67
  68 ~~~~{.c}
  69 ACTION(SIMCALL_<NAME>, <name>, WITH_ANSWER, TSPEC(result, tret), TSPEC(arg1, targ1), TSPEC(arg2, targ2), TSPEC(arg3, targ3)) sep  \
  70 ~~~~
  71
  72 Finaly you have to define the kernel code in a `SIMIX_pre_<name>` in the
  73 corresponding src/simix/smx_*.c file:
  74
  75 ~~~~{.c}
  76 tret SIMIX_pre_<name>(smx_simcall_t simcall, targ1 arg1, targ2 arg2, targ3 arg3) {
  77   SIMIX_<NAME>(arg1, arg2, arg3);
  78 }
  79
  80 tret SIMIX_<name>(targ1 arg1, targ2 arg2, targ3 arg3) {
  81   // Your code in kernel mode
  82 }
  83 ~~~~
  84
  85 \section simgrid_dev_guide_tag What is How to add a new tag for xml files?
  86 Search for expression \"TUTORIAL: New TAG\".
  87 \verbatim
  88 user@caraja:~/workspace/simgrid/src$ cg "TUTORIAL: New TAG"
  89 0 surf/sg_platf.c                    43 /* TUTORIAL: New TAG*/
  90 1 surf/sg_platf.c                    89 /* TUTORIAL: New TAG*/
  91 2 surf/sg_platf.c                   124 /* TUTORIAL: New TAG*/
  92 3 surf/sg_platf.c                   337 /* TUTORIAL: New TAG*/
  93 4 surf/surfxml_parse.c              769 /* TUTORIAL: New TAG*/
  94 5 surf/surf_private.h               205 /* TUTORIAL: New TAG*/
  95 6 surf/surfxml_parseplatf.c          64 /* TUTORIAL: New TAG*/
  96 7 surf/surfxml_parseplatf.c          85 /* TUTORIAL: New TAG*/
  97 8 include/simgrid/platf_interface.h  42 /* TUTORIAL: New TAG*/
  98 \endverbatim
  99 */