readme.txt

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

                    over period of time (new features are added etc.), so you 
                    may want to provide some spare room on the first file system
                    partition to provide sufficient room for future growth. 

        ===> NOTE.  While file system partitions have been created, they have not
                    been initialized yet. This will be done in Section 2.14.8.

        Skip Section 2.14.5, and proceed with Section 2.14.6.
        
2.14.5. For every 'block device', application must call routine 
        tffsHowManyParts() to find out how many file system partitions exist on
        this 'block 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
                    'block 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.14.6. Application must attach a partition manager to every 'block device'
        that has been created by routine tffsDevCreate() (see Section 2.14.1).
        This is accomplished by calling VxWorks routine dpartDevCreate(). This 
        routine is part of VxWorks 'dpartCbio' library.

        First argument passed to routine dpartDevCreate() is CBIO_DEV_ID
        handle returned by previous call to routine dcacheDevCreate() (see 
        Section 2.14.2).

        Second argument passed to routine dpartDevCreate(), specifies number
        of file system partitions that exist on this particular 'block device' 
        (see Sections 2.14.4 and 2.14.5).

        ===> NOTE.  You can also use VxWorks routine usrFdiskPartShow(), which
                    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 attach partition manager to this 'block 
        device':


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

            extern STATUS  usrFdiskPartRead (CBIO_DEV_ID dev, PART_TABLE_ENTRY *pPartTab, int nPart);

            CBIO_DEV_ID  rawdisk;
 
            /* 'dcache' has been defined in Section 2.14.2 */

            /* 
             * The 'totalPartitions' is number of file system partitions on this
             * block device (see Section 2.14.4 and 2.14.5).
             */

            rawdisk = dpartDevCreate (dcache, totalPartitions, usrFdiskPartRead);

            if (rawdisk == NULL) 
                {
                /* error */
                }


2.14.7. Once partition manager has been attached to every 'block device', 
        application can mount all file system partitions from these 'block
        devices'. This is accomplished by calling VxWorks routines 
        dpartPartGet() and dosFsDevCreate(). Routine dpartPartGet() is part 
        of VxWorks 'dpartCbio' library; routine dosFsDevCreate() is part of 
        VxWorks 'dosFsLib' 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 mount all file system partitions from this
        'block device':


            #include <dosFsLib.h>
            #include <usrLib.h>
            #include <cbioLib.h>
            #include <dcacheCbio.h>
            #include <dpartCbio.h>
                    
            /* 
             * 'rawdisk' has been defined in Section 2.14.6
             * 'totalPartitions' has been defined in Sections 2.14.4 and 2.14.5.
             */

             CBIO_DEV_ID   partition;
             char          name[32];
             int           iPart;
             STATUS        status;

             for (iPart = 0; iPart < totalPartitions; iPart++) 
                 {
                 partition = dpartPartGet (rawdisk, iPart);
                 if (partition == NULL) 
                     break;

                 /* generate names "/tffs0a", "/tffs0b" etc. */
 
                 sprintf( name, "/tffs0%c", (char)('a' + iPart) );

                 /* mount file system partition */

                 status = dosFsDevCreate( name, partition, 20, 
                                          (DOS_CHK_REPAIR | DOS_CHK_VERB_2) );
                 if (status == ERROR) 
                     {
                     /* eror */
                 }
                 }


        ===> NOTE.  Value '20' in the code fragment above specifies a limit on
                    number of files that can be simultaneously opened on each 
                    of the mounted file system partitions.

        After this code fragment above has been executed, devices with names
        "/tffs0a", "/tffs0b" etc. should appear in system's device list. To see
        system's device list, use Shell's 'devs' command.

2.14.8. If you have not re-partitioned 'block device' as described in 
        Section 2.14.4, skip this Section, and proceed with Section 2.14.9 
        instead.

        If you did re-partition 'block device' as described in Section 2.14.4,
        you have to initialize file systems on all file system partitions that
        have been mounted by calls to dosFsDevCreate() (see Section 2.14.7). 
        This is accomplished by calling VxWorks routine dosFsVolFormat(). The 
        routine dosFsVolFormat() is part of VxWorks 'dosFsFmtLib' library.

        After you have initialized any file system partition on particular 
        'block device' by calling dosFsVolFormat(), you must inform mDOC
        driver about that by calling routine tffsPartCtrl(). Here is the 
        declaration of this routine taken from fldrvvxw.h:

            extern STATUS  tffsPartCtrl (int handle, int partNo, int action);

        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
                    'block 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 <usrLib.h>
            #include <cbioLib.h>
            #include <dcacheCbio.h>
            #include <dpartCbio.h>
            #include "fldrvvxw.h"
                    
            int     iSocket;
            int     iDisk;
            int     handle;
            int     iPart;
            char    name[32];
            STATUS  status;
    
            /* 'totalPartitions' was defined in Sections 2.14.4 and 2.14.5 */

            for (iPart = 0; iPart < totalPartitions; iPart++) 
                {
                /* 
                 * Assuming file system partitions were assigned names 
                 * "/tffs0a", "/tffs0b" etc. See Section 2.14.7.
                 */
 
                sprintf( name, "/tffs0%c", (char)('a' + 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.14.9. At that point all file system partitions on all 'block device' have been
        mounted, and are accessible to VxWorks application. 

        ===> NOTE.  If file system partition has been mounted as shown in 
                    Section 2.14.7, file system consistency check will take 
                    place during the first access to that partition. 

2.15. If you are not using Workbench 2.4 skip this section.

2.15.1. Application must call routine xbdBlkDevCreate() to create VxWorks 'XBD
        device' for every 'block device' created in Section 2.14.1. This routine
        is part of VxWorks 'xbdBlkDev' library.
        The first argument passed to xbdBlkDevCreate() must be (BLK_DEV *) pointer
        returned by tffsDevCreate() (see Section 2.14.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 create 'XBD device':


          #include <xbdBlkDev.h>

          device_t  xbd;

          /* call xbd wrapper to create XBD device and name it "/tffs0" */
          xbd = xbdBlkDevCreateSync (tffs_blk_dev, "/tffs0");
          if (xbd == NULLDEV)
             {
             /* error */
             }
             
        After the XBD device is created it is automatically probed for
        a file system and partitions. If the device is already formatted, it
        is mounted. If a a file system is found, it is mounted as well.

        After the code fragment above has been executed, new devices should
        appear in system's device list. If the device has no partition table
        and FAT format, it will appear with "/tffs0:0" name. Otherwise, every
        device partition will appear as a separate device with names "/tffs0:1",
        "/tffs0:2" etc. To see system's device list, use Shell's 'devs' command.

2.15.2. If you do not wish to re-partition 'XBD device' (created in
        Section 2.15.1), skip this Section, and continue with Section 2.15.4
        instead.

        If you do wish to re-partition 'XBD device', you can do it now,
        by calling VxWorks routine xbdCreatePartition(). This routine is part
        of VxWorks 'partLib' 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 <xbdPartition.h>

            STATUS  status;
            int totalPartitions = 4;

            /* 'tffs0' has been defined in Section 2.15.1 */

            /*
             * 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.
             */

            /* try first with "/tffs0:0" (unformatted media) */
            status = xbdCreatePartition ("/tffs0:0", totalPartitions, 10, 20, 40);
            if (status != OK)
		{
		/* if failed try with "/tffs0:1" (FAT format already exists) */
		status = xbdCreatePartition ("/tffs0:1", totalPartitions, 10, 20, 40);
		if (status != OK)
		    {
                    /* error */
                    }
                }


        ===> NOTE.  While file system partitions have been created, they have not
                    been initialized yet. This will be done in Section 2.15.3.

2.15.3. If you have not re-partitioned 'XBD device' as described in
        Section 2.15.2, skip this Section, and proceed with Section 2.15.4
        instead.

        If you did re-partition 'XBD device' as described in Section 2.15.2,
        you have to initialize file systems on all file system partitions that
        have been mounted by call to xbdBlkDevCreateSync() (see Section 2.15.1).
        This is accomplished by calling VxWorks routine dosFsVolFormat(). The
        routine dosFsVolFormat() is part of VxWorks 'dosFsFmtLib' library.

        After you have initialized any file system partition on particular
        'XBD device' by calling dosFsVolFormat(), you must inform mDOC
        driver about that by calling routine tffsPartCtrl(). Here is the
        declaration of this routine taken from fldrvvxw.h:

            extern STATUS  tffsPartCtrl (int handle, int partNo, int action);