rt11fslib.c

大名鼎鼎的嵌入式操作系统vxworks的完整的源代码

/* rt11FsLib.c - RT-11 media-compatible file system library */

/* Copyright 1984-1995 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
06n,14mar99,jdi  doc: removed refs to config.h and/or configAll.h (SPR 25663).
06m,29mar95,kdl  removed obsolete date fields from stat structure.
06l,14sep93,kdl  fixed ignoring of driver error during rt11FsWrite (SPR #2516).
06k,03sep93,kdl  fixed use of standard skew & interleave (rtFmt) (SPR #959).
06j,25aug93,jmm  rt11FsFileStatGet() now sets atime, mtime, and ctime fields
06i,24jun93,kdl  fixed loss of fd if driver status check returns error during 
		 open() (SPR #2278).
06h,02feb93,jdi  documentation tweaks.
06g,02feb93,jdi  documentation cleanup for 5.1; added 3rd param to ioctl() examples.
06f,02oct92,srh  added ioctl(FIOGETFL) to return file's open mode
06e,07sep92,smb  added blksize and blocks to the stat structure initialisation.
06d,22jul92,kdl  changed from 4.0.2-style semaphores to mutexes.
06c,18jul92,smb  Changed errno.h to errnoLib.h.
06b,26may92,rrr  the tree shuffle
06a,13dec91,gae  ANSI cleanup.
05z,19nov91,rrr  shut up some ansi warnings.
05y,04oct91,rrr  passed through the ansification filter
                  -changed functions to ansi style
		  -changed includes to have absolute path from h/
		  -changed READ, WRITE and UPDATE to O_RDONLY O_WRONLY and ...
		  -changed VOID to void
		  -changed copyright notice
05x,26jun91,wmd  modified rt11FsFindEntry() to use field comparisons instead of bcmp().
05w,05apr91,jdi	 documentation -- removed header parens and x-ref numbers;
		 doc review by kdl.
05v,22feb91,jaa	 documentation cleanup.
05u,08oct90,kdl  added forward declaration for rt11FsOpen().
05t,08oct90,kdl  made rt11FsOpen, rt11FsWrite, etc. routines LOCAL (again).
05s,10aug90,kdl  added forward declarations for functions returning void.
05r,09aug90,kdl  changed name from rt11Lib to rt11FsLib.
05q,19jul90,dnw  mangen fix
05p,15jul90,dnw  moved rt11Ls back to usrLib as oldLs since it is applicable
		   to the netDrv as well
05o,12jul90,kdl  added BLK_DEV statusChk routine hook.
05n,26jun90,jcf  changed semTake () calling sequeuece for 5.0.
05m,07may90,kdl  made rt11Read read all requested bytes, added bd_readyChanged
		 and bd_mode in BLK_DEV, added POSIX-style directory listing,
		 moved old "ls" routine from usrLib and renamed it "rt11Ls",
		 made rt11Create and rt11FindEntry ignore leading slashes
		 in filename.
            jcc	 rt11Squeeze now does multi-sector reads and writes.
05l,23mar90,kdl	 lint, changed BLK_DEV field names.
05k,22mar90,kdl	 made rt11Read, rt11Write, etc. global again (temporary).
05j,16mar90,kdl	 added support for multi-filesystem device drivers (BLK_DEV),
		 added direct multi-block transfer to/from user's buffer.
05i,09oct89,dab  fixed stripping of O_CREAT and O_TRUNC from file mode in
		   rt11Open().
05h,04aug89,dab  fixed bug introduced in 05g that didn't free extra fd.
05g,21jun89,dab  made rt11Open() check for O_CREAT and O_TRUNC modes.
05f,07jul88,jcf  fixed mallocs to match new declaration.
05e,05jun88,dnw  changed from rtLib to rt11Lib.
05d,30may88,dnw  changed to v4 names.
05c,04may88,jcf  changed semaphores and sem calls for new semLib.
05b,09nov87,ecs  removed intemperate printErr from rtCreate.
05a,03nov87,ecs  documentation.
04z,20oct87,gae  made rtRename() cancel device portion of name, if present.
		 made rtDirEntry() return name for DES_TENTATIVE.
		 fixed bug in create() by flushing directory;
		 made create fail if create already active on device.
		 made rtSqueeze local.
04y,14sep87,dpg  moved squeeze to usrLib.c. changed FIOSQUEEZE call in rtIoctl
		 to use a fd rather than some aesoteric device pointer (i.e.
		 keep it looking the same).
04x,10sep87,dpg  deleted rtMaxRoom & maxRoom - we don't really need them now
		 renamed rtPack & pack to rtSqueeze & squeeze
04w,26aug87,dpg  added rtMaxRoom to find largest piece of free space on
		 a disk device, and a FIOMAXROOM to ioctl at it; together
		 with maxRoom - a user callable routine
04v,26jun87,dpg  added rtPack to compress free space on an RT-11 device into
		 one big block so that hard disks don't get too fragmented.
		 also added ioctl entry to provide uniform interface to
		 rtPack & pack (user callable routine)
04u,05may87,gae  fixed "the other" fatal bug introduced in 04t in rtRead().
		 changed constant N_RETRIES to rtMaxRetries to allow variation.
04u,28apr87,gae  fixed fatal bug introduced in 04t in rtVolMount().
04t,26mar87,gae  Made rtVolMount() fail on bad (unlikely) directory.
		 Got rid of rtVolFlush(), then renamed rtVFlush() to
		   rtVolFlush().
04s,07mar87,gae  Made the following LOCAL: rtGetEntry(), rtAbsSector(),
		   rtDirEntry(), rtRename(), rtFlush(), rtWhere(), rtSeek(),
		   rtVolFlush(), and rtVolInit().  Fixed documentation.
		 Made rtDevInit() return ERROR if out of memory.
04r,14feb87,dnw  Changed to accept null filename as special name for "raw disk"
		   instead of "-", now that ioLib protects against accidental
		   null filenames.
04q,03feb87,llk  Modified directory segments to handle any number of file
		   entries.  Directories are 1 segment long, with at least
		   2 blocks per segment.  2 block segments are still RT-11
		   compatible.  rtDevInit has a new parameter, the maximum
		   number of file entries that will go on the device.
		   See documentation below under RT-11 COMPATIBILITY.
		 Added FIODISKCHANGE to ioctl function codes.  Used for
		   manually issuing a ready change.
		 Fixed rtDirEntry so that it checks if the entry number passed
		   to it is less than the maximum possible entry number.
04p,14jan87,llk  changed to handle file size up to RT_MAX_BLOCKS_PER_FILE.
		 Changed rtVolInit to initialize disk with as many maximum
		 sized files as needed to cover all the disk space.
		 Changed rtCoalesce to coalesce files together iff the new
		 empty file would have less than RT_MAX_BLOCKS_PER_FILE blocks.
...deleted pre 87 history - see RCS
*/

/*
This library provides services for file-oriented device drivers which use
the RT-11 file standard.  This module takes care of all the necessary 
buffering, directory maintenance, and RT-11-specific details.

USING THIS LIBRARY
The various routines provided by the VxWorks RT-11 file system (rt11Fs) may
be separated into three broad groups:  general initialization,
device initialization, and file system operation.

The rt11FsInit() routine is the principal initialization function;
it need only be called once, regardless of how many rt11Fs devices
will be used.

Other rt11Fs routines are used for device initialization.  For
each rt11Fs device, either rt11FsDevInit() or rt11FsMkfs() must be called
to install the device and define its configuration.

Several functions are provided to inform the file system of
changes in the system environment.  The rt11FsDateSet() routine is used
to set the date.  The rt11FsModeChange() routine is used to
modify the readability or writability of a particular device.  The
rt11FsReadyChange() routine is used to inform the file system that a
disk may have been swapped, and that the next disk operation should first
remount the disk.

INITIALIZING RT11FSLIB
Before any other routines in rt11FsLib can be used, rt11FsInit() must 
be called to initialize this library.  This call specifies 
the maximum number of rt11Fs files that can be open simultaneously 
and allocates memory for that many rt11Fs file descriptors.
Attempts to open more files than the specified maximum will result
in errors from open() or creat().

This initialization is enabled when the configuration macro
INCLUDE_RT11FS is defined.

DEFINING AN RT-11 DEVICE
To use this library for a particular device, the device structure must
contain, as the very first item, a BLK_DEV structure.  This must be
initialized before calling rt11FsDevInit().  In the BLK_DEV structure, the
driver includes the addresses of five routines which it must supply:  one
that reads one or more sectors, one that writes one or more sectors, one
that performs I/O control on the device (using ioctl()), one that checks the
status of the device, and one that resets the device.  This structure also
specifies various physical aspects of the device (e.g., number of sectors,
sectors per track, whether the media is removable).  For more information about
defining block devices, see the
.I "VxWorks Programmer's Guide: I/O System."

The device is associated with the rt11Fs file system by the
rt11FsDevInit() call.  The arguments to rt11FsDevInit() include the name
to be used for the rt11Fs volume, a pointer to the BLK_DEV structure,
whether the device uses RT-11 standard skew and interleave, and the
maximum number of files that can be contained in the device directory.

Thereafter, when the file system receives a request from the I/O system, it
simply calls the provided routines in the device driver to fulfill the
request.

RTFMT
The RT-11 standard defines a peculiar software interleave and
track-to-track skew as part of the format.  The <rtFmt> parameter passed
to rt11FsDevInit() should be TRUE if this formatting is desired.  This
should be the case if strict RT-11 compatibility is desired, or if files
must be transferred between the development and target machines using the
VxWorks-supplied RT-11 tools.  Software interleave and skew will
automatically be dealt with by rt11FsLib.

When <rtFmt> has been passed as TRUE and the maximum number of files is
specified RT_FILES_FOR_2_BLOCK_SEG, the driver does not need to do
anything else to maintain RT-11 compatibility (except to add the track 
offset as described above).

Note that if the number of files specified is different than
RT_FILES_FOR_2_BLOCK_SEG under either a VxWorks system or an RT-11 system,
compatibility is lost because VxWorks allocates a contiguous directory,
whereas RT-11 systems create chained directories.

MULTIPLE LOGICAL DEVICES AND RT-11 COMPATIBILITY
The sector number passed to the sector read and write routines is an
absolute number, starting from sector 0 at the beginning of the device.
If desired, the driver may add an offset from the beginning of the
physical device before the start of the logical device.  This would
normally be done by keeping an offset parameter in the device-specific
structure of the driver, and adding the proper number of sectors to the
sector number passed to the read and write routines.

The RT-11 standard defines the disk to start on track 1.  Track 0 is set
aside for boot information.  Therefore, in order to retain true
compatibility with RT-11 systems, a one-track offset (i.e., the number of
sectors in one track) needs to be added to the sector numbers passed to
the sector read and write routines, and the device size needs to be
declared as one track smaller than it actually is.  This must be done by
the driver using rt11FsLib; the library does not add such an offset
automatically.

In the VxWorks RT-11 implementation, the directory is a fixed size, able
to contain at least as many files as specified in the call to
rt11FsDevInit().  If the maximum number of files is specified to be
RT_FILES_FOR_2_BLOCK_SEG, strict RT-11 compatibility is maintained,
because this is the initial allocation in the RT-11 standard.

RT-11 FILE NAMES
File names in the RT-11 file system use six characters, followed
by a period (.), followed by an optional three-character extension.

DIRECTORY ENTRIES
An ioctl() call with the FIODIRENTRY function returns information about a
particular directory entry.  A pointer to a REQ_DIR_ENTRY structure is
passed as the parameter.  The field `entryNum' in the REQ_DIR_ENTRY
structure must be set to the desired entry number.  The name of the file,
its size (in bytes), and its creation date are returned in the structure.
If the specified entry is empty (i.e., if it represents an unallocated
section of the disk), the name will be an empty string, the size will be
the size of the available disk section, and the date will be meaningless.
Typically, the entries are accessed sequentially, starting with `entryNum' = 0,
until the terminating entry is reached, indicated by a return code of ERROR.

DIRECTORIES IN MEMORY
A copy of the directory for each volume is kept in memory (in the RT_VOL_DESC
structure).  This speeds up directory accesses, but requires that rt11FsLib
be notified when disks are changed (i.e., floppies are swapped).  If the
driver can find this out (by interrogating controller status or by
receiving an interrupt), the driver simply calls rt11FsReadyChange() when a
disk is inserted or removed.  The library rt11FsLib will automatically try
to remount the device next time it needs it.

If the driver does not have access to the information that disk volumes
have been changed, the <changeNoWarn> parameter should be set to TRUE
when the device is defined using rt11FsDevInit().  This will cause the
disk to be automatically remounted before each open(), creat(), delete(),
and directory listing.

The routine rt11FsReadyChange() can also be called by user tasks, by
issuing an ioctl() call with FIODISKCHANGE as the function code.

ACCESSING THE RAW DISK
As a special case in open() and creat() calls, rt11FsLib recognizes a NULL
file name to indicate access to the entire "raw" disk, as opposed to a
file on the disk.  Access in raw mode is useful for a disk that has no
file system.  For example, to initialize a new file system on the disk,
use an ioctl() call with FIODISKINIT.  To read the directory of a disk for
which no file names are known, open the raw disk and use an ioctl() call
with the function FIODIRENTRY.

HINTS
The RT-11 file system is much simpler than the more common UNIX or MS-DOS
file systems.  The advantage of RT-11 is its speed; file access is made in
at most one seek because all files are contiguous.  Some of the most common
errors for users with a UNIX background are:
.iP "" 4
Only a single create at a time may be active per device.
.iP
File size is set by the first create and close sequence;
use lseek() to ensure a specific file size;
there is no append function to expand a file.
.iP
Files are strictly block oriented; unused portions
of a block are filled with NULLs -- there is no
end-of-file marker other than the last block.
.LP

IOCTL FUNCTIONS
The rt11Fs file system supports the following ioctl() functions.
The functions listed are defined in the header ioLib.h.  Unless stated
otherwise, the file descriptor used for these functions can be any file
descriptor open to a file or to the volume itself.

.iP "FIODISKFORMAT" 16 3
Formats the entire disk with appropriate hardware track and sector marks.
No file system is initialized on the disk by this request.
Note that this is a driver-provided function:
.CS
    fd = open ("DEV1:", O_WRONLY);
    status = ioctl (fd, FIODISKFORMAT, 0);
.CE
.iP "FIODISKINIT"
Initializes an rt11Fs file system on the disk volume.
This routine does not format the disk; formatting must be done by the driver.
The file descriptor should be obtained by opening the entire volume in raw mode:
.CS
    fd = open ("DEV1:", O_WRONLY);
    status = ioctl (fd, FIODISKINIT, 0);
.CE
.iP "FIODISKCHANGE"
Announces a media change.  It performs the same function as rt11FsReadyChange().
This function may be called from interrupt level:
.CS
    status = ioctl (fd, FIODISKCHANGE, 0);
.CE
.iP "FIOGETNAME"
Gets the file name of the file descriptor and copies it to the buffer <nameBuf>:
.CS
    status = ioctl (fd, FIOGETNAME, &nameBuf);
.CE
.iP "FIORENAME"
Renames the file to the string <newname>:
.CS
    status = ioctl (fd, FIORENAME, "newname");
.CE
.iP "FIONREAD"
Copies to <unreadCount> the number of unread bytes in the file:
.CS
    status = ioctl (fd, FIONREAD, &unreadCount);
.CE
.iP "FIOFLUSH"
Flushes the file output buffer.  It guarantees that any output that has been
requested is actually written to the device.
.CS
    status = ioctl (fd, FIOFLUSH, 0);
.CE
.iP "FIOSEEK"
Sets the current byte offset in the file to the position specified by
<newOffset>:
.CS
    status = ioctl (fd, FIOSEEK, newOffset);
.CE
.iP "FIOWHERE"
Returns the current byte position in the file.  This is the byte offset of
the next byte to be read or written.  It takes no additional argument:
.CS
    position = ioctl (fd, FIOWHERE, 0);
.CE
.iP "FIOSQUEEZE"
Coalesces fragmented free space on an rt11Fs volume:
.CS
    status = ioctl (fd, FIOSQUEEZE, 0);
.CE
.iP "FIODIRENTRY"
Copies information about the specified directory entries to a
\%REQ_DIR_ENTRY structure that is defined in ioLib.h.  The argument <req>
is a pointer to a \%REQ_DIR_ENTRY structure.  On entry, the structure
contains the number of the directory entry for which information is
requested.  On return, the structure contains the information on the
requested entry.  For example, after the following:
.CS
    REQ_DIR_ENTRY req;
    req.entryNum = 0;
    status = ioctl (fd, FIODIRENTRY, &req);
.CE
the request structure contains the name, size, and creation date of the
file in the first entry (0) of the directory.
.iP "FIOREADDIR"
Reads the next directory entry.  The argument <dirStruct> is a DIR
directory descriptor.  Normally, readdir() is used to read a
directory, rather than using the FIOREADDIR function directly.  See dirLib.
.CS
    DIR dirStruct;
    fd = open ("directory", O_RDONLY);
    status = ioctl (fd, FIOREADDIR, &dirStruct);
.CE
.iP "FIOFSTATGET"
Gets file status information (directory entry data).  The argument
<statStruct> is a pointer to a stat structure that is filled with data
describing the specified file.  Normally, the stat() or fstat() routine
is used to obtain file information, rather than using the FIOFSTATGET
function directly.  See dirLib.
.CS
    struct stat statStruct;
    fd = open ("file", O_RDONLY);
    status = ioctl (fd, FIOFSTATGET, &statStruct);
.CE
.LP
Any other ioctl() function codes are passed to the block device driver
for handling.

INCLUDE FILES: rt11FsLib.h

SEE ALSO: ioLib, iosLib, ramDrv,
.pG "I/O System, Local File Systems"
*/

/* LINTLIBRARY */

#include "vxWorks.h"
#include "ctype.h"
#include "ioLib.h"
#include "semLib.h"
#include "rt11FsLib.h"
#include "blkIo.h"
#include "stdlib.h"
#include "string.h"
#include "dirent.h"
#include "errnoLib.h"
#include "time.h"
#include "sys/stat.h"

#define RT_NAME_LEN	11

#ifndef	WAIT_FOREVER
#define	WAIT_FOREVER    NULL
#endif


/* GLOBALS */

int	rt11FsDrvNum = ERROR;	/* I/O system driver number for RT-11 */

int	rt11FsVolMutexOptions = (SEM_Q_PRIORITY | SEM_DELETE_SAFE);
					/* default mutex options */


/* LOCALS */

LOCAL char rad50 [] = " abcdefghijklmnopqrstuvwxyz$.\3770123456789";