Bug 24786
| Summary: | missing FILES descriptions in sa(4) | ||
|---|---|---|---|
| Product: | Documentation | Reporter: | rdm <rdm> |
| Component: | Manual Pages | Assignee: | freebsd-bugs (Nobody) <bugs> |
| Status: | Closed Overcome By Events | ||
| Severity: | Affects Only Me | CC: | doc, gonzo |
| Priority: | Normal | ||
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
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 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
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 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 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 For bugs matching the following criteria: Status: In Progress Changed: (is less than) 2014-06-01 Reset to default assignee and clear in-progress tags. Mail being skipped Closing as "Overcome by events" since mode devices were removed in r279219: o The extra sa(4) /dev entries (/dev/saN.[0-3]) have been removed. The extra devices were originally added as place holders for density-specific device nodes. Some OSes (NetBSD, NetApp's OnTap and Solaris) have had device nodes that, when you write to them, will automatically select a given density for particular tape drives. This is a convenient way of switching densities, but it was never implemented in FreeBSD. Only the device nodes were there, and that sometimes confused users. For modern tape devices, the density is generally not selectable (e.g. with LTO) or defaults to the highest availble density when the tape is rewritten from BOT (e.g. TS11X0). So, for most users, density selection won't be necessary. If they do need to select the density, it is easy enough to use 'mt density' to change it. |
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). 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! How-To-Repeat: man 4 sa