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