/share/man/man4/ng_ccatm.4

https://bitbucket.org/freebsd/freebsd-head/ · Forth · 324 lines · 324 code · 0 blank · 0 comment · 7 complexity · 31904cf01e4daa89c023bee05979173a MD5 · raw file

  1. .\"
  2. .\" Copyright (c) 2001-2004
  3. .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
  4. .\" All rights reserved.
  5. .\" Copyright (c) 2005
  6. .\" Hartmut Brandt.
  7. .\" All rights reserved.
  8. .\"
  9. .\" Author: Harti Brandt <harti@FreeBSD.org>
  10. .\"
  11. .\" Redistribution and use in source and binary forms, with or without
  12. .\" modification, are permitted provided that the following conditions
  13. .\" are met:
  14. .\" 1. Redistributions of source code must retain the above copyright
  15. .\" notice, this list of conditions and the following disclaimer.
  16. .\" 2. Redistributions in binary form must reproduce the above copyright
  17. .\" notice, this list of conditions and the following disclaimer in the
  18. .\" documentation and/or other materials provided with the distribution.
  19. .\"
  20. .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23. .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  24. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30. .\" SUCH DAMAGE.
  31. .\"
  32. .\" $FreeBSD$
  33. .\"
  34. .Dd March 10, 2005
  35. .Dt NG_CCATM 4
  36. .Os
  37. .Sh NAME
  38. .Nm ng_ccatm
  39. .Nd "ATM Call Control netgraph node type"
  40. .Sh SYNOPSIS
  41. .In netnatm/unimsg.h
  42. .In netnatm/msg/unistruct.h
  43. .In netnatm/sig/unidef.h
  44. .In netnatm/api/unisap.h
  45. .In netnatm/api/atmapi.h
  46. .In netnatm/api/ccatm.h
  47. .In netgraph.h
  48. .In netgraph/ng_uni.h
  49. .In netgraph/ng_ccatm.h
  50. .Sh DESCRIPTION
  51. The
  52. .Nm
  53. node implements the API specified by the ATM Forum for access to ATM services
  54. (see ATM-Forum document
  55. .Pa af-saa-0108 ) .
  56. This document specifies the semantics
  57. of the API, not the exact language binding.
  58. For this reason, it is expected that
  59. this implementation is neither compile-time nor binary compatible with
  60. other implementations of this API.
  61. It should, however, be fairly straightforward
  62. to convert between different API implementations.
  63. .Pp
  64. This node is usually stacked on top of one or more UNI nodes (see
  65. .Xr ng_uni 4 ) .
  66. Each of these hooks appears as a
  67. .Dq port
  68. to the user of the node.
  69. It also has one hook connected to the ILMI daemon for management purposes.
  70. .Pp
  71. The node is removed when it receives a
  72. .Dv NGM_SHUTDOWN
  73. messages or when all hooks are disconnected.
  74. .Sh HOOKS
  75. The node understands a number of hooks with predefined names and an
  76. unlimited number of hooks for user connections.
  77. The predefined names are:
  78. .Bl -tag -width ".Va orphans"
  79. .It Va uni Ns Ar NNN
  80. These hooks stack the
  81. .Nm
  82. node on top of a UNI stack.
  83. The node expects the interface on these hooks
  84. to conform to the upper interface specified in
  85. .Xr ng_uni 4 .
  86. These hooks are forced into queuing mode, so that there are no circular
  87. calls from call control to UNI and UNI back to call control.
  88. The
  89. .Ar NNN
  90. in the hook name is the decimal port number and should not be zero.
  91. The port number is a 32-bit unsigned integer.
  92. .It Va manage
  93. This hook should be connected to the ILMI daemon.
  94. No data is ever sent on this hook and all received data is discarded.
  95. The hook is used to send control messages along.
  96. .It Va dump
  97. On receipt of a
  98. .Dv NGM_CCATM_DUMP
  99. command a textual description of the current state of the node is sent
  100. out of this hook.
  101. This text is sent as one large message consisting of more
  102. than one
  103. .Vt mbuf .
  104. .El
  105. .Pp
  106. All other hook names are taken to be user hooks and correspond to an
  107. ATM endpoint as specified in the ATM Forum document.
  108. The interface on these hooks is defined in
  109. .In atmapi.h
  110. and uses a structure
  111. .Bd -literal
  112. struct ccatm_op {
  113. uint32_t op; /* request code */
  114. u_char data[]; /* optional data */
  115. };
  116. .Ed
  117. .Pp
  118. This structure is followed directly by the data for the operation.
  119. The opcode is one of the following:
  120. .Bd -literal
  121. enum atmop {
  122. ATMOP_RESP,
  123. ATMOP_ABORT_CONNECTION,
  124. ATMOP_ACCEPT_INCOMING_CALL,
  125. ATMOP_ADD_PARTY,
  126. ATMOP_ADD_PARTY_REJECT,
  127. ATMOP_ADD_PARTY_SUCCESS,
  128. ATMOP_ARRIVAL_OF_INCOMING_CALL,
  129. ATMOP_CALL_RELEASE,
  130. ATMOP_CONNECT_OUTGOING_CALL,
  131. ATMOP_DROP_PARTY,
  132. ATMOP_GET_LOCAL_PORT_INFO,
  133. ATMOP_P2MP_CALL_ACTIVE,
  134. ATMOP_P2P_CALL_ACTIVE,
  135. ATMOP_PREPARE_INCOMING_CALL,
  136. ATMOP_PREPARE_OUTGOING_CALL,
  137. ATMOP_QUERY_CONNECTION_ATTRIBUTES,
  138. ATMOP_REJECT_INCOMING_CALL,
  139. ATMOP_SET_CONNECTION_ATTRIBUTES,
  140. ATMOP_WAIT_ON_INCOMING_CALL,
  141. ATMOP_SET_CONNECTION_ATTRIBUTES_X,
  142. ATMOP_QUERY_CONNECTION_ATTRIBUTES_X,
  143. ATMOP_QUERY_STATE
  144. };
  145. .Ed
  146. .Pp
  147. These codes correspond directly to the operations specified in the ATM
  148. Forum document with the following exceptions:
  149. .Bl -tag -width indent
  150. .It Dv ATMOP_RESP
  151. As discussed in
  152. .Xr ng_uni 4 ,
  153. this is used to
  154. .Dq synchronify
  155. the interface.
  156. The argument is a
  157. .Bd -literal
  158. struct atm_resp {
  159. int32_t resp;
  160. uint32_t data; /* type of attached data */
  161. };
  162. .Ed
  163. .Pp
  164. If the response code
  165. .Va resp
  166. is zero, the node has accepted the user request.
  167. If something goes wrong,
  168. .Va resp
  169. contains an error code.
  170. For requests that return data,
  171. .Va data
  172. contains a code describing the type of data and the data itself
  173. starts immediately after the structure.
  174. .It Dv ATMOP_QUERY_CONNECTION_ATTRIBUTES_X
  175. This is the same as
  176. .Dv ATMOP_QUERY_CONNECTION_ATTRIBUTES
  177. except that it allows to query several attributes
  178. within one request.
  179. .It Dv ATMOP_SET_CONNECTION_ATTRIBUTES_X
  180. This is the same as
  181. .Dv ATMOP_SET_CONNECTION_ATTRIBUTES
  182. except that it allows to set several attributes
  183. within one request.
  184. The list of attributes is followed directly by the attributes in the same
  185. order as they appear in the list.
  186. .El
  187. .Pp
  188. If a user hook is disconnected, an active connection on that hook is released.
  189. Incoming connections waiting to be accepted are reoffered to other
  190. listening hooks or rejected.
  191. .Sh CONTROL MESSAGES
  192. Besides the generic messages the node understands the following special
  193. messages:
  194. .Bl -tag -width indent
  195. .It Dv NGM_CCATM_DUMP
  196. This causes the internal state of the node to be dumped in ASCII to the
  197. .Va dump
  198. hook.
  199. .It Dv NGM_CCATM_STOP
  200. This message causes all connections on that port to be aborted (not released!\&)
  201. and all ATM endpoints which are bound to that port to be closed.
  202. It stops processing of all messages from the UNI stack on that port UNI stack.
  203. The argument is a
  204. .Bd -literal
  205. struct ngm_ccatm_port {
  206. uint32_t port;
  207. };
  208. .Ed
  209. .Pp
  210. .It Dv NGM_CCATM_START
  211. Start processing on the port.
  212. The argument is a
  213. .Vt ngm_ccatm_port
  214. structure.
  215. .It Dv NGM_CCATM_CLEAR
  216. This message takes a
  217. .Vt ngm_ccatm_port
  218. structure and clears all prefixes and addresses on that port.
  219. If the port number is zero, all ports are cleared.
  220. .It Dv NGM_CCATM_GET_ADDRESSES
  221. Get the list of all registered addresses on the given port.
  222. The argument is a
  223. .Vt ngm_ccatm_port
  224. structure and the result is a
  225. .Vt ngm_ccatm_get_addresses
  226. structure:
  227. .Bd -literal
  228. struct ngm_ccatm_get_addresses {
  229. uint32_t count;
  230. struct ngm_ccatm_address_req addr[0];
  231. };
  232. struct ngm_ccatm_address_req {
  233. uint32_t port;
  234. struct uni_addr addr;
  235. };
  236. .Ed
  237. .Pp
  238. If the
  239. .Va port
  240. field is zero in the request, all addresses on all ports
  241. are returned.
  242. If it is not zero, only the addresses on that port are reported.
  243. The number of addresses is returned in the
  244. .Va count
  245. field.
  246. .It Dv NGM_CCATM_ADDRESS_REGISTERED
  247. This message is used by ILMI to inform the
  248. .Nm
  249. node that a previous address registration request was successful.
  250. This causes the node to activate that address.
  251. The argument to the message is a
  252. .Vt ngm_ccatm_address_req
  253. structure.
  254. .It Dv NGM_CCATM_ADDRESS_UNREGISTERED
  255. This message is used by ILMI to inform the
  256. .Nm
  257. node that an address has been unregistered.
  258. The node clears that address from its tables.
  259. The argument is a
  260. .Vt ngm_ccatm_address_req
  261. structure.
  262. .It Dv NGM_CCATM_SET_PORT_PARAM
  263. This request sets the parameters on the given port.
  264. The argument is a
  265. .Bd -literal
  266. struct ngm_ccatm_atm_port {
  267. uint32_t port; /* port for which to set parameters */
  268. uint32_t pcr; /* port peak cell rate */
  269. uint32_t max_vpi_bits;
  270. uint32_t max_vci_bits;
  271. uint32_t max_svpc_vpi;
  272. uint32_t max_svcc_vpi;
  273. uint32_t min_svcc_vci;
  274. uint8_t esi[6];
  275. uint32_t num_addr;
  276. };
  277. .Ed
  278. .Pp
  279. This should be used only by ILMI and when that port is stopped and the
  280. address and prefix tables of that port are empty.
  281. The
  282. .Va num_addr
  283. field is ignored.
  284. .It Dv NGM_CCATM_GET_PORT_PARAM
  285. Retrieve the parameters of the given port.
  286. The argument is a
  287. .Vt ngm_ccatm_port
  288. and the result a
  289. .Vt ngm_ccatm_atm_port .
  290. .It Dv NGM_CCATM_GET_PORTLIST
  291. Get a list of all available ports on that node.
  292. This is returned as a
  293. .Bd -literal
  294. struct ngm_ccatm_portlist {
  295. uint32_t nports;
  296. uint32_t ports[];
  297. };
  298. .Ed
  299. .It Dv NGM_CCATM_GETSTATE
  300. Return the state of a port.
  301. The argument is a
  302. .Vt "struct ngm_ccatm_port"
  303. and the return values as a
  304. .Vt uint32_t .
  305. .It Dv NGM_CCATM_SETLOG
  306. This requests sets a new logging level and returns the previous one.
  307. The argument is either a
  308. .Vt uint32_t
  309. in which case it specifies the new logging level, or may be empty
  310. in which case just the old level is returned as a
  311. .Vt uint32_t .
  312. .It Dv NGM_CCATM_RESET
  313. Reset the node.
  314. This is allowed only if the number of user hooks and connected UNI stacks is
  315. zero.
  316. .It Dv NGM_CCATM_GET_EXSTAT
  317. Return extended status information from the node.
  318. .El
  319. .Sh SEE ALSO
  320. .Xr netgraph 4 ,
  321. .Xr ng_uni 4 ,
  322. .Xr ngctl 8
  323. .Sh AUTHORS
  324. .An Harti Brandt Aq harti@FreeBSD.org