.\" Copyright (c) 1997
.\"	John-Mark Gurney.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the author nor the names of any co-contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY John-Mark Gurney AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	%Id: sysmouse.4,v 1.7 1998/03/12 07:30:38 charnier Exp %
.\" $FreeBSD$
.\"
.\" word: movement	(マウスの)動き[sysmouse.4]
.\"
.Dd December 3, 1997
.Dt SYSMOUSE 4 i386
.Os FreeBSD
.Sh 名称
.Nm sysmouse
.Nd 仮想化されたマウスドライバ
.Sh 書式
.Fd #include <machine/mouse.h>
.Fd #include <machine/console.h>
.Sh 解説
マウスデーモン
.Xr moused 8
と一緒に使うことにより、コンソールドライバは、
.Nm
ドライバを通して、ユーザプロセスに標準的な方法でマウスのデータを提供します。
このように整理することで、
.Po
.Tn X\ Window System
などのような
.Pc
ユーザプロセスとコンソールとでマウスを共有することができるようになります。
.Pp
ユーザプロセスがマウス機能を利用しようとする場合、単に
.Xr open 2
システムコールで
.Pa /dev/sysmouse
をオープンし、
.Xr read 2
システムコールを用いてマウスデータを読み込むだけでよいです。
ここで、確実に
.Xr moused 8
を実行しておいて下さい。さもないと、ユーザプロセスはマウスからデータを
一切受け取ることができないでしょう。
.Pp
.Ss 機能レベル
.Nm
ドライバには 2 つの機能レベルがあります。現在の機能レベルは ioctl
システムコールにより参照、変更することができます。
.Pp
レベル 0 は最も低いレベルで、基本的なレベルでもあります。このレベルでは、
ドライバは、ユーザプログラムに対して基本的なサービスを提供します。
.Nm
ドライバは、マウスの水平垂直の動きと、最大で 3 個までのボタンの状態を、
以下に示す
.Tn MouseSystems 
形式で通知します。
.Pp
.Bl -tag -width Byte_1 -compact
.It Byte 1 
.Bl -tag -width bit_7 -compact
.It bit 7
常に 1 です。
.It bit 6..3
常に 0 です。
.It bit 2
左ボタンの状態です。押し下げられている状態でビットクリア、そうでなければ
ビットセットです。
.It bit 1
中ボタンの状態です。押し下げられている状態でビットクリア、そうでなければ
ビットセット。中ボタンを持たない機器の場合は常に 1 です。
.It bit 0
右ボタンの状態です。押し下げられている状態でビットクリア、そうでなければ
ビットセットです。
.El
.It Byte 2
水平の動きのカウントを 2 の補数形式で表した値の先頭半分です。
-128 から 127 までの値。
.It Byte 3
垂直の動きのカウントを 2 の補数形式で表した値の先頭半分です。
-128 から 127 までの値。
.It Byte 4
水平の動きのカウントを 2 の補数形式で表した値の後ろ半分です。
-128 から 127 までの値。水平の動きのカウントを得るには、
byte 2 と byte 4 を足して下さい。
.It Byte 5
垂直の動きのカウントを 2 の補数形式で表した値の後ろ半分です。
-128 から 127 までの値。垂直の動きのカウントを得るには、
byte 3 と byte 5 を足して下さい。
.El
.Pp
レベル 1 は拡張レベルで、マウスのデータは
.Xr mouse 4
で定義された標準形式
.Dv MOUSE_PROTO_SYSMOUSE
でコード化されます。
.\" .Ss Acceleration
.\" The
.\" .Nm
.\" 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.
.Sh IOCTL
この節では、2 種類の
.Xr ioctl 2
コマンドについて説明します。
1 つは、
.Nm
ドライバそれ自体に対するコマンドで、もう 1 つは、コンソールと
コンソール制御ドライバに対するコマンドです。
.Ss Sysmouse Ioctl
マウスドライバに対するコマンドがいくつかあります。このコマンド一般の説明は、
.Xr mouse 4
にあります。
以下では、
.Nm
ドライバ固有の機能を説明します。
.Pp
.Bl -tag -width MOUSE -compact
.It Dv MOUSE_GETLEVEL Ar int *level
.It Dv MOUSE_SETLEVEL Ar int *level
これらのコマンドは、マウスドライバの機能レベルを操作します。
.Pp
.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
以下の構造体で、接続された機器のハードウェア情報を返します。現在の
バージョンの
.Nm
ドライバでは、
.Dv iftype
フィールドだけが正しい値が詰まっていることが保証されています。
.Bd -literal
typedef struct mousehw {
    int buttons;    /* ボタンの数 */
    int iftype;     /* I/F タイプ */
    int type;       /* マウス/トラックボール/パッド... */
    int model;      /* I/F 依存のモデル ID */
    int hwid;       /* I/F 依存のハードウェア ID */
} mousehw_t;
.Ed
.Pp
.Dv buttons
フィールドには、ドライバが検出したボタンの数が保持されています。
.Pp
.Dv iftype
は常に
.Dv MOUSE_IF_SYSMOUSE
です。
.Pp
.Dv type
は機器の型: 
.Dv MOUSE_MOUSE ,
.Dv MOUSE_TRACKBALL ,
.Dv MOUSE_STICK ,
.Dv MOUSE_PAD ,
.Dv MOUSE_UNKNOWN
を表します。
.Pp
.Dv model
は、機能レベル 0 では常に
.Dv MOUSE_MODEL_GENERIC
です。
これは、より高いレベルでは、
.Dv MOUSE_MODEL_GENERIC
または、
.Dv MOUSE_MODEL_XXX
のうちの 1 つになります。
.Pp
.Dv hwid
は常に 0 です。
.Pp
.It Dv MOUSE_GETMODE Ar mousemode_t *mode
このコマンドは、マウスドライバの現在の機能パラメータを返します。
.Bd -literal
typedef struct mousemode {
    int protocol;    /* MOUSE_PROTO_XXX */
    int rate;        /* 通知レート (秒単位) */
    int resolution;  /* MOUSE_RES_XXX, 不明の場合は -1 */
    int accelfactor; /* 加速率 */
    int level;       /* ドライバの機能レベル */
    int packetsize;  /* データパケットの長さ */
    unsigned char syncmask[2]; /* 同期ビット */
} mousemode_t;
.Ed
.Pp
.Dv protocol
フィールドは、ユーザプログラムがマウスデータを読みとる時に、
その機器の状態を返す形式を表します。
機能レベル 0 では、
.Dv MOUSE_PROTO_MSC
であり、機能レベル 1 では、
.Dv MOUSE_PROTO_SYSMOUSE
です。
.Pp
.Dv rate
フィールドは、常に -1 です。
.Pp
.Dv resolution
フィールドは、常に -1 です。
.Pp
.Dv accelfactor
フィールドは、常に 0 です。
.Pp
.Dv packetsize
フィールドは、データパケットの長さを表します。これは機能レベルに
よって変わります。
.Pp
.Bl -tag -width level_0__ -compact
.It Em レベル 0
5 バイト
.It Em レベル 1
8 バイト
.El
.Pp
配列
.Dv syncmask
は、データパケットの先頭バイトを検出するための、ビットマスクとパターンを
保持します。
.Dv syncmask[0]
はビットマスクで、調べるバイトと AND を取ります。この結果が
.Dv syncmask[1]
と等しい場合、そのバイトはデータパケットの先頭バイトらしいと言えます。
この方法で先頭バイトを検出するやり方は 100% 確実とは言えません。
よって、これは参考扱いにするべきと注意をしておきます。
.Pp
.It Dv MOUSE_SETMODE Ar mousemode_t *mode
このコマンドは、マウスドライバの現在の機能パラメータを
.Ar mode
で指定した値に変更します。
.Dv level 
だけが変更可能です。他のフィールドに値を設定してもエラーは出ませんが、
何の効果も及ぼしません。
.\" .Pp
.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
.\" These commands are not supported by the
.\" .Nm
.\" driver.
.Pp
.It Dv MOUSE_READDATA Ar mousedata_t *data
.It Dv MOUSE_READSTATE Ar mousedata_t *state
これらのコマンドは
.Nm
ドライバではサポートされません。
.Pp
.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
このコマンドはボタンの現在の状態と動きのカウントを
.Xr mouse 4
で定義された構造体で返します。
.El
.Ss コンソールとコンソール制御 Ioctl
ユーザプログラムは、現在の仮想コンソールに対してコンソール 
.Fn ioctl
システムコールを発行し、マウスポインタを制御します。コンソール
.Fn ioctl 
はまた、ボタンが押された時に
.Xr signal 3
を受け取る手段をユーザプロセスに提供します。
.Pp
マウスデーモン
.Xr moused 8
は、
コンソール制御デバイス
.Pa /dev/consolectl
に対して
.Fn ioctl
システムコールを用いることにより、
マウスの動きとボタンの状態を含むマウスの動作をコンソールに通知します。
.Pp
両方のクラスの
.Fn ioctl
コマンドとも、以下の引数を取る
.Dv CONS_MOUSECTL
として定義されています。
.Bd -literal
struct mouse_info {
    int operation;
    union {
        struct mouse_data data;
        struct mouse_mode mode;
        struct mouse_event event;
    } u;
};
.Ed
.Pp
.Bl -tag -width operation -compact
.It Dv operation
これは以下のどれか 1 つを取ります。
.Pp
.Bl -tag -width MOUSE_MOVEABS -compact
.It Dv MOUSE_SHOW
マウスカーソルを有効にして表示します。
.It Dv MOUSE_HIDE
マウスカーソルを無効にして隠します。
.It Dv MOUSE_MOVEABS
マウスカーソルを
.Dv u.data
で与えた位置に移動させます。
.It Dv MOUSE_MOVEREL
現在の位置に、
.Dv u.data
で与えた値を加えた位置に移動させます。
.It Dv MOUSE_GETINFO
現在の仮想コンソールにおけるマウスの現在の位置と、ボタンの状態を
.Dv u.data
に収めて返します。
.It Dv MOUSE_MODE
これは、
.Xr signal 3
を設定し、現在のプロセスにボタンが押されたことを通知します。
シグナルは
.Dv u.mode
に収められて通知されます。
.El
.Pp
ここまでの機能は仮想コンソールに対するものです。これ以後に定義する機能は
コンソール制御ドライバに対するもので、
.Xr moused 8
がマウスデータをコンソールドライバに渡すために用います。
.Pp
.Bl -tag -width MOUSE_MOVEABS -compact
.It Dv MOUSE_ACTION
.It Dv MOUSE_MOTIONEVENT
これらの機能は
.Dv u.data
に情報を取り、その上で動作します。
.Nm
ドライバがオープンされている場合、マウスデータは
.Nm
ドライバに送られます。
.Dv MOUSE_ACTION
はボタン押し下げ動作を一緒に行ない、要求がある場合はシグナルを送ります。
現在のコンソールがテキストインタフェースを持つ場合、カットアンドペースト
処理を行ないます。
.It Dv MOUSE_BUTTONEVENT
.Dv u.data
で、ボタンの種類とそのクリックカウント数を指定します。コンソールドライバは
その情報を用い、要求がある場合はシグナルを送り、コンソールが
テキストインタフェースを持つ場合は、カットアンドペースト処理を行ないます。
.El
.Pp
.Dv MOUSE_MOTIONEVENT
と
.Dv MOUSE_BUTTONEVENT
は、新しいインタフェースで、この 2 つを一緒に使うことを想定して
作られています。これらは
.Dv MOUSE_ACTION
ひとつで行なわれている機能を置き換えるためのものです。
.Pp
.It Dv u
この共用体は、以下のいずれかです。
.Pp
.Bl -tag -width data -compact
.It Dv data
.Bd -literal
struct mouse_data {
    int x;
    int y;
    int z;
    int buttons;
};
.Ed
.Pp
.Dv x ,
.Dv y ,
.Dv z
は、それぞれの方向に対するマウスの移動を表します。
.Dv buttons
はボタンの状態を示します。ビット 0 からビット 30 までで最大 31 個の
ボタンの状態を表すことができます。ボタンが押されていると、対応する
ビットがセットされます。
.Pp
.It Dv mode
.Bd -literal
struct mouse_mode {
    int mode;
    int signal;
};
.Ed
.Pp
.Dv signal
フィールドは、プロセスに送るシグナルを指定します。この値は
.Ao Pa signal.h Ac
で定義された値のうちのひとつである必要があります。
.Dv mode
フィールドは現在は使用されていません。
.Pp
.It Dv event
.Bd -literal
struct mouse_event {
    int id;
    int value;
};
.Ed
.Pp
.Dv id
フィールドは、
.Dv u.data.buttons
と同じように、ボタン番号を指定します。
1 ビット/ボタンだけを設定できます。
.Dv value
フィールドは、クリック数を保持しています。これは、ユーザがボタンを
連続して押した回数です。
.Pp
.El
.El
.Sh 関連ファイル
.Bl -tag -width /dev/consolectl -compact
.It Pa /dev/consolectl
コンソールを制御するデバイス
.It Pa /dev/sysmouse
仮想化されたマウスドライバ
.It Pa /dev/ttyv%d
仮想コンソール
.El
.Sh 関連項目
.Xr vidcontrol 1 ,
.Xr ioctl 2 ,
.Xr signal 3 ,
.Xr mouse 4 ,
.Xr moused 8
.Sh 歴史
.Nm
マニュアルページは、
.Fx 2.2
で初めて現れました。
.Sh 作者
このマニュアルは
.An John-Mark Gurney Aq gurney_j@efn.org 
と
.An Kazutaka Yokota Aq yokota@FreeBSD.org
が書きました。
.\" translated by Norihiro Kumagai kuma@nk.rim.or.jp 99-7-18