make-srpm-cleanup

package: srpm-cleanup

title: make-srpm-cleanup(7)

text:
# make-srpm-cleanup(7)

## NAME
make-srpm-cleanup - truntate unused files in SRPM packages stage by stage

## SYNOPSIS
make status

make stage...

make stage...-status

make list-...

make show-...

make check-...

make update-...

make export...

make statclean

make clean...

make update-versions.sed

## DESCRIPTION
In order to control the process of SRPM cleanup with make(1) copy the example Makefile from /usr/share/doc/srpm-cleanup/Makefile.example to Makefile in the working directory and modify it in accordance with your needs. You can also write your own configuration Makefile from scratch but don´t forget to include /usr/share/srpm-cleanup/main.mk at its end.

### Stages
The whole process of SRPM cleanup is divided onto 5 following stages:

- Stage I: SRPM packages are rebuilt using hsh-separate-sources(1) and a list of unused files is written down for each package.

- Stage II: SRPM packages are rebuilt using srpm-cleanup(1) and a TAR with source files is written down for each package. Comparing to the original package, the resulting TAR doesn´t contain unused files.

- Stage III: For each TAR package the corresponding SRPM package is built using srpm-cleanup(1).

- Stage IV: SRPM packages from Stage III are rebuilt with hsh-separate-sources(1) in verification mode. The verification process checks there are no new unused files. However, in some situations that check should be toolerated (see TOOLERANCE below).

- Stage V: The resulting verified SRPM packages are rebuilt with additional options (for example --with-pre and --with-post). For packages that have failed with verification the corresponding original SRPMs are rebuilt instead.

On each stage the packages are rebuilt in parallel inside a number of hasher(1) slots on a set of build hosts. The results of that builds and the build log files are transferred from build hosts and collected in the configured directories. The results of one stage are used on the next stage.

When a package is processed the output of used tools such as hsh-separate-sources(1) is written to the stage log file. The tarnscript of low-level operation goes to the build log file. After the whole stage is passed the corresponding stage status file is updated. That status file is constituted from the stage log records plus a special status record for each package that is deduced from the stage log records related to it. With the stage status file it is very easy to find the resulting status of each particular package.

Knowing the resulting status of each package it is possible to retry the stage processing for only a subset of packages based on thier status and after making the necessary configuration changes (see "Stage retries" below).

For each stage the following common targets are available:

- stageN: Run the stage N for packages that havn´t yet been processed. Run the stage on all configured BUILDERS on all architectures (see CONFIGURATION below). The values for N are 1..4, 5v and 5o. The last two are for the separate substages of Stage V: rebuilt of verified and the original packages.

- stageN-status: Show statistics for stage N.

- list-stageN-C[-A]: List names and versions of packages that fall into category C and optionally architecture A in stage N. The packages are divided onto categories using information from the stage status file.

Available architectures A are those for which BUILDERS are defined (see CONFIGURATION below).

Popular C examples among different stages are:

- done: successfully built packages,

- noatt: there were no attempts to build these packages yet,

- excl: build failed because of ExclusiveArch or ExcludeArch declaration,

- blderr: any kind of build error,

- brkndep: build failed because of broken dependencies,

- chkerr: build failed in the %check section,

- nosrpm: the builder was unable to find the SRPM file for the given package,

- nospace: build failed due to no space left on device,

- noinode: build failed due to lack of inodes,

- logerr: hsh-separate-sources(1) failed to analize the build log,

- other: any other error,

- unused: the packages are not listed in SRPM_LISTS (see CONFIGURATION below).

### Stage retries
When a lot of packages are processed, building some of them are often failed --- that´s normal. In that situation the first thing is to investigate the situation, then fix the problem and re-run the stage for the failed packages only.

To help the investigation the following additional targets are available for each stage:

- list-stageN-C[-A]-logs: List paths to the build logs of packages that fall into category C and optionally architecture A in stage N.

- show-stageN-C[-A]-status: Output the stage status log entries related to the packages that fall into category C and optionally architecture A in stage N.

- show-stageN-pkg-status: Output the stage status log entries related to a single package specified with PKG=PKG. For stages I, IV-V the architecture can be additionally limited with ARCH=ARCH.

To re-run the stage for the failed packages only use:

- stageN-retry-C[-A]: Retry the stage N for packages that fall into category C and optionally architecture A.

- stageN-retry-pkgs

If INDEP_LOGS (see CONFIGURATION) is set then a number of such jobs can be run for the same stage in parallel.

To re-run the stage for all packages (failed, done and not tried) use:

•

stageN-rebuild-all: Run stage N from scratch.

When re-running the stage it is possible to alter the configuration of builders, for instance, to change the number of hasher slots --- see BUILDERS in CONFIGURATION below. Additionaly, for Stage V (both 5v and 5o parts) it is possible to run the process for only a subset of architectures: use FOR_ARCHES=<arch1,arch2...> on the command line.

### Partial Stage V targets
For Stage V the following partial subtartets are available:

- stage5v|o-all: Run the stage for not yet tried packages included in all defined architectures.

- stage5v|o-A: Run the stage for not yet tried packages of architecture A.

### Complete stage rebuilds
The run of a stageN target selects and process packages that weren´t processed on that stage yet (that are the packages from noatt category). In order to run the stage for all listed SRPM packages use stageN-rebuild-all target. However, the hsh-separate-sources(1) and srpm-cleanup(1) tools are known to skip the already processed packages anyway. So, to really rebuild all packages delete the existing results with stageN-clean or add -f|--force to the OPTS (see Runtime options below).

### Rebuilds with manual package selection and multistage retries

- stageN-retry-pkgs: Re-run stage N for a specified list of packages. These targets expect name-version-release of packages to be specified on the command line with PKGS=<PKGS...>. In order to rebuild a package forcily pass -f|--force to the OPTS (see Runtime options below).

- reclean-pkgs: Runs stages II and III for the selected packages specified with PKGS=<PKGS...>.

- reclean-and-rebuild-pkgs: Runs stages II, III and IV for the selected packages specified with PKGS=<PKGS...>.

- relook-pkgs: Runs stage I in force mode for the selected packages specified with PKGS=<PKGS...>.

- relook-and-reclean-pkgs: Runs stages I--III for the selected packages specified with PKGS=<PKGS...>.

- relook-and-rebuild-pkgs: Runs stages I--IV for the selected packages specified with PKGS=<PKGS...>.

- clean-and-verify-noatt: Runs stages I--IV for the selected packages specified with PKGS=<PKGS...> with force mode off.

### Dry runs
For each stage target, either the main stage target or any retry or additional target, there is the corresponding -dry-run target available. In the dry-run mode the stage isn´t actually run. Instead of that the list of command lines that would be executed in the normal stage run is printed out.

Moreover, for each stage target the corresponding -dry-run-run target is also available. In that "semi-dry" mode the tools are actually run (on remote hosts, if configured --- see BUILDERS), but each tools is run with --dry-run option.

In both dry-run modes no packages are built, the log files are not written and the stage status is not updated.

### Building external SRPMs
It is possible to rebuild out of the repo SRPM packages passing WITH_SRPMS=EXTRA_DIR to any stage target. However, dist-tags of such packages are undefined!

### Check and export
•

check-rebuild-lists: This target outputs the final statistics after stage IV separated the onto four following categories: done-included-all --- successfully rebuilt packages, included on all architectures; done-xincluded --- successfully rebuilt packages, included on some architectures (for each architecture); not-done-included-all --- failed packages, included on all architectures; not-done-xincluded --- failed packages, included on some architectures (for each architecture).

These package lists constitute a plan for stage V. The successfully rebuilt packages go to V/1 substage and the rest goes to V/2 (rebuilt of the original packages).

The target checks for intersections between the resulting lists and package coverage on each architecture (i. e. the number of all packages included in SRPM_LISTS versus the number of packages, planned for stage V).

•

check-rebuild-results-A: The target outputs statistics similar to check-rebuild-lists, but from stage V point of view: the number of planned verified and original builds can be compared with actual V/1 and V/2 results. The additional feature of the target is that the coverage is calculated twice: first as a plain number of packages successfully rebuilt on stage V, and a second time --- with additional number of packages, failed due to architecture exclusion (i. e. ExcludeArch and ExclusiveArch tags in the RPM spec file).

The statistic is output for the specified architecture A only.

- check-versions: Runs check-included and then check-disttags if DISTTAG_OPTS is defined (see Configuring Stage V).

- check-included: Output the diff between SRPM_LISTS and the packages, actually included into processing on the stages I-V. Normally, the diff should be empty.

- check-disttags: Compares the dist-tags of packages in the reference repository REPO_DIR with dist-tags in the stage V resulting packages in REBUILD_V_DIR and REBUILD_O_DIR directories (see Configuring Stage V). Normally, the diff should be empty.

- export: Copy stage V results from REBUILD_V_DIR and REBUILD_O_DIR directories along with index files into the target directory DESTDIR=DESTDIR (can be specified on the command line or configured in the Makefile). Any extra RPM files in DESTDIR are removed making the source and destination synchronized.

Additional options can be passed to rsync(1) via EXPORT_OPTS=EXPORT_OPTS.

- repo: Constructs an APT repository at OUTREPO (repo by default) with clean, orig, clean-dbg and orig-dbg packages sections.

- export-repo: Copies the repository to DESTDIR. By default the symbolic links to packages are not resolved. In order to copy the linked files add -L to EXPORT_REPO_OPTS (see rsync(1) for more information).

### Clean targets

- statclean: Deletes all temporary files used to calculate statistic values for stageN-status targets.

- clean-stage1-<arch>-unused: Delete SKIPLIST_DIR lists for the packages that aren´t currently included in SRPM_LISTS for the architecture arch.

- clean-stage2-unused: Delete TAR_DIR files for the packages that aren´t currently included in SRPM_LISTS.

- clean-stage3-unused: Delete SRPM_DIR packages that aren´t currently included in SRPM_LISTS.

- clean-stage4-<arch>-unused: Delete RPM_DIR packages that aren´t currently included in SRPM_LISTS for the architecture arch.

- clean-stage5v-unused: Delete REBUILD_V_DIR packages that aren´t currently included in SRPM_LISTS.

- clean-stage5o-unused: Delete REBUILD_O_DIR packages that aren´t currently included in SRPM_LISTS.

- clean-indices: Remove the index files, first of all, the DISTTAG_INDEX file used for stage V (see Configuring Stage V). The indices can explicitly be re-created with index-rebuild target.

- stageN-clean: Delete all results and status files of stage N. WARNING! these targets are dangerous! In order to protect the results from accidentally deletion a confirmation is asked.

### Other targets

- list-srpms: Output the list of all included SRPMs.

- show-builders: Output the resulting command-line for the configured BUILDERS (see the CONFIGURATION below) that is used for rebuilding of binary packages (stages I, IV-V).

- list-builders: Displays the table of the defined builders with their basic parameters.

- add-builder: Adds the host with specified parameters (see below) to the list of builders.

- del-builder: Deletes the given host from the list of builders.

- show-cleaners: Output the resulting command-line for the configured CLEANERS (see the CONFIGURATION below) that is used to clean-up source packages (stage II).

- list-cleaners: Displays the table of the defined cleaners with their basic parameters.

- add-cleaner: Adds the host with specified parameters (see below) to the list of cleaners.

- del-cleaner: Deletes the given host from the list of cleaners.

- show-srpm-builders: Output the resulting command-line for the configured BUILDERS (see the CONFIGURATION below) that is used for rebuilding of source packages (stage III).

- show-repo-dir: Displays the current value of REPO_DIR.

- set-repo-dir: Sets the REPO_DIR value to REPO_DIR=repo_dir specified on the command line.

- show-srpm-lists: Displays the current contents of SRPM_LISTS. Especially suitable if automatic source list configuration via AUTO_SRPM_LIST_DIR is set up.

- update-srpm-versions: Runs the update-versions.sed script (see below) against the SRPM_LISTS files.

### Scripts
•

update-versions.sed: The script that is automatically prepared from BIN_LIST (depends on REPO_DIR) and can be used to update version numbers in the existing SRPM lists (manually or by the update-srpm-versions target).

## CONFIGURATION

### Automatic source list configuration
•

AUTO_SRPM_LIST_DIR: Put *-<arch>.srpms files into AUTO_SRPM_LIST_DIR in order to automatically add to SRPM_LISTS the latest file for each architecture. In the example Makefile AUTO_SRPM_LIST_DIR is set to srpm-lists.

If you have two or more different kinds of lists (for example, one that defines packages for server and another for the desktop) and want to use the automatic source list configuration, you have to put them into different subdirectories within AUTO_SRPM_LIST_DIR.

To see the current contents of SRPM_LISTS run the show-srpm-lists target.

### Manual source list configuration
•

SRPM_LISTS: Defines source package list files for each architecture. Each set of files should be added to SRPM_LISTS using $(call def_srpm_list,arch,files...), where arch is the name of an architecture and files is a space-separated list of files listing source RPM file names (name-version-release.src.rpm) line by line.

For example:

```
SRPM_LISTS = $(call def_srpm_list,ppc64le,lists/alt-sp8-server-latest-ppc64le.iso.srpms)
SRPM_LISTS += $(call def_srpm_list,aarch64,lists/alt-sp8-server-latest-aarch64.iso.srpms lists/alt-sp8-workstation-latest-aarch64.iso.srpms)
SRPM_LISTS += $(call def_srpm_list,armh,lists/alt-sp8-workstation-01-mcom02-latest-armh.img.srpm-list)
SRPM_LISTS += $(call def_srpm_list,i586,lists/alt-sp8-server-latest-i586.iso.srpms lists/alt-sp8-workstation-latest-i586.iso.srpms)
SRPM_LISTS += $(call
def_srpm_list,x86_64,lists/alt-sp8-server-latest-x86_64.iso.srpms
lists/alt-sp8-workstation-latest-x86_64.iso.srpms)
```

### Configuring buidlers
To simplyfy adding builders there is the add-builder target:

```
add-builder HOST=<host> ARCH=<arch> SLOTS=<slots> REPO=REPO_DIR|<repo> [WORKDIR=<workdir>] [NPROCS=<nprocs>] [NOT_CLEANER=]´
```

The specified host is added to the list of BUILDERS. If NOT_CLEANER=1 isn´t passed, the specified host is also added to the list of CLEANERS.

If DEFAULT_NPROFILE is defined, then the add-builder target initializes the host.nprofile file from the specified file.

In order to delete the builder you can use the del-builder target:

```
del-builder HOST=<host> [NOT_CLEANER=]
```

The specified host is removed from the list of BUILDERS. If NOT_CLEANER=1 isn´t passed, the specified host is also removed from the list of CLEANERS.

•

BUILDERS: Defines the set of local and remote builders (hosts where hsh-separate-sources(1) can be run). Each builder should be added to BUILDERS using $(call def_builder,[user@]hostname,arches...,slots,workdir,repo[,nprofile]), where [user@]hostname defines the name of the remote host and an optional user name to connect with, arches is a space-separated list of architecture names, slots is a list of a range of Hasher slot numbers, workdir is the path to the working directory (on the remote host), repo is the path to package repository (on the remote host) and nprofile is the optional name of a CPU profile file.

All of the def_builder argumentsare match the command line options of hsh-separate-sources(1). In order to build on the local machine use : for the name of the host and don´t specify the user name.

Example:

``` BUILDERS = $(call def_builder,ppc,ppc64le,$(ppc_slots),/tmp/.private/builder/hashers,$(nfs_repo),$(nprocs))

BUILDERS += $(call def_builder,taishan1,aarch64 armh,$(arm_slots),/tmp/.private/builder/hashers,$(nfs_repo),$(nprocs))

BUILDERS += $(call def_builder,builder_new@ivkbuilder,x86_64 i586,$(ivk_slots),/tmp/.private/builder_new/hashers,$(ivk_repo),$(nprocs)) ```

### Configuring cleanders
To simplyfy adding builders there is the add-cleaner target:

```
add-cleaner HOST=<host> SLOTS=<slots> SRPMS=<srpms> | REPO=REPO_DIR|<repo> [WORKDIR=<workdir>]
```

The specified host is added to the list of CLEANERS. In order to delete the cleaner you can use the del-cleaner target:

```
del-cleaner HOST=<host>
```

The specified host is removed from the list of CLEANERS.

•

CLEANERS: Defines the set of local and remote cleaners (hosts where srpm-cleanup(1) can be run). Each cleaner should be added to CLEANERS using $(call def_cleaner,[user@]hostname,slots,workdir,srpms), where [user@]hostname defines the name of the remote host and an optional user name to connect with, slots is a space-separated list of a range of Hasher slot numbers, workdir is the path to the working directory (on the remote host) and srpms is the path to the directory with SRPM files (on the remote host).

All of the def_cleaner argumentsare match the command line options of srpm-cleanup(1). In order to build on the local machine use : for the name of the host and don´t specify the user name.

Example:

```
CLEANERS = $(call def_cleaner,ppc,1-40,/tmp/.private/builder/hashers,$(nfs_repo)/files/SRPMS)
CLEANERS += $(call def_cleaner,taishan1,1-40,/tmp/.private/builder/hashers,$(nfs_repo)/files/SRPMS)
CLEANERS += $(call def_cleaner,builder_new@ivkbuilder,1-40,/tmp/.private/builder/hashers,$(ivk_repo)/files/SRPMS)
```

- EXTRA_ARCHES: Specify extra arches of those builders that aren´t currently configured.

- REPO_DIR: Defines the default repository path for add-builder and add-cleaner targets. Also used in the configuration of Stage V.

- DEFAULT_NPROFILE: Defines the name of the reference NPROC profile file that is used by add-builder target.

### Remote options

- SSHDELAY: Log-in to the next remote host after a delay. Setting this to a positive non-zero value helps against SSH errors when a lot of parallel remote processes are started.

- SELFIE: Tell the tools to copy theirselves on the remote hosts.

- REMOTE_DIR: The directory to use as the current when executing tools on remote hosts. If is set to ... then a temporary directory is used which is deleted after execution. Using this value is a good alternative to CLEANUP=1.

- WITH_NPROFILE: Copy NPROC profile to remote builders. To select files automatically based on the name of the host set it to %h.nprofile (see --with-nprofile in hsh-separate-sources(1)).

- CLEANUP: Set this to enable --cleanup mode with hsh-separate-sources(1) and srpm-cleanup(1) in order to save space on the remote hosts. Note, that --cleanup is incompatible with --selfie, so the scripts have to be copied to the hosts beforehand (see also Tools).

### Tools

- HSH_SEPARATE_SOURCES: Sets the path to the hsh-separate-sources(1) script on all remote hosts (no customization yet).

- SRPM_CLEANUP: Sets the path to the srpm-cleanup(1) script on all remote hosts (no customization yet).

The default is to use the script from the current directory, then --- the script in PATH.

- COMMON_OPTS: The set of common options to pass to the tools.

- BUILD_COMMON_OPTS: The set of common options passed to hsh-separate-sources(1).

- CLEAN_COMMON_OPTS: The set of common options passed to srpm-cleanup(1).

Don´t override the common options by accident as their default values contain important things about the remote options described above.

### Log options

- LOG_SUF: Defines a suffix to use for stage log file names. Using the same stage log file name prevents from running multiple jobs for the same stage (for instace, retries with different options --- see Stage retries) simultaneously. That´s become possible if a different log filename suffix is used with each job. If INDEP_LOGS is set, i.e. not empty (the default) then random suffixes are used.

- INDEP_LOGS: Controls if random LOG_SUF values should be used for each stage run. The flag is set by default (a non empty value).

- BACKUP_LOGS: Set to a non-empty value to disable independent logs and enable making backups of the stage log file on each next stage run (including stage retries). Setting BACKUP_LOGS to a non-empty value prevents from running multiple jobs for the same stage simultaneously.

### Configuring Stage I

- SKIPLIST_DIR: Directory to write the list of unused packages for each processed source package. The default is skip.

- INCLIST_DIR: Directory to write the list of used packages for each processed source package. The default is inc.

- STAGE1_LOG: Log file for Stage I. The default is logs/stage1.log.

- STAGE1_LOGDIR: Directory for Stage I package build logs. The default is logs/stage1.logs.

- STAGE1_STATUS: Status file for Stage I. The default is stage1.status.

### Configuring Stage II

- TAR_DIR: Directory to output TAR packages to. The default is pkgs.

- STAGE2_LOG: Log file for Stage II. The default is logs/stage2.log.

- STAGE2_LOGDIR: Directory for Stage II package build logs. The default is logs/stage2.logs.

- STAGE2_STATUS: Status file for Stage II. The default is stage2.status.

- EXCEPTIONS: A file with the list of exception paths for srpm-cleanup(1) (-x|--exceptions). The default is exceptions.list. The list is also used with Stage IV.

### Configuring Stage III

- SRPM_DIR: Directory to output SRPM packages to. The default is out.

- STAGE3_LOG: Log file for Stage III. The default is logs/stage3.log.

- STAGE3_LOGDIR: Directory for Stage III package build logs. The default is logs/stage3.logs.

- STAGE3_STATUS: Status file for Stage III. The default is stage3.status.

### Configuring Stage IV

- RPM_DIR: Directory to output the resulting RPM packages to. The default is rpms.

- STAGE4_LOG: Log file for Stage IV. The default is logs/stage4.log.

- STAGE4_LOGDIR: Directory for Stage IV package build logs. The default is logs/stage4.logs.

- STAGE4_STATUS: Status file for Stage IV. The default is stage4.status.

- TOOLERANCE: SRPM cleanup verification toolerance, %. The default is 0%.

If EXCEPTIONS (see above) is defined, the name of the file is passed to hsh-separate-sources(1) with -x|--exceptions).

- REPO_DIR: Path to the reference package repository (on the local host). The value is also used by add-builder and add-cleaner targets as the default package repository path. See also show-repo-dir and set-repo-dir targets.

- BIN_LIST: Path to the bin.list file in the reference repository on the local host. The default is $(REPO_DIR)/files/list/bin.list.

- DISTTAG_INDEX: The name of the dist-tag index file. The dist-tag index depends on the BIN_LIST and is updated automatically. The default is disttag.index.

- DISTTAG_OPTS: Options to pass to hsh-separate-sources in order to enable dist-tags. The default is --disttag-index="$(DISTTAG_INDEX)".

- CUSTOM_TAGS: A file with a list of tab-separated pairs of package-version-release and custom dist-tag values.

### Configuring Stage V

- REBUILD_OPTS: Additional options to pass to hsh-separate-sources on Stage V. For example, the --with-pre and --with-post options. There is no default value for this option.

- REBUILD_V_DIR: Directory to write the verified, cleaned-up RPM packages to. The default is rebuild.v.

- STAGE5_V_LOG: Log file for Stage V/1. The default is logs/stage5.v.log.

- STAGE5_V_LOGDIR: Directory for Stage V/1 package build logs. The default is logs/stage5.v.logs.

- STAGE5_V_STATUS: Status file for Stage V/1. The default is stage5.v.status.

- STAGE5_V_EXCLUDE_LIST: Name of the file with a list of package base names (no version and release) be excluded packages from Stage V/1. The listed packages are included in Stage V/2 even if they have sucessfully passed Stage IV. The default name is exclude.list.

- REBUILD_O_DIR: Directory to write the RPM packages resulted from rebuilding of the original SRPM packages, typically --- the packages that failed on Stage IV. The default is rebuild.o.

- STAGE5_O_LOG: Log file for Stage V/2. The default is logs/stage5.o.log.

- STAGE5_O_LOGDIR: Directory for Stage V/2 package build logs. The default is logs/stage5.o.logs.

- STAGE5_O_STATUS: Status file for Stage V/2. The default is stage5.o.status.

### Runtime options

- OPTS: Any command line options to pass to a tool corresponding to the stage.

- FOR_ARCHES: Run the stage (I, IV-V) on the hosts of the specified architectures only. The architectures can be listed separated by spaces or commas.

- PKGS: List of packages to rebuild (stageN-retry-pkgs targets only).

- LIMIT: Limit the work plan by LIMIT packages (see the --limit option in hsh-separate-sources(1) and srpm-cleanup(1)).

- SLOTS: Overrides the builder-specific slots value.

- NPROCS: Overrides the builder-specific nprocs (nprofile) value.

## SEE ALSO
hsh-separate-sources(1), hasher(1), gear(1), hsh(1).

## COPYRIGHT
Copyright (C) 2020 BaseALT /basealt.ru/. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## AUTHOR

- Anton V. Boyarshinov boyarsh@altlinux.org

- Michael Shigorin mike@altlinux.org

- Paul Wolneykien manowar@altlinux.org

## REPORTING BUGS
Report bugs to https://bugzilla.altlinux.org/.


sshguard-setup

package: sshguard

title: sshguard-setup(7)

summary: setting up SSHGuard on your system

text:
# sshguard-setup(7)

## Name
sshguard-setup - setting up SSHGuard on your system

## DESCRIPTION
To set up SSHGuard, write sshguard.conf and set up the backend, if necessary. Configuration options are documented in the sample configuration file. A good starting point is to copy it and make the necessary changes:

1.

Set BACKEND. You may also need to set it up to work with SSHGuard (see BACKENDS).

2.

Set FILES, LOGREADER, or both. Alternatively, give sshguard a list of files to monitor as positional arguments on the command-line.

Use FILES to specify a space-separated list of log files to monitor. Use LOGREADER to specify a shell command to run to obtain logs. Both settings are ignored if files are given on the command-line.

Sample LOGREADER commands for journalctl(1) and macOS 10.12+ are available in the sample configuration.

## OTHER LOGS

### syslog-ng
For syslog-ng 2.x, add the following lines to syslog-ng.conf:

```
# pass only entries with auth+authpriv facilities from programs other than sshguard
filter sshlogs { facility(auth, authpriv) and not match("sshguard"); };
# pass to this process with this template (avoids <ID> prefixes)
destination sshguardproc {
program("/usr/local/sbin/sshguard"
template("$DATE $FULLHOST $MESSAGE\n"));
};
log { source(src); filter(sshlogs); destination(sshguardproc); };
```

For syslog-ng 3.x, add the following lines to syslog-ng.conf:

```
# enable 3.x mode
@version:3.0
# pass only entries with auth+authpriv facilities from programs other than sshguard
filter f_sshguard { facility(auth, authpriv) and not program("sshguard"); };
# pass entries built with this format
destination sshguard {
program("/usr/sbin/sshguard"
template("$DATE $FULLHOST $MSGHDR$MESSAGE\n")
);
};
log { source(src); filter(f_sshguard); destination(sshguard); };
```

After restarting syslog-ng, SSHGuard should start as soon as a log entry with facility auth or authpriv arrives. If you are monitoring services other than sshd, add the appropriate log facilities to syslog-ng.conf.

### metalog
Add the following lines to metalog.conf:

```
Stuff to protect from brute force attacks :

    # for ssh

    facility = "*"

    program = "sshd"

    # other services ...

    # log to /var/log/sshguard directory

    logdir = "/var/log/sshguard"
```

After restarting metalog, log entries will appear in /var/log/sshguard. Use log polling to monitor the current log.

## BACKENDS
SSHGuard can block attackers using one of several firewall backends that is selected at compile-time.

Warning:

Read the documentation for your firewall. Make sure you fully understand each rule or command in the examples below before using them. They may need to be adjusted to suit your particular configuration.

### pf
SSHGuard adds attackers to table <sshguard>. Create the table and block attackers by adding the following lines to the end of pf.conf:

```
table <sshguard> persist
block in proto tcp from <sshguard>
```

After reloading the pf configuration, you can inspect the contents of the table using:

```
# pfctl -t sshguard -T show
```

### ipfw
SSHGuard creates and adds attackers to table 22. The table can be used to block attackers in your ruleset. For example:

```
# ipfw add 5000 reset ip from table\(22\) to me
```

You can inspect the contents of the table using:

```
# ipfw table 22 list
```

### firewalld
Blocked attackers are added to two ipsets named sshguard4 and sshguard6. The entries in the ipsets are blocked by default in the default firewall zone. Additional firewall zones can be configured using:

```
# firewall-cmd --zone=zone-name --permanent \

    --add-rich-rule="rule source ipset=sshguard4 drop"
# firewall-cmd --zone=zone-name --permanent \

    --add-rich-rule="rule source ipset=sshguard6 drop"
```

You can inspect the entries in the two ipsets using:

```
# firewall-cmd --permanent --info-ipset=sshguard4
# firewall-cmd --permanent --info-ipset=sshguard6
```

### ipset
Blocked attackers are added to two ipsets named sshguard4 and sshguard6. Nothing is blocked by default, but can used as a source for iptables and other tools. E.g.:

```
# iptables  -I INPUT -m set --match-set sshguard4 src -j DROP
# ip6tables -I INPUT -m set --match-set sshguard6 src -j DROP
```

### netfilter/iptables
Create a chain for SSHGuard:

```
# iptables -N sshguard      # for IPv4
# ip6tables -N sshguard     # for IPv6
```

Update the INPUT chain to also pass the traffic to the sshguard chain at the very end of its processing. Specify in --dport all the ports of services your sshguard protects. If you want to prevent attackers from doing any traffic to the host, remove the option completely:

```
# block any traffic from abusers
iptables -A INPUT -j sshguard
ip6tables -A INPUT -j sshguard
```

Or:

```
# block abusers only for SSH, FTP, POP, IMAP services (use "multiport" module)
iptables -A INPUT -m multiport -p tcp --destination-ports 21,22,110,143 -j sshguard
ip6tables -A INPUT -m multiport -p tcp --destination-ports 21,22,110,143 -j sshguard
```

Verify that you have NOT a default allow rule passing all ssh traffic higher in the chain. Verify that you have NOT a default deny rule blocking all ssh traffic in your firewall. In either case, you already have the skill to adjust your firewall setup.

Here is a sample ruleset that makes sense:

```
iptables -N sshguard
# block whatever SSHGuard says be bad ...
iptables -A INPUT -j sshguard
# enable ssh, dns, http, https
iptables -A INPUT -p tcp --dport 22 -j ACCEPT
iptables -A INPUT -p udp --dport 53 -j ACCEPT
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT
# and block everything else (default deny)
iptables -P INPUT DROP
```

When rebooting, most systems reset the firewall configuration by default. To preserve your configuration, you usually use the iptables-save and iptables-restore utilities. However, each Linux variant has its own "right way".

### nftables
SSHGuard creates tables with a high priority and adds attackers to a set automatically.

You can inspect the contents of the sets using:

```
# nft list set ip sshguard attackers
# nft list set ip6 sshguard attackers
```

Moreover, you can display sshguard's tables with:

```
# nft list table ip sshguard
# nft list table ip6 sshguard
```

## TROUBLESHOOTING

### Is SSHGuard configured correctly?
Check that the correct FILES (or LOGREADER) and BACKEND are set in sshguard.conf.

### Is SSHGuard running?
SSHGuard spawns a pipeline of cooperating processes. You can verify that SSHGuard is started correctly by viewing your process list using ps or top. Shown here are the processes associated with an example configuration:

```
/bin/sh /opt/sshguard/sbin/sshguard
tail -F -n 0 /tmp/log.txt
/opt/sshguard/libexec/sshg-parser
/opt/sshguard/libexec/sshg-blocker -a 30 -p 120 -s 1800 -N 128 -n 32
/bin/sh /usr/local/libexec/sshg-fw-null
```

In order:

- SSHGuard, installed in /opt/sshguard, is being interpreted by /bin/sh.

- SSHGuard launched tail -F -n 0, which is monitoring /tmp/log.txt.

- The default parser sshg-parser is running.

- The blocker is running with options -a 30 -p 120 -s 1800 -N 128 -n 32.

- The firewall sshg-fw-null is running. The null backend doesn't actually block any attacks.

### Is SSHGuard recognizing attacks?
SSHGuard recognizes attacks by parsing log messages. The format of log messages can occasionally change. If you are using the default, built-in attack parser, you can check if SSHGuard recognizes your attacks by running:

```
$ cat /var/log/auth.log | %PREFIX%/libexec/sshg-parser -a
```

Log messages that are recognized as attacks are prefixed with a '*' at the beginning of each line. If a log message that should be recognized as an attack is not, consider reporting it.

## EXAMPLES
Ignore FILES and monitor these files instead:

```
# sshguard /var/log/auth.log /var/log/maillog
```

## SEE ALSO
sshguard(8)

branch: sisyphus


svgalib

package: svgalib

title: svgalib(7)

summary: a low level graphics library for linux

text:
# svgalib(7)

## NAME
svgalib - a low level graphics library for linux

## TABLE OF CONTENTS
0. Introduction

1. Installation

2. How to use svgalib

3. Description of svgalib functions

4. Overview of supported SVGA chipsets and modes

5. Detailed comments on certain device drivers

6. Goals

7. References (location of latest version, apps etc.)

8. Known bugs

## 0. INTRODUCTION
This is a low level graphics library for Linux, originally based on VGAlib 1.2 by Tommy Frandsen. VGAlib supported a number of standard VGA graphics modes, as well as Tseng ET4000 high resolution 256-color modes. As of now, support for many more chipsets has been added. See section 4 Overview of supported SVGA chipsets and modes

It supports transparent virtual console switching, that is, you can switch consoles to and from text and graphics mode consoles using alt-[function key]. Also, svgalib corrects most of VGAlib's textmode corruption behaviour by catching SIGSEGV, SIGFPE, SIGILL, and other fatal signals and ensuring that a program is running in the currently visible virtual console before setting a graphics mode.

Note right here that SIGUSR1 and SIGUSR2 are used to manage console switching internally in svgalib. You can not use them in your programs. If your program needs to use one of those signals, svgalib can be compiled to use other signals, by editing libvga.h

This version includes code to hunt for a free virtual console on its own in case you are not starting the program from one (but instead over a network or modem login, from within screen(1) or an xterm(1)). Provided there is a free console, this succeeds if you are root or if the svgalib calling user own the current console. This is to avoid people not using the console being able to fiddle with it. On graceful exit the program returns to the console from which it was started. Otherwise it remains in text mode at the VC which svgalib allocated to allow you to see any error messages. In any case, any I/O the svgalib makes in text mode (after calling vga_init(3)) will also take place at this new console.

Alas, some games misuse their suid root privilege and run as full root process. svgalib cannot detect this and allows Joe Blow User to open a new VC on the console. If this annoys you, ROOT_VC_SHORTCUT in Makefile.cfg allows you to disable allocating a new VC for root (except when he owns the current console) when you compile svgalib. This is the default.

When the library is used by a program at run-time, first the chipset is detected and the appropriate driver is used. This means that a graphics program will work on any card that is supported by svgalib, if the mode it uses is supported by the chipset driver for that card. The library is upwardly compatible with VGAlib.

The set of drawing functions provided by svgalib itself is limited (unchanged from VGAlib) and unoptimized; you can however use vga_setpage(3) and vga_getgraphmem(3) (which points to the 64K VGA framebuffer) in a program or graphics library. A fast external framebuffer graphics library for linear and banked 1, 2, 3 and 4 bytes per pixel modes is included (it also indirectly supports planar VGA modes). It is documented in vgagl(7).

One obvious application of the library is a picture viewer. Several are available, along with animation viewers. See the 7. References at the end of this document.

I have added a simple VGA textmode font restoration utility (restorefont(1)) which may help if you suffer from XFree86 textmode font corruption. It can also be used to change the textmode font. It comes with some other textmode utilities: restoretextmode(1) (which saves/restores textmode registers), restorepalette(1), and the script textmode(1). If you run the savetextmode(1) script to save textmode information to /var/lib/svgalib, you'll be able to restore textmode by running the textmode(1) script.

## 1. INSTALLATION
Installation is easy in general but there are many options and things you should keep in mind. This document however assumes that svgalib is already installed.

If you need information on installation see 0-INSTALL which comes with the svgalib distribution.

However, even after installation of the library you might need to configure svgalib using the file /etc/vga/libvga.config. Checkout section 4 Overview of supported SVGA chipsets and modes and libvga.config(5) for information.

## 2. HOW TO USE SVGALIB
For basic svgalib usage (no mouse, no raw keyboard) add #include <vga.h> at the beginning your program. Use vga_init(3) as your first svgalib call. This will give up root privileges right after initialization, making setuid-root binaries relatively safe.

The function vga_getdefaultmode(3) checks the environment variable SVGALIB_DEFAULT_MODE for a default mode, and returns the corresponding mode number. The environment string can either be a mode number or a mode name as in (G640x480x2, G640x480x16, G640x480x256 , G640x480x32K, G640x480x64K, G640x480x16M). As an example, to set the default graphics mode to 640x480, 256 colors, use:

export SVGALIB_DEFAULT_MODE=G640x480x256

on the bash(1) command line. If a program needs just a linear VGA/SVGA resolution (as required by vgagl(7)), only modes where bytesperpixel in the vga_modeinfo structure returned by vga_getmodeinfo(3) is greater or equal to 1 should be accepted (this is 0 for tweaked planar 256-color VGA modes).

Use vga_setmode(graphicsmode) to set a graphics mode. Use vga_setmode(TEXT) to restore textmode before program exit.

Programs that use svgalib must #include<vga.h>; if they also use the external graphics library vgagl(7), you must also #include<vgagl.h>. Linking must be done with -lvga (and -lvgagl before -lvga, if vgagl(7) is used). You can save binary space by removing the unused chipset drivers in Makefile.cfg if you only use specific chipsets. However this reduces the flexibility of svgalib and has a significant effect only when you use the static libraries. You should better use the shared libraries and these will load only the really used parts anyway.

Functions in the vgagl(7) library have the prefix gl_. Please see vgagl(7) for details.

There are demos with sources available which will also help to get you started, in recomended order of interest: vgatest(6), keytest(6), mousetest(6), eventtest(6), forktest(6), bg_test(6), scrolltest(6), speedtest(6), fun(6), spin(6), testlinear(6), lineart(6), testgl(6), accel(6), testaccel(6), plane(6), and wrapdemo(6).

Debugging your programs will turn out to be rather difficult, because the svgalib application can not restore textmode when it returns to the debugger.

Happy are the users with a serial terminal, X-station, or another way to log into the machine from network. These can use

textmode </dev/ttyN

on the console where the program runs and continue.

However, the vga_flip(3) function allows you to switch to textmode by entering a call to it blindly into your debugger when your program stops in graphics mode. vga_flip(3) is not very robust though. You shall not call it when svgalib is not yet initialized or in textmode.

Before continuing your program, you must then call vga_flip(3) again to return to graphics mode. If the program will not make any screen accesses or svgalib calls before it returns to the debugger, you can omit that, of course.

This will only work if your program and the debugger run in the same virtual linux console.

## 3. DESCRIPTION OF SVGALIB FUNCTIONS
Each function has it's own section 3 manual page. For a list of vgagl functions see vgagl(7).

### Initialization
vga_init(3)

- initialize svgalib library.

vga_disabledriverreport(3)

- makes svgalib not emit any startup messages.

vga_claimvideomemory(3)

- declare the amount of video memory used.

vga_safety_fork(3)

- start a parallel process to restore the console at a crash.

vga_setchipset(3)

- force chipset.

vga_setchipsetandfeatures(3)

- force chipset and optional parameters.

### Inquire hardware configuration
vga_getmousetype(3)

- returns the mouse type configured.

vga_getcurrentchipset(3)

- returns the current SVGA chipset.

vga_getmonitortype(3)

- returns the monitor type configured.

### Setting video modes
vga_setmode(3)

- sets a video mode.

vga_setdisplaystart(3)

- set the display start address.

vga_setlogicalwidth(3)

- set the logical scanline width.

vga_setlinearaddressing(3)

- switch to linear addressing mode.

vga_setmodeX(3)

- try to set Mode X-like memory organization .

vga_ext_set(3)

- set and query several extended features.

vga_screenoff(3), vga_screenon(3)

- turn generation of the video signal on or off.

### Get video mode information
vga_getxdim(3), vga_getydim(3), vga_getcolors(3)

- return the current screen resolution.

vga_white(3)

- return the color white in the current screen resolution.

vga_getcurrentmode(3)

- returns the current video mode.

vga_hasmode(3)

- returns if a video mode is supported.

vga_getmodeinfo(3)

- returns pointer to mode information structure for a mode.

vga_getdefaultmode(3)

- returns the default graphics mode number.

vga_lastmodenumber(3)

- returns the last video mode number.

vga_getmodename(3)

- return a name for the given video mode.

vga_getmodenumber(3)

- return a number for the given video mode.

### Drawing primitives
vga_clear(3)

- clear the screen.

vga_setcolor(3)

- set the current color.

vga_setrgbcolor(3)

- set the current color.

vga_setegacolor(3)

- set the current color.

vga_drawpixel(3)

- draw a pixel on the screen.

vga_drawscanline(3)

- draw a horizontal line of pixels.

vga_drawscansegment(3)

- draw a horizontal line of pixels.

vga_drawline(3)

- draw a line on the screen.

vga_getpixel(3)

- get a pixels value from the screen.

vga_getscansegment(3)

- get a list of consecutive pixel values.

vga_waitretrace(3)

- wait for vertical retrace.

### Basic (non raw) keyboard I/O
vga_getch(3)

- wait for a key.

vga_getkey(3)

- read a character from the keyboard without waiting.

vga_waitevent(3)

- wait for various I/O events.

### Direct VGA memory access
vga_setpage(3)

- set the 64K SVGA page number.

vga_setreadpage(3)

- set the 64K SVGA page number.

vga_setwritepage(3)

- set the 64K SVGA page number.

vga_getgraphmem(3)

- returns the address of the VGA memory.

vga_copytoplanar256(3)

- copy linear pixmap into Mode X video memory.

vga_copytoplanar16(3)

- copy linear pixmap into VGA 16 color mode video memory.

vga_copytoplane(3)

- copy linear pixmap to some planes of VGA 16 color mode video memory.

### Manage color lookup tables
vga_setpalette(3)

- set a color in the color lookup table.

vga_getpalette(3)

- get a color in the color lookup table.

vga_setpalvec(3)

- sets colors in the color lookup table.

vga_getpalvec(3)

- gets colors from the color lookup table.

### Mouse handling
vga_setmousesupport(3)

- enable mouse support.

mouse_init(3), mouse_init_return_fd(3)

- specifically initialize a mouse.

mouse_close(3)

- explicitly close a mouse.

mouse_update(3)

- updates the mouse state.

mouse_waitforupdate(3)

- wait for an mouse update.

mouse_setscale(3)

- sets a mouse scale factor.

mouse_setwrap(3)

- set what happens at the mouse boundaries.

mouse_setxrange(3), mouse_setyrange(3)

- define the boundaries for the mouse cursor.

mouse_getx(3), mouse_gety(3), mouse_getbutton(3)

- query the mouse state.

mouse_setposition(3)

- set the current mouse position.

mouse_getposition_6d(3), mouse_setposition_6d(3), mouse_setrange_6d(3)

- provide an interface to 3d mice.

mouse_seteventhandler(3), mouse_setdefaulteventhandler(3)

- set a mouse event handler.

### Raw keyboard handling
keyboard_init(3), keyboard_init_return_fd(3)

- initialize the keyboard to raw mode.

keyboard_close(3)

- return the keyboard to normal operation from raw mode.

keyboard_update(3), keyboard_waitforupdate(3)

- process raw keyboard events.

keyboard_translatekeys(3)

- modify scancode mappings in raw keyboard mode.

keyboard_keypressed(3)

- check if a key is pressed when in raw keyboard mode.

keyboard_getstate(3)

- get a pointer to a buffer holding the state of all keys in raw keyboard mode.

keyboard_clearstate(3)

- reset the state of all keys when in raw keyboard mode.

keyboard_seteventhandler(3), keyboard_setdefaulteventhandler(3)

- define an event handler for keyboard events in raw mode.

### Joystick handling
joystick_init(3)

- initialize and calibrate joysticks.

joystick_close(3)

- close a joystick device.

joystick_update(3)

- query and process joystick state changes.

joystick_sethandler(3), joystick_setdefaulthandler(3)

- define own joystick even handler.

joystick_getnumaxes(3), joystick_getnumbuttons(3)

- query the capabilities of a joystick.

joystick_getaxis(3), joystick_getbutton(3)

- query the state of a joystick.

joystick_button1|2|3|4(3), joystick_getb1|2|3|4(3), joystick_x|y|z(3), joystick_getx|y|z(3)

- convenience macros to query the joystick position.

### Accelerator interface (new style)
vga_accel(3)

- calls the graphics accelerator.

### Accelerator interface (old style)
vga_bitblt(3)

- copy pixmap on screen using an accelerator.

vga_fillblt(3)

- fill rectangular area in video memory with a single color.

vga_hlinelistblt(3)

- draw horizontal scan lines.

vga_imageblt(3)

- copy a rectangular pixmap from system memory to video memory.

vga_blitwait(3)

- wait for any accelerator operation to finish.

### Controlling VC switches
vga_lockvc(3)

- disables virtual console switching for safety.

vga_unlockvc(3)

- re-enables virtual console switching.

vga_oktowrite(3)

- indicates whether the program has direct access to the SVGA.

vga_runinbackground(3)

- enable running of the program while there is no VGA access.

vga_runinbackground_version(3)

- returns the version of the current background support.

### Debugging aids
vga_dumpregs(3)

- dump the contents of the SVGA registers.

vga_gettextfont(3), vga_puttextfont(3)

- get/set the font used in text mode.

vga_gettextmoderegs(3), vga_settextmoderegs(3)

- get/set the vga state used in text mode.

vga_flip(3)

- toggle between text and graphics mode.

vga_setflipchar(3)

- set the character causing a vga_flip().

## 4. OVERVIEW OF SUPPORTED SVGA CHIPSETS AND MODES

### VGA and compatibles
320x200x256, and the series of 16-color and non-standard planar 256 color modes supported by VGAlib, as well as 720x348x2.

### ALI2301
Supports 640x480x256, 800x600x256, 1024x768x256 SVGA modes

### AT3D (AT25)
Also known as Promotion at25. Popular as the 2D part of a voodoo rush card. As of this writing there are a few known problems with this driver. Read below.

### ARK Logic ARK1000PV/2000PV
Full support, limited RAMDAC support. Only ARK1000PV tested. Supports Clocks and Ramdac lines in config file.

### ATI SVGA (VGA Wonder and friends)
This is no real driver. I do not support any new modes. However it saves additional card setup and thus allows use of the plain VGA modes even when you are using non standard text modes. It is possible to enforce use of this driver even on ATI Mach32 but not very useful.

### ATI Mach32
The driver by Michael Weller supports all ATI BIOS-defined modes and more... It hits the best out of your card. Some modes may not have nice default timings but it uses the ATI's EEPROM for custom config or allows to specify modes in libvga.config(5). Some problems may occur with quite some third party cards (usually on board) Mach32 based controllers as they do not completely conform to the Mach32 data sheets. Check out svgalib.mach32(7) (and libvga.config(5)).

### ATI Mach64 (rage)
A driver for ATi Mach64 based cards with internal DAC.

### Chips and Technologies chipsets 65525, 65535, 65546, 65548, 65550, and 65554 (usually in laptops).
This server was written using the SVGALIB patch from Sergio and Angelo Masci as a starting point. This version of the code resembled the XFree server code that was used up to XFree 3.1.2. As such it was incapable of programming the clocks, using linear addressing, Hi-Color, True-Color modes or the hardware acceleration. All of these features have since been added to the code. The 64200 and 64300 chips are unsupported, however these chips are very similar to the 6554x chips which are supported.

### Cirrus Logic GD542x/3x
All the modes, including 256 color, 32K/64K color, 16M color (3 bytes per pixel) and 32-bit pixel 16M color modes (5434). Some bitblt functions are supported. The driver doesn't work with mode dumps, but uses a SVGA abstraction with mode timings like the X drivers.

### Genoa(?) GVGA6400 cards.
Supported.

### Hercules Stingray 64/Video
Is supported as an ARK2000PV

### NV3 driver for the Riva128.
This driver was written by Matan Ziv-Av and is derived from the XFree86 driver by David J. Mckay. It lacks 24bit modes (can the card do them at all?), acceleration support and pageflipping in threeDKit is broken.

### Oak Technologies OTI-037/67/77/87
Driver by Christopher Wiles; includes 32K color modes for OTI-087.

### S3
The driver is not complete, but should work on a number of cards/RAMDACs, and 640x480x256 should work on most card. The best support is for a 801/805 with AT&T20C490-compatible RAMDAC, and S3-864 + SDAC. All 256/32K/64K/16M works for them (within the bounds of video memory & ramdac restrictions).

The supported cards include S3 Virge and S3 Trio64 cards.

None of the acceleration function is supported yet.

The chip level code should work with the 964/868/968, but most likely the card they come on would use an unsupported ramdac/clock chip. Support for these chips is slowly being added.

Clocks and Ramdac lines in libvga.config(5) supported.

The maximum pixel clock (in MHz) of the ramdac can be set using a Dacspeed line in the config file. A reasonable default is assumed if the Dacspeed line is omitted. Clocks should be the same as in XFree86. Supported ramdac IDs: Sierra32K, SC15025, SDAC, GenDAC, ATT20C490, ATT20C498, IBMRGB52x.

Example:

Clocks 25.175 28.3 40 70 50 75 36 44.9 0 118 77 31.5 110 65 72 93.5

Ramdac att20c490

DacSpeed 85

Also supported, at least in combination with the SC15025/26A ramdac, is the ICD 2061A clock chip. Since it cannot be autodetected you need to define it in the config file using a Clockchip line. As there is no way to read the current settings out of the 2061, you have the option to specify the frequency used when switching back to text mode as second argument in the Clockchip line.

This is especially required if your text mode is an 132 column mode, since these modes use a clock from the clock chip, while 80 column modes use a fixed clock of 25 MHz. The text mode frequency defaults to 40 MHz, if omitted.

Example:

ClockChip icd2061a 40.0

### Trident TVGA 8900C/9000 (and possibly also 8800CS/8900A/B) and also TVGA 9440
Derived from tvgalib by Toomas Losin. TVGA 9440 support by ARK <ark@lhq.com, root@ark.dyn.ml.or>.

Supports 640x480x256, 800x600x256, 1024x768x256 (interlaced and non-interlaced) Might be useful to add 16-color modes (for those equipped with a 512K TVGA9000) for the 8900 and 9000 cards.

320x200x{32K, 64K, 16M}, 640x480x{256, 32K, 64K, 16M}, 800x600x{256, 32K, 64K, 16M}, 1024x768x{16, 256}, 800x600x{16, 256, 32K, 64K} modes are supported for the TVGA 9440.

Autodetection can be forced with a:

chipset TVGA memory flags

line in the config file.

memory is the amount of VGA memory in KB, flags is composed of three bits:

bit2 = false, bit1 = false

force 8900.

bit2 = false, bit1 = true

force 9440.

bit2 = true, bit1 = false

force 9680.

bit0 = true

force noninterlaced.

bit0 = false

force interlaced which only matters on 8900's with at least 1M since there is no 512K interlaced mode on the 8900 or any of the other cards.

### Tseng ET4000/ET4000W32(i/p)
Derived from VGAlib; not the same register values. ET4000 register values are not compatible; see svgalib.et4000(7).

Make sure the colors are right in hicolor mode; the vgatest program should draw the same color bars for 256 and hicolor modes (the DAC type is defined at compilation in et4000.regs or the dynamic registers file). ET4000/W32 based cards usually have an AT&T or Sierra 15025/6 DAC. With recent W32p based cards, you might have some luck with the AT&T DAC type. If the high resolution modes don't work, you can try dumping the registers in DOS using the program in the et4000/ directory and putting them in a file (/etc/vga/libvga.et4000 is parsed at runtime if DYNAMIC is defined in Makefile.cfg at compilation (this is default)).

Supported modes are 640x480x256, 800x600x256, 1024x768x256, 640x480x32K, 800x600x32K, 640x480x16M, etc.

Reports of ET4000/W32i/p functionality are welcome.

There may be a problem with the way the hicolor DAC register is handled; dumped registers may use one of two timing methods, with the value written to the register for a particular DAC for a hicolor mode (in vgahico.c) being correct for just one of the these methods. As a consequence some dumped resolutions may work while others don't.

### Tseng ET6000
Most modes of which the card is capable are supported. The 8 15 16 24 and 32 bit modes are supported.

The ET6000 has a built in DAC and there is no problem coming from that area. The ET6000 is capable of acceleration, but this as well as sprites are not yet implemented in the driver.

The driver now uses modelines in libvga.config for user defined modes. It is sometimes useful to add a modeline for a resolution which does not display well. For example, the G400x600 is too far to the right of the screen using standard modes. This is corrected by including in libvga.config the line

Modeline "400x600@72" 25.000 400 440 488 520 600 639 644 666

More examples are given below.

This driver was provided by Don Secrest.

### VESA
Please read README.vesa and README.lrmi in doc subdirectory of the standard distribution.

Go figure! I turned off autodetection in the release, as a broken bios will be called too, maybe crashing the machine. Enforce VESA mode by putting a chipset VESA in the end of your libvga.config(5).

Note that it will leave protected mode and call the cards bios opening the door to many hazards.

## 5. DETAILED COMMENTS ON CERTAIN DEVICE DRIVERS
This section contains detailed information by the authors on certain chipsets.

### AT3D (AT25)
Also known as Promotion at25. Popular as the 2D part of a voodoo rush card.

I have written a driver for this chipset, based on the XF86 driver for this chipset.

The programs that work with this driver include all the programs in the demos directory, zgv and dvisvga (tmview).

I believe it should be easy to make it work on AT24, AT6422.

### ATI Mach32
Please see svgalib.mach32(7).

### ATI Mach64
The rage.c driver works only on mach64 based cards with internal DAC. The driver might misdetect the base frequency the card uses, so if when setting any svgalib modes the screen blanks, or complains about out of bound freqencies, or the display is unsynced, then try adding the option RageDoubleClock to the config file.

### Chips and Technologies chipsets 65525, 65535, 65546, 65548, 65550, and 65554 (usually in laptops).
Please see svgalib.chips(7).

### Tseng ET4000/ET4000W32(i/p)
Please see svgalib.et4000(7).

### Tseng ET6000
I have only 2 Mbytes of memory on my ET6000 card, so I am not able to get all possible modes running. I haven't even tried to do all of the modes which I am capable of doing, but I am confident that I can manage more modes when I have time. I have enough modes working to make the card useful, so I felt it was worth while to add the driver to svgalib now.

Linear graphics is working on this card, both with and without BACKGROUND enabled, and vga_runinbackground works.

I decided it was best to quit working on more modes and try to get acceleration and sprites working.

My et6000 card is on a PCI bus. The card will run on a vesa bus, but since I don't have one on my machine I couldn't develop vesa bus handling. I quit if the bus is a vesa bus.

I check for an et6000 card, which can be unequivocally identified. The et4000 driver does not properly identify et4000 cards. It thinks the et6000 card is an et4000, but can only run it in vga modes.

I have found the following four modelines to be useful in libvga.config or in ~/.svgalibrc for proper display of some modes.

Modeline "512x384@79" 25.175 512 560 592 640 384 428 436 494

Modeline "400x300@72" 25.000 400 456 472 520 300 319 332 350 DOUBLESCAN

Modeline "512x480@71" 25.175 512 584 600 656 480 500 510 550

Modeline "400x600@72" 25.000 400 440 488 520 600 639 644 666

Don Secrest <secrest@uiuc.edu> Aug 21, 1999

### Oak Technologies OTI-037/67/77/87
First a few comments of me (Michael Weller <eowmob@exp-math.uni-essen.de>):

As of this writing (1.2.8) fixes were made to the oak driver by Frodo Looijaard <frodol@dds.nl> to reenable OTI-067 support. It is unknown right now if they might have broken OTI-087 support. The author of the '87 support Christopher Wiles <wileyc@moscow.com> owns no longer an OTI-087 card and can thus no longer give optimal support to this driver. Thus you might be better off contacting me or Frodo for questions. If you are a knowledgable OTI-087 user and experience problems you are welcome to provide fixes. No user of a OTI-087 is currently known to me, so if you are able to fix problems with the driver please do so (and contact me) as noone else can.

Michael.

Now back to the original Oak information:

The original OTI driver, which supported the OTI-067/77 at 640x480x256, has been augmented with the following features:

1)

Supported resolutions/colors have been expanded to 640x480x32K, 800x600x256/32K, 1024x768x256, and 1280x1024x16.

2)

The OTI-087 (all variants) is now supported. Video memory is correctly recognized.

The driver as it exists now is somewhat schizoid. As the '87 incorporates a completely different set of extended registers, I found it necessary to split its routines from the others. Further, I did not have access to either a '67 or a '77 for testing the new resolutions. If using them causes your monitor/video card to fry, your dog to bite you, and so forth, I warned you. The driver works on my '87, and that's all I guarantee. Period.

Heh. Now, if someone wants to try them out ... let me know if they work.

New from last release:

32K modes now work for 640x480 and 800x600. I found that the Sierra DAC information in VGADOC3.ZIP is, well, wrong. But, then again, the information for the '87 was wrong also.

64K modes do not work. I can't even get Oak's BIOS to enter those modes.

I have included a 1280x1024x16 mode, but I haven't tested it. My monitor can't handle that resolution. According to the documentation, with 2 megs the '87 should be able to do an interlaced 1280x1024x256 ... again, I couldn't get the BIOS to do the mode. I haven't 2 megs anyway, so there it sits.

I have included routines for entering and leaving linear mode. They should work, but they don't. It looks like a pointer to the frame buffer is not being passed to SVGALIB. I've been fighting with this one for a month. If anyone wants to play with this, let me know if it can be make to work. I've got exams that I need to pass.

Tidbit: I pulled the extended register info out of the video BIOS. When the information thus obtained failed to work, I procured the OTI-087 data book. It appears that Oak's video BIOS sets various modes incorrectly (e.g. setting 8-bit color as 4, wrong dot clock frequencies, etc.). Sort of makes me wonder ...

Christopher M. Wiles (a0017097@wsuaix.csc.wsu.edu)

12 September 1994

## 6. GOALS
I think the ability to use a VGA/SVGA graphics resolution in one virtual console, and being able to switch to any other virtual console and back makes a fairly useful implementation of graphics modes in the Linux console.

Programs that use svgalib must be setuid root. I don't know how desirable it is to have this changed; direct port access can hardly be done without. Root privileges can now be given up right after initialization. I noticed some unimplemented stuff in the kernel header files that may be useful, although doing all register I/O via the kernel would incur a significant context-switching overhead. An alternative might be to have a pseudo /dev/vga device that yields the required permissions when opened, the device being readable by programs in group vga.

It is important that textmode is restored properly and reliably; it is fairly reliable at the moment, but fast console switching back and forth between two consoles running graphics can give problems. Wild virtual console switching also sometimes corrupts the contents of the textmode screen buffer (not the textmode registers or font). Also if a program crashes it may write into the area where the saved textmode registers are stored, causing textmode not be restored correctly. It would be a good idea to somehow store this information in a 'safe' area (say a kernel buffer). Note that the vga_safety_fork(3) thing has the same idea.

Currently, programs that are in graphics mode are suspended while not in the current virtual console. Would it be a good idea to let them run in the background, virtualizing framebuffer actions (this should not be too hard for linear banked SVGA modes)? It would be nice to have, say, a raytracer with a real-time display run in the background (although just using a separate real-time viewing program is much more elegant).

Anyone wanting to rewrite it all in a cleaner way (something with loadable kernel modules shouldn't hurt performance with linear framebuffer/vgagl type applications) is encouraged.

Also, if anyone feels really strongly about a low-resource and truecolor supporting graphical window environment with cut-and-paste, I believe it would be surprisingly little work to come up with a simple but very useful client-server system with shmem, the most useful applications being fairly trivial to write (e.g. shell window, bitmap viewer). And many X apps would port trivially.

This is old information, please be sure to read svgalib.faq(7) if you are interested in further goals.

## 7. REFERENCES
The latest version of svgalib can be found on sunsite.unc.edu in /pub/Linux/libs/graphics or tsx-11.mit.edu in /pub/linux/sources/libs as svgalib-X.X.X.tar.gz. As of this writing the latest version is svgalib-1.4.1.tar.gz. There are countless mirrors of these ftp servers in the world. Certainly a server close to you will carry it.

The original VGAlib is on tsx-11.mit.edu, pub/linux/sources/libs/vgalib12.tar.Z. tvgalib-1.0.tar.Z is in the same directory.

SLS has long been distributing an old version of VGAlib. Slackware keeps a fairly up-to-date version of svgalib, but it may be installed in different directories from what svgalib likes to do by default. The current svgalib install tries to remove most of this. It also removes /usr/bin/setmclk and /usr/bin/convfont, which is a security risk if setuid-root. Actually the recent makefiles try to do a really good job to cleanup the mess which some distributions make.

If you want to recompile the a.out shared library, you will need the DLL 'tools' package (found on tsx-11.mit.edu, GCC dir). To make it work with recent ELF compiler's you actually need to hand patch it. You should probably not try to compile it. Compiling the ELF library is deadly simple.

And here is a list of other references which is horribly outdated. There are many more svgalib applications as well as the directories might have changed. However, these will give you a start point and names to hunt for on CD's or in ftp archives.

### Viewers (in /pub/Linux/apps/graphics/viewers on sunsite.unc.edu):
spic

Picture viewer; JPG/PPM/GIF; truecolor; scrolling.

zgv

Full-featured viewer with nice file selector.

see-jpeg

Shows picture as it is being built up.

mpeg-linux

svgalib port of the Berkeley MPEG decoder (mpeg_play); it also includes an X binary.

flip

FLI/FLC player (supports SVGA-resolution).

### Games (in /pub/Linux/games on sunsite.unc.edu):
bdash

B*lderdash clone with sound.

sasteroids

Very smooth arcade asteroids game.

yatzy

Neat mouse controlled dice game.

vga_cardgames

Collection of graphical card games.

vga_gamespack

Connect4, othello and mines.

wt

Free state-of-the-art Doom-like engine.

Maelstrom

A very nice asteroids style game port from Mac.

Koules

A game. (I've no idea what it looks like)

### Docs
In the vga directory of the SIMTEL MSDOS collection, there is a package called vgadoc3 which is a collection of VGA/SVGA register information.

The XFree86 driver sources distributed with the link-kit may be helpful.

### Miscellaneous
There's an alternative RAW-mode keyboard library by Russell Marks for use with svgalib on sunsite.unc.edu.

LIBGRX, the extensive framebuffer library by Csaba Biegl distributed with DJGPP, has been ported to Linux. Contact Hartmut Schirmer (phc27@rz.uni-kiel.d400.de, subject prefix "HARTMUT:"). A more up-to-date port by Daniel Jackson (djackson@icomp.intel.com) is on sunsite.unc.edu.

The vgalib ghostscript device driver sources can be found on sunsite.unc.edu, /pub/Linux/apps/graphics. Ghostscript patches from Slackware: ftp.cdrom.com, /pub/linux/misc. gnuplot patches are on sunsite.unc.edu.

Mitch D'Souza has written font functions that work in 16 color modes and can use VGA textmode (codepage format) fonts; these can be found in his g3fax package in sunsite.unc.edu. These functions may go into a later version of svgalib.

## 8. KNOWN BUGS
This section is most probably outdated, none of these problems are no longer reported.

Using a 132 column textmode may cause graphics modes to fail. Try using something like 80x28.

The console switching doesn't preserve some registers that may be used to draw in planar VGA modes.

Wild console switching can cause the text screen to be corrupted, especially when switching between two graphics consoles.

On ET4000, having run XFree86 may cause high resolution modes to fail (this is more XFree86's fault).

The Trident probing routine in the XFree86 server may cause standard VGA modes to fail after exiting X on a Cirrus. Try putting a 'Chipset' line in your Xconfig to avoid the Trident probe, or use the link kit to build a server without the Trident driver. Saving and restoring the textmode registers with savetextmode/textmode (restoretextmode) should also work. [Note: svgalib now resets the particular extended register, but only if the Cirrus driver is used (i.e. the chipset is not forced to VGA)] [This is fixed in XFree86 v2.1]

Some Paradise VGA cards may not work even in standard VGA modes. Can anyone confirm this?

Piping data into a graphics program has problems. I am not sure why. A pity, since zcatting a 5Mb FLC file into flip on a 4Mb machine would be fun.

The tseng3.exe DOS program include as source in the svgalib distribution doesn't recognize any modes on some ET4000 cards. Also ET4000 cards with a Acumos/Cirrus DAC may only work correctly in 64K color mode.

## FILES
/etc/vga/libvga.config

/etc/vga/libvga.et4000

## SEE ALSO
svgalib.et4000(7), svgalib.chips(7), svgalib.mach32(7), vgagl(7), libvga.config(5), 3d(6), accel(6), bg_test(6), eventtest(6), forktest(6), fun(6), keytest(6), lineart(5), mousetest(6), joytest(6), mjoytest(6), scrolltest(6), speedtest(6), spin(6), testaccel(6), testgl(6), testlinear(6), vgatest(6), plane(6), wrapdemo(6), convfont(1), dumpreg(1), fix132x43(1), restorefont(1), restorepalette(1), restoretextmode(1), runx(1), savetextmode(1), setmclk(1), textmode(1), mach32info(1).

## AUTHOR
There are many authors of svgalib. This page was edited by Michael Weller <eowmob@exp-math.uni-essen.de>. The original documentation and most of svgalib was done by Harm Hanemaayer <H.Hanemaayer@inter.nl.net> though.


svgalib.chips

title: svgalib.chips(7)

text:
# svgalib.chips(7)

## NAME
svgalib.chips - Information for Chips and Technologies Users

## TABLE OF CONTENTS
Information for Chips and Technologies Users

David Bateman <dbateman@eng.uts.edu.au>

23nd May 1997

0. Introduction

1. "libvga.config" options

2. Unsupported Chips and Technologies chipsets

3. Known bugs

## 0. INTRODUCTION
This is the really only my first attempt to get a working fully featured driver for the Chips and Technologies chipset to work with svgalib(7). As such the only machine that I know it will work on is my own. If you use this software then at this point I'm still very interested in hearing from you by e-mail. Include full details of your chipset, amount of videoram and whether you have a VL-Bus or PCI bus machine.

This server was written using the svgalib(7) patch from Sergio and Angelo Masci as a starting point. This version of the code resembled the XFree server code that was used up to XFree 3.1.2. As such it was incapable of programming the clocks, using linear addressing, Hi-Color, True-Color modes or the hardware acceleration. All of these features have since been added to the code. In addition support for the 65525, 65535, 65546, 65548, 65550 and 65554 have been included. The 64200 and 64300 chips are unsupported, however these chips are very similar to the 6554x chips which are supported.

At this point this code is only confirmed to work correctly on a 65545 VL-Bus machine. However as much of the code was stolen from my experiences with writing code for XFree I hope not to have too many problems with other machines. However if you run this code on a 65545/48 PCI machine or a 65550/54 machine then I am particularly interested in hearing of any success or failure stories.

## 1. "libvga.config" OPTIONS
The first thing to note is that the option parser for svgalib(7) is not very robust. Hence if you make some typing mistakes, you can have some very strange effects. I've set out below the libvga.config(5) options that are of particular interest to Chips and Technologies users. Normally this configuration file can be found at /etc/vga/libvga.config.

HorizSync MIN MAX

Often LCD panels has very different specifications for the horizontal sync than CRT's do. Hence often you'll need this option, particularly if you are using the XFree like modelines described below. The two floating point numbers specified will set the minimum and maximum allowed horizontal sync in kHz.

VertRefresh MIN MAX

Similar to the above, but this sets the LCD or CRT's vertical refresh rate in Hz.

modeline 640x480 20.00 640 688 704 776 480 480 481 486

This option allows you to specify XFree like modelines to use in preference to the in built modelines. Often LCD panels will need very different pixel clocks and timings than CRT's. Hence this option allows you to specify these. Note that the LCD panel timings are related to the panel size and not the mode size. Therefore by default the BIOS setting already uploaded into the registers are used by default. See the "UseModeline" option below if you wish to override these.

chipset C&T 5 1024

These option allows the user to specify the chipset to use and the amount of installed memory in kBytes. Currently supported chipsets are

0 65520

1 65525

2 65530

3 65535

4 65540

5 65545

6 65546

7 65548

8 65550

9 65554

TextClockFreq 25.175

One major difference between this code and the previously available support for the Chips and Technologies chipsets is that it supports the use of programmable clocks. Because of the way that the Chips and Technologies chips program the VCO from the registers, there is no way to be sure to recover the previously programmed clock value. Hence the driver assumes that the console clock is 25.175MHz. This will be wrong for many machines. However I have supplied this option to use a different value that might be more suitable for your machine.

nolinear

This option disables the use of the linear framebuffer. This might be useful for machines that have broken linear framebuffers. In lar the linear framebuffer doesn't seem to work with the achines.

linear

Allow, but don't enforce the use of the linear framebuffer. As this is the default anyway, I don't see that this option is much use.

setuplinear 0xC0000000

For VL-Bus machines I expect that the linear framebuffer starting address will be setup correctly. However to get the starting address for PCI machines requires access to the MEMBASE register in the PCI address space. Code to do this doesn't currently exist with svgalib(7), and so I've taken the easy option of just testing a few known PCI starting addresses. For now these are just 0xFE000000, 0xFD000000, 0x41000000 and 0xC0000000. If you have a different starting address then the linear framebuffer will be unusable. You might like to report your starting address to me so that I can include it in the probing code, but till then this option can be used to set up the correct address. This option just forces the given address to be the only one probed. It doesn't force the linear framebuffer to be used.

LCDPanelSize 800 600

For some machines the LCD panel size is incorrectly probed from the registers. This option forces the LCD panel size to be as specified. If you have a black band down one side of your LCD display you might very well need this option. Also if you are using the option "fix_panel_size" in XFree then this option has a similar effect. This option can be used in conjunction with the option "UseModeline" to program all the panel timings using the modeline values. Two machines that are known to need this option are the HP Omnibook 5000CTS and the NEC Versa 4080 800x600 TFT machines.

UseModeline

The flat panel timings are related to the panel size and not the size of the mode specified. For this reason the default behaviour of the svgalib(7) is to use the panel timings already installed in the chip. The user can force the panel timings to be recalculated from the modeline with this option. However the panel size will still be probed. Two machines that are known to need this option are the HP Omnibook 5000CTS and the Prostar 8200. You are advised to check the README.chips that come with XFree for more details.

NoBitBlt

This option disables the use of H/W acceleration. As far as I know the only thing that currently uses the H/W acceleration is libvgagl, so this might not be a problem anyway. However if you see corruption of the graphics on the screen try this option and see if it goes away.

Use18BitBus

For 24bpp on TFT screens, the server assumes that a 24bit bus is being used. This can result in a reddish tint to 24bpp mode for machines that actually have a 18 bit bus. This option, selects an 18 bit TFT bus. Note that using this option with a 24 bit bus machine will similarly discolour the screen. For other depths this option has no effect.

Center ENABLE/DISABLE or Stretch ENABLE/DISABLE

The default behaviour of svgalib(7) is to leave the stretching and centring registers completely alone. However for some machines this might result in poorly placed modes, or modes that don't fill the whole screen. These two options can be used to centre and stretch the mode on the screen. Note that for instance a Center DISABLE might follow a Center ENABLE in the config file. Only the last option takes effect.

## 2. UNSUPPORTED CHIPS AND TECHNOLOGIES CHIPSETS
The 64200 and 64300 chips are unsupported. However by specifying the chipset in your libvga.config as either a

chipset C&T 3 2048

Use 65535 for a 64200 assuming 2M of video ram, or

chipset C&T 7 2048

Use 65548 for a 64300 assuming 2Mb of video ram

then svgalib can be made to give limited support to these chipsets. Note that the paged addressing mode of the 65548 chip and earlier can only address upto 1Mb of video ram. If the additional memory is needed then linear addressing must be used!! Note that support of the 64xxx chips has not been tested at all, and the above is just a suggestion that I believe will work.

## 3. KNOWN BUGS
One persistent and annoying bug is that the text mode stretching on LCD displays is not always restored correctly for 65550 and 65554 machines. This is to do with the manner in which the extended registers are restored and what is being done with the synchronous reset while the registers are restored. As I don't have a 65550 or 65554 machine of my own on which to test this code, I have been unable to fix this problem. In most circumstances an LCD-CRT switch will restore the LCD stretching to the desired state.

David.

## FILES
/etc/vga/libvga.config

## SEE ALSO
svgalib(7), libvga.config(5).

## AUTHOR
of the driver and this documentation is David Bateman <dbateman@eng.uts.edu.au>. However, it was slightly reformatted by Michael Weller <eowmob@exp-math.uni-essen.de>.


title: svgalib.et4000(7)

summary: Information for Tseng ET4000 users

text:
# svgalib.et4000(7)

## NAME
svgalib.et4000, libvga.et4000 - Information for Tseng ET4000 users

## TABLE OF CONTENTS
NOTE: The ET4000 register layout changed stepping from svgalib 0.98 to 0.99. See 8. Problems below first

1. Basics of ET4000 cards

2. How to configure svgalib(7)

3. Creating card dependent register values

4. Defining new modes

5. Redefining standard modes

6. Available examples

7. ET4000/W32 support

8. Problems

9. Using dynamic loading with other cards

## 1. BASICS OF ET4000 CARDS
Basicly all ET4000 cards are equal, some are even more equal ...

The Chipset is well documented (by Tseng Labs and eg. the vgadoc2.zip) and all graphics functions can be used the same way on different cards (including the ET4000/W32 based ones). There are three important points to be kept in mind:

a.)

amount of available, the organisation and timing of video memory

b.)

type and capabilities of the DAC

c.)

available oscillator frequencies

svgalib(7) will check the available video memory during startup. This should work on all DRAM cards. If there are any problems concerning VRAM equipped cards, please tell us about.

By now we found is no reliable way to detect the memory organisation/ timing and the DAC type/capabilities. Most modern card use a frequency synthizier and provide the following pixel frequencies (in MHz):

50.350 56.644 65.0 72.0 80.0 89.8 63.0 75.0

Checking older ET4000 cards we found a wide spread range of available frequencies. Since the video timing is based on the pixel frequency, the required register values are card dependent.

## 2. HOW TO CONFIGURE SVGALIB
svgalib(7) has a somewhat 'standard' registers set that may work with modern ET4000 cards. If svgalib(7) fails on your machine or you have a HiColor dac, you need to configure your svgalib(7).

The svgalib(7) may use hard linked or dynamical linked register values. If you use hard linked values, the binary will be smaller and start up faster but might fail on other machines.

Compiling the svgalib(7) with DYNAMIC defined (see Makefile.cfg) will set up dynamic register loading. Otherwise the value from svgalib/et4000.regs will be hard linked.

The dynamic configuration will be read from /etc/vga/libvga.et4000 which is an ASCII file (see Makefile.cfg for exact naming). If you have a working et4000.regs for your system just copy this file to /etc/vga/libvga.et4000 or link /etc/vga/libvga.et4000 to your svgalib/et4000.regs file.

The actual scanner/parser will handle the following entries:

\#define DAC_TYPE <integer>

Overwrite the DAC detection

\#define <MODE1> <MODE2>

Enable MODE1 using MODE2 registers, eg. 64K modes like 32K modes

\#define <MODE> DISABLE_MODE

do not use MODE (eg. from vgadrv)

char <MODE><strg>[..] = {<integer>, <integer>, ... };

register definition

with

<MODE> ::= 'g'<decimal>x<decimal>x<color><ignored>

<integer> ::= <decimal>|<hex>

<hex> ::= '0x'<hexdigit>{<hexdigit>}

<decimal> ::= ['+'|'-']<digit>{<digit>}

<hexdigit>::= <digit>|'a..f'|'A..F'

<digit> ::= '0..9'

<color> ::= '2'|'16'|'256'|'32k'|'32K'|'64k'|'64K'|'16M'

<strg> ::= <empty>|[(<alpha>|'_'){<digit>|<alpha>|'_'}]

<alpha> ::= 'a..z'|'A..Z'

C style comments will be skipped. See the et4000/ subdirectory of the svgalib distribution for examples.

## 3. CREATING CARD DEPENDENT REGISTER VALUES
You may create a et4000.regs on your own with the tseng3.exe program. This DOS program and its source is included in the svgalib distribution.

Just boot MS-DOS and start

tseng3 et4000.reg

The tseng3.exe will measure the video timing for each available mode. Check the et4000.regs file against your monitor documentation and disable all non conformant modes, eg.

\#define g1024x768x256_regs DISABLE_MODE

/*

static unsigned char g1024x768x256_regs[71] = {

...

};

*/

will disable the 1024x768x256 mode. You mustn't disable the 640x480x256 mode!

Your et4000.regs must define the following symbols (register values or #define ... DISABLE_MODE) for hard linking:

g320x200x32K_regs, g640x400x256_regs, g640x480x256_regs, g640x480x32K_regs, g640x480x16M_regs, g800x600x16_regs, g800x600x256_regs, g800x600x32K_regs, g1024x768x16_regs, g1024x768x256_regs, and g1280x1024x16_regs.

and all 64K modes handled like 32K modes by the driver:

\#define g320x200x64K_regs g320x200x32K_regs

\#define g640x480x64K_regs g640x480x32K_regs

\#define g800x600x64K_regs g800x600x32K_regs

You may omit every unusable mode in /usr/lib/libvga.et4000.

## 4. DEFINING NEW MODES
All standard svgalib(7) modes may be selected by the mode constants defined in #include<vga.h> (eg. G320x200x16). You may define new modes on your own. Just use dynamic register loading and add the register definition of the new mode. Your program may determine the related modenumber by checking the vga_getmodeinfo(1..vga_lastmodenumber()).

Most ET4000 cards provide 640x350 and 640x400 graphics modes. The tseng3.exe generates the related register sets. You may also use dumpreg(1) from an X window to grab you favourite X graphics mode. The X mode normaly isn't usable directly. See cardex.w32 for an example and et4000.c for a brief description of et4000 registers (both files are included in the svgalib distribution).

## 5. REDEFINING STANDARD MODES
Using dynamic register loading you may redefine any standard VGA mode except of TEXT and 640x480x16. Just add the ET4000 specific register set to /etc/vga/et4000.regs.

## 6. AVAILABLE EXAMPLES
In the et4000/ subdir of teh svgalib distribution you'll find some sample register sets:

cardex.w32

Cardex ET4000/W32 card, Music TrueColor DAC

speedstar+

SpeedSTAR PLUS card, Normal DAC

orchid.pdII

Orchid Prodesigner II

## 7. ET4000/W32 SUPPORT
The actual driver seems to be ET4000/W32 compatible. Tell us about any problems (and solutions). If you've got any information about the ET4000/W32 blitter, we would be pleased to receive it.

## 8. PROBLEMS
As mentioned before, the DAC detection isn't very reliable. vgatest(6) should print equal screens in 256 color and HiColor/TrueColor modes. You may have to edit your libvga.et4000 register file by hand to setup the correct DAC.

The tseng3.exe may fail due to incompatible mode numbering. You might use a VESA driver (eg. tlivesa.com from VPIC 6.0) or edit and recompile the tseng3.exe.

Newer ET4000 chipsets (eg. W32 and W32i) allow up to 32 clock frequencies. Two additional register values were added just before the old extened register value. The new registers are CRTC/30h and CRTC/31h. The old register set had 71 values, the new growed to 73. You may update your old register set by hand:

-

run the dumpreg program, remember the first two values from last data line.

-

edit your libvga:

for each mode change the number of register values from 71 to 73

add the values from dumreg output at front of last data line

-

run .BR vgatest (6) to check the new register set

## 9. USING DYNAMIC LOADING WITH OTHER CARDS
The dynamical register loading may be used in other drivers. Since hard linked register values work fine for Cirrus and Trident cards, we didn't include this feature.

## FILES
/etc/vga/libvga.config

/etc/vga/libvga.et4000

## SEE ALSO
svgalib(7), libvga.config(5).

## AUTHOR
This documentation for the ET4000 registers was provided by Hartmut Schirmer. However, it was slightly reformatted by Michael Weller <eowmob@exp-math.uni-essen.de>.


svgalib.faq

title: svgalib.faq(7)

text:
# svgalib.faq(7)

## NAME
svgalib.faq - frequently asked questions about svgalib

## INTRODUCTION
I (Matan Ziv-Av), added/changed some of the answers in this file, so some answers are mine, and some are Michael's.

List of (recently) frequently asked questions about svgalib. Esp. about it's status and future. Please note that as of now all answers are just written by me, Michael Weller <eowmob@exp-math.uni-essen.de>. I'd like this to change. So email your suggestion (best of all: question and the answer).

Also, most questions deal with the status and future and my ideas about it. Necessarily they contain my own private opinions on this. People may disagree and I'm sure I don't have the best ideas about it or may even be completely wrong. I don't want to force anyone to agree with me.

Also, I was asked about MY opinions, so I'm just presenting them here.

## CONTENTS
Q 1)

I want to write some svgalib application. Where is the documentation?

Q 2)

My board is not supported. What now?

Q 3)

I get: You must be the owner of the current console to use svgalib.

Not running in a graphics capable console, and unable to find one.

However, though logged in not directly from the linux console, I am the owner of the console.

Q 4)

Is svgalib dead?

Q 5)

There are so many Xfree drivers, why not just use them.

Q 6)

Why not just use the VGA BIOS?.

Q 7)

What about GGI?

Q 8)

Why not just use X11?

Q 9)

Now, again, what about the future of svgalib?

Q 10)

Ok, just for completeness, what are your plans about svgalib anyway?

Q 11)

Nice plan. But will it become true?

## THE QUESTIONS

### Q 1)
I want to write some svgalib application. Where is the documentation?

### A a)
Well, did you really look at everything? The 0-README file in the top level directory contains all function prototypes and explanations on how to call them.

Yes, the documentation is short and/or confusing. Sorry, English is not my native tongue. Many people complain and want to write some better documentation. You are welcome to do so! However, up to now, either people found the documentation sufficient once they looked at the correct files or they just gave up. At least, I never heard from these people again.

Also, svgalib comes with source. If in doubt: read it.

Finally: Linux distributions include svgalib, but not the source and README's (or hide them so good noone finds them). Well, no problem, get full svgalib source, demos, readme's from svgalib-*.tar.gz on any Linux FTP server in your vicinity. Even if you don't dare to install or compile it, it contains the readme's.

Oh yes, there are some simple demos in the demos/ subdir. They should get you started.

When someone writes man(1) manual pages, a distribution might just install them. Please do not complain, write them, mail them to me.

### A b)
Finally, I, Michael Weller wrote the manpages. Looking at svgalib(7) should get you started. Additions and corrections are still welcome, of course.

### Q 2)
My board is not supported. What now?

### A)
Simple:

a)

Contact the maintainers (see other README's) and check out if someone is working on a driver.

b)

If so, contact them if you like and announce you'd be willing to test things or even help coding.

c)

If not, write a driver. Get as many docs on your card as you can, then read and understand the internals of svgalib (again read the README's carefully!).

Please understand that this is a free project. I will not go and buy a similar card and write a driver for you. I already wrote support for the hardware I have! I just do this as a hobby. Because I don't get paid for this I can not just buy card & docu and spend much much time supporting whatever graphics card on earth exists.

Also read below on the future of svgalib.

If you don't feel able to write a driver for whatever reason, please do not complain if other people don't do it for you (because you are not better than they are).

### Q 3)
I get:

You must be the owner of the current console to use svgalib.

Not running in a graphics capable console, and unable to find one.

However, though logged in not directly from the linux console, I am the owner of the console.

### A)
Alas, some programs use their suid root privilege and become a full root owned process. svgalib thinks they are run by root which does not own the current console. Defining ROOT_VC_SHORTCUT in Makefile.cfg and recompiling will allow svgalib to allocate a new VC. However, it will allow any person which is able to exec that program to start in on a new console. Even if not logged in from the console at all. Thus, for security, you need to explicitly enable that root feature.

### Q 4)
Is svgalib dead?

### A)
This question comes up frequently esp. in recent times.

The answer is, of course, no.

### Q 5)
There are so many Xfree drivers, why not just use them.

### A)
Well, actually much of the code in there is actually already used by svgalib. Xfree coders worked on svgalib and vice versa. But honestly, do not expect that a driver from Xfree can just be used for svgalib. The internal structures of Xfree and svgalib (and GGI) are just too different. As a source of knowledge and for one or the other subroutine, the Xfree sources are invaluable however.

### Q 6)
Why not just use the VGA BIOS?.

### A)
Actually, we do. There is now, thanks to Josh Vanderhoof, a VESA driver. The VESA driver does not work on all cards, even though it should. It does not even work on all cards where vbetest works. If vbetest does not work it means the bios writers assumed it would always run in DOS, and used tricks (for delay, etc.) that can't work under Linux. If vbetest works, but the VESA driver does not, I (Matan Ziv-Av) believe it is due to the following reason: The driver use VESA function 4 (save/restore video state). This function can't be used in a singletasking environment (DOS) and as such, some bios writers failed to implement it properly, and all the tests (which are run under DOS) failed to discover this.

The VESA driver does work with many cards though.

### Q 7)
What about GGI?

### A)
Yes, GGI. Another long story. At first: Yes, I like the idea of an in kernel graphics driver. I like it very much. And, yes, this is a bit weird because I am the svgalib maintainer and a working GGI will make svgalib obsolete. Again, I already said above: I did not invent svgalib nor do I promote it as the solution (now compare this to GGI). It just does what it does and works for me and some other people.

I liked this idea so much, I even started coding a frame buffer device once. After a short time, other people came out with the GGI idea. Right from their beginning they claimed to be the only source of wisdom. I tried to join our efforts, but failed. In general we have the same goals (read the GGI project pages for that).

Anyhow, at that time a flame war started. I don't really know why. I don't see I did anything else than offering my opinions, work and experience. But that should be judged by others.

Well, after some time I stopped bothering them. I was satisfied to learn later though that they actually came up with some conclusions I proposed first but weeks or months later. But let us leave the past alone.

When intending to contribute to svgalib, you should think about what you really want. I don't see that GGI is becoming available soon. GGI people told me the opposite again and again, ok, I still don't see it. Still out of a sudden, everything might be GGI infested, so you might consider contributing to GGI instead.

With svgalib you might be able to use your fruits earlier. And anyone (with supported hardware) can just use it right away without reinstalling kernel/X11 what else (maybe being unable to use something he did before).

### Q 8)
Why not just use X11?

Yes, this is what many people say. This is the common Unix way to do it. X does it.

But X has some drawbacks:

i)

It uses many resources. Admittedly this is becoming of lesser importance now, where you can run a sensible X11 Linux system on 8MB (16 MB for heaven like performance) which is the absolute minimum to get a simple text editor running under M$ windows. Still, an advantage of Linux is the ability to use old hardware for mission critical background jobs on the net (servers/routers/firewalls) on low price or otherwise even unusable hardware.

ii)

X has a nice API with draw commands for any kind of 'command oriented' screen output. I mean with that: Select a color, draw a line, polygon, etc. This imposes a bunch of overhead. If you just want access to the screen memory, it slows things down as hell. If you want just to use above's draw commands, it is ok!

iii)

One can now circumvent the API restrictions by getting direct screen access using a special Xfree extension. Basically Xfree just setups the screen and gives you shared memory access to the screen memory. IMHO, this is not much different from the shared memory X11 extension by MIT (which is probably why it was added so easily). Still it needs quite some overhead, at least when the card does not allow for a linear frame buffer. However, you cannot change screen modes and rez as easily. This is IMHO THE drawback of X. For a picture viewer, you want 256 color high/true color modes on a per picture basis (also, insert any other application you like: movie viewers, a special game, a drawing program). Also, you want a small picture use a low rez s.t. it does not appear as a thumbnail, maybe use a high rez mode for a huge picture which you don't want to use on a permanent basis because it flickers like hell (and you don't want to use a panning virtual desktop too, I hated them at best).

This latter restriction can of course be circumvented by enlarging the picture. But this will need much time for a picture viewer already and certainly too much for smooth video or game animations.

iv)

Finally, the problem how X11 itself accesses the screen is not solved. Security is usually no concern because X11 does it, is a trusted executable and a firewall between applications and the hardware. Alas, there might be security holes, also the stability and performance issues (IRQ driven accelerator queue, CPU support for VGA memory paging) still exist, though one can expect an Xserver to be a generally well coded application.

### Q 9)
Now, again, what about the future of svgalib?

For console graphics, svgalib is still the only solution for most people, and as such it should go on for a while. Compared to the other console graphics options (kgi and kernel fb device), writing svgalib driver is the simplest (at least, this is my experience), and so it makes sense to believe that svgalib will work on all cards where there is someone interested enough in that support.

### Q 10)
Ok, just for completeness, what are your plans about svgalib anyway?

First, make svgalib cooperate nicely with kernel fb device. Then (and it should be very similiar) make svgalib work on a secondary vga card.

A rewrite of the code for memory handling and virtual console handling is necessary for the previous goals, but is also necessary in itself, and so will be done also.

I do intend to maintain complete binary compatibility, so that older programs will go on working.

As internal changes are made, the drivers have to be changed as well. For some of the older drivers (ali, ark, ati, et3000, et4000, gvga, oak), I no longer get any reports, so I don't know if they still work. Some features are also lost, for example, linear frame buffer on non-PCI cards. This should not be a very big problem, as users with such cards can go on using 1.3.1, as most changes are not applicable for older machines.

## SEE ALSO
svgalib(7), libvga.config(5).

## AUTHOR
This file was written by Michael Weller <eowmob@exp-math.uni-essen.de>, And later changed by Matan Ziv-Av.