[PATCH] Documentation/cdrom: update cdrom-standard.tex for kernel changes

[PATCH] Documentation/cdrom: update cdrom-standard.tex for kernel changes

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

Documentation updates for Documentation/cdrom/cdrom-standard.tex:

cdrom_device_ops:
- add check_events() and generic_packet()

cdrom_device_info:
- add one 'const' modifier
- correct some field descriptions
- add some missing fields
- drop 'kdev_t dev;' field

Also drop <n_discs> sentence from documentation because it is not
referenced anywhere in the kernel header or C files.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Jens, there are 2 fields in struct cdrom_device_info that I marked as
"unknown:TBD". Will you either update those short descriptions or give
me short descriptions that I can use there?  Thanks.

 Documentation/cdrom/cdrom-standard.tex |   29 +++++++++++++++--------
 1 file changed, 20 insertions(+), 9 deletions(-)

--- linux-next-20180126.orig/Documentation/cdrom/cdrom-standard.tex
+++ linux-next-20180126/Documentation/cdrom/cdrom-standard.tex
@@ -234,6 +234,7 @@ struct& cdrom_device_ops\ \{ \hidewidth\
   &int& (* open)(struct\ cdrom_device_info *, int)\cr
   &void& (* release)(struct\ cdrom_device_info *);\cr 
   &int& (* drive_status)(struct\ cdrom_device_info *, int);\cr     
+  &unsigned\ int& (* check_events)(struct\ cdrom_device_info *, unsigned\ int, int);\cr
   &int& (* media_changed)(struct\ cdrom_device_info *, int);\cr 
   &int& (* tray_move)(struct\ cdrom_device_info *, int);\cr
   &int& (* lock_door)(struct\ cdrom_device_info *, int);\cr
@@ -245,10 +246,9 @@ struct& cdrom_device_ops\ \{ \hidewidth\
   &int& (* reset)(struct\ cdrom_device_info *);\cr
   &int& (* audio_ioctl)(struct\ cdrom_device_info *, unsigned\ int, 
         void *{});\cr 
-  &int& (* dev_ioctl)(struct\ cdrom_device_info *, unsigned\ int, 
-        unsigned\ long);\cr
 \noalign{\medskip}
   &const\ int& capability;& capability flags \cr
+  &int& (* generic_packet)(struct\ cdrom_device_info *, struct\ packet_command *{});\cr
 \};\cr
 }
 $$
@@ -274,19 +274,32 @@ $$
 \halign{$#$\ \hfil&$#$\ \hfil&\hbox to 10em{$#$\hss}&
   $/*$ \rm# $*/$\hfil\cr
 struct& cdrom_device_info\ \{ \hidewidth\cr
-  & struct\ cdrom_device_ops *& ops;& device operations for this major\cr
-  & struct\ cdrom_device_info *& next;& next device_info for this major\cr
+  & const\ struct\ cdrom_device_ops *& ops;& device operations for this major\cr
+  & struct\ list_head& list;& linked list of all device_info\cr
+  & struct\ gendisk *& disk;& matching block layer disk\cr
   & void *&  handle;& driver-dependent data\cr
 \noalign{\medskip}
-  & kdev_t&  dev;& device number (incorporates minor)\cr
   & int& mask;& mask of capability: disables them \cr
   & int& speed;& maximum speed for reading data \cr
   & int& capacity;& number of discs in a jukebox \cr
 \noalign{\medskip}
-  &int& options : 30;& options flags \cr
+  &unsigned\ int& options : 30;& options flags \cr
   &unsigned& mc_flags : 2;& media-change buffer flags \cr
+  &unsigned\ int& vfs_events;& cached events for vfs path\cr
+  &unsigned\ int& ioctl_events;& cached events for ioctl path\cr
   & int& use_count;& number of times device is opened\cr
   & char& name[20];& name of the device type\cr
+\noalign{\medskip}
+  &__u8& sanyo_slot : 2;& Sanyo 3-CD changer support\cr
+  &__u8& keeplocked : 1;& CDROM_LOCKDOOR status\cr
+  &__u8& reserved : 5;& not used yet\cr
+  & int& cdda_method;& see CDDA_* flags\cr
+  &__u8& last_sense;& saves last sense key\cr
+  &__u8& media_written;& dirty flag, DVD+RW bookkeeping\cr
+  &unsigned\ short& mmc3_profile;& current MMC3 profile\cr
+  & int& for_data;& unknown:TBD\cr
+  & int\ (* exit)\ (struct\ cdrom_device_info *);&& unknown:TBD\cr
+  & int& mrw_mode_page;& which MRW mode page is in use\cr
 \}\cr
 }$$
 Using this $struct$, a linked list of the registered minor devices is
@@ -298,9 +311,7 @@ The $mask$ flags can be used to mask out
 in $ops\to capability$, if a specific drive doesn't support a feature
 of the driver. The value $speed$ specifies the maximum head-rate of the
 drive, measured in units of normal audio speed (176\,kB/sec raw data or
-150\,kB/sec file system data). The value $n_discs$ should reflect the
-number of discs the drive can hold simultaneously, if it is designed
-as a juke-box, or otherwise~1. The parameters are declared $const$
+150\,kB/sec file system data).  The parameters are declared $const$
 because they describe properties of the drive, which don't change after
 registration.
 

Re: [PATCH] Documentation/cdrom: update cdrom-standard.tex for kernel changes

[Jens Axboe]

On 1/26/18 8:58 PM, Randy Dunlap wrote:
> From: Randy Dunlap <rdunlap@infradead.org>
> 
> Documentation updates for Documentation/cdrom/cdrom-standard.tex:
> 
> cdrom_device_ops:
> - add check_events() and generic_packet()
> 
> cdrom_device_info:
> - add one 'const' modifier
> - correct some field descriptions
> - add some missing fields
> - drop 'kdev_t dev;' field
> 
> Also drop <n_discs> sentence from documentation because it is not
> referenced anywhere in the kernel header or C files.

Applied, thanks.

-- 
Jens Axboe