hwip
add_ip(IP_NAME **kwargs)
This function creates an INTERFACE library for a given IP.
This function is a wrapper around the cmake built-in add_library() function. It generates the library name using the vendor, library, name, and version (VLNV) information passed in arguments (see create_ip_vlnv()). It creates two alias libraries to the default <vendor><library><name>__<version>:
- <vendor>::<library>::<name>::<version> ('__' replaced by '::')
- <vendor>::<library>::<name> (short name without the version)
This function can be used in FULL and SHORT form.
Full form:
add_ip(ip
VENDOR vendor
LIBRARY lib
VERSION 1.2.3
DESCRIPTION "This is a sample IP"
)
In full form it is possible to omit VENDOR, LIBRARY, VERSION, and DESCRIPTION, although it is not recommended.
Omitting them all would have following signature:
add_ip(ip2)
Short form:
add_ip(vendor2::lib2::ip2::1.2.2)
In short form only the full VLNV format is accepted
Parameters
| Name | Type | Description |
|---|---|---|
IP_NAME | string | The name of the IP. |
Keyword Arguments
| Name | Type | Description |
|---|---|---|
VENDOR | string | Name of the IP vendor. |
LIBRARY | string | Name of the IP library. |
VERSION | string | Version of the IP following a three-part version number (Major.Minor.Patch, e.g., 1.0.13). |
DESCRIPTION | string | Short description to be associated with the IP library, will appear in help_ips() message |
create_ip_vlnv(OUTVAR IP_NAME **kwargs)
This function creates an IP name provided vendor, library, name, and version (VLNV) information.
This function appends the vendor, library, name, and version (VLNV) information separated by '__' to create a unique string representing an IP name. This string is used as the library name when calling the cmake built-in add_library() function (see add_ip()).
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | The generate IP name. |
IP_NAME | string | The name of the IP. |
Keyword Arguments
| Name | Type | Description |
|---|---|---|
VENDOR | string | Name of the IP vendor. |
LIBRARY | string | Name of the IP library. |
VERSION | string | Version of the IP following a three-part version number (Major.Minor.Patch, e.g., 1.0.13). |
parse_ip_vlnv(IP_VLNV VENDOR LIBRARY IP_NAME VERSION **kwargs)
This function parses an IP VLNV string into its individual components.
Accepts either the full four-part format vendor::lib::ip::0.0.1 or the
short single-name format ip. The parsed values are written into the
caller's scope via the output variable names supplied as arguments.
In the short form only IP_NAME is set; VENDOR, LIBRARY, and
VERSION are unset in the parent scope. Any other number of
::-separated tokens is a fatal error.
Parameters
| Name | Type | Description |
|---|---|---|
IP_VLNV | string | The VLNV string to parse (e.g. vendor::lib::ip::0.0.1 or ip). |
VENDOR | string | Output variable name that receives the vendor field. |
LIBRARY | string | Output variable name that receives the library field. |
IP_NAME | string | Output variable name that receives the IP name field. |
VERSION | string | Output variable name that receives the version field (e.g. 1.0.13). |
ip_sources(IP_LIB LANGUAGE **kwargs)
This function adds source file(s) to an IP target.
This functions adds source file(s) under a file set to an IP target as a property named after the name of the file set, type of source file(s) and the suffix 'SOURCES'. The property is of the following format <LANGUAGE><FILE_SET>_SOURCES, in case FILE_SET is not set, DEFAULT is used. If source files of the same type already exist they are appended to the existing list. The source files can also be prepended with the optional keyword PREPEND. The source files are later used to create the list of files to be compiled (e.g., by a simulator) by a tool to execute its tasks. The source files are passed as a list after the parameters and keywords.
Relative file paths are accepted and will be converted to absolute, relative to ${CMAKE_CURRENT_SOURCE_DIR}
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | The target IP library. |
TYPE | string | The type of source file(s). |
FILE_SET | string | Specify to which file set to associate the listed files |
HEADERS | list | List of header files. Header files are stored in separate property ${LANGUAGE}_HEADERS, the include directory will also be set. |
get_ip_sources(OUTVAR IP_LIB LANGUAGE **kwargs)
This function retrieves the specific source files of a target library.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | The variable containing the retrieved source file. |
IP_LIB | string | The target IP library. |
LANGUAGE | string | The type of source file(s). |
ip_include_directories(IP_LIB LANGUAGE **kwargs)
This function adds include directory(ies) to a target library.
This function adds an interface include directory(ies) to a target library. The include directory(ies) is added with the INTERFACE option (i.e., passed to targets depending on this one). The include directories are passed as a list after the parameter.
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | The target IP library. |
LANGUAGE | string | Language of the included files. |
FILE_SET | string | Specify to which file set to associate the listed include directories |
get_ip_include_directories(OUTVAR IP_LIB LANGUAGE **kwargs)
This function retrieves the included directories of a target library and its dependencies.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | The variable containing the retrieved included directory(ies). |
IP_LIB | string | The target IP library. |
LANGUAGE | string | Language of the included files. |
ip_link(IP_LIB **kwargs)
This function adds a target link library and a dependency to an IP target.
This function gets the original target and dependency names in case an alias is given. Then it checks if the link library exists and adds it (if it's not already added). Finally, the link library is added as a dependency. This last step can be skipped with the keyword NODEPEND. The dependencies are passed as a list after the parameters and the keyword.
It is also allowed to pass version conditions to be checked as following:
ip_link(v::l::ip1::1.1.1
"v::l::ip2 >= 1.0.4, <=2.0.0")
If all the comparisons are not satisfied, FATAL_ERROR is issued. Allowed comparisons are ==, >=, >, <=, <
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | The target IP library. |
Keyword Arguments
| Name | Type | Description |
|---|---|---|
NODEPEND | string | This keyword disable the dependency between the targets. |
get_ip_property(OUTVAR IP_LIB PROPERTY **kwargs)
This function retrieves a specific property from a target library and its dependencies.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | Variable containing the requested property. |
IP_LIB | string | The target IP library. |
PROPERTY | string | Property to retrieve from IP_LIB. |
ip_compile_definitions(IP_LIB LANGUAGE **kwargs)
Set a compile definition on a IP for a given language inside property <LANGUAGE>_COMPILE_DEFINITIONS.
Any leading -D on an item will be removed. Empty items are ignored. For example, the following are all equivalent:
ip_compile_definitions(foo VERILOG FOO) ip_compile_definitions(foo VERILOG -DFOO) # -D removed ip_compile_definitions(foo VERILOG "" FOO) # "" ignored ip_compile_definitions(foo VERILOG -D FOO) # -D becomes "", then ignored.
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | The target IP library. |
LANGUAGE | string | Language to which the definition should apply. |
FILE_SET | string | Specify to which file set to associate the listed include directories |
get_ip_compile_definitions(OUTVAR IP_LIB LANGUAGE **kwargs)
This function is a hardcoded version of get_ip_property() for the <LANGUAGE>_COMPILE_DEFINITIONS property.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | Variable containing the requested property. |
IP_LIB | string | The target IP library. |
LANGUAGE | string | Language to which the definition apply. |
get_ip_links(OUTVAR IP_LIB **kwargs)
Get the IP link graph in a flat list
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | Variable containing the link list. |
socmake_add_languages()
Add languages to the list of supported languages There is no special meaning of language being supported by SoCMake, other than not issuing a warning message if an unsupported language is detected.
Parameters
| Name | Type | Description |
|---|---|---|
ARGN | list[string] | list of languages to add |
get_socmake_languages(OUTVAR)
This function return a list of the supported language by your SoCMake environnement.
This means, the langauges initially supported by SoCMake and the one that have been added using socmake_add_languages().
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | list[string] | Variable in which to store the supported languages |
check_languages(LANGUAGE)
This function checks the the language is supported by SoCMake.
This function checks the the language is supported by SoCMake and issue a warning/error depending on the verbosity level. The supported languages can be augmented using the variable SOCMAKE_ADDITIONAL_LANGUAGES.
Parameters
| Name | Type | Description |
|---|---|---|
OUT | string | The variable in which to store the original retrieved name. |
LIB | string | The target IP library name. |
find_ip(IP_LIB)
.. note:: This is a macro, and so does not introduce a new scope.
This macro wraps the find_package() calls.
It always searches for packages in CONFIG mode The name of the IP_LIB is sanitized to replace : with _
Use it as following: find_package(Vendor::Library::Name REQUIRED)
This will then search for a file called "Vendor__Library__NameConfig.cmake" or "vendor__library__name-config.cmake" It is recommended to place the directory of this file in "CMAKE_PREFIX_PATH" variable, to facilitate finding it
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | the target IP library. |
ip_find_and_link(IP_LIB)
This function combines ip_link() and find_ip() functions.
It checks first if the library is already defined. In case it is not already defined it calls ip_find(<ip_lib> REQUIRED) Finally it calls ip_link() to link it.
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | the target IP library. |
flatten_graph_and_disallow_flattening(IP_LIB)
This function is an optimization to disable graph flattening too often in EDA tool functions.
The flattening is done using flatten_graph, an SoCMake function and a variable is set to disallow further flattening, made by EDA tool.
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | the target IP library. |
socmake_allow_topological_sort(STATE)
This function can be used to allow or disallow flattening by setting STATE to ON or OFF.
Parameters
| Name | Type | Description |
|---|---|---|
STATE | bool | ON to allow it, OFF to disallow it. |
socmake_get_topological_sort_state(OUTVAR)
This function return the value of SOCMAKE_ALLOW_TOPOLOGICAL_SORT, the variable used to allow or disallow flattening.
By default, it's set to ON.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | bool | Variable that will store the value of SOCMAKE_ALLOW_TOPOLOGICAL_SORT. |
flatten_graph_if_allowed(IP_LIB)
As the name of this function say, it will look at SOCMAKE_ALLOW_TOPOLOGICAL_SORT value and proceed to flattening if allowed.
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | the target IP library. |
ip_sources(IP_LIB LANGUAGE **kwargs)
This function adds source file(s) to an IP target.
This functions adds source file(s) under a file set to an IP target as a property named after the name of the file set, type of source file(s) and the suffix 'SOURCES'. The property is of the following format <LANGUAGE><FILE_SET>_SOURCES, in case FILE_SET is not set, DEFAULT is used. If source files of the same type already exist they are appended to the existing list. The source files can also be prepended with the optional keyword PREPEND. The source files are later used to create the list of files to be compiled (e.g., by a simulator) by a tool to execute its tasks. The source files are passed as a list after the parameters and keywords.
Relative file paths are accepted and will be converted to absolute, relative to ${CMAKE_CURRENT_SOURCE_DIR}
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | The target IP library. |
LANGUAGE | string | The language type of the source files (e.g. SYSTEMVERILOG, VHDL). |
Keyword Arguments
| Name | Type | Description |
|---|---|---|
PREPEND | bool | Prepend the new source files before the existing ones instead of appending. |
REPLACE | bool | Replace the existing source file list instead of appending. |
FILE_SET | string | Name of the file set to associate the listed files with; defaults to DEFAULT. |
HEADERS | list[string] | List of header files. Stored in the ${LANGUAGE}_${FILE_SET}_HEADERS property; their parent directories are added as include directories automatically. |
get_ip_sources(OUTVAR IP_LIB LANGUAGE **kwargs)
This function retrieves the specific source files of a target library.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | The variable containing the retrieved source file. |
IP_LIB | string | The target IP library. |
LANGUAGE | string | The type of source file(s). |
Keyword Arguments
| Name | Type | Description |
|---|---|---|
NO_DEPS | bool | If set, only return sources belonging directly to IP_LIB, without traversing its dependencies. |
HEADERS | bool | If set, return header files instead of source files. |
FILE_SETS | list[string] | Restrict results to the listed file sets; returns all file sets when omitted. |
ip_include_directories(IP_LIB LANGUAGE **kwargs)
This function adds include directory(ies) to a target library.
This function adds an interface include directory(ies) to a target library. The include directory(ies) is added with the INTERFACE option (i.e., passed to targets depending on this one). The include directories are passed as a list after the parameter.
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | The target IP library. |
LANGUAGE | string | Language of the included files. |
FILE_SET | string | Specify to which file set to associate the listed include directories |
get_ip_include_directories(OUTVAR IP_LIB LANGUAGE **kwargs)
This function retrieves the included directories of a target library and its dependencies.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | The variable containing the retrieved included directory(ies). |
IP_LIB | string | The target IP library. |
LANGUAGE | string | Language of the included files. |
Keyword Arguments
| Name | Type | Description |
|---|---|---|
NO_DEPS | bool | If set, only return include directories belonging directly to IP_LIB, without traversing its dependencies. |
FILE_SETS | list[string] | Restrict results to the listed file sets; returns all file sets when omitted. |
ip_link(IP_LIB **kwargs)
This function adds a target link library and a dependency to an IP target.
This function gets the original target and dependency names in case an alias is given. Then it checks if the link library exists and adds it (if it's not already added). Finally, the link library is added as a dependency. This last step can be skipped with the keyword NODEPEND. The dependencies are passed as a list after the parameters and the keyword.
It is also allowed to pass version conditions to be checked as following:
ip_link(v::l::ip1::1.1.1
"v::l::ip2 >= 1.0.4, <=2.0.0")
If all the comparisons are not satisfied, FATAL_ERROR is issued. Allowed comparisons are ==, >=, >, <=, <
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | The target IP library. |
Keyword Arguments
| Name | Type | Description |
|---|---|---|
NODEPEND | bool | If set, skip adding a build dependency between the linked targets (only the link is added). |
get_ip_property(OUTVAR IP_LIB PROPERTY **kwargs)
This function retrieves a specific property from a target library and its dependencies.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | Variable containing the requested property. |
IP_LIB | string | The target IP library. |
PROPERTY | string | Property to retrieve from IP_LIB. |
Keyword Arguments
| Name | Type | Description |
|---|---|---|
NO_DEPS | bool | If set, only return the property from IP_LIB itself, without traversing its dependencies. |
ip_compile_definitions(IP_LIB LANGUAGE **kwargs)
Set a compile definition on a IP for a given language inside property <LANGUAGE>_COMPILE_DEFINITIONS.
Any leading -D on an item will be removed. Empty items are ignored. For example, the following are all equivalent:
ip_compile_definitions(foo VERILOG FOO) ip_compile_definitions(foo VERILOG -DFOO) # -D removed ip_compile_definitions(foo VERILOG "" FOO) # "" ignored ip_compile_definitions(foo VERILOG -D FOO) # -D becomes "", then ignored.
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | The target IP library. |
LANGUAGE | string | Language to which the definition should apply. |
FILE_SET | string | Specify to which file set to associate the listed include directories |
get_ip_compile_definitions(OUTVAR IP_LIB LANGUAGE **kwargs)
Retrieve compile definitions for one or more languages from IP_LIB and its dependencies.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | Variable that receives the list of compile definitions (without leading -D). |
IP_LIB | string | The target IP library. |
LANGUAGE | string | First language whose compile definitions should be retrieved (e.g. SYSTEMVERILOG, VHDL). |
Keyword Arguments
| Name | Type | Description |
|---|---|---|
NO_DEPS | bool | If set, only return compile definitions belonging directly to IP_LIB, without traversing its dependencies. |
FILE_SETS | list[string] | Restrict results to the listed file sets; returns all file sets when omitted. |
get_ip_links(OUTVAR IP_LIB **kwargs)
Return the dependency graph of IP_LIB as a flat, topologically-sorted list.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | string | Variable that receives the ordered list of IP targets. |
IP_LIB | string | The target IP library whose link graph should be retrieved. |
Keyword Arguments
| Name | Type | Description |
|---|---|---|
NO_DEPS | bool | If set, only return the direct (immediate) dependencies of IP_LIB instead of the full transitive graph. |
socmake_add_languages()
Add languages to the list of supported languages There is no special meaning of language being supported by SoCMake, other than not issuing a warning message if an unsupported language is detected.
Parameters
| Name | Type | Description |
|---|---|---|
ARGN | list[string] | list of languages to add |
get_socmake_languages(OUTVAR)
This function returns a list of the supported languages by your SoCMake environment.
This means, the languages initially supported by SoCMake and the ones that have been added using socmake_add_languages().
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | list[string] | Variable in which to store the supported languages |
check_languages(LANGUAGE)
Check whether a language is supported by SoCMake and emit a warning or fatal error if not.
The verbosity level is controlled by the SOCMAKE_UNSUPPORTED_LANGUAGE_FATAL variable:
when set, an unsupported language causes a FATAL_ERROR; otherwise a WARNING is emitted.
The set of supported languages can be extended with socmake_add_languages().
Parameters
| Name | Type | Description |
|---|---|---|
LANGUAGE | string | The language identifier to validate (e.g. SYSTEMVERILOG, VHDL). |
find_ip(IP_LIB)
.. note:: This is a macro, and so does not introduce a new scope.
This macro wraps the find_package() calls.
It always searches for packages in CONFIG mode The name of the IP_LIB is sanitized to replace : with _
Use it as following: find_package(Vendor::Library::Name REQUIRED)
This will then search for a file called "Vendor__Library__NameConfig.cmake" or "vendor__library__name-config.cmake" It is recommended to place the directory of this file in "CMAKE_PREFIX_PATH" variable, to facilitate finding it
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | the target IP library. |
ip_find_and_link(IP_LIB)
This function combines ip_link() and find_ip() functions.
It checks first if the library is already defined. In case it is not already defined it calls ip_find(<ip_lib> REQUIRED) Finally it calls ip_link() to link it.
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | the target IP library. |
flatten_graph_and_disallow_flattening(IP_LIB)
This function is an optimization to disable graph flattening too often in EDA tool functions.
The flattening is done using flatten_graph, an SoCMake function and a variable is set to disallow further flattening, made by EDA tool.
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | the target IP library. |
socmake_allow_topological_sort(STATE)
This function can be used to allow or disallow flattening by setting STATE to ON or OFF.
Parameters
| Name | Type | Description |
|---|---|---|
STATE | bool | ON to allow it, OFF to disallow it. |
socmake_get_topological_sort_state(OUTVAR)
This function returns the value of SOCMAKE_ALLOW_TOPOLOGICAL_SORT, the variable used to allow or disallow flattening.
By default, it's set to ON.
Parameters
| Name | Type | Description |
|---|---|---|
OUTVAR | bool | Variable that will store the value of SOCMAKE_ALLOW_TOPOLOGICAL_SORT. |
flatten_graph_if_allowed(IP_LIB)
As the name of this function say, it will look at SOCMAKE_ALLOW_TOPOLOGICAL_SORT value and proceed to flattening if allowed.
Parameters
| Name | Type | Description |
|---|---|---|
IP_LIB | string | the target IP library. |