From 92ecf0a8a5b4d3f683bf5f63893238f9a70f59d4 Mon Sep 17 00:00:00 2001 From: Renuka Manavalan <47282725+renukamanavalan@users.noreply.github.com> Date: Thu, 4 Jul 2019 12:00:19 -0700 Subject: [PATCH 1/3] Added debug dockers & image info Added details on how to build debug docker images and how they can be exploited for debugging. --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4f9ed41d22b1..1ff7a235e5a5 100644 --- a/README.md +++ b/README.md @@ -123,6 +123,67 @@ Every target has a clean target, so in order to clean swss, execute: It is recommended to use clean targets to clean all packages that are built together, like dev packages for instance. In order to be more familiar with build process and make some changes to it, it is recommended to read this short [Documentation](README.buildsystem.md). +## Build debug dockers and debug SONiC installer image: +_Note: For now enabled for Broadcom platform only. Soon it will be extended to all._ + +`make INSTALL_DEBUG_TOOLS=y make target/sonic-broadcom.bin` + +* Builds debug docker images. +* Debug images carry a suffix of "-dbg" + * e.g. target/docker-orchagent-dbg.gz +* target/sonic-broadcom.bin is built using debug docker images + * Selective sources are archived and available under /src + * An empty /debug dir is created for use during debug session. + * All debug dockers are mounted with /src:ro and /debug:rw + * Login banner will briefly describe these features. + + +_Note: target/sonic-broadcom.bin name is the same irrespective of built using debug or non-debug dockers._ + +_Recommend: Rename image built using INSTALL_DEBUG_TOOLS=y to mark it explicit. May be `mv target/sonic-broadcom.bin target/sonic-broadcom-dbg.bin`_ + +### Debug dockers +* Built with all available debug symbols. +* Installed with many basic packages that would be required for debugging + * gdb + * gdbserver + * vim + * strace + * openssh-client + * sshpass +* Loadable into any environment that supports docker +* Outside SONiC image, you may run the docker with `--entrypoint=/bin/bash` +* Use -v to map any of your host directories +* To debug a core file in non-SONiC environment that supports docker + * `docker load -i docker--dbg.gz` + * copy your unzipped core file into ~/debug + * `docker run -it -entrypoint=/bin/bash -v ~/debug:/debug ` + * `gdb /usr/bin/ -c /debug/` + +### Debug SONiC image +_NOTE: For now available for broadcom only; soon to be extended._ + +* Install this image into your broadcom switch that supports SONiC. +* Open the archive in /src, if you would need source code for debugging +* Every debug enabled docker is mounted with /src as read-only +* The host has /debug dir and it is mapped into every debuggable docker as /debug with read-write permission. +* To debug a core + * Copy core into /debug of host and unzip it + * Feel free to create & use sub-dirs as needed. + * Entire /debug is mounted inside docker + * Get into the docker (`docker -it exec bash`) + * `gdb /usr/bin/ -c /debug/` + * Use set-directory in gdb to map appropriate source dir from under /src + * You may set gdb logs to go into /debug +* For live debugging + * Use this as a regular switch + * Get into docker, and you may + * start process under dbg + * attach gdb to running process + * Set required source dir from under /src as needed + * May use /debug to reecord all geb logs or any spew from debug session. + + ## Notes: - If you are running make for the first time, a sonic-slave-${USER} docker image will be built automatically. This may take a while, but it is a one-time action, so please be patient. @@ -135,10 +196,7 @@ This may take a while, but it is a one-time action, so please be patient. - docker-base.gz: base docker image where other docker images are built from, only used in build process (gzip tar archive) - docker-database.gz: docker image for in-memory key-value store, used as inter-process communication (gzip tar archive) - docker-fpm.gz: docker image for quagga with fpm module enabled (gzip tar archive) - - docker-orchagent-brcm.gz: docker image for SWitch State Service (SWSS) on Broadcom platform (gzip tar archive) - - docker-orchagent-cavm.gz: docker image for SWitch State Service (SWSS) on Cavium platform (gzip tar archive) - - docker-orchagent-mlnx.gz: docker image for SWitch State Service (SWSS) on Mellanox platform (gzip tar archive) - - docker-orchagent-nephos.gz: docker image for SWitch State Service (SWSS) on Nephos platform (gzip tar archive) + - docker-orchagent.gz: docker image for SWitch State Service (SWSS) (gzip tar archive) - docker-syncd-brcm.gz: docker image for the daemon to sync database and Broadcom switch ASIC (gzip tar archive) - docker-syncd-cavm.gz: docker image for the daemon to sync database and Cavium switch ASIC (gzip tar archive) - docker-syncd-mlnx.gz: docker image for the daemon to sync database and Mellanox switch ASIC (gzip tar archive) From c1c4271d07294d86e022f01f1df54453025ce387 Mon Sep 17 00:00:00 2001 From: Renuka Manavalan <47282725+renukamanavalan@users.noreply.github.com> Date: Wed, 10 Jul 2019 13:41:41 -0700 Subject: [PATCH 2/3] Update README.buildsystem.md --- README.buildsystem.md | 71 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/README.buildsystem.md b/README.buildsystem.md index 6735e1ce8968..f2d804d7e90f 100644 --- a/README.buildsystem.md +++ b/README.buildsystem.md @@ -207,3 +207,74 @@ $ make list ``` All target groups are used by one or another recipe, so use those recipes as a reference when adding new ones. + +## Build debug dockers and debug SONiC installer image: +Using 'INSTALL_DEBUG_TOOLS=y' builds the debug image. + +For example: +`INSTALL_DEBUG_TOOLS=y make target/sonic-broadcom.bin` + +* Builds debug docker images. +* Debug images carry a suffix of "-dbg" + * e.g. target/docker-orchagent-dbg.gz +* target/sonic-broadcom.bin is built using debug docker images + * Selective sources are archived and available under /src + * An empty /debug dir is created for use during debug session. + * All debug dockers are mounted with /src:ro and /debug:rw + * Login banner will briefly describe these features. + + +_Note: target/sonic-broadcom.bin name is the same irrespective of built using debug or non-debug dockers._ + +_Recommend: Rename image built using INSTALL_DEBUG_TOOLS=y to mark it explicit. May be `mv target/sonic-broadcom.bin target/sonic-broadcom-dbg.bin`_ + +### Debug dockers +* Built with all available debug symbols. +* Installed with many basic packages that would be required for debugging + * gdb + * gdbserver + * vim + * strace + * openssh-client + * sshpass +* Loadable into any environment that supports docker +* Outside SONiC image, you may run the docker with `--entrypoint=/bin/bash` +* Use -v to map any of your host directories +* To debug a core file in non-SONiC environment that supports docker + * `docker load -i docker--dbg.gz` + * copy your unzipped core file into ~/debug + * `docker run -it -entrypoint=/bin/bash -v ~/debug:/debug ` + * `gdb /usr/bin/ -c /debug/` + +### Debug SONiC image + +* Install this image into the switch that supports this image. + * For platform independent binary, you may use a debug image for virtual switch +* Open the archive in /src, if you would need source code for debugging +* Every debug enabled docker is mounted with /src as read-only +* The host has /debug dir and it is mapped into every debuggable docker as /debug with read-write permission. +* To debug a core + * Copy core into /debug of host and unzip it + * Feel free to create & use sub-dirs as needed. + * Entire /debug is mounted inside docker + * Get into the docker (`docker -it exec bash`) + * `gdb /usr/bin/ -c /debug/` + * Use set-directory in gdb to map appropriate source dir from under /src + * You may set gdb logs to go into /debug +* For live debugging + * Use this as a regular switch + * Get into docker, and you may + * start process under dbg + * attach gdb to running process + * Set required source dir from under /src as needed + * May use /debug to record all geb logs or any spew from debug session. + + ### To enhance debug dockers + * Add to `_DBG_IMAGE_PACKAGES`, additional debug tools that will be pre-installed during build. + * e.g. `$(DOCKER_ORCHAGENT)_DBG_IMAGE_PACKAGES += perl` + * Build will install these tools using "apt" + * Add to `_DBG_DEPENDS`, additional debug .deb packages that will be pre-installed during build. + * e.g. `$(DOCKER_ORCHAGENT)_DBG_DEPENDS += $(SWSS_DBG) $(LIBSWSSCOMMON_DBG) $(LIBSAIREDIS_DBG)` + * Add to `DBG_SRC_ARCHIVE`, the source dirs to archive + * The source files (.c, .cpp, .h & .hpp) under this dir tree are archived. + * e.g. rules/swss.mk has `DBG_SRC_ARCHIVE += swss` From 4f7f9f45a7f97f5c0ca083fd5f8273b2a95d3484 Mon Sep 17 00:00:00 2001 From: Renuka Manavalan <47282725+renukamanavalan@users.noreply.github.com> Date: Wed, 10 Jul 2019 13:48:39 -0700 Subject: [PATCH 3/3] Update README.md --- README.md | 60 +------------------------------------------------------ 1 file changed, 1 insertion(+), 59 deletions(-) diff --git a/README.md b/README.md index 1ff7a235e5a5..ac64902aa773 100644 --- a/README.md +++ b/README.md @@ -124,65 +124,7 @@ Every target has a clean target, so in order to clean swss, execute: It is recommended to use clean targets to clean all packages that are built together, like dev packages for instance. In order to be more familiar with build process and make some changes to it, it is recommended to read this short [Documentation](README.buildsystem.md). ## Build debug dockers and debug SONiC installer image: -_Note: For now enabled for Broadcom platform only. Soon it will be extended to all._ - -`make INSTALL_DEBUG_TOOLS=y make target/sonic-broadcom.bin` - -* Builds debug docker images. -* Debug images carry a suffix of "-dbg" - * e.g. target/docker-orchagent-dbg.gz -* target/sonic-broadcom.bin is built using debug docker images - * Selective sources are archived and available under /src - * An empty /debug dir is created for use during debug session. - * All debug dockers are mounted with /src:ro and /debug:rw - * Login banner will briefly describe these features. - - -_Note: target/sonic-broadcom.bin name is the same irrespective of built using debug or non-debug dockers._ - -_Recommend: Rename image built using INSTALL_DEBUG_TOOLS=y to mark it explicit. May be `mv target/sonic-broadcom.bin target/sonic-broadcom-dbg.bin`_ - -### Debug dockers -* Built with all available debug symbols. -* Installed with many basic packages that would be required for debugging - * gdb - * gdbserver - * vim - * strace - * openssh-client - * sshpass -* Loadable into any environment that supports docker -* Outside SONiC image, you may run the docker with `--entrypoint=/bin/bash` -* Use -v to map any of your host directories -* To debug a core file in non-SONiC environment that supports docker - * `docker load -i docker--dbg.gz` - * copy your unzipped core file into ~/debug - * `docker run -it -entrypoint=/bin/bash -v ~/debug:/debug ` - * `gdb /usr/bin/ -c /debug/` - -### Debug SONiC image -_NOTE: For now available for broadcom only; soon to be extended._ - -* Install this image into your broadcom switch that supports SONiC. -* Open the archive in /src, if you would need source code for debugging -* Every debug enabled docker is mounted with /src as read-only -* The host has /debug dir and it is mapped into every debuggable docker as /debug with read-write permission. -* To debug a core - * Copy core into /debug of host and unzip it - * Feel free to create & use sub-dirs as needed. - * Entire /debug is mounted inside docker - * Get into the docker (`docker -it exec bash`) - * `gdb /usr/bin/ -c /debug/` - * Use set-directory in gdb to map appropriate source dir from under /src - * You may set gdb logs to go into /debug -* For live debugging - * Use this as a regular switch - * Get into docker, and you may - * start process under dbg - * attach gdb to running process - * Set required source dir from under /src as needed - * May use /debug to reecord all geb logs or any spew from debug session. - +SONiC build system supports building dockers and ONE-image with debug tools and debug symbols, to help with live & core debugging. For details refer to [(SONiC Buildimage Guide)](https://github.com/Azure/sonic-buildimage/blob/master/README.buildsystem.md). ## Notes: - If you are running make for the first time, a sonic-slave-${USER} docker image will be built automatically.