From rdm@cfcl.com Thu Feb 1 15:51:17 2001 Return-Path: Received: from cfcl.com (cpe-24-221-169-54.ca.sprintbbd.net [24.221.169.54]) by hub.freebsd.org (Postfix) with ESMTP id AC8CB37B67D for ; Thu, 1 Feb 2001 15:51:12 -0800 (PST) Received: (from rdm@localhost) by cfcl.com (8.9.3/8.9.3) id PAA29338; Thu, 1 Feb 2001 15:51:47 -0800 (PST) (envelope-from rdm) Message-Id: <200102012351.PAA29338@cfcl.com> Date: Thu, 1 Feb 2001 15:51:47 -0800 (PST) From: Rich Morin Reply-To: rdm@cfcl.com To: FreeBSD-gnats-submit@freebsd.org Subject: missing FILES descriptions in sa(4) X-Send-Pr-Version: 3.2 >Number: 24786 >Category: docs >Synopsis: missing FILES descriptions in sa(4) >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Thu Feb 01 16:00:03 PST 2001 >Closed-Date: >Last-Modified: Fri Feb 9 13:20:01 PST 2001 >Originator: Rich Morin >Release: FreeBSD 4.1-RELEASE i386 >Organization: Canta Forda Computer Laboratory >Environment: FreeBSD cfcl.com 4.1-RELEASE FreeBSD 4.1-RELEASE #0: Fri Jul 28 14:30:31 GMT 2000 jkh@ref4.freebsd.org:/usr/src/sys/compile/GENERIC i386 >Description: The sa(4) man page neglects to give definitions for /dev/[en][r]sa0. It also fails to describe the meaning of the ".[0-3]" extensions (e.g., /dev/sa0.1). >How-To-Repeat: man 4 sa >Fix: Find out the real story on the naming convention, then write it up. It _looks_ as if the [r] field has to do with requiring root access. I dunno what the ".[0-3]" field is all about... Note: Please send me the new write-up, once it's done! >Release-Note: >Audit-Trail: From: Nik Clayton To: Rich Morin Cc: FreeBSD-gnats-submit@freebsd.org, julian@freebsd.org, mjacob@freebsd.org Subject: Re: docs/24786: missing FILES descriptions in sa(4) Date: Fri, 9 Feb 2001 00:36:51 +0000 I'm copying Julian and Matt on this, who know more about this subsystem than I do. On Thu, Feb 01, 2001 at 03:51:47PM -0800, Rich Morin wrote: > >Number: 24786 > >Category: docs > >Synopsis: missing FILES descriptions in sa(4) <...> > The sa(4) man page neglects to give definitions for > /dev/[en][r]sa0. Yes it does. The device name takes the form /dev/[n][e]sa[0-9] If it's just /dev/sa then the device will try and rewind the tape when the device is closed. If there's a leading 'n' then the device will not be rewound. If there's a leading 'e' then the device will be ejected on close. So if your application opens /dev/nesa0, and then closes the device, the tape will not be rewound, and the driver will tell the drive to eject the tape. This is all in the FILES section. 'r' means 'raw', but that isn't used on FreeBSD any more. It looks as if MAKEDEV wasn't updated to remove the code that creates the rsa* devices. > It also fails to describe the meaning > of the ".[0-3]" extensions (e.g., /dev/sa0.1). Covered in the SUB-MODES section in the man page (I think), although this is somewhat cryptic. We could probably add something like /dev/sa0.0 Corresponds to sub-mode 00 /dev/sa0.1 Corresponds to sub-mode 01 /dev/sa0.2 Corresponds to sub-mode 10 /dev/sa0.3 Corresponds to sub-mode 11 to the FILES section. Matt, Julian, any thoughts on 1. Adding the above to the FILES section. 2. Remove the code from MAKEDEV that creates /dev/rsa* If it's OK, I'll go and commit. N -- Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. Telephone line, $24.95 a month. Software, free. USENET transmission, hundreds if not thousands of dollars. Thinking before posting, priceless. Somethings in life you can't buy. For everything else, there's MasterCard. -- Graham Reed, in the Scary Devil Monastery From: Rich Morin To: Nik Clayton Cc: FreeBSD-gnats-submit@freebsd.org, julian@freebsd.org, mjacob@freebsd.org Subject: Re: docs/24786: missing FILES descriptions in sa(4) Date: Fri, 9 Feb 2001 11:35:29 -0800 So I gather that the device is ALWAYS used in "raw" mode, so there is really no need for an explicit "r" designation. Getting rid of the "r" versions cleans things up a lot, so it works for me... Regarding the ".[0-3]" extensions, I am still perplexed. It sounds like the mode bits are overloaded with the [en] designations, as: /dev/sa0.0 Corresponds to sub-mode 00 (i.e., /dev/sa0) /dev/sa0.1 Corresponds to sub-mode 01 (i.e., /dev/nsa0) /dev/sa0.2 Corresponds to sub-mode 10 (i.e., /dev/esa0) But if that's true, I don't understand how there can be names such as ersa0.0. Finally, mode 3 is actually being created by MAKEDEV, but it is not mentioned as a possibility by the man page. What's going on? -r -- -- http://www.cfcl.com/rdm email: rdm@cfcl.com phone: +1 650-873-7841 From: Julian Elischer To: Nik Clayton Cc: Rich Morin , FreeBSD-gnats-submit@freebsd.org, julian@freebsd.org, mjacob@freebsd.org Subject: Re: docs/24786: missing FILES descriptions in sa(4) Date: Fri, 09 Feb 2001 11:44:06 -0800 Nik Clayton wrote: > > I'm copying Julian and Matt on this, who know more about this subsystem > than I do. > > On Thu, Feb 01, 2001 at 03:51:47PM -0800, Rich Morin wrote: > > >Number: 24786 > > >Category: docs > > >Synopsis: missing FILES descriptions in sa(4) > > <...> > > > The sa(4) man page neglects to give definitions for > > /dev/[en][r]sa0. > > Yes it does. > > The device name takes the form > > /dev/[n][e]sa[0-9] > > If it's just /dev/sa then the device will try and rewind the tape when > the device is closed. > > If there's a leading 'n' then the device will not be rewound. > > If there's a leading 'e' then the device will be ejected on close. > > So if your application opens /dev/nesa0, and then closes the device, the > tape will not be rewound, and the driver will tell the drive to eject > the tape. > > This is all in the FILES section. > > 'r' means 'raw', but that isn't used on FreeBSD any more. It looks as > if MAKEDEV wasn't updated to remove the code that creates the rsa* > devices. > > > It also fails to describe the meaning > > of the ".[0-3]" extensions (e.g., /dev/sa0.1). > > Covered in the SUB-MODES section in the man page (I think), although this is > somewhat cryptic. > > We could probably add something like > > /dev/sa0.0 Corresponds to sub-mode 00 > /dev/sa0.1 Corresponds to sub-mode 01 > /dev/sa0.2 Corresponds to sub-mode 10 > /dev/sa0.3 Corresponds to sub-mode 11 > > to the FILES section. > > Matt, Julian, any thoughts on > > 1. Adding the above to the FILES section. > > 2. Remove the code from MAKEDEV that creates /dev/rsa* > > If it's OK, I'll go and commit. OK by me, but I haven't been hearding that code for about 5 years :-) check who's doing all the commts therre these days... Probably Ken Merry there was also a control device that allowed you to set teh modes for each virtual device. I assume that's still documented correctly.. > > N > -- > Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. > Telephone line, $24.95 a month. Software, free. USENET transmission, > hundreds if not thousands of dollars. Thinking before posting, priceless. > Somethings in life you can't buy. For everything else, there's MasterCard. > -- Graham Reed, in the Scary Devil Monastery -- __--_|\ Julian Elischer / \ julian@elischer.org ( OZ ) World tour 2000-2001 ---> X_.---._/ v From: Julian Elischer To: Rich Morin Cc: Nik Clayton , FreeBSD-gnats-submit@freebsd.org, julian@freebsd.org, mjacob@freebsd.org Subject: Re: docs/24786: missing FILES descriptions in sa(4) Date: Fri, 09 Feb 2001 11:48:07 -0800 Rich Morin wrote: > > So I gather that the device is ALWAYS used in "raw" mode, so there > is really no need for an explicit "r" designation. Getting rid of > the "r" versions cleans things up a lot, so it works for me... > > Regarding the ".[0-3]" extensions, I am still perplexed. It sounds > like the mode bits are overloaded with the [en] designations, as: > > /dev/sa0.0 Corresponds to sub-mode 00 (i.e., /dev/sa0) > /dev/sa0.1 Corresponds to sub-mode 01 (i.e., /dev/nsa0) > /dev/sa0.2 Corresponds to sub-mode 10 (i.e., /dev/esa0) nope.. > > But if that's true, I don't understand how there can be names such as > ersa0.0. Finally, mode 3 is actually being created by MAKEDEV, but it > is not mentioned as a possibility by the man page. What's going on? I'm not sure if it's STILL true, but when I write it originally, the submodes were so that you could have a single device programmed up to use different block sizes and densities, and teh nyou could read/write tapes in those densities by just using the different subdevices. (e.g. .1 might write in 3K blocks and .2 might right in variable block mode) useful if you are distributing media to people with machines with different capabilities. > > -r > -- > -- > http://www.cfcl.com/rdm > email: rdm@cfcl.com > phone: +1 650-873-7841 -- __--_|\ Julian Elischer / \ julian@elischer.org ( OZ ) World tour 2000-2001 ---> X_.---._/ v From: Rich Morin To: Julian Elischer Cc: Nik Clayton , FreeBSD-gnats-submit@freebsd.org, mjacob@freebsd.org Subject: Re: docs/24786: missing FILES descriptions in sa(4) Date: Fri, 9 Feb 2001 13:09:43 -0800 At 11:48 AM -0800 2/9/01, Julian Elischer wrote: >I'm not sure if it's STILL true, but when I write it originally, >the submodes were so that you could have a single device programmed >up to use different block sizes and densities, and teh nyou could >read/write tapes in those densities by just using the different >subdevices. >(e.g. .1 might write in 3K blocks and .2 might right in variable >block mode) useful if you are distributing media to people with >machines with different capabilities. Well, that certainly isn't what the sa(4) man page says: SUB-MODES Bits 0 and 1 of the minor number are interpreted as `sub-modes'. The sub- modes differ in the action taken when the device is closed: 00 A close will rewind the device; if the tape has been written, then a file mark will be written before the rewind is requested. The device is unmounted. 01 A close will leave the tape mounted. If the tape was written to, a file mark will be written. No other head positioning takes place. Any further reads or writes will occur directly after the last read, or the written file mark. 10 A close will rewind the device. If the tape has been written, then a file mark will be written before the rewind is requested. On completion of the rewind an unload command will be issued. The de- vice is unmounted. FWIW, /usr/src/sys/cam/scsi/scsi_sa.c contains the code typedef enum { SA_MODE_REWIND = 0x00, SA_MODE_NOREWIND = 0x01, SA_MODE_OFFLINE = 0x02 } sa_mode; ... #define SAMODE(z) ((minor(z) & 0x3)) ... #define SA_NUM_MODES 4 struct sa_devs { dev_t ctl_dev; struct sa_mode_devs { dev_t r_dev; dev_t nr_dev; dev_t er_dev; } mode_devs[SA_NUM_MODES]; dev_t r_dev; dev_t nr_dev; dev_t er_dev; }; So, it _appears_ to me that the modes have been taken over to do the same things as the [en] flags. If this is the case, this seems a bit redundant. In any event, the true situation needs to be clarified. -r -- -- http://www.cfcl.com/rdm email: rdm@cfcl.com phone: +1 650-873-7841 >Unformatted: