これは本屋に行ったときに何も考えずに面白そうだから買った(笑)
結構難しそうだ。
この手の本は積読になりそうなので、そうならないように頑張ります。 分かったことがあれば、日記に書いてみたり、GitHubに上げてみたりしよう。
関係ないけど、今はこれを読んでいるよ。AMDのアウトオブオーダ実行についてかなり詳しく書いてある。
Chip Architect: Detailed Architecture of AMD's Opteron
翻訳を少しずつGitHubにアップロードしている。
前のブログでもちょっと書いたけど。
![ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによる モダンライティング]](http://ecx.images-amazon.com/images/I/51VoBpYkfbL._SL160_.jpg "ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによる モダンライティング]")
ドキュメント作成システム構築ガイド[GitHub、RedPen、Asciidoctor、CIによる モダンライティング]
ドキュメントと仕様書(一緒か)、そして実装は常に一体であるべき、というのは基本的な考え方。 ドキュメントから実装が生成される、実装からドキュメントが作られる、というのは究極の理想だけど、もうちょっとドキュメント作成が簡単になればね、ということで購入。
主に内容はMarkdownやAsciiDoc、さらに著者らが開発に参加しているRedPenなどの使用方法の紹介。GitHubによるドキュメント管理の方法からgitの使い方まで書いてあるけど、簡単すぎるので省略。 一番しっかり読んだのはRedPenの使い方の部分だ。キュメントを書くときはAsciiDocかSphinxを使うつもりだから、AsciiDocとAsciiDoctorの部分もしっかり読まなければならない。 とりあえず現状は今ある文章を校正しなければならないということでRedPenに注力。
これは前回もやった。前回はネットの情報だけで試してみたけど、今回は書籍も買ったし、いろいろカスタマイズできるはずだ！
トライしたのは、例によって数年前に翻訳したxv6のドキュメントである。
書籍の中では、RedPenのインストール方法としてMacOS XかLinuxしか書いていなかった。ちょっとー、Windows使っている人だってたくさんいるんだよ！むしろ、WindowsのWordか何かで書いている人たちをRedPenに移行させたいなら、Windowsでの環境構築手順をしっかりしないと意味ないんじゃないかなあ？大企業でMac使っているところなんて、聞いたことがない。
といっても、MingWをインストールしているので、特に困ったことはなかった。RedPenのパッケージをダウンロードして、パスを通し、Javaをインストールすればそれで終了だ。 MingWの.bashrcに、以下を記述していればそれで終了。
export PATH=/c/Program\ Files\ \(x86\)/Java/jre1.8.0_77/bin/:${PATH} export PATH=~/work/redpen-distribution-1.5.4/bin:${PATH} export JAVA_HOME=/c/Program Files (x86)/Java/jre1.8.0_77/
エラーの大半は"DoubledWord"という、文章内に同じ文字を連続して書いてしまった時のものだ。
chapter0.md:6: ValidationError[DoubledWord], 一文に二回以上利用されている単語 "動作" がみつかりました。 at line: オペレーティングシステムはハードウェアを分割させ、多くのプログラムがコンピュータを共有し同時動作(もしくは動作しているように見える)を実現している。 chapter0.md:6: ValidationError[DoubledWord], 一文に二回以上利用されている単語 "し" がみつかりました。 at line: オペレーティングシステムはハードウェアを分割させ、多くのプログラムがコンピュータを共有し同時動作(もしくは動作しているように見える)を実現している。 chapter0.md:6: ValidationError[DoubledWord], 一文に二回以上利用されている単語 "し" がみつかりました。 at line: オペレーティングシステムはハードウェアを分割させ、多くのプログラムがコンピュータを共有し同時動作(もしくは動作しているように見える)を実現している。 chapter0.md:6: ValidationError[DoubledWord], 一文に二回以上利用されている単語 "て" がみつかりました。 at line: オペレーティングシステムはハードウェアを分割させ、多くのプログラムがコンピュータを共有し同時動作(もしくは動作しているように見える)を実現している。 chapter0.md:6: ValidationError[DoubledWord], 一文に二回以上利用されている単語 "いる" がみつかりました。 at line: オペレーティングシステムはハードウェアを分割させ、多くのプログラムがコンピュータを共有し同時動作(もしくは動作しているように見える)を実現している。
でも、これはひどいんじゃない？単純にセンテンスを解析しているだけとはいえ、これは直しようが無いよ？
以上のように、RedPenの出してくるエラーはあまりにも過剰だ。 なので、最初はRedPenのルールをかなり甘々に設定し、エラーが減ってくると少しずつ厳しくしていくのが良いのではないだろうか？
技術文書なら、半角括弧はOKでしょ！redpenのconfに、以下を追加する。
<symbols> <symbol name="LEFT_PARENTHESIS" value="(" invalid-chars="（" after-space="true" /> <symbol name="RIGHT_PARENTHESIS" value=")" invalid-chars="）" after-space="true" /> </symbols>
最初はかなり戸惑ったのだが、ドキュメントを一生懸命読むとわかった。半角とか、特定の文字のためのルールが存在するのね。
そうでないとこの大量のエラーは処理しきれない。下の例では、「読点、で、を」を文中に2回以上登場させても良い設定にしているが、もっと別の接続詞も追加しておくべきだろう。そうでないと何のために文章を校正しているのかわからなくなる。
<validator name="DoubledWord"> <property name="list" value="、,で,を" /> </validator>
というわけで、デフォルトで使ってみると、申し訳ないが「相当使い物にならない」。自分でカスタマイズして、適材適所で使っていくべきツールだと思う。
とはいえ、これだけ大量に怒られると、「普段どういう部分に意識して文章を書くべきか」というのくらいはちょっと分かったかな。投稿する前にちゃんと読み直せとか(笑)
もしくは、今はやりのディープラーニングで、学習させて適切な校正をしてくれるように進化してくれてもいいよ！
RedHatより、RedHat Enterprise Linux 7.2が開発者向けに無償公開された。
RedHat Enterprise Linuxといえば開発者向けに推奨されているLinux OSであり、ハードウェア設計者にとってはEDAツールのインストール先として推奨されているケースが多い。 僕も会社ではRedHat Enterprise Linuxを使っている。別にCentOSでも構わないが、しっかりサポートを得られるのはRHELだし、インストール時にトラブルに合う確率も低い。 RedHat系で動作確認をしたいときは一度は試しておきたいディストリビューションだったりする。
これまではRedHatを使いたいときは有償だったのだが、どうやら今回開発者向けに無償公開されたようだ。 このあたりの解説を見れば大体分かる。
Red Hat Enterprise Linux Developer Program - Red Hat Customer Portal
どうやら、開発者向けのバージョンDeveloper Suiteは全くサポートは受けられないということだろうか。 ただしソフトウェアのアップデートにはしっかりアクセスできるし、別に趣味のプログラミングの環境として使うだけなので個人利用ならば問題ないだろう。
早速ダウンロードして、仮想環境上にインストールしてみよう。
ダウンロードにはRedHatのDeveloper Subscriptionに登録する必要がある。僕はGoogleのアカウントを使って登録した。 この後、ユーザ登録するとダウンロードできるようになる。インストールガイドもその時に入手できるようになった。
インストール中にはいくつかライセンスの契約の確認をする操作があった。これまで結構CentOS系や、Scientific LinuxなどのRedHat系のLinuxをインストールをしてきたが、これ系のメッセージと確認が出てきたのは初めてだったなあ。
インストール時に「パッケージとして開発者用のソフトウェア」と「GUI」をインストールしておいた。これはダウンロード時に参照できるインストールガイドに載っている。
このページを見るとわかるとおり、ベアメタル、Hyper-V、VirtualBox, VMwareでのインストール方法のガイドが載っている。僕はVirtualBoxを利用した。
無事にインストール完了した。また、Guest Additionもインストール出来た。
GUIはUbuntuと比較すると非常に軽快な印象だ。まあ、GUIはどっちにしろ開発用とならば使わないし、そのうちどうせSSH経由でアクセスするようになるんだから、大したことではないだろう。
とりあえずは、せっかくインストールしたので活用して行きたい。以下の記事にも興味がある。
なお、Red HatはMicrosoftと協業し、Microsoftの.NETをRHEL上で動作できるようにすることを2015年の11月に発表したが、今回Microsoftの開発者向けイベント「Build 2016」で、この動作デモをステージ上で行なうとともに、.NET coreおよびASP.NET、Entity Frameworkのオープンソース版をGitHubで公開した。また同時に、.NETファウンデーションへの参画を表明した。
僕は波形デバッグはあまり好きではなく、基本的に波形を水にログファイルだけでデバッグできるようにしておきたいのだが、ベーシックな部分を観測するためには最後には波形デバッグが必要だ。 そこで、Vivado Simulatorを使った時の波形デバッグの環境を構築しよう。やりたいことは、GUI付きでのシミュレーション、波形の追加などの操作だ。
Vivado Simulatorにおいて、GUI付きでデバッグをするためには、xsimにおいて-guiを追加すると良い。
xsim run_tb_mag_top -gui
ただしこれだけでは波形のダンプは取得できず、コンパイル時にデバッグオプションを追加しておかないと怒られる。
xelab -debug wave -s run_tb_mag_top work.tb_mag_top --timescale 1ns/100ps
自分がはまったのは、-R と -onfinishの考え方だ。
-R : シミュレーションを最後まで実行し、終了します (「run -all; exit」を実行)。
これを最初つけていたのだが、これを付けたままGUIを起動すると、シミュレーションが終了するとすぐにウィンドウも閉じられてしまう。これではデバッグできない。 結論としては、-Rオプションを除くだけでよい。ついでに、シミュレーション終了時の挙動を変えるためには、onfinishオプションも使用できる。
-onfinish stop|quit : シミュレーションが終了したときの動作を指定します。有効な値はquit および stop で、デフォルトは stop です。
基本的にstopのままで良いと思われるが、-Rを使わずにウィンドウも閉じたいときは、-onfinish quitを指定しておけばよいのかな。
Vivado Simulatorにおいて、XilinxのIPを使ってシミュレーションをしようとしたところ、Primitiveなモジュールが存在しないと怒られてしまった。
ERROR: [VRFC 10-2063] Module <GND> not found while processing module instance <GND> [... funcsim.v:2047]
GND GND (.G(\<const0> ));
そういえば、Vivado Simulatorにおいてfsblのようなモジュール群を読み込むためにはどうしたらよいのかと思い調査したところ、ちゃんとVivadoにもunisimのようなライブラリ群が存在していた。
っていうか、以下のFAQを見る限り、これらのライブラリは別に指定しなくても読み込まれるという理解だったんだけどな。
AR# 64052 - Vivado シミュレーション ライブラリの使用 - UNISIM ライブラリ
Vivado 2015.4ならば、以下のVerilogファイルがそれに相当するようだ。
c:/Xilinx/Vivado/2015.4/data/verilog/src/unisim_comp.v
とりあえずfilelistにこのファイルを追加すると、無事にコンパイルされるようになった。
それともう一つ、このunisim_comp.vにはタイムスケールの指定が無いため、コンパイルに失敗するケースがある。
ERROR: [XSIM 43-4099] "c:/Xilinx/Vivado/2015.4/data/verilog/src/unisim_comp.v" Line 3236. Module GND doesn't have a timescale but at least one module in design has a timescale.
これもオプションを調査して行くと、xelabの実行時にタイムスケールを指定すれば良さそうだ。
COMMAND xelab -s run_tb_mag_top work.tb_mag_top --timescale 1ns/100ps
これで、コンパイルとシミュレーションが無事に通るようになった。
以前、CMakeを使ってVerilogシミュレーションの環境を整える準備を行った。趣味でVerilogを書いている中で、Windows上のVivadoでシミュレーションを行う必要が出てきたため、環境を構築しよう。
利用したのは、Cygwinから若干進化して、MingW64上で構築を行っている。
Verilogの自動生成のための環境として、rubyと、cmakeのインストールを行った。 これはパッケージインストールをするだけで完了できる。
pacman -S ruby cmake
MingWの環境では、vivado_settingsもちゃんと動作した。
/c/Xilinx/Vivado/2015.4/settings64.sh
あとは、CMakeで必要なVerilogファイルを記述するだけだ。ファイルリストは、以下のようにしたものを利用している。
HW_DIR/mag_core/mag_top/sim/tb_mag_top.v #include "../rtl/mag_top.f"
シミュレーションベンチと、RTLファイルリストを分けて記述している。 あとは、以前の記事でテンプレートを作成したCMakeLists.txtを移植して、cmakeの実行と、シミュレーションを実行するだけだ。
ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:85] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:93] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:101] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:109] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:117] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:125] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:133] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:141] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:149] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:157] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:165] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:173] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:181] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:189] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:205] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:565] ERROR: [VRFC 10-1412] syntax error near , [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:573] ERROR: [VRFC 10-91] IF_INST is not declared [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:53] ERROR: [VRFC 10-91] IF_INST is not declared [C:/msys64/home/masayuki/work/magnetor-1/hardware/mag_core/mag_idu/rtl/riscv_ctrl.v:61]
いろいろと怒られてしまった。あとで修正しよう。
僕はどちらかというとドキュメントを書くのが好きだ。ドキュメントって、正直言うと何も考えずに書くことができる。普段プログラムを書いたり回路を設計しているときは、頭を回転させないとちゃんとしたものが作れない。しかし、仕様書とかドキュメントって、その実何も考えずに作ることができるのだ。そういう意味で、僕はドキュメント作成はエンジニアにとって急速の時というか、いったん休憩を挟むのにちょうど良いものだと考えている。
ただしそんな気持ちでドキュメント作成に臨んでいるもんだから、クオリティが高いとは言えない。実際、自分で読み直してみると何書いてんだかわかんない時がある。 大学の卒業論文では、第1項を六に自分でチェックせずに先輩に見せたものだから、ずいぶんと訂正させられたものだ。 まあ、文章のストーリー性や組み立て方はともかく、一文一文を読みやすいものにしておきたい。そこで、文章校正ツールとしてRedPenを使ってみよう。
RedPen の特徴 設定が柔軟に行えます。（カスタマイズも柔軟） どのような言語で書かれた文書でも処理できます。（もちろん日本語も OK です） Markdown や Textile フォーマットで記述された文書をそのまま検査できます。
良さそうね。
対象は、Ubuntu15.10だ。インストールにはJava 8とMavenが必要らしい。
$ sudo add-apt-repository ppa:webupd8team/java
$ sudo apt-get update
$ sudo apt-get install oracle-java8-installer
次にRedPenをダウンロードする。
wget https://github.com/redpen-cc/redpen/releases/download/redpen-1.5.3/redpen-1.5.3.tar.gz tar xvfz redpen-1.5.3.tar.gz cd redpen-distribution-1.5.3/ ./bin/redpen -c conf/redpen-conf-ja.xml sample-doc/ja/sampledoc-ja.md ... [2016-03-27 14:46:00.463][ERROR] cc.redpen.Main - The number of errors "28" is larger than specified (limit is "1").
いくつかエラーが表示された。なるほど、こうやって校正していくのね。 じゃあ、僕の作ったドキュメントを使うとどうなるんだろう。
xv6のドキュメントを、日本語化したものを公開している。これを使って、校正をかけてみよう。
git clone https://github.com/msyksphinz/xv6_translate.git ./redpen-distribution-1.5.3/bin/redpen -c ./redpen-distribution-1.5.3/conf/redpen-conf-ja.xml xv6_translate/chapter0.md ... とを見ることができるだろう。 chapter0.md:283: ValidationError[DoubledWord], Found repeated word "に". at line: xv6を学んだあとは、読者はより複雑なオペレーティングシステムを学ぶことによって、xv6の内部の考え方がそれらのシステムにも同様に存在しているこ とを見ることができるだろう。 chapter0.md:283: ValidationError[DoubledWord], Found repeated word "こと". at line: xv6を学んだあとは、読者はより複雑なオペレーティングシステムを学ぶことによって、xv6の内部の考え方がそれらのシステムにも同様に存在している ことを見ることができるだろう。 chapter0.md:283: ValidationError[DoubledWord], Found repeated word "を". at line: xv6を学んだあとは、読者はより複雑なオペレーティングシステムを学ぶことによって、xv6の内部の考え方がそれらのシステムにも同様に存在しているこ とを見ることができるだろう。 chapter0.md:283: ValidationError[DoubledWord], Found repeated word "こと". at line: xv6を学んだあとは、読者はより複雑なオペレーティングシステムを学ぶことによって、xv6の内部の考え方がそれらのシステムにも同様に存在している ことを見ることができるだろう。 chapter0.md:283: ValidationError[DoubledWord], Found repeated word "が". at line: xv6を学んだあとは、読者はより複雑なオペレーティングシステムを学ぶことによって、xv6の内部の考え方がそれらのシステムにも同様に存在しているこ とを見ることができるだろう。 chapter0.md:283: ValidationError[SpaceBetweenAlphabeticalWord], Space not present before an alphabetical word. at line: 本書はxv6をUnix系のインタフェースインタフェーウとして実装する方法について述べるが、アイデアと概念はUnixだけに適用されるものではない。 chapter0.md:283: ValidationError[SpaceBetweenAlphabeticalWord], Space not present before an alphabetical word. at line: 本書はxv6をUnix系のインタフェースインタフェーウとして実装する方法について述べるが、アイデアと概念はUnixだけに適用されるものではない。 chapter0.md:283: ValidationError[SpaceBetweenAlphabeticalWord], Space not present after an alphabetical word. at line: 本書はxv6をUnix系のインタフェースインタフェーウとして実装する方法について述べるが、アイデアと概念はUnixだけに適用されるものではない。 chapter0.md:283: ValidationError[SpaceBetweenAlphabeticalWord], Space not present before an alphabetical word. at line: 本書はxv6をUnix系のインタフェースインタフェーウとして実装する方法について述べるが、アイデアと概念はUnixだけに適用されるものではない。 chapter0.md:283: ValidationError[SpaceBetweenAlphabeticalWord], Space not present after an alphabetical word. at line: 本書はxv6をUnix系のインタフェースインタフェーウとして実装する方法について述べるが、アイデアと概念はUnixだけに適用されるものではない。 [2016-03-27 14:49:44.465][ERROR] cc.redpen.Main - The number of errors "1663" is larger than specified (limit is "1").
めちゃ怒られた。これはひどい。
セクションの長さの規定か。これ以上長く書くなということ？まあ確かに、一節が長いと読む気はなくなるかもしれない。ってか、これを出すってことはMarkdownのセクションをちゃんと認識してるってことね。えらい。
これ、結構多い。どうやら、接続詞などを続けても怒られるようだ。確かに、僕は接続詞と句読点で文章を続ける傾向があるので、それは大量に指摘されるのかもしれない。
そうなんだ。細かいね...
ここら辺は、キチンと気を付けて書ける人はどれくらいいるんだろうか。。。
./redpen-distribution-1.5.3/bin/redpen -c ./redpen-distribution-1.5.3/conf/redpen-conf-ja.xml ./diary.md ... [2016-03-27 14:57:08.330][ERROR] cc.redpen.Main - The number of errors "72" is larger than specified (limit is "1").
あらまあ。でも、
diary.md:1: ValidationError[DoubledWord], Found repeated word "と". at line: 僕はどちらかというとドキュメントを書くのが好きだ。
これは勘弁してほしいかなあ。
