1*4882a593Smuzhiyun.. include:: <isonum.txt> 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun=================== 4*4882a593SmuzhiyunThe userio Protocol 5*4882a593Smuzhiyun=================== 6*4882a593Smuzhiyun 7*4882a593Smuzhiyun 8*4882a593Smuzhiyun:Copyright: |copy| 2015 Stephen Chandler Paul <thatslyude@gmail.com> 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunSponsored by Red Hat 11*4882a593Smuzhiyun 12*4882a593Smuzhiyun 13*4882a593SmuzhiyunIntroduction 14*4882a593Smuzhiyun============= 15*4882a593Smuzhiyun 16*4882a593SmuzhiyunThis module is intended to try to make the lives of input driver developers 17*4882a593Smuzhiyuneasier by allowing them to test various serio devices (mainly the various 18*4882a593Smuzhiyuntouchpads found on laptops) without having to have the physical device in front 19*4882a593Smuzhiyunof them. userio accomplishes this by allowing any privileged userspace program 20*4882a593Smuzhiyunto directly interact with the kernel's serio driver and control a virtual serio 21*4882a593Smuzhiyunport from there. 22*4882a593Smuzhiyun 23*4882a593SmuzhiyunUsage overview 24*4882a593Smuzhiyun============== 25*4882a593Smuzhiyun 26*4882a593SmuzhiyunIn order to interact with the userio kernel module, one simply opens the 27*4882a593Smuzhiyun/dev/userio character device in their applications. Commands are sent to the 28*4882a593Smuzhiyunkernel module by writing to the device, and any data received from the serio 29*4882a593Smuzhiyundriver is read as-is from the /dev/userio device. All of the structures and 30*4882a593Smuzhiyunmacros you need to interact with the device are defined in <linux/userio.h> and 31*4882a593Smuzhiyun<linux/serio.h>. 32*4882a593Smuzhiyun 33*4882a593SmuzhiyunCommand Structure 34*4882a593Smuzhiyun================= 35*4882a593Smuzhiyun 36*4882a593SmuzhiyunThe struct used for sending commands to /dev/userio is as follows:: 37*4882a593Smuzhiyun 38*4882a593Smuzhiyun struct userio_cmd { 39*4882a593Smuzhiyun __u8 type; 40*4882a593Smuzhiyun __u8 data; 41*4882a593Smuzhiyun }; 42*4882a593Smuzhiyun 43*4882a593Smuzhiyun``type`` describes the type of command that is being sent. This can be any one 44*4882a593Smuzhiyunof the USERIO_CMD macros defined in <linux/userio.h>. ``data`` is the argument 45*4882a593Smuzhiyunthat goes along with the command. In the event that the command doesn't have an 46*4882a593Smuzhiyunargument, this field can be left untouched and will be ignored by the kernel. 47*4882a593SmuzhiyunEach command should be sent by writing the struct directly to the character 48*4882a593Smuzhiyundevice. In the event that the command you send is invalid, an error will be 49*4882a593Smuzhiyunreturned by the character device and a more descriptive error will be printed 50*4882a593Smuzhiyunto the kernel log. Only one command can be sent at a time, any additional data 51*4882a593Smuzhiyunwritten to the character device after the initial command will be ignored. 52*4882a593Smuzhiyun 53*4882a593SmuzhiyunTo close the virtual serio port, just close /dev/userio. 54*4882a593Smuzhiyun 55*4882a593SmuzhiyunCommands 56*4882a593Smuzhiyun======== 57*4882a593Smuzhiyun 58*4882a593SmuzhiyunUSERIO_CMD_REGISTER 59*4882a593Smuzhiyun~~~~~~~~~~~~~~~~~~~ 60*4882a593Smuzhiyun 61*4882a593SmuzhiyunRegisters the port with the serio driver and begins transmitting data back and 62*4882a593Smuzhiyunforth. Registration can only be performed once a port type is set with 63*4882a593SmuzhiyunUSERIO_CMD_SET_PORT_TYPE. Has no argument. 64*4882a593Smuzhiyun 65*4882a593SmuzhiyunUSERIO_CMD_SET_PORT_TYPE 66*4882a593Smuzhiyun~~~~~~~~~~~~~~~~~~~~~~~~ 67*4882a593Smuzhiyun 68*4882a593SmuzhiyunSets the type of port we're emulating, where ``data`` is the port type being 69*4882a593Smuzhiyunset. Can be any of the macros from <linux/serio.h>. For example: SERIO_8042 70*4882a593Smuzhiyunwould set the port type to be a normal PS/2 port. 71*4882a593Smuzhiyun 72*4882a593SmuzhiyunUSERIO_CMD_SEND_INTERRUPT 73*4882a593Smuzhiyun~~~~~~~~~~~~~~~~~~~~~~~~~ 74*4882a593Smuzhiyun 75*4882a593SmuzhiyunSends an interrupt through the virtual serio port to the serio driver, where 76*4882a593Smuzhiyun``data`` is the interrupt data being sent. 77*4882a593Smuzhiyun 78*4882a593SmuzhiyunUserspace tools 79*4882a593Smuzhiyun=============== 80*4882a593Smuzhiyun 81*4882a593SmuzhiyunThe userio userspace tools are able to record PS/2 devices using some of the 82*4882a593Smuzhiyundebugging information from i8042, and play back the devices on /dev/userio. The 83*4882a593Smuzhiyunlatest version of these tools can be found at: 84*4882a593Smuzhiyun 85*4882a593Smuzhiyun https://github.com/Lyude/ps2emu 86