readme.txt

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

         #include "fldrvvxw.h"

         /* address ranges to search for 3 mDOCs */

         long  tffsAddresses[] = { 0xc00d0000, 0xc00d1fff, /* 1st mDOC */
                                   0xc00d2000, 0xc00d3fff, /* 2nd      */
                                   0xc00d4000, 0xc00d5fff; /* 3rd      */
                                 }; 

         /* tell driver to detect up to 3 mDOCs */

         tffsSetup (3, tffsAddresses);


     In a common case when there is single mDOC installed in the system at
     well known address, it makes sense to prevent driver from scanning host 
     address space for mDOC. In such cases, both upper and lower bounds of
     the search range could be set to the exact mDOC address. For instance,
     if mDOC is always installed at address 0xc00d0000, then application
     can tell driver to look for mDOC at this particular address only:


         #include "fldrvvxw.h"

         /* exact address to look for single mDOC */

         long  tffsAddresses[] = { 0xc00d0000, 0xc00d0000 };

         /* tell driver to detect single mDOC */

         tffsSetup (1, tffsAddresses);

2.7. Excluded.

2.8. mDOC driver features number of configuration options, which are
     described in detail in Chapter 8. Default settings of these options should
     be adequate for most applications. If you wish, for some reason, to change
     some of these configuration options, then do it at this stage. 

     ===> NOTE.  All driver's configuration options must be set to their desired
                 values BEFORE calling driver's initialization routine tffsDrv().
                 Once routine tffsDrv() has been called, configuration options
                 must NOT be changed.

2.9. mDOC driver must be initialized by calling routine tffsDrv():


         #include "fldrvvxw.h"

         if( tffsDrv() != OK )
             {
             /* error */
             }


     ===> NOTE.  This routine must be called exactly once, AFTER call to 
                 routine tffsSetup(). 

2.10. In case if there is single mDOC in the system, skip this Section,
      and proceed with Section 2.11. In this case it is known that there is 
      only one "socket" in the system (see Section 1.2 for definition of term
      "socket").

      In case if there are multiple mDOCs in the system, you could find
      out how many "sockets" driver has actually detected during tffsDrv() call
      by executing the following code fragment:


          #include "fldrvvxw.h"

          int  totalSockets = tffsSockets ();


2.11. To find out how many "disks" (see Chapter 1 for the definition of term 
      "disk") exists on each mDOC "socket", execute the following code
      fragment:


          #include "fldrvvxw.h"

          int  disksOnSocket[4] = { 1, 0, 0, 0 };
          int  iSocket;       

          /* find out number of "disks" on each "socket" */

          for (iSocket = 0; iSocket < totalSockets; iSocket++)
              {
              disksOnSocket[iSocket] = tffsDisksOnSocket (iSocket);
              }


2.12. Excluded.

2.13. Excluded.

2.14. It is assumed that you are using dosFs-2 VxWorks file system. An old dosFs
      file system is not supported by this driver.

      Make sure that you have included all dosFs-2 file system components
      in your application. In case of Tornado-2, these components can be seen
      in the 'VxWorks' view of Workspace window, under "operating system 
      components -> IO system components -> DOSFS2 File System components".
      In case of Workbench 2.x, these components can be seen in the 'Components'
      view of the "Kernel configuration" under "operating system components ->
      IO system components -> dosFs File System Components(dosFs2)".

2.14.1. Application must call routine tffsDevCreate() to create VxWorks 'block
        device' for every "disk" of every "socket". Here is declaration of this
        routine taken from fldrvvxw.h :

            extern BLK_DEV*  tffsDevCreate (int handle, int flags);

        ===> NOTE.  mDOC parts in TSOP and BGA packages are normally
                    shipped from the factory unformatted, which causes routine
                    tffsDevCreate() to fail and return NULL. You will need to
                    format these mDOC parts as described in Chapter 4,
                    and re-attempt tffsDevCreate() call. 

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


             #include "fldrvvxw.h"

             int  handle = tffsMakeHandle (socketNo, diskNo);


        Any of the following optional flags can be OR-ed into
        argument 'flags':

            FL_VERIFY_WRITE2
            FL_VERIFY_WRITE3

        Flag FL_VERIFY_WRITE2, when OR-ed into argument 'flags', instructs 
        mDOC driver to follow every critical 'write' operation with
        respective read-back-and-verify cycle. Usually there is no noticable
        degradation in I/O performance associated with FL_VERIFY_WRITE2 flag. 

        Flag FL_VERIFY_WRITE3, when OR-ed into argument 'flags',  instructs 
        mDOC driver to follow every 'write' operation (regardless whether
        it is critical or not) with respective read-back-and-verify cycle. 
        Since this flag causes significant degradation in mDOC's I/O
        performance, it should be used only in rare cases (for example, when
        system is exposed to extreme temperatures, radiation etc.).

        Routine tffsDevCreate() returns a pointer of (BLK_DEV *) type which
        must be saved by the application for later use.

        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 create VxWorks 'block device':


            #include "fldrvvxw.h"

            int       iSocket;
            int       iDisk;
            int       handle;
            int       flags;
            BLK_DEV * tffs_blk_dev;

            iSocket = 0;
            iDisk   = 0;

            /* create TFFS handle */

            handle = tffsMakeHandle (iSocket, iDisk);

            /* specify 'flags' */

            flags = 0 /* FL_VERIFY_WRITE2 */;

            /* create VxWorks block device */
 
            tffs_blk_dev = tffsDevCreate (handle, flags);


        Here is generic example which should work in every possible case:


            #include "fldrvvxw.h"

            int  totalSockets;
            int  disksOnThisSocket;
            int  iSocket;
            int  iDisk;
            int  flags;

            /* up to 4 "sockets", up to 4 "disks" per "socket" */

            BLK_DEV * tffs_blk_dev [4][4];

            /* clear */

            for (iSocket = 0; iSocket < 4; iSocket++)
                for (iDisk = 0; iDisk < 4; iDisk++)
                    tffs_blk_dev[iSocket][iDisk] = NULL;

            /* specify 'flags' */

            flags = 0 /* FL_VERIFY_WRITE2 */;

            /* find out how many "sockets" are in the system */

            totalSockets = tffsSockets ();

            for (iSocket = 0; iSocket < totalSockets; iSocket++)
                {
                /* find out how many "disks" are on this "socket" */

                disksOnThisSocket = tffsDisksOnSocket (iSocket);

                for (iDisk = 0; iDisk < 4; iDisk++)
                    {
                    /* create block device for 'iDisk' of 'iSocket' */
 
                    tffs_blk_dev[iSocket][iDisk] = 
                        tffsDevCreate( tffsMakeHandle(iSocket, iDisk), flags );
                    }
                }


2.14.2. If you are using Workbench 2.4 skip this section and continue with Section
        2.15 instead.
        
        Application must attach disk cache to every 'block device' created in
        Section 2.14.1. This is accomplished by calling VxWorks' routine
        dcacheDevCreate(). This routine is part of VxWorks 'dcacheCbio' library.
        The first argument passed to dcacheDevCreate() must be (BLK_DEV *) 
        pointer returned by tffsDevCreate() (see Section 2.14.1).

        For description of all other arguments of dcacheDevCreate(), see 
        'dcacheCbio' library documentation.

        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 attach disk cache:


            #include <cbioLib.h>
            #include <dcacheCbio.h>
            #include <dpartCbio.h>

            CBIO_DEV_ID  dcache;

            /* 
             * Dynamically allocate 128KB disk cache, attach it to block
             * device created in Section 2.14.1, and name it "tffsCache0"
             */

            dcache = 
                dcacheDevCreate( (CBIO_DEV_ID) tffs_blk_dev, 
                                  NULL,           /* alloc. cache dynamically */ 
                                  (128 * 1024),   /* cache size : 128 KB      */
                                  "tffsCache0" ); /* name of this cache       */
            if (dcache == NULL) 
                {
                /* 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.  

                    See also description of the routine dcacheDevTune() in
                    'dcacheCbio' library entry in dosFs-2 documentation, and
                    Section 2.14.3.

2.14.3. After disk cache has been created as shown in Section 2.14.2, user should
        tune it to suit application's needs. VxWorks routine dcacheDevTune() 
        can be used for this purpose. This routine is part of VxWorks 
        'dcacheCbio' library.

        One of disk cache parameters that user might want to tune, is "sync 
        interval" (number of seconds during which "dirty" disk block are not 
        written to the media). 

        Another parameter that application should tune is "read ahead". This
        parameter is meant to improve 'read' performance of the mechanical 
        hard disks (by reducing so-called "seek time"), and doesn't make 
        sense for flash disks. We recommend to set "read ahead" parameter to 
        minimum possible value (which is '2').

2.14.4. If you do not wish to re-partition 'block device' (created in 
        Section 2.14.1), skip this Section, and continue with Section 2.14.5 
        instead.

        ===> NOTE. In case when mDOC serves as system's boot device, it is
                   generally a good idea to create at least two file system
                   partitions on it. In this case the first partition can be used
                   for storing VxWorks bootimage(s), while all the other
                   partitions will be used to store application's files. In case
                   when application creates a lot of temporary files, separate
                   file system partition could be set aside specifically for
                   storing temporary files on it.

        If you do wish to re-partition 'block device', you should do it now,
        by calling VxWorks routine usrFdiskPartCreate(). This routine is part
        of VxWorks 'usrFdiskPartLib' 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 re-partitioning 'block device':


            #include <cbioLib.h>
            #include <dcacheCbio.h>
            #include <dpartCbio.h>

            extern STATUS  usrFdiskPartCreate (CBIO_DEV_ID dev, int nPart, int sz1, int sz2, int sz3);

            STATUS  status;

            /* 'dcache' has been defined in Section 2.14.2 */

            /* 
             * Create 4 file system partitions. The size of first partition
             * is 10% from the media size, second partition 20%, third
             * partition 40%, and rest goes into forth file system partition.
             */

            status = usrFdiskPartCreate (dcache, 4, 10, 20, 40);

            if (status != OK) 
                {
                /* error */
                }


        ===> NOTE.  When deciding on size of the first file system partition, 
                    take into account most applications tend to grow in size