home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / SWI.pm < prev    next >
Text File  |  1999-04-17  |  7KB  |  191 lines
  1. NAME
  2.     RISCOS::SWI -- perl interface to SWI calls
  3.  
  4. SYNOPSIS
  5.         use RISCOS::SWI;
  6.         $number = RISCOS::SWI::swix ('OS_SWINumberFromString', regmask([1]), $name);
  7.         @regs = unpack 'I10', kernelswi ('OS_File', 5, $filename);
  8.  
  9.  
  10. DESCRIPTION
  11.     This module provides a SWI interface for perl. There are two
  12.     alternative interfaces supported - kernelswi and swi/swix. Both
  13.     take the SWI to call as the first parameter, which can be
  14.     specified by name or number. Although calling a SWI by name
  15.     makes for highly readable code, the name lookup itself often
  16.     takes longer than the actual SWI, so for production code it is
  17.     wise to perform the name lookup once at initialisation using
  18.     `SWINumberFromString' and cache the number in a variable.
  19.  
  20.     `kernelswi' and `swix' both automatically call the `X' (error
  21.     returning) version of the SWI, return undefined on error and
  22.     copy the error block number and message to `$^E'. `swi' calls
  23.     `swix', but will terminate the script with the error number and
  24.     message if an error occurs.
  25.  
  26.     For both interfaces registers are initialised from perl
  27.     variables according to the following rules:
  28.  
  29.     the undefined value is passed as zero
  30.  
  31.     "numbers" are passed as integers
  32.  
  33.     "strings" are passed as pointers to the strings - perl automatically adds
  34.     a `"\0"' at the end to create null terminated strings.
  35.         Overwriting the contents alters the variable's value - it is
  36.         up to the script to ensure that the perl scalar value is
  37.         made long enough before calling the SWI. Note also that
  38.         string constants are treated as read only so attempting to
  39.         call
  40.  
  41.             $number = RISCOS::SWI::swix ('OS_SWINumberFromString', regmask([1]),
  42.                          'OS_SWINumberFromString');
  43.  
  44.  
  45.         would cause a fatal runtime error.
  46.  
  47.  
  48.     "strings" and "numbers" are in quotes because the internals rely
  49.     on perl's flags to determine whether a scalar is a number or
  50.     string. The trouble comes when perl has been implicitly
  51.     converting between the two and thinks that the result of `6*7'
  52.     is `"42"', which it will try to pass in as a pointer to a
  53.     string. The work around is to add zero to parameters that must
  54.     be numeric, and concatenate `''' to parameters that are strings:
  55.  
  56.         $number += 0;
  57.  
  58.         $string = "0";    # This may be interpreted as the number zero
  59.         kernelswi ($swi, 0, $string . '')        # Not now.
  60.  
  61.  
  62.     The latter is, to quote Paul Moore, "fairly obscure magic
  63.     (deliberately invalidating the flag which says that the string
  64.     has a valid numeric value, and then using the string before perl
  65.     has a chance to notice that the numeric value is still OK), but
  66.     works fine."
  67.  
  68.     The two interfaces are both built into the perl binary and so
  69.     are always available, with or without this module. They differ
  70.     in the method of passing in and returning results from
  71.     registers.
  72.  
  73.     kernelswi <name>|<number>, [<R0 value>, [<R1 value], ...
  74.         is similar to the C library function of the same name. It
  75.         takes as parameters the SWI to call and optionally up to 10
  76.         more values assigned to `R0' - `R9' in order. Unassigned
  77.         registers have undefined values (not zero, unlike `BASIC').
  78.         If the SWI generates an error then undefined is returned,
  79.         and `$^E' is set to the error number and message from the
  80.         error block (*c.f.* `$!'). If there is no error then
  81.         `kernelswi' returning a single scalar block of length 40,
  82.         the packed return results from `R0' - `R9'. For example,
  83.         these may be converted to an array of integers with code of
  84.         the form
  85.  
  86.             @regs = unpack 'I10', $kernelswi_result;
  87.  
  88.  
  89.     swix <name>|<number>, [<mask>, [<value> ...
  90.         is similar to the alternative C veneer written by Edward
  91.         Nevill and Jonathan Roach and supplied with Acorn C versions
  92.         4 and later.
  93.  
  94.         Like `kernelswi', swix returns undefined and sets `$^E' if
  95.         an error is generated. If there is no error, swix returns
  96.         the contents of `R0'
  97.  
  98.         *mask* is a bitmask that describes the interpretation to
  99.         place on the remaining parameters. If it is omitted it is
  100.         treated as zero (no parameters). Otherwise it is best
  101.         generated by the `regmask' function. *mask* must be numeric
  102.         - string values are reserved and cause a fatal error at
  103.         runtime.
  104.  
  105.     regmask <in>, [<out>, [<block>]]
  106.             *in* and *out* are references to arrays of register
  107.             numbers to respectively pass into and out from the SWI.
  108.             If either is undefined it is treated as an empty array.
  109.             Registers 0 to 9 can be passed in, 0 to 9 and 15
  110.             returned.
  111.  
  112.             If present, *block* is the number of register to set up
  113.             to point to any remaining parameters "left over". This
  114.             provides a convenient way of generating parameter blocks
  115.             for SWIs such as `Wimp_CreateWindow'.
  116.  
  117.  
  118.         values follow in register number order - first values to
  119.         pass in, then scalars in which the value of registers out
  120.         are returned. The script must ensure that these scalars are
  121.         at least 4 bytes long, as the assembler `swix' veneer makes
  122.         no checks.
  123.  
  124.         Although this interface seems considerably more complex than
  125.         `kernelswi', it does allow much greater flexibility in
  126.         exactly which registers are wanted.
  127.  
  128.         Integer results can be retrieved with code such as
  129.  
  130.             unpack('i', $len)
  131.  
  132.  
  133.         string results by dereferencing pointers
  134.  
  135.             unpack('p', $addr)
  136.  
  137.  
  138.     swi calls `swix', returning `R0 + 0' to ensure a number, or `die's
  139.         with the numeric and string values of `$^E' if there was an
  140.         error.
  141.  
  142.  
  143.     `RISCOS::SWI' also provides conversion functions between SWI
  144.     names and numbers, and symbolic constants for the 4 ARM flags
  145.     and the OS 'X' bit.
  146.  
  147.     V_Flag
  148.  
  149.     C_Flag
  150.  
  151.     Z_Flag
  152.  
  153.     N_Flag
  154.         return the bit corresponding to the position of flag in the
  155.         `PC/PSR'.
  156.  
  157.     XOS_Bit
  158.         returns 0x20000 - which when set marks the error returning
  159.         form of a SWI.
  160.  
  161.     SWINumberToString <SWI number>
  162.         converts a SWI number to a name using the SWI
  163.         `OS_SWINumberToString'. Returns the name of the SWI, or
  164.         undefined if there was an error. Unknown SWI numbers which
  165.         the SWI `OS_SWINumberToString' converts to '`User'' or
  166.         '`XUser'' are returned as '`User (&C00FEE)'' or '`XUser
  167.         (&0B100D)''.
  168.  
  169.     SWINumberFromString <SWI name>
  170.         provides a full inverse to `SWINumberToString'. "User" SWIs
  171.         described above are recognised, as are `OS_WriteI' variants.
  172.         Other SWIs numbers are converted using the SWI
  173.         `OS_SWINumberFromString'.
  174.  
  175.  
  176. BUGS
  177.     `swix' doesn't automatically ensure that scalars for return
  178.     values exist and are long enough. Additionally the current mask
  179.     system doesn't allow the script to specify whether it wants a
  180.     number, string or fixed length block to be returned, and let the
  181.     perl internals convert and assign the return values
  182.     automatically. String "masks" are reserved for this purpose.
  183.  
  184. AUTHOR
  185.     Nicholas Clark <nick@unfortu.net>, based on the previous perl
  186.     ports.
  187.  
  188.     The `swi' interface is `syscall' from the perl 5.001 port. The
  189.     `kernelswi' interface is `syscall' from the perl 3 port.
  190.  
  191.