gigaset: documentation amendments

Various additions and improvements to the Gigaset driver's README file, and added comments to its userspace visible include file. Signed-off-by: Tilman Schmidt <tilman@imap.cc> Signed-off-by: David S. Miller <davem@davemloft.net>

gigaset: documentation amendments
Various additions and improvements to the Gigaset driver's README file, and added comments to its userspace visible include file. Signed-off-by: Tilman Schmidt <tilman@imap.cc> Signed-off-by: David S. Miller <davem@davemloft.net>
Tilman Schmidt · David S. Miller
1 parent 073886ff23
Showing 2 changed files with 106 additions and 32 deletions Side-by-side Diff
Documentation/isdn/README.gigaset
include/linux/gigaset_dev.h
@@ -68,22 +68,38 @@
      for troubleshooting or to pass module parameters.
  
      The module ser_gigaset provides a serial line discipline N_GIGASET_M101
-     which drives the device through the regular serial line driver. It must
-     be attached to the serial line to which the M101 is connected with the
-     ldattach(8) command (requires util-linux-ng release 2.14 or later), for
-     example:
-	 ldattach GIGASET_M101 /dev/ttyS1
+     which uses the regular serial port driver to access the device, and must
+     therefore be attached to the serial device to which the M101 is connected.
+     The ldattach(8) command (included in util-linux-ng release 2.14 or later)
+     can be used for that purpose, for example:
+	ldattach GIGASET_M101 /dev/ttyS1
      This will open the device file, attach the line discipline to it, and
      then sleep in the background, keeping the device open so that the line
      discipline remains active. To deactivate it, kill the daemon, for example
      with
-	 killall ldattach
+	killall ldattach
      before disconnecting the device. To have this happen automatically at
      system startup/shutdown on an LSB compatible system, create and activate
      an appropriate LSB startup script /etc/init.d/gigaset. (The init name
      'gigaset' is officially assigned to this project by LANANA.)
      Alternatively, just add the 'ldattach' command line to /etc/rc.local.
  
+     The modules accept the following parameters:
+
+	Module	 	Parameter  Meaning
+
+	gigaset	 	debug	   debug level (see section 3.2.)
+
+			startmode  initial operation mode (see section 2.5.):
+	bas_gigaset )		   1=ISDN4linux/CAPI (default), 0=Unimodem
+	ser_gigaset )
+	usb_gigaset )	cidmode    initial Call-ID mode setting (see section
+				   2.5.): 1=on (default), 0=off
+
+     Depending on your distribution you may want to create a separate module
+     configuration file /etc/modprobe.d/gigaset for these, or add them to a
+     custom file like /etc/modprobe.conf.local.
+
 2.2. Device nodes for user space programs
      ------------------------------------
      The device can be accessed from user space (eg. by the user space tools
  
  
@@ -93,12 +109,49 @@
      - /dev/ttyGU0 for M105 (USB data boxes)
      - /dev/ttyGB0 for the base driver (direct USB connection)
  
-     You can also select a "default device" which is used by the frontends when
+     If you connect more than one device of a type, they will get consecutive
+     device nodes, eg. /dev/ttyGU1 for a second M105.
+
+     You can also set a "default device" for the user space tools to use when
      no device node is given as parameter, by creating a symlink /dev/ttyG to
      one of them, eg.:
  
-        ln -s /dev/ttyGB0 /dev/ttyG
+	ln -s /dev/ttyGB0 /dev/ttyG
  
+     The devices accept the following device specific ioctl calls
+     (defined in gigaset_dev.h):
+
+     ioctl(int fd, GIGASET_REDIR, int *cmd);
+     If cmd==1, the device is set to be controlled exclusively through the
+     character device node; access from the ISDN subsystem is blocked.
+     If cmd==0, the device is set to be used from the ISDN subsystem and does
+     not communicate through the character device node.
+
+     ioctl(int fd, GIGASET_CONFIG, int *cmd);
+     (ser_gigaset and usb_gigaset only)
+     If cmd==1, the device is set to adapter configuration mode where commands
+     are interpreted by the M10x DECT adapter itself instead of being
+     forwarded to the base station. In this mode, the device accepts the
+     commands described in Siemens document "AT-Kommando Alignment M10x Data"
+     for setting the operation mode, associating with a base station and
+     querying parameters like field strengh and signal quality.
+     Note that there is no ioctl command for leaving adapter configuration
+     mode and returning to regular operation. In order to leave adapter
+     configuration mode, write the command ATO to the device.
+
+     ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);
+     (usb_gigaset only)
+     Set the break characters on an M105's internal serial adapter to the six
+     bytes stored in brkchars[]. Unused bytes should be set to zero.
+
+     ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
+     Retrieve version information from the driver. version[0] must be set to
+     one of:
+     - GIGVER_DRIVER: retrieve driver version
+     - GIGVER_COMPAT: retrieve interface compatibility version
+     - GIGVER_FWBASE: retrieve the firmware version of the base
+     Upon return, version[] is filled with the requested version information.
+
 2.3. ISDN4linux
      ----------
      This is the "normal" mode of operation. After loading the module you can
  
  
  
@@ -113,16 +166,25 @@
          Connection State: 0, Response: -1
          gigaset_process_response: resp_code -1 in ConState 0 !
          Timeout occurred
-     you might need to use unimodem mode. (see section 2.5.)
+     you probably need to use unimodem mode. (see section 2.5.)
  
 2.4. CAPI
      ----
      If the driver is compiled with CAPI support (kernel configuration option
      GIGASET_CAPI, experimental) it can also be used with CAPI 2.0 kernel and
-     user space applications.  ISDN4Linux is supported in this configuration
+     user space applications. For user space access, the module capi.ko must
+     be loaded. The capiinit command (included in the capi4k-utils package)
+     does this for you.
+
+     The CAPI variant of the driver supports legacy ISDN4Linux applications
      via the capidrv compatibility driver. The kernel module capidrv.ko must
-     be loaded explicitly ("modprobe capidrv") if needed.
+     be loaded explicitly with the command
+        modprobe capidrv
+     if needed, and cannot be unloaded again without unloading the driver
+     first. (These are limitations of capidrv.)
  
+     The note about unimodem mode in the preceding section applies here, too.
+
 2.5. Unimodem mode
      -------------
      This is needed for some devices [e.g. SX100] as they have problems with
@@ -134,9 +196,14 @@
      You can switch back using
          gigacontr --mode isdn
  
-     You can also load the driver using e.g.
-         modprobe usb_gigaset startmode=0
-     to prevent the driver from starting in "isdn4linux mode".
+     You can also put the driver directly into Unimodem mode when it's loaded,
+     by passing the module parameter startmode=0 to the hardware specific
+     module, e.g.
+	modprobe usb_gigaset startmode=0
+     or by adding a line like
+	options usb_gigaset startmode=0
+     to an appropriate module configuration file, like /etc/modprobe.d/gigaset
+     or /etc/modprobe.conf.local.
  
      In this mode the device works like a modem connected to a serial port
      (the /dev/ttyGU0, ... mentioned above) which understands the commands
@@ -164,9 +231,8 @@
  
         options ppp_async flag_time=0
  
-     to /etc/modprobe.conf. If your distribution has some local module
-     configuration file like /etc/modprobe.conf.local,
-     using that should be preferred.
+     to an appropriate module configuration file, like /etc/modprobe.d/gigaset
+     or /etc/modprobe.conf.local.
  
 2.6. Call-ID (CID) mode
      ------------------
  
@@ -189,12 +255,13 @@
        settings (CID mode).
      - If you have several DECT data devices (M10x) which you want to use
        in turn, select Unimodem mode by passing the parameter "cidmode=0" to
-       the driver ("modprobe usb_gigaset cidmode=0" or modprobe.conf).
+       the appropriate driver module (ser_gigaset or usb_gigaset).
  
      If you want both of these at once, you are out of luck.
  
-     You can also use /sys/class/tty/ttyGxy/cidmode for changing the CID mode
-     setting (ttyGxy is ttyGU0 or ttyGB0).
+     You can also use the tty class parameter "cidmode" of the device to
+     change its CID mode while the driver is loaded, eg.
+        echo 0 > /sys/class/tty/ttyGU0/cidmode
  
 2.7. Unregistered Wireless Devices (M101/M105)
      -----------------------------------------
@@ -208,7 +275,7 @@
      driver. In that situation, a restricted set of functions is available
      which includes, in particular, those necessary for registering the device
      to a base or for switching it between Fixed Part and Portable Part
-     modes.
+     modes. See the gigacontr(8) manpage for details.
  
 3.   Troubleshooting
      ---------------
@@ -222,9 +289,7 @@
  
            options isdn dialtimeout=15
  
-        to /etc/modprobe.conf. If your distribution has some local module
-        configuration file like /etc/modprobe.conf.local,
-        using that should be preferred.
+        to /etc/modprobe.d/gigaset, /etc/modprobe.conf.local or a similar file.
  
      Problem:
         Your isdn script aborts with a message about isdnlog.
@@ -264,7 +329,8 @@
      The initial value can be set using the debug parameter when loading the
      module "gigaset", e.g. by adding a line
         options gigaset debug=0
-     to /etc/modprobe.conf, ...
+     to your module configuration file, eg. /etc/modprobe.d/gigaset or
+     /etc/modprobe.conf.local.
  
      Generated debugging information can be found
      - as output of the command
@@ -16,16 +16,24 @@
  
 #include <linux/ioctl.h>
  
+/* The magic IOCTL value for this interface. */
 #define GIGASET_IOCTL 0x47
  
-#define GIGVER_DRIVER 0
-#define GIGVER_COMPAT 1
-#define GIGVER_FWBASE 2
+/* enable/disable device control via character device (lock out ISDN subsys) */
+#define GIGASET_REDIR    _IOWR(GIGASET_IOCTL, 0, int)
  
-#define GIGASET_REDIR    _IOWR (GIGASET_IOCTL, 0, int)
-#define GIGASET_CONFIG   _IOWR (GIGASET_IOCTL, 1, int)
-#define GIGASET_BRKCHARS _IOW  (GIGASET_IOCTL, 2, unsigned char[6]) //FIXME [6] okay?
-#define GIGASET_VERSION  _IOWR (GIGASET_IOCTL, 3, unsigned[4])
+/* enable adapter configuration mode (M10x only) */
+#define GIGASET_CONFIG   _IOWR(GIGASET_IOCTL, 1, int)
+
+/* set break characters (M105 only) */
+#define GIGASET_BRKCHARS _IOW(GIGASET_IOCTL, 2, unsigned char[6])
+
+/* get version information selected by arg[0] */
+#define GIGASET_VERSION  _IOWR(GIGASET_IOCTL, 3, unsigned[4])
+/* values for GIGASET_VERSION arg[0] */
+#define GIGVER_DRIVER 0		/* get driver version */
+#define GIGVER_COMPAT 1		/* get interface compatibility version */
+#define GIGVER_FWBASE 2		/* get base station firmware version */
  
 #endif
...	...	@@ -68,22 +68,38 @@
68	68	for troubleshooting or to pass module parameters.
69	69
70	70	The module ser_gigaset provides a serial line discipline N_GIGASET_M101
71		- which drives the device through the regular serial line driver. It must
72		- be attached to the serial line to which the M101 is connected with the
73		- ldattach(8) command (requires util-linux-ng release 2.14 or later), for
74		- example:
75		- ldattach GIGASET_M101 /dev/ttyS1
	71	+ which uses the regular serial port driver to access the device, and must
	72	+ therefore be attached to the serial device to which the M101 is connected.
	73	+ The ldattach(8) command (included in util-linux-ng release 2.14 or later)
	74	+ can be used for that purpose, for example:
	75	+ ldattach GIGASET_M101 /dev/ttyS1
76	76	This will open the device file, attach the line discipline to it, and
77	77	then sleep in the background, keeping the device open so that the line
78	78	discipline remains active. To deactivate it, kill the daemon, for example
79	79	with
80		- killall ldattach
	80	+ killall ldattach
81	81	before disconnecting the device. To have this happen automatically at
82	82	system startup/shutdown on an LSB compatible system, create and activate
83	83	an appropriate LSB startup script /etc/init.d/gigaset. (The init name
84	84	'gigaset' is officially assigned to this project by LANANA.)
85	85	Alternatively, just add the 'ldattach' command line to /etc/rc.local.
86	86
	87	+ The modules accept the following parameters:
	88	+
	89	+ Module Parameter Meaning
	90	+
	91	+ gigaset debug debug level (see section 3.2.)
	92	+
	93	+ startmode initial operation mode (see section 2.5.):
	94	+ bas_gigaset ) 1=ISDN4linux/CAPI (default), 0=Unimodem
	95	+ ser_gigaset )
	96	+ usb_gigaset ) cidmode initial Call-ID mode setting (see section
	97	+ 2.5.): 1=on (default), 0=off
	98	+
	99	+ Depending on your distribution you may want to create a separate module
	100	+ configuration file /etc/modprobe.d/gigaset for these, or add them to a
	101	+ custom file like /etc/modprobe.conf.local.
	102	+
87	103	2.2. Device nodes for user space programs
88	104	------------------------------------
89	105	The device can be accessed from user space (eg. by the user space tools
90	106
91	107
...	...	@@ -93,12 +109,49 @@
93	109	- /dev/ttyGU0 for M105 (USB data boxes)
94	110	- /dev/ttyGB0 for the base driver (direct USB connection)
95	111
96		- You can also select a "default device" which is used by the frontends when
	112	+ If you connect more than one device of a type, they will get consecutive
	113	+ device nodes, eg. /dev/ttyGU1 for a second M105.
	114	+
	115	+ You can also set a "default device" for the user space tools to use when
97	116	no device node is given as parameter, by creating a symlink /dev/ttyG to
98	117	one of them, eg.:
99	118
100		- ln -s /dev/ttyGB0 /dev/ttyG
	119	+ ln -s /dev/ttyGB0 /dev/ttyG
101	120
	121	+ The devices accept the following device specific ioctl calls
	122	+ (defined in gigaset_dev.h):
	123	+
	124	+ ioctl(int fd, GIGASET_REDIR, int *cmd);
	125	+ If cmd==1, the device is set to be controlled exclusively through the
	126	+ character device node; access from the ISDN subsystem is blocked.
	127	+ If cmd==0, the device is set to be used from the ISDN subsystem and does
	128	+ not communicate through the character device node.
	129	+
	130	+ ioctl(int fd, GIGASET_CONFIG, int *cmd);
	131	+ (ser_gigaset and usb_gigaset only)
	132	+ If cmd==1, the device is set to adapter configuration mode where commands
	133	+ are interpreted by the M10x DECT adapter itself instead of being
	134	+ forwarded to the base station. In this mode, the device accepts the
	135	+ commands described in Siemens document "AT-Kommando Alignment M10x Data"
	136	+ for setting the operation mode, associating with a base station and
	137	+ querying parameters like field strengh and signal quality.
	138	+ Note that there is no ioctl command for leaving adapter configuration
	139	+ mode and returning to regular operation. In order to leave adapter
	140	+ configuration mode, write the command ATO to the device.
	141	+
	142	+ ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);
	143	+ (usb_gigaset only)
	144	+ Set the break characters on an M105's internal serial adapter to the six
	145	+ bytes stored in brkchars[]. Unused bytes should be set to zero.
	146	+
	147	+ ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
	148	+ Retrieve version information from the driver. version[0] must be set to
	149	+ one of:
	150	+ - GIGVER_DRIVER: retrieve driver version
	151	+ - GIGVER_COMPAT: retrieve interface compatibility version
	152	+ - GIGVER_FWBASE: retrieve the firmware version of the base
	153	+ Upon return, version[] is filled with the requested version information.
	154	+
102	155	2.3. ISDN4linux
103	156	----------
104	157	This is the "normal" mode of operation. After loading the module you can
105	158
106	159
107	160
...	...	@@ -113,16 +166,25 @@
113	166	Connection State: 0, Response: -1
114	167	gigaset_process_response: resp_code -1 in ConState 0 !
115	168	Timeout occurred
116		- you might need to use unimodem mode. (see section 2.5.)
	169	+ you probably need to use unimodem mode. (see section 2.5.)
117	170
118	171	2.4. CAPI
119	172	----
120	173	If the driver is compiled with CAPI support (kernel configuration option
121	174	GIGASET_CAPI, experimental) it can also be used with CAPI 2.0 kernel and
122		- user space applications. ISDN4Linux is supported in this configuration
	175	+ user space applications. For user space access, the module capi.ko must
	176	+ be loaded. The capiinit command (included in the capi4k-utils package)
	177	+ does this for you.
	178	+
	179	+ The CAPI variant of the driver supports legacy ISDN4Linux applications
123	180	via the capidrv compatibility driver. The kernel module capidrv.ko must
124		- be loaded explicitly ("modprobe capidrv") if needed.
	181	+ be loaded explicitly with the command
	182	+ modprobe capidrv
	183	+ if needed, and cannot be unloaded again without unloading the driver
	184	+ first. (These are limitations of capidrv.)
125	185
	186	+ The note about unimodem mode in the preceding section applies here, too.
	187	+
126	188	2.5. Unimodem mode
127	189	-------------
128	190	This is needed for some devices [e.g. SX100] as they have problems with
...	...	@@ -134,9 +196,14 @@
134	196	You can switch back using
135	197	gigacontr --mode isdn
136	198
137		- You can also load the driver using e.g.
138		- modprobe usb_gigaset startmode=0
139		- to prevent the driver from starting in "isdn4linux mode".
	199	+ You can also put the driver directly into Unimodem mode when it's loaded,
	200	+ by passing the module parameter startmode=0 to the hardware specific
	201	+ module, e.g.
	202	+ modprobe usb_gigaset startmode=0
	203	+ or by adding a line like
	204	+ options usb_gigaset startmode=0
	205	+ to an appropriate module configuration file, like /etc/modprobe.d/gigaset
	206	+ or /etc/modprobe.conf.local.
140	207
141	208	In this mode the device works like a modem connected to a serial port
142	209	(the /dev/ttyGU0, ... mentioned above) which understands the commands
...	...	@@ -164,9 +231,8 @@
164	231
165	232	options ppp_async flag_time=0
166	233
167		- to /etc/modprobe.conf. If your distribution has some local module
168		- configuration file like /etc/modprobe.conf.local,
169		- using that should be preferred.
	234	+ to an appropriate module configuration file, like /etc/modprobe.d/gigaset
	235	+ or /etc/modprobe.conf.local.
170	236
171	237	2.6. Call-ID (CID) mode
172	238	------------------
173	239
...	...	@@ -189,12 +255,13 @@
189	255	settings (CID mode).
190	256	- If you have several DECT data devices (M10x) which you want to use
191	257	in turn, select Unimodem mode by passing the parameter "cidmode=0" to
192		- the driver ("modprobe usb_gigaset cidmode=0" or modprobe.conf).
	258	+ the appropriate driver module (ser_gigaset or usb_gigaset).
193	259
194	260	If you want both of these at once, you are out of luck.
195	261
196		- You can also use /sys/class/tty/ttyGxy/cidmode for changing the CID mode
197		- setting (ttyGxy is ttyGU0 or ttyGB0).
	262	+ You can also use the tty class parameter "cidmode" of the device to
	263	+ change its CID mode while the driver is loaded, eg.
	264	+ echo 0 > /sys/class/tty/ttyGU0/cidmode
198	265
199	266	2.7. Unregistered Wireless Devices (M101/M105)
200	267	-----------------------------------------
...	...	@@ -208,7 +275,7 @@
208	275	driver. In that situation, a restricted set of functions is available
209	276	which includes, in particular, those necessary for registering the device
210	277	to a base or for switching it between Fixed Part and Portable Part
211		- modes.
	278	+ modes. See the gigacontr(8) manpage for details.
212	279
213	280	3. Troubleshooting
214	281	---------------
...	...	@@ -222,9 +289,7 @@
222	289
223	290	options isdn dialtimeout=15
224	291
225		- to /etc/modprobe.conf. If your distribution has some local module
226		- configuration file like /etc/modprobe.conf.local,
227		- using that should be preferred.
	292	+ to /etc/modprobe.d/gigaset, /etc/modprobe.conf.local or a similar file.
228	293
229	294	Problem:
230	295	Your isdn script aborts with a message about isdnlog.
...	...	@@ -264,7 +329,8 @@
264	329	The initial value can be set using the debug parameter when loading the
265	330	module "gigaset", e.g. by adding a line
266	331	options gigaset debug=0
267		- to /etc/modprobe.conf, ...
	332	+ to your module configuration file, eg. /etc/modprobe.d/gigaset or
	333	+ /etc/modprobe.conf.local.
268	334
269	335	Generated debugging information can be found
270	336	- as output of the command
...	...	@@ -16,16 +16,24 @@
16	16
17	17	#include <linux/ioctl.h>
18	18
	19	+/* The magic IOCTL value for this interface. */
19	20	#define GIGASET_IOCTL 0x47
20	21
21		-#define GIGVER_DRIVER 0
22		-#define GIGVER_COMPAT 1
23		-#define GIGVER_FWBASE 2
	22	+/* enable/disable device control via character device (lock out ISDN subsys) */
	23	+#define GIGASET_REDIR _IOWR(GIGASET_IOCTL, 0, int)
24	24
25		-#define GIGASET_REDIR _IOWR (GIGASET_IOCTL, 0, int)
26		-#define GIGASET_CONFIG _IOWR (GIGASET_IOCTL, 1, int)
27		-#define GIGASET_BRKCHARS _IOW (GIGASET_IOCTL, 2, unsigned char[6]) //FIXME [6] okay?
28		-#define GIGASET_VERSION _IOWR (GIGASET_IOCTL, 3, unsigned[4])
	25	+/* enable adapter configuration mode (M10x only) */
	26	+#define GIGASET_CONFIG _IOWR(GIGASET_IOCTL, 1, int)
	27	+
	28	+/* set break characters (M105 only) */
	29	+#define GIGASET_BRKCHARS _IOW(GIGASET_IOCTL, 2, unsigned char[6])
	30	+
	31	+/* get version information selected by arg[0] */
	32	+#define GIGASET_VERSION _IOWR(GIGASET_IOCTL, 3, unsigned[4])
	33	+/* values for GIGASET_VERSION arg[0] */
	34	+#define GIGVER_DRIVER 0 /* get driver version */
	35	+#define GIGVER_COMPAT 1 /* get interface compatibility version */
	36	+#define GIGVER_FWBASE 2 /* get base station firmware version */
29	37
30	38	#endif