1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright(c) 2019-2021 Broadcom 3 * All rights reserved. 4 */ 5 6 #ifndef _TF_SESSION_H_ 7 #define _TF_SESSION_H_ 8 9 #include <stdint.h> 10 #include <stdlib.h> 11 12 #include "bitalloc.h" 13 #include "tf_core.h" 14 #include "tf_device.h" 15 #include "tf_rm.h" 16 #include "tf_tbl.h" 17 #include "tf_resources.h" 18 #include "stack.h" 19 #include "ll.h" 20 21 /** 22 * The Session module provides session control support. A session is 23 * to the ULP layer known as a session_info instance. The session 24 * private data is the actual session. 25 * 26 * Session manages: 27 * - The device and all the resources related to the device. 28 * - Any session sharing between ULP applications 29 */ 30 31 /** Session defines 32 */ 33 #define TF_SESSION_ID_INVALID 0xFFFFFFFF /** Invalid Session ID define */ 34 35 /** 36 * At this stage we are using fixed size entries so that each 37 * stack entry represents either 2 or 4 RT (f/n)blocks. So we 38 * take the total block allocation for truflow and divide that 39 * by either 2 or 4. 40 */ 41 #ifdef TF_EM_ENTRY_IPV4_ONLY 42 #define TF_SESSION_EM_ENTRY_SIZE 2 /* 2 blocks per entry */ 43 #else 44 #define TF_SESSION_EM_ENTRY_SIZE 4 /* 4 blocks per entry */ 45 #endif 46 47 /** 48 * Session 49 * 50 * Shared memory containing private TruFlow session information. 51 * Through this structure the session can keep track of resource 52 * allocations and (if so configured) any shadow copy of flow 53 * information. It also holds info about Session Clients. 54 * 55 * Memory is assigned to the Truflow instance by way of 56 * tf_open_session. Memory is allocated and owned by i.e. ULP. 57 * 58 * Access control to this shared memory is handled by the spin_lock in 59 * tf_session_info. 60 */ 61 struct tf_session { 62 /** TrueFlow Version. Used to control the structure layout 63 * when sharing sessions. No guarantee that a secondary 64 * process would come from the same version of an executable. 65 */ 66 struct tf_session_version ver; 67 68 /** 69 * Session ID, allocated by FW on tf_open_session() 70 */ 71 union tf_session_id session_id; 72 73 /** 74 * Boolean controlling the use and availability of shadow 75 * copy. Shadow copy will allow the TruFlow Core to keep track 76 * of resource content on the firmware side without having to 77 * query firmware. Additional private session core_data will 78 * be allocated if this boolean is set to 'true', default 79 * 'false'. 80 * 81 * Size of memory depends on the NVM Resource settings for the 82 * control channel. 83 */ 84 bool shadow_copy; 85 86 /** 87 * Session Reference Count. To keep track of functions per 88 * session the ref_count is updated. There is also a 89 * parallel TruFlow Firmware ref_count in case the TruFlow 90 * Core goes away without informing the Firmware. 91 */ 92 uint8_t ref_count; 93 94 /** 95 * Session Reference Count for attached sessions. To keep 96 * track of application sharing of a session the 97 * ref_count_attach is updated. 98 */ 99 uint8_t ref_count_attach; 100 101 /** 102 * Device handle 103 */ 104 struct tf_dev_info dev; 105 /** 106 * Device init flag. False if Device is not fully initialized, 107 * else true. 108 */ 109 bool dev_init; 110 111 /** 112 * Linked list of clients registered for this session 113 */ 114 struct ll client_ll; 115 }; 116 117 /** 118 * Session Client 119 * 120 * Shared memory for each of the Session Clients. A session can have 121 * one or more clients. 122 */ 123 struct tf_session_client { 124 /** 125 * Linked list of clients 126 */ 127 struct ll_entry ll_entry; /* For inserting in link list, must be 128 * first field of struct. 129 */ 130 131 /** 132 * String containing name of control channel interface to be 133 * used for this session to communicate with firmware. 134 * 135 * ctrl_chan_name will be used as part of a name for any 136 * shared memory allocation. 137 */ 138 char ctrl_chan_name[TF_SESSION_NAME_MAX]; 139 140 /** 141 * Firmware FID, learned at time of Session Client create. 142 */ 143 uint16_t fw_fid; 144 145 /** 146 * Session Client ID, allocated by FW on tf_register_session() 147 */ 148 union tf_session_client_id session_client_id; 149 }; 150 151 /** 152 * Session open parameter definition 153 */ 154 struct tf_session_open_session_parms { 155 /** 156 * [in] Pointer to the TF open session configuration 157 */ 158 struct tf_open_session_parms *open_cfg; 159 }; 160 161 /** 162 * Session attach parameter definition 163 */ 164 struct tf_session_attach_session_parms { 165 /** 166 * [in] Pointer to the TF attach session configuration 167 */ 168 struct tf_attach_session_parms *attach_cfg; 169 }; 170 171 /** 172 * Session close parameter definition 173 */ 174 struct tf_session_close_session_parms { 175 /** 176 * [] 177 */ 178 uint8_t *ref_count; 179 /** 180 * [] 181 */ 182 union tf_session_id *session_id; 183 }; 184 185 /** 186 * @page session Session Management 187 * 188 * @ref tf_session_open_session 189 * 190 * @ref tf_session_attach_session 191 * 192 * @ref tf_session_close_session 193 * 194 * @ref tf_session_is_fid_supported 195 * 196 * @ref tf_session_get_session_internal 197 * 198 * @ref tf_session_get_session 199 * 200 * @ref tf_session_get_session_client 201 * 202 * @ref tf_session_find_session_client_by_name 203 * 204 * @ref tf_session_find_session_client_by_fid 205 * 206 * @ref tf_session_get_device 207 * 208 * @ref tf_session_get_fw_session_id 209 * 210 * @ref tf_session_get_session_id 211 */ 212 213 /** 214 * Creates a host session with a corresponding firmware session. 215 * 216 * [in] tfp 217 * Pointer to TF handle 218 * 219 * [in] parms 220 * Pointer to the session open parameters 221 * 222 * Returns 223 * - (0) if successful. 224 * - (-EINVAL) on failure. 225 */ 226 int tf_session_open_session(struct tf *tfp, 227 struct tf_session_open_session_parms *parms); 228 229 /** 230 * Attaches a previous created session. 231 * 232 * [in] tfp 233 * Pointer to TF handle 234 * 235 * [in] parms 236 * Pointer to the session attach parameters 237 * 238 * Returns 239 * - (0) if successful. 240 * - (-EINVAL) on failure. 241 */ 242 int tf_session_attach_session(struct tf *tfp, 243 struct tf_session_attach_session_parms *parms); 244 245 /** 246 * Closes a previous created session. Only possible if previous 247 * registered Clients had been unregistered first. 248 * 249 * [in] tfp 250 * Pointer to TF handle 251 * 252 * [in/out] parms 253 * Pointer to the session close parameters. 254 * 255 * Returns 256 * - (0) if successful. 257 * - (-EUSERS) if clients are still registered with the session. 258 * - (-EINVAL) on failure. 259 */ 260 int tf_session_close_session(struct tf *tfp, 261 struct tf_session_close_session_parms *parms); 262 263 /** 264 * Verifies that the fid is supported by the session. Used to assure 265 * that a function i.e. client/control channel is registered with the 266 * session. 267 * 268 * [in] tfs 269 * Pointer to TF Session handle 270 * 271 * [in] fid 272 * FID value to check 273 * 274 * Returns 275 * - (true) if successful, else false 276 * - (-EINVAL) on failure. 277 */ 278 bool 279 tf_session_is_fid_supported(struct tf_session *tfs, 280 uint16_t fid); 281 282 /** 283 * Looks up the private session information from the TF session 284 * info. Does not perform a fid check against the registered 285 * clients. Should be used if tf_session_get_session() was used 286 * previously i.e. at the TF API boundary. 287 * 288 * [in] tfp 289 * Pointer to TF handle 290 * 291 * [out] tfs 292 * Pointer pointer to the session 293 * 294 * Returns 295 * - (0) if successful. 296 * - (-EINVAL) on failure. 297 */ 298 int tf_session_get_session_internal(struct tf *tfp, 299 struct tf_session **tfs); 300 301 /** 302 * Looks up the private session information from the TF session 303 * info. Performs a fid check against the clients on the session. 304 * 305 * [in] tfp 306 * Pointer to TF handle 307 * 308 * [out] tfs 309 * Pointer pointer to the session 310 * 311 * Returns 312 * - (0) if successful. 313 * - (-EINVAL) on failure. 314 */ 315 int tf_session_get_session(struct tf *tfp, 316 struct tf_session **tfs); 317 318 /** 319 * Looks up client within the session. 320 * 321 * [in] tfs 322 * Pointer pointer to the session 323 * 324 * [in] session_client_id 325 * Client id to look for within the session 326 * 327 * Returns 328 * client if successful. 329 * - (NULL) on failure, client not found. 330 */ 331 struct tf_session_client * 332 tf_session_get_session_client(struct tf_session *tfs, 333 union tf_session_client_id session_client_id); 334 335 /** 336 * Looks up client using name within the session. 337 * 338 * [in] session, pointer to the session 339 * 340 * [in] session_client_name, name of the client to lookup in the session 341 * 342 * Returns: 343 * - Pointer to the session, if found. 344 * - (NULL) on failure, client not found. 345 */ 346 struct tf_session_client * 347 tf_session_find_session_client_by_name(struct tf_session *tfs, 348 const char *ctrl_chan_name); 349 350 /** 351 * Looks up client using the fid. 352 * 353 * [in] session, pointer to the session 354 * 355 * [in] fid, fid of the client to find 356 * 357 * Returns: 358 * - Pointer to the session, if found. 359 * - (NULL) on failure, client not found. 360 */ 361 struct tf_session_client * 362 tf_session_find_session_client_by_fid(struct tf_session *tfs, 363 uint16_t fid); 364 365 /** 366 * Looks up the device information from the TF Session. 367 * 368 * [in] tfp 369 * Pointer to TF handle 370 * 371 * [out] tfd 372 * Pointer pointer to the device 373 * 374 * Returns 375 * - (0) if successful. 376 * - (-EINVAL) on failure. 377 */ 378 int tf_session_get_device(struct tf_session *tfs, 379 struct tf_dev_info **tfd); 380 381 /** 382 * Looks up the FW Session id the requested TF handle. 383 * 384 * [in] tfp 385 * Pointer to TF handle 386 * 387 * [out] session_id 388 * Pointer to the session_id 389 * 390 * Returns 391 * - (0) if successful. 392 * - (-EINVAL) on failure. 393 */ 394 int tf_session_get_fw_session_id(struct tf *tfp, 395 uint8_t *fw_session_id); 396 397 /** 398 * Looks up the Session id the requested TF handle. 399 * 400 * [in] tfp 401 * Pointer to TF handle 402 * 403 * [out] session_id 404 * Pointer to the session_id 405 * 406 * Returns 407 * - (0) if successful. 408 * - (-EINVAL) on failure. 409 */ 410 int tf_session_get_session_id(struct tf *tfp, 411 union tf_session_id *session_id); 412 413 #endif /* _TF_SESSION_H_ */ 414