[PATCH 0/2] firewire: core: allow unit drivers to schedule work item to process isochronous context

[PATCH 0/2] firewire: core: allow unit drivers to schedule work item to process isochronous context

[Takashi Sakamoto]

Hi,

ALSA firewire stack uses packet-per-buffer mode for both isochronous
receive (IR) and transmit (IT) contexts of 1394 OHCI. To process time
stamp per packet (or per sample in some cases) steadily for media clock
recovery against unexpected transmission skips in the IR context, it uses
an IT context to operate all of isochronous contexts by calls of
fw_iso_context_flush_completions() in the bottom-half of hardIRQ for the
IT context.

Although it looks well to handle all of isochronous contexts in a single
bottom-half context, it relatively takes longer time to finish. In the
future code integration (not yet), it is possible to apply parallelism
method to process these context. In the case, it is useful to allow unit
drivers to schedule work items to process these isochronous contexts.

As a preparation, in this series of changes,
fw_iso_context_schedule_flush_completions() is exposed as a kernel API
available by unit drivers. It is a counter part of
fw_iso_context_flush_completions(). This series of changes also includes
documentation about these kernel APIs.

Takashi Sakamoto (2):
  firewire: core: expose kernel API to schedule work item to process
    isochronous context
  firewire: core: fulfill documentation of
    fw_iso_context_flush_completions()

 Documentation/driver-api/firewire.rst |  2 ++
 drivers/firewire/core-iso.c           | 11 +++++++++++
 drivers/firewire/core.h               |  5 -----
 drivers/firewire/ohci.c               |  4 ++--
 include/linux/firewire.h              | 17 +++++++++++++++++
 5 files changed, 32 insertions(+), 7 deletions(-)

-- 
2.43.0

[PATCH 1/2] firewire: core: expose kernel API to schedule work item to process isochronous context

[Takashi Sakamoto]

In packet-per-buffer mode for isochronous context of 1394 OHCI, software
can schedule hardIRQ to the buffer in which the content of isochronous
packet is processed. The actual behaviour is different between isochronous
receive (IR) and transmit (IT) contexts in respect to isochronous cycle in
which the hardIRQ occurs.

In IR context, the hardIRQ occurs when the buffer is filled actually by
the content of received packet. If there are any isochronous cycles in
which the packet transmission is skipped, it is postponed to generate
the hardIRQ in respect to the isochronous cycle. In IT context, software
can schedule the content of packet every isochronous cycle including
skipping, therefore the hardIRQ occurs in the isochronous cycle to which
the software scheduled.

ALSA firewire stack uses the packet-per-buffer mode for both IR/IT
contexts. To process time stamp per packet (or per sample in some cases)
steadily for media clock recovery against unexpected transmission skips,
it uses an IT context to operate all of isochronous contexts by calls of
fw_iso_context_flush_completions() in the bottom-half of hardIRQ for the
IT context.

Although it looks well to handle all of isochronous contexts in a single
bottom-half context, it relatively takes longer time. In the future code
integration (not yet), it is possible to apply parallelism method to
process these context. In the case, it is useful to allow unit drivers to
schedule work items to process these isochronous contexts.

As a preparation, this commit exposes
fw_iso_context_schedule_flush_completions() as a kernel API available by
unit drivers. It is renamed from fw_iso_context_queue_work() since it is
a counter part of fw_iso_context_flush_completions().

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
---
 Documentation/driver-api/firewire.rst |  2 ++
 drivers/firewire/core.h               |  5 -----
 drivers/firewire/ohci.c               |  4 ++--
 include/linux/firewire.h              | 17 +++++++++++++++++
 4 files changed, 21 insertions(+), 7 deletions(-)

diff --git a/Documentation/driver-api/firewire.rst b/Documentation/driver-api/firewire.rst
index d3cfa73cbb2b..28a32410f7d2 100644
--- a/Documentation/driver-api/firewire.rst
+++ b/Documentation/driver-api/firewire.rst
@@ -43,6 +43,8 @@ Firewire core transaction interfaces
 Firewire Isochronous I/O interfaces
 ===================================
 
+.. kernel-doc:: include/linux/firewire.h
+   :functions: fw_iso_context_schedule_flush_completions
 .. kernel-doc:: drivers/firewire/core-iso.c
    :export:
 
diff --git a/drivers/firewire/core.h b/drivers/firewire/core.h
index 2874f316156a..0ae2c84ecafe 100644
--- a/drivers/firewire/core.h
+++ b/drivers/firewire/core.h
@@ -164,11 +164,6 @@ static inline void fw_iso_context_init_work(struct fw_iso_context *ctx, work_fun
 	INIT_WORK(&ctx->work, func);
 }
 
-static inline void fw_iso_context_queue_work(struct fw_iso_context *ctx)
-{
-	queue_work(ctx->card->isoc_wq, &ctx->work);
-}
-
 
 /* -topology */
 
diff --git a/drivers/firewire/ohci.c b/drivers/firewire/ohci.c
index d0b1fccc450f..3a911cfb5ff3 100644
--- a/drivers/firewire/ohci.c
+++ b/drivers/firewire/ohci.c
@@ -2283,7 +2283,7 @@ static irqreturn_t irq_handler(int irq, void *data)
 
 		while (iso_event) {
 			i = ffs(iso_event) - 1;
-			fw_iso_context_queue_work(&ohci->ir_context_list[i].base);
+			fw_iso_context_schedule_flush_completions(&ohci->ir_context_list[i].base);
 			iso_event &= ~(1 << i);
 		}
 	}
@@ -2294,7 +2294,7 @@ static irqreturn_t irq_handler(int irq, void *data)
 
 		while (iso_event) {
 			i = ffs(iso_event) - 1;
-			fw_iso_context_queue_work(&ohci->it_context_list[i].base);
+			fw_iso_context_schedule_flush_completions(&ohci->it_context_list[i].base);
 			iso_event &= ~(1 << i);
 		}
 	}
diff --git a/include/linux/firewire.h b/include/linux/firewire.h
index 72f497b61739..f815d12deda0 100644
--- a/include/linux/firewire.h
+++ b/include/linux/firewire.h
@@ -531,6 +531,23 @@ int fw_iso_context_queue(struct fw_iso_context *ctx,
 			 unsigned long payload);
 void fw_iso_context_queue_flush(struct fw_iso_context *ctx);
 int fw_iso_context_flush_completions(struct fw_iso_context *ctx);
+
+/**
+ * fw_iso_context_schedule_flush_completions() - schedule work item to process isochronous context.
+ * @ctx: the isochronous context
+ *
+ * Schedule a work item on workqueue to process the isochronous context. The registered callback
+ * function is called in the worker if some packets have been already transferred since the last
+ * time. If it is required to process the context in the current context,
+ * fw_iso_context_flush_completions() is available instead.
+ *
+ * Context: Any context.
+ */
+static inline void fw_iso_context_schedule_flush_completions(struct fw_iso_context *ctx)
+{
+	queue_work(ctx->card->isoc_wq, &ctx->work);
+}
+
 int fw_iso_context_start(struct fw_iso_context *ctx,
 			 int cycle, int sync, int tags);
 int fw_iso_context_stop(struct fw_iso_context *ctx);
-- 
2.43.0

[PATCH 2/2] firewire: core: fulfill documentation of fw_iso_context_flush_completions()

[Takashi Sakamoto]

The fw_iso_context_flush_completions() is the counterpart of
fw_iso_context_schedule_work() to process isochronous context in current
process context.

This commit fulfills its documentation.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
---
 drivers/firewire/core-iso.c | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/drivers/firewire/core-iso.c b/drivers/firewire/core-iso.c
index a249974a0f87..f2394f3ed194 100644
--- a/drivers/firewire/core-iso.c
+++ b/drivers/firewire/core-iso.c
@@ -209,6 +209,17 @@ void fw_iso_context_queue_flush(struct fw_iso_context *ctx)
 }
 EXPORT_SYMBOL(fw_iso_context_queue_flush);
 
+/**
+ * fw_iso_context_flush_completions() - process isochronous context in current process context.
+ * @ctx: the isochronous context
+ *
+ * Process the isochronous context in the current process context. The registered callback function
+ * is called if some packets have been already transferred since the last time. If it is required
+ * to process the context asynchronously, fw_iso_context_schedule_flush_completions() is available
+ * instead.
+ *
+ * Context: Process context. May sleep due to disable_work_sync().
+ */
 int fw_iso_context_flush_completions(struct fw_iso_context *ctx)
 {
 	int err;
-- 
2.43.0

Re: [PATCH 0/2] firewire: core: allow unit drivers to schedule work item to process isochronous context

[Takashi Sakamoto]

On Sun, Sep 08, 2024 at 01:05:47PM +0900, Takashi Sakamoto wrote:
> Hi,
> 
> ALSA firewire stack uses packet-per-buffer mode for both isochronous
> receive (IR) and transmit (IT) contexts of 1394 OHCI. To process time
> stamp per packet (or per sample in some cases) steadily for media clock
> recovery against unexpected transmission skips in the IR context, it uses
> an IT context to operate all of isochronous contexts by calls of
> fw_iso_context_flush_completions() in the bottom-half of hardIRQ for the
> IT context.
> 
> Although it looks well to handle all of isochronous contexts in a single
> bottom-half context, it relatively takes longer time to finish. In the
> future code integration (not yet), it is possible to apply parallelism
> method to process these context. In the case, it is useful to allow unit
> drivers to schedule work items to process these isochronous contexts.
> 
> As a preparation, in this series of changes,
> fw_iso_context_schedule_flush_completions() is exposed as a kernel API
> available by unit drivers. It is a counter part of
> fw_iso_context_flush_completions(). This series of changes also includes
> documentation about these kernel APIs.
> 
> Takashi Sakamoto (2):
>   firewire: core: expose kernel API to schedule work item to process
>     isochronous context
>   firewire: core: fulfill documentation of
>     fw_iso_context_flush_completions()
> 
>  Documentation/driver-api/firewire.rst |  2 ++
>  drivers/firewire/core-iso.c           | 11 +++++++++++
>  drivers/firewire/core.h               |  5 -----
>  drivers/firewire/ohci.c               |  4 ++--
>  include/linux/firewire.h              | 17 +++++++++++++++++
>  5 files changed, 32 insertions(+), 7 deletions(-)

Applied to for-next branch.


Regards

Takashi Sakamoto