Line data Source code
1 : #ifndef HEADER_fd_src_disco_topo_fd_topob_h
2 : #define HEADER_fd_src_disco_topo_fd_topob_h
3 :
4 : /* fd_topob is a builder for fd_topo, providing many convenience
5 : functions for creating a useful topology. */
6 :
7 : #include "../../disco/topo/fd_topo.h"
8 : #include "fd_cpu_topo.h"
9 :
10 : /* A link in the topology is either unpolled or polled. Almost all
11 : links are polled, which means a tile which has this link as an in
12 : will read fragments from it and pass them to the tile handling
13 : code. An unpolled link will not read off the link by default and
14 : the user code will need to specifically read it as needed. */
15 :
16 0 : #define FD_TOPOB_UNPOLLED 0
17 9 : #define FD_TOPOB_POLLED 1
18 :
19 : /* A reliable link is a flow controlled one, where the producer will
20 : not send fragments if any downstream consumer does not have enough
21 : capacity (credits) to handle it. */
22 :
23 0 : #define FD_TOPOB_UNRELIABLE 0
24 9 : #define FD_TOPOB_RELIABLE 1
25 :
26 : /* Affinity entries prefixed with 's' ("s2", "s2-3") are shared, the
27 : tile is homed at that CPU but floats over the shared CPUs on the
28 : same NUMA node. The bit is set in the parsed CPU index, and only
29 : callers passing allow_shared accept it. */
30 174 : #define FD_TOPOB_CPU_SHARED (0x8000UL)
31 :
32 : /* Tile priority types used by fd_topob_auto_layout to classify tiles
33 : into scheduling categories. */
34 0 : #define FD_TOPOB_PRIORITY_FLOATING (1)
35 0 : #define FD_TOPOB_PRIORITY_STARTUP (2)
36 0 : #define FD_TOPOB_PRIORITY_NORMAL (3)
37 0 : #define FD_TOPOB_PRIORITY_CRITICAL (4)
38 :
39 : FD_PROTOTYPES_BEGIN
40 :
41 : /* Initialize a new fd_topo_t with the given app name and at the memory address
42 : provided. Returns the topology at given address. The topology will be empty
43 : with no tiles, objects, links. */
44 :
45 : fd_topo_t *
46 : fd_topob_new( void * mem,
47 : char const * app_name );
48 :
49 : /* Add a workspace with the given name to the topology. Workspace names
50 : must be unique and adding the same workspace twice will produce an
51 : error. */
52 :
53 : fd_topo_wksp_t *
54 : fd_topob_wksp( fd_topo_t * topo,
55 : char const * name );
56 :
57 : /* Add an object with the given type to the topology. An object is
58 : something that takes up space in memory, in a workspace.
59 :
60 : The workspace must exist and have been added to the topology.
61 : Adding an object will cause it to occupt space in memory, but not
62 : be mapped into any tiles. If you wish the object to be readable or
63 : writable by a tile, you need to add a fd_topob_tile_uses relationship. */
64 :
65 : fd_topo_obj_t *
66 : fd_topob_obj( fd_topo_t * topo,
67 : char const * obj_type,
68 : char const * wksp_name );
69 :
70 : /* Same as fd_topo_obj, but labels the object. */
71 :
72 : fd_topo_obj_t *
73 : fd_topob_obj_named( fd_topo_t * topo,
74 : char const * obj_type,
75 : char const * wksp_name,
76 : char const * label );
77 :
78 : /* Add a relationship saying that a certain tile uses a given object.
79 : This has the effect that when memory mapping required workspaces
80 : for a tile, it will map the workspace required for this object in
81 : the appropriate mode.
82 :
83 : mode should be one of FD_SHMEM_JOIN_MODE_READ_ONLY or
84 : FD_SHMEM_JOIN_MODE_READ_WRITE. */
85 :
86 : void
87 : fd_topob_tile_uses( fd_topo_t * topo,
88 : fd_topo_tile_t * tile,
89 : fd_topo_obj_t const * obj,
90 : int mode );
91 :
92 : /* Add a link to the topology. The link will not have any producer or
93 : consumer(s) by default, and those need to be added after. The link
94 : can have no backing data buffer, a dcache, or a reassembly buffer
95 : behind it. */
96 :
97 : fd_topo_link_t *
98 : fd_topob_link( fd_topo_t * topo,
99 : char const * link_name,
100 : char const * wksp_name,
101 : ulong depth,
102 : ulong mtu,
103 : ulong burst );
104 :
105 : /* Add a tile to the topology. This creates various objects needed for
106 : a standard tile, including tile scratch memory, metrics memory and so
107 : on. These objects will be created and linked to the respective
108 : workspaces provided, and the tile will be specified to map those
109 : workspaces when it is attached. */
110 :
111 : fd_topo_tile_t *
112 : fd_topob_tile( fd_topo_t * topo,
113 : char const * tile_name,
114 : char const * tile_wksp,
115 : char const * metrics_wksp,
116 : ulong cpu_idx,
117 : int is_agave,
118 : int uses_id_keyswitch,
119 : int uses_av_keyswitch,
120 : int is_waker_client );
121 :
122 : /* fd_topob_waker adds the waker tile and wires every tile marked
123 : is_waker_client to it. Call once after all tiles are added, in any
124 : topology containing a waker client. */
125 :
126 : void
127 : fd_topob_waker( fd_topo_t * topo );
128 :
129 : /* Add an input link to the tile. If the tile is created with fd_stem,
130 : it will automatically poll the in link and forward fragments to the
131 : user code (unless the link is specified as unpolled).
132 :
133 : An input link has an fseq which is a ulong used for returning the
134 : current reader position in sequence space, used for wiring flow
135 : control to the producer. The producer will not produce fragments
136 : while any downstream consumer link is not ready to receive them,
137 : unless the link is marked as unreliable. */
138 :
139 : void
140 : fd_topob_tile_in( fd_topo_t * topo,
141 : char const * tile_name,
142 : ulong tile_kind_id,
143 : char const * fseq_wksp,
144 : char const * link_name,
145 : ulong link_kind_id,
146 : int reliable,
147 : int polled );
148 :
149 : /* Add an output link to the tile. This doesn't do much by itself,
150 : but will cause the link to get mapped in as writable for the tile,
151 : and the tile can later look up the link by name and write to it
152 : as it wants. */
153 :
154 : void
155 : fd_topob_tile_out( fd_topo_t * topo,
156 : char const * tile_name,
157 : ulong tile_kind_id,
158 : char const * link_name,
159 : ulong link_kind_id );
160 :
161 : /* Automatically layout the tiles onto CPUs in the topology for a
162 : best effort. fd_topob_auto_layout reads CPU topology from the OS.
163 : fd_topob_auto_layout_cpus takes a pre-built CPU topology, useful
164 : for testing. */
165 :
166 : void
167 : fd_topob_auto_layout( fd_topo_t * topo,
168 : int reserve_agave_cores );
169 :
170 : void
171 : fd_topob_auto_layout_cpus( fd_topo_t * topo,
172 : fd_topo_cpus_t * cpus,
173 : int reserve_agave_cores );
174 :
175 : /* Finish creating the topology. Lays out all the objects in the
176 : given workspaces, and sizes everything correctly. Also validates
177 : the topology before returning.
178 :
179 : This must be called to finish creating the topology. */
180 :
181 : void
182 : fd_topob_finish( fd_topo_t * topo,
183 : fd_topo_obj_callbacks_t ** callbacks );
184 :
185 :
186 : /* Classify a tile name into one of the FD_TOPOB_PRIORITY_* categories. */
187 : int
188 : fd_topob_tile_priority_type( char const * name );
189 :
190 : void
191 : fd_topob_validate_cpu_overlaps( fd_topo_t const * topo );
192 :
193 : ulong
194 : fd_topob_parse_affinity_cstr( char const * cstr,
195 : ushort * tile_to_cpu,
196 : int allow_repeats,
197 : int allow_shared );
198 :
199 : FD_PROTOTYPES_END
200 :
201 : #endif /* HEADER_fd_src_disco_topo_fd_topob_h */
|
