2024/04/06 Takashi Sakamoto
I design the library for userspace application to send asynchronous transaction to node in IEEE 1394 bus and to handle asynchronous transaction initiated by the node. The library is itself an application of Linux FireWire subsystem, GLib and GObject.
The library had originally included some helper object classes for model-specific functions via ALSA HwDep character device added by drivers in ALSA firewire stack. The object classes have been already obsoleted and deligated the functions to libhitaki, while are still kept for backward compatibility. They should not be used for applications written newly.
The latest release is 4.0.2. The package archive is available in https://kernel.org/pub/linux/libs/ieee1394/ with detached signature created by my GnuPG key. I note that version 3 release is skipped to use the same major version in library itself and GObject Introspection (g-i) metadata.
- GNU Lesser General Public License version 2.1 or later
- Mirror at https://github.com/alsa-project/libhinawa for user support and continuous integration.
- Glib 2.44.0 or later
- GObject Introspection 1.32.1 or later
- Linux kernel 3.12 or later
- Meson 0.60.0 or later
- Ninja
- PyGObject (optional to run unit tests)
- gi-docgen 2023.1 or later (optional to generate API documentation)
$ meson setup (--prefix=directory-to-install) build $ meson compile -C build $ meson install -C build ($ meson test -C build)
When working with gobject-introspection, Hinawa-4.0.typelib should be
installed in your system girepository so that libgirepository can find
it. Of course, your system LD should find ELF shared object for libhinawa4.
Before installing, it's good to check path of the above and configure
'--prefix' meson option appropriately. The environment variables,
GI_TYPELIB_PATH and LD_LIBRARY_PATH are available for ad-hoc settings
of the above as well.
$ meson configure (--prefix=directory-to-install) -Ddoc=true build $ meson compile -C build $ meson install -C build
You can see documentation files under (directory-to-install)/share/doc/hinawa/.
- PyGObject is a dynamic loader in Python 3 language for libraries compatible with g-i.
- hinawa-rs includes crates to use the library in Rust language.
Some sample scripts are available under samples directory:
- read-quadlet - demonstration to read quadlet data from node in IEEE 1394 bus
- read-quadlet-async - demonstration of the above example with asynchronous runtime
#!/usr/bin/env python3
import gi
gi.require_version('GLib', '2.0')
gi.require_version('Hinawa', '4.0')
from gi.repository import GLib, Hinawa
from threading import Thread
from struct import unpack
node = Hinawa.FwNode.new()
_ = node.open('/dev/fw1', 0)
ctx = GLib.MainContext.new()
_, src = node.create_source()
src.attach(ctx)
dispatcher = GLib.MainLoop.new(ctx, False)
th = Thread(target=lambda d: d.run(), args=(dispatcher, ))
th.start()
addr = 0xfffff0000404
req = Hinawa.FwReq.new()
frame = [0] * 4
_, frame = req.transaction(
node,
Hinawa.FwTcode.READ_QUADLET_REQUEST,
addr,
len(frame),
frame,
50
)
quad = unpack('>I', frame)[0]
print('0x{:012x}: 0x{:02x}'.format(addr, quad))
dispatcher.quit()
th.join()
- Please refer to https://salsa.debian.org/debian/libhinawa.
- Please refer to https://build.opensuse.org/package/show/openSUSE:Factory/libhinawa.
This is a sample of wrap file to satisfy dependency on libhinawa by Meson subprojects.
$ cat subprojects/hinawa.wrap [wrap-git] directory = hinawa url = https://git.kernel.org/pub/scm/libs/ieee1394/libhinawa.git revision = 4.0.2 depth = 1 [provide] dependency_names = hinawa
After installation of the wrap file, the dependency can be solved by hinawa name since it is
common in both pkg-config and the wrap file. The implicit or explicit fallback to subproject is
available.
$ cat meson.build
hinawa_dependency = dependency('hinawa',
version: '>=4.0'
)
In the current version of the library, the focus is on supporting features to operate 1394 OHCI hardware for asynchronous communication. However, it originally started by supporting features provided by drivers in ALSA firewire stack.
The version 0 of library supported the GObject class Hinawa.FwUnit, which was derived by
Hinawa.SndUnit class. The Hinawa.SndUnit class was then inherited by other object classes
for each driver. However, there was an inconvenience where only some parts of asynchronous
transactions (read, write, and lock) were supported by Hinawa.SndUnit.
To address the inconvenience, the version 1 of library integrated Hinawa.FwReq GObject class
with Hinawa.FwTcode and Hinawa.FwRcode GObject enumerations. Nonetheless, another
inconvenience persisted, as some threads were internally launched to dispatch events in Linux
FireWire subsystem and Linux Sound subsystem. These threads, running GLib.MainLoop, were
hidden from the user application.
The version 2 of library aimed to alleviate this issue by providing GLib.Source to user
applications instead of processing it in the internal threads. The application became responsible
for processing it using GLib.MainContext. Additionally, Hinawa.FwNode was introduced to
obsolete Hinawa.FwUnit in an aspect of topology in IEEE 1394 bus. Consequently,
Hinawa.SndUnit directly derived from GObject.
Before releasing the version 4 of library, libhitaki
was released. The library provides Hitaki.SndUnit and its derived object classes to obsolete
equivalent features in the version 2 of library. Furthermore, with the release of Linux kernel
version 6.5, new events were introduced to deliver hardware time stamp for asynchronous
communication. To accommodate this, Hinawa.CycleTime was added, along with some methods of
Hinawa.FwReq, Hinawa.FwResp, and Hinawa.FwFcp, to facilitating user application
processing of the hardware time stamp.
The version 4 library is specifically tailored to features in Linux FireWire subsystem, with a sole focus on asynchronous communication in IEEE 1394 bus. For isochronous communication, libhinoko provides the necessary features.
Hinawa is a Japanese term for a match cord used to ignite fires for various purposes. For
example, twine fuses used for igniting gunpowder weapons are a type of Hinawa. The name
Hinawa consists of two kanji characters; Hi (U+2F55 ⽕) meaning fire, and
Nawa (U+7E04 縄) meaning cord.
In the IEEE 1394 bus, asynchronous communication is the foundational step for operating functions
within nodes. The Hinawa library is designed specifically to address this aspect.
end