/share/man/man4/man4.i386/mse.4

https://bitbucket.org/freebsd/freebsd-head/ · Forth · 385 lines · 385 code · 0 blank · 0 comment · 15 complexity · 1028bc87a1d80b78bdaa3bc0550c001e MD5 · raw file

  1. .\" Copyright 1992 by the University of Guelph
  2. .\"
  3. .\" Permission to use, copy and modify this
  4. .\" software and its documentation for any purpose and without
  5. .\" fee is hereby granted, provided that the above copyright
  6. .\" notice appear in all copies and that both that copyright
  7. .\" notice and this permission notice appear in supporting
  8. .\" documentation.
  9. .\" University of Guelph makes no representations about the suitability of
  10. .\" this software for any purpose. It is provided "as is"
  11. .\" without express or implied warranty.
  12. .\"
  13. .\" $FreeBSD$
  14. .\"
  15. .Dd December 3, 1997
  16. .Dt MSE 4 i386
  17. .Os
  18. .Sh NAME
  19. .Nm mse
  20. .Nd bus and InPort mice driver
  21. .Sh SYNOPSIS
  22. .\" .Cd "options MSE_XXX=N"
  23. .Cd "device mse"
  24. .Pp
  25. In
  26. .Pa /boot/device.hints :
  27. .Cd hint.mse.0.at="isa"
  28. .Cd hint.mse.0.port="0x23c"
  29. .Cd hint.mse.0.irq="5"
  30. .Sh DESCRIPTION
  31. The
  32. .Nm
  33. driver provides support for the bus mouse and the InPort mouse, which
  34. are often collectively called ``bus'' mice, as these mice are sold with
  35. an interface card which needs to be installed in an expansion bus slot.
  36. The interface circuit may come on an integrated I/O card or as an option
  37. on video cards.
  38. .Pp
  39. The bus and InPort mice have two or three buttons,
  40. and a D-sub 9-pin male connector or a round DIN 9-pin
  41. male connector.
  42. .Pp
  43. The primary port address of the bus and InPort mouse interface cards
  44. is usually 0x23c.
  45. Some cards may also be set to use the secondary port
  46. address at 0x238.
  47. The interface cards require a single IRQ, which may be
  48. 2, 3, 4 or 5.
  49. Some cards may offer additional IRQs.
  50. The port number and the IRQ number are configured by jumpers on the cards
  51. or by software provided with the card.
  52. .Pp
  53. Frequency, or report rate, at which the device sends movement
  54. and button state reports to the host system, may also be configurable on
  55. some interface cards.
  56. It may be 15, 30, 60 or 120Hz.
  57. .Pp
  58. The difference between the two types of the mice is not in mouse devices
  59. (in fact they are exactly the same).
  60. But in the circuit on the interface
  61. cards.
  62. This means that the device from a bus mouse package can be
  63. connected to the interface card from an InPort mouse package, or vice
  64. versa, provided that their connectors match.
  65. .Ss Operation Levels
  66. The
  67. .Nm
  68. driver has two levels of operation.
  69. The current operation level can be set via an ioctl call.
  70. .Pp
  71. At the level zero the basic support is provided; the device driver will report
  72. horizontal and vertical movement of the attached device
  73. and state of up to three buttons in the format described below.
  74. It is a subset of the MouseSystems protocol.
  75. .Pp
  76. .Bl -tag -width Byte_1 -compact
  77. .It Byte 1
  78. .Bl -tag -width bit_7 -compact
  79. .It bit 7
  80. Always one.
  81. .It bit 6..3
  82. Always zero.
  83. .It bit 2
  84. Left button status; cleared if pressed, otherwise set.
  85. .It bit 1
  86. Middle button status; cleared if pressed, otherwise set.
  87. Always one,
  88. if the device does not have the middle button.
  89. .It bit 0
  90. Right button status; cleared if pressed, otherwise set.
  91. .El
  92. .It Byte 2
  93. Horizontal movement count in two's compliment; -128 through 127.
  94. .It Byte 3
  95. Vertical movement count in two's compliment; -128 through 127.
  96. .It Byte 4
  97. Always zero.
  98. .It Byte 5
  99. Always zero.
  100. .El
  101. .Pp
  102. This is the default level of operation and the driver is initially
  103. at this level when opened by the user program.
  104. .Pp
  105. At the operation level one (extended level), a data packet is encoded
  106. in the standard format
  107. .Dv MOUSE_PROTO_SYSMOUSE
  108. as defined in
  109. .Xr mouse 4 .
  110. .Ss Acceleration
  111. The
  112. .Nm
  113. driver can somewhat `accelerate' the movement of the pointing device.
  114. The faster you move the device, the further the pointer
  115. travels on the screen.
  116. The driver has an internal variable which governs the effect of
  117. the acceleration.
  118. Its value can be modified via the driver flag
  119. or via an ioctl call.
  120. .Ss Device Number
  121. The minor device number of the
  122. .Nm
  123. is made up of:
  124. .Bd -literal -offset indent
  125. minor = (`unit' << 1) | `non-blocking'
  126. .Ed
  127. .Pp
  128. where `unit' is the device number (usually 0) and the `non-blocking' bit
  129. is set to indicate ``do not block waiting for mouse input,
  130. return immediately''.
  131. The `non-blocking' bit should be set for \fIXFree86\fP,
  132. therefore the minor device number usually used for \fIXFree86\fP is 1.
  133. See
  134. .Sx FILES
  135. for device node names.
  136. .Sh DRIVER CONFIGURATION
  137. .\" .Ss Kernel Configuration Options
  138. .Ss Driver Flags
  139. The
  140. .Nm
  141. driver accepts the following driver flag.
  142. Set it in the
  143. kernel configuration file
  144. (see
  145. .Xr config 8 )
  146. or in the User Configuration Menu at
  147. the boot time
  148. (see
  149. .Xr boot 8 ) .
  150. .Bl -tag -width MOUSE
  151. .It bit 4..7 ACCELERATION
  152. This flag controls the amount of acceleration effect.
  153. The smaller the value of this flag is, more sensitive the movement becomes.
  154. The minimum value allowed, thus the value for the most sensitive setting,
  155. is one.
  156. Setting this flag to zero will completely disables the
  157. acceleration effect.
  158. .El
  159. .Sh IOCTLS
  160. There are a few
  161. .Xr ioctl 2
  162. commands for mouse drivers.
  163. These commands and related structures and constants are defined in
  164. .In sys/mouse.h .
  165. General description of the commands is given in
  166. .Xr mouse 4 .
  167. This section explains the features specific to the
  168. .Nm
  169. driver.
  170. .Pp
  171. .Bl -tag -width MOUSE -compact
  172. .It Dv MOUSE_GETLEVEL Ar int *level
  173. .It Dv MOUSE_SETLEVEL Ar int *level
  174. These commands manipulate the operation level of the
  175. .Nm
  176. driver.
  177. .Pp
  178. .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
  179. Returns the hardware information of the attached device in the following
  180. structure.
  181. Only the
  182. .Dv iftype
  183. field is guaranteed to be filled with the correct value by the current
  184. version of the
  185. .Nm
  186. driver.
  187. .Bd -literal
  188. typedef struct mousehw {
  189. int buttons; /* number of buttons */
  190. int iftype; /* I/F type */
  191. int type; /* mouse/track ball/pad... */
  192. int model; /* I/F dependent model ID */
  193. int hwid; /* I/F dependent hardware ID */
  194. } mousehw_t;
  195. .Ed
  196. .Pp
  197. The
  198. .Dv buttons
  199. field holds the number of buttons on the device.
  200. .Pp
  201. The
  202. .Dv iftype
  203. is either
  204. .Dv MOUSE_IF_BUS
  205. or
  206. .Dv MOUSE_IF_INPORT .
  207. .Pp
  208. The
  209. .Dv type
  210. may be
  211. .Dv MOUSE_MOUSE ,
  212. .Dv MOUSE_TRACKBALL ,
  213. .Dv MOUSE_STICK ,
  214. .Dv MOUSE_PAD ,
  215. or
  216. .Dv MOUSE_UNKNOWN .
  217. .Pp
  218. The
  219. .Dv model
  220. is always
  221. .Dv MOUSE_MODEL_GENERIC
  222. at the operation level 0.
  223. It may be
  224. .Dv MOUSE_MODEL_GENERIC
  225. or one of
  226. .Dv MOUSE_MODEL_XXX
  227. constants at higher operation levels.
  228. .Pp
  229. The
  230. .Dv hwid
  231. is always 0.
  232. .Pp
  233. .It Dv MOUSE_GETMODE Ar mousemode_t *mode
  234. The command gets the current operation parameters of the mouse
  235. driver.
  236. .Bd -literal
  237. typedef struct mousemode {
  238. int protocol; /* MOUSE_PROTO_XXX */
  239. int rate; /* report rate (per sec), -1 if unknown */
  240. int resolution; /* MOUSE_RES_XXX, -1 if unknown */
  241. int accelfactor; /* acceleration factor */
  242. int level; /* driver operation level */
  243. int packetsize; /* the length of the data packet */
  244. unsigned char syncmask[2]; /* sync. bits */
  245. } mousemode_t;
  246. .Ed
  247. .Pp
  248. The
  249. .Dv protocol
  250. is either
  251. .Dv MOUSE_PROTO_BUS
  252. or
  253. .Dv MOUSE_PROTO_INPORT
  254. at the operation level zero.
  255. .Dv MOUSE_PROTO_SYSMOUSE
  256. at the operation level one.
  257. .Pp
  258. The
  259. .Dv rate
  260. is the status report rate (reports/sec) at which the device will send
  261. movement report to the host computer.
  262. As there is no standard to detect the current setting,
  263. this field is always set to -1.
  264. .Pp
  265. The
  266. .Dv resolution
  267. is always set to -1.
  268. .Pp
  269. The
  270. .Dv accelfactor
  271. field holds a value to control acceleration feature
  272. (see
  273. .Sx Acceleration ) .
  274. It is zero or greater.
  275. If it is zero, acceleration is disabled.
  276. .Pp
  277. The
  278. .Dv packetsize
  279. field specifies the length of the data packet.
  280. It depends on the
  281. operation level.
  282. .Pp
  283. .Bl -tag -width level_0__ -compact
  284. .It Em level 0
  285. 5 bytes
  286. .It Em level 1
  287. 8 bytes
  288. .El
  289. .Pp
  290. The array
  291. .Dv syncmask
  292. holds a bit mask and pattern to detect the first byte of the
  293. data packet.
  294. .Dv syncmask[0]
  295. is the bit mask to be ANDed with a byte.
  296. If the result is equal to
  297. .Dv syncmask[1] ,
  298. the byte is likely to be the first byte of the data packet.
  299. Note that this detection method is not 100% reliable,
  300. thus, should be taken only as an advisory measure.
  301. .Pp
  302. Only
  303. .Dv level
  304. and
  305. .Dv accelfactor
  306. are modifiable by the
  307. .Dv MOUSE_SETMODE
  308. command.
  309. Changing the other field does not cause error, but has no effect.
  310. .Pp
  311. .It Dv MOUSE_SETMODE Ar mousemode_t *mode
  312. The command changes the current operation parameters of the mouse driver
  313. as specified in
  314. .Ar mode .
  315. Only
  316. .Dv level
  317. and
  318. .Dv accelfactor
  319. may be modifiable.
  320. Setting values in the other field does not generate
  321. error and has no effect.
  322. .\" .Pp
  323. .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
  324. .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
  325. .\" These commands are not supported by the
  326. .\" .Nm
  327. .\" driver.
  328. .Pp
  329. .It Dv MOUSE_READDATA Ar mousedata_t *data
  330. .It Dv MOUSE_READSTATE Ar mousedata_t *state
  331. These commands are not supported by the
  332. .Nm
  333. driver.
  334. .Pp
  335. .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
  336. The command returns the current state of buttons and
  337. movement counts as described in
  338. .Xr mouse 4 .
  339. .El
  340. .Sh FILES
  341. .Bl -tag -width /dev/nmse0 -compact
  342. .It Pa /dev/mse0
  343. `non-blocking' device node in the system without
  344. .Em devfs ,
  345. `blocking' under
  346. .Em devfs .
  347. .It Pa /dev/nmse0
  348. `non-blocking' device node under
  349. .Em devfs .
  350. .El
  351. .Sh EXAMPLES
  352. .Dl "device mse"
  353. .Pp
  354. In
  355. .Pa /boot/device.hints :
  356. .Dl hint.mse.0.at="isa"
  357. .Dl hint.mse.0.port="0x23c"
  358. .Dl hint.mse.0.irq="5"
  359. .Pp
  360. Add the
  361. .Nm
  362. driver at the primary port address with the IRQ 5.
  363. .Pp
  364. .Dl "device mse"
  365. .Pp
  366. .Dl hint.mse.1.at="isa"
  367. .Dl hint.mse.1.port="0x238"
  368. .Dl hint.mse.1.irq="4"
  369. .Dl hint.mse.1.flags="0x30"
  370. .Pp
  371. Define the
  372. .Nm
  373. driver at the secondary port address with the IRQ 4 and the acceleration
  374. factor of 3.
  375. .Sh SEE ALSO
  376. .Xr ioctl 2 ,
  377. .Xr mouse 4 ,
  378. .Xr psm 4 ,
  379. .Xr sysmouse 4 ,
  380. .Xr moused 8
  381. .\".Sh HISTORY
  382. .Sh CAVEATS
  383. Some bus mouse interface cards generate interrupts at the fixed report rate
  384. when enabled, whether or not the mouse state is changing.
  385. The others generate interrupts only when the state is changing.