CTask

                           A Multitasking Kernel for C



                          Version 2.2  Released 90-10-12




                        Public Domain Software written by

                                  Thomas Wagner

                             Ferrari electronic GmbH



                                     Contents


        About this Manual                                               1

        Introduction                                                    2
          An Example                                                    2
            Switching the Context                                       2
            You have Mail                                               3
            Reentrancy and Resources                                    3
            DOS Access                                                  4
            Handling the Keyboard                                       4
            Serial I/O and Timeouts                                     5
            Priorities                                                  5
          Change to your liking                                         5

        General Notes                                                   7
          What can CTask NOT be used for?                               7
          What is required to use CTask?                                7
          Do I have to pay for using CTask?                             8
          What support can I expect?                                    9
          About this Release                                           10

        Multitasking Basics                                            11
          Tasks                                                        11
          Events                                                       11
          Reentrancy                                                   12
          Deadlocks                                                    13

        Using CTask                                                    15
          Configuration Options                                        15
          Memory Allocation                                            21
          Snapshot                                                     21
          Task Stacks                                                  22
          Drivers                                                      22
          Things to remember                                           23
          Priority Handling                                            23

        Multitasking and DOS                                           25
          Spawning and CTask TSR's                                     26
          Task Groups                                                  27

        How does CTask work                                            29
          Queues                                                       29
          The Scheduler                                                30
          Events                                                       30
            Resources                                                  30
            Flags                                                      31
            Counters                                                   31
            Mailboxes and Pipes                                        31
          Serial and Printer Drivers                                   32


        
        
        Ctask Manual       - Version 2.2 - 90-10-12 -          Contents 1


        CTask Data Types                                               34
          Other definitions                                            35
          Typedefs used for simplified type specifications             36
          Error return values for event wait functions                 37
          Queues                                                       37
          The timer/watch/hotkey control block                         38
          The name link structure                                      43
          The task control block structure                             43
          Task states                                                  46
          Task flags                                                   47
          The Group Control Block                                      48
          The event control blocks                                     49
            The Ticker structure                                       49
            The flag event structure                                   50
            The counter event structure                                50
            The resource event structure                               51
            The mailbox event structure                                51
            The pipe and word pipe event structure                     51
            The buffer event structure                                 52
            The call chain structure                                   53

        CTask Routines                                                 54
          Global Variables                                             54
          Installation and Removal                                     54
          Searching for names                                          57
          Adding names                                                 58
          Remove Functions                                             58
          Preemption and Scheduling                                    59
          Miscellaneous                                                60
          Task Operations                                              62
          Timer Operations                                             64
          Event wait Timeouts                                          65
          "Tickers"                                                    65
          Delays                                                       66
          Timed Events, Watch Events, and Hotkeys                      66
          Event Operations                                             75
            Resources                                                  75
            Flags                                                      77
            Counters                                                   79
            Mailboxes                                                  81
            Pipes                                                      83
            Buffers                                                    86
          The Keyboard Handler                                         88
          The Serial I/O handler                                       88
          The Printer Output Driver                                    94
          Support Modules                                              96
            Memory Allocation Interface                                96
            Printf replacements                                        97
            Snapshot Dump                                             100




        
        
        Ctask Manual       - Version 2.2 - 90-10-12 -          Contents 2


        Advanced Topics                                               101
          Primary and Secondary Kernels                               101
          TSR, Spawning, and EMS                                      104
          Functions called by Kernel Routines                         105

        Some notes on potential trouble spots                         107
          Turbo C console output                                      107
          The timer tick EOI                                          107
          Debugging                                                   108

        Changes from Previous Versions                                109
          Changes for CTask 2.1 to 2.2                                109
            Version 2.2 Interface Changes                             111
          Changes for CTask 2.0 to 2.1                                112
            Version 2.1 Interface Changes                             115
          Changes for CTask 1.2 to 2.0                                116
            Version 2.0 Interface Changes                             116
          Changes for CTask 1.1b to 1.2                               118
          Changes for CTask 1.1 to 1.1b                               120
          Changes for CTask 0.1 to 1.1                                120

































        
        
        Ctask Manual       - Version 2.2 - 90-10-12 -          Contents 3


                                About this Manual

        If you are new to CTask, I would suggest reading all chapters
        before attempting to build your first application. One chapter
        you can skip is the CTask Data Types section, since you are not
        required to know about the innards of CTask's structures. You can
        also ignore the List of Changes.

        If you are updating from version 2.0, read the List of Changes,
        and the new Advanced Topics section. The chapters on Data Types
        and Routines, and the Using CTask section, also contain new
        information. All other chapters are basically unchanged.

        Version 2.1 users will find little new information here. The
        changes in the data structures, and the new routines, are
        reflected here, but if you're short on paper, it should be
        sufficient to print just the list of changes.

        If you are updating from an older release, the List of Changes at
        the end is for you. You can safely skip the Introduction, and the
        section on Multitasking Basics. In the General Notes, you should
        read the section on support and the info about this release. In
        the Using CTask section, check the new configuration options, and
        the chapter on Memory Allocation. Check the Routine descriptions,
        and, if you are using internal data structures directly, the Data
        Type descriptions, for changes. The Advanced Topics section is
        new.


        Finally, a note to German speaking readers:

        Dieses Handbuch, wie auch die Kommentare im Quellcode, ist in
        Englisch abgefa醫, da dies die universelle Sprache f乺 Computer-
        benutzer weltweit ist. Es gibt keine deutsche Version, und es
        wird voraussichtlich auch keine geben (sofern nicht jemand bereit
        ist einen angemessenen Betrag f乺 eine 歜ersetzung auf den Tisch
        des Hauses zu legen). Selbstverst刵dlich bleibt es Ihnen
        unbenommen, das Handbuch selbst zu 乥ersetzen und diese Version
        auch zu vertreiben, oder mir zum Vertrieb anzubieten. Wie die
        Software ist auch dieses Handbuch Public Domain.













        
        
        Ctask Manual       - Version 2.2 - 90-10-12 -              Page 1


                                   Introduction

        CTask is a set of routines that allow your C program to execute
        functions in parallel, without you having to build in sophisti-
        cated polling and switching schemes. CTask handles the switching
        of processor time with a priority based, preemptive scheduler,
        and provides a fairly complete set of routines for inter-task
        communication, event signalling, and task interlocking. CTask
        also includes a number of drivers for MS-DOS that build on the
        basic functions to allow you to include serial I/O, printer
        buffering, and concurrent access to DOS functions into your
        programs with little programming effort.


                                    An Example

        To illustrate one possible use of CTask, let me elaborate on the
        following example. Say you just finished your nifty telecommuni-
        cations program, complete with download protocols, scripts, and
        everything.  But wouldn't it be nice to be able to print the file
        you just downloaded while receiving the next, and edit a comment
        to some previous message without interrupting the transmission?
        So you take those editor routines from a previous project, plug
        them in, and - oops, how do you switch back and forth between
        editing, communication and printing? The answer to this is CTask.
        CTask allows your C program to do many different things at the