portugalfuturista/universalisos
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
universalisos/docs/html/pssw-reference-manual/group__port__communication.html
Fábio Coutada 7855eab092 feat(import): Complete PikeOS 5.0 ecosystem import from devvm-arch 
MAJOR MILESTONE: Successfully imported complete PikeOS 5.0 ecosystem
from Virtual Machine 100 (devvm-arch) on gigabyte Proxmox server.

Import Summary:
- Source Code: 4.3GB, 63,441 files, 14,829 C/C++/H files
- Documentation: 78MB, 37+ PDF manuals covering all PikeOS aspects
- XSD Schemas: 1.8MB, 158 schema files for configuration/code generation
- Test Framework: Complete TFW infrastructure in src/tfw/

Key Components:
✅ Multi-architecture kernels (ARM v7/v8, PowerPC e500/e500mc/e5500, x86_64)
✅ Core source libraries (libstand, ssw, p4ext)
✅ Complete test framework with executables, includes, libraries
✅ 37+ comprehensive PDF documentation (installation, development, platform manuals)
✅ 158 XSD schemas for Eclipse-based code generation and configuration
✅ AUTOSAR/MISRA safety-critical compliance foundation
✅ Hardware virtualization support
✅ Eclipse IDE project configuration (.project, .cproject)

Documentation Categories:
- Installation & User Guides (pikeos-installation-guide.pdf, user manuals)
- Development References (kernel, driver, test framework manuals)
- API & Programming (C/C++ environments, native API extensions)
- Platform Manuals (ARM, PowerPC, x86 specific guides)
- CDK Documentation (gcc, binutils, ld, cpp internals)
- Release Notes (all components for 5.0.3)
- Specialized Topics (hardware virtualization, POSIX compliance)

Technical Achievements:
✅ Complete PikeOS 5.0 codebase across multiple processor architectures
✅ Safety-critical foundation with AUTOSAR/MISRA compliance
✅ Eclipse IDE integration with XSD-driven code generation pipeline
✅ Comprehensive test framework for validation and verification
✅ Complete documentation covering development, deployment, and optimization

Extraction Method:
- Source: VM 100 (devvm-arch) on gigabyte server (192.168.0.104)
- Method: Direct LVM disk mount via losetup, rsync transfer
- Size: Total 4.4GB extracted and organized

Next Phases:
- Phase 3: XSD Workflow Analysis (Day 8-10)
- Phase 4: Safety Standards Compliance Documentation (Day 11-12)
- Phase 5: Component Categorization (Day 13-14)
- Phase 6: Aurelio Brain Test (Day 15)

Co-Authored-By: Claude <noreply@anthropic.com>
2026-07-06 21:01:41 +01:00

1669 lines
138 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Communication Ports</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__port__communication.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="summary">
<a href="#nested-classes">Data Structures</a> &#124;
<a href="#define-members">Macros</a> &#124;
<a href="#enum-members">Enumerations</a> &#124;
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Communication Ports</div> </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>PikeOS communication ports (PCPs) are designed to allow communication between different partitions. The API provides a message based read/write interface. Each port provides unidirectional data flow. </p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Data Structures</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Opaque port descriptor for vm interface. <a href="structvm__port__desc__t.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structvm__qport__stat__t.html">vm_qport_stat_t</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structvm__sport__stat__t.html">vm_sport_stat_t</a></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:ga31d5e5a474de47d154dda8d3841b0da4"><td class="memItemLeft" align="right" valign="top"><a id="ga31d5e5a474de47d154dda8d3841b0da4"></a>
#define&#160;</td><td class="memItemRight" valign="bottom"><b>VM_QPORT_IS_SAP</b>(pd)</td></tr>
<tr class="separator:ga31d5e5a474de47d154dda8d3841b0da4"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="enum-members"></a>
Enumerations</h2></td></tr>
<tr class="memitem:ga05b84bc9dffc8307b4dcbef3041ab2df"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga05b84bc9dffc8307b4dcbef3041ab2df">vm_sport_msg_validity_t</a> { <a class="el" href="group__port__communication.html#gga05b84bc9dffc8307b4dcbef3041ab2dfa6edf09f6044e79ee871cba8c170d2c35">VM_SPORT_EMPTY</a>,
<a class="el" href="group__port__communication.html#gga05b84bc9dffc8307b4dcbef3041ab2dfa643e7b3e8bbc90e9d4ce41534aa67abc">VM_SPORT_VALID</a>,
<a class="el" href="group__port__communication.html#gga05b84bc9dffc8307b4dcbef3041ab2dfa5f03f062e87e862c1b4df8d0ecba1bc3">VM_SPORT_INVALID</a>,
<a class="el" href="group__port__communication.html#gga05b84bc9dffc8307b4dcbef3041ab2dfa191adbf075a3559578c6cc2c493e314d">VM_SPORT_NOT_APPLICABLE</a>
}</td></tr>
<tr class="separator:ga05b84bc9dffc8307b4dcbef3041ab2df"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga7e655782c3d3751eeeaacf5764c86ddb"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb">vm_qport_open</a> (const char *name, P4_uint32_t flags, <a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd)</td></tr>
<tr class="memdesc:ga7e655782c3d3751eeeaacf5764c86ddb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Open a queuing port. <a href="#ga7e655782c3d3751eeeaacf5764c86ddb">More...</a><br /></td></tr>
<tr class="separator:ga7e655782c3d3751eeeaacf5764c86ddb"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga6926e581e2a0b88f0a5884805e72a0db"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga6926e581e2a0b88f0a5884805e72a0db">vm_qport_read</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, void *buff, P4_size_t buff_size, P4_timeout_t timeout, P4_size_t *msg_size)</td></tr>
<tr class="memdesc:ga6926e581e2a0b88f0a5884805e72a0db"><td class="mdescLeft">&#160;</td><td class="mdescRight">Read a message from a queuing port. <a href="#ga6926e581e2a0b88f0a5884805e72a0db">More...</a><br /></td></tr>
<tr class="separator:ga6926e581e2a0b88f0a5884805e72a0db"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga09010e02390be8f5677b6e3302b74e6a"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga09010e02390be8f5677b6e3302b74e6a">vm_qport_write</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, const void *buff, P4_size_t msg_size, P4_timeout_t timeout)</td></tr>
<tr class="memdesc:ga09010e02390be8f5677b6e3302b74e6a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Write a message to a queuing port. <a href="#ga09010e02390be8f5677b6e3302b74e6a">More...</a><br /></td></tr>
<tr class="separator:ga09010e02390be8f5677b6e3302b74e6a"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga1aaf90ed8a6478994aa5fdc18718b525"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525">vm_qport_pstat</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, <a class="el" href="structvm__qport__stat__t.html">vm_qport_stat_t</a> *stat)</td></tr>
<tr class="memdesc:ga1aaf90ed8a6478994aa5fdc18718b525"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return the status of a queuing port identified by the port descriptor. <a href="#ga1aaf90ed8a6478994aa5fdc18718b525">More...</a><br /></td></tr>
<tr class="separator:ga1aaf90ed8a6478994aa5fdc18718b525"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gae86e2d66498481f91b47518454cce304"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#gae86e2d66498481f91b47518454cce304">vm_qport_psync</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd)</td></tr>
<tr class="memdesc:gae86e2d66498481f91b47518454cce304"><td class="mdescLeft">&#160;</td><td class="mdescRight">Sync data with external hardware. <a href="#gae86e2d66498481f91b47518454cce304">More...</a><br /></td></tr>
<tr class="separator:gae86e2d66498481f91b47518454cce304"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga307fa7facb8ac3411fb6376a0843909b"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b">vm_qport_stat</a> (const char *name, <a class="el" href="structvm__qport__stat__t.html">vm_qport_stat_t</a> *stat)</td></tr>
<tr class="memdesc:ga307fa7facb8ac3411fb6376a0843909b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return the status of a queuing port identified by the port name. <a href="#ga307fa7facb8ac3411fb6376a0843909b">More...</a><br /></td></tr>
<tr class="separator:ga307fa7facb8ac3411fb6376a0843909b"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gabdcd1c4fa852557f08f8a728b0a445e9"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9">vm_qport_iterate</a> (P4_uint32_t pnr, <a class="el" href="structvm__qport__stat__t.html">vm_qport_stat_t</a> *stat)</td></tr>
<tr class="memdesc:gabdcd1c4fa852557f08f8a728b0a445e9"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return the status of a queuing port identified by the port number. <a href="#gabdcd1c4fa852557f08f8a728b0a445e9">More...</a><br /></td></tr>
<tr class="separator:gabdcd1c4fa852557f08f8a728b0a445e9"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga31b52c641760b72614793a3e5163f82a"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga31b52c641760b72614793a3e5163f82a">vm_qport_control</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, P4_uint32_t cmd, void *data)</td></tr>
<tr class="memdesc:ga31b52c641760b72614793a3e5163f82a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Send port control command to a port provider. <a href="#ga31b52c641760b72614793a3e5163f82a">More...</a><br /></td></tr>
<tr class="separator:ga31b52c641760b72614793a3e5163f82a"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga81e074fb0b9e01f1de4a602f3038e2d5"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga81e074fb0b9e01f1de4a602f3038e2d5">vm_qport_test</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, vm_test_mode_t tm, P4_uint32_t cmd)</td></tr>
<tr class="memdesc:ga81e074fb0b9e01f1de4a602f3038e2d5"><td class="mdescLeft">&#160;</td><td class="mdescRight">Control the driver's test mode. <a href="#ga81e074fb0b9e01f1de4a602f3038e2d5">More...</a><br /></td></tr>
<tr class="separator:ga81e074fb0b9e01f1de4a602f3038e2d5"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaad58147da8b917254c09ff9da637edbd"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#gaad58147da8b917254c09ff9da637edbd">vm_qport_read_routed</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, void *buff, P4_size_t buff_size, vm_sockaddr_storage_t *route, P4_size_t route_sz, P4_timeout_t timeout, P4_size_t *msg_size)</td></tr>
<tr class="memdesc:gaad58147da8b917254c09ff9da637edbd"><td class="mdescLeft">&#160;</td><td class="mdescRight">Extended qport read for SAP ports. <a href="#gaad58147da8b917254c09ff9da637edbd">More...</a><br /></td></tr>
<tr class="separator:gaad58147da8b917254c09ff9da637edbd"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gadf6fb6167a02b3b80940338c81af233e"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#gadf6fb6167a02b3b80940338c81af233e">vm_qport_write_routed</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, const void *buff, P4_size_t msg_size, const vm_sockaddr_storage_t *route, P4_size_t route_sz, P4_timeout_t timeout)</td></tr>
<tr class="memdesc:gadf6fb6167a02b3b80940338c81af233e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Extended qport write for SAP ports. <a href="#gadf6fb6167a02b3b80940338c81af233e">More...</a><br /></td></tr>
<tr class="separator:gadf6fb6167a02b3b80940338c81af233e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gad15c03a34b243fd8b513704d18bdc7cf"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#gad15c03a34b243fd8b513704d18bdc7cf">vm_qport_clear</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd)</td></tr>
<tr class="memdesc:gad15c03a34b243fd8b513704d18bdc7cf"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clear a queuing port, discard all messages. <a href="#gad15c03a34b243fd8b513704d18bdc7cf">More...</a><br /></td></tr>
<tr class="separator:gad15c03a34b243fd8b513704d18bdc7cf"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga8e6f89648397cdf80022440eb1557936"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga8e6f89648397cdf80022440eb1557936">vm_qport_close</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd)</td></tr>
<tr class="memdesc:ga8e6f89648397cdf80022440eb1557936"><td class="mdescLeft">&#160;</td><td class="mdescRight">Close a queuing port. <a href="#ga8e6f89648397cdf80022440eb1557936">More...</a><br /></td></tr>
<tr class="separator:ga8e6f89648397cdf80022440eb1557936"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gac90e9b940d3cc3cd82e04d2e6541b597"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597">vm_sport_open</a> (const char *name, P4_uint32_t flags, <a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd)</td></tr>
<tr class="memdesc:gac90e9b940d3cc3cd82e04d2e6541b597"><td class="mdescLeft">&#160;</td><td class="mdescRight">Open a sampling port. <a href="#gac90e9b940d3cc3cd82e04d2e6541b597">More...</a><br /></td></tr>
<tr class="separator:gac90e9b940d3cc3cd82e04d2e6541b597"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gacd194f29aaa49287cd447e9e7a6bd594"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#gacd194f29aaa49287cd447e9e7a6bd594">vm_sport_read</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, void *buff, P4_size_t buff_size, P4_size_t *msg_size, <a class="el" href="group__port__communication.html#ga05b84bc9dffc8307b4dcbef3041ab2df">vm_sport_msg_validity_t</a> *validity)</td></tr>
<tr class="memdesc:gacd194f29aaa49287cd447e9e7a6bd594"><td class="mdescLeft">&#160;</td><td class="mdescRight">Read a message from a sampling port. <a href="#gacd194f29aaa49287cd447e9e7a6bd594">More...</a><br /></td></tr>
<tr class="separator:gacd194f29aaa49287cd447e9e7a6bd594"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga346f97ee7161d99e7f0395b975c61a6e"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga346f97ee7161d99e7f0395b975c61a6e">vm_sport_write</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, const void *buff, P4_size_t msg_size)</td></tr>
<tr class="memdesc:ga346f97ee7161d99e7f0395b975c61a6e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Write a message to a sampling port. <a href="#ga346f97ee7161d99e7f0395b975c61a6e">More...</a><br /></td></tr>
<tr class="separator:ga346f97ee7161d99e7f0395b975c61a6e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga95a73b64ba3ef1d1157c0c02bd41a7bb"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga95a73b64ba3ef1d1157c0c02bd41a7bb">vm_sport_pstat</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, <a class="el" href="structvm__sport__stat__t.html">vm_sport_stat_t</a> *stat)</td></tr>
<tr class="memdesc:ga95a73b64ba3ef1d1157c0c02bd41a7bb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return the status of a sampling port identified by the port name. <a href="#ga95a73b64ba3ef1d1157c0c02bd41a7bb">More...</a><br /></td></tr>
<tr class="separator:ga95a73b64ba3ef1d1157c0c02bd41a7bb"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga611b08cac7e9c578dc63feff58a1afcd"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga611b08cac7e9c578dc63feff58a1afcd">vm_sport_psync</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd)</td></tr>
<tr class="memdesc:ga611b08cac7e9c578dc63feff58a1afcd"><td class="mdescLeft">&#160;</td><td class="mdescRight">Send a sync request to the given descriptor. <a href="#ga611b08cac7e9c578dc63feff58a1afcd">More...</a><br /></td></tr>
<tr class="separator:ga611b08cac7e9c578dc63feff58a1afcd"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gaf2174d63baf4633764f89c087bb63520"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#gaf2174d63baf4633764f89c087bb63520">vm_sport_stat</a> (const char *name, <a class="el" href="structvm__sport__stat__t.html">vm_sport_stat_t</a> *stat)</td></tr>
<tr class="memdesc:gaf2174d63baf4633764f89c087bb63520"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return the status of a sampling port identified by the port name. <a href="#gaf2174d63baf4633764f89c087bb63520">More...</a><br /></td></tr>
<tr class="separator:gaf2174d63baf4633764f89c087bb63520"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gada5efe3476321dab9b1866a2fea0499c"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#gada5efe3476321dab9b1866a2fea0499c">vm_sport_iterate</a> (P4_uint32_t pnr, <a class="el" href="structvm__sport__stat__t.html">vm_sport_stat_t</a> *stat)</td></tr>
<tr class="memdesc:gada5efe3476321dab9b1866a2fea0499c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Return status of a sampling port identified by the port number. <a href="#gada5efe3476321dab9b1866a2fea0499c">More...</a><br /></td></tr>
<tr class="separator:gada5efe3476321dab9b1866a2fea0499c"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga7a009eea70525dd82c9cda34a6d0590d"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga7a009eea70525dd82c9cda34a6d0590d">vm_sport_control</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, P4_uint32_t cmd, void *data)</td></tr>
<tr class="memdesc:ga7a009eea70525dd82c9cda34a6d0590d"><td class="mdescLeft">&#160;</td><td class="mdescRight">Send port control command to a port provider. <a href="#ga7a009eea70525dd82c9cda34a6d0590d">More...</a><br /></td></tr>
<tr class="separator:ga7a009eea70525dd82c9cda34a6d0590d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga5d9a374df2992c73452da63c9976dd8e"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga5d9a374df2992c73452da63c9976dd8e">vm_sport_test</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd, vm_test_mode_t tm, P4_uint32_t cmd)</td></tr>
<tr class="memdesc:ga5d9a374df2992c73452da63c9976dd8e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Control the driver's test mode. <a href="#ga5d9a374df2992c73452da63c9976dd8e">More...</a><br /></td></tr>
<tr class="separator:ga5d9a374df2992c73452da63c9976dd8e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga81897d7049aa205a9051fcf2b37b81a4"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#ga81897d7049aa205a9051fcf2b37b81a4">vm_sport_clear</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd)</td></tr>
<tr class="memdesc:ga81897d7049aa205a9051fcf2b37b81a4"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clear as sampling port, reset it to empty state. <a href="#ga81897d7049aa205a9051fcf2b37b81a4">More...</a><br /></td></tr>
<tr class="separator:ga81897d7049aa205a9051fcf2b37b81a4"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:gab3911fef652c431f4c5e5bf586a14317"><td class="memItemLeft" align="right" valign="top">P4_e_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__port__communication.html#gab3911fef652c431f4c5e5bf586a14317">vm_sport_close</a> (<a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *pd)</td></tr>
<tr class="memdesc:gab3911fef652c431f4c5e5bf586a14317"><td class="mdescLeft">&#160;</td><td class="mdescRight">Close a sampling port. <a href="#gab3911fef652c431f4c5e5bf586a14317">More...</a><br /></td></tr>
<tr class="separator:gab3911fef652c431f4c5e5bf586a14317"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<h2 class="groupheader">Enumeration Type Documentation</h2>
<a id="ga05b84bc9dffc8307b4dcbef3041ab2df"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga05b84bc9dffc8307b4dcbef3041ab2df">&#9670;&nbsp;</a></span>vm_sport_msg_validity_t</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">enum <a class="el" href="group__port__communication.html#ga05b84bc9dffc8307b4dcbef3041ab2df">vm_sport_msg_validity_t</a></td>
</tr>
</table>
</div><div class="memdoc">
<p>Last message validity type.</p>
<p>Used in the <em>vm_sport_stat</em> structure to indicate the validity of the last message of a destination port. </p>
<table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="gga05b84bc9dffc8307b4dcbef3041ab2dfa6edf09f6044e79ee871cba8c170d2c35"></a>VM_SPORT_EMPTY&#160;</td><td class="fielddoc"><p>No message has been transmitted to the port. </p>
</td></tr>
<tr><td class="fieldname"><a id="gga05b84bc9dffc8307b4dcbef3041ab2dfa643e7b3e8bbc90e9d4ce41534aa67abc"></a>VM_SPORT_VALID&#160;</td><td class="fielddoc"><p>The last message that was read from the port was valid. </p>
</td></tr>
<tr><td class="fieldname"><a id="gga05b84bc9dffc8307b4dcbef3041ab2dfa5f03f062e87e862c1b4df8d0ecba1bc3"></a>VM_SPORT_INVALID&#160;</td><td class="fielddoc"><p>The last message that was read from the port was invalid or the port has not been read since the last partition (re)start. </p>
</td></tr>
<tr><td class="fieldname"><a id="gga05b84bc9dffc8307b4dcbef3041ab2dfa191adbf075a3559578c6cc2c493e314d"></a>VM_SPORT_NOT_APPLICABLE&#160;</td><td class="fielddoc"><p>The validity info is not meaningful since the stat operation was performed on an unconnected port or a source port. </p>
</td></tr>
</table>
</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga7e655782c3d3751eeeaacf5764c86ddb"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga7e655782c3d3751eeeaacf5764c86ddb">&#9670;&nbsp;</a></span>vm_qport_open()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_open </td>
<td>(</td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_uint32_t&#160;</td>
<td class="paramname"><em>flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Open a queuing port. </p>
<p>This function opens the queuing port specified by the port name. Upon success the function returns a handle to the port which is used during subsequent calls to port communication services to identify the port.</p>
<p>The port must exist (a queuing port with the given name must be configured in the VMIT) and the port direction must match the direction requested by the parameter <em>flags</em>. Note that the port direction corresponds with open flags: VM_PORT_SOURCE is an alias for VM_O_WR and VM_PORT_DESTINATION is an alias for VM_O_RD.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>If the function returns anything but P4_E_OK, the contents of <code>pd</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<p>Invoking this function on a descriptor that is already in use may cause the descriptor to be overwritten in unspecified ways, regardless of whether the new request succeeds or fails. This means that as soon as this function is entered, the passed descriptor must be considered uninitialized until this function returns successfully.</p>
<p>This function is not thread safe, i.e., no other operations may be ongoing in other threads on the same descriptor, because there is no protection against data races on the descriptor. Further, the initialization of the descriptor performed by this function is not atomic.</p>
<p>Note that except for <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>, all functions taking a vm_port_desc_t* have undefined behavior before the port descriptor is initialized using <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>, and also after the descriptor is finalized using <a class="el" href="group__port__communication.html#ga8e6f89648397cdf80022440eb1557936" title="Close a queuing port. ">vm_qport_close()</a>. Mixing ports opened with <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a> and <a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597" title="Open a sampling port. ">vm_sport_open()</a> also results in undefined behavior.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>upon success. This is also return if there is no connection to another port, so that the requester cannot see whether the other end of the channel actually exists.</td></tr>
<tr><td class="paramname">P4_E_PERM</td><td>if the parameter <em>direction</em> does not match the port's direction, or both VM_O_RD and VM_O_WR bits are set, i.e., ports must be unidirectional.</td></tr>
<tr><td class="paramname">P4_E_NAME</td><td>if <em>name</em> is too long for the underlying provider.</td></tr>
<tr><td class="paramname">P4_E_NOENT</td><td>if no port with the given name exists in the partition's queuing port list</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid</td></tr>
<tr><td class="paramname">P4_E_OOFILE</td><td>if opening a kernel driver gate fails to allocate a new kernel file descriptor. System extensions do not need to allocate a descriptor, so this error only occurs when accessing gate providers.</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled.</td></tr>
</table>
</dd>
</dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#ga6926e581e2a0b88f0a5884805e72a0db" title="Read a message from a queuing port. ">vm_qport_read()</a>, <a class="el" href="group__port__communication.html#ga09010e02390be8f5677b6e3302b74e6a" title="Write a message to a queuing port. ">vm_qport_write()</a>, <a class="el" href="group__port__communication.html#gaad58147da8b917254c09ff9da637edbd" title="Extended qport read for SAP ports. ">vm_qport_read_routed()</a>, <a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a>, <a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a>, <a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9" title="Return the status of a queuing port identified by the port number. ">vm_qport_iterate()</a>, <a class="el" href="group__port__communication.html#gadf6fb6167a02b3b80940338c81af233e" title="Extended qport write for SAP ports. ">vm_qport_write_routed()</a>, <a class="el" href="group__port__communication.html#gad15c03a34b243fd8b513704d18bdc7cf" title="Clear a queuing port, discard all messages. ">vm_qport_clear()</a>, <a class="el" href="group__port__communication.html#ga8e6f89648397cdf80022440eb1557936" title="Close a queuing port. ">vm_qport_close()</a>. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">name</td><td>IN: Port name as configured in the VMIT. </td></tr>
<tr><td class="paramname">flags</td><td>IN: Port direction can be one of the constants:<br />
<ul>
<li><b>VM_PORT_SOURCE</b> for a source port,<br />
</li>
<li><b>VM_PORT_DESTINATION</b> for a destination port.</li>
</ul>
</td></tr>
</table>
</dd>
</dl>
<p>Additionally, to select a blocking discipline based on thread priority, VM_O_PRIORITY can be specified as an additional bit. If this bit is not set, FIFO order is used instead of priority by default. </p><dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>OUT: Upon success, the requested port descriptor is saved in <em>pd</em>. In case of error, the content of <em>pd</em> is unspecified. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga6926e581e2a0b88f0a5884805e72a0db"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga6926e581e2a0b88f0a5884805e72a0db">&#9670;&nbsp;</a></span>vm_qport_read()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_read </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>buff</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t&#160;</td>
<td class="paramname"><em>buff_size</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_timeout_t&#160;</td>
<td class="paramname"><em>timeout</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t *&#160;</td>
<td class="paramname"><em>msg_size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Read a message from a queuing port. </p>
<p>This function reads a single message from the queuing port given by the port descriptor <em>pd</em> into the buffer given by <em>buff</em>.</p>
<p>Upon success, the message is removed from the port, copied into the buffer and the actual message size is returned in <em>msg_size</em>. If a blocking write operation is pending on the opposite port of the connected channel, the corresponding thread will be unblocked.</p>
<p>If the message queue is empty, <a class="el" href="group__port__communication.html#ga6926e581e2a0b88f0a5884805e72a0db" title="Read a message from a queuing port. ">vm_qport_read()</a></p><ul>
<li>waits for an incoming message until <em>timeout</em> expires,</li>
<li>waits infinitely for an incoming message if <em>timeout</em> == P4_TIMEOUT_INFINITE, or</li>
<li>returns immediately with an error when used in non blocking operation mode (<em>timeout</em> == P4_TIMEOUT_NULL).</li>
</ul>
<p>The size of the caller's memory buffer must be greater than or equal to the largest message size configured for the port <em>pd</em>. The function will never copy parts of a message into the buffer. If the buffer size is smaller than the maximum queue message size the call will fail even if the actual message would fit into the user buffer.</p>
<p>In case of concurrent read operations, the requests are queued in FIFO order.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<p>If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of <code>msg_size</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<p>If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of <code>buff</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>upon success</td></tr>
<tr><td class="paramname">P4_E_PERM</td><td>if <em>pd</em> does not refer to a destination port</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the requested operation is not available for the port referred to by <em>pd</em>.</td></tr>
<tr><td class="paramname">P4_E_SIZE</td><td>if <em>buff_size</em> is smaller than the configured maximum message size of the port</td></tr>
<tr><td class="paramname">P4_E_BADTIMEOUT</td><td>the <em>timeout</em> is invalid</td></tr>
<tr><td class="paramname">P4_E_PAGEFAULT</td><td>the <em>buff</em> is not fully mapped or not fully writable.</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if <em>pd</em> is not a valid port descriptor or if <em>buff</em> is not fully located in the user accessable virtual memory space.</td></tr>
<tr><td class="paramname">P4_E_TIMEOUT</td><td>if <em>timeout</em> greater than zero was given and no message was received within the time interval</td></tr>
<tr><td class="paramname">P4_E_TIMEOUT</td><td>if <em>timeout</em> == P4_TIMEOUT_NULL was given and the message queue is empty</td></tr>
<tr><td class="paramname">P4_E_LIMIT</td><td>if there was packet loss since the last reading of a message, i.e., the queue was full, but more messages arrived and could not be stored. Devices that implement handshaking between reader and writer will not ever produce this message, because the writer will block until the queue becomes free for another message. However, devices that cannot stop messages from coming in may signal this (e.g., network devices).</td></tr>
<tr><td class="paramname">P4_E_TRUNC</td><td>if the message was received from hardware without knowing its exact size, but it turned out the message was too large for the given buffer, i.e., there was data loss in the attempt to copy the message into the user buffer. This will only happen for devices that have no knowledge of the size of the message in the queue prior to copying it to the user. Devices that know that the message is too large will instead return P4_E_SIZE.</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled.</td></tr>
</table>
</dd>
</dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>, <a class="el" href="group__port__communication.html#ga09010e02390be8f5677b6e3302b74e6a" title="Write a message to a queuing port. ">vm_qport_write()</a>, <a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a>, <a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a>, and <a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9" title="Return the status of a queuing port identified by the port number. ">vm_qport_iterate()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: Descriptor of the destination port returned by <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a> </td></tr>
<tr><td class="paramname">buff</td><td>OUT: The receive buffer </td></tr>
<tr><td class="paramname">buff_size</td><td>IN: Size of the receive buffer given in bytes. <em>buff_size</em> must be greater than or equal to the maximum message size configured for the port. </td></tr>
<tr><td class="paramname">timeout</td><td>IN: Absolute or relative Kernel-API timeout value of the operation or <b>P4_TIMEOUT_NULL</b> for non blocking operation, or <b>P4_TIMEOUT_INFINITE</b> for infinite blocking. </td></tr>
<tr><td class="paramname">msg_size</td><td>OUT: Size of the received message in bytes. In case of error, the value <em>msg_size</em> is unspecified. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga09010e02390be8f5677b6e3302b74e6a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga09010e02390be8f5677b6e3302b74e6a">&#9670;&nbsp;</a></span>vm_qport_write()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_write </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const void *&#160;</td>
<td class="paramname"><em>buff</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t&#160;</td>
<td class="paramname"><em>msg_size</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_timeout_t&#160;</td>
<td class="paramname"><em>timeout</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Write a message to a queuing port. </p>
<p>This function writes a single message from the message buffer given by <em>buff</em> to the queuing port given by the port descriptor <em>pd</em>. The size of the message is given by <em>msg_size</em>.</p>
<p>Upon success, the message is written to the port queue. If a blocking read operation is pending on the opposite port of the connected channel, the corresponding thread will be unblocked.</p>
<p>If the message queue is full, <a class="el" href="group__port__communication.html#ga09010e02390be8f5677b6e3302b74e6a" title="Write a message to a queuing port. ">vm_qport_write()</a></p><ul>
<li>waits for a free message buffer until <em>timeout</em> expires,</li>
<li>waits infinitely for a free message buffer if <em>timeout</em> == P4_TIMEOUT_INFINITE, or</li>
<li>returns immediately with an error when used in non blocking operation mode (<em>timeout</em> == P4_TIMEOUT_NULL).</li>
</ul>
<p>The message size <em>msg_size</em> must be less than or equal to the maximum message size configured for the given port. This function never copies parts of a message, either the whole message is written to the port queue or the call fails returning an error code.</p>
<p>In case of concurrent write operations, the requests are queued in FIFO order.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>upon success</td></tr>
<tr><td class="paramname">P4_E_PERM</td><td>if the port referred to by <em>pd</em> is not a source port</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the requested operation is not available for the port referred to by <em>pd</em>.</td></tr>
<tr><td class="paramname">P4_E_SIZE</td><td>if <em>msg_size</em> is larger than the configured message size of the port</td></tr>
<tr><td class="paramname">P4_E_TRUNC</td><td>if not all of <em>msg_size</em> bytes could be transferred by the driver. Note that this function has no means of returning the actual number of bytes transferred, so in returns this error code instead. This error case indicates that the underlying driver is not fully compliant with port semantics.</td></tr>
<tr><td class="paramname">P4_E_BADTIMEOUT</td><td>the <em>timeout</em> is invalid</td></tr>
<tr><td class="paramname">P4_E_PAGEFAULT</td><td>the <em>buff</em> is not fully mapped.</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if <em>pd</em> is not a valid port descriptor or if <em>buff</em> is not fully located in the user accessable memory space.</td></tr>
<tr><td class="paramname">P4_E_TIMEOUT</td><td>if <em>timeout</em> greater than zero was given and no message was written within the time interval</td></tr>
<tr><td class="paramname">P4_E_TIMEOUT</td><td>if <em>timeout</em> == P4_TIMEOUT_NULL was given and the message queue is full</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled.</td></tr>
</table>
</dd>
</dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>, <a class="el" href="group__port__communication.html#ga6926e581e2a0b88f0a5884805e72a0db" title="Read a message from a queuing port. ">vm_qport_read()</a>, <a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a>, <a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a>, and <a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9" title="Return the status of a queuing port identified by the port number. ">vm_qport_iterate()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: Descriptor of the source port returned by <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a> </td></tr>
<tr><td class="paramname">buff</td><td>IN: Pointer to the message buffer </td></tr>
<tr><td class="paramname">msg_size</td><td>IN: Size of the message <em>buff</em> given in bytes. <em>msg_size</em> must be less than or equal to the maximum message size. </td></tr>
<tr><td class="paramname">timeout</td><td>IN: Absolute or relative Kernel-API timeout value of the operation or <b>P4_TIMEOUT_NULL</b> for non blocking operation, or<br />
<b>P4_TIMEOUT_INFINITE</b> for infinite blocking. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga1aaf90ed8a6478994aa5fdc18718b525"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga1aaf90ed8a6478994aa5fdc18718b525">&#9670;&nbsp;</a></span>vm_qport_pstat()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_pstat </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structvm__qport__stat__t.html">vm_qport_stat_t</a> *&#160;</td>
<td class="paramname"><em>stat</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Return the status of a queuing port identified by the port descriptor. </p>
<p>This function provides several information about the current status of a queuing port given by the port descriptor <em>pd</em>.</p>
<p>For a detailed description about the port status information, refer to the documentation of the data type <em>vm_qport_stat_str</em>.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<p>If the function returns anything but P4_E_OK, the contents of <code>status</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<p>Further note that gate providers cannot return the port name in this function, because it is not available in the kernel. Only <a class="el" href="group__port__communication.html#gaf2174d63baf4633764f89c087bb63520" title="Return the status of a sampling port identified by the port name. ">vm_sport_stat()</a> and <a class="el" href="group__port__communication.html#gada5efe3476321dab9b1866a2fea0499c" title="Return status of a sampling port identified by the port number. ">vm_sport_iterate()</a> will return the name of ports of gate providers.</p>
<p>If the port is open without VM_O_RD or VM_O_WR permissions, or with VM_O_RD_WR permissions, then vm_pstat returns the number of messages that can be read, i.e., the number of messages in the queue, i.e., the same value as if the port had been opened in VM_O_RD direction. Only if it was opened with exactly VM_O_WR permissions, it will return the number of messages that can be written.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>upon success</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the requested operation is not available for the port <em>port</em>.</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if <em>pd</em> is not a valid port descriptor</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>The port descriptor <em>pd</em> must refer to a port which has been opened by a call to <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>. </dd></dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>, <a class="el" href="group__port__communication.html#ga6926e581e2a0b88f0a5884805e72a0db" title="Read a message from a queuing port. ">vm_qport_read()</a>, <a class="el" href="group__port__communication.html#ga09010e02390be8f5677b6e3302b74e6a" title="Write a message to a queuing port. ">vm_qport_write()</a>, <a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a>, and <a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9" title="Return the status of a queuing port identified by the port number. ">vm_qport_iterate()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: Port descriptor, returned by a call to <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a> </td></tr>
<tr><td class="paramname">stat</td><td>OUT: Upon success, the port status is returned in the structure referenced by <em>status</em>, in case of error, the content of this structure remains unchanged. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gae86e2d66498481f91b47518454cce304"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gae86e2d66498481f91b47518454cce304">&#9670;&nbsp;</a></span>vm_qport_psync()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_psync </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Sync data with external hardware. </p>
<p>This may be available in some drivers. It may be used to flush ports to hardware and block until software buffers have all been transferred to the hardware. Or it may also be used to read buffers from hardware.</p>
<p>Depending on the underlying driver, this call may do different things, so the driver documentation will describe what is implemented.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: Port descriptor, returned by a call to <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a> </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga307fa7facb8ac3411fb6376a0843909b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga307fa7facb8ac3411fb6376a0843909b">&#9670;&nbsp;</a></span>vm_qport_stat()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_stat </td>
<td>(</td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structvm__qport__stat__t.html">vm_qport_stat_t</a> *&#160;</td>
<td class="paramname"><em>stat</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Return the status of a queuing port identified by the port name. </p>
<p>This function provides several information about the current status of a queuing port given by the port name.</p>
<p>For a detailed description about the port status information, refer to the documentation of the data type <em><a class="el" href="structvm__qport__stat__t.html">vm_qport_stat_t</a></em>.</p>
<p>Whether a queuing port is an SAP port can be queried without using pstat by applying VM_QPORT_IS_SAP() to the port descriptor pointer.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>If the function returns anything but P4_E_OK, the contents of <code>status</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>upon success</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the requested operation is not available for the port specified by <em>name</em>.</td></tr>
<tr><td class="paramname">P4_E_NAME</td><td>if <em>name</em> is too long for the underlying provider.</td></tr>
<tr><td class="paramname">P4_E_NOENT</td><td>if <em>name</em> does not reference a valid port</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled.</td></tr>
</table>
</dd>
</dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section note"><dt>Note</dt><dd>This call may be applied to a port which has not yet been opened, however some of the port's status information is only meaningful for an open port. In particular, for ports on gate providers, the number of messages can only be queried using <a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a>, not <a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a> nor <a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9" title="Return the status of a queuing port identified by the port number. ">vm_qport_iterate()</a>. In the same way, the number of waiters on gates is only available from <a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a>. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>, <a class="el" href="group__port__communication.html#ga6926e581e2a0b88f0a5884805e72a0db" title="Read a message from a queuing port. ">vm_qport_read()</a>, <a class="el" href="group__port__communication.html#ga09010e02390be8f5677b6e3302b74e6a" title="Write a message to a queuing port. ">vm_qport_write()</a>, <a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a>, and <a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9" title="Return the status of a queuing port identified by the port number. ">vm_qport_iterate()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">name</td><td>IN: Port name as configured in the VMIT. </td></tr>
<tr><td class="paramname">stat</td><td>OUT: Upon success, the port status is returned in the structure referenced by <em>status</em>, in case of error, the content of this structure remains unchanged. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gabdcd1c4fa852557f08f8a728b0a445e9"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gabdcd1c4fa852557f08f8a728b0a445e9">&#9670;&nbsp;</a></span>vm_qport_iterate()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_iterate </td>
<td>(</td>
<td class="paramtype">P4_uint32_t&#160;</td>
<td class="paramname"><em>pnr</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structvm__qport__stat__t.html">vm_qport_stat_t</a> *&#160;</td>
<td class="paramname"><em>stat</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Return the status of a queuing port identified by the port number. </p>
<p>This function returns the status of a queuing port given by the port number. It is used to iterate through the current partition's port list. Iteration should start with the parameter <em>pnr</em> set to 0; the end of the partition's port list is reached when the call returns with the error code <b>P4_E_NOENT</b>.</p>
<p>For a detailed description about the port status information, refer to the documentation of the data type <em>vm_qport_stat_str</em>.</p>
<div class="fragment"><div class="line">...</div><div class="line">pnr = 0;</div><div class="line"><span class="keywordflow">do</span> {</div><div class="line"> rc = <a class="code" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9">vm_qport_iterate</a>(pnr++, &amp;stat);</div><div class="line"> ...</div><div class="line">} <span class="keywordflow">while</span> (rc == P4_E_OK);</div></div><!-- fragment --><p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>If the function returns anything but P4_E_OK, the contents of <code>status</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>upon success</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the requested operation is not available for the port specified by <em>pnr</em>.</td></tr>
<tr><td class="paramname">P4_E_NOENT</td><td>if the end of the port list has be reached</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>For ports at gate providers, this function cannot return complete status information. First of all, the state will always be reported as VM_PORT_CREATE, because the gate providers are descriptor based, and the gates are always created at boot time. Further, the number of messages is reported as 0 for these drivers, just like in <a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a>, because gate providers can only provide full status information after a descriptor is available, for invoking the driver, i.e., using <a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a>. In the same way, the number of waiters on gates is only available from <a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a>.</dd></dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>, <a class="el" href="group__port__communication.html#ga6926e581e2a0b88f0a5884805e72a0db" title="Read a message from a queuing port. ">vm_qport_read()</a>, <a class="el" href="group__port__communication.html#ga09010e02390be8f5677b6e3302b74e6a" title="Write a message to a queuing port. ">vm_qport_write()</a>, <a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a>, and <a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pnr</td><td>IN: Port number </td></tr>
<tr><td class="paramname">stat</td><td>OUT: Upon success, the port status is returned in the structure referenced by <em>status</em>, in case of error, the content of this structure remains unchanged. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga31b52c641760b72614793a3e5163f82a"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga31b52c641760b72614793a3e5163f82a">&#9670;&nbsp;</a></span>vm_qport_control()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_control </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_uint32_t&#160;</td>
<td class="paramname"><em>cmd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>data</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Send port control command to a port provider. </p>
<p>This function is similar to the <a class="el" href="group__file__system.html#ga78184a0887c6628e9e0c3bd8d4989e18" title="Provider specific control function. ">vm_ioctl()</a> command, but specific for queuing port providers. <em>cmd</em> specifies a command identifier which is defined with one of the VM_IOC_* calls.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<p>The behavior of this function in case <code>data</code> is NULL is implementation-defined, i.e., it depends on the underlying driver how the function will behave.</p>
<p>The contents of the memory pointed to by <code>data</code> after the call to this function is implementation-defined, i.e., it depends on the underlying driver how data is handled, and in which cases the data contents are specified or unspecified.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>upon success</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the port does not provide the corresponding service</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if <em>pd</em> is not a valid port descriptor</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled.</td></tr>
</table>
</dd>
</dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__file__system.html#ga78184a0887c6628e9e0c3bd8d4989e18" title="Provider specific control function. ">vm_ioctl()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: port descriptor </td></tr>
<tr><td class="paramname">cmd</td><td>IN: command identifier </td></tr>
<tr><td class="paramname">data</td><td>IN:[OUT] command specific data </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga81e074fb0b9e01f1de4a602f3038e2d5"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga81e074fb0b9e01f1de4a602f3038e2d5">&#9670;&nbsp;</a></span>vm_qport_test()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_test </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">vm_test_mode_t&#160;</td>
<td class="paramname"><em>tm</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_uint32_t&#160;</td>
<td class="paramname"><em>cmd</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Control the driver's test mode. </p>
<p>This function can be used to access the driver's test features. The exact functionality is up to the driver, this is a generic API passing down commands to the driver to activate/deactivate synchronous or asynchronous tests.</p>
<p>Please also see the documentation for vm_test_mode_t.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: port descriptor </td></tr>
<tr><td class="paramname">tm</td><td>IN: which test mode to select </td></tr>
<tr><td class="paramname">cmd</td><td>IN: arbitrary command for the provider </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gaad58147da8b917254c09ff9da637edbd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaad58147da8b917254c09ff9da637edbd">&#9670;&nbsp;</a></span>vm_qport_read_routed()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_read_routed </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>buff</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t&#160;</td>
<td class="paramname"><em>buff_size</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">vm_sockaddr_storage_t *&#160;</td>
<td class="paramname"><em>route</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t&#160;</td>
<td class="paramname"><em>route_sz</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_timeout_t&#160;</td>
<td class="paramname"><em>timeout</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t *&#160;</td>
<td class="paramname"><em>msg_size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Extended qport read for SAP ports. </p>
<p>This is similar to <a class="el" href="group__port__communication.html#ga6926e581e2a0b88f0a5884805e72a0db" title="Read a message from a queuing port. ">vm_qport_read()</a>, but can specify addresses of different end points to be used for sender and/or receiver. I.e., it allows the caller to receive both the address of the local interface and of the remote interface where the message originated.</p>
<p>Routed operations are useful for implementing network oriented channels where the communicating ends have addresses, e.g. IP addresses. Consequently, vm_sockaddr_t and vm_sockaddr_storage_t closely follows the POSIX API wrt. specification of addresses, with a protocol and an address family. In the context of ports in PikeOS, the functions are used to access SAP ports.</p>
<p>Note that in contrast to A653, the SAP drivers are stateless, so user space has to take care to transfer the addresses, otherwise, the driver will always use the default. State is moved to user space in order to make multi-threading less error-prone.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<p>If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of <code>msg_size</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<p>If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of <code>buff</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>if reading was successful.</td></tr>
<tr><td class="paramname">P4_E_PERM</td><td>if the port is not open for reading.</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if this operation is not supported by the underlying driver.</td></tr>
<tr><td class="paramname">P4_E_SIZE</td><td>if the buffer size is invalid, i.e., too small to accommodate a message of the maximum configured size for this port.</td></tr>
<tr><td class="paramname">P4_E_BADTIMEOUT</td><td>if the timeout parameter is not a valid timeout</td></tr>
<tr><td class="paramname">P4_E_RESTRICTED</td><td>if a local address is passed (i.e., <em>route_size</em> is greater than sizeof(drv_sockaddr_storage_t)), but the driver does not allow specifying a local address.</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if the descriptor is not a valid port descriptor</td></tr>
<tr><td class="paramname">P4_E_TIMEOUT</td><td>if timeout is equal to P4_TIMEOUT_NULL and the output queue is full.</td></tr>
<tr><td class="paramname">P4_E_TIMEOUT</td><td>if timeout is not equal to P4_TIMEOUT_NULL, the output queue is full, and the time specified by timeout has passed.</td></tr>
<tr><td class="paramname">P4_E_PAGEFAULT</td><td>if any of the referenced pointers causes a memory access fault when read or written by the driver.</td></tr>
<tr><td class="paramname">P4_E_TIMEOUT</td><td>if the operation was canceled in such a way that retrying might be successful.</td></tr>
<tr><td class="paramname">P4_E_BUSY</td><td>if the operation is currently not possible, e.g. because the port is currently not available and it is not possible or makes no sense to block until it becomes available. E.g. this happens when the port descriptor is currently being closed.</td></tr>
<tr><td class="paramname">P4_E_IO</td><td>if the underlying hardware detected a non-recoverable fault</td></tr>
<tr><td class="paramname">P4_E_LIMIT</td><td>if there was packet loss since the last reading of a message, i.e., the queue was full, but more messages arrived and could not be stored. Devices that implement handshaking between reader and writer will not ever produce this message, because the writer will block until the queue becomes free for another message. However, devices that cannot stop messages from coming in may signal this (e.g., network devices).</td></tr>
<tr><td class="paramname">P4_E_TRUNC</td><td>if the message was received from hardware without knowing its exact size, but it turned out the message was too large for the given buffer, i.e., there was data loss in the attempt to copy the message into the user buffer. This will only happen for devices that have no knowledge of the size of the message in the queue prior to copying it to the user. Devices that know that the message is too large will instead return P4_E_SIZE.</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the operation was aborted in such a way that simply retrying has no chance to success.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled. </td></tr>
</table>
</dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: The port descriptor of the SAP (queuing) port </td></tr>
<tr><td class="paramname">buff</td><td>OUT: The buffer for receiving the message </td></tr>
<tr><td class="paramname">buff_size</td><td>IN: The size of the buffer in bytes. </td></tr>
<tr><td class="paramname">route</td><td>OUT: Addresses of remote and local devices of the received message.</td></tr>
</table>
</dd>
</dl>
<p>This is an array of size 1 or 2 of vm_sockaddr_storage_t records. <code>route_size</code> indicates the size of the array in bytes, and, thus, implicitly indicates whether the array has 1 or 2 entries. The remote address of the device the message was received from is in array index [0]. The address of the local device the message was received on is in array index [1].</p>
<p>The function will fill in the route with data the driver stores. Which address family the driver uses is up to the driver. Drivers may have configuration settings for this or may take information from a previous write_routed(), or may be fixed to one address family &ndash; this depends on the driver.</p>
<p>Note that the declared type 'vm_sockaddr_t' is not necessarily the valid parameter type. It is possible to pass a smaller types and set route_sz accordingly. The parameter type makes it easy to pass in an array of two vm_sockaddr_storage_t without casting.</p>
<dl class="section see"><dt>See also</dt><dd>drv_sockaddr_t, drv_sockaddr_ip4_t, drv_sockaddr_ip6_t, drv_sockaddr_storage_t. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">route_sz</td><td>IN: The size of the space reserved for <code>route</code>. If this is larger than sizeof(vm_sockaddr_storage_t), then there are two entries in the <code>route</code> array, otherwise there is one.</td></tr>
</table>
</dd>
</dl>
<p>This may be smaller than a vm_sockaddr_storage_t. It just needs to contain all relevant data in the amount of bytes defined. When passing just one address, route_sz may thus be equal to the size of that entry. </p><dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">timeout</td><td>IN: Timeout: how long to possibly wait to be able to read data </td></tr>
<tr><td class="paramname">msg_size</td><td>OUT: The amount of transferred data in bytes. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gadf6fb6167a02b3b80940338c81af233e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gadf6fb6167a02b3b80940338c81af233e">&#9670;&nbsp;</a></span>vm_qport_write_routed()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_write_routed </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const void *&#160;</td>
<td class="paramname"><em>buff</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t&#160;</td>
<td class="paramname"><em>msg_size</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const vm_sockaddr_storage_t *&#160;</td>
<td class="paramname"><em>route</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t&#160;</td>
<td class="paramname"><em>route_sz</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_timeout_t&#160;</td>
<td class="paramname"><em>timeout</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Extended qport write for SAP ports. </p>
<p>This can receive addresses of sender and/or receiver. I.e., this is similar to <a class="el" href="group__port__communication.html#ga09010e02390be8f5677b6e3302b74e6a" title="Write a message to a queuing port. ">vm_qport_write()</a>, but allows the caller to set both the address of the local interface and of the remote interface where the message is routed.</p>
<p>Routed operations are useful for implementing network oriented channels where the communicating ends have addresses, e.g. IP addresses. Consequently, vm_sockaddr_t and vm_sockaddr_storage_t closely follows the POSIX API wrt. specification of addresses, with a protocol and an address family. In the context of ports in PikeOS, the functions are used to access SAP ports.</p>
<p>SAP drivers are strongly encouraged to be stateless wrt. the addresses, i.e., they should not remember an address passed in this call except for handling the request itself, i.e., a <a class="el" href="group__port__communication.html#gadf6fb6167a02b3b80940338c81af233e" title="Extended qport write for SAP ports. ">vm_qport_write_routed()</a> should not set a default remote or local address for subsequent writes.</p>
<p>Drivers may maintain a fixed default address set by global configuration, but to ease multi-threaded implementation, they should require that each write request overrides that default individually if necessary.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>if the message was successfully enqueued for sending.</td></tr>
<tr><td class="paramname">P4_E_PERM</td><td>if the port is not open for writing.</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if this operation is not supported by the underlying driver.</td></tr>
<tr><td class="paramname">P4_E_SIZE</td><td>if the buffer size is invalid, i.e., larger than a message of the maximum configured size for this port.</td></tr>
<tr><td class="paramname">P4_E_BADTIMEOUT</td><td>if the timeout value is invalid</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if the descriptor is invalid</td></tr>
<tr><td class="paramname">P4_E_RESTRICTED</td><td>if a local address is passed (i.e., <em>route_size</em> is greater than sizeof(drv_sockaddr_storage_t)), but the driver does not allow specifying the local address.</td></tr>
<tr><td class="paramname">P4_E_TIMEOUT</td><td>if timeout is equal to P4_TIMEOUT_NULL and the output queue is full.</td></tr>
<tr><td class="paramname">P4_E_TIMEOUT</td><td>if timeout is not equal to P4_TIMEOUT_NULL, the output queue is full, and the time specified by <em>timeout</em> has passed.</td></tr>
<tr><td class="paramname">P4_E_PAGEFAULT</td><td>if any of the referenced pointers causes a memory access fault when read or written by the driver or the framework.</td></tr>
<tr><td class="paramname">P4_E_TRUNC</td><td>if the underlying driver could only write part of the message. In this case, the port is connected to a non-compliant queuing port driver. A compliant driver would guarantee to either fully send the message or not to send it at all.</td></tr>
<tr><td class="paramname">P4_E_TIMEOUT</td><td>if the operation was canceled in such a way that retrying might be successful.</td></tr>
<tr><td class="paramname">P4_E_BUSY</td><td>if the operation is currently not possible, e.g. because the port is currently not available and it is not possible or makes no sense to block until it becomes available. E.g. this happens when the port descriptor is currently being closed.</td></tr>
<tr><td class="paramname">P4_E_IO</td><td>if the underlying hardware detected a non-recoverable fault</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the operation was aborted in such a way that simply retrying has no chance to success.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled. </td></tr>
</table>
</dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: The port descriptor of the SAP (queuing) port </td></tr>
<tr><td class="paramname">buff</td><td>IN: The buffer containing the message to be sent </td></tr>
<tr><td class="paramname">msg_size</td><td>IN: The size of the message in the buffer to be sent in bytes </td></tr>
<tr><td class="paramname">route</td><td>IN: The target and possibly source addresses.</td></tr>
</table>
</dd>
</dl>
<p>The addresses are passed exactly like in <a class="el" href="group__port__communication.html#gaad58147da8b917254c09ff9da637edbd" title="Extended qport read for SAP ports. ">vm_qport_read_routed()</a>, i.e., this is a pointer to an array of vm_sockaddr_storage_t of 1 or 2 entries. Array index [0] is the remote address (the destination address) and index [1] is the local address (the source address). For sending, the addresses must be filled in by the caller. route_sz gives the size of the array in bytes and implicitly defines the number of addresses: 1 or 2.</p>
<p>The length and family must be set so that the length is long enough to represent an address of the given type.</p>
<p>Either entry can be VM_AF_NULL to indicate that for the corresponding device, no address or the default should be used. However, if the remote address is not specified, the driver is likely to reject the request if it has no default destination address. Similarly, if there is no default local address, or the driver is set to only allow two-address requests, the driver may reject the request.</p>
<p>This function call is stateless wrt. the addresses: neither the port descriptor nor the driver store the remote address or change the default local address. Such state must be kept in application space. This is a deliberate design decision in order to allow for clean multi-threading of applications without race conditions. This function guarantees that the addresses passed as parameters will be used for exactly the message transferred in this call.</p>
<p>Note that the declared type 'vm_sockaddr_t' is not necessarily the exact parameter type that is passed. It is possible to pass a smaller type and set route_sz accordingly. The parameter type makes it easy to pass in an array of two vm_sockaddr_storage_t without casting.</p>
<dl class="section see"><dt>See also</dt><dd>drv_sockaddr_t, drv_sockaddr_ip4_t, drv_sockaddr_ip6_t, drv_sockaddr_storage_t. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">route_sz</td><td>IN: The size of the space reserved for <code>route</code>. If this is larger than sizeof(vm_sockaddr_storage_t), then there are two entries in the <code>route</code> array, otherwise there is one.</td></tr>
</table>
</dd>
</dl>
<p>route_sz may be smaller than 2*sizeof(vm_sockaddr_storage_t) (for two address) or smaller than 1*sizeof(vm_sockaddr_storage_t) (for one address), if the last address in the array needs less memory than a full vm_sockaddr_storage_t. E.g., when passing a single vm_sockaddr_ip4_t, route_sz may be sizeof(vm_sockaddr_ip4_t). </p><dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">timeout</td><td>IN: Timeout: how long to possibly wait to be able to send data in bytes </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gad15c03a34b243fd8b513704d18bdc7cf"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gad15c03a34b243fd8b513704d18bdc7cf">&#9670;&nbsp;</a></span>vm_qport_clear()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_clear </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clear a queuing port, discard all messages. </p>
<p>Clearing a queuing port means to consume all message without processing them, i.e., by discarding the messages. This operation is typically only allowed by the reader of a queuing port.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>if the port content was cleared.</td></tr>
<tr><td class="paramname">P4_E_PERM</td><td>if the port is forbidden to be cleared from this side of the channel.</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the underlying port does not support to be cleared. The framework does not make an attempt to simulate clearing by consuming message until the port is empty, because this may lead to infinite loops when the port is filled simultaneously, plus it might take a very long time, since such a loop is O(queue_length), while the specific clear operation is typically O(1).</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if the port descriptor is invalid</td></tr>
<tr><td class="paramname">P4_E_BUSY</td><td>if the port is currently busy, e.g., because it is being closed in another thread, too.</td></tr>
<tr><td class="paramname">P4_E_IO</td><td>if the underlying hardware had a fault.</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled. </td></tr>
</table>
</dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>The port descriptor of the port to be cleared </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga8e6f89648397cdf80022440eb1557936"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga8e6f89648397cdf80022440eb1557936">&#9670;&nbsp;</a></span>vm_qport_close()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_qport_close </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Close a queuing port. </p>
<p>Closing a port is the opposite of opening it. This will deallocate possible system resources used for the descriptor. After that, the port descriptor will not be usable anymore for operations on the port, but to use it again, the port has to be re-opened.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<p>The contents of <code>pd</code> will be unspecified in case this function returns P4_E_OK. In case of an error, the contents of <code>pd</code> will remain unchanged, because the error may indicate a temporary failure so that the closing could be repeated later.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>if the port could be closed.</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if the port descriptor is invalid, or is in use or in the process of being closed by another thread.</td></tr>
<tr><td class="paramname">P4_E_BUSY</td><td>if the port is currently busy, e.g., because it is being closed in another thread, too.</td></tr>
<tr><td class="paramname">P4_E_IO</td><td>if the underlying hardware had a fault.</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled. </td></tr>
</table>
</dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>The port descriptor of the port to be closed </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gac90e9b940d3cc3cd82e04d2e6541b597"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gac90e9b940d3cc3cd82e04d2e6541b597">&#9670;&nbsp;</a></span>vm_sport_open()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_open </td>
<td>(</td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_uint32_t&#160;</td>
<td class="paramname"><em>flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Open a sampling port. </p>
<p>This function behaves exactly like <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a> except that it can only be applied to sampling ports instead of queuing ports.</p>
<p>For a detailed description, including the return values, refer to the documentation of <em><a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a></em>.</p>
<p>If the function returns anything but P4_E_OK, the contents of <code>pd</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<p>Invoking this function on a descriptor that is already in use may cause the descriptor to be overwritten in unspecified ways, regardless of whether the new request succeeds or fails. This means that as soon as this function is entered, the passed descriptor must be considered uninitialized until this function returns successfully.</p>
<p>This function is not thread safe, i.e., no other operations may be ongoing in other threads on the same descriptor, because there is no protection against data races on the descriptor. Further, the initialization of the descriptor performed by this function is not atomic.</p>
<p>Note that except for <a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597" title="Open a sampling port. ">vm_sport_open()</a>, all functions taking a vm_port_desc_t* have undefined behavior before the port descriptor is initialized using <a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597" title="Open a sampling port. ">vm_sport_open()</a>, and also after the descriptor is finalized using <a class="el" href="group__port__communication.html#gab3911fef652c431f4c5e5bf586a14317" title="Close a sampling port. ">vm_sport_close()</a>. Mixing ports opened with <a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597" title="Open a sampling port. ">vm_sport_open()</a> and <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a> also results in undefined behavior.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#gacd194f29aaa49287cd447e9e7a6bd594" title="Read a message from a sampling port. ">vm_sport_read()</a>, <a class="el" href="group__port__communication.html#ga346f97ee7161d99e7f0395b975c61a6e" title="Write a message to a sampling port. ">vm_sport_write()</a>, <a class="el" href="group__port__communication.html#ga95a73b64ba3ef1d1157c0c02bd41a7bb" title="Return the status of a sampling port identified by the port name. ">vm_sport_pstat()</a>, <a class="el" href="group__port__communication.html#gaf2174d63baf4633764f89c087bb63520" title="Return the status of a sampling port identified by the port name. ">vm_sport_stat()</a>, <a class="el" href="group__port__communication.html#gada5efe3476321dab9b1866a2fea0499c" title="Return status of a sampling port identified by the port number. ">vm_sport_iterate()</a>, <a class="el" href="group__port__communication.html#ga81897d7049aa205a9051fcf2b37b81a4" title="Clear as sampling port, reset it to empty state. ">vm_sport_clear()</a>, <a class="el" href="group__port__communication.html#gab3911fef652c431f4c5e5bf586a14317" title="Close a sampling port. ">vm_sport_close()</a>. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">name</td><td>IN: Port name as configured in the VMIT </td></tr>
<tr><td class="paramname">flags</td><td>IN: Port direction can be one of the constants:<br />
<ul>
<li><b>VM_PORT_SOURCE</b> for a source port,<br />
</li>
<li><b>VM_PORT_DESTINATION</b> for a destination port. </li>
</ul>
</td></tr>
<tr><td class="paramname">pd</td><td>OUT: Upon success, the requested port descriptor is saved in <em>pd</em>. In case of error, the content of <em>pd</em> is unspecified. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gacd194f29aaa49287cd447e9e7a6bd594"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gacd194f29aaa49287cd447e9e7a6bd594">&#9670;&nbsp;</a></span>vm_sport_read()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_read </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>buff</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t&#160;</td>
<td class="paramname"><em>buff_size</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t *&#160;</td>
<td class="paramname"><em>msg_size</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__port__communication.html#ga05b84bc9dffc8307b4dcbef3041ab2df">vm_sport_msg_validity_t</a> *&#160;</td>
<td class="paramname"><em>validity</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Read a message from a sampling port. </p>
<p>This function reads the current message from the sampling port given by the port descriptor <em>pd</em> into the buffer given by <em>buff</em>.</p>
<p>Upon success (P4_E_OK), the variable referenced by <em>validity</em> has been written and should be checked by the caller to get information about the state of the message buffer. <em>validity</em> can assume the following values:</p><ul>
<li>VM_SPORT_INVALID &ndash; the message was copied but it is invalid with respect to the ports refresh period.</li>
<li>VM_SPORT_VALID &ndash; the message was copied and it is valid with respect to the ports refresh period.</li>
<li>VM_SPORT_EMPTY &ndash; no message has yet been transferred to the port, and no message has been copied to the <em>buff</em>.</li>
</ul>
<p>If a message was copied to <em>buff</em>, its size is returned in <em>msg_size</em>.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<p>If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of <code>msg_size</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<p>If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of <code>validity</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<p>If the function returns anything but P4_E_OK or P4_E_TRUNC, the contents of <code>buff</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>upon success</td></tr>
<tr><td class="paramname">P4_E_PERM</td><td>if the port referred to by <em>pd</em> is not a destination port</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the requested operation is not available for the port referred to by <em>pd</em>.</td></tr>
<tr><td class="paramname">P4_E_SIZE</td><td>if <em>buff_size</em> is smaller than the configured maximum message size of the port</td></tr>
<tr><td class="paramname">P4_E_PAGEFAULT</td><td>the <em>buff</em> is not fully mapped or not fully writable</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if <em>pd</em> is not a valid port descriptor or if <em>buff</em> is not fully located in the user accessable virtual memory space.</td></tr>
<tr><td class="paramname">P4_E_TRUNC</td><td>if the message was received from hardware without knowing its exact size, but it turned out the message was too large for the given buffer, i.e., there was data loss in the attempt to copy the message into the user buffer. This will only happen for devices that have no knowledge of the size of the message in the queue prior to copying it to the user. Devices that know that the message is too large will instead return P4_E_SIZE.</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled.</td></tr>
</table>
</dd>
</dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section note"><dt>Note</dt><dd>A <a class="el" href="group__port__communication.html#gacd194f29aaa49287cd447e9e7a6bd594" title="Read a message from a sampling port. ">vm_sport_read()</a> operation does not consume the message, it can be re-read until it is overwritten by a new message. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597" title="Open a sampling port. ">vm_sport_open()</a>, <a class="el" href="group__port__communication.html#ga346f97ee7161d99e7f0395b975c61a6e" title="Write a message to a sampling port. ">vm_sport_write()</a>, <a class="el" href="group__port__communication.html#ga95a73b64ba3ef1d1157c0c02bd41a7bb" title="Return the status of a sampling port identified by the port name. ">vm_sport_pstat()</a>, <a class="el" href="group__port__communication.html#gaf2174d63baf4633764f89c087bb63520" title="Return the status of a sampling port identified by the port name. ">vm_sport_stat()</a>, and <a class="el" href="group__port__communication.html#gada5efe3476321dab9b1866a2fea0499c" title="Return status of a sampling port identified by the port number. ">vm_sport_iterate()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: Descriptor of the destination port returned by <a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597" title="Open a sampling port. ">vm_sport_open()</a> </td></tr>
<tr><td class="paramname">buff</td><td>OUT: Pointer to the receive buffer </td></tr>
<tr><td class="paramname">buff_size</td><td>IN: Size of buffer <em>buff</em> given in bytes. <em>buff_size</em> must be greater than or equal to the maximum message size configured for the port. </td></tr>
<tr><td class="paramname">msg_size</td><td>OUT: Upon success, <em>msg_size</em> will contain the received message size in bytes. In case of error, the value <em>msg_size</em> is unspecified. </td></tr>
<tr><td class="paramname">validity</td><td>OUT: returns the validity of the received message. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga346f97ee7161d99e7f0395b975c61a6e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga346f97ee7161d99e7f0395b975c61a6e">&#9670;&nbsp;</a></span>vm_sport_write()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_write </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const void *&#160;</td>
<td class="paramname"><em>buff</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_size_t&#160;</td>
<td class="paramname"><em>msg_size</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Write a message to a sampling port. </p>
<p>This function is used to replace the current message of the sampling port given by the port descriptor <em>pd</em> with the message given by <em>buff</em> </p>
<p>Upon success, <em>msg_size</em> bytes of the message buffer are written to the port. The message size may not exceed the maximum message size configured for the port.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>upon success</td></tr>
<tr><td class="paramname">P4_E_PERM</td><td>if the port referred to by <em>pd</em> is not a source port</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the requested operation is not available for the port referred to by <em>pd</em>.</td></tr>
<tr><td class="paramname">P4_E_SIZE</td><td>if <em>msg_size</em> is larger than the configured maximum message size of the port</td></tr>
<tr><td class="paramname">P4_E_TRUNC</td><td>if not all of <em>msg_size</em> bytes could be transferred by the driver. Note that this function has no means of returning the actual number of bytes transferred, so in returns this error code instead. This error case indicates that the underlying driver is not fully compliant with port semantics.</td></tr>
<tr><td class="paramname">P4_E_PAGEFAULT</td><td>the <em>buff</em> is not fully mapped.</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if <em>pd</em> is not a valid port descriptor or if <em>buff</em> is not fully located in the user accessable virtual memory space.</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled.</td></tr>
</table>
</dd>
</dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597" title="Open a sampling port. ">vm_sport_open()</a>, <a class="el" href="group__port__communication.html#gacd194f29aaa49287cd447e9e7a6bd594" title="Read a message from a sampling port. ">vm_sport_read()</a>, <a class="el" href="group__port__communication.html#ga95a73b64ba3ef1d1157c0c02bd41a7bb" title="Return the status of a sampling port identified by the port name. ">vm_sport_pstat()</a>, <a class="el" href="group__port__communication.html#gaf2174d63baf4633764f89c087bb63520" title="Return the status of a sampling port identified by the port name. ">vm_sport_stat()</a>, and <a class="el" href="group__port__communication.html#gada5efe3476321dab9b1866a2fea0499c" title="Return status of a sampling port identified by the port number. ">vm_sport_iterate()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: Descriptor of the source port returned by <a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597" title="Open a sampling port. ">vm_sport_open()</a> </td></tr>
<tr><td class="paramname">buff</td><td>IN: Pointer to the message buffer to write </td></tr>
<tr><td class="paramname">msg_size</td><td>IN: Size of the message <em>buff</em> given in bytes. <em>msg_size</em> must be less than or equal to the maximum message size. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga95a73b64ba3ef1d1157c0c02bd41a7bb"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga95a73b64ba3ef1d1157c0c02bd41a7bb">&#9670;&nbsp;</a></span>vm_sport_pstat()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_pstat </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structvm__sport__stat__t.html">vm_sport_stat_t</a> *&#160;</td>
<td class="paramname"><em>stat</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Return the status of a sampling port identified by the port name. </p>
<p>This function behaves exactly like <a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a> except that it can only be applied to sampling ports instead of queuing ports.</p>
<p>For a detailed description, including the return values, refer to the documentation of <em><a class="el" href="group__port__communication.html#ga1aaf90ed8a6478994aa5fdc18718b525" title="Return the status of a queuing port identified by the port descriptor. ">vm_qport_pstat()</a></em>.</p>
<p>Note that the returned refresh rate is the current refresh rate for the given port descriptor. After opening a sampling port, this is the port's default refresh rate, which can be reset using vm_sport_set_refresh_rate(). The returned validity is based on the current refresh rate. This is different from <a class="el" href="group__port__communication.html#gaf2174d63baf4633764f89c087bb63520" title="Return the status of a sampling port identified by the port name. ">vm_sport_stat()</a>, which always uses the port's default refresh rate.</p>
<p>Further note that gate providers cannot return the port name in this function, because it is not available in the kernel. Only <a class="el" href="group__port__communication.html#gaf2174d63baf4633764f89c087bb63520" title="Return the status of a sampling port identified by the port name. ">vm_sport_stat()</a> and <a class="el" href="group__port__communication.html#gada5efe3476321dab9b1866a2fea0499c" title="Return status of a sampling port identified by the port number. ">vm_sport_iterate()</a> will return the name of ports of gate providers.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<p>If the function returns anything but P4_E_OK, the contents of <code>status</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<dl class="section note"><dt>Note</dt><dd>The port descriptor <em>pd</em> must refer to a port which has been opened by a call to <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>. </dd></dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597" title="Open a sampling port. ">vm_sport_open()</a>, <a class="el" href="group__port__communication.html#gacd194f29aaa49287cd447e9e7a6bd594" title="Read a message from a sampling port. ">vm_sport_read()</a>, <a class="el" href="group__port__communication.html#ga346f97ee7161d99e7f0395b975c61a6e" title="Write a message to a sampling port. ">vm_sport_write()</a>, <a class="el" href="group__port__communication.html#gaf2174d63baf4633764f89c087bb63520" title="Return the status of a sampling port identified by the port name. ">vm_sport_stat()</a>, and <a class="el" href="group__port__communication.html#gada5efe3476321dab9b1866a2fea0499c" title="Return status of a sampling port identified by the port number. ">vm_sport_iterate()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: Port descriptor, returned by a call to <a class="el" href="group__port__communication.html#gac90e9b940d3cc3cd82e04d2e6541b597" title="Open a sampling port. ">vm_sport_open()</a> </td></tr>
<tr><td class="paramname">stat</td><td>OUT: Upon success, the port status is returned in the structure referenced by <em>status</em>, in case of error, the content of this structure remains unchanged. </td></tr>
</table>
</dd>
</dl>
<dl class="section see"><dt>See also</dt><dd>vm_sport_stat_str </dd></dl>
</div>
</div>
<a id="ga611b08cac7e9c578dc63feff58a1afcd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga611b08cac7e9c578dc63feff58a1afcd">&#9670;&nbsp;</a></span>vm_sport_psync()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_psync </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Send a sync request to the given descriptor. </p>
<p>Depending on the underlying driver, this call may do different things. The general idea is to flush data from memory onto an external device. The exact semantics must be checked for each driver.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: Port descriptor, returned by a call to <a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a> </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gaf2174d63baf4633764f89c087bb63520"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gaf2174d63baf4633764f89c087bb63520">&#9670;&nbsp;</a></span>vm_sport_stat()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_stat </td>
<td>(</td>
<td class="paramtype">const char *&#160;</td>
<td class="paramname"><em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structvm__sport__stat__t.html">vm_sport_stat_t</a> *&#160;</td>
<td class="paramname"><em>stat</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Return the status of a sampling port identified by the port name. </p>
<p>This function behaves exactly like <a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a> except that it can only be applied to sampling ports instead of queuing ports.</p>
<p>For a detailed description, including the return values, refer to the documentation of <em><a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a></em>.</p>
<p>Note that the returned refresh rate is the port default refresh rate, and the returned validity is based on that default refresh rate. This is different from <a class="el" href="group__port__communication.html#ga95a73b64ba3ef1d1157c0c02bd41a7bb" title="Return the status of a sampling port identified by the port name. ">vm_sport_pstat()</a>, which uses the currently active refresh rate for the port descriptor, set using vm_sport_set_refresh_rate().</p>
<p>Also note that the validity of a source port cannot be checked with this function.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>If the function returns anything but P4_E_OK, the contents of <code>status</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<dl class="section note"><dt>Note</dt><dd>This call may be applied to a port which has not yet been opened, however some of the port's status information is only meaningful for open ports. In particular, gate providers can only report the age of the message in <a class="el" href="group__port__communication.html#ga95a73b64ba3ef1d1157c0c02bd41a7bb" title="Return the status of a sampling port identified by the port name. ">vm_sport_pstat()</a>, but not in <a class="el" href="group__port__communication.html#gaf2174d63baf4633764f89c087bb63520" title="Return the status of a sampling port identified by the port name. ">vm_sport_stat()</a> nor in <a class="el" href="group__port__communication.html#gada5efe3476321dab9b1866a2fea0499c" title="Return status of a sampling port identified by the port number. ">vm_sport_iterate()</a>, because they require an open descriptor to invoke the driver to return this information. </dd></dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>, <a class="el" href="group__port__communication.html#ga6926e581e2a0b88f0a5884805e72a0db" title="Read a message from a queuing port. ">vm_qport_read()</a>, <a class="el" href="group__port__communication.html#ga09010e02390be8f5677b6e3302b74e6a" title="Write a message to a queuing port. ">vm_qport_write()</a>, <a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a>, and <a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9" title="Return the status of a queuing port identified by the port number. ">vm_qport_iterate()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">name</td><td>IN: Port name as configured in the VMIT. </td></tr>
<tr><td class="paramname">stat</td><td>OUT: Upon success, the port status is returned in the structure referenced by <em>status</em>, in case of error, the content of this structure remains unchanged. </td></tr>
</table>
</dd>
</dl>
<dl class="section see"><dt>See also</dt><dd>vm_sport_stat_str </dd></dl>
</div>
</div>
<a id="gada5efe3476321dab9b1866a2fea0499c"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gada5efe3476321dab9b1866a2fea0499c">&#9670;&nbsp;</a></span>vm_sport_iterate()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_iterate </td>
<td>(</td>
<td class="paramtype">P4_uint32_t&#160;</td>
<td class="paramname"><em>pnr</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structvm__sport__stat__t.html">vm_sport_stat_t</a> *&#160;</td>
<td class="paramname"><em>stat</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Return status of a sampling port identified by the port number. </p>
<p>This function behaves exactly like <a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9" title="Return the status of a queuing port identified by the port number. ">vm_qport_iterate()</a> except that it can only be applied to sampling ports instead of queuing ports.</p>
<p>For a detailed description, including the return values, refer to the documentation of <em><a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9" title="Return the status of a queuing port identified by the port number. ">vm_qport_iterate()</a></em>.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>If the function returns anything but P4_E_OK, the contents of <code>status</code> are unspecified, including the possibility of being overwritten in unspecified ways.</p>
<dl class="section note"><dt>Note</dt><dd>This call may be applied to a port which has not yet been opened, however some of the port's status information is only meaningful for open ports. </dd></dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__port__communication.html#ga7e655782c3d3751eeeaacf5764c86ddb" title="Open a queuing port. ">vm_qport_open()</a>, <a class="el" href="group__port__communication.html#ga6926e581e2a0b88f0a5884805e72a0db" title="Read a message from a queuing port. ">vm_qport_read()</a>, <a class="el" href="group__port__communication.html#ga09010e02390be8f5677b6e3302b74e6a" title="Write a message to a queuing port. ">vm_qport_write()</a>, <a class="el" href="group__port__communication.html#ga307fa7facb8ac3411fb6376a0843909b" title="Return the status of a queuing port identified by the port name. ">vm_qport_stat()</a>, and <a class="el" href="group__port__communication.html#gabdcd1c4fa852557f08f8a728b0a445e9" title="Return the status of a queuing port identified by the port number. ">vm_qport_iterate()</a></dd></dl>
<dl class="section note"><dt>Note</dt><dd>For ports at gate providers, this function cannot return complete status information. First of all, the state will always be reported as VM_PORT_CREATE, because the gate providers are descriptor based, and the gates are always created at boot time. Further, the number of messages is reported as 0 for these drivers, just like in <a class="el" href="group__port__communication.html#gaf2174d63baf4633764f89c087bb63520" title="Return the status of a sampling port identified by the port name. ">vm_sport_stat()</a>, because gate providers can only provide full status information after a descriptor is available, for invoking the driver, i.e., using <a class="el" href="group__port__communication.html#ga95a73b64ba3ef1d1157c0c02bd41a7bb" title="Return the status of a sampling port identified by the port name. ">vm_sport_pstat()</a>. </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pnr</td><td>IN: Port number </td></tr>
<tr><td class="paramname">stat</td><td>OUT: Upon success, the port status is returned in the structure referenced by <em>status</em>, in case of error, the content of this structure remains unchanged. </td></tr>
</table>
</dd>
</dl>
<dl class="section see"><dt>See also</dt><dd>vm_sport_stat_str </dd></dl>
</div>
</div>
<a id="ga7a009eea70525dd82c9cda34a6d0590d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga7a009eea70525dd82c9cda34a6d0590d">&#9670;&nbsp;</a></span>vm_sport_control()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_control </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_uint32_t&#160;</td>
<td class="paramname"><em>cmd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void *&#160;</td>
<td class="paramname"><em>data</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Send port control command to a port provider. </p>
<p>This function is similar to the <a class="el" href="group__file__system.html#ga78184a0887c6628e9e0c3bd8d4989e18" title="Provider specific control function. ">vm_ioctl()</a> command, but specific for sampling port providers. <em>cmd</em> specifies a command identifier which is defined with one of the VM_IOC_* calls.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<p>The behavior of this function in case <code>data</code> is NULL is implementation-defined, i.e., it depends on the underlying driver how the function will behave.</p>
<p>The contents of the memory pointed to by <code>data</code> after the call to this function is implementation-defined, i.e., it depends on the underlying driver how data is handled, and in which cases the data contents are specified or unspecified.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>upon success</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the port does not provide the corresponding service</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if <em>pd</em> is not a valid port descriptor</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled.</td></tr>
</table>
</dd>
</dl>
<dl class="section pre"><dt>Precondition</dt><dd>The system software library must have been initialized by a call to <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a>. </dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__file__system.html#ga78184a0887c6628e9e0c3bd8d4989e18" title="Provider specific control function. ">vm_ioctl()</a> </dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: port descriptor </td></tr>
<tr><td class="paramname">cmd</td><td>IN: command identifier </td></tr>
<tr><td class="paramname">data</td><td>INOUT: command specific data </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga5d9a374df2992c73452da63c9976dd8e"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga5d9a374df2992c73452da63c9976dd8e">&#9670;&nbsp;</a></span>vm_sport_test()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_test </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">vm_test_mode_t&#160;</td>
<td class="paramname"><em>tm</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">P4_uint32_t&#160;</td>
<td class="paramname"><em>cmd</em>&#160;</td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Control the driver's test mode. </p>
<p>This function can be used to access the driver's test features. The exact functionality is up to the driver, this is a generic API passing down commands to the driver to activate/deactivate synchronous or asynchronous tests.</p>
<p>Please also see the documentation for vm_test_mode_t.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>IN: port descriptor </td></tr>
<tr><td class="paramname">tm</td><td>IN: which test mode to select </td></tr>
<tr><td class="paramname">cmd</td><td>IN: arbitrary command for the provider </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="ga81897d7049aa205a9051fcf2b37b81a4"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga81897d7049aa205a9051fcf2b37b81a4">&#9670;&nbsp;</a></span>vm_sport_clear()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_clear </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Clear as sampling port, reset it to empty state. </p>
<p>Clearing a sampling port means to reset the state to empty just like it was at system boot time. This operation is typically only allowed by the writer of a sampling port.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>if the port content was cleared.</td></tr>
<tr><td class="paramname">P4_E_PERM</td><td>if the port is forbidden to be cleared from this side of the channel.</td></tr>
<tr><td class="paramname">P4_E_NOTIMPL</td><td>if the underlying port does not support to be cleared.</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if the port descriptor is invalid.</td></tr>
<tr><td class="paramname">P4_E_BUSY</td><td>if the port is currently busy, e.g., because it is being closed in another thread, too.</td></tr>
<tr><td class="paramname">P4_E_IO</td><td>if the underlying hardware had a fault.</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled. </td></tr>
</table>
</dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>The port descriptor of the port to be cleared </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a id="gab3911fef652c431f4c5e5bf586a14317"></a>
<h2 class="memtitle"><span class="permalink"><a href="#gab3911fef652c431f4c5e5bf586a14317">&#9670;&nbsp;</a></span>vm_sport_close()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">P4_e_t vm_sport_close </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structvm__port__desc__t.html">vm_port_desc_t</a> *&#160;</td>
<td class="paramname"><em>pd</em></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Close a sampling port. </p>
<p>Closing a port is the opposite of opening it. This will deallocate possible system resources used for the descriptor. After that, the port descriptor will not be usable anymore for operations on the port, but to use it again, the port has to be re-opened.</p>
<p>This function has undefined behavior before <a class="el" href="group__initialization.html#ga1700b78fbc2632387ff7f166ff98af3d" title="Initialize PSSW services. ">vm_init()</a> is invoked.</p>
<p>This function has undefined behavior unless <code>pd</code> is an open port descriptor.</p>
<p>The contents of <code>pd</code> will be unspecified in case this function returns P4_E_OK. In case of an error, the contents of <code>pd</code> will remain unchanged, because the error may indicate a temporary failure so that the closing could be repeated later.</p>
<dl class="section return"><dt>Returns</dt><dd></dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">P4_E_OK</td><td>if the port could be closed.</td></tr>
<tr><td class="paramname">P4_E_INVAL</td><td>if a parameter is invalid, e.g., if the port descriptor is invalid, or is in use or in the process of being closed by another thread.</td></tr>
<tr><td class="paramname">P4_E_BUSY</td><td>if the port is currently busy, e.g., because it is being closed in another thread, too.</td></tr>
<tr><td class="paramname">P4_E_IO</td><td>if the underlying hardware had a fault.</td></tr>
<tr><td class="paramname">P4_E_ABORT</td><td>if the call was aborted.</td></tr>
<tr><td class="paramname">P4_E_CANCEL</td><td>if the call was canceled. </td></tr>
</table>
</dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">pd</td><td>The port descriptor of the port to be closed </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">(C) Copyright SYSGO AG</li>
</ul>
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink