home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD1.img / d1xx / d168 / src / deemu / deemu.doc < prev    next >
Encoding:
Text File  |  1988-11-22  |  8.8 KB  |  282 lines
  1.  
  2.     PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY PRELIMINARY
  3.  
  4.                    DEEMU
  5.            USER MODIFIABLE EXECUTABLE EMBEDDED DATA
  6.  
  7.                 Matthew Dillon            (SNAIL)
  8.                 891 Regal Rd.
  9.                   Berkeley, Ca. 94708
  10.                      USA
  11.  
  12.                 dillon@ucbvax.Berkeley.EDU        (APRANET)
  13.                 ...!ihnp4!ucbvax!dillon        (USENET)
  14.  
  15.  
  16.                  30 July 1988
  17.  
  18.     Includes:
  19.     CONFIG        -V1.00 of my config program
  20.     CLOCK        -V1.00 of my really-small non-intrusive clock program
  21.              (which uses DEEMU for window placement)
  22.     DEEMU.DOC   -Docs on DEEMU
  23.     SCRIPT.TXT  -Example script of configuring the clock executable
  24.     MAKEFILE
  25.     CONFIG.C
  26.     CLOCK.C
  27.  
  28.  
  29.     This document describes DEEMU, which allows end users to modify various
  30. parameters of a program by directly modifying the executable in question
  31. through standard programs.  This is what happens:
  32.  
  33.     (1) The programmer embedds a DEEMU structure at the very beginning
  34.     of his initialized data hunk.  Since the C startup module usually
  35.     contains only BSS declarations, a simple C declaration at the
  36.     beginning of your first module will suffice.
  37.  
  38.         ** THIS HAS BEEN TESTED WITH AZTEC C.  COULD SOMEBODY PLEASE
  39.            TEST IT WITH LATTICE?
  40.  
  41.  
  42.     (2) The user comes along and can modify various DEEMU entries in the
  43.     executable to customize the program to his needs.
  44.  
  45.     Thus, the programmer need not put any extra code into his program to
  46.     allow the user to modify parameters from the program.  Additionaly,
  47.     the script or initialization files that would otherwise have been
  48.     required are now nonexistant, making the user's enviroment that much
  49.     more streamlined and clean.
  50.  
  51.                 STRUCTURE FORMAT
  52.  
  53.     The programm should put the following declaration at the beginning of
  54.     his first C (or assembly, or whatever) module:
  55.  
  56.     long Deemu[] = {
  57.     'STRT', 0,
  58.     (other DEEMU entries)
  59.     'END ', 0
  60.     };
  61.  
  62.     Note that the name of the array is arbitrary.  This is an array of
  63.     longwords consisting of a START entry, intermediate entries, and an
  64.     END entry.    The format of each entry is:
  65.  
  66.     long type;        -longword describing the structure type
  67.     uword flags;        -RESERVED, SET TO 0
  68.     uword bytes;        -# of bytes
  69.     char data[bytes] + PAD0 -The structure data, padded to a WORD BOUNDRY
  70.  
  71.     The CONFIG program (yours, mine, anybody's) will check for 'STRT', 0 at
  72.     the beginning of every DATA HUNK in the program until it finds one,
  73.     then verifies the entire structure all the way to the 'END ', 0 is
  74.     correct, then prompts the user with the various structures allowing him
  75.     to modify them.
  76.  
  77.     The user gets very nice descriptive prompts for structure types that
  78.     CONFIG knows about.  The user can still modify structures CONFIG does
  79.     not know about, but will not get the descriptive prompts.
  80.  
  81.     ALL STRUCTURES ARE WORD ALIGNED.  That is, if a structure is not word
  82.     aligned it should be padded with a 0 at the end to make it so.  Thus,
  83.     EVEN WHEN THE #BYTES IS NOT WORD SIZED, the #bytes is extended to a
  84.     longword boundry to find the next DEEMU entry: bytes = (bytes+1)&~1
  85.  
  86.     Fields within the structure need not be word aligned.  This allows you
  87.     to embed standard Amiga structures.
  88.  
  89.  
  90.                 STANDARD STRUCTURES
  91.  
  92.     Since this is the first release, only a couple custom structures have
  93.     been defined so far.
  94.  
  95.     NOTE #1:    The entire structure need not be entered.  It is perfectly
  96.         acceptable to cut out the tail ends of structures that you
  97.         do not want to bother with.  For instance, you might have
  98.         the following for a NewWindow structure:
  99.  
  100.         'NW  ', 10, (short leftedge, topedge, width, height,
  101.                  ubyte detpen, blockpen)
  102.  
  103.                     OR
  104.  
  105.         'NW  ',  9, (short leftedge, topedge, width, height,
  106.                  ubyte detpen)
  107.             + one byte padding.
  108.  
  109.         In this case, the CONFIG program only prompts for those
  110.         fields that exist.
  111.  
  112.     NOTE #2:    Structures may be longer than the 'standard' size.  For
  113.         future compatibility.  The DEEMU program will prompt for
  114.         these fields but will not be able to give descriptions of
  115.         them to the user.
  116.  
  117.     STRT {    The START structure, must be the first DEEMU structure.
  118.     long type = 'STRT';
  119.     word flags= 0;
  120.     word size = 0;
  121.     };
  122.  
  123.     END  {    The END structure, must be the last DEEMU structure.
  124.     long type = 'END ';
  125.     word flags= 0;
  126.     word size = 0;
  127.     };
  128.  
  129.     TEXT {
  130.     long type = 'TEXT';
  131.     word flags= 0;
  132.     word size = N
  133.     char prompt[A];     N = A + B.    This includes the \0 after each string
  134.     char contents[B];
  135.     };
  136.  
  137.  
  138.     The contents string need not be exactly B long, but may terminate
  139.     with a \0 before it reaches the maximum allowed length.  In this
  140.     case the extra bytes at the end may be garbage.
  141.  
  142.     The contents string is thus limited to N-strlen(A)-2 character bytes,
  143.     not including the \0.
  144.  
  145.     THE PROMPT STRING MAY NOT BE MODIFIED BY THE USER.  SEE CLOCK.C FOR
  146.     EXAMPLE USAGE OF 'TEXT'.
  147.  
  148.     NOP {
  149.     long type = 'NOP ';
  150.     word flags = 0;
  151.     word size = N;
  152.     };
  153.  
  154.     No operation.  The data, if any, can be modified, but will probably
  155.     not be used by the program.
  156.  
  157.     DATA {
  158.     long type = 'DATA';
  159.     word flags = 0;
  160.     word size = N;
  161.     };
  162.  
  163.     Program dependant data.  Contents and ordering are defined by the
  164.     program.  The documentation for the program will tell you which
  165.     word means what (the CONFIG program prompts for the data in WORD
  166.     sized chunks).
  167.  
  168.     TRCT {
  169.     long type = 'TRCT';
  170.     word flags = 0;
  171.     word size = N;
  172.     short pri;
  173.     short cpu;
  174.     long chipmem;
  175.     long generalmem;
  176.     };
  177.  
  178.     Task/Resource Control.    Dynamic specification of the task priority.
  179.     pri:
  180.  
  181.         Specify the task priority.    If bit 8 ($100) is set, an absolute
  182.         priority is given in the low byte.    If bit 8 is clear, a
  183.         priority relative to the startup-priority is given. (i.e. a
  184.         1 means, 1 over my priority when I started up).
  185.  
  186.     cpu:    0-FFFF
  187.  
  188.         Specify how much of a CPU hog this program can be, in
  189.         percentage (FFFF=100%).  Most programs ignore the field.
  190.  
  191.     chipmem/generalmem:
  192.  
  193.         some value representing the maximum #bytes of memory you want
  194.         this program to use.  These fields do not apply to most
  195.         programs but could come in useful in, say, a disk cache program
  196.         or something like that.
  197.  
  198.         NOTE that there is no specification for 'fast' memory. chipmem
  199.         refers to specific CHIP allocations the program makes, and
  200.         generalmem refers to non-specific allocations the program might
  201.         make.
  202.  
  203.  
  204.     NW {
  205.     long type = 'NW  ';
  206.     word flags= 0;
  207.     word size = N;        (usually 8 or 10 bytes.. partial NewWindow structure)
  208.     (A partial NewWindow structure)
  209.     };
  210.  
  211.     struct NewWindow NW;
  212.     'NW  ', (0-sizeof(NewWindow))L, <data>
  213.  
  214.     The NewWindow structure.  However, the contents of LeftEdge,
  215.     TopEdge, Width, and Height, are allowed to be NEGATIVE.
  216.  
  217.     TopEdge  < 0        : specify right edge relative to screen right
  218.     LeftEdge < 0        : specify bottom edge relative to screen bottom
  219.     Width    <= 0        : specify width relative to screen Width
  220.     Height    <= 0        : specify height relative to screen height
  221.  
  222.     The programmer should do a sanity check of parameters after
  223.     adjusting them properly.  The GetScreenData() should be used to
  224.     retrieve screen information.
  225.  
  226.     For instance, specifying -1, -1 places the window as follows:
  227.  
  228.     ActualLeftEdge = Screen.Width - Nw.Width - 1;
  229.     ActualTopEdge  = Screen.Height- Nw.Height- 1;
  230.  
  231.     SPECIFYING 0 FOR THE Nw.Width and/or Nw.Height should cause the
  232.     window to be openned to its fullest size in that dimension.
  233.  
  234.     IF YOU USE THE 'NW  ' DEEMU STRUCTURE, YOU MUST BE ABLE TO HANDLE
  235.     THESE SPECIAL CONDITION!
  236.  
  237.  
  238.                 EXAMPLE
  239.  
  240. short Deemu[] = {
  241.     'ST','RT', 0, 0,
  242.     'NW','  ', 0, 9, -16, -8, 64, 32, -1, 0,
  243.     'TE','XT', 0, 16, 'HI', '\0T', 'ES', 'T.', 0, 0, 0, 0,
  244.     'EN','ND', 0, 0
  245. };
  246.  
  247.  
  248.     We have a STRT structure of 0 length (it MUST be 0 length).
  249.  
  250.     We then have the first 9 bytes of a NewWindow structure:
  251.     short LeftEdge = -16;
  252.     short TopEdge  = -8;
  253.     short Width    = 64;
  254.     short Height   = 32;
  255.     char  DetailPen= -1;
  256.  
  257.     NOTE: The NW structure is padded to a word boundry with a 0, this
  258.     0 is *NOT*, I repeat *NOT* the char BlockPen; specification, which
  259.     normally comes after DetailPen.
  260.  
  261.     And, before the END we have a 'TEXT' entry with the prompt "HI" and
  262.     the contents "TEST".  The user is allowed to modify the contents and
  263.     up to 12 characters (not including the \0) may be used.  For TEXT, no
  264.     more than 128 bytes total should be allocated.
  265.  
  266.                   LIMITATIONS
  267.  
  268.     Currently the config program only checks the first 32 longwords of
  269.     each DATA hunk.  This is done mainly to prevent the possibility that
  270.     non DEEMU data might look like a DEEMU header, but also taking into
  271.     account that the linker might put some amount of data in the hunk
  272.     before it gets to the DEEMU data.
  273.  
  274.     The Aztec linker (don't know about the others) sticks stuff before
  275.     your own (jump tables when using the small code model).  If your
  276.     program is big enough, the DEEMU data might be out of reach.  The
  277.     solution is to place the DEEMU data in its own hunk, which can be
  278.     accomplished with a little more work and various linker options.
  279.  
  280.     Future CONFIG programs will fix the problem.
  281.  
  282.