cbmctrl

Langue: en

Version: April 2006 (mandriva - 01/05/08)

Section: 1 (Commandes utilisateur)

NAME


 cbmctrl - manual page for cbmctrl 0.4.2
 - control serial CBM devices This document is poorly maintained and probably outdated. If in doubt, use the Texinfo manual. If the info program is properly installed at your site, the command
info opencbm

should give you access to the complete manual.

SYNOPSIS

cbmctrl [global_options] [action] [action_args]

DESCRIPTION

cbmctrl can control all kinds of serial CBM devices like floppy drives and printers. So far, it has been successfully tested with the disk drives 1541(-II), 1571 and a MPS-1200 printer.

Structure

Overall structure of cbmctrl actionss
The overall format of all cbmctrl actions is:
cbmctrl [global_options] [action] [action_args]
cbmctrl
The name of the cbmctrl program
global_options
Some options that are related to cbmctrl in general or affect the overall behaviour of all actions
action
One of a bunch of different subcommands that direct cbmctrl what to do
action_args
Arguments that are required for the subcommand action to work

OPTIONS

Global options
cbmctrl understands the following global options
-h
[<action>]
--help
[<action>]
Outputs the help screen with a short listing of all available actions. If the optional <action> name is given also, you retrieve more information on a specific action together with its arguments and parameters
-V, --version
Output version information as well as the build date and time.

Actions overview

cbmctrl understands the following subcommand actions
reset
- Reset all drives on the IEC bus
detect
- Detect all drives on the IEC bus
lock
- Lock the parallel port for cbm4win/cbm4linux use
unlock
- Unlock the parallel port from exclusive usage
listen
- Perform a listen on the IEC bus
talk
- Perform a talk on the IEC bus
unlisten
- Perform an unlisten on the IEC bus
untalk
- Perform an untalk on the IEC bus
open
- Perform an open on the IEC bus
close
- Perform a close on the IEC bus
popen
- Same as open, but with ASCII to PETSCII conversion
read
- Get a stream of raw data from an IEC bus device
write
- Put a stream of raw data to an IEC bus device
status
- Give the status of a specified drive
command
- Issue a command to a specified drive
pcommand
- Same as command, with ASCII to PETSCII conversion
dir
- Output the directory of a disk in a specified drive
download
- Download memory contents from a floppy drive
upload
- Upload memory contents to a floppy drive
change
- Wait for a disk to be changed in a specified drive

Common action arguments

Many of the cbmctrl subcommands understand the following common arguments:
<device>
Advice cbmctrl to direct its communication to the IEC bus device with the number <device>. IEC bus device numbers can be denoted in the range from 0 to 30, although no Commodore device is known to use device numbers 0 to 3. Most commonly used are the numbers 4 (printer) and 8 to 11 (disk drives). Device number 31 is used to denote the UNTALK respectively the UNLISTEN command code on the IEC bus instead of the TALK respectively LISTEN command code, therefore device address 31 cannot be used in general.
<secadr>
With several cbmctrl actions the secondary address parameter <secadr> denotes a dedicated logical communication channel for the specified <device>. IEC bus channel numbers can be denoted in the range from 0 to 15. Take note that for floppy disk drive devices some secondary addresses are interpreted in a special way. Secondary address 0 is used, when a program is loaded, address 1, when a program is saved. Address number 15 represents the command channel of the disk drive, so effectively, for bulk data transfers to and from disk drives, only the logical channel numbers 2 to 14 can be used.

Actions

cbmctrl understands the following actions:
reset
This action performs a hardware reset of all devices attached to the IEC bus. Control is returned after it is made sure that all devices are ready.
detect
This action tries to detect all devices attached to the IEC bus. For this, this subcommand accesses all possible devices and tries to read some bytes from its memory. If a devices is detected, its name is output. Additionally, this routine determines if the device is connected via a parallel cable (XP1541 companion cable, may be true for disk drives only).
lock
This command locks the parallel port for exclusive use by cbm4win/cbm4linux, so that sequences of e.g. talk/read/untalk commands are not broken by concurrent processes wanting to access the parallel port.

Best practice is it to enclose each such sequence that contains either talk, untalk, listen, unlisten, open, close, read or write by a lock/unlock pair of commands. Scripting systems or other software systems using cbmctrl instead of the OpenCBM API should issue a cbmctrl lock command on startup and a cbmctrl unlock upon (each) exit.
unlock
Ends exclusive parallel port access by opencbm so that other processes are allowed to access the parallel port.
listen <device> <secadr>
Tell device <device> to listen on secondary address <secadr>. Until the next unlisten command, everything written with the action command write (see below) will be received by this device. Take note that a listen command has to be undone later with an unlisten (see below) command.

This command corresponds to the following 6502 assembler code on a C64:
lda #dev jsr $ffb1 lda #sa ora #$60 jsr $ff93
talk <device> <secadr>
Tell device <device> to talk on secondary address <secadr>. Until the next untalk command, data from this device can be received by reading with the action command read (see below). Take note that a talk command has to be undone later with an untalk (see below) command.

This command corresponds to the following 6502 assembler code on a C64:
lda #dev jsr $ffb4 lda #sa ora #$60 jsr $ff96
unlisten
Ends communication with listening devices by undoing one or more previous listen or talk commands. This IEC command affects all devices on the bus; it corresponds to the C64 kernel routine $ffae.
untalk
Ends communication with talking devices by undoing one or more previous listen or talk commands. This IEC command affects all devices on the bus; it corresponds to the C64 kernel routine $ffab.
open <device> <secadr> <filename>
Open file <filename> on device <device>. After opening, data can be read/written by sending a talk resp. listen command with secondary address <secadr>. Take note that an open command has to be undone later with a close command.
Notes:
*
If <secadr> is greater than 1, file type and access mode must also be specified by appending ,<type>,<mode> to <filename>. Valid types are D, P, S, U and R (del, prg, seq, usr, rel), valid modes are R for reading and W for writing.
*
You cannot do an open without a filename. Although a CBM machine (i.e., a C64) allows this, it is an internal operation to that computer only.
*
cbmctrl open does not change any character encoding, that is, it does not convert between ASCII (used by the PC) and PETSCII (used by the CBM device). If this is needed, use cbmctrl popen instead.
popen <device> <secadr> <filename>
The popen action is the very same as the open action and all parameters act the same. The difference is that the <filename> string is converted from ASCII to PETSCII before beeing sent to the device.
Notes:
The same notes as with the open action apply to the popen action.
close <device> <secadr>
Close the file associated with secondary address <secadr> on device <device>. This undoes a previous open or popen command.
read [<file>]
Reads raw data from a device, after it has been set into talk mode. The data stream may be stored into a file named by the optional parameter <file>. If <file> is omitted or if it is named -, the data stream is put to the standard output channel on the host computer.
write [<file>]
Writes raw data to a device, after it has been set into listen mode. The data stream may be taken from a file named by the optional parameter <file>. If <file> is omitted or if it is named -, the data stream is get from the standard input channel on the host computer.
status <device>
Copies input from device <device>, secondary address 15 (command/status channel), to standard out. Note that all upper case characters are changed to lower case. Carriage return (0x0d) is also changed to the current operating systems line ending convention (0x0a on Unix oriented systems, 0x0d 0x0a on Windows oriented systems).
This action is similar to (in this case, no character conversions would be made):
cbmctrl lock cbmctrl talk <device> 15 cbmctrl read cbmctrl untalk cbmctrl unlock
command <device> <cmdstr>
Sends <cmdstr> to device <device>, secondary address 15 (command/status channel). Note that most (all?) devices accept upper case commands only, lower case will not work (i.e., N: to format a drive, V: to validate, etc.)!
This command is identical to:
cbmctrl lock cbmctrl listen <device> 15 echo -n <cmdstr> | cbmctrl write cbmctrl unlisten cbmctrl unlock (NOTE: "echo -n" does natively work under Linux only)
pcommand <device> <cmdstr>
The pcommand action is the very same as the command action and the <device> parameter acts the same. The difference is that the <cmdstr> string is converted from ASCII to PETSCII before beeing used.
Notes:
*
Despite the command action command, all commands (stated within <cmdstr>) have to be given in lower case letters. The letter case conversion is one of the things the ASCII to PETSCII conversion does.
*
Due to the conversion from ASCII to PETSCII, sending "m-r" and "m-w" device commands will not work in most cases, because the data to be sent will be converted too and thus corrupts the stream.
dir <device>
Display the directory from the disk in the specified disk drive IEC device <device>.
download <device> <address> <count> [<file>]
Read <count> bytes from a disk drive's memory, starting at <address> via one or more M-R commands. Memory contents are written to standard output as long as <file> is ommited or equivalent to -. Note that <count> and <address> accept decimal as well as sedecimal (hexadecadic) numbers when prefixed with 0x or 0X (but not with the usual $ sign).
upload <device> <address> [<file>]
Send <file> to drive memory, starting at <address> via one or more M-W commands. If <address> is -1, the first two bytes from <file> are considered as start address. Reads standard input if <file> is ommited or equivalent to -. <count> and <address> accept decimal as well as hex numbers (with 0x or 0X prefix).
cbmctrl change <device>
This action advises a disk drive IEC device with number <device> to wait for a disk to be exchanged. It makes the following assumptions for this:
*
there is already a disk in the drive,
*
that disk will be completely removed and replaced by another disk,
*
we do not want to return from this command until the disk is completely inserted and ready to be read/written.
Because of this, just opening the drive and closing it again (without actually removing the disk) will not work in most cases.

EXIT CODES

cbmctrl sets the exit code to 0, if the operation completed successfully. It exits with 2 if the command parser detected a problem with the number of arguments, their size or the combination of commands and options.

Take note that each command action does return its own exit codes (mostly 0 for success and 1 as a failure indicator). The exact exit code, especially when looking to failure conditions, is platform and implementation (driver) specific, because operation system specific error codes are used often.

BUGS

Due to the nature of cbmctrl beeing a command (sub-) processor, the global options are currently also beeing interpreted as commands and therefore cannot be combined. For example,
cbmtrl -V --help change

does not work and leads to an error message.

The lock/unlock actions are currently without any functionality within the cbm4linux driver. They can be issued without any failure, but actually the parallel port becomes not explicitly locked/unlocked to the driver. That way scripts containing lock/unlock commands can be ported from Windows to Linux without changes.

EXAMPLES

Send file contents to printer #4:
cbmctrl lock cbmctrl listen 4 0 cbmctrl write filename cbmctrl unlisten cbmctrl unlock
Copy file to disk drive #8:
cbmctrl lock cbmctrl open 8 2 CBMNAME,P,W cbmctrl listen 8 2 cbmctrl write filename cbmctrl unlisten cbmctrl close 8 2 cbmctrl unlock
Copy file from disk drive #8:
cbmctrl lock cbmctrl open 8 2 CBMNAME,P,R cbmctrl talk 8 2 cbmctrl read filename cbmctrl untalk cbmctrl close 8 2 cbmctrl unlock
Download the #9 disk drive DOS ROM to file:
cbmctrl download 9 0xc000 0x4000 1541ROM.BIN
Transfer file to disk drive #10, buffer at address $500:
cbmctrl upload 10 0x500 BUFFER2.BIN

AUTHOR

Michael Klein <michael(dot)klein(at)puffin(dot)lb(dot)shuttle(dot)de>, additions and reworks by Spiro Trikaliotis, additions by Wolfgang Moser <cbm(a)d81(o)de>.

DATE

Apr 27 2006