This lesson will show you how to prepare a YANG module and build the Server Instrumentation Library (SIL) that will be used to hold the instrumentation code you will write.



Pre-requisites

You should have installed and configured YumaPro SDK as described in the YumaPro SDK Installation Manual



Working with YANG module and Creating the SIL Source Code


Instrumentation used by the server for various system attributes, interface counters, configuration data, etc., is provided by Server Instrumentation Libraries (SILs) which contain the code that hooks the YANG data model into the system. Creating SILs is heavily automated and shields the developer from the inner workings of NETCONF, the transaction model, protocol encoding, etc. The process is as follows:

 

  1. have your YANG module ready and store in location that the server has access to
  2. run make_sil_dir_pro with the YANG module you are working on to generate SIL source code
  3. add instrumentation to the code stubs in the source code files
  4. make and install
  5. load the YANG module and the SIL into the server


These steps will now be explained in more detail.


There is no any specific steps to prepare your YANG module, all you need to do is to make the YANG module visible to the server, store it in the location that the server has access to.


First, the easiest way to provide the server access to your modules is to store them in $HOME/modules. This is the first location the server and other tools and application are looking for modules. Note, that this is the first location where the server looks for modules and if the server finds a module there it will not look anywhere else.

Also, it is possible to create a work directory so your work in progress will not conflict with existing modules such as those provided by YumaPro SDK. In this case you will need to add the work directory you choose to YumaPro SDK’s search path using the YUMAPRO_MODPATH environment variable:


john> mkdir $HOME/modules
john> cd $HOME/modules

OR
john> mkdir ~/work
john> cd ~/work
work> YUMAPRO_MODPATH=~/work
work> export YUMAPRO_MODPATH


If you chose to use variable and your work directory you will probably want to set YUMAPRO_MODPATH to your work directory in your system startup so it is set for your work even after a reboot.


For more on YumaPro environment variables see YumaPro User Manual section Environment Variables


Then copy the YANG module you will be working on into your $HOME/modules or working directory. For example, in this lesson we are going to use the ietf-interfaces.yang module (refer to attachments). Create the SIL source code that will be used for development using the YumaPro SDK tool make_sil_dir_pro as shown below:


work> cp /usr/share/yumapro/modules/ietf/RFC/ietf-interfaces.yang  .
work> make_sil_dir_pro --split ietf-interfaces --sil-get2 --sil-edit2


These parameters, --sil-get2 and --sil-edit2 signal make_sil_dir_pro to generate the SIL code with YumaPro SDK’s 2nd generation callbacks for operational and configuration data. These parameters will be described in more details in the next lessons.


The output of make_sil_dir_pro may look something as follows:


modparms =  --sil-get2 --sil-edit2

*** /home/john/work/temp/ietf-interfaces.yang
*** 0 Errors, 0 Warnings


*** /home/john/work/temp/ietf-interfaces.yang
*** 0 Errors, 0 Warnings


*** /home/john/work/temp/ietf-interfaces.yang
*** 0 Errors, 0 Warnings


*** /home/john/work/temp/ietf-interfaces.yang
*** 0 Errors, 0 Warnings

Run the following commands to get started:

  cd ietf-interfaces
  make doc
  make opendoc

john@U18D-VM-YP-work work$ ls -al ietf-interfaces/src
total 112
drwxrwxr-x 2 john john  4096 Jul 14 19:04 .
drwxrwxr-x 5 john john  4096 Jul 14 19:04 ..
-rw-rw-r-- 1 john john  9646 Jul 14 19:04 Makefile
-rw-rw-r-- 1 john john 38530 Jul 14 19:04 u_ietf-interfaces.c
-rw-rw-r-- 1 john john 14270 Jul 14 19:04 u_ietf-interfaces.h
-rw-rw-r-- 1 john john 28304 Jul 14 19:04 y_ietf-interfaces.c
-rw-rw-r-- 1 john john  4708 Jul 14 19:04 y_ietf-interfaces.h


This creates a directory with the same name as the YANG module, in this instance ietf-interfaces. Refer to attachments for sample SIL code for this module. Within that directory there is a bin, lib and src directory. The src directory contains the generated source files used to build the SIL:



Generated filesDescription
Makefilemakefile to control the building and installation of the SIL
u_ietf-interfaces.cuser source code for the YANG module
u_ietf-interfaces.huser header file for the YANG module
y_ietf-interfaces.cYumaPro system source code for the YANG module
y_ietf-interfaces.hYumaPro system header file for the YANG module



There are two types of source files, u_* user files and y_* YumaPro system files:


The u_* files contains the user callback functions needed to hook the YANG defined operational and configuration data to the underlying system. The code stubs in this file are typically replaced by the developer with system-specific function calls to commit database changes or retrieve data.  


The y_* files contain the system code that allows SILs to be protocol and encoding independent and includes the integration code to hook the user callback code into the transaction engine. You shouldn’t modify these files.



For more information see the YumaPro Developer Manual section SIL Shared Libraries  and the make_sil_dir_pro manual page:

    mydir> man make_sil_dir_pro


Now, we have YANG module and SIL code built and ready. The next steps will illustrates what is in the SIL code in more details and how to build, install and load YANG module and its SIL code into the netconfd-pro server.


Doxygen documentation

You may have noticed that after make_sil_dir_pro finished the following was displayed:


Run the following commands to get started:

  cd ietf-interfaces
  make doc
  make opendoc

These are the instructions to generate the doxygen content and add it to the YumaPro Doxygen Browser.


Follow the instructions, cd to the new ietf-interfaces SIL directory and execute "make doc":


john@U18D-VM-YP-work work$ cd ietf-interfaces/
john@U18D-VM-YP-work ietf-interfaces$ make doc
DOXY_UTIL=/usr/share/yumapro/util doxygen /usr/share/yumapro/util/Doxyfile.sil
Notice: Output directory `output' does not exist. I have created it for you.
Searching for include files...
Searching for example files...
Searching for images...
Searching for files in directory /usr/share/yumapro/util

   ...

Patching output file 558/559
Patching output file 559/559
lookup cache used 8026/65536 hits=69961 misses=8338
finished...

Documentation created in /home/john/work/ietf-interfaces/output directory
file:///home/john/work/ietf-interfaces/output/html/index.html

Run 'make opendoc' to open the doxygen documentation in the default browser


Then execute "make opendoc". This will open your default browser to the YumaPro Doxygen Browser Home page as shown below:



Select: Modules | YANG Library | Module ietf-interface


This will display the APIs of the newly created ietf-interfaces module. Selecting one, such as y_if_T_interface, will display the associated collaboration diagram as shown below. 




You can hover over any of the elements to display a short description and select them to go to their detail page such as ncx_idlink_t in the top left of the diagram above goes to the reference page shown below:




More information on the YumaPro Doxygen Browser can be found here: YumaPro SDK Documentation  and in the  FAQ.




Next Lesson: YANG and SIL Module Components