/share/man/man4/ng_atm.4

https://bitbucket.org/freebsd/freebsd-head/ · Forth · 416 lines · 416 code · 0 blank · 0 comment · 17 complexity · 3130931fa372c15f464f04e39097adc0 MD5 · raw file

  1. .\"
  2. .\" Copyright (c) 2001-2003
  3. .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
  4. .\" All rights reserved.
  5. .\"
  6. .\" Redistribution and use in source and binary forms, with or without
  7. .\" modification, are permitted provided that the following conditions
  8. .\" are met:
  9. .\" 1. Redistributions of source code must retain the above copyright
  10. .\" notice, this list of conditions and the following disclaimer.
  11. .\" 2. Redistributions in binary form must reproduce the above copyright
  12. .\" notice, this list of conditions and the following disclaimer in the
  13. .\" documentation and/or other materials provided with the distribution.
  14. .\"
  15. .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25. .\" SUCH DAMAGE.
  26. .\"
  27. .\" Author: Hartmut Brandt <harti@FreeBSD.org>
  28. .\"
  29. .\" $FreeBSD$
  30. .\"
  31. .\" ng_atm(4) man page
  32. .\"
  33. .Dd June 24, 2003
  34. .Dt NG_ATM 4
  35. .Os
  36. .Sh NAME
  37. .Nm ng_atm
  38. .Nd netgraph ATM node type
  39. .Sh SYNOPSIS
  40. .In sys/types.h
  41. .In net/if_atm.h
  42. .In netgraph.h
  43. .In netgraph/atm/ng_atm.h
  44. .Sh DESCRIPTION
  45. The
  46. .Nm atm
  47. netgraph node type allows
  48. .Xr natm 4
  49. ATM drivers to be connected to the
  50. .Xr netgraph 4
  51. networking subsystem.
  52. When the
  53. .Nm
  54. module is loaded a node is automatically created for each
  55. .Xr natm 4
  56. ATM interface.
  57. The nodes are named with the same name as the
  58. interface.
  59. Nodes are also created if a driver for an ATM
  60. card is loaded after
  61. .Nm
  62. was loaded.
  63. .Pp
  64. The
  65. .Nm atm
  66. nodes are persistent.
  67. They are removed when the interface is removed.
  68. .Dv NGM_SHUTDOWN
  69. messages are ignored by the node.
  70. .Sh HOOKS
  71. Four special hooks with fixed names and an unlimited number of hooks with user
  72. defined names are supported.
  73. Three of the fixed hooks are attached to
  74. strategic points in the information flow in the
  75. .Xr natm 4
  76. system and support only reading.
  77. The fourth fixed hook behaves like the other
  78. user hooks, but a number of management messages are sent along the hook.
  79. The other hooks can be attached to VCIs dynamically by means of
  80. control messages to the
  81. .Nm atm
  82. node and can be written and read.
  83. .Pp
  84. The four fixed hooks are:
  85. .Bl -tag -width ".Va orphans"
  86. .It Va input
  87. This is a connection to the raw input stream from the network.
  88. If this hook is connected, all incoming packets are delivered out to
  89. this hook.
  90. Note that this redirects ALL input.
  91. Neither
  92. .Xr natm 4
  93. nor the user hooks will see any input if
  94. .Va input
  95. is connected.
  96. An
  97. .Vt atm_pseudohdr
  98. (see
  99. .Xr natm 4 )
  100. is prepended to the actual data.
  101. .It Va output
  102. This is a connection to the raw output stream to the network device.
  103. If this hook is connected, all outgoing packets are handed over to
  104. the netgraph system and delivered to the hook instead of being delivered
  105. to the ATM driver.
  106. An
  107. .Vt atm_pseudohdr
  108. (see
  109. .Xr natm 4 )
  110. is prepended to the actual data.
  111. .It Va orphans
  112. This hook receives all packets that are unrecognized, i.e., do not belong to
  113. either a
  114. .Xr natm 4
  115. socket, a
  116. .Nm
  117. VCI or
  118. .Xr natm 4
  119. IP.
  120. Because ATM is connection oriented and packets are received on a given VCI only
  121. when someone initiates this VCI, packets should never be orphaned.
  122. There is
  123. however one exception: if you use
  124. .Xr natm 4
  125. IP with LLC/SNAP encapsulation packets with do not have the IP protocol
  126. indicated in the packet header are delivered out of this hook.
  127. An
  128. .Vt atm_pseudohdr
  129. (see
  130. .Xr natm 4 )
  131. is prepended to the actual data send out to the hook.
  132. .It Va manage
  133. This hook behaves exactly like a normal user hook (see below) except that
  134. the node at the other hand will receive management messages.
  135. .El
  136. .Pp
  137. Hooks for dynamically initiated VCIs can have whatever name is allowed by
  138. .Xr netgraph 4
  139. as long as the name does not collide with one of the three predefined names.
  140. .Pp
  141. To initiate packet sending and receiving on a dynamic hook, one has to issue
  142. a
  143. .Dv NGM_ATM_CPCS_INIT
  144. control message.
  145. To terminate sending and receiving one must send a
  146. .Dv NGM_ATM_CPCS_TERM
  147. message (see
  148. .Sx CONTROL MESSAGES ) .
  149. The data sent and received on these hooks has no additional
  150. headers.
  151. .Sh CONTROL MESSAGES
  152. This node type supports the generic messages plus the following:
  153. .Bl -tag -width 4n
  154. .It Dv NGM_ATM_GET_IFNAME
  155. Return the name of the interface as a
  156. .Dv NUL Ns
  157. -terminated string.
  158. This is normally the same name as that of the node.
  159. .It Dv NGM_ATM_GET_CONFIG
  160. Returns a structure defining the configuration of the interface:
  161. .Bd -literal
  162. struct ng_atm_config {
  163. uint32_t pcr; /* peak cell rate */
  164. uint32_t maxvpi; /* maximum vpi */
  165. uint32_t maxvci; /* maximum vci */
  166. uint32_t max_vpcs; /* maximum number of VPCs */
  167. uint32_t max_vccs; /* maximum number of VCCs */
  168. };
  169. .Ed
  170. .It Dv NGM_ATM_GET_VCCS
  171. Returns the table of open VCCs from the driver.
  172. This table consists of
  173. a header and a variable sized array of entries, one for each open VCC:
  174. .Bd -literal
  175. struct atmio_vcctable {
  176. uint32_t count; /* number of vccs */
  177. struct atmio_vcc vccs[0]; /* array of VCCs */
  178. };
  179. struct atmio_vcc {
  180. uint16_t flags; /* flags */
  181. uint16_t vpi; /* VPI */
  182. uint16_t vci; /* VCI */
  183. uint16_t rmtu; /* Receive maximum CPCS size */
  184. uint16_t tmtu; /* Transmit maximum CPCS size */
  185. uint8_t aal; /* aal type */
  186. uint8_t traffic; /* traffic type */
  187. struct atmio_tparam tparam; /* traffic parameters */
  188. };
  189. struct atmio_tparam {
  190. uint32_t pcr; /* 24bit: Peak Cell Rate */
  191. uint32_t scr; /* 24bit: VBR Sustainable Cell Rate */
  192. uint32_t mbs; /* 24bit: VBR Maximum burst size */
  193. uint32_t mcr; /* 24bit: MCR */
  194. uint32_t icr; /* 24bit: ABR ICR */
  195. uint32_t tbe; /* 24bit: ABR TBE (1...2^24-1) */
  196. uint8_t nrm; /* 3bit: ABR Nrm */
  197. uint8_t trm; /* 3bit: ABR Trm */
  198. uint16_t adtf; /* 10bit: ABR ADTF */
  199. uint8_t rif; /* 4bit: ABR RIF */
  200. uint8_t rdf; /* 4bit: ABR RDF */
  201. uint8_t cdf; /* 3bit: ABR CDF */
  202. };
  203. .Ed
  204. .Pp
  205. Note that this is the driver's table, so all VCCs opened via
  206. .Xr natm 4
  207. sockets and IP are also shown.
  208. They can, however, be distinguished by
  209. their flags.
  210. The
  211. .Va flags
  212. field contains the following flags:
  213. .Pp
  214. .Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
  215. .It Dv ATM_PH_AAL5
  216. use AAL5 instead of AAL0
  217. .It Dv ATM_PH_LLCSNAP
  218. if AAL5 use LLC SNAP encapsulation
  219. .It Dv ATM_FLAG_NG
  220. this is a netgraph VCC
  221. .It Dv ATM_FLAG_HARP
  222. this is a HARP VCC
  223. .It Dv ATM_FLAG_NORX
  224. transmit only VCC
  225. .It Dv ATM_FLAG_NOTX
  226. receive only VCC
  227. .It Dv ATMIO_FLAG_PVC
  228. treat channel as a PVC
  229. .El
  230. .Pp
  231. If the
  232. .Dv ATM_FLAG_NG
  233. flag is set, then
  234. .Va traffic
  235. and
  236. .Va tparam
  237. contain meaningful information.
  238. .Pp
  239. The
  240. .Va aal
  241. field
  242. contains one of the following values:
  243. .Pp
  244. .Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
  245. .It Dv ATMIO_AAL_0
  246. AAL 0 (raw cells)
  247. .It Dv ATMIO_AAL_34
  248. AAL 3 or AAL 4
  249. .It Dv ATMIO_AAL_5
  250. AAL 5
  251. .It Dv ATMIO_AAL_RAW
  252. device specific raw cells
  253. .El
  254. .Pp
  255. The
  256. .Va traffic
  257. field
  258. can have one of the following values (not all drivers support
  259. all traffic types however):
  260. .Pp
  261. .Bl -tag -width ".Dv ATM_PH_LLCSNAP" -offset indent -compact
  262. .It Dv ATMIO_TRAFFIC_UBR
  263. .It Dv ATMIO_TRAFFIC_CBR
  264. .It Dv ATMIO_TRAFFIC_ABR
  265. .It Dv ATMIO_TRAFFIC_VBR
  266. .El
  267. .It Dv NGM_ATM_CPCS_INIT
  268. Initialize a VCC for sending and receiving.
  269. The argument is a structure:
  270. .Bd -literal
  271. struct ng_atm_cpcs_init {
  272. char name[NG_HOOKSIZ];
  273. uint32_t flags; /* flags. (if_natmio.h) */
  274. uint16_t vci; /* VCI to open */
  275. uint16_t vpi; /* VPI to open */
  276. uint16_t rmtu; /* receive maximum PDU */
  277. uint16_t tmtu; /* transmit maximum PDU */
  278. uint8_t aal; /* AAL type (if_natmio.h) */
  279. uint8_t traffic; /* traffic type (if_natmio.h) */
  280. uint32_t pcr; /* Peak cell rate */
  281. uint32_t scr; /* Sustainable cell rate */
  282. uint32_t mbs; /* Maximum burst size */
  283. uint32_t mcr; /* Minimum cell rate */
  284. uint32_t icr; /* ABR: Initial cell rate */
  285. uint32_t tbe; /* ABR: Transmit buffer exposure */
  286. uint8_t nrm; /* ABR: Nrm */
  287. uint8_t trm; /* ABR: Trm */
  288. uint16_t adtf; /* ABR: ADTF */
  289. uint8_t rif; /* ABR: RIF */
  290. uint8_t rdf; /* ABR: RDF */
  291. uint8_t cdf; /* ABR: CDF */
  292. };
  293. .Ed
  294. .Pp
  295. The
  296. .Va name
  297. field
  298. is the name of the hook for which sending and receiving should be enabled.
  299. This hook must already be connected.
  300. The
  301. .Va vpi
  302. and
  303. .Va vci
  304. fields
  305. are the respective VPI and VCI values to use for the ATM cells.
  306. They must be
  307. within the range, given by the
  308. .Va maxvpi
  309. and
  310. .Va maxvci
  311. fields of the
  312. .Vt ng_atm_config
  313. structure.
  314. The
  315. .Va flags
  316. field
  317. contains the flags (see above) and the other fields describe the
  318. type of traffic.
  319. .It Dv NGM_ATM_CPCS_TERM
  320. Stop sending and receiving on the indicated hook.
  321. The argument is a
  322. .Bd -literal
  323. struct ng_atm_cpcs_term {
  324. char name[NG_HOOKSIZ];
  325. };
  326. .Ed
  327. .El
  328. .Sh MANAGEMENT MESSAGES
  329. If the
  330. .Va manage
  331. hook is connected, certain messages are sent along the hook.
  332. They are
  333. received by the peer node with a cookie of
  334. .Dv NG_ATM_COOKIE .
  335. .Bl -tag -width 4n
  336. .It Dv NGM_ATM_CARRIER_CHANGE
  337. The carrier state of the ATM physical interface has changed.
  338. The message has the following structure:
  339. .Bd -literal
  340. struct ng_atm_carrier_change {
  341. uint32_t node;
  342. uint32_t state;
  343. };
  344. .Ed
  345. .Pp
  346. The
  347. .Va node
  348. field
  349. is the node ID of the ATM node.
  350. This can be used by the managing entity
  351. (for example
  352. .Xr ilmid 8 )
  353. to manage several interfaces at the same time through the same node.
  354. The
  355. .Va state
  356. field is 1 if the carrier was detected, and 0 if it was lost.
  357. .It Dv NGM_ATM_VCC_CHANGE
  358. A permanent VCC has been added, deleted or changed.
  359. This is used by
  360. .Xr ilmid 8
  361. to generate the appropriate ILMI traps.
  362. The structure of the message is:
  363. .Bd -literal
  364. struct ng_atm_vcc_change {
  365. uint32_t node;
  366. uint16_t vci;
  367. uint8_t vpi;
  368. uint8_t state;
  369. };
  370. .Ed
  371. Where
  372. .Va state
  373. is 0 if the PVC was deleted, and 1 if it was added or modified.
  374. .El
  375. .Sh FLOW CONTROL
  376. If the hardware driver supports it, the node can emit flow control messages
  377. along a user hook.
  378. The format of these messages is described in
  379. .In netgraph/ng_message.h .
  380. The
  381. .Nm atm
  382. node may generate
  383. .Dv NGM_HIGH_WATER_PASSED
  384. and
  385. .Dv NGM_LOW_WATER_PASSED
  386. messages.
  387. The first one indicates that the hardware driver has stopped output
  388. on the channel and drops new packets, the second one reports that
  389. output was reenabled.
  390. Currently, the structures are not filled with
  391. information.
  392. .Sh SHUTDOWN
  393. The nodes are persistent as long as the corresponding interface exists.
  394. Upon receipt of a
  395. .Dv NGM_SHUTDOWN
  396. messages, all hooks are disconnected and the node is reinitialized.
  397. All
  398. VCCs opened via
  399. .Xr netgraph 4
  400. are closed.
  401. When the ATM interface is unloaded,
  402. the node disappears.
  403. If the node is compiled with
  404. .Dv NGATM_DEBUG
  405. there is a sysctl
  406. .Va net.graph.atm.allow_shutdown
  407. which, when set to a non-zero value, allows the nodes to shut down.
  408. Note that this is intended for development only and may lead to kernel
  409. panics if set.
  410. .Sh SEE ALSO
  411. .Xr natm 4 ,
  412. .Xr netgraph 4 ,
  413. .Xr ng_ether 4 ,
  414. .Xr ngctl 8
  415. .Sh AUTHORS
  416. .An Harti Brandt Aq harti@FreeBSD.org