readme.txt

ucos source code for 8051

          The uC/OS-II port for Keil C V6.20, V6.21 or higher
               By John X. Liu, China, ([e-mail])


1. About this port.
      This package contains the files of porting uC/OS-II V2.51  to
      Keil C environment,  including  the  necessary head files and
      source files and an example to show how to use this port.

2. Files list.
      This package  only  included  the  files specific to port for 
      Keil C, and  assumed that you have all the other uC/OS source 
      files.

      Porting files:
          OS_CPU.H    Defines the data types and some macros needed 
                      by uC/OS.  Also  defines some macros to work-
                      around  the problem that some keil c keywords 
                      were used  as identifiers  in uC/OS-II source 
                      files.

          OS_KC51.H   Declares the uC/OS functions with 'reentrant' 
                      suffix, so as to make them reentrant, what is
                      needed as system functions.

          OS_KCDEF.H  Resumes the original definition of the words,
                      which are keywords in keil C but were used as
                      identifiers in uC/OS files.

          INCLUDES.H  Includes all needed header files together

          OS_CPU_C.C  The c part of porting source files.

          OS_CPU_A.ASM  The assembling language part.

      Example files:
          OS_CFG.H    The configuaration file, specific to every 
                      application, used to define what features of 
                      the os are needed to be included 

          EX1L.C      The example file ported from borland c++ port
                      which can be found in directory:
                            \SOFTWARE\uCOS-II\EX1_IX86L

          PC.H        The PC-emulating head file, ported from its
                      original directory \SOFTWARE\PC

          PC.C        The PC-emulating source file,implementes PC's
                      display screen, ported from \SOFTWARE\PC

          PC51EMU.DLL   The debug DLL of Keil UV2 degugger environ-
                        ment. To be used to emulate the behavior of
                        a PC display screen.

          EX1KC51.UV2   The example's project file.

          EX1KC51.OPT   Option file of the project.

      Document: 
          Readme.Txt   This file.

3. About the porting files.
      The required functions have been implemented according to the
      description in the book 'uC/OS, The Real-Time Kernel'. Mainly 
      the work of porting is arround how to save the status of CPU
      and restore it later.  The status include the register ACC,B,
      PSW, DPTR,IE,R0-R7,SP, and the hardware stack resides in 8051
      strach RAM. This work is fulfiled by c code in OS_CPU_C.C and
      some assembly code in OS_CPU_A.ASM.

      Due to the specific grammer of keil c, the functions declared
      by default are non-reentrantable.  If you need re-entrantable
      function, you must add a 'reentrant' after the declaration,
      like this:
         func() reentrant
         {
           .
           .
           .
         }
      So it is necessary to modify the declarations and definitions
      of uC/OS-II's system functions to make them work as expected.
      Head file os_kcdef.h declares all uC/OS functions reentrant.
      But you still need do lot of things.  You need modify all the
      uC/OS-II function declarations in .h files and definitions in
      .c files so as to make them conform to the respective ones in
      os_kcdef.h.

4. The example.
      The example comes from \SOFTWARE\UCOS-II\EX1_IX86L,  which is
      intended running under MS-DOS originally.  Seeing it's a nice
      illustration of uC/OS multi-tasking feature, I included it in
      this port for keil c environment. In order to show the result
      I wrote a Keil UV2 debugger simulator DLL to emulate PC's the
      display screen to show the result of the examle.  It maps the
      XDATA:0-0x1000 as PC's display buffer at B800:0 and  displays
      the characters and attributes as same as PC does.  To see the
      result of the example, you should copy the PC51Emu.DLL to the
      Keil's C51\Bin directory and add '-dPC51Emu' at the paramters
      editbox of dialog DLL in debug panel of the project's options.

5. Compiling and running the example files.
      First, Unzip the files in this package to a directory,  
      i.e. \SOFTWARE\uCOS-II\I8051\Keil, make the directory current.
      Then copy all uC/OS files in the directory \SOFTWARE\uCOS-II\
      SOURCE to the current directory, edit the declarations of all
      functions in UCOS_II.H, and the definitions in OS_*.C to make
      them same with the  respective ones in OS_KCDEF.H.

      Second, Run Keil UV2 IDE, open the project file "Ex1KC51.UV2", 
      click compile or build, let KC compile all the source files,
      and build the target Ex1Kc51. If any error occurs, correct it.
      Mostly circumstance  it is due to incorrect modifing of uC/OS
      source files.  It is rather simple to find the mismatches out
      and correct them.

      Third, start debugging,and check the peripheral menu,you will 
      see a menu item 'Virtual screen' added there.  Click the menu
      item, a PC-liked virtual screen window will display.  Run the
      example in full speed, you will see the output of the example
      shown on the virtual screen window.

      You may run the original example in \SOFTWARE\uCOS-II\EX1_I86L, 
      to have a comparation between them.

6. Adapting this port in your application.
   1) Copy the files you need from the directory of this example to
      the directory of your project.
   2) Edit the OS_CPU.H and select a critical method best to you by
      set the OS_CRITICAL_METHOD to 1,2, or 3. You may refer to the
      book 9.03.02 to decide which method to be used.
   3) Read and edit the OS_CFG.H and decide what system services
      you need include in your project.
   4) Write your own interrupt service routines as demonstrated in
      OS_CPU_C.C. If you like you may reimplement the OSTickISR.
   5) At least in your first task you must write code to initialize 
      the timer that uC/OS uses. If you change the timer rate, you 
      must change the OS_TICKS_PER_SEC to the right value as well.

7.Limitations.
      This port has some limitations, listed as below.
   1) Only large mode is supported.
   2) Does not support register banking.
   3) Does not support RET_PSTK or RET_XSTK option.
   4) Does not support multiple data pointer accessing.
   5) Never tested whether this port could support arithmetic  unit
      in some specific chips.