home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD1.img / d1xx / d111 / amyload / load.doc < prev    next >
Text File  |  1987-11-15  |  11KB  |  343 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. load.device/structure/LoadBase
  6. load.device/command/Flush
  7. load.device/command/Read
  8. load.device/command/Reset
  9. load.device/command/Set
  10. load.device/command/Start
  11. load.device/command/Stop
  12. load.device/function/AbortIO
  13. load.device/function/BeginIO
  14. load.device/function/CloseDevice
  15. load.device/function/OpenDevice
  16.  
  17.  
  18. load.device/structure/LoadBase              load.device/command/LoadBase
  19.  
  20.    NAME
  21.        LoadBase - the load device data structure
  22.  
  23.    DESCRIPTION
  24.        The io_Device field of the loadrequest structure points to the
  25.        LoadBase structure.  This structure should not be modified except
  26.        indirectly as a result of executing a device command.  It is
  27.        permissible to read the data structure (using Forbid/Permit as
  28.        appropriate), but the only values of any interest are probably
  29.         ld_max_chip - the maximum amount of chip memory available at
  30.               the time the load device was first loaded.
  31.         ld_max_fast - as above, but for fast memory.
  32.  
  33.    SEE ALSO
  34.        devices/load.h
  35.        devices/load.i
  36.  
  37. load.device/command/Flush              load.device/command/Flush
  38.  
  39.    NAME
  40.        Flush -- clear all queued I/O requests for the load task
  41.  
  42.    FUNCTION
  43.        This command purges the read request queue for the load
  44.        task.
  45.  
  46.    IO REQUEST
  47.        io_Message      mn_ReplyPort initialized
  48.        io_Device       set by OpenDevice
  49.        io_Command      CMD_FLUSH
  50.  
  51.    RESULTS
  52.        io_Error -- if the Flush succeded, then io_Error will be 0.
  53.            If the Flush failed, then the io_Error will be non-zero.
  54.            (No known reason for it to fail.)
  55.  
  56.    SEE ALSO
  57.        load.device/command/Read
  58.  
  59. load.device/command/Read               load.device/command/Read
  60.  
  61.    NAME
  62.        Read -- read load values collected by load task
  63.  
  64.    FUNCTION
  65.        This command reads the load values of the CPU, blitter, chip
  66.        memory, and fast memory.
  67.  
  68.    IO REQUEST
  69.        io_Message      mn_ReplyPort initialized
  70.        io_Device       set by OpenDevice
  71.        io_Command      CMD_READ
  72.        io_Flags        IOF_QUICK if quick I/O desired
  73.  
  74.    RESULTS
  75.        If the read succeeded, the following load values will be set:
  76.        lr_load.lv_cpu      -- The sum of the length of the ready queue as
  77.                  measured at each tick during the interval.
  78.                  This value may be greater than the number of
  79.                  ticks in an interval, theoretically having no
  80.                  upper bound (but try to tell that to your
  81.                  poor little 68000!).
  82.        lr_load.lv_blitter -- The number of ticks at which the blitter was
  83.                  detected to be busy during the interval.
  84.        lr_load.lv_chip      -- The number of bytes of chip memory currently
  85.                  in use.  To find the maximum chip memory
  86.                  available, see the description of the
  87.                  LoadBase structure.
  88.        lr_load.lv_fast      -- The number of bytes of fast memory currently
  89.                  in use.  To find the maximum fast memory
  90.                  available, see the description of the
  91.                  LoadBase structure.
  92.  
  93.        io_Error -- If the Read succeeded, then io_Error will be 0.
  94.            If the Read failed, then the io_Error will be non-zero.
  95.            It may fail if IOF_QUICK is not set and a Flush or AbortIO
  96.            request is executed before the end of the current interval,
  97.            in which case the error will be IOERR_ABORTED.
  98.  
  99.    BUGS
  100.        The length of the ready queue is measured, which may not be an
  101.        accurate measurement of CPU usage.
  102.  
  103.        Time arithmetic is not currently used to ensure that an interval is
  104.        really an interval.  That is, that due to delays between the time
  105.        that the load.device task is signalled by the timer and when the
  106.        task places its next timer request, the actual interval will end up
  107.        being greater than the specified interval.
  108.  
  109.    SEE ALSO
  110.        load.device/structure/LoadBase
  111.        load.device/command/Flush
  112.        load.device/function/AbortIO
  113.  
  114. load.device/command/Reset              load.device/command/Reset
  115.  
  116.    NAME
  117.        Reset -- reinitializes the load device parameters
  118.  
  119.    FUNCTION
  120.        This command sets the interval time, the number of ticks per interval,
  121.        and the priority of the load task to their default values.
  122.  
  123.    IO REQUEST
  124.        io_Message      mn_ReplyPort initialized
  125.        io_Device       set by OpenDevice
  126.        io_Command      CMD_RESET
  127.  
  128.    RESULTS
  129.        io_Error -- If the Reset succeeded, then io_Error will be 0.
  130.            If the Reset failed, then the io_Error will be non-zero.
  131.         (No known reason for it to fail.)
  132.        If the Reset succeeded, then the lr_interval, lr_ticks, and lr_pri
  133.        fields of the loadrequest will contain the default settings of
  134.        those parameters.
  135.  
  136.    SEE ALSO
  137.        load.device/command/Set
  138.        load.device/function/OpenDevice
  139.  
  140. load.device/command/Set                   load.device/command/Set
  141.  
  142.    NAME
  143.        Set -- change load device parameters
  144.  
  145.    FUNCTION
  146.        This command sets the interval time, number of ticks per interval,
  147.        and priority of the load task to values specified in the load IO
  148.        request.
  149.  
  150.    IO REQUEST
  151.        io_Message      mn_ReplyPort initialized
  152.        io_Command      LD_SET
  153.        lr_interval     A word indicating the sampling period time (in seconds),
  154.                during which a number of samples may be taken.
  155.        lr_ticks        A word indicating the number of samples to be taken
  156.                during each interval.
  157.        lr_pri           A byte indicating the priority of the load task.
  158.         NOTE: The last three fields are initialized when OpenDevice
  159.           is called to indicate the devices current configuration.
  160.  
  161.    RESULTS
  162.        io_Error -- 0 if the command succeeded, otherwise an error number.
  163.            (No known reason for it to fail.)
  164.  
  165.    SEE ALSO
  166.        load.device/command/Reset
  167.        load.device/function/OpenDevice
  168.  
  169. load.device/command/Start              load.device/command/Start
  170.  
  171.    NAME
  172.        Start -- restart the paused load task.
  173.  
  174.    FUNCTION
  175.        Restarts the paused load task, but not if other Stop commands
  176.        have been performed without corresponding Start commands.
  177.  
  178.    IO REQUEST
  179.        io_Message      mn_ReplyPort initialized
  180.        io_Device       set by OpenDevice
  181.        io_Command      CMD_START
  182.  
  183.    RESULTS
  184.        io_Error -- 0 if the start succeeded, an error number otherwise.
  185.            The only possible error is LDERR_NOT_STOPPED, if the
  186.            device was not currently in the stopped state.
  187.  
  188.    SEE ALSO
  189.        load.device/command/Stop
  190.  
  191. load.device/command/Stop               load.device/command/Stop
  192.  
  193.    NAME
  194.        Stop -- stop the load task from executing
  195.  
  196.    FUNCTION
  197.        Stops the load task at the end of the current interval if it is not
  198.        already stopped, otherwise increments the number of Stop commands
  199.        that must be cancelled by Start commands before the load task will
  200.        begin executing again.
  201.  
  202.    IO REQUEST
  203.        io_Message      mn_ReplyPort initialized
  204.        io_Device       set by OpenDevice
  205.        io_Command      CMD_STOP
  206.  
  207.    RESULTS
  208.        io_Error -- 0 if the Stop succeeded, an error number otherwise.
  209.            (No known reason for it to fail.)
  210.  
  211.    SEE ALSO
  212.        load.device/command/Start
  213.  
  214.    BUGS
  215.        If 255 Stop commands are already outstanding, executing
  216.        another Stop command will cause a counter to wrap around, and
  217.        undesirable behaviour may result.
  218.  
  219. load.device/function/AbortIO               load.device/function/AbortIO
  220.  
  221.    NAME
  222.        AbortIO -- abort an I/O request
  223.  
  224.    SYNOPSIS
  225.        AbortIO(ioRequest)
  226.  
  227.    FUNCTION
  228.        This function aborts a specified read request
  229.        If the request is queued, it is painlessly removed.
  230.  
  231.    INPUTS
  232.        iORequest  -- pointer to the IORequest Block that is to be aborted.
  233.  
  234.    RESULTS
  235.        io_Error -- IOERR_ABORTED if the AbortIO succeeded.
  236.            0 if the AbortIO failed (the request was not in the queue).
  237.  
  238.    SEE ALSO
  239.     load.device/function/BeginIO
  240.  
  241. load.device/function/BeginIO               load.device/function/BeginIO
  242.  
  243.    NAME
  244.        BeginIO -- start up an I/O process
  245.  
  246.    FUNCTION
  247.        This function initiates a I/O request made to the load
  248.        device. Other than read, the functions are performed
  249.        synchronously, and do not depend on any interrupt handling
  250.        logic (or it's associated discontinuities), and hence, if so
  251.        selected, can be performed as IO_QUICK.
  252.        Read requests that are not flagged as IO_QUICK are queued and
  253.        replied to by the load task at the end of the next interval.
  254.        Completion is signalled via the standard ReplyMsg routine.
  255.  
  256.    INPUTS
  257.        iORequest  -- pointer to an I/O Request Block of size
  258.        sizeof(struct loadrequest) (see devices/load.h for
  259.        definition), containing a valid command in io_Command
  260.        to process, as well as the command's other required parameters.
  261.        The io_Device field must have been initialized during the
  262.        OpenDevice call to point to the load.device.
  263.  
  264.    RESULTS
  265.        Error -- if the BeginIO succeded, then Error will be 0.
  266.         If the BeginIO failed, then the Error will be non-zero.
  267.         Possible errors:
  268.             IOERR_NOCMD   - Invalid command attempted.
  269.             IOERR_ABORTED - The request was aborted before completion.
  270.  
  271.    SEE ALSO
  272.     devices/load.h
  273.     devices/load.i
  274.  
  275. load.device/function/CloseDevice       load.device/function/CloseDevice
  276.  
  277.    NAME
  278.        CloseDevice -- close the load device
  279.  
  280.    SYNOPSIS
  281.        CloseDevice(ioRequest)
  282.  
  283.    FUNCTION
  284.        Close the device previously opened by calling OpenDevice.
  285.  
  286.    INPUTS
  287.        ioRequest - pointer to a load request initialized by a call to
  288.            OpenDevice.
  289.  
  290.    SEE ALSO
  291.        load.device/function/OpenDevice
  292.  
  293. load.device/function/OpenDevice         load.device/function/OpenDevice
  294.  
  295.    NAME
  296.        OpenDevice -- Request an opening of the load device.
  297.  
  298.    SYNOPSIS
  299.        error = OpenDevice(loadname, unit, ioRequest, flags)
  300.  
  301.    FUNCTION
  302.        Open the load device and initialize the ioRequest.
  303.  
  304.    INPUTS
  305.        loadname     - pointer to literal string "load.device"
  306.        unit        - ignored (should be 0).
  307.        ioRequest    - pointer to an ioRequest block of size
  308.               sizeof(loadrequest) (see devices/load.i,h
  309.               for size/definition) to be
  310.               initialized by the OpenDevice routine.
  311.        flags        - LDF_OPEN_EXCL if exclusive access to the load
  312.               device is desired, othewise 0.
  313.  
  314.    RESULTS
  315.        error     - 0 if the OpenDevice succeeded, an error number otherwise.
  316.             Possible errors:
  317.             IOERR_OPENFAIL - generic
  318.             LDERR_ACCESS_DENIED - the device is currently opened
  319.                by a task with exclusive access.
  320.             LDERR_IN_USE - an attempt was made to obtain exclusive
  321.                access to the device but it has already been
  322.                opened by another task.
  323.  
  324.        If the OpenDevice succeeded, the io_Device field of the ioRequest
  325.        structure will be initialized to point to the load.device.  The
  326.        three load device parameters will contain their current settings:
  327.        lr_interval - The number of seconds in each interval.
  328.        lr_ticks    - The number of ticks in each interval.    Measurements
  329.              of CPU usage (ready queue length) and blitter usage
  330.              are taken at each tick during an interval, and at
  331.              the end of the interval queued read requests are
  332.              replied to.
  333.        lr_pri      - The priority of the load.device task.    Note that
  334.              CPU usage of tasks running at a priority greater
  335.              than this cannot be measured, and those at an
  336.              equal priority are not accurately measured.
  337.  
  338.    SEE ALSO
  339.     load.device/function/CloseDevice
  340.     devices/load.h
  341.     devices/load.i
  342.  
  343.