www.beck-ipc.com

@CHIP-RTOS - Programming notes


    IPC@CHIP® Documentation Index

Introduction

Here are some useful notes for programming applications for the IPC@CHIP®.   These notes contains general rules for programming DOS applications for the IPC@CHIP® and important information about internals of the @CHIP-RTOS which can prevent the programmers from making fatal errors.


  • Common notes for building IPC@CHIP® user applications
  • Using RTOS API
  • Programming CGI functions
  • Configure the FTP server
  • Usage of the TCP/IP API
  • General notes for the usage of the DOS and @CHIP-RTOS int API calls
  • Using Hardware API
  • Using Fossil API
  • Working with Float Data Types
  • Configure PPP client or server
  • SC1x3/SC2x Extended Memory and EXE File Format
  • Optional SC1x3/SC2x Libraries


  • Common notes for building IPC@CHIP® user applications


    1. Limited Flash Write Cycles (of IPC@CHIP®s internal Flash):
      To open files on the flash disk drive A: for reading or writing, you can use the standard C functions fopen or open.   We recommend the use of the fopen/fread/fwrite calls instead of open/read/write to reduce the flash write cycles, because these cycles are limited.
      For further information see the FlashWriteCycles document.

    2. Compiler option settings:
      • The compiler must produce 186 processor instruction code.
      • The data alignment must be set to 8 Bit (Byte alignment), not to 16-Bit (Word alignment)!


    3. For inexperienced programmers, we recommend the use of the Large memory model for user applications.   While Small (or Medium) memory models can offer more efficient use of memory and better performance than Large memory model, problems difficult to diagnose may occur when using the near data memory models such as:

      1. All pointer parameters passed to the @CHIP-RTOS API must be far pointers.   Normally, the compiler will handle this conversion when interfacing to the Beck C-Library functions.   But for functions that use a variable length argument list such as the helper_printf, one can end up generating invalid code without any warnings offered by the compiler.

      2. @CHIP-RTOS tasks created in a Small memory model program must have their stack memory declared in the program's data segment.   (This requirement is due to the compiler's "SS equals DS" assumption used in near data memory models.)   small memory model programmers who allocate their @CHIP-RTOS task stack space using the system memory allocation function, or declared as far data will observe some very strange program malfunctions and face tedious debugging.

      3. If floating point emulator is used within @CHIP-RTOS tasks, small memory model should not be used due to the emulator's stack requirements.

    4. No "exception handling" in Paradigm or Borland C 4.x or 5.x projects:
      Users of Paradigm or Borland C-compilers should choose for their program project "No exceptions" at the "Target Expert" window.   This setting saves Flash and RAM memory space.

    5. Do not select "Test stack overflow" in the Paradigm or Borland C project compiler settings:
      If "Test stack overflow" is selected a stack check is done at every function call.   If stack overflow is recognized the program halts.   This mechanism is not usable in applications which create additional @CHIP-RTOS tasks inside the application, because every task has its own stack and the compiler's runtime library stack functions are not aware of these additional stacks.

    6. Turbo Pascal programmers should include the example file SC12.INC (part of each IPC@CHIP® Pascal example program).   At the start of their program, they should install the procedure Terminate_Program as the default exit procedure of the program.   Usage of the standard unit crt is not allowed.

    7. Before starting the first Turbo Pascal program at the IPC@CHIP® the memopt 1 command must be executed (e.g. in the AUTOEXEC.BAT)

    8. If programs that depend on one another are started from a batch file (e.g. if a user program needs a previous driver program) the Batchmode 1 in chip.ini should be set.

    9. For C program development, the Beck C-Library should be used.   This library provides efficient wrapper functions around the software interrupt API offered by the @CHIP-RTOS.   Both the library source and binaries are available from the Beck Web site download area.

    10. It is not advisable to design an IPC@CHIP® application as a set of several DOS programs for various reasons including:

      1. It is usually more efficient to run several tasks (created with the RTOS API) inside of a single DOS program rather than running several DOS programs as tasks of the @CHIP-RTOS.   The single program should require much less RAM and flash disk storage space compared to the memory requirements for a set of programs.
      2. It can lead to high memory fragmentation and insufficient memory, if more than one or two DOS programs are running on the IPC@CHIP® when these programs are often terminated and restarted again.

    11. It is not advisable to use in your application the Borland C-library malloc function with memory model Large.   In that case the DOS program tries to increase its own memory block with int21h 0x4A.   If another program is loaded after that program the malloc call fails, because there is no memory space left between the two programs.   It is possible to define a memory gap between two loaded programs at chip.ini but then you must know what maximum memory is required by your malloc calls.   It may be better to statically reserve the memory inside your application by declaring an unsigned character array (or the type you require) of the required size.

    12. The @CHIP-RTOS allocates memory in the following manner:

      • DOS programs are loaded into the lowest address free memory block of sufficient size.
      • Memory blocks allocated inside of the @CHIP-RTOS or with DOS service 0x48 are taken from the first free memory block of sufficient size, starting the search from the highest heap RAM address.

      So the largest free memory block in the system is usually located in the middle of the @CHIP-RTOS memory area.   The shell command mem shows the state of the internal memory map.

    13. Compressed executable files

      Compressing executable files with e.g. pklite or upx are useful to reduce the required diskspace. In case that the compressed applications are executed by a batch file the following behaviour should be considered:
      If Batchmode 0 is set, the command shell task (MTSK) waits about 500 ms between executing each line of the batch file. In case of executing a large compressed application the execution of the next application may fail due to the large time (more than 500 ms) required for decompression of the executable in memory. The command shell prompts the error message "Not enough memory to load program" . To avoid this problem Batchmode 1 should be used. It is also possible to insert an additional delay command at the batchfile between the lines of executing applications. A delay of 1 second ( wait 1 ) should be sufficient.


    Top of list
    Index page

    Using RTOS API


    1. Timer procedure's execution time must be kept as short as possible, because they are executed in the Kernel task.   Long timer procedures block the kernel and other tasks of the @CHIP-RTOS.   Do not use slow stack hungry C-library functions like printf inside of a timer procedure.   This can cause a fatal stack overflow in the kernel task (stack size 1024 Bytes)

    2. Timer procedure declaration with Paradigm or Borland C:
      void huge my_timer(void)

    3. Microsoft C:
      void far _saveregs _loadds my_timer(void)

    4. Turbo Pascal:
          procedure Timer1_Proc;interrupt;
          begin
          
          [... your code ...]
          
          (************************************************)
          (* This is needed at the end of the Timer Proc. *)
               asm
               POP BP
               POP ES
               POP DS
               POP DI
               POP SI
               POP DX
               POP CX
               POP BX
               POP AX
               RETF
               end;
          (************************************************)
          end;


    5. DOS applications are running as an @CHIP-RTOS task with a default priority of 25.   If the user application does not yield, lower priority tasks like the FTP server or the Web server will not work.   In major loops within user applications, the programmer should insert sleep calls (or otherwise yield the CPU) if the FTP or Web servers' operation is desired during the execution of the user application.

    6. The stack of a task created inside of a DOS application should have a minimum stack size of 1024 Bytes.   Programmers of task functions who are using Microsoft C-Compilers with C-Library functions, e.g. sprintf, which requires a lot of stack space should increase this allocation to 6144 (6 Kbytes).   More stack space for the task is also required if your task function uses a large amount of stack for automatic data (local variables) declared inside the task function call.

    7. Declaring of task functions with Paradigm or Borland C:
      void huge my_task(void)

    8. Declaring of task functions with Microsoft C:
      void far _saveregs _loadds my_task(void)

    9. Before exiting an application, every task or timer procedure created inside of the application program must be removed.

    10. A sleep call with parameter 1 millisecond takes equal or less than one millisecond.   If a user needs a minimal sleep time of 1 millisecond then RTX_SLEEP_TIME must be called with value 2 milliseconds.

    11. It is possible to create tasks with a time slicing value in the taskdefblock structure..   Please note that the kernel executes time slicing only between tasks which have the same priority.   Other priority tasks are not affected.

      RTOS API


    Top of list
    Index page

    Programming CGI functions


    1. Avoid large loops inside of CGI functions.   CGI functions must be executed as fast as possible.   Long execution times in CGI functions block the Web server task, preventing response to other HTTP requests.

    2. Declaring of CGI functions with Paradigm or Borland C:
      void huge my_cgi_func(rpCgiPtr CgiRequest)

    3. Declaring of CGI functions with Microsoft C:
      void far _saveregs _loadds my_cgi_func(rpCgiPtr CgiRequest)

    4. Declaring of CGI functions with Borland Turbo Pascal:
      procedure my_cgi_func;interrupt;

    5. Turbo Pascal users must install their CGI functions with API call Install CGI Pascal function

    6. C-Programmers must use Install CGI function

    7. Avoid the declaration of large arrays as local variables inside
      of the CGI function to prevent stack overflows

    8. Users of Microsoft C should set Web server stacksize in chip.ini up to 6144 Bytes, to prevent stack overflows, if Microsoft C-library functions like sprintf are used.

    9. Dynamic HTML or text pages which are created inside a user CGI function should be as small as possible.   The Web server inside must allocate a temporary buffer for storing this page before sending it to the browser.   If your application builds large dynamic HTML page in RAM, your application should not use all available memory in the IPC@CHIP® because the Web server will need some memory for allocating temporary buffers for this page.   How much memory should be left depends on the application and the sizes of the created dynamic HTML or CGI pages.

    10. Before exiting an application, every CGI function installed by the application must be removed with the Remove CGI page API.


      CGI API


    Top of list
    Index page

    Configure the FTP server


    The default FTP idle timeout is set to 300 seconds.   This is a very long time for waiting, if FTP commands fail.   The idletimeout can be reduced in chip.ini.


    Top of list
    Index page

    Usage of the TCP/IP API


    1. Processing in a socket callback function (see Register callback) should be kept at a minimum to prevent stack overflows.

    2. Declaring of socket callback functions with Paradigm or Borland C:
      void huge my_callback(int socketdescriptor,
                      int eventflagmask)


    3. Declaring of socket callback functions with Microsoft C:
      void far _saveregs _loadds my_callback(int sd,
                      int eventmask)


    4. The internal TCP/IP stack of the IPC@CHIP® allocates memory for buffers smaller than 4096 bytes from a pre-allocated memory block, for private use by the TCP/IP stack.   Larger buffers are allocated direct from the @CHIP-RTOS-x86 main system heap.   If user TCP/IP network communication sends and receives packets larger than 4096 bytes, the user application should not use all available memory in the IPC@CHIP® in order that the TCP/IP stack can allocate space for these large packets from the system's main heap.   There should be in that case always a minimum of 30-40 KBytes of free available memory in the system's main heap.   The MEM command list at runtime the status of all memory blocks in the system's main heap.   The maximum amount of TCP/IP memory can be configured at chip.ini (see [IP] TCPIPMEM).   The application programmer can reduce or increase this size in chip.ini.   The Get_TCPIP_Memory_Status() API can be used to observe the TCP/IP memory usage at application runtime.

      The amount of memory required by the TCP/IP stack depends on the number of open sockets and the size and number of data packets transported.   We recommended testing with all of your TCP/IP applications executing simultaneously in order to check how much memory is required from the TCP/IP stack's pre-allocated block.   This result should be used by the application engineer to set the TCPIPMEM entry of chip.ini to a sufficient value (a reserve of about 20%-30% is recommended).

      The BIOS_Install_Error_Handler() API may be used to install a user error handler callback function which the system will invoke if this TCP/IP memory limit is reached (among other reasons).

    5. The TCP/IP stack of the @CHIP-RTOS supports multiple interfaces and multiple IPs on the same physical interface. Anyhow, there are some restrictions that should be noticed.

      • Each interface must be assigned with an unique IP address. The same IP address is not allowed on any other active interface.

      • Each interface IP address should be located in a different network. It does not make sense to connect two or more interfaces to the same network, because the @CHIP-RTOS does NOT check automatically when sending a frame if the connectivity on the outgoing link is down. Therefore the traffic will NOT automatically be routed via one of the remaining links. The outgoing traffic will always be send over the first matching interface, regardless whether this interface has a link or not. If multiple interfaces should be connected to the same network, e.g. WLAN and Ethernet, a special user application is required that assures that only one interface is configured and active at the same time.


      • Each interface can have multiple (up to five) IP addresses. These IP addresses may be located in different networks, but multiple IP addresses in the same network are also possible here. Additionally, DHCP and fixed IP addresses can be combined this way.


    See also:


    Top of list
    Index page

    General notes for the usage of the DOS and @CHIP-RTOS int API calls


    1. At the start of a user program the Stdio focus should be set to USER. Before ending the application switch the focus back to SHELL or BOTH (see Set Stdio focus).

    2. If more than one user program runs in the IPC@CHIP®, only one of them should read characters from Stdin

    3. The functionality of most of the shell commands is also available through calls into the @CHIP-RTOS INT API.   If not, use the @CHIP-RTOS BIOS execute shell command INT call accessible through the BIOS_Execute C-library function.   This call executes a shell command from inside the user application.

    4. User error handler can be installed with the BIOS_Install_Error_Handler API.   The user callback could then, for example, execute a BIOS_Reboot to reset the IPC@CHIP® on fatal errors.

    5. Used RTOS software interrupts:

      0x00 - Reserved (@CHIP-RTOS Divide Overflow Handler)
      0x01 - Reserved (Debugger Trace Interrupt)
      0x02 - Reserved (Hardware Non-Maskable Interrupt (NMI))
      0x03 - Reserved (Debugger Breakpoint Interrupt)
      0x04 - Reserved (@CHIP-RTOS INTO Overflow Handler)
      0x05 - Reserved (@CHIP-RTOS Array Bounds Exception Handler)
      0x06 - Reserved (@CHIP-RTOS Invalid Opcode Exception Handler)
      0x07 - Reserved (@CHIP-RTOS ESC Opcode Exception Handler)
      0x08 - Reserved (Hardware, Timer #0 Handler)
      0x09 - Reserved
      0x0A - Reserved (Hardware, DMA #0 / INT5 Handler)
      0x0B - Reserved (Hardware, DMA #1 / INT6 Handler)
      0x0C - Reserved (Hardware, INT0 Handler)
      0x0D - Reserved (Hardware, INT1 Ethernet Handler)
      0x0E - Reserved (Hardware, INT2 Handler)
      0x0F - Reserved (Hardware, INT3 Handler)
      0x10 - Biosint (and Hardware UART #2 Handler)
      0x11 - Biosint (and Hardware UART #1 Handler)
      0x12 - Reserved (Hardware, Timer #1 Handler)
      0x13 - Reserved (Hardware, Timer #2 Handler)
      0x14 - Fossil Interface (and Hardware UART #0 Handler)
      0x15 - Reserved (Hardware INT5, UART #3 Handler)
      0x16 - Biosint (and Hardware, DMA #2 Handler)
      0x17 - Reserved (Hardware, DMA #3 Handler)
      0x18 - Reserved (Hardware, CAN Handler)
      0x1A - Biosint
      0x1C - Timer Interrupt, see Set timer 1C interval
      0x20 - Terminate Program (Only for compatibility, instead use DOS service 0x4C)
      0x21 - DOSEmu Interrupt Interface
      0x34 thru 0x3E - Used by Borland (or Paradigm) floating-point emulator
      0x51 - Floating Point Emulator (Paradigm Beck Edition)
      0xA0 - Several 'chip' related services
      0xA1 - Hardware API (HAL)
      0xA2 - Hardware API (PFE)
      0xAA - I2C / SPI Interface
      0xAB - CGI / SSI Interface
      0xAC - TCP/IP API
      0xAD - RTOS API
      0xAE - Ethernet Packet Driver
      0xAF - Timer Interrupt, see Set timer AF interval
      0xB0 - External Disk API
      0xBF - USB and CAN API's (SC1x3/SC2x only)

    6. Used Add-on driver software interrupts:

      0x67 - Dynamic Library Service
      0x6F - BCxxx device driver
      0xB1 - External Disk Driver
      0xB2 - External Disk Driver (SC1x3/SC2x only)
      0xC0 - PPPoE API (SC1x3/SC2x only)
      0xC1 - WLAN WL01/WL03 API (SC1x3/SC2x only)
      0xC2 - ETH1 Packet driver interface (SC1x3/SC2x only)
      0xC3 thru 0xCF - Reserved for future drivers

    7. Software interrupts that can be freely used inside user applications:

      0xD0 thru 0xDF - These vectors are available for user applications

    8. External hardware interrupts are enabled (STI opcode) during execution of the following API software interrupts:

        DOS ints 0x10, 0x14(Fossil), 0x16, 0x20, 0x21, @CHIP-RTOS int 0xA0, PFE int 0xA2, I2C int 0xAA, CGI int 0xAB, Pkt int 0xAE, Extdisk int 0xB0, Extdisk user int 0xB1, CAN/USB int 0xBF


      The state of the interrupt flag is not changed during the execution on the following API software interrupts (If interrupts are disabled before the API call, they are kept disabled during execution of the call. If interrupts are enabled before the API call, they get reenabled during execution of the call.):

        TCPIP int 0xAC, RTOS int 0xAD


      External hardware interrupts are disabled during execution of the following API software interrupts:

        HAL int 0xA1



      BIOS ints
      Int21h


    Top of list
    Index page

    Using Hardware API


    1. The HAL functions keep interrupts disabled, so you can call them inside an interrupt routine. The PFE functions are only for choosing and initializing a specific function on the selected pin.   They should be called once in your application for initializing your hardware environment and not at runtime or inside interrupt routines.

    2. Do not use functions of the RTOS API inside of a normal HW API user ISR. For this purpose install a RTX user ISR, see Install ISR.

    3. The latency time of the user ISR (from generation of an interrupt until first line of code inside the user ISR) depends on the used IPC@CHIP®, see Performance comparison .

    4. Instead of HAL functions Read data bus and Write data bus you can call C-functions inportb and outportb from DOS.H for faster data bus accesses.

    5. Usage of DMA0/INT5 and DMA1/INT6:
      DMA0 and INT5 are served inside the @CHIP-RTOS with a single shared interrupt handler.   (Likewise for DMA1 and INT6.)
      If a user application has activated serial EXT DMA mode and also wants to use external interrupt INT5, the DMA interrupt event is higher priority.  (And again, likewise for COM DMA mode and INT6.)
      This means that if a DMA0/1 interrupt occurs simultaneous with an external INT5/6 interrupt, the installed user handler for the external interrupt is not called.

      See Hardware API

    6. Usage of NMI/Power fail detection:

      The NMI function of the multifunction pin 17 (RESET/NMI/LINK_LED) of the IPC@CHIP® SC11/SC12/SC13 is for power fail purposes only.   It is not possible to use NMI as a "normal" interrupt pin like e.g. INT0 for generating interrupts.   It can only be used as described in the IPC@CHIP® hardware documentation.

      The flowchart below describes how the @CHIP-RTOS handles an incoming NMI interrupt.



      See also:


    Top of list
    Index page

    Using Fossil API


    1. The receive and send queue size can be configured over the CHIP.INI.

    2. If you want to use external DMA, you have to disable the serial DMA receive mode.   Otherwise the DMA receive mode is recommended.

    3. Since SC12 @CHIP-RTOS 1.02B XON/XOFF mode is available also with the serial DMA receive mode in use.
      Please note:   Because of the internal functionality of DMA it is not possible to immediately detect an XON or XOFF character from the connected peer.   It is possible that an overrun situation at the peer (e.g. GSM modem) can occur.   Nevertheless, we enable this mode because some GSM modems (any??) support only XON/XOFF as serial flow control mechanism.

    4. The default serial receiver queue size is 1024 bytes.   If the default DMA receive mode is used, it is advised to increase the receiver queue size in Chip.ini up to a minimum value of 2048 bytes to prevent a possible buffer overrun (even if hardware handshake is used).   This can only happen with the default queue size of 1024 bytes if the user doesn't call the Fossil API read block function frequently enough.   If the application programmer does not increase this buffer size up to the recommended value, they should call the Fossil API read block function with sufficient buffer size in the CX-Register to flush the internal buffers and prevent a receive buffer overrun.

    5. Serial ports, running with IRQ receive mode:
      The two serial ports of the SC1x IPC@CHIP® have no hardware FIFO buffer.   Only one incoming character can be stored directly by the ports.  (SC1x3/SC2x IPC@CHIP® serial ports have a four deep receiver FIFO.)   As a consequence of this hardware, it is possible that incoming characters get lost due to delayed receiver interrupt execution (see Operating mode of serial ports).   For example, writing a flash sector (which occurs when writing a file to drive A:) disables all interrupt execution in SC1x systems for about 15 ms.  (For SC1x3/SC2x, the interrupts are not masked throughout the sector write period.)   If the serial port is configured with a baud rate of 9600, incoming characters can be lost during this time.

      Loss or delayed execution of serial receiver interrupts depends on the number and the execution frequency of all enabled interrupts in the IPC@CHIP® system.   It depends also on execution times of user interrupt service functions and the duration of interrupt masking periods (CLI / STI instruction sequences).

    6. For a given serial port the fossil functions are not all reentrant.   However you may, for example, call the transmitter services from task A and receiver services from task B without problems.  The port must first be configured before this concurrent operation of transmitter and receiver is permissible.  For different serial ports the fossil functions are fully reentrant, including the port configuration functions.  The behavior of the fossil API when a serial port device is used in a reentrant fashion (e.g. two tasks attempt to call a transmitter service at the same time for the same device) is controlled within the API using a semaphore, one semaphore for send and another for receive.

      Fossil API


    Top of list
    Index page

    Working with Float Data Types


    1. The IPC@CHIP® does not provide a floating point co-processor.   So if you want to use floating point data types you need to enable the math-emulation in your compiler.   In Paradigm Beck Edition or Borland C++ 5.02 see the option "Emulation" under the Target Expert's (right mouse click on your Exe-file in your project) "Math Support".

      CAUTION:    The floating-point emulators are implemented using a set of software interrupts.   Consequenctly, only a single DOS program may use the floating-point emulators at any one time.   Otherwise one of your DOS programs is likely to crash during floating-point usage.

    2. Using the floating-point math emulation inside @CHIP-RTOS tasks with the Paradigm Beck Edition is relatively simple.  Three things must be considered.

      1. Do not use memory model small or medium.
      2. Assure that the task's stack includes offset zero. (See discussion below how this can be achieved.)
      3. Call _fpinit() from your @CHIP-RTOS task before performing any floating-point operations to initialize the task's stack for use by the floating-point emulator.   (The prototype for the _fpinit() library function is declared in the header file float.h.)

      If for some reason your code must be compatible with both the Borland 5.02 and Paradigm Beck Edition compilers, or if you have an older Borland 5.02 program which you want to leave as is, you can also use the more complicated floating-point initialization required for Borland 5.02 described below.   The Paradigm Beck Edition compiler tolerates this form of floating-point initialization as well.

    3. The Borland/Paradigm Math Emulation libraries are not made for usage in a multitasking system like the @CHIP-RTOS.   If you want to use float data types in tasks other than your main (DOS) task, please pay attention to the following work around solution:

      1. For floating point emulator usage, the current stack (the stack of the task) must have offset 0.   One way to achieve this is to allocate the task stack memory directly from the @CHIP-RTOS memory pool using int21h 0x48 (or the corresponding helper_alloc_rtos_mem CLIB function).

            unsigned int task_stacksegment =
                         helper_alloc_rtos_mem(STACK_SIZE);
            unsigned char * task_stackptr =
                         MK_FP(task_stacksegment, 0);

            task_defblock.stackptr = &task_stackptr[STACK_SIZE];
            task_defblock.stacksize = STACK_SIZE;

        Another way is to normalize a pointer for the task stack:

            #define PARAGRAPH_SIZE (16)
            unsigned char task_stack[STACK_SIZE+PARAGRAPH_SIZE];
            unsigned int huge *fp_huge_stack;
            unsigned char far *fp_stack;

            fp_huge_stack = (unsigned int huge *)
                &task_stack[PARAGRAPH_SIZE-sizeof(unsigned int)];
            fp_huge_stack++; //Compiler normalizes pointer
            fp_stack = (unsigned char far *)
                MK_FP(FP_SEG(fp_huge_stack), 0);
            task_defblock.stackptr = (unsigned int far *)
                &fp_stack[STACK_SIZE];
            task_defblock.stacksize = STACK_SIZE;

        Notes:
        • For SC1x3/SC2x IPC@CHIP® systems, the PARAGRAPH_SIZE is 256 instead of 16.
        • The CGI callbacks execute on the Web server's stack, which satisfies this "offset 0 present" requirement.

      2. Before executing floating point arithmetic inside tasks, the current stack must be pre-initialized for math emulation.

        Within Paradigm Beck Edition this is done by calling the _fpinit() function.
        Example for a task function:

            void huge my_task(void)
            {
                float a;
                _fpinit();
                // Ready for floating point arithmetic
            }

        Within Borland 5.02 this can be achieved with the following code.
        Example for a task function:

            void my_emu1st(void)
            {
                asm{
                    // Set end of FPU stack
                    mov word ptr ss:[0x2f],0x0065
                    // Set start of FPU stack
                    mov word ptr ss:[0x31],0x0125
                    mov word ptr ss:[0x27],0 // no protected mode
                    mov byte ptr ss:[0x26],0 // no 8087
                }
            }

            void huge my_task(void)
            {
                float a;
                my_emu1st();
                _fpreset();
                // Ready for floating point arithmetic
            }

      If you are interested in more details, take a look at the Paradigm or Borland 5.02 RTL sources (fpinit.asm).   We provide an example for using floating point arithmetic in separate tasks or within CGI callbacks.

    4. Using Math emulation with Borland C++ 5.02 (also for older versions of Borland C) produces a conflict between the NMI interrupt of the @CHIP-RTOS (Interrupt Vector 0x02) and the Borland floating exception handling.   Borland C math emulation also uses INT 2 for generating floating point exceptions.   Our internal NMI interrupt service function (normally called at power fail case) will no longer execute during the runtime of the user's application.   We have provided a solution which moves the Borland exception function from INT 2 to another interrupt vector.   We modified the Borland RTL source (fpinit.asm) and include the modifications directly into the application project.   An example is provided in our Internet download area.

      Note:  For Paradigm Beck Edition compiler there is no conflict between NMI vector and the floating point exception handler.   The Paradigm compiler uses interrupt 0x51 for the floating point exception.


    Top of list
    Index page

    Configure PPP client or server


    1. Connected modems should be configured in chip.ini with the modem command ATE0 INITCMD.   This prevents the modem from echoing characters to the peer in command mode.   The COM and the serial ports of the IPC@CHIP® have only 4 lines (TxD/RxD/CTS/RTS) and no line for detecting a hang-up of the modem.   Because of this fact we provided the Idletimeout and the MODEMCTRL configuration features in chip.ini or in the PPP client initialization structure. But the idletimeout and modemctrl detection can fail if a modem has switched its echo mode on.   If the peer modem hangs up without correctly closing a PPP session, the IPC@CHIP® modem also hangs up and goes into the command mode.   Because of the missing line for detecting a modem hang-up, the PPP server doesn't know anything about the broken connection and still sends PPP frames to the modem.   It can happen that the modem echoes these characters back to the IPC@CHIP® due to being in "Echo on" mode.   This will cause the idletimeout to not work.

    2. We recommend that the PPP server or client and the connected modems should run (if possible) with RTS/CTS flow control (see chip.ini flow control mode or the PPP client initialization structure).   Most modems use RTS/CTS flow control, if they get the AT command AT\Q3.

    3. The COM and EXT port of the IPC@CHIP® has only CTS, RTS, RxD and TxD lines, so you have to configure your modem with DTR always on (e.g. AT cmd for a most modem types: AT&D0).

    4. If the option PPP_IPCP_PROTOCOL (VJ TCP/IP header compression) is set (see PPPCLIENT_SET_OPTIONS), it is possible that the FTP server of the IPC@CHIP® is not usable via the PPP interface.   This was noticed at PPP sessions connected to a Linux PPP peer.

      PPP


    Top of list
    Index page

    SC1x3/SC2x Extended Memory and EXE File Format

    Extended Memory


    The SC1x3/SC2x computers operate with a 256 byte paragraph size instead of the conventional 16 byte paragraphs on traditional DOS computers.   This means that translation between segmented addresses and linear addresses on the SC1x3/SC2x systems would be done as:

      typedef unsigned long DWORD ;
      void far *ptr ;
      DWORD linear_addr = ((DWORD) FP_SEG(ptr) << 8 )
                                 + FP_OFF(ptr) ;

    as opposed to the traditional DOS x86 computer's similar calculation:

      DWORD linear_addr = ((DWORD) FP_SEG(ptr) << 4 )
                                 + FP_OFF(ptr) ;

    This provides the SC1x3/SC2x with an address space of 2**24 bytes, or 16 MByte which overcomes the standard DOS limitation of 1 MByte address space (2**20).

    EXE File Format


    The Paradigm Beck IPC Edition compiler's linker takes into consideration this 256 byte paragraph size as it allocates the segments for an extended mode program.   The resulting EXE executable file header is tagged with an 'MX' designation to distinguish it from a standard 'MZ' DOS program EXE.   This allows the @Chip-RTOS to detect if an EXE has been properly linked for the respective target system type.   The error message

      "file is not a valid executable"

    is issued to the console if an attempt is made to use an EXE type not suited for the particular system.

    Below is the EXE header data structure, as viewed by the @CHIP-RTOS.   Structure members which receive special handling by the @CHIP-RTOS are highlighted.

    typedef struct {
       union {
         unsigned char Byte[2];
         unsigned int Word;
       } Signature ;
       unsigned int  nBytesLastPage;         // 02, 03
       unsigned int  nPages;                 // 04, 05
       unsigned int  nRelocations;           // 06, 07
       unsigned int  nParagraphsHeader ;     // 08, 09
       unsigned int  minParagraphs ;         // 0xA
       unsigned int  maxParagraphs ;         // 0xC
       unsigned int  initialSS;              // 0xE
       unsigned int  initialSP;              // 0x10
       unsigned int  chksum;                 // 0x12
       unsigned int  initialIP;              // 0x14
       unsigned int  initialCS;              // 0x16
       unsigned int  startOfRelocationtable; // 0x18
       unsigned int  nOverlays ;             // 1A
       unsigned long Time_Tag ;              // 0x1C
       unsigned int  _Pad1;                  // 0x20
       unsigned int  RN_Tag ;                // 0x22
       unsigned int  _Pad2 ;                 // 0x24
       unsigned long ActualFixupEntries;     // 0x26
       unsigned int  _Pad3;                  // 0x2A through 0x2B
       unsigned long ParadigmTimeTag ;       // 0x2C
    } FILE_HEADER;

    #define RN_SIGNATURE    (((WORD)'N' << 8) | 'R')

    The SC1x3/SC2x @CHIP-RTOS uses special handling for the following members of the EXE file header.

    Signature - These two bytes must be 'M', 'X' in order to launch on the SC1x3/SC2x.   The 'M', 'Z' DOS programs will not launch with one exception:   If the nOverlays member is set to magic number 0xABCD, then the program is considered to be a legal TINY program and it will be launched provided that the stack space indicated by initialSS and initialSP members fits within the program's single 64 Kbyte segment.

    nParagraphsHeader - This is the number of 16 byte DOS paragraphs which the EXE file header occupies.   Note that the paragraph size used here is 16 bytes for either extended mode (SC1x3/SC2x) or normal DOS (SC1x).

    minParagraphs - This is the minimum number of paragraphs that the @CHIP-RTOS will allocate as the program is loaded.   Here hardware paragraph size is used, which is 16 bytes for SC1x and 256 bytes for the extended mode SC1x3/SC2x computers. (Exception: The flat memory 'M', 'Z' TINY DOS programs which run on either target use 16 byte paragraph size here.)

    maxParagraphs - This is the maximum number of paragraphs that the program needs.   This value is not used by the @CHIP-RTOS.   It is mentioned here only to state that hardware paragraph size is used, which is 16 bytes for SC1x and 256 bytes for the extended mode SC1x3/SC2x computers.

    Time_Tag - Place where TIMETAG tool outputs a 32 bit build timestamp, seconds past year 1969.   When the Paradigm Beck IPC Edition compiler linker is used, this field is ignored.


    RN_Tag - Special indicator set by Paradigm Beck IPC Edition compiler linker to indicate that the program time-tag should be taken from the ParadigmTimeTag location, alternative to the old Beck convention at offset 0x1C.   This field is set to RN_SIGNATURE by the Paradigm Beck IPC Edition linker.

    nOverlays - Set to 0xABCD in order to force execution of a 'M', 'Z' type DOS program on SC1x3/SC2x.   (Note:   One way this header field can be set to 0xABCD is with the -x option on the TIMETAG tool distributed with Debug@Chip.   Only specially prepared flat memory model (TINY) standard DOS programs can be expected to execute on the SC1x3/SC2x.   The PROBE.EXE used by the debuggers and the CHIPEDIT.EXE example program are such flat memory model programs, which can be executed on both SC1x and SC1x3/SC2x targets.   For any normal SC1x3/SC2x program, the Paradigm Beck IPC Edition compiler's linker must be used.   Creating the cross-target flat memory programs is not straight forward and is beyond the scope of the support users can expect from Beck.   These type programs are mentioned here only to make this @CHIP-RTOS EXE header documentation complete.)

    ParadigmTimeTag - This build timestamp is automatically set by the Paradigm Beck IPC Edition compiler linker. This 32 bit build timestamp (seconds past year 1969) is used by the debuggers to correlate target code with symbol tables.



    Top of list
    Index page

    Optional SC1x3/SC2x Libraries

    Two optional libraries are available for SC1x3/SC2x application programs:


    Top of list
    Index page


    End of document