winadmin, winadminreset -- manage Win4Lin resource tokens

Syntax

winadmin class list [token]

winadmin class printdef token

winadmin class add token:definition_file:full_name

winadmin class delete token

winadmin class update token:definition_file:full_name

winadminreset

Description

The winadmin command manages Win4Lin tokens. A token is a name for a device definition, which provides access to a hardware device or another resource that is not automatically available to DOS and Windows sessions.

Win4Lin supplies several predefined tokens for commonly used resources, such as COM ports and DOS partitions. The system administrator can create tokens for additional resources that may be made available to all users.

If somehow the predefined tokens get set incorrectly and you cannot set them correctly, you can use the winadminreset command to restore the tokens. This moves aside all of the tokens, even new ones you might have created and restores the predefined tokens to the factory defaults. It prints out where it moved the current tokens aside so that you may reinstall any of those tokens.

Any user can use the list and printdef options to list the tokens in a class or display a token's definition. Only the system administrator, logged in as root, can add, delete, update or reset tokens.

The printdef option displays a token's definition in the same format required in the definition_file required by the add and update options, so you can use the output of printdef as a starting point for new token definitions.

Win4Lin uses the following classes of tokens:

Within each class, there can be multiple tokens, each of which provides access to a specific resource.

Users associate resources defined by tokens with their DOS and Windows sessions in the following ways: by using the Win4Lin Setup dialog box on the X Desktop; by using Linux command-line options with the dos or win command; or by using the winconfig command to add the token to their DOS or Windows session configurations.


NOTE: On Linux, Win4Lin only supports direct attaching IO ports. The only VPI/PPI attachments that are supported are those that are already defined in the default set of tokens.

Creating Tokens

To create a token for a resource, you specify the characteristics of the resource in a definition file and then enter:

winadmin class add token:definition_file:full_name

where

Definition Files

A definition file is a text file that specifies the characteristics of a particular resource using lines in the following format:

characteristic=value

Different token classes require different lines in their definition files. All definition files, however, contain lines that define one or more of the following characteristics:

attachtype
Value may be direct, drive, vpippi, or spooler.

This line is required in all definition files and must be the first entry.

irq
A single decimal number or series of comma-separated numbers that denote which interrupt levels are used. Values can only be 2 through 7, 9, 10, 12, or 15. (See the Win4Lin User's Guide for more information on IRQ numbers.)

The irq line is used only when attachtype is direct or vpippi, and it is optional.

Notes:
Direct attach IRQ is not currently available on Linux systems.
For vpippi type attach this setting is for documentation purposes only, to indicate the virtual IRQ.

ioports
Has the following recursive definition:

X[-Y][,io_port_range]

where the form X specifies the I/O port address (in hex), and the form X-Y specifies an I/O port address range, from low X (in hex) to high Y (in hex), that the device uses. As the syntax shows, single or multiple ports or ranges may be given. Values are typically in the range of 0 to 7ff (hex).

The ioports line is used only when attachtype is direct or vpippi, and it is optional.

Note:
For vpippi type attach this setting is for documentation purposes only, to indicate the virtual I/O ports.

memmappedio
Has this recursive definition:

X-Y[,memory_mapped_io_range]

where X and Y are two hex numbers, separated by a hyphen, denoting the range of the memory-mapped I/O. The first number is the lowest address and the second is the highest address. Each range must start on a 4K boundary and be a multiple of 4K. As the syntax shows, multiple ranges may be specified. Values are typically c0000 to effff (hex).

The memmappedio line is used only when attachtype is direct, and it is optional.


NOTE: When you add or remove a definition that uses memmappedio or change memmappedio in an existing definition, you must make new DOS images. See ``Making new DOS images'' in Chapter 5 for more information.

Note:
Direct attach memory-mapped I/O is not currently available on Linux systems.

dmachannel
Is a single decimal number or a series of comma-separated decimal numbers that denote which DMA channels are used. (Note that devices that use certain DMA modes may not work.) Values may be 0, 1, 2, 3, 4, 5, 6, or 7.

The dmachannel line is used only when attachtype is direct, and it is optional.

Note:
Direct attach DMA is not currently available on Linux systems.

failureaction
Can be set to abort, warn, or ignore. When set to abort, any DOS or Windows session that tries to attach this device (using +atoken or using the Win4Lin Setup window) fails to start up if this device is not available (that is, if it is in use by another process). When this option is set to warn, only a warning is issued and the session continues to start up. If set to ignore, all failures are silently ignored. While setting up and testing a token, set this field to abort. Once the token works correctly, set it to warn unless you have special requirements that are best served with the abort or ignore values.

useraccess
Can be set to root or nothing. When set to root, only the root user can attach this device. When this entry is removed or set to nothing, all users can attach the device. While you are setting up and testing your token, set this entry to root. Once you have a token configuration that works correctly, remove this entry or set it to nothing so that the device becomes available to all users.

vpidevice
Set to the full path of the Linux VPI device. Used and required only when attachtype is vpippi.

If the token is to be used as COM1 this setting must be /dev/vcom1. If the token is to be used as COM2 this setting must be /dev/vcom2.

Note:
The only Linux VPI devices that can be specified are those already specified in the default set of tokens that are supplied with Win4Lin. You cannot add your own.

ppidevice
Set to the full path of the Linux PPI device, i.e., the Linux device name of the actual serial port. Used and required only when attachtype is vpippi.

Note:
The only Linux PPI devices that can be specified are those already specified in the default set of tokens that are supplied with Win4Lin. You cannot add your own.

printercommand
The Linux command that processes a print stream (lp, for example). Used and required only when attachtype is spooler.

drivename
The full Linux path and filename of a virtual DOS drive or a file name preceded by H/, indicating a filename relative to the user's home directory (e.g., H/vpart.dsk). Used and required only when attachtype is drive.

When you list tokens in the dosdrive class, you might see names such as dosc, dosd, etc., which represent physical DOS drives. These tokens define the drivename value as the Linux device name of a physical DOS drive. Win4Lin manages tokens for physical DOS drives automatically. Do not try to create or modify tokens for physical DOS drives.

NOTE: If you expect to see tokens such as dosc, dosd, etc., for physical DOS drives and they do not exist, do not try to create them with winadmin. If the DOS drive tokens do not exist, Linux is not properly configured to recognize DOS partitions. To correct the problem, reconfigure Linux to recognize the partitions and reboot. Refer to your Linux documentation for more information.

vpippioptions
This is only used for definitions of special pre-defined devices and is NOT used for definitions a user would create. Possible settings: Multiple values separated by commas can be specified.

This line is used only when attachtype is vpippi, and it is optional.

physicalirq
When used, this specifies the real physical IRQ(s), and irq specifies the virtual IRQ(s) that the DOS or Windows process uses. The number of IRQ values specified must be the same in irq and physicalirq.

This line is used only when attachtype is direct and when irq is also used. It is optional.

physicalioports
When used, this specifies the real physical I/O ports, and ioports specifies the virtual ioports that the DOS or Windows process uses. The syntax of the port values for physicalioports is the same as for ioports. The ranges in ioports and physicalioports must match in size and number.

This line is used only when attachtype is direct and when ioports is also used. It is optional.

physicalmemmappedio
When used, this specifies the real physical addresses of the memory mapped I/O of the device, and memmappedio specifies the virtual address where the DOS or Windows process accesses it. The syntax of the address values is the same as for memmappedio. The ranges in memmappedio and physicalmemmappedio must match in size and number.

This line is used only when attachtype is direct and when memmappedio is also used. It is optional.

physicaldmachannel
When used, this specifies the real physical DMA channel(s) used by the device, and dmachannel specifies the virtual DMA channel(s) that the DOS or Windows process uses. The number of channels specified in dmachannel and physicaldmachannel must be the same.

This line is used only when attachtype is direct and when dmachannel is also used. It is optional.

umbreserve
Reserves UMB RAM locations, preventing the specified ranges from being put on the free list. The syntax of the address ranges is the same as for memmappedio. The range must be within the UMB area 0xa0000 through 0xfffff. Note that ROMs and other devices already consume part of the UMB area, so you must be careful to specify address ranges that are actually available.

This line is used when attachtype is direct or vpippi. It is optional.

It is unlikely that the device definition for a directly attached device will need to have umbreserve specified.

driveoptions
Can be set to readonly or exclusive or both (in either order separated by a comma). Specifies whether a drive is to be read-only (unwriteable) or exclusively attached (i.e., unavailable to other DOS or Windows processes).

This line is used only when attachtype is drive. It is optional.

Definition File Contents for Specific Resources

Following are the definition file contents required for printers, serial ports, DOS drives, and custom devices. Do not use the add, update, or delete options with the ems or mouse classes.

Printers

By default, Win4Lin defines the token "default", which is used for DOS and Windows printing through the Linux spooler (i.e. the standard Linux printing system). If you have special printing requirements, you can set up additional printer tokens by defining the following characteristics in the token definition file:

attachtype=spooler
printercommand=
unix printer command

For situations where printing through the Linux printing system is not desirable, Win4Lin can use tokens that provide direct access to parallel (printer) ports. The following characteristics are defined for these tokens:

attachtype=direct
failureaction=
abort, warn, or ignore
irq=
The interrupt used by the parallel port
ioports=
The I/O port address range used by the parallel port

Note:
On Linux, Win4Lin does not support attaching interrupts.

Serial Ports

NOTE:
On Linux, Win4Lin does not currently support attaching serial ports.

Token definitions for indirectly attached serial ports require that the following characteristics be defined in the definition file:

attachtype=vpippi
vpidevice=
/dev/vcom1, /dev/vcom2
ppidevice=Actual Linux serial port name
failureaction=abort, warn, or ignore
irq=The virtual IRQ used, for documentation only. 4 for COM1, 3 for COM2
ioports=The virtual I/O port address range, for documentation only. 3f8-3ff for COM1, 2f8-2ff for COM2

Token definitions for directly attached serial ports require that the following characteristics be defined in the definition file:

attachtype=direct
failureaction=
abort, warn, or ignore
irq=
The interrupt used by the serial port
ioports=
The I/O port address range used by the serial port

Note:

DOS Drives

You can define tokens for virtual DOS drives using the following token definition file lines:

attachtype=drive
drivename=
full Linux path or H/path relative to $HOME
driveoptions=readonly, exclusive, or both
failureaction=abort, warn, or ignore

By default, Win4Lin defines one token for virtual partitions, homevdrv, which refers to $HOME/vdrive.dsk. Users do not by default have $HOME/vdrive.dsk files, but they can create them using the mkvdisk (/usr/lib/merge/mkvdisk) utility. Any user with a $HOME/vdrive.dsk file can access it using the homevdrv token.

Custom Devices

Custom devices require the line attachtype=direct at the top of the token definition file. Any of the following characteristics that are relevant should also be defined:

irq
ioports
memmappedio
dmachannel
physicalirq
physicalioports
physicalmemmappedio
physicaldmachannel
failureaction
useraccess

You can omit the lines for characteristics that are not relevant from the token definition file, or you can leave the value part of the definition blank.

Note:


NOTE: On Linux systems, only direct attachment of I/O ports is supported, and not IRQ, DMA, or memory mapped I/O.

Updating Token Definitions

Use the "update" option to change existing token definitions. The command-line arguments and contents of the token definition file are identical for the "add" and "update" options. "winadmin add" effectively deletes and re-creates a token with a new definition.


Files

/usr/bin/winadmin

/usr/bin/winadminreset

See also

win(1)
winconfig(1)
© 2000 TreLOS, Inc.

2000/01/10