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 :
9 : /* A link in the topology is either unpolled or polled. Almost all
10 : links are polled, which means a tile which has this link as an in
11 : will read fragments from it and pass them to the tile handling
12 : code. An unpolled link will not read off the link by default and
13 : the user code will need to specifically read it as needed. */
14 :
15 3 : #define FD_TOPOB_UNPOLLED 0
16 90 : #define FD_TOPOB_POLLED 1
17 :
18 : /* A reliable link is a flow controlled one, where the producer will
19 : not send fragments if any downstream consumer does not have enough
20 : capacity (credits) to handle it. */
21 :
22 39 : #define FD_TOPOB_UNRELIABLE 0
23 54 : #define FD_TOPOB_RELIABLE 1
24 :
25 : FD_PROTOTYPES_BEGIN
26 :
27 : /* Initialize a new fd_topo_t with the given app name and at the memory address
28 : provided. Returns the topology at given address. The topology will be empty
29 : with no tiles, objects, links. */
30 :
31 : fd_topo_t *
32 : fd_topob_new( void * mem,
33 : char const * app_name );
34 :
35 : /* Add a workspace with the given name to the topology. Workspace names
36 : must be unique and adding the same workspace twice will produce an
37 : error. */
38 :
39 : void
40 : fd_topob_wksp( fd_topo_t * topo,
41 : char const * name );
42 :
43 : /* Add an object with the given name to the toplogy. An object is
44 : something that takes up space in memory, in a workspace.
45 :
46 : The workspace must exist and have been added to the topology.
47 : Adding an object will cause it to occupt space in memory, but not
48 : be mapped into any tiles. If you wish the object to be readable or
49 : writable by a tile, you need to add a fd_topob_tile_uses relationship. */
50 :
51 : fd_topo_obj_t *
52 : fd_topob_obj( fd_topo_t * topo,
53 : char const * obj_name,
54 : char const * wksp_name );
55 :
56 : /* Add a relationship saying that a certain tile uses a given object.
57 : This has the effect that when memory mapping required workspaces
58 : for a tile, it will map the workspace required for this object in
59 : the appropriate mode.
60 :
61 : mode should be one of FD_SHMEM_JOIN_MODE_READ_ONLY or
62 : FD_SHMEM_JOIN_MODE_READ_WRITE. */
63 :
64 : void
65 : fd_topob_tile_uses( fd_topo_t * topo,
66 : fd_topo_tile_t * tile,
67 : fd_topo_obj_t * obj,
68 : int mode );
69 :
70 : /* Add a link to the toplogy. The link will not have any producer or
71 : consumer(s) by default, and those need to be added after. The link
72 : can have no backing data buffer, a dcache, or a reassembly buffer
73 : behind it. */
74 :
75 : void
76 : fd_topob_link( fd_topo_t * topo,
77 : char const * link_name,
78 : char const * wksp_name,
79 : int is_reasm,
80 : ulong depth,
81 : ulong mtu,
82 : ulong burst );
83 :
84 : /* Add a tile to the topology. This creates various objects needed for
85 : a standard tile, including tile scratch memory, metrics memory and so
86 : on. These objects will be created and linked to the respective
87 : workspaces provided, and the tile will be specified to map those
88 : workspaces when it is attached. */
89 :
90 : fd_topo_tile_t *
91 : fd_topob_tile( fd_topo_t * topo,
92 : char const * tile_name,
93 : char const * tile_wksp,
94 : char const * metrics_wksp,
95 : ulong cpu_idx,
96 : int is_agave );
97 :
98 : /* Add an input link to the tile. If the tile is created with the
99 : standard mux runner, it will automatically poll the in link and
100 : forward fragments to the user code (unless the link is specified
101 : as unpolled).
102 :
103 : An input link has an fseq which is a ulong used for returning the
104 : current reader position in sequence space, used for wiring flow
105 : control to the producer. The producer will not produce fragments
106 : while any downstream consumer link is not ready to receive them,
107 : unless the link is marked as unreliable. */
108 :
109 : void
110 : fd_topob_tile_in( fd_topo_t * topo,
111 : char const * tile_name,
112 : ulong tile_kind_id,
113 : char const * fseq_wksp,
114 : char const * link_name,
115 : ulong link_kind_id,
116 : int reliable,
117 : int polled );
118 :
119 : /* Add an output link to the tile. This doesn't do much by itself,
120 : but will cause the link to get mapped in as writable for the tile,
121 : and the tile can later look up the link by name and write to it
122 : as it wants. */
123 :
124 : void
125 : fd_topob_tile_out( fd_topo_t * topo,
126 : char const * tile_name,
127 : ulong tile_kind_id,
128 : char const * link_name,
129 : ulong link_kind_id );
130 :
131 : /* Automatically layout the tiles onto CPUs in the topology for a
132 : best effort. */
133 :
134 : void
135 : fd_topob_auto_layout( fd_topo_t * topo );
136 :
137 : /* Finish creating the topology. Lays out all the objects in the
138 : given workspaces, and sizes everything correctly. Also validates
139 : the topology before returning.
140 :
141 : This must be called to finish creating the topology. */
142 :
143 : void
144 : fd_topob_finish( fd_topo_t * topo,
145 : ulong (* align )( fd_topo_t const * topo, fd_topo_obj_t const * obj ),
146 : ulong (* footprint)( fd_topo_t const * topo, fd_topo_obj_t const * obj ),
147 : ulong (* loose )( fd_topo_t const * topo, fd_topo_obj_t const * obj) );
148 :
149 : FD_PROTOTYPES_END
150 :
151 : #endif /* HEADER_fd_src_disco_topo_fd_topob_h */
|
