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_topob_layout.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 0 : #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 0 : #define FD_TOPOB_RELIABLE 1
25 :
26 : FD_PROTOTYPES_BEGIN
27 :
28 : /* Initialize a new fd_topo_t with the given app name and at the memory address
29 : provided. Returns the topology at given address. The topology will be empty
30 : with no tiles, objects, links. */
31 :
32 : fd_topo_t *
33 : fd_topob_new( void * mem,
34 : char const * app_name );
35 :
36 : /* Add a workspace with the given name to the topology. Workspace names
37 : must be unique and adding the same workspace twice will produce an
38 : error. */
39 :
40 : fd_topo_wksp_t *
41 : fd_topob_wksp( fd_topo_t * topo,
42 : char const * name );
43 :
44 : /* Add an object with the given type to the topology. An object is
45 : something that takes up space in memory, in a workspace.
46 :
47 : The workspace must exist and have been added to the topology.
48 : Adding an object will cause it to occupt space in memory, but not
49 : be mapped into any tiles. If you wish the object to be readable or
50 : writable by a tile, you need to add a fd_topob_tile_uses relationship. */
51 :
52 : fd_topo_obj_t *
53 : fd_topob_obj( fd_topo_t * topo,
54 : char const * obj_type,
55 : char const * wksp_name );
56 :
57 : /* Same as fd_topo_obj, but labels the object. */
58 :
59 : fd_topo_obj_t *
60 : fd_topob_obj_named( fd_topo_t * topo,
61 : char const * obj_type,
62 : char const * wksp_name,
63 : char const * label );
64 :
65 : /* Add a relationship saying that a certain tile uses a given object.
66 : This has the effect that when memory mapping required workspaces
67 : for a tile, it will map the workspace required for this object in
68 : the appropriate mode.
69 :
70 : mode should be one of FD_SHMEM_JOIN_MODE_READ_ONLY or
71 : FD_SHMEM_JOIN_MODE_READ_WRITE. Adding an object the tile already
72 : uses keeps one entry, upgraded to READ_WRITE if either mode is. */
73 :
74 : void
75 : fd_topob_tile_uses( fd_topo_t * topo,
76 : fd_topo_tile_t * tile,
77 : fd_topo_obj_t const * obj,
78 : int mode );
79 :
80 : /* Add a link to the topology. The link will not have any producer or
81 : consumer(s) by default, and those need to be added after. The link
82 : can have no backing data buffer, a dcache, or a reassembly buffer
83 : behind it. */
84 :
85 : fd_topo_link_t *
86 : fd_topob_link( fd_topo_t * topo,
87 : char const * link_name,
88 : char const * wksp_name,
89 : ulong depth,
90 : ulong mtu,
91 : ulong burst );
92 :
93 : /* Add a tile to the topology. This creates various objects needed for
94 : a standard tile, including tile scratch memory, metrics memory and so
95 : on. These objects will be created and linked to the respective
96 : workspaces provided, and the tile will be specified to map those
97 : workspaces when it is attached. */
98 :
99 : fd_topo_tile_t *
100 : fd_topob_tile( fd_topo_t * topo,
101 : char const * tile_name,
102 : char const * tile_wksp,
103 : char const * metrics_wksp,
104 : ulong cpu_idx,
105 : int uses_id_keyswitch,
106 : int uses_av_keyswitch,
107 : int is_waker_client );
108 :
109 : /* fd_topob_waker adds the waker tile and wires every tile marked
110 : is_waker_client to it. Call once after all tiles are added, in any
111 : topology containing a waker client. */
112 :
113 : void
114 : fd_topob_waker( fd_topo_t * topo );
115 :
116 : void
117 : fd_topob_sleep( fd_topo_t * topo,
118 : char const * metrics_wksp,
119 : ulong mwaitx_cpu_idx );
120 :
121 : void
122 : fd_topob_sleep_finish( fd_topo_t * topo );
123 :
124 : /* Add an input link to the tile. If the tile is created with fd_stem,
125 : it will automatically poll the in link and forward fragments to the
126 : user code (unless the link is specified as unpolled).
127 :
128 : An input link has an fseq which is a ulong used for returning the
129 : current reader position in sequence space, used for wiring flow
130 : control to the producer. The producer will not produce fragments
131 : while any downstream consumer link is not ready to receive them,
132 : unless the link is marked as unreliable. */
133 :
134 : void
135 : fd_topob_tile_in( fd_topo_t * topo,
136 : char const * tile_name,
137 : ulong tile_kind_id,
138 : char const * fseq_wksp,
139 : char const * link_name,
140 : ulong link_kind_id,
141 : int reliable,
142 : int polled );
143 :
144 : /* Add an output link to the tile. This doesn't do much by itself,
145 : but will cause the link to get mapped in as writable for the tile,
146 : and the tile can later look up the link by name and write to it
147 : as it wants. */
148 :
149 : void
150 : fd_topob_tile_out( fd_topo_t * topo,
151 : char const * tile_name,
152 : ulong tile_kind_id,
153 : char const * link_name,
154 : ulong link_kind_id );
155 :
156 : /* Finish creating the topology. Lays out all the objects in the
157 : given workspaces, and sizes everything correctly. Also validates
158 : the topology before returning.
159 :
160 : This must be called to finish creating the topology. */
161 :
162 : void
163 : fd_topob_finish( fd_topo_t * topo,
164 : fd_topo_obj_callbacks_t ** callbacks );
165 :
166 : FD_PROTOTYPES_END
167 :
168 : #endif /* HEADER_fd_src_disco_topo_fd_topob_h */
|
