1.\" Copyright (c) 2015 Baptiste Daroussin <bapt@FreeBSD.org> 2.\" 2015 Koop Mast <kwm@FreeBSD.org> 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.Dd January 08, 2015 25.Dt LIBDEVQ 3 26.Os 27.Sh NAME 28.Nm libdevq 29.Nd Generic Device Query and Monitor interface 30.Sh LIBRARY 31Portable query and monitoring library (libdevq, -ldevq) 32.Sh SYNOPSIS 33.In sys/types.h 34.In libdevq.h 35.Ft devq_class_t 36.Fo devq_device_get_class 37.Fa "struct devq_device *device" 38.Fc 39.Ft const char * 40.Fo devq_device_get_devpath_from_fd 41.Fa "int fd" 42.Fa "char *path" 43.Fa "size_t *path_len" 44.Fc 45.Ft const char * 46.Fo devq_device_get_path 47.Fa "struct devq_device *device" 48.Fc 49.Ft int 50.Fo devq_device_get_pcibusaddr 51.Fa "int *domain" 52.Fa "int *bus" 53.Fa "int *slot" 54.Fa "int *function" 55.Fc 56.Ft int 57.Fo devq_device_get_pciid_from_fd 58.Fa "int fd" 59.Fa "int *vendor_id" 60.Fa "int *device_id" 61.Fc 62.Ft int 63.Fo devq_device_get_pciid_full_from_fd 64.Fa "int fd" 65.Fa "int *vendor_id" 66.Fa "int *device_id" 67.Fa "int *subvendor_id" 68.Fa "int *subdevice_id" 69.Fa "int *revision_id" 70.Fc 71.Ft const char * 72.Fo devq_device_get_product 73.Fa "struct devq_device *device" 74.Fc 75.Ft devq_device_t 76.Fo devq_device_get_type 77.Fa "struct devq_device *device" 78.Fc 79.Ft const char * 80.Fo devq_device_get_vendor 81.Fa "struct devq_device *device" 82.Fc 83.Ft int 84.Fo devq_drm_get_drvname_from_fd 85.Fa "int fd" 86.Fa "char *driver_name" 87.Fa "size_t *driver_name_len" 88.Fc 89.Ft const char * 90.Fo devq_event_dump 91.Fa "struct devq_event *" 92.Fc 93.Ft void 94.Fo devq_event_free 95.Fa "struct devq_event *" 96.Fc 97.Ft struct devq_device * 98.Fo devq_event_get_deviced 99.Fa "struct devq_event *" 100.Fc 101.Ft devq_event_t 102.Fo devq_event_get_type 103.Fa "struct devq_event *" 104.Fc 105.Ft void 106.Fo devq_event_monitor_fini 107.Fa "struct devq_evmon *" 108.Fc 109.Ft int 110.Fo devq_event_monitor_get_fd 111.Fa "struct devq_evmon *" 112.Fc 113.Ft struct devq_evmon * 114.Fo devq_event_monitor_init 115.Fa "void" 116.Fc 117.Ft int 118.Fo devq_event_monitor_poll 119.Fa "struct devq_evmon *" 120.Fc 121.Ft struct devq_event * 122.Fo devq_event_monitor_read 123.Fa "struct devq_evmon *" 124.Fc 125.Sh REFERENCE 126This section documents the functions, types, and variable available via 127.In libdevq.h . 128.Ss Types 129.Bl -ohang 130.It Vt "devq_class_t" 131A list of event class. Values are: 132.Bl -tag -width "DEVQ_CLASS_UNKNOWN" -compact -offset indent 133.It Em DEVQ_CLASS_UNKNOWN 134Unknown class 135.It Em DEVQ_CLASS_INPUT 136Input device class 137.El 138.It Vt "devq_device_t" 139A list of device types. Values are: 140.Bl -tag -width "DEVQ_DEVICE_TOUCHSCREEN" -compact -offset indent 141.It Em DEVQ_DEVICE_UNKNOWN 142Unknown device type 143.It Em DEVQ_DEVICE_KEYBOARD 144Device is a keyboard 145.It Em DEVQ_DEVICE_MOUSE 146Device is a mouse 147.It Em DEVQ_DEVICE_JOYSTICK 148Device is a joystick 149.It Em DEVQ_DEVICE_TOUCHPAD 150Device is a touchpad 151.It Em DEVQ_DEVICE_TOUCHSCREEN 152Device is a touchscreen 153.El 154.It Vt "devq_event_t" 155A list of event types. Values are: 156.Bl -tag -width "DEVQ_ATTACHED" -compact -offset indent 157.It Em DEVQ_ATTACHED 158A device have been attached 159.It Em DEVQ_DETACHED 160A device have been detached 161.It Em DEVQ_NOTICE 162An information is available 163.It Em DEVQ_UNKNOWN 164An unknown event has occured 165.El 166.It Vt "struct devq_device" 167An opaque structure representing a device 168.It Vt "struct devq_event" 169An opaque structure representing an event 170.It Vt "struct devq_evmon" 171An opaque structure representing an event monitor 172.El 173.Ss Functions 174Device query functions. 175.Bl -ohang 176.It Fn devq_device_get_pcibusaddr 177Return the pci bus location: domain, bus, slot and function. 178.Sy Currently 179only for DRM devices. 180.It Fn devq_device_get_devpath_from_fd 181Returns the absolute path of the device. 182.It Fn devq_device_get_pciid_full_from_fd 183Return the vendor_id, device_id, subvendor_id, subdevice_id and revision_id 184of the supplied fd. 185.Sy Currently 186only for DRM devices. 187.It Fn devq_device_get_pciid_from_fd 188Return the vendor_id and device_id of the supplied fd. 189.Sy Currently 190only for DRM devices. 191.It Fn devq_drm_get_drvname_from_fd 192Returns the driver name. 193.Pp 194Device notification API 195.It Fn devq_event_dump 196Returns the raw devq_event content. 197.It Fn devq_event_free 198Frees the devq_event struct. 199.It Fn devq_event_monitor_init 200function setups the monitoring code. 201.It Fn devq_event_monitor_fini 202function cleanup the event monitering code. 203.It Fn devq_event_monitor_get_fd 204Return the fd of the devq_evmon. 205.It Fn devq_event_monitor_poll 206Returns 1 if there are events waiting, otherwise 0. 207.It Fn devq_event_monitor_read 208Returns a devq_event struct otherwise NULL. 209.It Fn devq_event_get_type 210Returns what kind of event this is. 211.It Fn devq_event_get_deviced 212Returns information about the device on ATTACH or DETACH events. Otherwise NULL. 213.It Fn devq_device_get_type 214Returns the type of the device the event is about. 215.It Fn devq_device_get_class 216Return the device class for a given device. 217.It Fn devq_device_get_path 218Return the absolute path of the device. 219.It Fn devq_device_get_product 220Return the product of the device the event is about. 221.It Fn devq_device_get_vendor 222Return the vendor of the device the event is about. 223.El 224.Sh EXAMPLES 225fill me... 226.Sh Return values 227.Rv -std 228.Sh ERRORS 229The functions in 230.Fn libdevq 231may fail with the following errors: 232.Bl -tag -width Er 233.It Bq Er EBADF 234Bad File Descriptor 235.It Bq Er ENOMEM 236Cannot allocate memory 237.It Bq Er ENOENT 238No such file or directory 239.It Bq Er EINVAL 240Invalid argument 241.El 242.Sh SEE ALSO 243.Xr devinfo 3 , 244.Xr devctl 4 , 245.Xr devclass 9 246.Sh AUTHORS 247The 248.Nm 249library was written by: 250.Pp 251.An Baptiste Daroussin Aq Mt bapt@FreeBSD.org , 252.An Jean-S\['e]bastien P\['e]dron Aq Mt dumbbell@FreeBSD.org , 253.An Koop Mast Aq Mt kwm@FreeBSD.org 254