diff options
Diffstat (limited to 'src/plugins/acl/acl_lookup_context.md')
| -rw-r--r-- | src/plugins/acl/acl_lookup_context.md | 34 |
1 files changed, 23 insertions, 11 deletions
diff --git a/src/plugins/acl/acl_lookup_context.md b/src/plugins/acl/acl_lookup_context.md index c049aae5f19..53ad1ef0e46 100644 --- a/src/plugins/acl/acl_lookup_context.md +++ b/src/plugins/acl/acl_lookup_context.md @@ -52,33 +52,32 @@ Using ACL contexts in your code In order to use the ACL lookup contexts, you need to include plugins/acl/exports.h into your code. This header includes -all the necessary dependencies required, as well as -the actual "meat" include file containing the necessary -definitions - plugins/acl/public_inlines.h +all the necessary dependencies required. As you probably will invoke this code from another plugin, the non-inline function calls are implemented via function pointers, -which you need to initialize by calling acl_plugin_exports_init(), which, -if everything succeeds, returns 0 - else it will return clib_error_t with +which you need to initialize by calling acl_plugin_exports_init(&acl_plugin), which, +if everything succeeds, returns 0 and fills in the acl_plugin structure +with pointers to the exported methods - else it will return clib_error_t with more information about what went wrong. When you have initialized the symbols, you also need to register yourself as a user of the ACL lookups - this allows to track the ACL lookup context ownership, as well as make the debug show outputs more user friendly. -To do that, call acl_plugin_register_user_module(caller_module_string, val1_label, val2_label) - +To do that, call acl_plugin.register_user_module(caller_module_string, val1_label, val2_label) - and record the returned value. This will bethe first parameter that you pass to create a new lookup context. The passed strings must be static, and are used as descriptions for the ACL contexts themselves, as well as labels for up to two user-supplied u32 labels, used to differentiate the lookup contexts for the debugging purposes. -Creating a new context is done by calling acl_plugin_get_lookup_context_index(user_id, val1, val2). +Creating a new context is done by calling acl_plugin.get_lookup_context_index(user_id, val1, val2). The first argument is your "user" ID obtained in a registration call earlier, the other two arguments are u32s with semantics that you designate. They are used purely for debugging purposes in the "show acl lookup context" command. To set the vector of ACL numbers to be looked up within the context, use the function -acl_plugin_set_acl_vec_for_context(lc_index, acl_list). The first parameter specifies the context +acl_plugin.set_acl_vec_for_context(lc_index, acl_list). The first parameter specifies the context that you have created, the second parameter is a vector of u32s, each u32 being the index of the ACL which we should be looking up within this context. The comand is idempotent, i.e. it unapplies the previously applied list of ACLs, and then sets the new list of ACLs. @@ -87,17 +86,30 @@ Subsequent ACL updates for the already applied ACLs will cause the re-applicatio on an as-needed basis. Note, that the ACL application is potentially a relatively costly operation, so it is only expected that these changes will be done in the control plane, NOT in the datapath. -The matching within the context is done using two functions - acl_plugin_fill_5tuple() and -acl_plugin_match_5tuple() and their corresponding inline versions, named acl_plugin_fill_5tuple_inline() +The matching within the context is done using two functions - acl_plugin.fill_5tuple() and +acl_plugin.match_5tuple() and their corresponding inline versions, named acl_plugin_fill_5tuple_inline() and acl_plugin_match_5tuple_inline(). The inline and non-inline versions have the equivalent functionality, in that the non-inline version calls the inline version. These two variants are provided for debugging/maintenance reasons. When you no longer need a particular context, you can return the allocated resources by calling -acl_plugin_put_lookup_context_index() to mark it as free. The lookup structured associated with +acl_plugin.put_lookup_context_index() to mark it as free. The lookup structured associated with the vector of ACLs set for the lookup are cleaned up automatically. However, the ACLs themselves are not deleted and are available for subsequent reuse by other lookup contexts if needed. +There is one delicate detail that you might want to be aware of. +When the non-inline functions reference the inline functions, +they are compiled as part of ACL plugin; whereas when you refer to the inline +functions from your code, they are compiled as part of your code. +This makes referring to a single acl_main structure a little trickier. + +It is done by having a static p_acl_main within the .h file, +which points to acl_main of the ACL plugin, and is initialized by a static constructor +function. + +This way the multiple includes and inlines will "just work" as one would expect. + + Debug CLIs ========== |