diff options
Diffstat (limited to 'RELNOTES.txt')
| -rw-r--r-- | RELNOTES.txt | 369 |
1 files changed, 369 insertions, 0 deletions
diff --git a/RELNOTES.txt b/RELNOTES.txt new file mode 100644 index 0000000..be4df57 --- /dev/null +++ b/RELNOTES.txt @@ -0,0 +1,369 @@ +Release notes for Open Source OSS version v4.2-build2006 +================================================== + + +What is the open sourced version +-------------------------------- + +It is an open source version of the Open Sound System (OSS) sound subsystem +software released under the GPL license. The only difference between the +"commercial" version and the open source version of OSS is the commercial +version contains certain drivers that contain code encumbered under NDA. + +There are three source packages released by 4Front Technologies: + + * GPL version contains the source code for Linux + * CDDL version contains the source code for Solaris + * BSD version contains the source code for FreeBSD (and other BSD OSs) + +See www.opensound.com for more information about OSS. Our developer web site +(http://developer.opensound.com) will give additional information for +application developers and OSS contributors. + +NOTICE! In general it is not possible to mix binary modules from the commercial +OSS package with rest of the software compiled from open source OSS sources +because certain header files and core data structures are incompatible. If you +need to use one of the drivers missing from the open source version you will +have to use the retail version of OSS instead. + +Build system requirements +------------------------- + +To be able to extract the source files from the tarball you will +need the bunzip2 command in the system. It's usually available by default +but otherwise you will need to download the sources from the net and compile it. + +OSS is currently compatible with the following operating systems and processor +architectures. Other environments may be supported later. + +Operating system Version Processor architecture + +Solaris/OpenSolaris 10 or later x86, amd64, Sparc (64 bit) +Linux 2.6 or later x86, x86_64 +FreeBSD 6 or later x86, x86_64 +SCO UnixWare 7 or later x86 +SCO OpenServer 6 or later x86 + +Note that the very latest kernel versions may not be supported out of box. +Changes may be needed to OSS before it supports them. + +The system used to build OSS should have full kernel/driver development +environment installed (C/C++ compiler, linker, make, kernel headers, etc). +Please refer to the documentation of the operating system you are using + +Under Linux and FreeBSD the C compiler to use is GCC (_MUST_ be v3.0 or later). +With the other operating systems you need to use the C compiler provided by +the operating system vendor. + +In addition GNU awk needs to be available in the system as gwak. Otherwise the +manual pages will not be created correctly (otherwise OSS will compile and +work OK). + +The stock make command shipped with some operating systems (SCO UnixWare and +OpenServer) is not capable to compile OSS. In such systems you will have to +install GNU make and use it instead. The make utilities shipped with Linux, +Solaris and FreeBSD are OK. + + +GTK 1.2 or GTK 2.0 development libraries must also be installed for the +GUI apps like ossxmix. GTK 2.0 must be installed and registered via pkgconfig +or GTK-1.2 must be installed and gtk-config must be there in the path. + + +Target system requirements +-------------------------- + +OSS can be installed in a different computer system than where the +software was compiled (OTOH in many cases these systems are the same machine). + +Under Linux and FreeBSD some parts of the software need to be compiled in +the target system to handle differences between different kernel versions. For +this reason it's necessary to have a functional kernel development system +installed in the target machine too. In FreeBSD this is the default. + +Under Linux systems the target machine should have the following packages +installed (unfortunatgely they are not installed by default. + +- Kernel sources and/or headers for the currently active kernel. +- C compiler (gcc or cc) +- make (gmake or make) +- GNU binutils (ld, as) +- GNU awk (gawk) +- Standard C library (libc/glibc) headers. +- GTK+ (either v1.2 or v2.0) + +Source directory structure +-------------------------- + +The directory scheme of OSS is different from most other software packages. +Instead of storing source files in the "build" tree we have separated +the build (object) directory from the source directory. In this way the sources +can be located in a common directory on a (NFS) server and shared between +several "build" machines possibly running different operating systems. Any +number of build machines can be used to compile OSS at the same time without +disturbing each other. However nothing prevents from having the source +directory located in the local machine or even on CD-ROM or some other +read-only media. + +There is nothing special in the source directory. Its contents are distributed +in the source tarball (oss-v4.2-build2006-src-gpl.tar.bz2). + +The build directory is a special directory that contains symbolic links to +the corresponding files in the source directory. Files in the build directory +can be edited and the changes will be directed to the original file in the +source directory (provided that it is writeable). However the object files will +only be created in the local build directory only. + +Note that there is also some C code (.c and .inc) files that are not built in +the source system but in the target. These files are located in the +setup/`uname`/oss directory. This is necessary because certain kernel data +structures depend on the kernel version being installed in the target system. +The goal of this mechanism is that majority of the code can be compiled in +any system. Only the kernel version dependent parts (wrappers) need to be +compiled in the target system (this mechanism will become unnecessary in the +future when these operating systems (Linux in particular) get a proper +device driver interface. + + +Installing the sources +---------------------- + +Save the tarball containing the source files in /tmp (or some other +directory in the development system). In this document we will assume +that you have stored the sources in /tmp/oss-v4.2-build2006-src-gpl.tar.bz2. + +Go to the directory where you would like to create the source directory. +For example: + + cd /usr/src + +Next restore the files in the tarball by executing the following command: + + bunzip2 -c /tmp/oss-v4.2-build2006-src-gpl.tar.bz2 | tar xvf - + +(Or if you have GNU make (Linux, FreeBSD) you simply use +tar xvfj /tmp/oss-v4.2-build2006-src-gpl.tar.bz2). + +After restoring the files they will appear in the oss-v4.2-build2006-src-gpl +subdirectory under the current directory. + +Note! bunzip2 command is part of the bzip2 package. + +Compiling obsolete drivers +-------------------------- + +Drivers for few sound cards are no longer actively maintained and they will +not be compiled by default. These devices have been out of production for +about 10 years and we don't expect that anybody has them any more: + + oss_allegro + oss_als3xx + oss_als4k + oss_digi32 + oss_maestro + oss_neomagic + oss_s3vibes + oss_vortex + +The above drivers are located in the attic/drv subdirectory and they will not +get compiled by default. However you can compile any of them after creating +a symbolic link (this needs to be done in the source directory before running +the configure script. For example if you would like to compile the oss_digi32 +driver then you can do the following: + + cd kernel/drv + ln -s ../../attic/drv/oss_digi32 . + +Creating the build environment +------------------------------ + +If you have an earlier OSS build directory in the system it's recommended that +you remove it before creating the build directory for v4.2-build2006 +alternatively you may create separate build directories for different +OSS versions. + +Before you can build OSS you will need to create an empty "build" directory +and run the configure script. This as well as the actual compile/build step can +be done by any user (ie super user capabilities are not required). + +NOTE! THE BUILD DIRECTORY MUST BE OUTSIDE THE SOURCE DIRECTORY. Otherwise + the configure script will go to endless loop and fail. You need to give + absolute path to the source directory when running configure. Relative + paths (such as ../$TARGETDIR/configure) will not work properly. + +The build directory can be located anywhere (say in your home directory). +However the directory must be completely empty (no files in it). For example +you can create and initialize the build directory in the following way +(assuming that the source directory is /usr/src/$TARGETDIR): + + mkdir oss + cd oss + /usr/src/$TARGETDIR/configure + +The configure script will perform slightly different steps depending on the +current operating system. + +SCO OpenServer and SCO UnixWare are regarded as the same plattform and the +same OSS package will work under both of them. + +Solaris environment differs from the other operating systems because the +same build will compile both 32 and 64 bit drivers. So there will be two +almost identical subdirectory trees (i386 and amd64) under Solaris. + +Some drivers only work under x86 or certain operating systems. For this reason +not all drivers will get compiled in some environments. + +Command line arguments of the configure script +---------------------------------------------- + +In most cases you should execute the configure script without any command +line arguments. The following switches are available but they are mostly +untested and should only be used in special situations. + + +--regparm +--no-regparm + +These switches are only defined for Linux. They control if OSS is to be built +for a kernel compiled with or without the CONFIG_REGPARM setting. By default +OSS drivers will be compiled for both alternatives and the right one will be +selected automatically when OSS is installed. + +--target=uclinux-blackfin + +Experimental an incompletely implemented hack for cross compiling OSS for +uClinux/Blackfin. Do not use. + +--copy-files + +By default the configure script will create symbolic links from the build +directory to the original files in the source directory. This switch can be +used to force copying of files instead of linking. This will result in multiple +copies of the same file in the source tree (under Linux and Solaris/x86). +For this reason this switch should not be used. + +--config-vmix=FLOAT | FIXEDPOINT | NO + +By default the virtual mixer (vmix) subsystem will be enabled. Depending on the target operating system +it will use floating point (Linux) or fixed point arithmetic. This command line switch can be used +to disable vmix (NO) or to enforce fixed point (FIXEDPOINT). Note that floating point is not supported +under other that x86/x86_64 processors. Also some operating systems don't support it. + +--config-midi=NO|YES + +By default (in OSS v4.1) MIDI support is disabled. If you like to do hacking with MIDI you can enable it +by using --config-midi=YES. + +Compiling OSS +------------- + +You can compile OSS by running make under the build directory. This will +only compile the C source files to binary objects but doesn't actually build +the installable files. There are few make targets that are used to +build the software in different ways: + +make build: + +This command compiles the binaries and runs the ./build.sh script +(OS dependent) to create the full prototype tree (./prototype). This directory +contains a copy of the files to be installed in the target system (relative +to the / directory). + +make install: + +This command does "make build" and then copies the files/directories located +in the ./prototype subdirectory to their proper places (under /). After that +the script performs the (OS dependent) steps required to install the drivers +in the local system. It may be necessary to run soundoff and soundon to reload +the drivers in the kernel after running "make install". + +This method is a fast way to recompile and install OSS in the system +when hacking with the drivers. However it's necessary to create the proper +installation package and install it when installing a new OSS version +for the first time. + +make package: + +This command will compile the OSS software and buil a proper installation +package (.rpm, .pkg or something else depending on the operating system). +This package (from the local directory) can then be installed in the target +system (local computer or somewhere else) using the usual software installation +and management tools (pkgadd/pkgrm, rpm) provided by the operating system. + +Notice that this command may not work properly in all Linux systems because +most Linux distributions are incompatible with each other. So the +files/scripts used to create the RPM package may need to be edited if you are +using any other distribution than SuSE or Redhat/Fedora. In particular Debian +style package management is not supported. If you are installing OSS in a +noncompatible system you will have to use "make install" (or to move the +files using a tar package and then run the install script +(cd /usr/lib/oss/build;sh install.sh). + +Summary: (This is how we build OSS at 4front) +--------------------------------------------- +1) cd /usr/src; tar -jxvf oss-v4.2-build2006-src-gpl.tar.bz2 +2) mkdir /usr/src/oss; cd /usr/src/oss +3) /usr/src/$TARGETDIR/configure +4) make install + This step compiles the software and copies the files to their right + places. Finally it starts the drivers using the soundon script. + +Installing the compiled (binary) package in the target system +------------------------------------------------------------- + +After running make package the install package (.pkg/.rpm) will be created in +the build directory. This package can be moved to the target system and +installed using the pkgadd or rpm commands. + +Managing OSS installation +------------------------- + +OSS can be started and stopped by using the soundon and soundoff commands +(respectively). Soundon will create a log file (/usr/lib/oss/logs/soundon.log) +that contains debugging information that helps in solving problems with OSS. + +Installing the OSS package will also install a startup script (usually +/etc/rc3.d/S89oss) that will start OSS automatically when the system gets +rebooted. So running soundoff or soundon is manually is rarely necessary. + +Information about the devices in the system can be printed using +the ossinfo command (ossinfo -v3 for most detailed output). + +When new hardware is installed in ths system it is usually necessary to +run the ossdetect utility (ossdetect -v for verbose output) to find the new +devices in the system. After running ossdetect you will need to run soundoff +and soundon to reload the drivers (not necessary under Solaris). + +Configuration options +--------------------- + +The /usr/lib/oss/conf directory will contain various configuration +files (or actually symbolic links to the actual files in system dependent +directories). These files can be edited using any text editor to change the +settings. However there is rarely need to change these settings. + +You need to run soundoff and soundon to make the config option changes +to take effect. Under SCO OpenServer and UnixWare you will also need to run +the following commands _before_ doing soundoff;soundon: + + cd /usr/lib/oss/build + sh install.sh + +Developing OSS compatible applications +-------------------------------------- + +The OSS API is documented in the OSS Programmer's Guide +(http://manuals.opensound.com/developer). + +Making modifications to Open Sound System +----------------------------------------- + +If you plan to make modifications to Open Sound System, please check +our developer web site (http://developer.opensound.com) before doing anything. +Also it's recommended that you join the oss-devel mailing list and describe +the changes you are planning to do. We will accept contributions to the code. +However there are certain rules the contributions must follow before they can +be accepted. First of all the contributions must not cause any compatibility +problems between different OSS versions. Also changes that may increase +complexity of the OSS API or could cause incompatibilities between devices will +probably not be accepted. |