wdbtsfsdrv.c

VXWORKS源代码

/* wdbTsfsDrv.c - virtual generic file I/O driver for the WDB agent */

/* Copyright 1996-2001 Wind River Systems, Inc. */

/*
modification history
--------------------
01s,09oct01,jhw  Fixed memory leak in tsfsOpen(). SPR 67981.
01r,03mar99,dgp  update to reference project facility, make tsfsOpen() NOMANUAL
01q,28jan99,jmp  added initialization of semGiveAddr in WDB_TSFS_GENERIC_INFO
                 structure, for TSFS_BOOT facility (SPR# 24466).
01p,23nov98,cth  added explicit setting of WDB_TSFS_O_TEXT open mode (SPR 23467)
01o,31aug98,dgp  final editing for WV 2.0 FCS, corrections to tgtsvr stuff
01n,28aug98,dgp  FCS man page edit, add tgtsvr info
01m,25aug98,cth  added errno mapping for ECONNREFUSED
01l,10aug98,cth  FIORENAME now handles prepended device names, updated docs
01k,27may98,cth  modified docs, removed get snd/rcv buf ioctls
01j,05may98,dgp  clean up man pages for WV 2.0 beta release
01i,16apr98,cth  removed debug print statements
01h,16apr98,cth  mapped errnos from tsfs portable definitions to vxworks'
      		 added errno reset in open, updated docs
01g,03apr98,cjtc i960 port for WV20
01f,19mar98,cth  added ioctl support for sockets
01e,25feb98,cth  added O_APPEND, _EXCL modes, doc changes, added FIORENAME
01d,30jan98,cth  added directory creation/deletion, added man page
01c,18aug97,cth  added FIOSNDURGB ioctl command
01b,18nov96,dbt  replaced the field delete in WDB_TSFS_INFO struct for C++
                 compatibility, with field remove.
01a,28aug96,c_s  written, based on wdbVioDrv.c by ms.
*/

/*
DESCRIPTION

This library provides a virtual file I/O driver for use with the WDB
agent.  I/O is performed on this virtual I/O device exactly as it would be
on any device referencing a VxWorks file system.  File operations, such as
read() and write(), move data over a virtual I/O channel created between the
WDB agent and the Tornado target server.  The operations are then executed 
on the host file system.  Because file operations are actually performed on 
the host file system by the target server, the file system presented by this 
virtual I/O device is known as the target-server file system, or TSFS.

The driver is installed with wdbTsfsDrv(), creating a device typically
called '/tgtsvr'.  See the manual page for wdbTsfsDrv() for more information
about using this function.  The initialization is done automatically,
enabling access to TSFS, when INCLUDE_WDB_TSFS is defined.
The target server also must have TSFS enabled in order to use TSFS.  See the
.I WindView User's Guide: Data Upload
and the target server documentation.

TSFS SOCKETS
TSFS provides all of the functionality of other VxWorks file systems.
For details, see the 
.pG "I/O System and Local File Systems."
In addition to normal
files, however, TSFS also provides basic access to TCP sockets.  This
includes opening the client side of a TCP socket, reading, writing, and
closing the socket.  Basic setsockopt() commands are also supported.

To open a TCP socket using TSFS, use a filename of the form:
.tS
    TCP:<server_name> | <server_ip>:<port_number>
.tE

To open and connect a TCP socket to a server socket located on a server 
named 'mongoose', listening on port 2010, use the following:
.CS
    fd = open ("/tgtsvr/TCP:mongoose:2010", 0, 0)
.CE
The open flags and permission arguments to the open call are ignored when
opening a socket through TSFS.  If the server 'mongoose' has an IP
number of '144.12.44.12', you can use the following equivalent form of the 
command:
.CS
    fd = open ("/tgtsvr/TCP:144.12.44.12:2010", 0, 0)
.CE

DIRECTORIES
All directory functions, such as mkdir(), rmdir(), opendir(), readdir(),
closedir(), and rewinddir() are supported by TSFS, regardless of
whether the target server providing TSFS is being run on a UNIX or 
Windows host.

While it is possible to open and close directories using open() and close(),
it is not possible to read from a directory using read(). Instead, readdir() 
must be used.  It is also not possible to write to an open directory, and 
opening a directory for anything other than read-only results in an 
error, with 'errno' set to 'EISDIR'.  Calling read() on a directory 
returns 'ERROR' with 'errno' set to 'EISDIR'.

OPEN FLAGS
When the target server that is providing the TSFS is running on a Windows
host, the default file-translation mode is binary translation.  If text
translation is required, then WDB_TSFS_O_TEXT can be included in the mode
argument to open().  For example:
.CS
    fd = open ("/tgtsvr/foo", O_CREAT | O_RDWR | WDB_TSFS_O_TEXT, 0777)
.CE

If the target server providing TSFS services is running on a UNIX host, 
WDB_TSFS_O_TEXT is ignored.

TGTSVR
For general information on the target server, see the reference
entry for 'tgtsvr'. In order to use this library, the target server must
support and be configured with the following options:

.iP "-R <root>" 20
Specify the root of the host's file system that is visible to target processes
using TSFS.  This flag is required to use TSFS.  Files under this root are by
default read only.  To allow read/write access, specify -RW.
.iP "-RW"
Allow read and write access to host files by target processes using
TSFS.  When this option is specified, access to the
target server is restricted as if `-L' were also specified.

IOCTL SUPPORT
TSFS supports the following ioctl() functions for controlling files
and sockets. Details about each function can be found in the documentation 
listed below.

.iP 'FIOSEEK'
.iP 'FIOWHERE'
.iP 'FIOMKDIR'
Create a directory.  The path, in this case '/tgtsvr/tmp', must be an
absolute path prefixed with the device name. To create the directory '/tmp' 
on the root of the TSFS file system use the following:
.CS
    status = ioctl (fd, FIOMKDIR, "/tgtsvr/tmp")
.CE
.iP 'FIORMDIR'
Remove a directory.  The path, in this case '/tgtsvr/foo', must be an 
absolute path prefixed with the device name.  To remove the directory '/foo' 
from the root of the TSFS file system, use the following:
.CS
    status = ioctl (fd, FIORMDIR, "/tgtsvr/foo")
.CE
.iP 'FIORENAME'
Rename the file or directory represented by 'fd' to the name in the string
pointed to by 'arg'.  The path indicated by 'arg' may be prefixed with the
device name or not.  Using this ioctl() function with the path '/foo/goo'
produces the same outcome as the path '/tgtsvr/foo/goo'.  The path is not
modified to account for the current working directory, and therefore must
be an absolute path.
.CS
    char *arg = "/tgtsvr/foo/goo"; 
    status = ioctl (fd, FIORENAME, arg);
.CE
.iP 'FIOREADDIR'
.iP 'FIONREAD'
Return the number of bytes ready to read on a TSFS socket file
descriptor.
.iP 'FIOFSTATGET'
.iP 'FIOGETFL'
.LP
The following ioctl() functions can be used only on socket file
descriptors.  Using these functions with ioctl() provides similar behavior
to the setsockopt() and getsockopt() functions usually used with socket
descriptors.  Each command's name is derived from a
getsockopt()/setsockopt() command and works in exactly the same way as the
respective getsockopt()/setsockopt() command.  The functions setsockopt()
and getsockopt() can not be used with TSFS socket file descriptors.

For example, to enable recording of debugging information on the TSFS socket
file descriptor, call:
.CS
    int arg = 1;
    status = ioctl (fd, SO_SETDEBUG, arg);
.CE
To determine whether recording of debugging information for the TSFS-socket
file descritptor is enabled or disabled, call:
.CS
    int arg;
    status = ioctl (fd, SO_GETDEBUG, & arg);
.CE
After the call to ioctl(), 'arg' contains the state of the debugging attribute.

The ioctl() functions supported for TSFS sockets are:

.iP SO_SETDEBUG
Equivalent to setsockopt() with the SO_DEBUG command.
.iP SO_GETDEBUG
Equivalent to getsockopt() with the SO_DEBUG command.
.iP SO_SETSNDBUF
This command changes the size of the send buffer of the host socket.  The 
configuration of the WDB channel between the host and target also affects the
number of bytes that can be written to the TSFS file descriptor in a single
attempt.
.iP SO_SETRCVBUF
This command changes the size of the receive buffer of the host socket.  The 
configuration of the WDB channel between the host and target also affects the
number of bytes that can be read from the TSFS file descriptor in a single
attempt.
.iP SO_SETDONTROUTE
Equivalent to setsockopt() with the SO_DONTROUTE command.
.iP SO_GETDONTROUTE
Equivalent to getsockopt() with the SO_DONTROUTE command.
.iP SO_SETOOBINLINE
Equivalent to setsockopt() with the SO_OOBINLINE command.
.iP SO_GETOOBINLINE
Equivalent to getsockopt() with the SO_OOBINLINE command.
.iP SO_SNDURGB
The SO_SNDURGB command sends one out-of-band byte (pointed to by 'arg') 
through the socket.

ERROR CODES
The routines in this library return the VxWorks error codes that 
most closely match the errnos generated by the corresponding host function.
If an error is encountered that is due to a WDB failure, a WDB error
is returned instead of the standard VxWorks 'errno'.  If an 'errno' generated
on the host has no reasonable VxWorks counterpart, the host 'errno' is
passed to the target calling routine unchanged.

SEE ALSO:
.I "Tornado User's Guide,"
.I "VxWorks Programmer's Guide: I/O System, Local File Systems"

INTERNAL
opendir(), closedir(), readdir() and rewinddir() are supported when
the tgtsvr is running on a Unix host.  All of these, with the exception of
rewinddir() are supported on Win32.  Win32 provides directory listings with
an iterator model (findfirst(), findnext(), findclose()).  There is no
way to back up this iterator, like rewinddir does.

There are times when the host must return an error code that is not 
defined on the target.  These error codes are defined in wdb.h.  Each
time the errno is set in this function, it is first mapped from the
portable error codes defined in wdb.h to a vxWorks' error code.  Common,
usually Posix, errnos are passed through this mapping unchanged.  If
an errno generated on the host is not understood by the mapping routines,
then it is passed through unchanged.  This may give the user useful 
information about what has happened when vxWorks doesn't have an 
equivalent errno.  Many of the errnos mapped are the Win32 socket and
networking errnos, which have vxWorks counterparts, but are very different
from unix and vxWorks definitions.

The ioctl command FIORENAME does not work ideally.  It should modify the path
it is handed to account for the current working directory.  Doing this however
requires that this wdb-virtual-io driver call into ioLib, something that has
been avoided so far.  This creates a problem with rename() that is not seen
in dosFsLib.  The rename function, in ioLib, does not patch up the path name
with the current working directory, letting the ioctl in dosFsLib do it
instead.  When the current working directory is '/tgtsvr/foo/goo', and it 
contains the file 'file1', and the tsfsRoot is '/folk/blimpy', calling 
'rename ("file1", "file-renamed") results in /folk/blimpy/foo/goo/file1
being renamed to /folk/blimpy/file-renamed.  Notice the /foo/goo working
directory was ignored.  By the way, passFsLib has the same problem.
*/

#include "vxWorks.h"
#include "ioLib.h"
#include "iosLib.h"
#include "tyLib.h"
#include "stdlib.h"
#include "stdio.h"
#include "intLib.h"
#include "string.h"
#include "sys/stat.h"
#include "dirent.h"

#include "wdb/wdb.h"
#include "wdb/wdbLibP.h"
#include "wdb/wdbEvtLib.h"
#include "wdb/wdbVioLib.h"
#include "wdb/wdbLibP.h"



#if (defined (CPU_FAMILY) && (CPU_FAMILY==I960) && (defined __GNUC__))
#pragma align 1                 /* tell gcc960 not to optimize alignments */
#endif  /* CPU_FAMILY==I960 */

typedef struct
    {
    DEV_HDR		devHdr;			/* device header */
    } TSFS_DEV;

typedef struct
    {
    int			channel;		/* tsfs channel number */
    int			openmode;		/* used for FIOGETFL */
    SEMAPHORE		tsfsSem;		/* mutex sem for access */
    SEMAPHORE		waitSem;		/* used to wait for tgtsvr */
    WDB_EVT_NODE	evtNode;		/* agent event node */
    WDB_TSFS_INFO	info;			/* event contents */
    struct
	{
	TGT_INT_T	value;			/* value to return to caller */
	TGT_INT_T	errNo;			/* errno to return to caller */
	TGT_INT_T	extra1;			/* for ioctl extra results */
	TGT_INT_T	extra2;			/* for ioctl extra results */
	}		result;
    } TSFS_CHANNEL_DESC;

#if (defined (CPU_FAMILY) && (CPU_FAMILY==I960) && (defined __GNUC__))
#pragma align 0                 /* turn off alignment requirement */
#endif  /* CPU_FAMILY==I960 */

static int		tsfsDrvNum;		/* drvnum for this driver */
static int		tsfsChanNum;		/* next channel number */
static TSFS_DEV		tsfsDev;		/* virtual I/O device */



/* globals */

int mutexOptionsTsfsDrv   = SEM_Q_PRIORITY | SEM_DELETE_SAFE;
int binaryOptionsTsfsDrv  = SEM_Q_FIFO;
int wdbTsfsDefaultDirPerm = DEFAULT_DIR_PERM;	/* created directory perms */


/* forward declarations */

static int 		tsfsCreate   (TSFS_DEV *pDev, char *name, int mode);
static int     		tsfsOpen     (TSFS_DEV *pDev, char * name, int mode, 
				      int perm);
static int     		tsfsDelete   (TSFS_DEV *pDev, char * name);
static STATUS  		tsfsClose    (TSFS_CHANNEL_DESC *pChannelDesc);
static int 		tsfsRead     (TSFS_CHANNEL_DESC *pNetFd, char *buf,
				      int maxBytes);
static int 		tsfsWrite    (TSFS_CHANNEL_DESC *pNetFd, char *buf,
				      int maxBytes);
static STATUS		tsfsIoctl    (TSFS_CHANNEL_DESC *pChannelDesc,
				      int request, int arg);
static int		tsfsErrnoMap (int hostErrno);
static void		tsfsEventGet (void * pChannelDesc,
				      WDB_EVT_DATA *pEvtData);
static void		tsfsEventDeq (void * pChannelDesc);


/*******************************************************************************
*
* wdbTsfsDrv - initialize the TSFS device driver for a WDB agent
*
* This routine initializes the VxWorks virtual I/O "2" driver and creates
* a TSFS device of the specified name.
*
* This routine should be called exactly once, before any reads, writes, or
* opens.  Normally, it is called by usrRoot() in usrConfig.c,
* and the device name created is '/tgtsvr'.
*
* After this routine has been called, individual virtual I/O channels
* can be opened by appending the host file name to the virtual I/O
* device name.  For example, to get a file descriptor for the host
* file '/etc/passwd', call open() as follows:
* .CS
*     fd = open ("/tgtsvr/etc/passwd", O_RDWR, 0)
* .CE
*
* RETURNS: OK, or ERROR if the driver can not be installed.
*/

STATUS wdbTsfsDrv
    (
    char *		name		/* root name in i/o system */
    )
    {
    /* check if driver already installed */

    if (tsfsDrvNum > 0)
	return (OK);

    tsfsDrvNum = iosDrvInstall (tsfsCreate, tsfsDelete, tsfsOpen,
				tsfsClose, tsfsRead, tsfsWrite, 
				tsfsIoctl);

    if (tsfsDrvNum <= 0)
        return (ERROR);

    /* Add the device to the I/O systems device list */

    return (iosDevAdd (&tsfsDev.devHdr, name, tsfsDrvNum));
    }

/*******************************************************************************
*
* tsfsCreate - open a virtual I/O channel
*
* RETURNS: tsfsDev handle
*/

static int tsfsCreate
    (
    TSFS_DEV *		pDev,		/* I/O system device entry */
    char *		name,		/* name of file to open */
    int			mode		/* VxWorks open mode */
    )

    {
    return tsfsOpen (pDev, name, mode | O_CREAT | O_TRUNC, 0666);
    }

/*******************************************************************************
*
* tsfsOpen - open a virtual I/O channel
*
* This routine opens a virtual I/O channel and returns a device handle
* for the channel.  It does this by creating a WDB event containing the
* information necessary for the tgtsvr to perform the requested open
* operation.  This routine waits, after the event is sent to the tgtsvr,
* until the tgtsvr stores the results of the request back to target memory.
* These results are handed back to the caller.
*
* This routine is also used to create files and directories.  After the file
* or directory is created, it is opened and a valid device handle is handed
* back to the caller.
*
* Note, when creating a directory, the mode argument (O_RDWR, O_RDONLY...)
* is not necessary, except to indicate O_CREAT.  It is illegal in most file
* systems, including all of VxWorks' file systems, to open a directory in
* any mode other than O_RDONLY.  Because the directory is created, as well
* as opened in this routine, it is unreasonable to expect that the mode be
* O_RDONLY in order to succeed.  After all, the user wants to create the
* directory, not open it.  This is confused by our implementation of mkdir,