Osmocom Open Build Service

osmo-e1d.spec Added

@@ -0,0 +1,141 @@
+#
+# spec file for package osmo-e1d
+#
+# Copyright (c) 2022 SUSE LLC
+# Copyright (c) 2019-2021, Martin Hauke <mardnh@gmx.de>
+#
+# All modifications and additions to the file contributed by third parties
+# remain the property of their copyright owners, unless otherwise agreed
+# upon. The license for this file, and modifications and additions to the
+# file, is the same license as for the pristine package itself (unless the
+# license for the pristine package is not an Open Source License, in which
+# case the license is the MIT License). An "Open Source License" is a
+# license that conforms to the Open Source Definition (Version 1.9)
+# published by the Open Source Initiative.
+
+Name:           osmo-e1d
+Requires: osmocom-nightly = 202211080002
+Version: 0.4.0.20.2041.202211080002
+Release:        0
+Summary:        Osmocom E1 Daemon
+License:        GPL-2.0-or-later
+Group:          Productivity/Telephony/Utilities
+URL:            https://osmocom.org/projects/osmo-e1d/wiki/Wiki
+Source: osmo-e1d_0.4.0.20.2041.202211080002.tar.xz
+Source1: rpmlintrc
+BuildRequires:  automake >= 1.9
+BuildRequires:  libtool >= 2
+BuildRequires:  pkg-config >= 0.20
+%if 0%{?suse_version}
+BuildRequires:  systemd-rpm-macros
+%endif
+BuildRequires:  pkgconfig(libosmocore) >= 1.7.0
+BuildRequires:  pkgconfig(libosmousb) >= 1.7.0
+BuildRequires:  pkgconfig(libosmovty) >= 1.7.0
+BuildRequires:  pkgconfig(talloc) >= 2.0.1
+%{?systemd_requires}
+
+%description
+osmo-e1d is an E1 interface daemon that is part of the Osmocom E1
+interface driver architecture. It was primarily written for the
+ICE40_E1_USB_interface (ICE40 based E1 framer IP core developed by
+tnt).
+
+osmo-e1d acts as an interface between the hardware/firmware of the E1
+interface on the bottom side, and applications wanting to use E1
+timeslots on the top side.
+
+%package -n libosmo-e1d1
+Requires: osmocom-nightly = 202211080002
+Summary:        Osmocom E1 daemon protocol library
+License:        LGPL-3.0-or-later
+Group:          System/Libraries
+
+%description -n libosmo-e1d1
+Osmocom E1 Daemon Protocol Library.
+
+%package -n libosmo-octoi0
+Requires: osmocom-nightly = 202211080002
+Summary:        Library for the Osmocom Community TDMoIP network
+License:        LGPL-3.0-or-later
+Group:          System/Libraries
+
+%description -n libosmo-octoi0
+Library for the Osmocom Community TDMoIP network.
+
+%package devel
+Requires: osmocom-nightly = 202211080002
+Summary:        Header files for the Osmocom E1 daemon protocol library
+License:        LGPL-3.0-or-later
+Group:          Development/Libraries/C and C++
+Requires:       libosmo-e1d1 = %version-%release
+Requires:       libosmo-octoi0 = %version-%release
+Provides:       libosmo-e1d-devel = %version-%release
+Obsoletes:      libosmo-e1d-devel < %version-%release
+
+%description devel
+This subpackage contains libraries and header files for developing
+applications that want to make use of libosmo-e1d.
+
+%prep
+%setup -n osmo-e1d -q
+
+%build
+echo "%version" >.tarball-version
+autoreconf -fiv
+# bugzilla.opensuse.org/795968 for rationale
+%configure --includedir="%_includedir/%name" --disable-static \
+	--docdir="%_docdir/%name" \
+	--with-systemdsystemunitdir="%_unitdir"
+%make_build
+
+%install
+%make_install
+find "%buildroot" -type f -name "*.la" -delete -print
+rm -Rf "%buildroot/%_sysconfdir/osmocom"
+
+%check
+%make_build check || find . -name testsuite.log -exec cat {} +
+
+%post   -n libosmo-e1d1 -p /sbin/ldconfig
+%postun -n libosmo-e1d1 -p /sbin/ldconfig
+%post   -n libosmo-octoi0 -p /sbin/ldconfig
+%postun -n libosmo-octoi0 -p /sbin/ldconfig
+
+%if 0%{?suse_version}
+%preun
+%service_del_preun %name.service
+
+%postun
+%service_del_postun %name.service
+
+%pre
+%service_add_pre %name.service
+
+%post
+%service_add_post %name.service
+%endif
+
+%files
+%license COPYING COPYING.gpl2 COPYING.lgpl3
+%doc README.md
+%_bindir/osmo-e1d
+%_bindir/osmo-e1d-pipe
+%dir %_docdir/%name
+%dir %_docdir/%name/examples
+%_docdir/%name/examples/
+%_unitdir/osmo-e1d.service
+
+%files -n libosmo-e1d1
+%_libdir/libosmo-e1d.so.*
+
+%files -n libosmo-octoi0
+%_libdir/libosmo-octoi.so.*
+
+%files devel
+%_includedir/%name/
+%_libdir/libosmo-e1d.so
+%_libdir/libosmo-octoi.so
+%_libdir/pkgconfig/*.pc
+
+%changelog

osmo-e1d_0.4.0.15.5806.202211070002.dsc -> osmo-e1d_0.4.0.20.2041.202211080002.dsc Changed

@@ -2,7 +2,7 @@
 Source: osmo-e1d
 Binary: osmo-e1d, libosmo-e1d1, libosmo-e1d-dev, libosmo-octoi0, libosmo-octoi-dev
 Architecture: any
-Version: 0.4.0.15.5806.202211070002
+Version: 0.4.0.20.2041.202211080002
 Maintainer: Harald Welte <laforge@osmocom.org>
 Homepage: https://projects.osmocom.org/projects/osmo-e1d
 Standards-Version: 3.9.8
@@ -16,8 +16,8 @@
  libosmo-octoi0 deb libs extra arch=any
  osmo-e1d deb net extra arch=any
 Checksums-Sha1:
- 1bdc59e229134f3d655374e2c61ded202ea4ef0b 76796 osmo-e1d_0.4.0.15.5806.202211070002.tar.xz
+ 463e57f92dfcf3ecd9fba3db15b848b5f6851d34 102152 osmo-e1d_0.4.0.20.2041.202211080002.tar.xz
 Checksums-Sha256:
- af882ee1e502e7c56979675819afee039a619ba45df3880c865b2f1e31a1652f 76796 osmo-e1d_0.4.0.15.5806.202211070002.tar.xz
+ 93fbcd8de4ceb44794f36b13f05560cc458a79f67f07473fc6e41be3c43fd679 102152 osmo-e1d_0.4.0.20.2041.202211080002.tar.xz
 Files:
- 2ee4f1b48a61699b947c044374b4592a 76796 osmo-e1d_0.4.0.15.5806.202211070002.tar.xz
+ 8ef45c6565e453f8e47b5e43680385f8 102152 osmo-e1d_0.4.0.20.2041.202211080002.tar.xz

osmo-e1d_0.4.0.15.5806.202211070002.tar.xz/.tarball-version -> osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/.tarball-version Changed

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/Doxyfile.in Added

@@ -0,0 +1,1716 @@
+# Doxyfile 1.7.4
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project.
+#
+# All text after a hash (#) is considered a comment and will be ignored.
+# The format is:
+#       TAG = value value, ...
+# For lists items can also be appended using:
+#       TAG += value value, ...
+# Values that contain spaces should be placed between quotes (" ").
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+# This tag specifies the encoding used for all characters in the config file
+# that follow. The default is UTF-8 which is also the encoding used for all
+# text before the first occurrence of this tag. Doxygen uses libiconv (or the
+# iconv built into libc) for the transcoding. See
+# http://www.gnu.org/software/libiconv for the list of possible encodings.
+
+DOXYFILE_ENCODING      = UTF-8
+
+# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
+# by quotes) that should identify the project.
+
+PROJECT_NAME           = libosmo-e1d
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number.
+# This could be handy for archiving the generated documentation or
+# if some version control system is used.
+
+PROJECT_NUMBER         = @VERSION@
+
+# Using the PROJECT_BRIEF tag one can provide an optional one line description
+# for a project that appears at the top of each page and should give viewer
+# a quick idea about the purpose of the project. Keep the description short.
+
+PROJECT_BRIEF          = "Osmocom e1d client library"
+
+# With the PROJECT_LOGO tag one can specify an logo or icon that is
+# included in the documentation. The maximum height of the logo should not
+# exceed 55 pixels and the maximum width should not exceed 200 pixels.
+# Doxygen will copy the logo to the output directory.
+
+PROJECT_LOGO           =
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
+# base path where the generated documentation will be put.
+# If a relative path is entered, it will be relative to the location
+# where doxygen was started. If left blank the current directory will be used.
+
+OUTPUT_DIRECTORY       = doc/e1d
+
+# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
+# 4096 sub-directories (in 2 levels) under the output directory of each output
+# format and will distribute the generated files over these directories.
+# Enabling this option can be useful when feeding doxygen a huge amount of
+# source files, where putting all generated files in the same directory would
+# otherwise cause performance problems for the file system.
+
+CREATE_SUBDIRS         = NO
+
+# The OUTPUT_LANGUAGE tag is used to specify the language in which all
+# documentation generated by doxygen is written. Doxygen will use this
+# information to generate all constant output in the proper language.
+# The default language is English, other supported languages are:
+# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional,
+# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German,
+# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English
+# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian,
+# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak,
+# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese.
+
+OUTPUT_LANGUAGE        = English
+
+# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
+# include brief member descriptions after the members that are listed in
+# the file and class documentation (similar to JavaDoc).
+# Set to NO to disable this.
+
+BRIEF_MEMBER_DESC      = YES
+
+# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
+# the brief description of a member or function before the detailed description.
+# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
+# brief descriptions will be completely suppressed.
+
+REPEAT_BRIEF           = YES
+
+# This tag implements a quasi-intelligent brief description abbreviator
+# that is used to form the text in various listings. Each string
+# in this list, if found as the leading text of the brief description, will be
+# stripped from the text and the result after processing the whole list, is
+# used as the annotated text. Otherwise, the brief description is used as-is.
+# If left blank, the following values are used ("$name" is automatically
+# replaced with the name of the entity): "The $name class" "The $name widget"
+# "The $name file" "is" "provides" "specifies" "contains"
+# "represents" "a" "an" "the"
+
+ABBREVIATE_BRIEF       =
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
+# Doxygen will generate a detailed section even if there is only a brief
+# description.
+
+ALWAYS_DETAILED_SEC    = NO
+
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
+# inherited members of a class in the documentation of that class as if those
+# members were ordinary class members. Constructors, destructors and assignment
+# operators of the base classes will not be shown.
+
+INLINE_INHERITED_MEMB  = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
+# path before files name in the file list and in the header files. If set
+# to NO the shortest path that makes the file name unique will be used.
+
+FULL_PATH_NAMES        = YES
+
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
+# can be used to strip a user-defined part of the path. Stripping is
+# only done if one of the specified strings matches the left-hand part of
+# the path. The tag can be used to show relative paths in the file list.
+# If left blank the directory from which doxygen is run is used as the
+# path to strip.
+
+STRIP_FROM_PATH        =
+
+# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of
+# the path mentioned in the documentation of a class, which tells
+# the reader which header file to include in order to use a class.
+# If left blank only the name of the header file containing the class
+# definition is used. Otherwise one should specify the include paths that
+# are normally passed to the compiler using the -I flag.
+
+STRIP_FROM_INC_PATH    =
+
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
+# (but less readable) file names. This can be useful if your file system
+# doesn't support long names like on DOS, Mac, or CD-ROM.
+
+SHORT_NAMES            = NO
+
+# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
+# will interpret the first line (until the first dot) of a JavaDoc-style
+# comment as the brief description. If set to NO, the JavaDoc
+# comments will behave just like regular Qt-style comments
+# (thus requiring an explicit @brief command for a brief description.)
+
+JAVADOC_AUTOBRIEF      = YES
+
+# If the QT_AUTOBRIEF tag is set to YES then Doxygen will
+# interpret the first line (until the first dot) of a Qt-style
+# comment as the brief description. If set to NO, the comments
+# will behave just like regular Qt-style comments (thus requiring
+# an explicit command for a brief description.)
+
+QT_AUTOBRIEF           = YES
+
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
+# treat a multi-line C++ special comment block (i.e. a block of //! or ///
+# comments) as a brief description. This used to be the default behaviour.
+# The new default is to treat a multi-line C++ comment block as a detailed
+# description. Set this tag to YES if you prefer the old behaviour instead.
+
+MULTILINE_CPP_IS_BRIEF = NO
+
+# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
+# member inherits the documentation from any documented member that it
+# re-implements.
+
+INHERIT_DOCS           = YES
+
+# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
+# a new page for each member. If set to NO, the documentation of a member will
+# be part of the file/class/namespace that contains it.
+
+SEPARATE_MEMBER_PAGES  = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab.
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+
+TAB_SIZE               = 8
+
+# This tag can be used to specify a number of aliases that acts
+# as commands in the documentation. An alias has the form "name=value".
+# For example adding "sideeffect=\par Side Effects:\n" will allow you to
+# put the command \sideeffect (or @sideeffect) in the documentation, which
+# will result in a user-defined paragraph with heading "Side Effects:".
+# You can put \n's in the value part of an alias to insert newlines.
+
+ALIASES                =
+
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
+# sources only. Doxygen will then generate output that is more tailored for C.
+# For instance, some of the names that are used will be different. The list

osmo-e1d_0.4.0.15.5806.202211070002.tar.xz/configure.ac -> osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/configure.ac Changed

@@ -75,6 +75,49 @@
 	CPPFLAGS="$CPPFLAGS $WERROR_FLAGS"
 fi
 
+
+# Generate manuals
+AC_ARG_ENABLE(manuals,
+	AS_HELP_STRING(
+		--enable-manuals,
+		Generate manual PDFs default=no,
+	),
+	osmo_ac_build_manuals=$enableval, osmo_ac_build_manuals="no")
+AM_CONDITIONAL(BUILD_MANUALS, test x"$osmo_ac_build_manuals" = x"yes")
+AC_ARG_VAR(OSMO_GSM_MANUALS_DIR, path to common osmo-gsm-manuals files, overriding pkg-config and "../osmo-gsm-manuals"
+	fallback)
+if test x"$osmo_ac_build_manuals" = x"yes"
+then
+	# Find OSMO_GSM_MANUALS_DIR (env, pkg-conf, fallback)
+	if test -n "$OSMO_GSM_MANUALS_DIR"; then
+		echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from env)"
+	else
+		OSMO_GSM_MANUALS_DIR="$($PKG_CONFIG osmo-gsm-manuals --variable=osmogsmmanualsdir 2>/dev/null)"
+		if test -n "$OSMO_GSM_MANUALS_DIR"; then
+			echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from pkg-conf)"
+		else
+			OSMO_GSM_MANUALS_DIR="../osmo-gsm-manuals"
+			echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (fallback)"
+		fi
+	fi
+	if ! test -d "$OSMO_GSM_MANUALS_DIR"; then
+		AC_MSG_ERROR("OSMO_GSM_MANUALS_DIR does not exist! Install osmo-gsm-manuals or set OSMO_GSM_MANUALS_DIR.")
+	fi
+
+	# Find and run check-depends
+	CHECK_DEPENDS="$OSMO_GSM_MANUALS_DIR/check-depends.sh"
+	if ! test -x "$CHECK_DEPENDS"; then
+		CHECK_DEPENDS="osmo-gsm-manuals-check-depends"
+	fi
+	if ! $CHECK_DEPENDS; then
+		AC_MSG_ERROR("missing dependencies for --enable-manuals")
+	fi
+
+	# Put in Makefile with absolute path
+	OSMO_GSM_MANUALS_DIR="$(realpath "$OSMO_GSM_MANUALS_DIR")"
+	AC_SUBST(OSMO_GSM_MANUALS_DIR)
+fi
+
 AC_ARG_ENABLE(external_tests,
 		AC_HELP_STRING(--enable-external-tests,
 				Include the VTY/CTRL tests in make check default=no),
@@ -93,6 +136,14 @@
 AC_MSG_RESULT($enable_ext_tests)
 AM_CONDITIONAL(ENABLE_EXT_TESTS, test "x$enable_ext_tests" = "xyes")
 
+AC_ARG_ENABLE(doxygen,
+	AS_HELP_STRING(
+		--disable-doxygen,
+		Disable generation of documentation using doxygen,
+	),
+	doxygen=$enableval, doxygen="yes")
+AC_PATH_PROG(DOXYGEN,doxygen,false)
+AM_CONDITIONAL(HAVE_DOXYGEN, test $DOXYGEN != false && test "x$doxygen" = "xyes")
 
 
 # https://www.freedesktop.org/software/systemd/man/daemon.html
@@ -113,10 +164,13 @@
 
 AC_OUTPUT(
 	Makefile
+	Doxyfile
 	contrib/Makefile
 	contrib/systemd/Makefile
+	contrib/osmo-e1d.spec
 	doc/Makefile
 	doc/examples/Makefile
+	doc/manuals/Makefile
 	src/Makefile
 	src/octoi/Makefile
 	include/Makefile

osmo-e1d_0.4.0.15.5806.202211070002.tar.xz/contrib/Makefile.am -> osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/contrib/Makefile.am Changed

osmo-e1d_0.4.0.15.5806.202211070002.tar.xz/contrib/jenkins.sh -> osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/contrib/jenkins.sh Changed

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/contrib/osmo-e1d.spec.in Added

@@ -0,0 +1,140 @@
+#
+# spec file for package osmo-e1d
+#
+# Copyright (c) 2022 SUSE LLC
+# Copyright (c) 2019-2021, Martin Hauke <mardnh@gmx.de>
+#
+# All modifications and additions to the file contributed by third parties
+# remain the property of their copyright owners, unless otherwise agreed
+# upon. The license for this file, and modifications and additions to the
+# file, is the same license as for the pristine package itself (unless the
+# license for the pristine package is not an Open Source License, in which
+# case the license is the MIT License). An "Open Source License" is a
+# license that conforms to the Open Source Definition (Version 1.9)
+# published by the Open Source Initiative.
+
+Name:           osmo-e1d
+Requires: osmocom-nightly = 202211080002
+Version:        @VERSION@
+Release:        0
+Summary:        Osmocom E1 Daemon
+License:        GPL-2.0-or-later
+Group:          Productivity/Telephony/Utilities
+URL:            https://osmocom.org/projects/osmo-e1d/wiki/Wiki
+Source:         %{name}-%{version}.tar.xz
+BuildRequires:  automake >= 1.9
+BuildRequires:  libtool >= 2
+BuildRequires:  pkg-config >= 0.20
+%if 0%{?suse_version}
+BuildRequires:  systemd-rpm-macros
+%endif
+BuildRequires:  pkgconfig(libosmocore) >= 1.7.0
+BuildRequires:  pkgconfig(libosmousb) >= 1.7.0
+BuildRequires:  pkgconfig(libosmovty) >= 1.7.0
+BuildRequires:  pkgconfig(talloc) >= 2.0.1
+%{?systemd_requires}
+
+%description
+osmo-e1d is an E1 interface daemon that is part of the Osmocom E1
+interface driver architecture. It was primarily written for the
+ICE40_E1_USB_interface (ICE40 based E1 framer IP core developed by
+tnt).
+
+osmo-e1d acts as an interface between the hardware/firmware of the E1
+interface on the bottom side, and applications wanting to use E1
+timeslots on the top side.
+
+%package -n libosmo-e1d1
+Requires: osmocom-nightly = 202211080002
+Summary:        Osmocom E1 daemon protocol library
+License:        LGPL-3.0-or-later
+Group:          System/Libraries
+
+%description -n libosmo-e1d1
+Osmocom E1 Daemon Protocol Library.
+
+%package -n libosmo-octoi0
+Requires: osmocom-nightly = 202211080002
+Summary:        Library for the Osmocom Community TDMoIP network
+License:        LGPL-3.0-or-later
+Group:          System/Libraries
+
+%description -n libosmo-octoi0
+Library for the Osmocom Community TDMoIP network.
+
+%package devel
+Requires: osmocom-nightly = 202211080002
+Summary:        Header files for the Osmocom E1 daemon protocol library
+License:        LGPL-3.0-or-later
+Group:          Development/Libraries/C and C++
+Requires:       libosmo-e1d1 = %version-%release
+Requires:       libosmo-octoi0 = %version-%release
+Provides:       libosmo-e1d-devel = %version-%release
+Obsoletes:      libosmo-e1d-devel < %version-%release
+
+%description devel
+This subpackage contains libraries and header files for developing
+applications that want to make use of libosmo-e1d.
+
+%prep
+%setup -q
+
+%build
+echo "%version" >.tarball-version
+autoreconf -fiv
+# bugzilla.opensuse.org/795968 for rationale
+%configure --includedir="%_includedir/%name" --disable-static \
+	--docdir="%_docdir/%name" \
+	--with-systemdsystemunitdir="%_unitdir"
+%make_build
+
+%install
+%make_install
+find "%buildroot" -type f -name "*.la" -delete -print
+rm -Rf "%buildroot/%_sysconfdir/osmocom"
+
+%check
+%make_build check || find . -name testsuite.log -exec cat {} +
+
+%post   -n libosmo-e1d1 -p /sbin/ldconfig
+%postun -n libosmo-e1d1 -p /sbin/ldconfig
+%post   -n libosmo-octoi0 -p /sbin/ldconfig
+%postun -n libosmo-octoi0 -p /sbin/ldconfig
+
+%if 0%{?suse_version}
+%preun
+%service_del_preun %name.service
+
+%postun
+%service_del_postun %name.service
+
+%pre
+%service_add_pre %name.service
+
+%post
+%service_add_post %name.service
+%endif
+
+%files
+%license COPYING COPYING.gpl2 COPYING.lgpl3
+%doc README.md
+%_bindir/osmo-e1d
+%_bindir/osmo-e1d-pipe
+%dir %_docdir/%name
+%dir %_docdir/%name/examples
+%_docdir/%name/examples/
+%_unitdir/osmo-e1d.service
+
+%files -n libosmo-e1d1
+%_libdir/libosmo-e1d.so.*
+
+%files -n libosmo-octoi0
+%_libdir/libosmo-octoi.so.*
+
+%files devel
+%_includedir/%name/
+%_libdir/libosmo-e1d.so
+%_libdir/libosmo-octoi.so
+%_libdir/pkgconfig/*.pc
+
+%changelog

osmo-e1d_0.4.0.15.5806.202211070002.tar.xz/debian/changelog -> osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/debian/changelog Changed

osmo-e1d_0.4.0.15.5806.202211070002.tar.xz/debian/control -> osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/debian/control Changed

@@ -21,14 +21,14 @@
 Package: osmo-e1d
 Architecture: any
 Multi-Arch: foreign
-Depends: osmocom-nightly (= 202211070002), ${misc:Depends}, ${shlibs:Depends}
+Depends: osmocom-nightly (= 202211080002), ${misc:Depends}, ${shlibs:Depends}
 Description: osmo-e1d: Osmocom's E1 interface daemon
 
 Package: libosmo-e1d1
 Section: libs
 Architecture: any
 Multi-Arch: same
-Depends: osmocom-nightly (= 202211070002), ${misc:Depends}, ${shlibs:Depends}
+Depends: osmocom-nightly (= 202211080002), ${misc:Depends}, ${shlibs:Depends}
 Pre-Depends: ${misc:Pre-Depends}
 Description: Client library for talking to the Osmocom E1 interface daemon osmo-e1d.
 
@@ -36,7 +36,7 @@
 Section: libdevel
 Architecture: any
 Multi-Arch: same
-Depends: osmocom-nightly (= 202211070002), ${misc:Depends}, ${shlibs:Depends},
+Depends: osmocom-nightly (= 202211080002), ${misc:Depends}, ${shlibs:Depends},
 	 libosmo-e1d1 (= ${binary:Version}),
 	 libosmocore-dev,
 Description: Development headers for the osmo-e1d library.
@@ -45,7 +45,7 @@
 Section: libs
 Architecture: any
 Multi-Arch: same
-Depends: osmocom-nightly (= 202211070002), ${misc:Depends}, ${shlibs:Depends}
+Depends: osmocom-nightly (= 202211080002), ${misc:Depends}, ${shlibs:Depends}
 Pre-Depends: ${misc:Pre-Depends}
 Description: Library for the Osmocom Community TDMoIP network.
 
@@ -53,7 +53,7 @@
 Section: libdevel
 Architecture: any
 Multi-Arch: same
-Depends: osmocom-nightly (= 202211070002), ${misc:Depends}, ${shlibs:Depends},
+Depends: osmocom-nightly (= 202211080002), ${misc:Depends}, ${shlibs:Depends},
 	 libosmo-octoi0 (= ${binary:Version}),
 	 libosmocore-dev,
 Description: Development headers for the Osmocom Community TDMoIP library.

osmo-e1d_0.4.0.15.5806.202211070002.tar.xz/doc/Makefile.am -> osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/Makefile.am Changed

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/manuals Added

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/manuals/Makefile.am Added

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/manuals/chapters Added

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/manuals/chapters/client-interface.adoc Added

@@ -0,0 +1,72 @@
+e1dp
+== Client Interface
+
+This chapter documents the _Client interface_ which is used by
+application programs wanting to send and/or receive data on the E1
+circuits served by `osmo-e1d`.
+
+The interface is based on a `unix domain socket` and works in the
+following way:
+
+* `osmo-e1d` implements the server side of a unix domain socket
+
+* the application program acts as a client program establishing a socket
+  connection to the e1d unix domain socket
+* the application program preforms operations such as opening of a
+  specific E1 timeslot on a spcific line/interface.
+* `osmo-e1d` passes a file descriptor from the daemon to the client
+  application
+* the client application can read/write data from/to the E1 timeslot via
+  this file descriptor
+
+This architecture was chosen to allow for the _one file descriptor per
+timeslot_ paradigm that is known from other drivers, such as DAHDI.
+
+Each timeslot of each line on each interface can theoretically be opened
+by a different program.  This permits for example control/user plane
+splits like a signaling gateway + media gateway implemented as separate
+processes.
+
+When opening a timeslot, the client specifies the _mode_.
+
+* In _RAW mode_, the transparent 64kBps bit-stream is passed over the
+  per-timeslot file descriptor.  This is mostly used for B-channels /
+  user traffic.
+* In _HDLC-FCS mode_, a (software) HDLC processor is instantiated. It
+  performs flag sequence detection/generation and bit-stuffing.  This is
+  mostly used for D-channels / signalling.
+
+Details about the messaging on the unix domain socket can be found in
+the definitions contained in the `include/osmocom/e1d/proto.h` header
+file, as well as the doxygen API documentation generated from it.
+
+=== `libosmo-e1d` client library
+
+To simplify interfacing `osmo-e1d` from an application, there is a
+companion library called `libosmo-e1d`.
+
+It contains functions implementing the above-mentioned client interface
+protocol and prevents the application developer from having to implement
+the low-level bits of this interface.
+
+The library is licensed under GNU LGPL-3.0-or-later, which is a weak
+copyleft license that permits using the library from non-open-source /
+proprietary applications.
+
+The library offers the following functions:
+
+* initialization / teardown
+** `osmo_e1dp_client_create()`
+** `osmo_e1dp_client_destroy()`
+* information querying
+** `osmo_e1dp_client_intf_query()`
+** `osmo_e1dp_client_line_query()`
+** `osmo_e1dp_client_ts_query()`
+* configuration
+** `osmo_e1dp_client_line_config()`
+* opening of timeslots
+** `osmo_e1dp_client_ts_open()`
+** `osmo_e1dp_client_ts_open_force()`
+
+Details about those functions can be found in the definitions contained
+in the `include/osmocom/e1d/proto_clnt.h` header file.

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/manuals/chapters/drivers.adoc Added

@@ -0,0 +1,85 @@
+drivers
+== E1 drivers
+
+`osmo-e1d` was primarily developed for the icE1usb hardware, but also
+supports some other drivers by now.
+
+
+=== The `usb` driver for icE1usb and e1-tracer
+
+The `usb` driver implements the USB interface first implemented by the
+`icE1usb` hardware.
+
+For more information on the `icEusb`, please see its related user
+manual, published at https://downloads.osmocom.org/docs/latest/icE1usb-usermanual.pdf
+
+Each `icEusb` device implements one E1 interface with up to two E1
+lines.  Note that supporting two E1 lines is only supported on very few
+select USB host controllers. In most cases, your USB host controller
+will only permit using one of the two lines.
+
+==== Configuration
+
+`osmo-e1d` will automatically detect any supported USB devices when
+starting up. It will dynamically allocate E1 interface and E1 line
+numbers to those USB devices.  However, the order is not guaranteed and
+particularly in case you have multiple devices, it is strongly
+recommended to use _static configuration_.
+
+In this static configuration, you would have a block like
+
+.Example configuration snippet for an icE1usb
+----
+ interface 2 icE1usb
+  usb-serial dc697407e7881531
+----
+
+This way you reserve/allocate the E1 interface number 2 for the icE1usb
+with serial number dc697407e7881531.  The Serial number is unique and
+stored in the iSerial string of the USB device descriptor.  You can for
+example use `lsusb -v -d 1d50: | grep iSerial` to obtain it, or check
+the `dmesg` kernel log after plugging in a device.
+
+==== Using the `usb` driver with `e1-tracer`
+
+The same driver has been slightly extended to also support the passive,
+bi-directional `e1-tracer` hardware.  The configuration and use is
+identical to the use with the `icE1usb`, with the notable difference
+that a passive tracer can obviously only receive data from E1, but not
+transmit.  The two directions of a E1 circuit are represented as two
+lines in `osmo-e1d`.
+
+=== The `vpair` driver for virtual E1 circuits
+
+Sometimes it is useful to be able to interface multiple E1-using
+applications without a real E1 circuit or any hardware whatsoever.
+
+This can be used in automatic / virtualized software testing, but also
+in case a legacy application is migrate away from real physical E1
+circuits.
+
+==== Configuration
+
+The configuration of the `vpair` driver is relatively simple.  It
+consists of a single `virtual-e1-pair` command.
+
+.Example configuration snippet for a virtual E1 pair with one E1 line
+----
+e1d
+ virtual-e1-pair 1
+----
+
+The above example will create a virtual pair of E1 interfaces, each
+of those interface with one E1 line.
+
+.Log output of the example configuration for 1 virtual pair
+----
+intf_line.c:184 (I0) Created
+intf_line.c:285 (I0:L0) Created
+intf_line.c:184 (I1) Created
+intf_line.c:285 (I1:L0) Created
+----
+
+You can subsequently use the Lines just like you would use physical E1
+lines.  Any data you transmit on one line will be received on the other
+line, and vice versa.

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/manuals/chapters/overview.adoc Added

@@ -0,0 +1,105 @@
+== Overview
+
+=== About this manual
+
+This manual should help you getting started with the `osmo-e1d` software.
+It will cover aspects of configuring and running `osmo-e1d` as well as some
+introduction about its internal architecture and external interfaces.
+
+=== About `osmo-e1d`
+
+`osmo-e1d` is a driver (implemented as userspace daemon) for a variety of hardware
+related to the E1 (TDM) interface, such as
+
+* the `icEusb` USB attached E1 interface
+* the `e1-tracer` USB attached passive E1 tracer
+
+=== Credits
+
+`osmo-e1d` was originally developed in 2019 by Sylvain Munaut alongside
+the icE1usb project. It subsequently got improved and extended by Harald
+Welte.
+
+=== Architecture
+
+`osmo-e1d` is a driver system for E1 circuits, which are sometimes also called
+primary rate (PRI). It typically sits between an E1 hardware interface beneath
+it and application software above it.
+
+.How osmo-e1d fits in the overall system architecture
+graphviz
+----
+digraph G{
+  //rankdir = LR;
+  Application -> loa;
+  pipe -> e1d style=dashed;
+  loa -> e1d;
+
+  e1d -> HW;
+  e1d -> vpair;
+
+  HW -> BTS;
+
+  {rank=same;
+   Application label="Application\nosmo-nitb / osmo-bsc";
+   pipe label="osmo-e1d-pipe\nfor testing", style=dashed;
+  }
+  e1d label="osmo-e1d", color=red;
+  loa label="libosmo-abis\ne1_input";
+  HW label="E1 Hardware";
+  vpair label="Virtual E1 pair";
+}
+----
+
+Contrary to older E1 drivers such as DAHDI or mISDN, `osmo-e1d` runs entirely in userspace,
+without a need for kernel drivers.  This is obviously less computationally efficient,
+but has other advantages, such as working on unmodified Linux kernels / operating systems,
+and with a lower risk of software bugs affecting overall system
+stability.  Particularly at low E1 port density and modern hardware, the
+lower efficiency is not expected to make a big difference.
+
+==== E1 Interfaces
+
+In `osmo-e1d` language, an _E1 Interface_ is some kind of underlying hardware that contains one or more
+_Lines_.  Interfaces are numbered from 0..N and are often abbreviated e.g. as `I0` for Interface 0.
+
+==== E1 Lines
+
+In `osmo-e1d` language, an _E1 Line_ represents one single E1 circuit within an _E1 Interface_.
+
+=== Hardware support
+
+`osmo-e1d` currently supports the following hardware:
+
+* Osmocom icE1usb
+* Osmocom e1-tracer
+* Virtual pair of E1 circuits
+
+==== icE1usb
+
+The Osmocom icE1usb is an OSHW implementation of a USB-attached hardware
+interface for up to two E1 circuits (lines).
+
+For more information on the Osmocom icE1usb, see
+
+* data sheet: https://www.sysmocom.de/downloads/icE1usb_data_sheet.pdf
+* project wiki: https://osmocom.org/projects/e1-t1-adapter/wiki/ICE40_E1_USB_interface
+* user manual: https://ftp.osmocom.org/docs/latest/icE1usb-usermanual.pdf
+* product page: https://www.sysmocom.de/products/lab/icE1usb
+
+==== e1-tracer
+
+The Osmocom e1-tracer is an OSHW implementation of a passive,
+high-impedance bi-directional E1 tap/tracer/sniffer.  It can be used to
+capture traffic on an unmodified E1 interface.
+
+For more information on the Osmocom e1-tracer, see
+
+* project wiki: https://osmocom.org/projects/e1-t1-adapter/wiki/E1_tracer
+* user manual: https://ftp.osmocom.org/docs/latest/e1tracer-usermanual.pdf
+
+==== vpair
+
+The osmo-e1d _vpair_ is not actual hardware, but a virtual pair of E1
+interfaces.  It can be used to test E1-using applications without
+involving a hardware E1 circuit.

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/manuals/chapters/running.adoc Added

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/manuals/chapters/tdmoip.adoc Added

@@ -0,0 +1,68 @@
+octoi
+== OCTOI TDMoIP mode
+
+Instead of providing a programmatic client interface (<<client>>) enabling
+external applications timeslot-granular access to the data of a E1 line,
+`osmo-e1d` also supports an entirely separate mode of operation:
+_TDMoIP using the OCTOI (Osmocom Community TDMoIP) protocol_.
+
+In this mode of operation, osmo-e1d acts as interface between an E1 line
+and a remote system over UDP/IP.  This allows you to transparently pass
+an E1 line over an IP network such as the Internet.
+
+`osmo-e1d` can operate either as client or as server for the OCTOI protocol.
+
+=== osmo-e1d as OCTOI client
+
+Below is an example configuration snippet for operating as an OCTOI client.
+
+.Configuration snippet for operating as an OCTOI client
+----
+e1d
+ interface 0 icE1usb
+  usb-serial dc697407e7881531
+  line 0
+   mode e1oip <1>
+octoi-client 192.168.7.2 10013 <2>
+ local-bind 0.0.0.0 3333 <3>
+ account foobar <4>
+  mode ice1usb
+  ice1usb serial-number dc697407e7881531 <5>
+  ice1usb line-number 0
+----
+<1> we specify that Interface 0 Line 0 (I0:L0) of the icE1usb device with serial number dc697407e7881531 shall
+    be used in `e1oip` mode.
+<2> we instantiate an OCTOI client to the remote IP 192.168.7.2 / UDP port 10013
+<3> we specify to bind locally to INADDR_ANY and local UDP port 3333
+<4> we specify the account/user name to tell the server is `foobar`
+<5> we specify that this OCTOI client instance shall use the icE1usb device with the given serial number. This
+    must match the serial number used above when configuring the icE1usb line mode.
+
+There can of course be any number of E1 interfaces/lines and clients; the example just shows one for clarity.
+
+=== osmo-e1d as OCTOI server
+
+Below is an example configuration snippet for operating as an OCTOI server.
+
+.Configuration snippet for operating as an OCTOI server
+----
+e1d
+ interface 0 icE1usb
+  usb-serial dc697407e7881531
+  line 0
+   mode e1oip <1>
+octoi-server
+ local-bind 0.0.0.0 10013 <2>
+ account foobar <3>
+  mode ice1usb
+  ice1usb serial-number dc697407e7881531 <4>
+  ice1usb line-number 0
+----
+<1> we specify that Interface 0 Line 0 (I0:L0) of the icE1usb device with serial number dc697407e7881531 shall
+    be used in `e1oip` mode.
+<2> we bind the OCTOI server to UDP port 9999 of INADDR_ANY
+<3> we specify a user account `foobar`
+<4> we connect the user account `foobar` to the icE1usb serial number / line number specified above
+
+There can of course be any number of E1 interfaces/lines and user accounts; the example just shows one for
+clarity.

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/manuals/osmoe1d-usermanual-docinfo.xml Added

osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/doc/manuals/osmoe1d-usermanual.adoc Added

osmo-e1d_0.4.0.15.5806.202211070002.tar.xz/include/osmocom/e1d/proto.h -> osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/include/osmocom/e1d/proto.h Changed

@@ -1,7 +1,9 @@
-/*
- * proto.h
- *
- * (C) 2019 by Sylvain Munaut <tnt@246tNt.com>
+/*! \file proto.h
+ *  Specification of the IPC protocol used on the CTL UNIX domain socket between
+ *  osmo-e1d and its client programs.
+ */
+
+/* (C) 2019 by Sylvain Munaut <tnt@246tNt.com>
  * (C) 2020 by Harald Welte <laforge@gnumonks.org>
  *
  * All Rights Reserved
@@ -30,106 +32,122 @@
 #include <osmocom/core/utils.h>
 
 
-/*	E1DP_CMD_INTF_QUERY
- *	filter: intf (optional)
- *	in: n/a
- *	out: array of osmo_e1dp_intf_info
- *
- * 	E1DP_CMD_LINE_QUERY
- * 	filter: intf (required), line (optional)
- * 	in: n/a
- * 	out: array of osmo_e1dp_line_info
- *
- * 	E1DP_CMD_TS_QUERY
- * 	filter: intf (required), line (required), ts (optional)
- * 	in: n/a
- * 	out: array of osmo_e1dp_ts_info
- *
- *      E1DP_CMD_LINE_CONFIG
- *      filter: intf (required), line (required)
- *      in: osmo_e1dp_line_config
- *      out: osmo_e1dp_line_info
- *
- * 	E1DP_CMD_TS_OPEN
- * 	filter: intf (required), line (required), ts (required)
- * 	in: osmo_e1dp_ts_config
- * 	out: osmo_e1dp_ts_info with the opened TS (or an invalid one with id == -1 for errors)
- * 	    + message with the file descriptor
- */
-
+/*! e1d CTL protocol message type definition. Split in 'type' and 'command' portion. */
 enum osmo_e1dp_msg_type {
+	/*! Query information about E1 interface(s).
+	 * filter: intf (optional); in: n/a out: array of osmo_e1dp_intf_info */
 	E1DP_CMD_INTF_QUERY	= 0x00,
+
+	/*! Query information about E1 line(s).
+	 * filter: intf (required), line (optional); in: n/a; out: array of osmo_e1dp_line_info */
 	E1DP_CMD_LINE_QUERY	= 0x01,
+
+	/*! Query information about E1 timeslot(s).
+	 * filter: intf (required), line (required), ts (optional); in: n/a; out: array of osmo_e1dp_ts_info */
 	E1DP_CMD_TS_QUERY	= 0x02,
+
+	/*! Configure a given E1 line.
+	 * filter: intf (required), line (required); in: osmo_e1dp_line_config; out: osmo_e1dp_line_info */
 	E1DP_CMD_LINE_CONFIG	= 0x03,
+
+	/*! Open a given E1 timeslot.
+	 * filter: intf (required), line (required), ts (required); in: osmo_e1dp_ts_config;
+	 * out: osmo_e1dp_ts_info with the opened TS (or an invalid one with id == -1 for errors)
+	 *      + message with the file descriptor */
 	E1DP_CMD_TS_OPEN	= 0x04,
+
+	/*! Message is an event */
 	E1DP_EVT_TYPE		= 0x40,
+	/*! Message is a response  */
 	E1DP_RESP_TYPE		= 0x80,
+	/*! Message is an error */
 	E1DP_ERR_TYPE		= 0xc0,
+	/*! Mask to separate type from command */
 	E1DP_TYPE_MSK		= 0xc0,
 };
 
+/*! e1d CTL protocol line mode. */
 enum osmo_e1dp_line_mode {
+	/*! Line is switched off */
 	E1DP_LMODE_OFF		= 0x00,
+	/*! Line is used in channelized mode with (64kBps) timeslots */
 	E1DP_LMODE_CHANNELIZED	= 0x20,
+	/*! Line is used as superchannel (31TS combined together) */
 	E1DP_LMODE_SUPERCHANNEL	= 0x21,
+	/*! Line is used in E1oIP mode (not available to CTL clients) */
 	E1DP_LMODE_E1OIP	= 0x22,
 };
 
+/*! e1d CTL protocol timeslot mode. */
 enum osmo_e1dp_ts_mode {
+	/*! Timeslot is switched off. */
 	E1DP_TSMODE_OFF		= 0x00,
+	/*! Timeslot is in RAW mode, containing transparent 64kBps bitstream. */
 	E1DP_TSMODE_RAW		= 0x10,
+	/*! Timeslot is in HLDC-FCS mode; e1d will run software HDLC processor. */
 	E1DP_TSMODE_HDLCFCS	= 0x11,
 };
 
-/* osmo_e1dp_ts_config.flags */
+/*! Flag that can be used as osmo_e1dp_ts_config.flags to force opening a TS. */
 #define E1DP_TS_OPEN_F_FORCE	0x80
 
-/* the idea here is to use the first byte as a version number, to prevent incompatible
+/*! Magic value. the idea here is to use the first byte as a version number, to prevent incompatible
  * clients from connecting to e1d */
 #define E1DP_MAGIC	0x01e1
+/*! Maximum length of a protocol message */
 #define E1DP_MAX_LEN	4096
+/*! magic value used to indicate superchannel instead of timeslot. */
 #define E1DP_TS_SUPERCHAN 0xfe
+/*! magic value to indicate given field (interface/line/timeslot) is
+ * unspecified/invalid. */
 #define E1DP_INVALID	0xff
+/*! default location of osmo-e1d CTL protocol UNIX domain socket */
 #define E1DP_DEFAULT_SOCKET "/tmp/osmo-e1d.ctl"
 
+/*! Maximum length of HDLC messages */
 #define E1DP_MAX_SIZE_HDLC	264
 
+/*! message header of osmo-e1d CTL protocol. */
 struct osmo_e1dp_msg_hdr {
-	uint16_t magic;
-	uint16_t len;
+	uint16_t magic;		/*< magic value (E1DP_MAGIC) */
+	uint16_t len;		/*< length of message (octets) */
 
-	uint8_t  type; 
-	uint8_t  intf;
-	uint8_t  line;
-	uint8_t  ts;
+	uint8_t  type;		/*< message type (enum osmo_e1dp_msg_type) */
+	uint8_t  intf;		/*< E1 interface number (or E1DP_INVALID) */
+	uint8_t  line;		/*< E1 line number (or E1DP_INVALID) */
+	uint8_t  ts;		/*< timeslot number (or E1DP_INVALID) */
 } __attribute__((packed));
 
+/*! Information about an E1 interface */
 struct osmo_e1dp_intf_info {
-	uint8_t id;
-	uint8_t n_lines;
+	uint8_t id;		/*< Numeric identifier of E1 interface */
+	uint8_t n_lines;	/*< number of E1 lines within this interface */
 } __attribute__((packed));
 
+/*! Configuration of an E1 line */
 struct osmo_e1dp_line_config {
-	uint8_t mode;
+	uint8_t mode;		/*< E1 line mode (enum osmo_e1dp_line_mode) */
 } __attribute__((packed));
 
+/*! Information about an E1 line */
 struct osmo_e1dp_line_info {
-	uint8_t id;
-	struct osmo_e1dp_line_config cfg;
-	uint8_t status;		/* TBD */
+	uint8_t id;				/*< E1 line number */
+	struct osmo_e1dp_line_config cfg;	/*! E1 line configuration */
+	uint8_t status;				/*!< TBD */
 } __attribute__((packed));
 
+/*! Configuration of an E1 timeslot */
 struct osmo_e1dp_ts_config {
-	uint8_t mode;
-	uint8_t flags;
-	uint16_t read_bufsize;
+	uint8_t mode;		/*< timeslot mode (enum osmo_e1dp_ts_mode) */
+	uint8_t flags;		/*< flags (currently only E1DP_TS_OPEN_F_FORCE) */
+	uint16_t read_bufsize;	/*< size of read buffer (in octets) */
 } __attribute__((packed));
 
+/*! Information about an E1 timeslot */
 struct osmo_e1dp_ts_info {
-	uint8_t id;
-	struct osmo_e1dp_ts_config cfg;
-	uint8_t status;		/* TBD */
+	uint8_t id;				/*< E1 timeslot number */
+	struct osmo_e1dp_ts_config cfg;		/*< E1 timeslot configuration */
+	uint8_t status;				/*< TBD */
 } __attribute__((packed));

osmo-e1d_0.4.0.15.5806.202211070002.tar.xz/src/proto_clnt.c -> osmo-e1d_0.4.0.20.2041.202211080002.tar.xz/src/proto_clnt.c Changed

@@ -22,6 +22,28 @@
  * along with this program; if not, see <http://www.gnu.org/licenses/>.
  */
 
+/*! \file proto_clnt.c
+ * e1d protocol client library (libosmo-e1d).
+ *
+ * This library implements ways how an external client (application
+ * program) can talk to osmo-e1d.  The primary purpose is to open
+ * specific E1 timeslots in order to receive and/or transmit data on
+ * them.
+ *
+ * Each such open timeslot is represented to the client program as a
+ * file descriptor, which the client can read and/or write as usual.
+ * This is implemented using underlying UNIX domain sockets and file
+ * descriptor passing.
+ *
+ * In addition to opening timeslots, client applications can also query
+ * osmo-e1d for information about its E1 interfaces, E1 lines and E1 timeslots.
+ *
+ * The functions provided by this client library are implemented as
+ * synchronous/blocking calls to osmo-e1d.  This means that an API call
+ * will be blocking until there is a response received from osmo-e1d.
+ *
+ */
+
 #include <errno.h>
 #include <fcntl.h>
 #include <unistd.h>
@@ -43,9 +65,10 @@
 #include "log.h"
 
 
+/*! Internal representation of client program connected to the CTL socket */
 struct osmo_e1dp_client {
-	void *ctx;
-	struct osmo_fd ctl_fd;
+	void *ctx;		/*!< talloc context */
+	struct osmo_fd ctl_fd;	/*!< osmo-fd wrapped unix domain (CTL) socket to @osmo-e1d@ */
 };
 
 
@@ -85,6 +108,10 @@
 }
 
 
+/*! Create a new client talking to the CTL server socket of osmo-e1d.
+ *  \paramin ctx talloc context from which this client is allocated
+ *  \paramin path path of the CTL unix domain socket of osmo-e1d
+ *  \returns handle to newly-created client; NULL in case of errors */
 struct osmo_e1dp_client *
 osmo_e1dp_client_create(void *ctx, const char *path)
 {
@@ -113,6 +140,9 @@
 }
 
 
+/*! Destroy a previously created client. Closes socket and releases memory.
+ *  \paramin clnt Client previously returned from osmo_e1dp_client_create().
+ */
 void
 osmo_e1dp_client_destroy(struct osmo_e1dp_client *clnt)
 {
@@ -192,6 +222,12 @@
 	return rc;
 }
 
+/*! Query osmo-e1d for information about a specific E1 interface.
+ *  \paramin clnt Client previously returned from osmo_e1dp_client_create().
+ *  \paramout ii callee-allocated array of interface information structures.
+ *  \paramout n caller-provided pointer to integer. Will contain number of entries in ii.
+ *  \paramin intf E1 interface number to query, or E1DP_INVALID to query all interfaces.
+ *  \returns zero in case of success; negative in case of error. */
 int
 osmo_e1dp_client_intf_query(struct osmo_e1dp_client *clnt,
 	struct osmo_e1dp_intf_info **ii, int *n,
@@ -223,6 +259,14 @@
 	return 0;
 }
 
+/*! Query osmo-e1d for information about a specific E1 line.
+ *  \paramin clnt Client previously returned from osmo_e1dp_client_create().
+ *  \paramout li callee-allocated array of line information structures.
+ *  \paramout n caller-provided pointer to integer. Will contain number of entries in li.
+ *  \paramin intf E1 interface number to query.
+ *  \paramin line E1 line number (within interface) to query, or E1DP_INVALID to query all lines within the
+ *  interface.
+ *  \returns zero in case of success; negative in case of error. */
 int
 osmo_e1dp_client_line_query(struct osmo_e1dp_client *clnt,
 	struct osmo_e1dp_line_info **li, int *n,
@@ -254,6 +298,15 @@
 	return 0;
 }
 
+/*! Query osmo-e1d for information about a specific E1 timeslot.
+ *  \paramin clnt Client previously returned from osmo_e1dp_client_create().
+ *  \paramout ti callee-allocated array of timeslot information structures.
+ *  \paramout n caller-provided pointer to integer. Will contain number of entries in ti.
+ *  \paramin intf E1 interface number to query.
+ *  \paramin line E1 line number (within interface) to query.
+ *  \paramin ts E1 timeslot numer (within line) to query, or E1DP_INVALID to query all of the timeslots
+ *  within the line.
+ *  \returns zero in case of success; negative in case of error. */
 int
 osmo_e1dp_client_ts_query(struct osmo_e1dp_client *clnt,
 	struct osmo_e1dp_ts_info **ti, int *n,
@@ -285,6 +338,12 @@
 	return 0;
 }
 
+/*! Configure a specific E1 line in osmo-e1d.
+ *  \paramin clnt Client previously returned from osmo_e1dp_client_create().
+ *  \paramin intf E1 interface number to configure.
+ *  \paramin line E1 line number (within interface) to configure.
+ *  \paramin mode E1 line mode to set on line.
+ *  \returns zero in case of success; negative in case of error. */
 int
 osmo_e1dp_client_line_config(struct osmo_e1dp_client *clnt,
 	uint8_t intf, uint8_t line, enum osmo_e1dp_line_mode mode)
@@ -350,6 +409,14 @@
 	return tsfd;
 }
 
+/*! Open a specific E1 timeslot of osmo-e1d.
+ *  \paramin clnt Client previously returned from osmo_e1dp_client_create().
+ *  \paramin intf E1 interface number of line containing timeslot.
+ *  \paramin line E1 line number (within interface) of line containing timeslot.
+ *  \paramin ts E1 timeslot number (within line) to open.
+ *  \paramin mode timeslot mode (RAW, HDLC-FCE) in which to open timeslot.
+ *  \paramin read_bufsize size of read buffer (in octets) to use.
+ *  \returns file descriptor of opened timeslot in case of success; negative in case of error. */
 int
 osmo_e1dp_client_ts_open(struct osmo_e1dp_client *clnt,
 	uint8_t intf, uint8_t line, uint8_t ts,
@@ -358,6 +425,17 @@
 	return _client_ts_open(clnt, intf, line, ts, mode, read_bufsize, 0);
 }
 
+/*! Force-Open a specific E1 timeslot of osmo-e1d.
+ *  The normal (non-force) opening of a timeslot will fail in case the given timeslot is already
+ *  open (by either this or some other client).  Using the open_force variant you can force osmo-e1d
+ *  to disregard the existing client/timeslot and transfer ownership of the timeslot to this client.
+ *  \paramin clnt Client previously returned from osmo_e1dp_client_create().
+ *  \paramin intf E1 interface number of line containing timeslot.
+ *  \paramin line E1 line number (within interface) of line containing timeslot.
+ *  \paramin ts E1 timeslot number (within line) to open.
+ *  \paramin mode timeslot mode (RAW, HDLC-FCE) in which to open timeslot.
+ *  \paramin read_bufsize size of read buffer (in octets) to use.
+ *  \returns file descriptor of opened timeslot in case of success; negative in case of error. */
 int
 osmo_e1dp_client_ts_open_force(struct osmo_e1dp_client *clnt,
 	uint8_t intf, uint8_t line, uint8_t ts,

rpmlintrc Added

Changes of Revision 135