Rechercher une page de manuel
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 2006Contenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre