4
Porting WorkMan to a new platform is a two-step process. The first
5
step is to get the XView toolkit, version 3.0 or higher, running on
6
your system. If you're lucky, someone else has already done so. The
7
alt.toolkits.xview and comp.windows.open-look newsgroups are good
8
places to find out whether XView exists for your system.
10
Once you have XView installed, you can work on porting WorkMan itself.
11
If your system has builtin libraries for manipulating audio CDs, you
12
can use them. Or you can use your system's user-level SCSI interface,
15
All of the user interface modules ought to compile without
16
modification. For the most part they're just standard C and documented
19
The platform-dependent code in WorkMan is in source files named
20
plat_xxx.c, where xxx is the platform name. If you look at a directory
21
listing you'll see that there are files like this for Sun, HP, Linux,
22
and other platforms already. Each of these files (called "platform
23
modules") contains a set of well-defined functions for controlling and
24
getting information from a CD-ROM drive. You'll find a list of those
25
functions below. Ordinarily, porting WorkMan is simply a matter of
26
writing those functions for your platform, and you can usually use one
27
of the existing platform modules as a starting point.
29
WorkMan supports the notion of running any kind of drive on any
30
platform, assuming the platform has facilities for sending arbitrary
31
SCSI commands from user processes. To this end, you'll also find
32
"drive modules" named drv_xxx.c. Each drive module contains
33
replacement functions along the lines of the functions in the platform
34
modules; these replacement functions are called when the drive doesn't
35
respond to generic requests or when something unusual needs to be
36
done. For instance, the Sony CDU-8012 (also known as the SunCD drive)
37
has a weird volume scale, so we need to do a transformation on the
38
volume setting before passing it to the drive. But other than that,
39
the drive responds to generic CD-ROM commands, so drv_sony.c only has
40
code relating to volume control.
42
Implementing drive modules is fairly simple, but usually isn't
43
necessary so it won't be discussed here. Mail me if you need to do it.
45
Here are the functions a platform module needs to implement. All
46
functions should return integers. Unless otherwise noted, they should
47
return 0 on okay status, -1 on an error condition.
49
The first parameter of each function is a pointer to a wm_drive
50
structure. You'll find it defined in "struct.h". It's discussed after
51
the function call list. You will probably find it helpful to look at
52
one of the existing platform modules while reading this list. The Sun
53
module is one of the simpler ones.
55
wmcd_open(struct wm_drive *d)
56
Figure out the drive type and fill in pointers to the rest of
57
the routines listed here. This routine should set up the device
58
to receive CD-ROM commands if necessary. If the wm_drive
59
structure says the drive is already open, this routine should
60
return 0 -- in other words, it shouldn't hurt to call wmcd_open
61
ten times in a row. If the drive couldn't be opened yet, or
62
initialization couldn't be performed yet, the function should
63
clean up and return 1; it will be called again after a short
64
delay. A common example is an open() call failing because
65
there's no CD in the drive.
67
wmcd_open() should determine the drive type if possible. If the
68
wm_scsi() function has been implemented, it can simply call
69
wm_scsi_get_drive_type() (which is in scsi.c) to retrieve the
70
necessary information. Then find_drive_struct() (from cdrom.c)
71
should be called to look up the drive from the list of drive
72
modules; it returns a pointer to a wm_drive structure, which
73
should be copied into the buffer pointed to by the "d"
74
parameter. Finally, the drive init function should be called.
76
Some systems can't determine the drive type at all, for
77
instance because the CD-ROM drive can only be accessed through
78
a limited set of function calls. In that case, just pass empty
79
strings to find_drive_struct() and it'll return a wm_drive
80
structure pointing to the generic platform module routines.
82
wm_scsi(struct wm_drive *d, unsigned char *cdb, int cdblen, unsigned
83
char *buf, int len, int getdata)
84
Send a command to the SCSI device referenced by the wm_drive
85
structure. A CDB of appropriate size is passed in, as is a data
86
buffer. If "getdata" is true, read some data into the buffer in
87
response to the command. Otherwise the buffer might contain
88
some data to be written out as part of the command. "buf" can
89
be NULL if the caller doesn't want to pass in or receive any
90
data. Return -1 if the command doesn't complete successfully.
91
If your system doesn't support SCSI passthrough, this function
92
should just return -1 without doing anything else.
94
The following functions can be overridden by drive modules, as they're
95
always called indirectly via the wm_drive structure.
97
gen_init(struct wm_drive *d)
98
Initialize whatever drive-specific settings are required. For
99
the platform module this is usually just { return (0); } since
100
any platform-specific initialization should be performed in
101
wmcd_open(), but the function needs to be defined.
103
gen_get_trackcount(struct wm_drive *d, int *tracks)
104
Store the number of tracks on the CD in *tracks.
106
gen_get_cdlen(struct wm_drive *d, int *frames)
107
Store the total number of frames on the CD in *frames.
109
gen_get_trackinfo(struct wm_drive *d, int track, int *data, int
111
Get the starting frame number and type (1 = data track, 0 =
112
audio) of a particular track. Tracks are numbered starting at
115
gen_get_drive_status(struct wm_drive *d, enum mode oldmode, enum mode
116
*mode, int *pos, int *track, int *index)
117
Get the current status of the drive. Mode is one of PLAYING,
118
PAUSED, TRACK_DONE, STOPPED, and EJECTED, as is oldmode (which
119
will be the previous mode value returned by the routine.) The
120
other parameters are filled in if the drive is playing or
121
paused: the absolute position in frames, the track number, and
124
gen_get_volume(struct wm_drive *d, int *left, int *right)
125
Get the current volume settings for the left and right
126
channels, or -1 if that information can't be read from the
127
drive. Values range from 0 to 100 on a linear scale.
129
gen_set_volume(struct wm_drive *d, int left, int right)
130
Set the current volume for each channel. Values are from 0 to
131
100, on the same linear scale as returned by gen_get_volume().
133
gen_pause(struct wm_drive *d)
136
gen_resume(struct wm_drive *d)
137
Resume playing the CD after a pause.
139
gen_stop(struct wm_drive *d)
140
Stop the CD if it's playing or paused.
142
gen_play(struct wm_drive *d, int start, int end)
143
Play a stretch of the CD. Both times are in frames. This can
144
return negative values other than -1 if playing a CD is a
145
multi-step process, e.g. a "start motor" command followed by a
146
"play audio" command.
148
gen_eject(struct wm_drive *d)
149
Eject the CD. Return -3 if the CD can't be ejected because it
150
contains a mounted filesystem.
152
The wm_drive structure has at least the following elements:
154
int fd; /* File descriptor, if used by platform */
155
char vendor[16]; /* Vendor name */
156
char model[24]; /* Drive model */
157
void *aux; /* Pointer to optional platform-specific info *
159
void *daux; /* Pointer to optional drive-specific info */
162
int (*get_trackcount)();
164
int (*get_trackinfo)();
165
int (*get_drive_status)();
175
The "fd" and/or "aux" elements should be filled in by the wmcd_open()
176
function after find_drive_struct() is called. The "fd" element is for
177
an open file descriptor pointing to the drive, though if your platform
178
doesn't use file descriptors to refer to CD-ROM drives (e.g. the
179
BSD/386 platform, whose CD library uses structure pointers) you can
180
use the "fd" element for something else or ignore it completely.
182
The "aux" element should be used to point to any state information you
183
need to keep across calls to these functions. Since WorkMan may
184
eventually support controlling multiple drives simultaneously, you
185
should not use global variables to keep per-drive state. Define a
186
structure for whatever state you need, and point "aux" to it. You can
187
get at it in any of the routines since they are all passed the
188
wm_drive structure you fill in in wmcd_open(). On many platforms,
191
The "daux" element is reserved for use in drive modules.
193
If you have questions, don't hesitate to send me E-mail. I want to see
194
WorkMan as widely ported as possible.
196
-Steven Grimm [1]<koreth@hyperion.com>
198
_________________________________________________________________
200
[2]To the WorkMan home page
202
Last update: 02 Jun 1995
206
1. mailto:koreth@hyperion.com
207
2. file://localhost/home/woodstock/koreth/wm/workman/HTML/index.html
added
removed
doc/kscd/workman-docs/porting
