hwsd  2.0.1
Local and remote ZeroConf service discovery for hardware resources
 All Pages
README.md
1 # Hardware Service Discovery
2 
3 HW-SD is a library and daemon for the discovery and announcement of
4 hardware resources using ZeroConf. It enables auto-configuration
5 of ad-hoc GPU clusters and multi-GPU machines.
6 
7 The source code is hosted on
8 [github](https://github.com/Eyescale/hwsd) and documented on
9 [eyescale.github.io](https://eyescale.github.io/#hwsd).
10 
11 ## Modules
12 
13 The HW-SD library uses modules which implement discovery using different
14 protocols. Each module is a separate library, which can be selectively
15 linked by applications to limit dependencies. Currently available are:
16 
17 - gpu_dns_sd: Remote ZeroConf (Bonjour) discovery for GPUs announced by
18  the daemon
19 - gpu_cgl: Local discovery of Carbon displays (Mac OS X only)
20 - gpu_glx: Local discovery of X11 servers and screens
21 - gpu_wgl: Local discovery of WGL_NV_gpu_affinity, WGL_AMD_gpu_association
22  or Windows displays (Windows only)
23 - net_dns_sd: Remote ZeroConf (Bonjour) discovery for network interfaces
24  announced by the daemon
25 - net_sys: Local discovery of network interfaces
26 
27 ## VirtualGL
28 
29 When an application is run through VirtualGL, hwsd detects this and
30 sets the FLAG\_VIRTUALGL on all local GPUs, and additionally
31 FLAG\_VIRTUALGL\_DISPLAY on the GPU used by VirtualGL for
32 redirection. This is only implemented for GLX so far
33 ([more info](https://github.com/Eyescale/Equalizer/issues/67)).
34 
35 ## Announcement Daemon
36 
37 The daemon uses all available local modules to query local GPUs and
38 network interfaces to announce them using ZeroConf to the local
39 network. The service type name is "_gpu-sd" and "_net-sd". The dns_sd
40 discovery module gathers the information announced by all daemons on the
41 local network. The following protocol is used by the daemon:
42 
43 * Session=default | <string>
44 * NodeID=<UUID>
45 * Hostname=<string> // optional, hostname for connections
46 
47 * GPU Count=<integer>
48 * GPU<integer> Type=GLX | WGL | WGLn | WGLa | CGL
49 * GPU<integer> Port=<integer> // X11 display number, 0 otherwise
50 * GPU<integer> Device=<integer> // X11 screen number,
51  wglEnumGpusNV index, CGDirectDisplayID
52 * GPU<integer> Width=<integer>
53 * GPU<integer> Height=<integer>
54 * GPU<integer> X=<integer>
55 * GPU<integer> Y=<integer>
56 * GPU<integer> Flags=<integer> // optional flags (see gpuInfo.h)
57 
58 * Net Count=<integer>
59 * Net<integer> Type=TYPE_ETHERNET | TYPE_INFINIBAND | TYPE_LOOPBACK | TYPE_UNKNOWN
60 * Net<integer> Name=<string>
61 * Net<integer> Hostname=<string>
62 * Net<integer> MAC=<string> // ':' as separator
63 * Net<integer> IPv4=<string> // ':' as separator
64 * Net<integer> IPv6=<string> // ':' as separator
65 * Net<integer> Linkspeed=<integer> // in Megabits per second
66 * Net<integer> Up=<bool>
67 
68 ## Building from Source
69 
70 HWSD is a cross-platform library, designed to run on any modern
71 operating system, including all Unix variants and the Windows operating
72 system. Zeroconf support in Lunchbox is required for the DNS_SD module
73 and applications. The following platforms and build environments are
74 tested:
75 
76 * Linux: Ubuntu 16.04, RHEL 6.8 (Makefile, Ninja)
77 * Windows: 7 (Visual Studio 2012)
78 * Mac OS X: 10.9 (Makefile, Ninja)
79 
80 The build system is using CMake, with the standard CMake build process:
81 
82  git clone --recursive https://github.com/Eyescale/hwsd.git
83  mkdir hwsd/build
84  cd hwsd/build
85  cmake -GNinja .. -DCLONE_SUBPROJECTS=ON
86  ninja
87 
88 A ZeroConf implementation is required for the dns_sd module and the
89 daemon. On Mac OS X it is part of the operating system, on Linux AVAHI
90 is tested ('sudo apt-get install libavahi-compat-libdnssd-dev' on
91 Ubuntu), on Windows use the
92 [Bonjour SDK](https://developer.apple.com/downloads/index.action?q=Bonjour%20SDK%20for%20Windows).
93 If no ZeroConf implementation is found, HW-SD is only compiled with
94 local discovery modules.
95 
96 ## Bugs
97 
98 Please file a [Bug Report](https://github.com/Eyescale/hwsd/issues) if
99 you find any issue with this software.
100 
101 ## Usage
102 
103 An application can use the discovery by linking the relevant module
104 libraries, instantiating the modules in the code and then quering the
105 instantiated modules. The following will find all remote and local GPUs
106 and local network interfaces on Windows:
107 
108  #include <hwsd/hwsd.h>
109 
110  hwsd::gpu::wgl::Module::use();
111  hwsd::gpu::dns_sd::Module::use();
112  const hwsd::GPUInfos& gpus = hwsd::discoverGPUInfos();
113 
114  hwsd::net::sys::Module::use();
115  const hwsd::NetInfos& nets = hwsd::discoverNetInfos();
116 
117 Filters are chainable functors which can be passed to the query function
118 to discard information. The following filters are provided:
119 
120 * DuplicateFilter eliminates duplicates, e.g., when one announcement is
121  seen on multiple interfaces
122 * MirrorFilter eliminates the same GPU with a different type, e.g., when
123  enabling both the cgl and glx module on Mac OS X.
124 * SessionFilter discards all resources not belonging to a given session