# libhinawa

2019/10/12
Takashi Sakamoto

## Instruction

I design this library to send asynchronous transaction from Linux userspace
applications to units on IEEE 1394 bus by any language binding for GObject
Introspection. According to this design, this library is an application of Linux
FireWire subsystem and GLib/GObject.

Furthermore, my recent work since 2013 for Linux sound subsystem, a.k.a
ALSA, adds any loadable wodules for Linux kernel to handle some Audio and
Music units on IEEE 1394 bus by ALSA PCM/RawMidi/HwDep/Sequencer interfaces.
This library includes some helper objects to handle model-specific asynchronous
transactions with helps of the drivers. According to this design, a part of
this library is an application of Linux sound subsystem.

## Example of Python3 with PyGobject

```
#!/usr/bin/env python3

from threading import Thread

import gi
gi.require_version('GLib', '2.0')
gi.require_version('Hinawa', '2.0')
from gi.repository import GLib, Hinawa

unit = Hinawa.SndUnit()
unit.open('/dev/snd/hwC0D0')
node = unit.get_node()

ctx = GLib.MainContext.new()
unit_src = unit.create_source()
node_src = node.create_source()
unit_src.attach(ctx)
node_src.attach(ctx)
dispatcher = GLib.MainLoop.new(ctx, False)
dispatch_th = Thread(target=lambda d: d.run(), args=(dispatcher,))
dispatch_th.start()

addr = 0xfffff0000904
req = Hinawa.FwReq()
frame = bytearray(4)
frame = req.transaction(node, Hinawa.FwTcode.READ_QUADLET_REQUEST, addr, 4,
			frame)
for i, frame in enumerate(frame):
    print('0x{:016x}: 0x{:02x}'.format(addr + i, frame))

dispatcher.quit()
```

## License

- GNU Lesser General Public License version 2.1 or later
- A UAPI header of Linux kernel (include/uapi/sound/firewire.h) is included
  for backport (src/backport.h). This is licensed under GNU General Public
  License version 2. You can build libhinawa without the backport header. In
  this case libhinawa is built with the UAPI header installed in your system.

## Dependencies
- Glib 2.34.0 or later
- GObject Introspection 1.32.1 or later
- Linux kernel 3.12 or later

## Requirements to build
- Meson 0.46.0 or later
- Ninja
- PyGObject (optional to run unit tests)
- GTK-Doc 1.18-2 (optional to generate API documentation)

## How to build

```
$ meson . build
$ cd build
$ ninja
$ ninja install
($ ninja test)
```

## How to refer document

```
$ meson -Dgtk_doc=true . build
$ cd build
$ ninja
$ ninja install
```

## Sample scripts

```
$ ./samples/run.sh [gtk|qt5]
```
gtk - PyGObject is required.
qt5 - PyQt5 is required.

## How to make DEB package

- Please refer to https://salsa.debian.org/debian/libhinawa.

## How to make RPM package

1. archive all source code into libhinawa-1.4.4.tar.gz
  $ git archive --format tar.gz --prefix='libhinawa-1.4.4/' 1.4.4 -o ~/rpmbuild/SOURCES/libhinawa-1.4.4.tar.gz
2. rpmbuild -bb libhinawa.spec

## Future plan for libhinawa v2 and backward compatibility
 * HinawaFwUnit
   * This gobject class is planned to be an abstract class. Instead, any
     derived class such as HinawaSndUnit should be used for instantiation.
 * HinawaFwReq/HinawaFwResp/HinawaFwFcp
  * Any API with arguments for HinawaFwUnit is planned to be dropped. Instead,
    use APIs with arguments for HinawaFwNode.
  * Any API with arguments for GByteArray is planned to be dropped. Instead,
    use APIs with arguments for guint8(buffer) and gsize(buffer length).
 * HinawaSndEfw/HinawaSndDice
  * Any API with arguments for GArray is planned to be dropped. Instead, use
    APIs with arguments for guint32(buffer) and gsize(buffer length).
 * I/O thread
  * No thread is planned to be launched internally for event dispatcher.
    Instead, retrieve GSource from HinawaFwNode and HinawaSndUnit and use it
    with GMainContext for event dispatcher. When no dispatcher runs, timeout
    occurs for any transaction.
 * Notifier thread
  * No thread is planned to be launched internally for GObject signal notifier.
    Instead, launch another thread for your notifier and delegate any
    transaction into it. This is required to prevent I/O thread to be stalled
    because of waiting for an additional event of the transaction.

For backward compatibility, the deprecated APIs and features are kept during v1
period, however application developers should migrate to new APIs and implement
alternatives for the lost features.

end
