1 /**************************************************************************
2  *
3  * Copyright 2012 Francisco Jerez
4  * All Rights Reserved.
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a
7  * copy of this software and associated documentation files (the
8  * "Software"), to deal in the Software without restriction, including
9  * without limitation the rights to use, copy, modify, merge, publish,
10  * distribute, sub license, and/or sell copies of the Software, and to
11  * permit persons to whom the Software is furnished to do so, subject to
12  * the following conditions:
13  *
14  * The above copyright notice and this permission notice (including the
15  * next paragraph) shall be included in all copies or substantial portions
16  * of the Software.
17  *
18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
19  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT.
21  * IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
22  * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
23  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
24  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25  *
26  **************************************************************************/
27 
28 /**
29  * \file Library that provides device enumeration and creation of
30  * winsys/pipe_screen instances.
31  */
32 
33 #ifndef PIPE_LOADER_H
34 #define PIPE_LOADER_H
35 
36 #include "pipe/p_compiler.h"
37 #include "frontend/drm_driver.h"
38 #include "util/xmlconfig.h"
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43 
44 struct pipe_screen;
45 struct drisw_loader_funcs;
46 
47 enum pipe_loader_device_type {
48    PIPE_LOADER_DEVICE_SOFTWARE,
49    PIPE_LOADER_DEVICE_PCI,
50    PIPE_LOADER_DEVICE_PLATFORM,
51    NUM_PIPE_LOADER_DEVICE_TYPES
52 };
53 
54 /**
55  * A device known to the pipe loader.
56  */
57 struct pipe_loader_device {
58    enum pipe_loader_device_type type;
59 
60    union {
61       struct {
62          int vendor_id;
63          int chip_id;
64       } pci;
65    } u; /**< Discriminated by \a type */
66 
67    char *driver_name;
68    const struct pipe_loader_ops *ops;
69 
70    driOptionCache option_cache;
71    driOptionCache option_info;
72 };
73 
74 /**
75  * Get a list of known devices.
76  *
77  * \param devs Array that will be filled with pointers to the devices
78  *             available in the system.
79  * \param ndev Maximum number of devices to return.
80  * \return Number of devices available in the system.
81  */
82 int
83 pipe_loader_probe(struct pipe_loader_device **devs, int ndev);
84 
85 /**
86  * Create a pipe_screen for the specified device.
87  *
88  * \param dev Device the screen will be created for.
89  */
90 struct pipe_screen *
91 pipe_loader_create_screen(struct pipe_loader_device *dev);
92 
93 /**
94  * Ensure that dev->option_cache is initialized appropriately for the driver.
95  *
96  * This function can be called multiple times.
97  *
98  * \param dev Device for which options should be loaded.
99  */
100 void
101 pipe_loader_load_options(struct pipe_loader_device *dev);
102 
103 /**
104  * Get the driinfo XML string used by the given driver.
105  *
106  * The returned string is heap-allocated.
107  */
108 char *
109 pipe_loader_get_driinfo_xml(const char *driver_name);
110 
111 /**
112  * Release resources allocated for a list of devices.
113  *
114  * Should be called when the specified devices are no longer in use to
115  * release any resources allocated by pipe_loader_probe.
116  *
117  * \param devs Devices to release.
118  * \param ndev Number of devices to release.
119  */
120 void
121 pipe_loader_release(struct pipe_loader_device **devs, int ndev);
122 
123 /**
124  * Initialize sw dri device give the drisw_loader_funcs.
125  *
126  * This function is platform-specific.
127  *
128  * Function does not take ownership of the fd, but duplicates it locally.
129  * The local fd is closed during pipe_loader_release.
130  *
131  * \sa pipe_loader_probe
132  */
133 bool
134 pipe_loader_sw_probe_dri(struct pipe_loader_device **devs,
135                          const struct drisw_loader_funcs *drisw_lf);
136 
137 /**
138  * Initialize a kms backed sw device given an fd.
139  *
140  * This function is platform-specific.
141  *
142  * Function does not take ownership of the fd, but duplicates it locally.
143  * The local fd is closed during pipe_loader_release.
144  *
145  * \sa pipe_loader_probe
146  */
147 bool
148 pipe_loader_sw_probe_kms(struct pipe_loader_device **devs, int fd);
149 
150 /**
151  * Initialize a null sw device.
152  *
153  * This function is platform-specific.
154  *
155  * \sa pipe_loader_probe
156  */
157 bool
158 pipe_loader_sw_probe_null(struct pipe_loader_device **devs);
159 
160 /**
161  * Get a list of known software devices.
162  *
163  * This function is platform-specific.
164  *
165  * \sa pipe_loader_probe
166  */
167 int
168 pipe_loader_sw_probe(struct pipe_loader_device **devs, int ndev);
169 
170 /**
171  * Get a software device wrapped atop another device.
172  *
173  * This function is platform-specific.
174  *
175  * \sa pipe_loader_probe
176  */
177 boolean
178 pipe_loader_sw_probe_wrapped(struct pipe_loader_device **dev,
179                              struct pipe_screen *screen);
180 
181 /**
182  * Get a list of known DRM devices.
183  *
184  * This function is platform-specific.
185  *
186  * \sa pipe_loader_probe
187  */
188 int
189 pipe_loader_drm_probe(struct pipe_loader_device **devs, int ndev);
190 
191 /**
192  * Initialize a DRM device in an already opened fd.
193  *
194  * This function is platform-specific.
195  *
196  * \sa pipe_loader_probe
197  */
198 bool
199 pipe_loader_drm_probe_fd(struct pipe_loader_device **dev, int fd);
200 
201 /**
202  * Get the dri options used for the DRM driver of the given name, if any.
203  *
204  * The returned array is heap-allocated.
205  */
206 const struct driOptionDescription *
207 pipe_loader_drm_get_driconf_by_name(const char *driver_name, unsigned *count);
208 
209 #ifdef __cplusplus
210 }
211 #endif
212 
213 #endif /* PIPE_LOADER_H */
214