home *** CD-ROM | disk | FTP | other *** search
/ Fish 'n' More 2 / fishmore-publicdomainlibraryvol.ii1991xetec.iso / fish / languages / dice_443 / dice.lzh / doc / EXTENSIONS.DOC < prev    next >
Text File  |  1991-01-14  |  11KB  |  283 lines
  1.  
  2. extensions/extensions                    extensions/extensions
  3. extensions/EXTENSIONS                    extensions/EXTENSIONS
  4.  
  5.                    COMPILER EXTENSIONS
  6.  
  7.                  AUTO LIBRARY OPENNING
  8.  
  9.     Certain Amiga libraries are supported on an autoinit basis.  Normally
  10.     you declare the library base variable then OpenLibrary() it in your
  11.     main.
  12.  
  13.     If you EXTERN the library base variable instead then it will be brought
  14.     in from auto.lib along with autoinit code to automatically
  15.     OpenLibrary() it on startup and CloseLibrary() it on shutdown.
  16.     Currently, dos.library, intuition.library, graphics.library, and the
  17.     floating point libraries work this way.
  18.  
  19.     You can tell when the autoinit feature is not supported for a given
  20.     library base variable when the linker comes up with an 'undefined symbol'
  21.     error for base variable name.
  22.  
  23.            TYPE QUALIFIER AND STORAGER QUALIFIER EXTENSIONS
  24.  
  25.     availability:   reg-only = registered users
  26.  
  27.  
  28.     extension    avail        comment
  29.  
  30.     volatile    all        force auto's to NOT be placed in registers
  31.     const    all        place data items in the code section (see -ms/-mS)
  32.     __autoinit    all        cause a subroutine to be run automatically
  33.                 before _main (for variables, puts variable in
  34.                 alternate section)
  35.     __autoexit    all        cause a subroutine to be run automatically
  36.                 before _exit
  37.     __interrupt all        NOT AMIGA COMPATIBLE
  38.     __chip    reg-only    cause storage to be placed in CHIP memory
  39.     __far    all        cause storage to be referenced using absolute-long
  40.     __near    all        cause storage to be referenced using A4-relative
  41.     __aligned    all        cause storage to be aligned on a longword boundry
  42.     __unaligned all        allows structures to be byte-aligned (at your own risk)
  43.     __geta4    reg-only    cause a subroutine to setup the A4 data base
  44.                 pointer
  45.  
  46.     __shared    all        storage is placed in the code section and thus
  47.                 is shared between instances of a resident'd
  48.                 program.
  49.  
  50.     __config    all        storage is automatically loaded on startup and
  51.                 saved on exit to a configuration file.
  52.  
  53.     __regargs    reg-only    specify function takes registered arguments
  54.                 even if -mr/-mR/-mRR is not used.
  55.  
  56.     __stkargs    reg-only    specify function takes normal stack based
  57.                 args despite the possibility that -mr/-mR/-mRR
  58.                 has been specified.
  59.  
  60.     volatile
  61.     This storage qualifier normally specifies that the physical storage
  62.     is 'synched' at the end of each line of C code.  DICE already does
  63.     this by virtue of not doing any major optimizations.  Under ANSI
  64.     this storage qualifier also forces auto variables to NOT be placed
  65.     in a register.    This can be important if you use <setjmp.h>
  66.     (see MAN/SETJMP.DOC for more information)
  67.  
  68.     const
  69.     The const type qualifier can be handled in different ways by DICE.
  70.     As of the 2.05.11 version of DC1, any const qualified object is
  71.     placed in the code section.  Before 2.05.11 const qualified
  72.     objects were only placed in the code section if -ms or -mS was
  73.     also given to DCC.
  74.  
  75.     Normally a const qualified item is handled as a near item (pc-rel)
  76.     within the module that declares it, and handled with absolute-long
  77.     references in modules that extern it.
  78.  
  79.     If -ms is used then string constants are made const.  If -mS is
  80.     used then all external references to const items use pc-relative
  81.     instead of the absolute-long addressing mode.  Do NOT use -mS
  82.     unless your final code size is less than 32KBytes.
  83.  
  84.     Using -ms can substantially reduce the number of run-time
  85.     relocations for -r residentable programs as well as the run-time
  86.     dynamically allocated data+bss space.
  87.  
  88.     (refer to DCC.DOC, -ms and -mS options for details)
  89.  
  90.     __autoinit
  91.     __autoexit
  92.  
  93.     These storage qualifiers cause a routine to be called after libraries
  94.     are openned before _main is called (__autoinit), and just before
  95.     libraries are closed after _exit is called (__autoexit).  They may
  96.     be used for low level initialization and shutdown and may not make
  97.     any c.lib calls (i.e. malloc, fopen, open, etc... may not be called)
  98.  
  99.     __autoinit void
  100.     fubar()
  101.     {
  102.         NewList(&MyList);
  103.     }
  104.  
  105.     __autoinit may be used with a variable declaration.  The variable
  106.     is placed in an alternate section.  This is mainly of use for
  107.     ROMable applications to group declared data together, with a base
  108.     section pointer in the ROM startup object and a 'terminator'
  109.     in the last object module.  For example, a 'ROM MODULE LIST' may
  110.     be constructed painlessly using this feature.
  111.  
  112.     __autoinit int a;        /*    altbss,bss    */
  113.     __autoinit int a = 4;        /*    altdata,data    */
  114.     __autoinit const int a;     /*    altcode,code    */
  115.     __autoinit const int a = 4; /*    altcode,code    */
  116.  
  117.     SUGGESTION:  use dcc -a to oberve the assembly generated.  Note
  118.     that BSS data verses INITIALIZED data go into different sections.
  119.  
  120.     __interrupt
  121.  
  122.     This storage qualifier for a subroutine causes all used registers to
  123.     be saved and restored, including the scratch registers, and returns
  124.     via RTE instead of RTS.
  125.  
  126.     THIS KEYWORD IS NOT AMIGA COMPATIBLE
  127.  
  128.     __chip
  129.  
  130.     This storage qualifier forces a static or global data item to be
  131.     placed in CHIP memory.    Normally this precludes being able to make
  132.     such programs resident (-r option), but if you also use the -ms
  133.     option and the 'const' type qualifier you can make such programs
  134.     resident....  The 'const' type qualifier assumes that the contents
  135.     of the object will NEVER be modified!!!
  136.  
  137.     __chip short ImageData[] = { ... };        read-write object
  138.     __chip const short ImageData[] = { ... };   read-only object
  139.  
  140.     __far
  141.  
  142.     __far int a;
  143.  
  144.     This storage qualifier determines how a data object is to be
  145.     referenced.  It overides the data model for the reference and
  146.     forces the ABSOLUTE-LONG addressing mode to be used.
  147.  
  148.     Note that __chip data is automatically forced to be __far.
  149.     When compiling -mD the default is to use __far references.
  150.  
  151.     __near
  152.  
  153.     __near int a;
  154.  
  155.     This storage qualifier forces a small-data model (A4-Relative)
  156.     reference to a data object.  When using the -md (default) data
  157.     model data objects are accessed as near items by default.
  158.  
  159.     __aligned
  160.  
  161.     This storage qualifier forces the static, global, or auto data
  162.     object to be aligned on a longword boundry.
  163.  
  164.     foo()
  165.     {
  166.         __aligned struct FileInfoBlock fib;
  167.         ...
  168.     }
  169.  
  170.     WARNING:    __aligned does not work if this subroutine or any
  171.     higher level subroutine is passed a *structure* where said
  172.     structure is not aligned.  We are talking about passing actual
  173.     structures here, not pointers to structures (which work fine
  174.     with __aligned).
  175.  
  176.     __unaligned
  177.  
  178.     This storage qualifier allows structures to be byte-aligned in
  179.     terms of NOT padding them to the nearest word or longword.
  180.  
  181.         __unaligned struct foo {
  182.         char a;
  183.         } a, b, c;
  184.  
  185.     In the above example, sizeof(a), sizeof(b), and sizeof(c) is 1.
  186.  
  187.     USE AT YOUR OWN RISK.  Accessing word/long/ptr items at odd
  188.     byte addresses is illegal for the 68000 and will generate an
  189.     exception.  This qualifier is useful mainly for character
  190.     structures that must map over a text file.
  191.  
  192.     __geta4
  193.  
  194.     This storage qualifier on a subroutine definition forces the
  195.     subroutine to save A4 and then load A4 with the small-data model
  196.     data pointer on subroutine entry, then restore the original
  197.     contents of A4 on subroutine exit.  This is useful for
  198.     inter-context calls when using the small-data model.
  199.  
  200.     __geta4 void
  201.     fubar()
  202.     {
  203.  
  204.     }
  205.  
  206.     Unfortunately, using this qualifier precludes being able to
  207.     generate a residentable executable since a residentable
  208.     executable's data space pointer is unknown at link time.
  209.  
  210.     __shared
  211.  
  212.     This storage modifier places the global or static variable
  213.     declaration into the code segment, thus this variable will be
  214.     SHARED across multiple running instances of the same program,
  215.     assuming the program has been made RESIDENT.  A program that has
  216.     not been made resident will not share variables.
  217.  
  218.     __config
  219.  
  220.     This storage modifier generates loading and saving code for all
  221.     variables in question.    You should not declare any pointers as
  222.     a saved pointer value will not be valid when the program is run
  223.     later on.
  224.  
  225.     If no configuration file exists the initialized value of the static
  226.     or global storage is used, for example:
  227.  
  228.         __config int a = 34;
  229.  
  230.     'a' will be 34 if no configuration file exists.  If a configuration
  231.     file does exist all __config variables will be overriden with the
  232.     values stored in the configuration file.
  233.  
  234.     The name and version of the configuration file must be specified
  235.     by the programmer as two initialized global variables or a link
  236.     error will occur.  For example:
  237.  
  238.         char *ConfigFile = "s:myprog.config";
  239.         long ConfigVersion = 1;
  240.  
  241.     DICE configuration code will automatically ignore any configuration
  242.     file whos version does not equal ConfigVersion.  As a programmer,
  243.     you must change ConfigVersion if you modify ANY __config
  244.     declaration, the ordering of any __config declaration, or the
  245.     ordering of any object modules in your link.  If you fail to do so,
  246.     the program may attempt to load an invalid configuration.
  247.  
  248.     The configuration is automatically loaded on program startup,
  249.     before _main() (__main from assembly) gets run, and if ConfigFile
  250.     is non-NULL on program exit (_exit) then the configuration will be
  251.     saved.     Thus, __config is supported even if you use the _main()
  252.     entry point and _exit() exit point.
  253.  
  254.     WARNING: ONLY PROCESSES MAY USE THE __CONFIG TYPE QUALIFIER.  If
  255.     you plan to run a program as a task instead of a process then you
  256.     cannot use __config.  Note that any WORKBENCH or CLI run program
  257.     is a process.  DOS handlers are also processes, but it is not
  258.     suggested that __config be used for any program that is to be
  259.     a DOS handler (i.e. a DOS device).  Libraries and exec Devices are
  260.     NOT processes... not even tasks usually, and thus __config may not
  261.     be used for such programs.
  262.  
  263.     __regargs
  264.     __stkargs
  265.  
  266.     Normally these qualifiers are used in conjuction with the -mr,
  267.     -mR, or -mRR flags.  Even so, they are usually used only to
  268.     force a normal C calling convention for callback functions (when
  269.     you supply intuition, graphics, exec, or whomever with a callback
  270.     function the OS will call you with arguments on the stack).
  271.  
  272.     Specifying neither causes the routine to default to either stack
  273.     args or register args depending on the DCC flags.  Specifying
  274.     __stkargs forces the function to use stack based arguments no
  275.     matter what options are used.  Specifying __regargs forces the
  276.     function to use register based arguments in the same manner.
  277.     Specifying both forces the function to generate two entry points
  278.     (same thing occurs by default when -mr is used).
  279.  
  280.     Please refer to the discussion in REGARGS.DOC for more information
  281.  
  282.  
  283.