See Also:

links to this page

previous edition

tools/ pldd/

tools/ gccscsi/

Introduction

Welcome to the plscsi tutorial, presented in 6 chapters and 1 appendix.

Please write Pat LaVarre if you have questions.

We actually first wrote these words as the email replies to a series of delightfully clarifying questions sent to us by André Wilmus in September, 2003.  By email ofrecemos una traducción española, and by email nous offrons une traduction française.  Alta Vista Babel Fish, a free service for translating among some natural languages, began both translations for us.

This tutorial walks you thru the questions many people ask when first trying out plscsi.

By definition, each plscsi command line asks:

2) to copy Data In, to copy Data Out, or to copy No Data at all

3) to copy Status In, and to copy Auto Sense In after any autosensable failure

The traditional host-centred SCSI convention defines what we mean by the words In and Out.  That convention says to copy In is to copy in to the host from the device.  Also to copy Out is to copy out from the host to the device.

Contents

Six chapters:

1. All About You

2. SCSI Devices Named How

3. The First Three Commands To Try

4. Reading Your First Block

5. Decrypting Success

6. Decrypting Failure

One appendix:

A.1. More CDB's Found Defined Where

A.2. Decrypting Capacity

A.3. More Blocks Per Command Line

A.4. Correct CDB Lengths

A.5. Whole Commands

A.6. Less Auto Sense

1. All About You

Sorry you found PLScsi difficult enough to want a tutorial, thank you for finding the time to work thru this tutorial.

We're not sure what to tell you, because we do not know what you do and do not already understand.

If you write for further help, please then share the answers to one of (or more of) the Nine questions:

1) What do you want your DVD/ CD/ HDD/ RMB to do?

2) How did you find PLScsi?

3) What plscsi command did you try that gave you unexpected results?

4) Did you begin with `plscsi -w`?  What result did you get?

5) Where are you trying to learn plscsi: on Linux 2.6/ 2.4, Win XP/ 2K, Win ME/ 9X, Dos, Mac OF, what?

6) Have you already backed up your hard drive, for fear of plscsi crashing your operating system as you requested while you were learning to say what you mean?

7) Do you already know many CDB's, for example that -x "1B 00:00:00 02 00" means Eject, sometimes described as Stop Unit LoEj?

8) Have you already tried pldd?  pldd, plscsi, and gccscsi work at progressively lower levels of the operating system.  The lower the level you target, the more easily you can make a mistake that crashes your operating system.  In October 2003, pldd was freely available for Linux, Win 2K/XP, and Mac OS X.

9) Are you a C programmer yourself?  If so then you may prefer gccscsi - a macro language for writing short C programs that talk SCSI, programs compiled by the free C compilers of Linux/ Windows/ Dos.

2. SCSI Devices Named How

3. The First Three Commands To Try

We believe you can start after listing available devices:

plscsi -w

The same device names listed by plscsi -w work in pldd and in gccscsi.

You may wish to select a single device via such techniques as:

export plscsi=/dev/sg9

set PLSCSI=\\.\A:

set PLSCSI=9.1.0

setenv plscsi /dev/disk0

plscsi -w should print such suggested command lines separately from the commentary which says more about which names select which devices, but earlier versions did not.

Apart from plscsi -w, we recommend you start with:

plscsi -vx "12 00:00:00 24 00" -i x24

This is a more explicit way of asking plscsi to do what plscsi does by default, as plscsi -wv and plscsi -v and plscsi -- will tell you.

Op x12 is INQUIRY.  Among the x24 bytes of Data copied In you should see the name of your device.

The ':' colons are meaningless commentary, you can use ' ' blanks if you prefer.

Maybe next you try:

plscsi -vx "00 00:00:00 00 00"

Op x00 is TEST UNIT READY.  We recommend this command because playing with this command can teach you what success and failure look like.  This command will succeed if retried enough while the disc is present and spun up, but will fail when the disc is absent, arriving, or leaving.  Also this command copies No Data, by design, that is this command copies only Cdb Out and Status and Auto Sense In.

Maybe next you try:

plscsi -vx "25 00 00:00:00:00 00 00:00 00" -i 8

Op x25 is READ CAPACITY.  We recommend this command because it reports the maxLba (i.e. the count of blocks minus one) and the bytes per block.

We use ':' colon commentary in place of ' ' blank commentary to help us get the length of such a cdb correct - ten bytes - and to help us remember such facts as the lba of op x28 appearing in bytes 2:3:4:5, not bytes 1:2:3:4 and not bytes 3:4:5:6.

4. Reading Your First Block

After working thru the simpler exercises above, you may be ready to try tackling the more complex job of reading one block.

The trouble with reading blocks is that first you and the drive have to negotiate the count of bytes per block.  Often you can cheat: you can assume a count and see that it works.  Most DVD/ CD wake up saying  each read block holds 2 KiB = x800 bytes.  Most HDD/ RMB wake up saying each read block holds 0.5 KiB = x200 bytes.

With drives like UDF CD-RW, often we begin with:

plscsi -vx "28 00 00:00:00:10 00 00:01 00" -i x800

In pldd syntax, that same command is:

pldd if=/dev/sg9 of bs=2k count=1

The first byte of the cdb, also known as cdb[0], is the "opcode", nicknamed "op".

Op x28 is READ (10).  In this example, the first block address is cdb[2:3:4:5] = x00:00:00:10 = 16.  The count of blocks is cdb[7:8] = x00:01.  At 2 KiB = x800 bytes per block, x00:01 blocks is x800 bytes, therefore we say -i x800.

We're curious to know if these commands work for you or not.  I hear DVD/ CD make reading difficult.

In particular we've heard that we may have to issue op x5A Mode Sense 10 to copy soft switches of the device In and op x55 Mode Select 10 to copy soft switches Out.  Learning to copy soft switches goes quickly.  Learning what the switches mean and what the switches should say, that takes longer.

5. Decrypting Success

An example of success after asking to read one block from a DVD/ CD is:

> plscsi -vx "28 08 00:00:00:00 00 00:01 00" -i x800
x 00000000 28 08 00:00:00:10 00 00:01 00 .. .. .. .. .. .. "(H@@@P@@A@"
x 00000000 00:00:00:00 00:00:00:00 00:00:00:00 00:00:00:00 "@@@@@@@@@@@@@@@@"
...
x 000007F0 00:00:00:00 00:00:00:00 00:00:00:00 00:00:00:00 "@@@@@@@@@@@@@@@@"
// 0 = plscsi.main exit int
>

If you see something enough like this, congratulations!  You are reading single blocks!

You're also tracing the blocks you read to the screen.  If you'd rather store the blocks to a file, you could instead say something like:

In that example, we've changed the selected lba = cdb[2:3:4:5] = x0000:0010 = x10.

You should get the same results, no matter which syntax you choose from among:

Another equivalent syntax is:

We bother to mention this equivalence because this equivalence lets you use the | pipe char ('\x7C'), if already you know how to use that | pipe char in a command line, for example:

plscsi -x "28 00 00:00:00:10 00 00:01 00" -i x800 -t "" | hexdump -C

Of ever you do choose to view data via plscsi -v, then you  may wish to understand:

plscsi -v does trace all the data, but plscsi compresses the display of some kinds of less interesting trace data.  In email, a "..." ellipsis can mean merely "omitted", but here plscsi prints "..." ellipsis only to mean duplicate lines omitted.  This works much like the "*" convention of linux hexdump -C, except that plscsi omits only the duplicate lines in the middle, not also the last duplicate line.

More specifically, in the example here above, plscsi prints lots of "00" to tell us us explicitly that the x10 bytes at offset x0 and the x10 bytes at offset x7F0 are zero, but then plscsi prints "..." to tell us the x10 bytes at the offsets x 10 20 ... 7E0 (a total of x7E0 = x800 - x20 bytes) are also zero.

More clear than mud, yet?

6. Decrypting Failure

An example of failure after asking to read one block from a DVD/ CD is:

> plscsi -vx "28 00 00:00:00:00 00 00:01 00" -i x800
x 00000000 28 00 00:00:00:00 00 00:01 00 .. .. .. .. .. .. "(@@@@@@@A@"
x 00000000 AE:AE:AE:AE AE:AE:AE:AE AE:AE:AE:AE AE:AE:AE:AE "................"
...
x 000007F0 AE:AE:AE:AE AE:AE:AE:AE AE:AE:AE:AE AE:AE:AE:AE "................"
// x800 (2048) residue
x 00000000 70:00:05:00 00:00:00:12 00:00:00:00 64:00 .. .. "p@E@@@@d@@@@!@"
// x 5 64 sense
// -x0002 = -2 = plscsi.main exit int

>

VERY helpful to have you send to us precisely what you see.

All this rubbish is meaningful to Me, since I typed the source code.

We hear CD's come divided into data and not-data, and that an x28 block read fails if addressed to where not-data appears on the disk.  But we really really really do Not know that, we know very little of DVD/ CD as yet.

We see the plscsi -v command your entered was:

plscsi -vx "28 00 00:00:00:00 00 00:01 00" -i x800

We see PLScsi traced the 10 bytes of CDB copied Out:

x ... 28 00 00:00:00:00 00 00:01 00 ...

We see PLScsi traced the content of the Data buffer after trying to copy Data In:

x ... AE:AE:...

We see PLScsi mention a failure to copy In x800 of the -i x800 Data In bytes you requested:

// x800 (2048) residue

We see PLScsi traced the x12 bytes of Auto Sense copied In:

x ... 70:00:05:00 00:00:00:12 00:00:00:00 64:00 ...

We see the PLScsi summary of the Auto Sense bytes copied In is:

// x 5 64 sense

We remember auto sense bytes have a structure often specified together with op x03 Request Sense.  The x70 byte means the following bytes are "Current".  Current bytes apply to the command that failed, not some earlier command, unless SK is 6 "unit attention".  The x12 byte at offset 7 means as many as eighteen (i.e. x12) meaningful bytes could follow, though plscsi tries to make sense of only the six bytes that actually do follow.  The "5 ... 64:00" nybble and bytes are the SK ASC ASCQ ("sense key", "additional sense code", "additional sense code qualifier".

We remember this example summary implicitly refers to such English as Fuji5r15.pdf:

A-1 Error Reporting ...
A-1.2 Error Tables ...
Table 499 - All Error Codes (Sheet 7 of 8)
...
5 = Sense Key
64 = ASC
00 = ASC Q
ILLEGAL MODE FOR THIS TRACK = Description
CD Read = Type

We see the PLScsi summary of all of this is:

// -x0102 = -258 = plscsi.main exit int

We have not completed the design of exit codes for PLScsi, but in the version of PLScsi shown here, the x0100 bitmask here again says we asked to more data bytes than you managed to copy.  The x0002 bitmask here again says the command failed with auto sense.  Also we're told x0102 = 258, not that we care

A.1. More CDB's Found Defined Where

As of September, 2003 ...

The web trail we follow to discover CDB's for DVD and for CD is:

http://www.bswd.com/cornucop.htm

We think of INF-8090 as almost the "oldest available original", though we think we remember INF-8020 is more original.

We hear the newest but least stable DVD/ CD specificiation may be:

In our copyt, page 381 of 614 includes "Table 272 - READ (10) Command Descriptor Block".

Please write to Pat LaVarre if you want help finding CDB's for HDD and for RMB too.  We do possess a hard copy of SCSI-1 we can use to research historical questions.  ANSI T10 publishes final draft editions of the SPC and SBC command sets for HDD and for RMB, alongside the oldest available original SCSI-2, at:

http://www.t10.org/scsi-3.htm

A.2. Decrypting Capacity

Among the first three commands we suggested trying, we include op x25 Read Capacity because by that command, you discover bytes per block and you can begin to guess the maxLba.  But even that most basic of SCSI commands includes a pitfall by design.

On paper, despite the name READ CAPACITY, T10 actually requires that op to copy In a max Lba, not the disk capacity equal to the count of blocks that many other ops copy In, including SCSI op x23 Read Format Capacities and Ata op xEC Identify.

Fuji5r15.pdf

"14.20 READ CAPACITY command"

"The returned logical block address and the block length in bytes are those of the last logical block on the logical unit."

That is, on paper, the device copies in the Lba of the last block of the disk, not the Lba that points just past that block.  In practice we hear many devices report maxLba + 1 instead.  Bugs happen in device firmware too.  Linux USB Storage defines the connect option US_FL_FIX_CAPACITY to help overcome this popular misunderstanding.

We once heard that people prefer the newer op x23, but we still find drives that support only op x25, not op x23.

A.3. More Blocks Per Command Line

[ Editing incomplete here!  If you write Pat LaVarre to tell us you got this far, then we'll finish faster.]

You say you want to use plscsi.

Are you sure you want to do more than read/write blocks?

We ask for Four reasons:

1)

pldd only knows how to copy the 2 KiB/block = x800 byte/block of DVD/ CD and the 0.5 KiB = x200 byte/block of HDD/ RMB.  If that's all you want to do, then the extra options of plscsi may only confuse you pointlessly.

2)

With one pldd command line, you can ask to try sending many CDB's.  With one plscsi command line, you send one CDB, except for the -y and -n options that repeat that CDB unchanged.  With pldd, the parameter bs= specifies the data bytes per CDB, and the parameter count= specifies how many CDB's to send.

That difference in design may matter to you if you discover Windows misbehaving when you exceed 64 KiB per CDB.   I agree you should be able to copy xFFFF blocks ( = 128 MiB / 2 KiB = 32 MiB / 0.5 KiB) with one CDB.  Maybe thru Linux you can, but thru Windows anything much above 64 KiB ( = x20 * 2 KiB = x80 * 0.5 KiB) causes trouble in the host, even if the drive is ok.  Rumour tells me drives are often broken here too, because Windows makes them hard to test here.  Last I checked, Linux worked up to about 8 MiB per CDB.

3)

pldd -v ..., if it works, will have shown you some device names and CDB's that work.  Also, when your intent actually is to shatter a read or write into a series of CDB's with just a few bytes per CDB, often you'll find pldd runs faster than plscsi.

You could then duplicate those CDB's in plscsi with the appropriate -i and -o options.  Having duplicated these CDB's, you could then change these CDB's.

4)

Examples ...

With pldd, to read block x10:

pldd.exe -v if=\\.\A: of=x10.bin bs=2k skip=x10 count=1

With pldd, to read 16 blocks starting with block x450:

pldd.exe -v if=\\.\A: of=x450.bin bs=32k sbs=2k skip=x450 count=1

With pldd, to read 5 * 16 blocks starting with block x450:

pldd.exe -v if=\\.\A: of=x450.bin bs=32k sbs=2k skip=x450 count=5

The -v option should tell you you have achieved the effect:

plscsi -x "28 00 00:00:04:50 00 00:10 00" -i x8000
plscsi -x "28 00 00:00:04:60 00 00:10 00" -i x8000
plscsi -x "28 00 00:00:04:70 00 00:10 00" -i x8000
plscsi -x "28 00 00:00:04:80 00 00:10 00" -i x8000
plscsi -x "28 00 00:00:04:90 00 00:10 00" -i x8000

Suppose you do choose to read blocks via plscsi rather than pldd.  You might then try something like:

plscsi -x "28 00 00:00:04:50 00 00:50 00" -i x28000

This command probably won't work in Windows, because you're asking for x2:8000 bytes/CDB i.e. more than x1:0000 = 64 KiB/CDB = (x20 * 2 KiB) per CDB.  In Windows, you're supposed to throw away thruput by shattering streams of read/write into tiny 64 KiB pieces.

What should work in Windows is something like:

pldd -v if=\\.\R: of=x450.bin bs=x10000 count=3

Notice plscsi/pldd only throw away colons found in CDB's, e.g. we have to say bs=x10000, we cannot say bs=x1:0000.

That pldd -v option will tell you this command tried a sequence of CDB's:

plscsi -x "28 00 00:00:04:50 00 00:20 00" -i x10000
plscsi -x "28 00 00:00:04:70 00 00:20 00" -i x10000
plscsi -x "28 00 00:00:04:90 00 00:20 00" -i x10000

If you choose x1:0000 bytes/CDB = 64 KiB/CDB like this, then with pldd you can't read just xA0 = 160 KiB = x2:8000 bytes.  Instead you have to read x3:0000 bytes.

A.4. Correct CDB Lengths

A.5. Whole Commands

[ Editing incomplete here!  If you write Pat LaVarre to tell us you got this far, then we'll finish faster.]

I vehemently agree the CDB should unambiguously say how many bytes of data to copy which way.  I deeply regret that in fact the CDB does not.  I imagine we inherited this defect in protocol from the IBM mainframes of the 1960's.

plscsi works at a level below knowing that x28 means READ (10), because SCSI does not promise you that x28 means READ (10), although for DVD/ CD/ HDD/ RMB x28 usually does.

Consequently, to plscsi you have to specify more than the CDB via the -x option, you also have to say how many bytes of data you want to copy which way, via such options as -i and -o.  At the level of plscsi, the CDB alone is not the whole command, not unless you mean to ask to copy no bytes of data.

> > plscsi -vx "28 04 50 00 00 00 00 00 10 00"
> > ... rude if compared to:
> > plscsi -vx "28 04 50 00 00 00 00 00 10 00" -i x800

Correction, sorry.  Both of those are rude.  A copy of x10 blocks of x800 bytes each is x8000 bytes, not x800 bytes.

plscsi -vx "28 04 50 00 00 00 00 00 10 00"
is rude if compared to:
plscsi -vx "28 04 50 00 00 00 00 00 10 00" -i x800.

In the first case, we're sending a cdb to copy data, but in the same breath we're implicitly telling plscsi Not to copy data, because we have specified no -i and no -o option.  We're contradicting ourselves. This kind of thing tends to confuse Windows enough to crash it.  In the Usb Mass standard, this particular kind of contradiction is termed Hn < Di i.e. if the device thinks that the cdb meant to copy Data In then the host is asking to copy No Data but the device is asking to copy Data In and life goes downhill from there.

Notice you could deeply confuse, maybe even crash Windows if your -i x24 interpretation of the CDB in fact did not agree with the device's interpretation of the CDB.  Serial FireWire & USB connections copy the -i x24 Out to the device, so the device gets a chance to notice disagreements in interpretation, and a few devices in fact are that smart.  But parallel SCSI & parallel ATAPI connections copy only the CDB Out.  Those protocols by design assume that the host & the device perfectly coordinate all interpretations of CDB's.  Violating that assumption is how FireWire HDD that choke over op x12 cause so much trouble.

A.6. Less Auto Sense

If you trace the bus while you use plscsi, sometimes you will see two commands rather than one.

This occurs if the first command fails with an "auto sensable" status, such as a classic parallel SCSI x02 Check Condition or an ATAPI  x03 Status In of x01 ERR.  After an auto sensable status, the host automagically injects a second command, specifically op x03 Request Sense.

This fact violates the spirit of plscsi: you completely control only the first command, not the possibly automagic second command.

This fact arises because auto sense has to happen below plscsi to work reliably.  Somewhere below plscsi we need code to guarantee exclusive access to the device long enough to keep the auto sense together with the CDB to which the auto sense refers.  We need exclusive access because op x03 Request Sense by definition refers to the op that immediately preceded it and op x03 by definition "reads and clears".

For example, suppose we have two threads in the host that send commands that fail: cdb1 and cdb2.  Say the auto sense for each is as1 and as2.  The only sequences that work are  <cdb1 as1 cdb2 as2 > and < cdb2 as2 cdb1 as1>.  Mixed sequences like <cdb1 cdb2 as1 as2> get wrongs answers.  In that instance, cdb2 overwrites the sense of cdb1, as1 gets the error details for cdb2 rather than cdb1, and as2 gets the zeroed sense left behind when as1 read and cleared sense.

Clear so far?

Now, because auto sense happens below plscsi, we can't easily control auto sense.

plscsi cannot see if auto sense occurs via op x03 Request Sense as in classic parallel SCSI, ATAPI, USB, etc. or via some other mechanism as in 1394/ Apple FireWire/ Sony iLink, etc.  plscsi never traces the auto sense CDB that plscsi does not see.

In an autosense CDB, byte 4 is the max count of auto sense bytes to copy In across the bus.  plscsi can't see that either.  plscsi can only specify the max count of auto sense bytes to copy In to plscsi.  Some SCSI bus drivers round that count up to xFF, so that a bus trace always shows all the auto sense bytes that op x03 implicitly clears after reading some or all of them.  Some SCSI bus drivers round the count off to align the count, or to match a conventional choice, to avoid surprising the device.  Conventional choices for that byte include the x0E of Win 9X/ME and the x12 of Win 2K/XP.

The plscsi option -X sense x$XX exists to let you try asking to copy different lengths of auto sense bytes into plscsi.  We say plscsi "should" define an option to let you misalign your auto sense data on purpose, just as plscsi already defines the -a $page $offset to let you misaligned your data on purpose.

The -X sense x$XX option may not work well: despite our academic interest, we don't find much use for that option in the real world.  We find many hosts choke over any but standard lengths.

If you want to experiment as we have, we recommend you begin with "unsolicited sense" i.e. explicitly choose to send an op x03 e.g. plscsi -pvx "03 00:00:00 10 00" -i x10.  Indeed, before that, we recommend you begin with op x12 Inquiry e.g. plscsi -vx "12 00:00:00 10 00" -i x10.  Once you understand those results, you have a chance of understanding what -X sense x$XX will tell you.  On the other hand, we do know of hosts that transparently pass thru standard lengths of auto sense but choke over unsolicited sense.

Remember, hosts tend to have trouble with lengths other than a multiple of the word size of your motherboard.  For example, we imagine if you study auto sense carefully, you will discover that with 32 bit motherboards often you are copying in x10 bytes rather than x0E, or x14 rather than x12.  We say plscsi "should" make this rounding-up more obvious.

Specific hosts often support undocumented ways of turning off auto sense.  As the length of auto sense bytes to copy In to plscsi, we can try negative numbers, positive numbers in excess of xFF, and zero itself.  While indeed on paper the cdb -x "03 00:00:00 00 00" is meaningful, zero auto sense isn't very meaningful: zero auto sense asks to clear all sense data after reading zero bytes of sense data.  Consequently some hosts reserve length zero to mean do not auto sense.

Write to tell us if in fact one or more of the above "should"s actually do matter to you, and we will get around to messing with them in less years than otherwise.