Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
PSM(4)		       FreeBSD Kernel Interfaces Manual			PSM(4)

NAME
     psm -- PS/2 mouse style pointing device driver

SYNOPSIS
     options KBD_RESETDELAY=N
     options KBD_MAXWAIT=N
     options PSM_DEBUG=N
     options KBDIO_DEBUG=N
     device psm

     In	/boot/device.hints:
     hint.psm.0.at="atkbdc"
     hint.psm.0.irq="12"

DESCRIPTION
     The psm driver provides support for the PS/2 mouse	style pointing device.
     Currently there can be only one psm device	node in	the system.  As	the
     PS/2 mouse	port is	located	at the auxiliary port of the keyboard con-
     troller, the keyboard controller driver, atkbdc, must also	be configured
     in	the kernel.  Note that there is	currently no provision of changing the
     irq number.

     Basic PS/2	style pointing device has two or three buttons.	 Some devices
     may have a	roller or a wheel and/or additional buttons.

   Device Resolution
     The PS/2 style pointing device usually has	several	grades of resolution,
     that is, sensitivity of movement.	They are typically 25, 50, 100 and 200
     pulse per inch.  Some devices may have finer resolution.  The current
     resolution	can be changed at runtime.  The	psm driver allows the user to
     initially set the resolution via the driver flag (see DRIVER
     CONFIGURATION) or change it later via the ioctl(2)	command	MOUSE_SETMODE
     (see IOCTLS).

   Report Rate
     Frequency,	or report rate,	at which the device sends movement and button
     state reports to the host system is also configurable.  The PS/2 style
     pointing device typically supports	10, 20,	40, 60,	80, 100	and 200
     reports per second.  60 or	100 appears to be the default value for	many
     devices.  Note that when there is no movement and no button has changed
     its state,	the device won't send anything to the host system.  The	report
     rate can be changed via an	ioctl call.

   Operation Levels
     The psm driver has	three levels of	operation.  The	current	operation
     level can be set via an ioctl call.

     At	the level zero the basic support is provided; the device driver	will
     report horizontal and vertical movement of	the attached device and	state
     of	up to three buttons.  The movement and status are encoded in a series
     of	fixed-length data packets (see Data Packet Format).  This is the
     default level of operation	and the	driver is initially at this level when
     opened by the user	program.

     The operation level one, the `extended' level, supports a roller (or
     wheel), if	any, and up to 11 buttons.  The	movement of the	roller is
     reported as movement along	the Z axis.  8 byte data packets are sent to
     the user program at this level.

     At	the operation level two, data from the pointing	device is passed to
     the user program as is.  Modern PS/2 type pointing	devices	often use pro-
     prietary data format.  Therefore, the user	program	is expected to have
     intimate knowledge	about the format from a	particular device when operat-
     ing the driver at this level.  This level is called `native' level.

   Data	Packet Format
     Data packets read from the	psm driver are formatted differently at	each
     operation level.

     A data packet from	the PS/2 mouse style pointing device is	three bytes
     long at the operation level zero:

     Byte 1
	     bit 7  One	indicates overflow in the vertical movement count.
	     bit 6  One	indicates overflow in the horizontal movement count.
	     bit 5  Set	if the vertical	movement count is negative.
	     bit 4  Set	if the horizontal movement count is negative.
	     bit 3  Always one.
	     bit 2  Middle button status; set if pressed.  For devices without
		    the	middle button, this bit	is always zero.
	     bit 1  Right button status; set if	pressed.
	     bit 0  Left button	status;	set if pressed.
     Byte 2  Horizontal	movement count in two's	complement; -256 through 255.
	     Note that the sign	bit is in the first byte.
     Byte 3  Vertical movement count in	two's complement; -256 through 255.
	     Note that the sign	bit is in the first byte.

     At	the level one, a data packet is	encoded	in the standard	format
     MOUSE_PROTO_SYSMOUSE as defined in	mouse(4).

     At	the level two, native level, there is no standard on the size and for-
     mat of the	data packet.

   Acceleration
     The psm driver can	somewhat `accelerate' the movement of the pointing
     device.  The faster you move the device, the further the pointer travels
     on	the screen.  The driver	has an internal	variable which governs the
     effect of the acceleration.  Its value can	be modified via	the driver
     flag or via an ioctl call.

   Device Number
     The minor device number of	the psm	is made	up of:

	   minor = (`unit' << 1) | `non-blocking'

     where `unit' is the device	number (usually	0) and the `non-blocking' bit
     is	set to indicate	``don't	block waiting for mouse	input, return immedi-
     ately''.  The `non-blocking' bit should be	set for	XFree86, therefore the
     minor device number usually used for XFree86 is 1.	 See FILES for device
     node names.

DRIVER CONFIGURATION
   Kernel Configuration	Options
     There are following kernel	configuration options to control the psm
     driver.  They may be set in the kernel configuration file (see
     config(8)).

     KBD_RESETDELAY=X, KBD_MAXWAIT=Y
	    The	psm driver will	attempt	to reset the pointing device during
	    the	boot process.  It sometimes takes a long while before the
	    device will	respond	after reset.  These options control how	long
	    the	driver should wait before it eventually	gives up waiting.  The
	    driver will	wait X * Y msecs at most.  If the driver seems unable
	    to detect your pointing device, you	may want to increase these
	    values.  The default values	are 200	msec for X and 5 for Y.

     PSM_DEBUG=N, KBDIO_DEBUG=N
	    Sets the debug level to N.	The default debug level	is zero.  See
	    DIAGNOSTICS	for debug logging.

   Driver Flags
     The psm driver accepts the	following driver flags.	 Set them in
     /boot/device.hints	(see EXAMPLES below).

     bit 0..3 RESOLUTION
	    This flag specifies	the resolution of the pointing device.	It
	    must be zero through four.	The greater the	value is, the finer
	    resolution the device will select.	Actual resolution selected by
	    this field varies according	to the model of	the device.  Typical
	    resolutions	are:

	    1 (low)	       25 pulse	per inch (ppi)
	    2 (medium low)     50 ppi
	    3 (medium high)    100 ppi
	    4 (high)	       200 ppi

	    Leaving this flag zero will	selects	the default resolution for the
	    device (whatever it	is).

     bit 4..7 ACCELERATION
	    This flag controls the amount of acceleration effect.  The smaller
	    the	value of this flag is, more sensitive the movement becomes.
	    The	minimum	value allowed, thus the	value for the most sensitive
	    setting, is	one.  Setting this flag	to zero	will completely	dis-
	    ables the acceleration effect.

     bit 8 NOCHECKSYNC
	    The	psm driver tries to detect the first byte of the data packet
	    by checking	the bit	pattern	of that	byte.  Although	this method
	    should work	with most PS/2 pointing	devices, it may	interfere with
	    some devices which are not so compatible with known	devices.  If
	    you	think your pointing device is not functioning as expected, and
	    the	kernel frequently prints the following message to the console,

		  psmintr: out of sync (xxxx !=	yyyy).

	    set	this flag to disable synchronization check and see if it
	    helps.

     bit 9 NOIDPROBE
	    The	psm driver will	not try	to identify the	model of the pointing
	    device and will not	carry out model-specific initialization.  The
	    device should always act like a standard PS/2 mouse	without	such
	    initialization.  Extra features, such as wheels and	additional
	    buttons, won't be recognized by the	psm driver.

     bit 10 NORESET
	    When this flag is set, the psm driver won't	reset the pointing
	    device when	initializing the device.  If the FreeBSD kernel	is
	    started after another OS has run, the pointing device will inherit
	    settings from the previous OS.  However, because there is no way
	    for	the psm	driver to know the settings, the device	and the	driver
	    may	not work correctly.  The flag should never be necessary	under
	    normal circumstances.

     bit 11 FORCETAP
	    Some pad devices report as if the fourth button is pressed when
	    the	user `taps' the	surface	of the device (see CAVEATS).  This
	    flag will make the psm driver assume that the device behaves this
	    way.  Without the flag, the	driver will assume this	behavior for
	    ALPS GlidePoint models only.

     bit 12 IGNOREPORTERROR
	    This flag makes psm	driver ignore certain error conditions when
	    probing the	PS/2 mouse port.  It should never be necessary under
	    normal circumstances.

     bit 13 HOOKRESUME
	    The	built-in PS/2 pointing device of some laptop computers is
	    somehow not	operable immediately after the system `resumes'	from
	    the	power saving mode, though it will eventually become available.
	    There are reports that stimulating the device by performing	I/O
	    will help waking up	the device quickly.  This flag will enable a
	    piece of code in the psm driver to hook the	`resume' event and
	    exercise some harmless I/O operations on the device.

     bit 14 INITAFTERSUSPEND
	    This flag adds more	drastic	action for the above problem.  It will
	    cause the psm driver to reset and re-initialize the	pointing
	    device after the `resume' event.  It has no	effect unless the
	    HOOKRESUME flag is set as well.

IOCTLS
     There are a few ioctl(2) commands for mouse drivers.  These commands and
     related structures	and constants are defined in <sys/mouse.h>.  General
     description of the	commands is given in mouse(4).	This section explains
     the features specific to the psm driver.

     MOUSE_GETLEVEL int	*level
     MOUSE_SETLEVEL int	*level
	    These commands manipulate the operation level of the psm driver.

     MOUSE_GETHWINFO mousehw_t *hw
	    Returns the	hardware information of	the attached device in the
	    following structure.

	    typedef struct mousehw {
		int buttons;	/* number of buttons */
		int iftype;	/* I/F type */
		int type;	/* mouse/track ball/pad... */
		int model;	/* I/F dependent model ID */
		int hwid;	/* I/F dependent hardware ID */
	    } mousehw_t;

	    The	buttons	field holds the	number of buttons on the device.  The
	    psm	driver currently can detect the	3 button mouse from Logitech
	    and	report accordingly.  The 3 button mouse	from the other manu-
	    facturer may or may	not be reported	correctly.  However, it	will
	    not	affect the operation of	the driver.

	    The	iftype is always MOUSE_IF_PS2.

	    The	type tells the device type: MOUSE_MOUSE, MOUSE_TRACKBALL,
	    MOUSE_STICK, MOUSE_PAD, or MOUSE_UNKNOWN.  The user	should not
	    heavily rely on this field,	as the driver may not always, in fact
	    it is very rarely able to, identify	the device type.

	    The	model is always	MOUSE_MODEL_GENERIC at the operation level 0.
	    It may be MOUSE_MODEL_GENERIC or one of MOUSE_MODEL_XXX constants
	    at higher operation	levels.	 Again the psm driver may or may not
	    set	an appropriate value in	this field.

	    The	hwid is	the ID value returned by the device.  Known IDs
	    include:

	    0	 Mouse (Microsoft, Logitech and	many other manufacturers)
	    2	 Microsoft Ballpoint mouse
	    3	 Microsoft IntelliMouse

     MOUSE_GETMODE mousemode_t *mode
	    The	command	gets the current operation parameters of the mouse
	    driver.

	    typedef struct mousemode {
		int protocol;	 /* MOUSE_PROTO_XXX */
		int rate;	 /* report rate	(per sec), -1 if unknown */
		int resolution;	 /* MOUSE_RES_XXX, -1 if unknown */
		int accelfactor; /* acceleration factor	*/
		int level;	 /* driver operation level */
		int packetsize;	 /* the	length of the data packet */
		unsigned char syncmask[2]; /* sync. bits */
	    } mousemode_t;

	    The	protocol is MOUSE_PROTO_PS2 at the operation level zero	and
	    two.  MOUSE_PROTO_SYSMOUSE at the operation	level one.

	    The	rate is	the status report rate (reports/sec) at	which the
	    device will	send movement report to	the host computer.  Typical
	    supported values are 10, 20, 40, 60, 80, 100 and 200.  Some	mice
	    may	accept other arbitrary values too.

	    The	resolution of the pointing device must be one of MOUSE_RES_XXX
	    constants or a positive value.  The	greater	the value is, the
	    finer resolution the mouse will select.  Actual resolution
	    selected by	the MOUSE_RES_XXX constant varies according to the
	    model of mouse.  Typical resolutions are:

	    MOUSE_RES_LOW	    25 ppi
	    MOUSE_RES_MEDIUMLOW	    50 ppi
	    MOUSE_RES_MEDIUMHIGH    100	ppi
	    MOUSE_RES_HIGH	    200	ppi

	    The	accelfactor field holds	a value	to control acceleration	fea-
	    ture (see Acceleration).  It must be zero or greater.  If it is
	    zero, acceleration is disabled.

	    The	packetsize field specifies the length of the data packet.  It
	    depends on the operation level and the model of the	pointing
	    device.

	    level 0    3 bytes
	    level 1    8 bytes
	    level 2    Depends on the model of the device

	    The	array syncmask holds a bit mask	and pattern to detect the
	    first byte of the data packet.  syncmask[0]	is the bit mask	to be
	    ANDed with a byte.	If the result is equal to syncmask[1], the
	    byte is likely to be the first byte	of the data packet.  Note that
	    this detection method is not 100% reliable,	thus, should be	taken
	    only as an advisory	measure.

     MOUSE_SETMODE mousemode_t *mode
	    The	command	changes	the current operation parameters of the	mouse
	    driver as specified	in mode.  Only rate, resolution, level and
	    accelfactor	may be modifiable.  Setting values in the other	field
	    does not generate error and	has no effect.

	    If you do not want to change the current setting of	a field, put
	    -1 there.  You may also put	zero in	resolution and rate, and the
	    default value for the fields will be selected.

     MOUSE_READDATA mousedata_t	*data
     MOUSE_READSTATE mousedata_t *state
	    These commands are not currently supported by the psm driver.

     MOUSE_GETSTATUS mousestatus_t *status
	    The	command	returns	the current state of buttons and movement
	    counts as described	in mouse(4).

FILES
     /dev/psm0	 `non-blocking'	device node
     /dev/bpsm0	 `blocking' device node	under devfs.

EXAMPLES
     In	order to install the psm driver, you need to add

	   device atkbdc
	   device psm

     to	your kernel configuration file,	and put	the following lines to
     /boot/device.hints.

	   hint.atkbdc.0.at="isa"
	   hint.atkbdc.0.port="0x060"
	   hint.psm.0.at="atkbdc"
	   hint.psm.0.irq="12"

     If	you add	the following statement	to /boot/device.hints,

	   hint.psm.0.flags="0x2000"

     you will add the optional code to stimulate the pointing device after the
     `resume' event.

	   hint.psm.0.flags="0x24"

     The above line will set the device	resolution high	(4) and	the accelera-
     tion factor to 2.

DIAGNOSTICS
     At	debug level 0, little information is logged except for the following
     line during boot process:

	   psm0: device	ID X

     where X the device	ID code	returned by the	found pointing device.	See
     MOUSE_GETINFO for known IDs.

     At	debug level 1 more information will be logged while the	driver probes
     the auxiliary port	(mouse port).  Messages	are logged with	the LOG_KERN
     facility at the LOG_DEBUG level (see syslogd(8)).

	   psm0: current command byte:xxxx
	   kbdio: TEST_AUX_PORT	status:0000
	   kbdio: RESET_AUX return code:00fa
	   kbdio: RESET_AUX status:00aa
	   kbdio: RESET_AUX ID:0000
	   [...]
	   psm:	status 00 02 64
	   psm0	irq 12 on isa
	   psm0: model AAAA, device ID X, N buttons
	   psm0: config:00000www, flags:0000uuuu, packet size:M
	   psm0: syncmask:xx, syncbits:yy

     The first line shows the command byte value of the	keyboard controller
     just before the auxiliary port is probed.	It usually is 4D, 45, 47 or
     65, depending on how the motherboard BIOS initialized the keyboard	con-
     troller upon power-up.

     The second	line shows the result of the keyboard controller's test	on the
     auxiliary port interface, with zero indicating no error; note that	some
     controllers report	no error even if the port does not exist in the	sys-
     tem, however.

     The third through fifth lines show	the reset status of the	pointing
     device.  The functioning device should return the sequence	of FA AA <ID>.
     The ID code is described above.

     The seventh line shows the	current	hardware settings.  These bytes	are
     formatted as follows:

     Byte 1
	     bit 7  Reserved.
	     bit 6  0 -	stream mode, 1 - remote	mode.  In the stream mode, the
		    pointing device sends the device status whenever its state
		    changes.  In the remote mode, the host computer must
		    request the	status to be sent.  The	psm driver puts	the
		    device in the stream mode.
	     bit 5  Set	if the pointing	device is currently enabled.  Other-
		    wise zero.
	     bit 4  0 -	1:1 scaling, 1 - 2:1 scaling.  1:1 scaling is the
		    default.
	     bit 3  Reserved.
	     bit 2  Left button	status;	set if pressed.
	     bit 1  Middle button status; set if pressed.
	     bit 0  Right button status; set if	pressed.
     Byte 2
	     bit 7    Reserved.
	     bit 6..0
		      Resolution code: zero through three.  Actual resolution
		      for the resolution code varies from one device to
		      another.
     Byte 3  The status	report rate (reports/sec) at which the device will
	     send movement report to the host computer.

     Note that the pointing device will	not be enabled until the psm driver is
     opened by the user	program.

     The rest of the lines show	the device ID code, the	number of detected
     buttons and internal variables.

     At	debug level 2, much more detailed information is logged.

CAVEATS
     Many pad devices behave as	if the first (left) button were	pressed	if the
     user `taps' the surface of	the pad.  In contrast, some pad	products, e.g.
     some verions of ALPS GlidePoint and Interlink VersaPad, treat the tapping
     action as fourth button events.

     It	is reported that Interlink VersaPad requires both HOOKRESUME and
     INITAFTERSUSPEND flags in order to	recover	from suspended state.  These
     flags are automatically set when VersaPad is detected by the psm driver.

     Some PS/2 mouse models from MouseSystems require to be put	in the high
     resolution	mode to	work properly.	Use the	driver flag to set resolution.

     There is not a guaranteed way to re-synchronize with the first byte of
     the packet	once we	are out	of synchronization with	the data stream.  How-
     ever, if you are using the	XFree86	server and experiencing	the problem,
     you may be	able to	make the X server synchronize with the mouse by
     switching away to a virtual terminal and getting back to the X server,
     unless the	X server is accessing the mouse	via moused(8).	Clicking any
     button without moving the mouse may also work.

BUGS
     The ioctl command MOUSEIOCREAD has	been removed.  It was never functional
     anyway.

SEE ALSO
     ioctl(2), syslog(3), atkbdc(4), mouse(4), mse(4), sysmouse(4), moused(8),
     syslogd(8)

AUTHORS
     The psm driver is based on	the work done by quite a number	of people,
     including Eric Forsberg, Sandi Donno, Rick	Macklem, Andrew	Herbert,
     Charles Hannum, Shoji Yuen	and Kazutaka Yokota to name the	few.

     This manual page was written by Kazutaka Yokota <yokota@FreeBSD.org>.

FreeBSD	10.1			 April 1, 2000			  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | DRIVER CONFIGURATION | IOCTLS | FILES | EXAMPLES | DIAGNOSTICS | CAVEATS | BUGS | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=psm&sektion=4&manpath=FreeBSD+5.0-RELEASE>

home | help