From The Linux Foundation
Contents |
[edit] LibToDB Tool
The libtodb tool is developed to speed up the addition of new library into LSB Database. This tool uses `readelf` to get the DWARF info from a library, It parses the output of `readelf` and then puts it in a format which can be compared or inserted into the LSB Database.
[edit] LibtoDB home
lsbcvs/tools/scripts/libtodb
[edit] Things to do/know before using tool
Before using this tool I strongly recommend setting up a local copy of the SpecDatabase LSB specification database. If you remotely run libtodb against a central LSB mysql server, it will execute painfully slow. (It makes many, many database queries.).
You need to know following information about library before you insert into LSB Database. This information would be required by tool.
| Information | Used by option | Description | Required/Optional | |
| Library run time name | -S | grep SONAME | R | |
| Header Name | -H | Header file used by library and path should be relative to /usr/include | R | |
| Standard | -s | Standard (either an FSG approved spec, an ISO spec, an IETF RFC on the standards track or from an organization in liaison with ISO) defines the Interface or Interfaces entered using this tool. DB index (DBi) is a index value of standard entry, can be found from specdb/Standard.init file, if standard DOESN'T EXIST THEN CREATE ONE. If NO standard defined for an interface then use LSB STANDARD, index value of LSB is 10 | R | |
| Module | -M | Module this library belongs. DB index (DBi) is a index value of Module entry in specdb/Module.init file. if entry DOESN'T EXIST THEN CREATE ONE | R | |
| Host Architecture | -A | Architecture of machine where debugged version of library was compiled (refer Architecture.init to find appropriate string e.g. IA32) This architecture info is used to enter size and offset data of different datatype appropriately | R | |
| Architecture | -a | By Default interfaces is added for all architecture, you can override by specifying the architecture | O | |
| Library Group | -L | This option is used to specify the LibGroup Name. This is optional when inserting interfaces into DB. Default will take if not specified. | O | |
| Exclude/Include interface | -l/-x | By default this tool insert all the exported interfaces in given library, you can control that by creating a include or exclude list, file has to have one symbol per line | O | |
| Exclude/Include type | -X/-T | Tool enters all the datatype associated with public interfaces, but in certain cases that may not be the complete list of datatypes, so you can use this option to force to add missing types. You can specifiy the list in the form of exclude or include. List one interface per line in a file. Specify path of that file (File name is optional for -X, switch required to enable this feature). | O | |
| Opaque datatypes | -o | List of data type, which appears as opaque reference in header file. List one interface per line in a file. Specify path of that file. | O | |
| Regular expression | -e | Exclude interfaces matches the regex | O | |
| Constants | -c | List all the #define in a file in a given specific format, format should be <type>#define identifier token-sequence or <type>#define identifier (identifier-list) token-seq. Here <type> is as defined in the database Constants.Ctype field. Default value of type is int if type is not defined in angle bracket. e.g. <>#define MAX 256 | O |
NOTE:
- Replace <> bracket with appropriate value.
- You can create #define file using mkconstfile -h <header path>. Script is in lsbcvs/tools/scripts and <header path> is relative to /usr/include. User needs to capture the output and hand edit for #define type. Refer specdb/Constant.sql file for possible type value.
User need to build a debug version of the library, most cases you can do this by specifying --enable-debug switch during configuration, otherwise either look for an option or modify makefile.
To run libtodb, you'll need to pass the parameters it needs for connecting to the mysql server along with other option. You can feed it command-line options, as detailed in the output of './libtodb -h' or, you can set the environment variables as suggested in SpecDatabaseUsage LSB spec DB setup wiki page for DB connection.
[edit] Usage
`./libtodb [options] <library filename>`
e.g. for glib `./libtodb -q -H glib-2.0/glib.h -i -M 4 -s 96 -S libglib-2.0.so.0 -A IA32 -X ./extype.list -x ./ex.list -c ./const.def ~user/glib-2.0/libglib-2.0.so.0.600.4`
NOTE: I strongly encourage you to read the tool help before using it.
[edit] Assumptions
- Tool adds size of a datatype for the specified architecture in ArchType table, and then expect user to run devchk, which will report the missing information (ArchTypeMem, offset, etc) for datatype and #defines. Capture all the sql statements in file and run through SQL prompt using `source <sql-stmt-filename>` command, and repeat devchk execution till it fix all the missing information. Instruction to run devchk is given below in Miscellaneous sub section. This exercise should be performed on all the supported platform.
- This tool is not designed for multiple architecture and made a design decision for not handling architecture specific issues. There are couple of reason for that a) DWARF doesnât give any information about other architecture b) Libraries we will be adding in future may not have many architecture related stuff.
- Because the DWARF address 0 is taken to implicitly be the void type, I have taken the liberty of assuming that the Type entry with Tid=1 is the void entry. This is only in a few places, but it's handy. It can easily be fixed later, if this is problematic.
[edit] Miscellaneous
This section list the instructions to run other tools which consumes data insert by libtodb tool. This section just capture what I learned during validation of libtodb tool, so may not be complete. Ideally this page just cross reference the respective tool wiki pages.
[edit] Instruction to run devchk
- Go to lsbcvs/test/misc/devchk directory
- 2. Run `./Setup` (It will create the test cases for all libraries in the database)
- 3. If successfully done step 2, then `cd` to `ts/devchk`
- 4. Do `make` (It should build a binary name hdrchk)
- 5. Run `./hdrchk`
[edit] devchk FAQ
- Make sure you are running devchk against the right set of header file, devchk uses header file available in /usr/include while building. It may be possible to have different header file then you used for building debug version of library. One possible fix is update the header in /usr/include
- If library has opaque references, then you need to create <testfilename>.inc with dummy definition in ts/devchk directory (Refer old file in that directory). After that you should start again from step 1.
- By default tool only include header file in /usr/include if your library depends on header file in other directory then you need to specify them in <testfilename>.inc. After that you should start again from step 1.
[edit] Instruction to build headers/stub library
Building Headers
- Go to `lsbcvs/build_env/headers`
- 2. Run `make headers-All` (It will create header file as well as *.def file used by specs)
Building stub library
- Go to `lsbcvs/build_env/stub_libs`
- 2. `make dbfiles` (It pulls all the data from DB and create *.c files)
- 3. `make` (It will build .so file for host architecture)
[edit] Insider Info
The tool itself is organized into several smaller units.
In the beginning, the script handles command-line options, sets up sql queries, and does some housekeeping necessary to parse the DWARF info.
Next, the script reads the DWARF information from the library whose name it is given. (This is the loop containing get_level1_record().) get_level1_record() calls a whole bunch of functions, which also call each other. This whole system is composed of the functions beginning with "parse", and is in the section labeled "DWARF parsing subroutines". It puts all of this information into a few internal hashes.
The section titled "DB reading functions" contains subroutines that build a tree of hashes, rooted at an interface. The script currently builds one such tree for every interface that it sees in the public section of the DWARF information that it already parsed.
The section titled "Print naked reports" contains subroutines that take one of the trees constructed above and output them in a tree-like format; this makes their structure visible. It's mostly there for debugging, but might also be useful to be a way to simplify hand-editing in exceptional cases that this script might not handle. It's also a good example of how to traverse the interface trees.
The section titled "Database Editing" adds parsed DWARF interfaces to the database. Approach here is top down, It starts adding the interface and adds all the relevant data type and so on.
The section titled "#define handling" handles the addition of #defines.
To add comments to this page, click on [wiki:FooPage/Comments User Comments] and select edit.
[[Include(FooPage/Comments)]]