diff options
author | Tilman Schmidt <tilman@imap.cc> | 2009-04-22 22:24:21 -0400 |
---|---|---|
committer | David S. Miller <davem@davemloft.net> | 2009-04-27 08:37:39 -0400 |
commit | 554f200e22a13e19bd407d0037e41be0ec8a0a2e (patch) | |
tree | ebd605aaafbfbf45e1b8cd1e3b7507d04f99df60 /drivers | |
parent | 7ced70c47f68ad672f50781de5adc6d41e6d2866 (diff) |
Documentation/isdn/INTERFACE.CAPI
isdn: document Kernel CAPI driver interface
Create a file Documentation/isdn/INTERFACE.CAPI describing the
interface between the kernel CAPI subsystem and ISDN device drivers,
analogous to the existing Documentation/isdn/INTERFACE for the old
isdn4linux subsystem. Also add kerneldoc comments to the exported
functions in drivers/isdn/capi/kcapi.c.
Impact: Documentation
Signed-off-by: Tilman Schmidt <tilman@imap.cc>
Signed-off-by: Karsten Keil <keil@b1-systems.de>
Signed-off-by: David S. Miller <davem@davemloft.net>
Diffstat (limited to 'drivers')
-rw-r--r-- | drivers/isdn/capi/kcapi.c | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/drivers/isdn/capi/kcapi.c b/drivers/isdn/capi/kcapi.c index 5360c4fd4739..f33170368cd1 100644 --- a/drivers/isdn/capi/kcapi.c +++ b/drivers/isdn/capi/kcapi.c | |||
@@ -270,6 +270,15 @@ static void recv_handler(struct work_struct *work) | |||
270 | mutex_unlock(&ap->recv_mtx); | 270 | mutex_unlock(&ap->recv_mtx); |
271 | } | 271 | } |
272 | 272 | ||
273 | /** | ||
274 | * capi_ctr_handle_message() - handle incoming CAPI message | ||
275 | * @card: controller descriptor structure. | ||
276 | * @appl: application ID. | ||
277 | * @skb: message. | ||
278 | * | ||
279 | * Called by hardware driver to pass a CAPI message to the application. | ||
280 | */ | ||
281 | |||
273 | void capi_ctr_handle_message(struct capi_ctr * card, u16 appl, struct sk_buff *skb) | 282 | void capi_ctr_handle_message(struct capi_ctr * card, u16 appl, struct sk_buff *skb) |
274 | { | 283 | { |
275 | struct capi20_appl *ap; | 284 | struct capi20_appl *ap; |
@@ -348,6 +357,13 @@ error: | |||
348 | 357 | ||
349 | EXPORT_SYMBOL(capi_ctr_handle_message); | 358 | EXPORT_SYMBOL(capi_ctr_handle_message); |
350 | 359 | ||
360 | /** | ||
361 | * capi_ctr_ready() - signal CAPI controller ready | ||
362 | * @card: controller descriptor structure. | ||
363 | * | ||
364 | * Called by hardware driver to signal that the controller is up and running. | ||
365 | */ | ||
366 | |||
351 | void capi_ctr_ready(struct capi_ctr * card) | 367 | void capi_ctr_ready(struct capi_ctr * card) |
352 | { | 368 | { |
353 | card->cardstate = CARD_RUNNING; | 369 | card->cardstate = CARD_RUNNING; |
@@ -360,6 +376,14 @@ void capi_ctr_ready(struct capi_ctr * card) | |||
360 | 376 | ||
361 | EXPORT_SYMBOL(capi_ctr_ready); | 377 | EXPORT_SYMBOL(capi_ctr_ready); |
362 | 378 | ||
379 | /** | ||
380 | * capi_ctr_reseted() - signal CAPI controller reset | ||
381 | * @card: controller descriptor structure. | ||
382 | * | ||
383 | * Called by hardware driver to signal that the controller is down and | ||
384 | * unavailable for use. | ||
385 | */ | ||
386 | |||
363 | void capi_ctr_reseted(struct capi_ctr * card) | 387 | void capi_ctr_reseted(struct capi_ctr * card) |
364 | { | 388 | { |
365 | u16 appl; | 389 | u16 appl; |
@@ -391,6 +415,13 @@ void capi_ctr_reseted(struct capi_ctr * card) | |||
391 | 415 | ||
392 | EXPORT_SYMBOL(capi_ctr_reseted); | 416 | EXPORT_SYMBOL(capi_ctr_reseted); |
393 | 417 | ||
418 | /** | ||
419 | * capi_ctr_suspend_output() - suspend controller | ||
420 | * @card: controller descriptor structure. | ||
421 | * | ||
422 | * Called by hardware driver to stop data flow. | ||
423 | */ | ||
424 | |||
394 | void capi_ctr_suspend_output(struct capi_ctr *card) | 425 | void capi_ctr_suspend_output(struct capi_ctr *card) |
395 | { | 426 | { |
396 | if (!card->blocked) { | 427 | if (!card->blocked) { |
@@ -401,6 +432,13 @@ void capi_ctr_suspend_output(struct capi_ctr *card) | |||
401 | 432 | ||
402 | EXPORT_SYMBOL(capi_ctr_suspend_output); | 433 | EXPORT_SYMBOL(capi_ctr_suspend_output); |
403 | 434 | ||
435 | /** | ||
436 | * capi_ctr_resume_output() - resume controller | ||
437 | * @card: controller descriptor structure. | ||
438 | * | ||
439 | * Called by hardware driver to resume data flow. | ||
440 | */ | ||
441 | |||
404 | void capi_ctr_resume_output(struct capi_ctr *card) | 442 | void capi_ctr_resume_output(struct capi_ctr *card) |
405 | { | 443 | { |
406 | if (card->blocked) { | 444 | if (card->blocked) { |
@@ -413,6 +451,14 @@ EXPORT_SYMBOL(capi_ctr_resume_output); | |||
413 | 451 | ||
414 | /* ------------------------------------------------------------- */ | 452 | /* ------------------------------------------------------------- */ |
415 | 453 | ||
454 | /** | ||
455 | * attach_capi_ctr() - register CAPI controller | ||
456 | * @card: controller descriptor structure. | ||
457 | * | ||
458 | * Called by hardware driver to register a controller with the CAPI subsystem. | ||
459 | * Return value: 0 on success, error code < 0 on error | ||
460 | */ | ||
461 | |||
416 | int | 462 | int |
417 | attach_capi_ctr(struct capi_ctr *card) | 463 | attach_capi_ctr(struct capi_ctr *card) |
418 | { | 464 | { |
@@ -459,6 +505,15 @@ attach_capi_ctr(struct capi_ctr *card) | |||
459 | 505 | ||
460 | EXPORT_SYMBOL(attach_capi_ctr); | 506 | EXPORT_SYMBOL(attach_capi_ctr); |
461 | 507 | ||
508 | /** | ||
509 | * detach_capi_ctr() - unregister CAPI controller | ||
510 | * @card: controller descriptor structure. | ||
511 | * | ||
512 | * Called by hardware driver to remove the registration of a controller | ||
513 | * with the CAPI subsystem. | ||
514 | * Return value: 0 on success, error code < 0 on error | ||
515 | */ | ||
516 | |||
462 | int detach_capi_ctr(struct capi_ctr *card) | 517 | int detach_capi_ctr(struct capi_ctr *card) |
463 | { | 518 | { |
464 | if (card->cardstate != CARD_DETECTED) | 519 | if (card->cardstate != CARD_DETECTED) |
@@ -479,6 +534,13 @@ int detach_capi_ctr(struct capi_ctr *card) | |||
479 | 534 | ||
480 | EXPORT_SYMBOL(detach_capi_ctr); | 535 | EXPORT_SYMBOL(detach_capi_ctr); |
481 | 536 | ||
537 | /** | ||
538 | * register_capi_driver() - register CAPI driver | ||
539 | * @driver: driver descriptor structure. | ||
540 | * | ||
541 | * Called by hardware driver to register itself with the CAPI subsystem. | ||
542 | */ | ||
543 | |||
482 | void register_capi_driver(struct capi_driver *driver) | 544 | void register_capi_driver(struct capi_driver *driver) |
483 | { | 545 | { |
484 | unsigned long flags; | 546 | unsigned long flags; |
@@ -490,6 +552,13 @@ void register_capi_driver(struct capi_driver *driver) | |||
490 | 552 | ||
491 | EXPORT_SYMBOL(register_capi_driver); | 553 | EXPORT_SYMBOL(register_capi_driver); |
492 | 554 | ||
555 | /** | ||
556 | * unregister_capi_driver() - unregister CAPI driver | ||
557 | * @driver: driver descriptor structure. | ||
558 | * | ||
559 | * Called by hardware driver to unregister itself from the CAPI subsystem. | ||
560 | */ | ||
561 | |||
493 | void unregister_capi_driver(struct capi_driver *driver) | 562 | void unregister_capi_driver(struct capi_driver *driver) |
494 | { | 563 | { |
495 | unsigned long flags; | 564 | unsigned long flags; |
@@ -505,6 +574,13 @@ EXPORT_SYMBOL(unregister_capi_driver); | |||
505 | /* -------- CAPI2.0 Interface ---------------------------------- */ | 574 | /* -------- CAPI2.0 Interface ---------------------------------- */ |
506 | /* ------------------------------------------------------------- */ | 575 | /* ------------------------------------------------------------- */ |
507 | 576 | ||
577 | /** | ||
578 | * capi20_isinstalled() - CAPI 2.0 operation CAPI_INSTALLED | ||
579 | * | ||
580 | * Return value: CAPI result code (CAPI_NOERROR if at least one ISDN controller | ||
581 | * is ready for use, CAPI_REGNOTINSTALLED otherwise) | ||
582 | */ | ||
583 | |||
508 | u16 capi20_isinstalled(void) | 584 | u16 capi20_isinstalled(void) |
509 | { | 585 | { |
510 | int i; | 586 | int i; |
@@ -517,6 +593,18 @@ u16 capi20_isinstalled(void) | |||
517 | 593 | ||
518 | EXPORT_SYMBOL(capi20_isinstalled); | 594 | EXPORT_SYMBOL(capi20_isinstalled); |
519 | 595 | ||
596 | /** | ||
597 | * capi20_register() - CAPI 2.0 operation CAPI_REGISTER | ||
598 | * @ap: CAPI application descriptor structure. | ||
599 | * | ||
600 | * Register an application's presence with CAPI. | ||
601 | * A unique application ID is assigned and stored in @ap->applid. | ||
602 | * After this function returns successfully, the message receive | ||
603 | * callback function @ap->recv_message() may be called at any time | ||
604 | * until capi20_release() has been called for the same @ap. | ||
605 | * Return value: CAPI result code | ||
606 | */ | ||
607 | |||
520 | u16 capi20_register(struct capi20_appl *ap) | 608 | u16 capi20_register(struct capi20_appl *ap) |
521 | { | 609 | { |
522 | int i; | 610 | int i; |
@@ -571,6 +659,16 @@ u16 capi20_register(struct capi20_appl *ap) | |||
571 | 659 | ||
572 | EXPORT_SYMBOL(capi20_register); | 660 | EXPORT_SYMBOL(capi20_register); |
573 | 661 | ||
662 | /** | ||
663 | * capi20_release() - CAPI 2.0 operation CAPI_RELEASE | ||
664 | * @ap: CAPI application descriptor structure. | ||
665 | * | ||
666 | * Terminate an application's registration with CAPI. | ||
667 | * After this function returns successfully, the message receive | ||
668 | * callback function @ap->recv_message() will no longer be called. | ||
669 | * Return value: CAPI result code | ||
670 | */ | ||
671 | |||
574 | u16 capi20_release(struct capi20_appl *ap) | 672 | u16 capi20_release(struct capi20_appl *ap) |
575 | { | 673 | { |
576 | int i; | 674 | int i; |
@@ -603,6 +701,15 @@ u16 capi20_release(struct capi20_appl *ap) | |||
603 | 701 | ||
604 | EXPORT_SYMBOL(capi20_release); | 702 | EXPORT_SYMBOL(capi20_release); |
605 | 703 | ||
704 | /** | ||
705 | * capi20_put_message() - CAPI 2.0 operation CAPI_PUT_MESSAGE | ||
706 | * @ap: CAPI application descriptor structure. | ||
707 | * @skb: CAPI message. | ||
708 | * | ||
709 | * Transfer a single message to CAPI. | ||
710 | * Return value: CAPI result code | ||
711 | */ | ||
712 | |||
606 | u16 capi20_put_message(struct capi20_appl *ap, struct sk_buff *skb) | 713 | u16 capi20_put_message(struct capi20_appl *ap, struct sk_buff *skb) |
607 | { | 714 | { |
608 | struct capi_ctr *card; | 715 | struct capi_ctr *card; |
@@ -668,6 +775,16 @@ u16 capi20_put_message(struct capi20_appl *ap, struct sk_buff *skb) | |||
668 | 775 | ||
669 | EXPORT_SYMBOL(capi20_put_message); | 776 | EXPORT_SYMBOL(capi20_put_message); |
670 | 777 | ||
778 | /** | ||
779 | * capi20_get_manufacturer() - CAPI 2.0 operation CAPI_GET_MANUFACTURER | ||
780 | * @contr: controller number. | ||
781 | * @buf: result buffer (64 bytes). | ||
782 | * | ||
783 | * Retrieve information about the manufacturer of the specified ISDN controller | ||
784 | * or (for @contr == 0) the driver itself. | ||
785 | * Return value: CAPI result code | ||
786 | */ | ||
787 | |||
671 | u16 capi20_get_manufacturer(u32 contr, u8 *buf) | 788 | u16 capi20_get_manufacturer(u32 contr, u8 *buf) |
672 | { | 789 | { |
673 | struct capi_ctr *card; | 790 | struct capi_ctr *card; |
@@ -685,6 +802,16 @@ u16 capi20_get_manufacturer(u32 contr, u8 *buf) | |||
685 | 802 | ||
686 | EXPORT_SYMBOL(capi20_get_manufacturer); | 803 | EXPORT_SYMBOL(capi20_get_manufacturer); |
687 | 804 | ||
805 | /** | ||
806 | * capi20_get_version() - CAPI 2.0 operation CAPI_GET_VERSION | ||
807 | * @contr: controller number. | ||
808 | * @verp: result structure. | ||
809 | * | ||
810 | * Retrieve version information for the specified ISDN controller | ||
811 | * or (for @contr == 0) the driver itself. | ||
812 | * Return value: CAPI result code | ||
813 | */ | ||
814 | |||
688 | u16 capi20_get_version(u32 contr, struct capi_version *verp) | 815 | u16 capi20_get_version(u32 contr, struct capi_version *verp) |
689 | { | 816 | { |
690 | struct capi_ctr *card; | 817 | struct capi_ctr *card; |
@@ -703,6 +830,16 @@ u16 capi20_get_version(u32 contr, struct capi_version *verp) | |||
703 | 830 | ||
704 | EXPORT_SYMBOL(capi20_get_version); | 831 | EXPORT_SYMBOL(capi20_get_version); |
705 | 832 | ||
833 | /** | ||
834 | * capi20_get_serial() - CAPI 2.0 operation CAPI_GET_SERIAL_NUMBER | ||
835 | * @contr: controller number. | ||
836 | * @serial: result buffer (8 bytes). | ||
837 | * | ||
838 | * Retrieve the serial number of the specified ISDN controller | ||
839 | * or (for @contr == 0) the driver itself. | ||
840 | * Return value: CAPI result code | ||
841 | */ | ||
842 | |||
706 | u16 capi20_get_serial(u32 contr, u8 *serial) | 843 | u16 capi20_get_serial(u32 contr, u8 *serial) |
707 | { | 844 | { |
708 | struct capi_ctr *card; | 845 | struct capi_ctr *card; |
@@ -721,6 +858,16 @@ u16 capi20_get_serial(u32 contr, u8 *serial) | |||
721 | 858 | ||
722 | EXPORT_SYMBOL(capi20_get_serial); | 859 | EXPORT_SYMBOL(capi20_get_serial); |
723 | 860 | ||
861 | /** | ||
862 | * capi20_get_profile() - CAPI 2.0 operation CAPI_GET_PROFILE | ||
863 | * @contr: controller number. | ||
864 | * @profp: result structure. | ||
865 | * | ||
866 | * Retrieve capability information for the specified ISDN controller | ||
867 | * or (for @contr == 0) the number of installed controllers. | ||
868 | * Return value: CAPI result code | ||
869 | */ | ||
870 | |||
724 | u16 capi20_get_profile(u32 contr, struct capi_profile *profp) | 871 | u16 capi20_get_profile(u32 contr, struct capi_profile *profp) |
725 | { | 872 | { |
726 | struct capi_ctr *card; | 873 | struct capi_ctr *card; |
@@ -903,6 +1050,15 @@ static int old_capi_manufacturer(unsigned int cmd, void __user *data) | |||
903 | } | 1050 | } |
904 | #endif | 1051 | #endif |
905 | 1052 | ||
1053 | /** | ||
1054 | * capi20_manufacturer() - CAPI 2.0 operation CAPI_MANUFACTURER | ||
1055 | * @cmd: command. | ||
1056 | * @data: parameter. | ||
1057 | * | ||
1058 | * Perform manufacturer specific command. | ||
1059 | * Return value: CAPI result code | ||
1060 | */ | ||
1061 | |||
906 | int capi20_manufacturer(unsigned int cmd, void __user *data) | 1062 | int capi20_manufacturer(unsigned int cmd, void __user *data) |
907 | { | 1063 | { |
908 | struct capi_ctr *card; | 1064 | struct capi_ctr *card; |
@@ -981,6 +1137,21 @@ int capi20_manufacturer(unsigned int cmd, void __user *data) | |||
981 | EXPORT_SYMBOL(capi20_manufacturer); | 1137 | EXPORT_SYMBOL(capi20_manufacturer); |
982 | 1138 | ||
983 | /* temporary hack */ | 1139 | /* temporary hack */ |
1140 | |||
1141 | /** | ||
1142 | * capi20_set_callback() - set CAPI application notification callback function | ||
1143 | * @ap: CAPI application descriptor structure. | ||
1144 | * @callback: callback function (NULL to remove). | ||
1145 | * | ||
1146 | * If not NULL, the callback function will be called to notify the | ||
1147 | * application of the addition or removal of a controller. | ||
1148 | * The first argument (cmd) will tell whether the controller was added | ||
1149 | * (KCI_CONTRUP) or removed (KCI_CONTRDOWN). | ||
1150 | * The second argument (contr) will be the controller number. | ||
1151 | * For cmd==KCI_CONTRUP the third argument (data) will be a pointer to the | ||
1152 | * new controller's capability profile structure. | ||
1153 | */ | ||
1154 | |||
984 | void capi20_set_callback(struct capi20_appl *ap, | 1155 | void capi20_set_callback(struct capi20_appl *ap, |
985 | void (*callback) (unsigned int cmd, __u32 contr, void *data)) | 1156 | void (*callback) (unsigned int cmd, __u32 contr, void *data)) |
986 | { | 1157 | { |