readme.txt

mDOC在VxWorks开发环境下的详细开发文档。

        Argument 'handle' is constructed by macro tffsMakeHandle() based on
        "socket's" and "disk's" sequential numbers:


            #include "fldrvvxw.h"

            int  handle = tffsMakeHandle (socketNo, diskNo);


        ===> NOTE.  See generic example in Section 2.14.1 if you need to relate
                    'XBD device' to socketNo/diskNo pair.

        Argument 'partNo' must be specified as '-1', and argument 'action' must
        be specified as '1'.

        For example, in the typical case when there is single mDOC
        "socket" in the system, with the single "disk" on it (see definition of
        terms "socket" and "disk" in Chapter 1), application could use the
        following code fragment to initialize file system partitions:


            #include <dosFsLib.h>
            #include "fldrvvxw.h"

            int     iSocket;
            int     iDisk;
            int     handle;
            int     iPart;
            char    name[32];
            STATUS  status;

            /* 'totalPartitions' was defined in Section 2.15.2 */

            for (iPart = 0; iPart < totalPartitions; iPart++)
                {
                /*
                 * Assuming file system partitions were assigned names
                 * "/tffs0:1", "/tffs0:2" etc.
                 */

                sprintf( name, "/tffs0:%c", (char)('1' + iPart) );

                /* initialize file system partition */

                status = dosFsVolFormat (name, DOS_OPT_BLANK, NULL);
                if (status == ERROR)
                    {
                    /* eror */
                    }
                }

            /* inform mDOC driver */

            iSocket = 0;
            iDisk   = 0;
            handle  = tffsMakeHandle (iSocket, iDisk);

            tffsPartCtrl (handle, -1, 1);

2.15.4. You may call routine tffsHowManyParts() if you need to find out how
        many file system partitions exist on specific 'XBD device'. Here is
        declaration of this routine taken from fldrvvxw.h :

            extern STATUS  tffsHowManyParts (int handle, int *parts);

        Argument 'handle' is constructed by macro tffsMakeHandle(), based on
        "socket's" and "disk's" sequential numbers:


             #include "fldrvvxw.h"

             int  handle = tffsMakeHandle (socketNo, diskNo);


        ===> NOTE.  See generic example in Section 2.14.1 if you need to relate
                    'XBD device' to socketNo/diskNo pair.

        Argument 'parts' is a pointer to integer variable where routine
        tffsHowManyParts() returns result to.

        For example, in the typical case when there is single mDOC
        "socket" in the system, with the single "disk" on it (see definition of
        terms "socket" and "disk" in Chapter 1), application could use the
        following code fragment to find out number of file system partitions:


            #include "fldrvvxw.h"

            int     totalPartitions = 0;
            int     iSocket;
            int     iDisk;
            int     handle;
            STATUS  status;

            iSocket = 0;
            iDisk   = 0;

            handle = tffsMakeHandle (iSocket, iDisk);

            status = tffsHowManyParts (handle, &totalPartitions);
            if (status != OK)
                {
                /* error */
                }


2.15.5. If "Dos FS Cache Handler" component have been included, a read cache
        of a default size is automatically created for every file system
        partition. You can change the size of the cache by first destroying
        the cache with dosFsCacheDelete() and then re-creating the cache
        with dosFsCacheCreate(). These routines are part of VxWorks
        'dosFsCacheLib' library.

        For example, in the typical case when there is single mDOC
        "socket" in the system, with the single "disk" on it (see definition of
        terms "socket" and "disk" in Chapter 1), application could use the
        following code fragment to change cache size of every file system
        partition:


            #include <dosFsLib.h>
            #include "fldrvvxw.h"

            int     totalPartitions = 0;
            int     iSocket;
            int     iDisk;
            int     iPart;
            int     handle;
            STATUS  status;
            char    name[32];

            iSocket = 0;
            iDisk   = 0;

            handle = tffsMakeHandle (iSocket, iDisk);

            status = tffsHowManyParts (handle, &totalPartitions);
            if (status != OK)
                {
                /* error */
                }

            for (iPart = 0; iPart < totalPartitions; iPart++)
                {
                /*
                 * Assuming file system partitions were assigned names
                 * "/tffs0:1", "/tffs0:2" etc.
                 */

                sprintf( name, "/tffs0:%c", (char)('1' + iPart) );

                /* destroy old cache */
                dosFsCacheDelete(name);

                /* re-create the cache with a new size of 128KB */
		status = dosFsCacheCreate(name, 0, (128*1024));
		if (status != OK)
		    {
                    /* error */
                    }
		}

        ===> NOTE.  Size of the disk cache should be selected based on desired
                    I/O performance, anticipated I/O pattern, and concerns
                    related to file system's consistency in case of unexpected
                    system shutdowns. Generally, the larger the disk cache is,
                    the higher the I/O performance (especially the I/O 'read'
                    performance). On the other hand, larger disk cache usually
                    means higher chances that file system will be left in
                    inconsistent state in case of unexpected system shutdown.
                    The selection of disk cache size is usually system-specific
                    process of finding the right balance between these two
                    considerations.



3. BOOTING VXWORKS FROM mDOC
----------------------------

3.1. There are two basic VxWorks boot scenarios supported by mDOC driver:

         A.  One-step boot

             This scenario is used with relatively small VxWorks applications
             that can entirely fit into system's ROM.

             In this case VxWorks bootimage, along with VxWorks, includes 
             application and mDOC driver.

         B.  Two-step boot

             This scenario is used with larger VxWorks applications where 
             scenario 'A' cannot be used because of application's size.

             Two different bootimages are involved in this boot scenario - 
             'bootrom' and 'vxWorks'.

             The 'bootrom' bootimage resides in system's ROM. It includes minimal
             configuration of VxWorks (which includes dosFs2 file system) and
             mDOC driver; it does not include user application itself.
             Essentially, 'bootrom' bootimage is a program loader. It gets executed
             upon reset, and uses mDOC driver for loading the second bootimage -
             'vxWorks' - from mDOC. The 'vxWorks' bootimage includes the
             full configuration of VxWorks, mDOC driver, and user's
             application.

     If you are using boot scenario 'A', proceed with instructions in
     Section 3.2.

     If you are using boot scenario 'B', proceed with instructions in
     Section 3.3.

3.2. If you are using boot scenario 'B', skip this Section, and proceed with
     Section 3.3 instead.

     Boot scenario 'A' does not require any changes in VxWorks boot code. 

     All user has to do, is to place bootimage to board's ROM.
     
     If at that point user boots the system, bootimage will get executed. Once
     bootimage is up and running, user should see mDOC appearing in
     system's device list (produced by Shell's 'devs' command), under the 
     name "/tffs0" or "/tffs0a". 

     You are done; skip the rest of Chapter 3. 

3.3. In case if you are using boot scenario 'A', skip Section 3.3, and proceed
     with Section 3.2 instead.

3.3.1. If you are using boot scenario 'B', you will need to modify the following
       VxWorks files:

           - BSP configuration .H file (<tornado>/target/config/<bsp>/config.h)
           - <tornado>/target/config/all/bootConfig.c
           - <tornado>/target/config/all/usrConfig.c

       and build bootimage(s) in order to boot VxWorks application off the 
       mDOC. Sections 3.3.2 - 3.3.17 explain how to do this.

3.3.2. Add the following line to BSP configuration file 
       <tornado>/target/config/<bsp>/config.h:

           #define INCLUDE_DISKONCHIP   /* msystems mDOC */

3.3.3. Change DEFAULT_BOOT_LINE in BSP configuration file 
       <tornado>/target/config/<bsp>/config.h to look similar to this:


           #define DEFAULT_BOOT_LINE \
               "tffs=0,0(0,0)host:/tffs0/VxWorks h=90.0.0.3 e=90.0.0.50 u=target"


       ===> NOTE.  Bootline above instructs 'bootrom' bootimage to look for file 
                   named "VxWorks" in the root directory of device "/tffs0/" 
                   (which is mDOC). If you want to name your application
                   differently, or place it into location other than the root 
                   directory, you have to change bootline accordingly.

3.3.4. Excluded.

3.3.5. Modify file <tornado>/target/config/all/bootConfig.c to add the following 
       code fragment under #define INCLUDE_DISKONCHIP:


           #ifdef  INCLUDE_PCMCIA
           LOCAL STATUS  pcmciaLoad (int sock, char *fileName, FUNCPTR *pEntry);
           #endif  /* INCLUDE_PCMCIA */

           #ifdef  INCLUDE_TFFS
           LOCAL STATUS  tffsLoad (int drive, int removable, char *fileName, 
                                   FUNCPTR *pEntry);
           #endif  /* INCLUDE_TFFS */

           #ifdef  INCLUDE_DISKONCHIP
           LOCAL STATUS  tffsLoad (int drive, int removable, char *fileName, 
                                   FUNCPTR *pEntry);
           #endif  /* INCLUDE_DISKONCHIP */


3.3.6. Modify file <tornado>/target/config/all/bootConfig.c to add the following
       code fragment under #define INCLUDE_DISKONCHIP:


           #ifdef  INCLUDE_PCMCIA
           LOCAL STATUS  pcmciaLoad ();
           #endif  /* INCLUDE_PCMCIA */

           #ifdef  INCLUDE_TFFS
           LOCAL STATUS  tffsLoad ();
           #endif  /* INCLUDE_TFFS */

           #ifdef  INCLUDE_DISKONCHIP
           LOCAL STATUS  tffsLoad ();
           #endif  /* INCLUDE_DISKONCHIP */


3.3.7. If you are not using Workbench version 2.4 skip to Section 3.3.7.1.
       If you are using Workbench version 2.4, skip to Section 3.3.7.2.

3.3.7.1. If you are using Workbench 2.4, skip this Section, and follow
         instructions in Section 3.3.7.2 instead.

         Modify file <tornado>/target/config/all/bootConfig.c to add the following
         code fragment under #define INCLUDE_DISKONCHIP, just before routine
         usrInit():


           #ifdef  INCLUDE_DISKONCHIP

           #ifdef __cplusplus
           extern "C" {
           #endif

           #ifndef _ASMLANGUAGE

           #include "fldrvvxw.h"

           #endif  /* _ASMLANGUAGE */

           #ifdef __cplusplus
           }
           #endif

           /* forward declarations */

           #ifdef  __STDC__
           void devSplit (char *fullFileName, char *devName);
           #else
           void devSplit ();
           #endif  /* __STDC__ */


           STATUS usrTffsConfig
               (
               int     drive,     /* TFFS handle (usually zero)   */
               int     removable, /* 0 - nonremovable flash media */
               char *  fileName   /* mount point                  */
               )
               {
               BLK_DEV * pBootDev;
               char bootDir [BOOT_FILE_LEN];
               CBIO_DEV_ID cbio, rawdisk;
               char name[32];