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:
- printer
- com1
- com2
- dosdrive
- custom
- ems
- mouse
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
-
class is one of the token classes listed above.
-
token is a unique short name (up to 12 characters)
for the resource.
Tokens can contain only letters (uppercase or lowercase), numbers,
and hyphens.
-
definition_file is the name of the definition file that contains the
resource specification. definition_file can have any name and be
located in any directory. You can specify the definition_file
name alone if it is in your current directory when you invoke winadmin.
Otherwise, specify it by full path.
definition_file is used only at the time you use winadmin
to create the token, so you can delete it after you create the token.
-
full_name is a more descriptive name for the resource.
It appears in the Win4Lin Setup window and is displayed along with
token names when you use the winadmin list option.
Full names can be longer than tokens and
can use any characters, including spaces.
If you use spaces or other Linux metacharacters, enclose the
full name in quotes when you issue the winadmin command.
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:
- automouse
- closeppi
- openppi
- ppistreams
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