Documentation/DocBook/media/dvb/ca.xml

   1 <title>DVB CA Device</title>
   2 <para>The DVB CA device controls the conditional access hardware. It can be accessed through
   3 <emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by
   4 including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application.
   5 </para>
   6
   7 <section id="ca_data_types">
   8 <title>CA Data Types</title>
   9
  10
  11 <section id="ca-slot-info">
  12 <title>ca_slot_info_t</title>
  13  <programlisting>
  14 typedef struct ca_slot_info {
  15         int num;               /&#x22C6; slot number &#x22C6;/
  16
  17         int type;              /&#x22C6; CA interface this slot supports &#x22C6;/
  18 #define CA_CI            1     /&#x22C6; CI high level interface &#x22C6;/
  19 #define CA_CI_LINK       2     /&#x22C6; CI link layer level interface &#x22C6;/
  20 #define CA_CI_PHYS       4     /&#x22C6; CI physical layer level interface &#x22C6;/
  21 #define CA_DESCR         8     /&#x22C6; built-in descrambler &#x22C6;/
  22 #define CA_SC          128     /&#x22C6; simple smart card interface &#x22C6;/
  23
  24         unsigned int flags;
  25 #define CA_CI_MODULE_PRESENT 1 /&#x22C6; module (or card) inserted &#x22C6;/
  26 #define CA_CI_MODULE_READY   2
  27 } ca_slot_info_t;
  28 </programlisting>
  29
  30 </section>
  31 <section id="ca-descr-info">
  32 <title>ca_descr_info_t</title>
  33 <programlisting>
  34 typedef struct ca_descr_info {
  35         unsigned int num;  /&#x22C6; number of available descramblers (keys) &#x22C6;/
  36         unsigned int type; /&#x22C6; type of supported scrambling system &#x22C6;/
  37 #define CA_ECD           1
  38 #define CA_NDS           2
  39 #define CA_DSS           4
  40 } ca_descr_info_t;
  41 </programlisting>
  42
  43 </section>
  44 <section id="ca-caps">
  45 <title>ca_caps_t</title>
  46 <programlisting>
  47 typedef struct ca_caps {
  48         unsigned int slot_num;  /&#x22C6; total number of CA card and module slots &#x22C6;/
  49         unsigned int slot_type; /&#x22C6; OR of all supported types &#x22C6;/
  50         unsigned int descr_num; /&#x22C6; total number of descrambler slots (keys) &#x22C6;/
  51         unsigned int descr_type;/&#x22C6; OR of all supported types &#x22C6;/
  52  } ca_cap_t;
  53 </programlisting>
  54
  55 </section>
  56 <section id="ca-msg">
  57 <title>ca_msg_t</title>
  58 <programlisting>
  59 /&#x22C6; a message to/from a CI-CAM &#x22C6;/
  60 typedef struct ca_msg {
  61         unsigned int index;
  62         unsigned int type;
  63         unsigned int length;
  64         unsigned char msg[256];
  65 } ca_msg_t;
  66 </programlisting>
  67
  68 </section>
  69 <section id="ca-descr">
  70 <title>ca_descr_t</title>
  71 <programlisting>
  72 typedef struct ca_descr {
  73         unsigned int index;
  74         unsigned int parity;
  75         unsigned char cw[8];
  76 } ca_descr_t;
  77 </programlisting>
  78 </section>
  79
  80 <section id="ca-pid">
  81 <title>ca-pid</title>
  82 <programlisting>
  83 typedef struct ca_pid {
  84         unsigned int pid;
  85         int index;              /&#x22C6; -1 == disable&#x22C6;/
  86 } ca_pid_t;
  87 </programlisting>
  88 </section></section>
  89
  90 <section id="ca_function_calls">
  91 <title>CA Function Calls</title>
  92
  93
  94 <section id="ca_fopen">
  95 <title>open()</title>
  96 <para>DESCRIPTION
  97 </para>
  98 <informaltable><tgroup cols="1"><tbody><row><entry
  99  align="char">
 100 <para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para>
 101 <para>When an open() call has succeeded, the device will be ready for use.
 102  The significance of blocking or non-blocking mode is described in the
 103  documentation for functions where there is a difference. It does not affect the
 104  semantics of the open() call itself. A device opened in blocking mode can later
 105  be put into non-blocking mode (and vice versa) using the F_SETFL command
 106  of the fcntl system call. This is a standard system call, documented in the Linux
 107  manual page for fcntl. Only one user can open the CA Device in O_RDWR
 108  mode. All other attempts to open the device in this mode will fail, and an error
 109  code will be returned.</para>
 110 </entry>
 111  </row></tbody></tgroup></informaltable>
 112 <para>SYNOPSIS
 113 </para>
 114 <informaltable><tgroup cols="1"><tbody><row><entry
 115  align="char">
 116 <para>int open(const char &#x22C6;deviceName, int flags);</para>
 117 </entry>
 118  </row></tbody></tgroup></informaltable>
 119 <para>PARAMETERS
 120 </para>
 121 <informaltable><tgroup cols="2"><tbody><row><entry
 122  align="char">
 123 <para>const char
 124  *deviceName</para>
 125 </entry><entry
 126  align="char">
 127 <para>Name of specific video device.</para>
 128 </entry>
 129  </row><row><entry
 130  align="char">
 131 <para>int flags</para>
 132 </entry><entry
 133  align="char">
 134 <para>A bit-wise OR of the following flags:</para>
 135 </entry>
 136  </row><row><entry
 137  align="char">
 138 </entry><entry
 139  align="char">
 140 <para>O_RDONLY read-only access</para>
 141 </entry>
 142  </row><row><entry
 143  align="char">
 144 </entry><entry
 145  align="char">
 146 <para>O_RDWR read/write access</para>
 147 </entry>
 148  </row><row><entry
 149  align="char">
 150 </entry><entry
 151  align="char">
 152 <para>O_NONBLOCK open in non-blocking mode</para>
 153 </entry>
 154  </row><row><entry
 155  align="char">
 156 </entry><entry
 157  align="char">
 158 <para>(blocking mode is the default)</para>
 159 </entry>
 160  </row></tbody></tgroup></informaltable>
 161 <para>RETURN VALUE</para>
 162 <informaltable><tgroup cols="2"><tbody><row><entry
 163  align="char">
 164 <para>ENODEV</para>
 165 </entry><entry
 166  align="char">
 167 <para>Device driver not loaded/available.</para>
 168 </entry>
 169  </row><row><entry
 170  align="char">
 171 <para>EINTERNAL</para>
 172 </entry><entry
 173  align="char">
 174 <para>Internal error.</para>
 175 </entry>
 176  </row><row><entry
 177  align="char">
 178 <para>EBUSY</para>
 179 </entry><entry
 180  align="char">
 181 <para>Device or resource busy.</para>
 182 </entry>
 183  </row><row><entry
 184  align="char">
 185 <para>EINVAL</para>
 186 </entry><entry
 187  align="char">
 188 <para>Invalid argument.</para>
 189 </entry>
 190  </row></tbody></tgroup></informaltable>
 191
 192 </section>
 193 <section id="ca_fclose">
 194 <title>close()</title>
 195 <para>DESCRIPTION
 196 </para>
 197 <informaltable><tgroup cols="1"><tbody><row><entry
 198  align="char">
 199 <para>This system call closes a previously opened audio device.</para>
 200 </entry>
 201  </row></tbody></tgroup></informaltable>
 202 <para>SYNOPSIS
 203 </para>
 204 <informaltable><tgroup cols="1"><tbody><row><entry
 205  align="char">
 206 <para>int close(int fd);</para>
 207 </entry>
 208  </row></tbody></tgroup></informaltable>
 209 <para>PARAMETERS
 210 </para>
 211 <informaltable><tgroup cols="2"><tbody><row><entry
 212  align="char">
 213 <para>int fd</para>
 214 </entry><entry
 215  align="char">
 216 <para>File descriptor returned by a previous call to open().</para>
 217 </entry>
 218  </row></tbody></tgroup></informaltable>
 219 <para>RETURN VALUE</para>
 220 <informaltable><tgroup cols="2"><tbody><row><entry
 221  align="char">
 222 <para>EBADF</para>
 223 </entry><entry
 224  align="char">
 225 <para>fd is not a valid open file descriptor.</para>
 226 </entry>
 227  </row></tbody></tgroup></informaltable>
 228  </section>
 229
 230 <section id="CA_RESET"
 231 role="subsection"><title>CA_RESET</title>
 232 <para>DESCRIPTION
 233 </para>
 234 <informaltable><tgroup cols="1"><tbody><row><entry
 235  align="char">
 236 <para>This ioctl is undocumented. Documentation is welcome.</para>
 237 </entry>
 238  </row></tbody></tgroup></informaltable>
 239 <para>SYNOPSIS
 240 </para>
 241 <informaltable><tgroup cols="1"><tbody><row><entry
 242  align="char">
 243 <para>int ioctl(fd, int request = CA_RESET);
 244 </para>
 245 </entry>
 246  </row></tbody></tgroup></informaltable>
 247 <para>PARAMETERS
 248 </para>
 249 <informaltable><tgroup cols="2"><tbody><row><entry
 250  align="char">
 251 <para>int fd</para>
 252 </entry><entry
 253  align="char">
 254 <para>File descriptor returned by a previous call to open().</para>
 255 </entry>
 256  </row><row><entry
 257  align="char">
 258 <para>int request</para>
 259 </entry><entry
 260  align="char">
 261 <para>Equals CA_RESET for this command.</para>
 262 </entry>
 263  </row></tbody></tgroup></informaltable>
 264 &return-value-dvb;
 265 </section>
 266
 267 <section id="CA_GET_CAP"
 268 role="subsection"><title>CA_GET_CAP</title>
 269 <para>DESCRIPTION
 270 </para>
 271 <informaltable><tgroup cols="1"><tbody><row><entry
 272  align="char">
 273 <para>This ioctl is undocumented. Documentation is welcome.</para>
 274 </entry>
 275  </row></tbody></tgroup></informaltable>
 276 <para>SYNOPSIS
 277 </para>
 278 <informaltable><tgroup cols="1"><tbody><row><entry
 279  align="char">
 280 <para>int ioctl(fd, int request = CA_GET_CAP,
 281  ca_caps_t *);</para>
 282 </entry>
 283  </row></tbody></tgroup></informaltable>
 284 <para>PARAMETERS
 285 </para>
 286 <informaltable><tgroup cols="2"><tbody><row><entry
 287  align="char">
 288 <para>int fd</para>
 289 </entry><entry
 290  align="char">
 291 <para>File descriptor returned by a previous call to open().</para>
 292 </entry>
 293  </row><row><entry
 294  align="char">
 295 <para>int request</para>
 296 </entry><entry
 297  align="char">
 298 <para>Equals CA_GET_CAP for this command.</para>
 299 </entry>
 300  </row><row><entry
 301  align="char">
 302 <para>ca_caps_t *
 303 </para>
 304 </entry><entry
 305  align="char">
 306 <para>Undocumented.</para>
 307 </entry>
 308  </row></tbody></tgroup></informaltable>
 309 &return-value-dvb;
 310 </section>
 311
 312 <section id="CA_GET_SLOT_INFO"
 313 role="subsection"><title>CA_GET_SLOT_INFO</title>
 314 <para>DESCRIPTION
 315 </para>
 316 <informaltable><tgroup cols="1"><tbody><row><entry
 317  align="char">
 318 <para>This ioctl is undocumented. Documentation is welcome.</para>
 319 </entry>
 320  </row></tbody></tgroup></informaltable>
 321 <para>SYNOPSIS
 322 </para>
 323 <informaltable><tgroup cols="1"><tbody><row><entry
 324  align="char">
 325 <para>int ioctl(fd, int request = CA_GET_SLOT_INFO,
 326  ca_slot_info_t *);</para>
 327 </entry>
 328  </row></tbody></tgroup></informaltable>
 329 <para>PARAMETERS
 330 </para>
 331 <informaltable><tgroup cols="2"><tbody><row><entry
 332  align="char">
 333 <para>int fd</para>
 334 </entry><entry
 335  align="char">
 336 <para>File descriptor returned by a previous call to open().</para>
 337 </entry>
 338  </row><row><entry
 339  align="char">
 340 <para>int request</para>
 341 </entry><entry
 342  align="char">
 343 <para>Equals CA_GET_SLOT_INFO for this command.</para>
 344 </entry>
 345  </row><row><entry
 346  align="char">
 347 <para>ca_slot_info_t *
 348 </para>
 349 </entry><entry
 350  align="char">
 351 <para>Undocumented.</para>
 352 </entry>
 353  </row></tbody></tgroup></informaltable>
 354 &return-value-dvb;
 355 </section>
 356
 357 <section id="CA_GET_DESCR_INFO"
 358 role="subsection"><title>CA_GET_DESCR_INFO</title>
 359 <para>DESCRIPTION
 360 </para>
 361 <informaltable><tgroup cols="1"><tbody><row><entry
 362  align="char">
 363 <para>This ioctl is undocumented. Documentation is welcome.</para>
 364 </entry>
 365  </row></tbody></tgroup></informaltable>
 366 <para>SYNOPSIS
 367 </para>
 368 <informaltable><tgroup cols="1"><tbody><row><entry
 369  align="char">
 370 <para>int ioctl(fd, int request = CA_GET_DESCR_INFO,
 371  ca_descr_info_t *);</para>
 372 </entry>
 373  </row></tbody></tgroup></informaltable>
 374 <para>PARAMETERS
 375 </para>
 376 <informaltable><tgroup cols="2"><tbody><row><entry
 377  align="char">
 378 <para>int fd</para>
 379 </entry><entry
 380  align="char">
 381 <para>File descriptor returned by a previous call to open().</para>
 382 </entry>
 383  </row><row><entry
 384  align="char">
 385 <para>int request</para>
 386 </entry><entry
 387  align="char">
 388 <para>Equals CA_GET_DESCR_INFO for this command.</para>
 389 </entry>
 390  </row><row><entry
 391  align="char">
 392 <para>ca_descr_info_t *
 393 </para>
 394 </entry><entry
 395  align="char">
 396 <para>Undocumented.</para>
 397 </entry>
 398  </row></tbody></tgroup></informaltable>
 399 &return-value-dvb;
 400 </section>
 401
 402 <section id="CA_GET_MSG"
 403 role="subsection"><title>CA_GET_MSG</title>
 404 <para>DESCRIPTION
 405 </para>
 406 <informaltable><tgroup cols="1"><tbody><row><entry
 407  align="char">
 408 <para>This ioctl is undocumented. Documentation is welcome.</para>
 409 </entry>
 410  </row></tbody></tgroup></informaltable>
 411 <para>SYNOPSIS
 412 </para>
 413 <informaltable><tgroup cols="1"><tbody><row><entry
 414  align="char">
 415 <para>int ioctl(fd, int request = CA_GET_MSG,
 416  ca_msg_t *);</para>
 417 </entry>
 418  </row></tbody></tgroup></informaltable>
 419 <para>PARAMETERS
 420 </para>
 421 <informaltable><tgroup cols="2"><tbody><row><entry
 422  align="char">
 423 <para>int fd</para>
 424 </entry><entry
 425  align="char">
 426 <para>File descriptor returned by a previous call to open().</para>
 427 </entry>
 428  </row><row><entry
 429  align="char">
 430 <para>int request</para>
 431 </entry><entry
 432  align="char">
 433 <para>Equals CA_GET_MSG for this command.</para>
 434 </entry>
 435  </row><row><entry
 436  align="char">
 437 <para>ca_msg_t *
 438 </para>
 439 </entry><entry
 440  align="char">
 441 <para>Undocumented.</para>
 442 </entry>
 443  </row></tbody></tgroup></informaltable>
 444 &return-value-dvb;
 445 </section>
 446
 447 <section id="CA_SEND_MSG"
 448 role="subsection"><title>CA_SEND_MSG</title>
 449 <para>DESCRIPTION
 450 </para>
 451 <informaltable><tgroup cols="1"><tbody><row><entry
 452  align="char">
 453 <para>This ioctl is undocumented. Documentation is welcome.</para>
 454 </entry>
 455  </row></tbody></tgroup></informaltable>
 456 <para>SYNOPSIS
 457 </para>
 458 <informaltable><tgroup cols="1"><tbody><row><entry
 459  align="char">
 460 <para>int ioctl(fd, int request = CA_SEND_MSG,
 461  ca_msg_t *);</para>
 462 </entry>
 463  </row></tbody></tgroup></informaltable>
 464 <para>PARAMETERS
 465 </para>
 466 <informaltable><tgroup cols="2"><tbody><row><entry
 467  align="char">
 468 <para>int fd</para>
 469 </entry><entry
 470  align="char">
 471 <para>File descriptor returned by a previous call to open().</para>
 472 </entry>
 473  </row><row><entry
 474  align="char">
 475 <para>int request</para>
 476 </entry><entry
 477  align="char">
 478 <para>Equals CA_SEND_MSG for this command.</para>
 479 </entry>
 480  </row><row><entry
 481  align="char">
 482 <para>ca_msg_t *
 483 </para>
 484 </entry><entry
 485  align="char">
 486 <para>Undocumented.</para>
 487 </entry>
 488  </row></tbody></tgroup></informaltable>
 489 &return-value-dvb;
 490 </section>
 491
 492 <section id="CA_SET_DESCR"
 493 role="subsection"><title>CA_SET_DESCR</title>
 494 <para>DESCRIPTION
 495 </para>
 496 <informaltable><tgroup cols="1"><tbody><row><entry
 497  align="char">
 498 <para>This ioctl is undocumented. Documentation is welcome.</para>
 499 </entry>
 500  </row></tbody></tgroup></informaltable>
 501 <para>SYNOPSIS
 502 </para>
 503 <informaltable><tgroup cols="1"><tbody><row><entry
 504  align="char">
 505 <para>int ioctl(fd, int request = CA_SET_DESCR,
 506  ca_descr_t *);</para>
 507 </entry>
 508  </row></tbody></tgroup></informaltable>
 509 <para>PARAMETERS
 510 </para>
 511 <informaltable><tgroup cols="2"><tbody><row><entry
 512  align="char">
 513 <para>int fd</para>
 514 </entry><entry
 515  align="char">
 516 <para>File descriptor returned by a previous call to open().</para>
 517 </entry>
 518  </row><row><entry
 519  align="char">
 520 <para>int request</para>
 521 </entry><entry
 522  align="char">
 523 <para>Equals CA_SET_DESCR for this command.</para>
 524 </entry>
 525  </row><row><entry
 526  align="char">
 527 <para>ca_descr_t *
 528 </para>
 529 </entry><entry
 530  align="char">
 531 <para>Undocumented.</para>
 532 </entry>
 533  </row></tbody></tgroup></informaltable>
 534 &return-value-dvb;
 535 </section>
 536
 537 <section id="CA_SET_PID"
 538 role="subsection"><title>CA_SET_PID</title>
 539 <para>DESCRIPTION
 540 </para>
 541 <informaltable><tgroup cols="1"><tbody><row><entry
 542  align="char">
 543 <para>This ioctl is undocumented. Documentation is welcome.</para>
 544 </entry>
 545  </row></tbody></tgroup></informaltable>
 546 <para>SYNOPSIS
 547 </para>
 548 <informaltable><tgroup cols="1"><tbody><row><entry
 549  align="char">
 550 <para>int ioctl(fd, int request = CA_SET_PID,
 551  ca_pid_t *);</para>
 552 </entry>
 553  </row></tbody></tgroup></informaltable>
 554 <para>PARAMETERS
 555 </para>
 556 <informaltable><tgroup cols="2"><tbody><row><entry
 557  align="char">
 558 <para>int fd</para>
 559 </entry><entry
 560  align="char">
 561 <para>File descriptor returned by a previous call to open().</para>
 562 </entry>
 563  </row><row><entry
 564  align="char">
 565 <para>int request</para>
 566 </entry><entry
 567  align="char">
 568 <para>Equals CA_SET_PID for this command.</para>
 569 </entry>
 570  </row><row><entry
 571  align="char">
 572 <para>ca_pid_t *
 573 </para>
 574 </entry><entry
 575  align="char">
 576 <para>Undocumented.</para>
 577 </entry>
 578  </row></tbody></tgroup></informaltable>
 579 &return-value-dvb;
 580 </section>
 581
 582 </section>